Reorganize usage docs

docs/make.jl

@@ -10,7 +10,8 @@ makedocs(
     pages = [
         "Home"      => "index.md",
         "Theory"    => "theory.md",
-        "Usage"     => ["usage/index.md", "usage/in-yaml-keys.md"],
+        "Usage"     => ["usage/index.md", "usage/DFT-calculations.md", "usage/in-yaml.md",
+                        "usage/LCAO.md", "usage/in-yaml-keys.md"],
         "Tutorials"  => ["tutorials/IrIn3.md"],
         "API"       => ["api/index.md", "api/yaml.md"]
     ]

docs/src/IrIn3.md

@@ -183,7 +183,7 @@ found at `11_In-In/11_In-In_psphere_4.73.txt`:
 287     0.16723350141820606      at site [6.993, 0.000, 7.191]
 288     0.1572312564858335       at site [3.497, 3.497, 3.595]
 ```
-We find that ``Psphere`` drops precipitously at some points in this run. In order to complete the
+We find that ``P_{sphere}`` drops precipitously at some points in this run. In order to complete the
 analysis, we want to remove the orbitals from our total reconstruction and 
 We recommend that you manually inspect the orbitals to observe their
 character. When we do this, we find that orbitals 287 and 288 do not have the desired character, and

docs/src/tutorials/IrIn3.md

@@ -288,7 +288,7 @@ raMO functions more closely. For reference and throughness, it is recommended to
 functions directly preceding these (raMOs 280, 285).
 
 ```@raw html
-<br><center><p><img src="../assets/IrIn3_remainder_analysis.png" alt="From left to right: isosurfaces
+<br><center><p><img src="assets/IrIn3_remainder_analysis.png" alt="From left to right: isosurfaces
 of raMO 280, 281, 287, 288"></p>
 <p><i>From left to right: isosurfaces of raMO 280, 281, 287, 288</i></p></center><br>
 ```

docs/src/usage/DFT-calculations.md

@@ -0,0 +1,24 @@
+# DFT calculations
+
+## Preparation of VASP input files
+Currently, DFT-raMO supports VASP inputs, and the required VASP outputs are the `OUTCAR`, `POSCAR`,
+`KPOINTS`, and `WAVECAR` files. Future versions will support abinit (likely to be tested on versions
+8.10.3 and 9.10.1), and this will require a `WFK` output.
+
+A static calculation should be performed with a `POSCAR` pertaining to the unit cell geometry. The `POSCAR` file must specify atomic identities after giving cell parameters but before the stoichiometry and direct coordinates. This is not a problem with VASP version 5 or later, but POSCAR files in VASP 4 do not include this information. Ensure this information is in the `POSCAR` or add it manually. An example is given below, where the atomic identities are given in the line `Sc Al`.
+```
+Al3 Sc1                                 
+   1.00000000000000     
+     4.1046969868448775    0.0000000000000000    0.0000000000000000
+     0.0000000000000000    4.1046969868448775    0.0000000000000000
+     0.0000000000000000    0.0000000000000000    4.1046969868448775
+Sc Al
+   1   3
+Direct
+  0.0000000000000000  0.0000000000000000  0.0000000000000000
+  0.0000000000000000  0.5000000000000000  0.5000000000000000
+```
+
+A Γ-centered k-point mesh (`KPOINTS`) corresponding to the desired supercell in real space should also be used. For example, if using a 2×2×3 supercell, the k-point grid must also be 2×2×3. The supercell size should be large enough such that atoms do not interact with their translational copies in neighboring supercells. The recommended starting point is to use a supercell approximately 12 Å in length for each axis (assuming cubic, tetragonal, or orthorhombic systems). A larger grid may be used but the user should be aware that significantly more memory will be needed.
+
+Be sure to turn off symmetry (`ISYM = -1`) and print the `WAVECAR`.

docs/src/usage/LCAO.md

@@ -0,0 +1,81 @@
+# LCAOs
+
+## Overview
+
+Linear combinations of atomic orbitals (LCAOs) are also available target options in DFT-raMO.jl. A user can more precisely specify the contribution of different AOs on multiple atoms to the target, allowing users to rotate AOs (such as a combination of ``p_x`` and ``p_y`` orbitals) or target π-bonding between two atoms. Due to the complexity of the customization, a separate YAML file reserved for LCAO-type customization is necessary to reduce clutter in the instructional YAML file. Details of this separate YAML file are discussed [below](#The-LCAO-YAML).
+
+The keys and options for LCAO-type runs are similar to *sp*-type runs. The `site_file` key must point to the [LCAO-specific YAML](#The-LCAO-YAML), and the `sites` key now is limited to integers that correspond to the sites listed in the LCAO-specific YAML or the `all` keyword. Unlike the *sp*-type runs, the `radius` keyword can be left blank or omitted entirely.
+
+```@raw html
+<br><center><p><img src="assets/lcao_options.png" width="200" alt="Example options for a lcao-type run."></p>
+<p><i>Example options for a lcao-type run.</i></p></center><br>
+```
+
+## The LCAO YAML
+
+Now, let’s examine the options for the YAML file exclusively for customizing the targeted LCAOs (`lcao1.yaml` in the above figure). The YAML file has two keys that serve as lists: `target` and `lcao`. Each list item in `target` specifies contributing AOs for that atom. The possible keys in each item are AOs: `s`, `px`, `py`, `pz`, `dx2y2`, `dz2`, `dxy`, `dxz`, `dyz`. The options for these keys are numerical values corresponding to the relative contribution of that AO to the LCAO (these values will be normalized with respect to the entire LCAO).
+
+### LCAOs on one atomic site
+Example options in the LCAO YAML targeting rotated *p* orbitals:
+
+```yaml
+target:
+  - px: -1
+    py: 1
+lcao:
+  - [1]
+  - [2]
+  - [17]
+  - [18]
+  - [33]
+  - [34]
+  - [49]
+  - [50]
+  - [65]
+  - [66]
+  - [81]
+  - [82]
+  - [97]
+  - [98]
+  - [113]
+  - [114]
+```
+
+Here are some of the important components of this example file:
+  - The `target:` key indicates that a list of LCAOs will follow. Each atomic site is indicated with
+    a `-`, and relative contributions of each atomic orbital follow each atomic orbital key.
+      + Relative contributions of each atomic orbital will be normalized such that the total
+        contribution equals 1.
+      + Any atomic orbital keys that are notdefined are ignored.
+  - The `lcao` key indicates the list of targets in the run.
+      + Each list item must be a vector of integers indicating the number corresponding to the atom
+        in the supercell. These atomic positions can usually be found by checking the xsfs of a
+        previously run.
+      + The number of integers in the list *must* match the number of atomic sites in `target`.
+
+Because only one atom is targeted per raMO in the example above, `target` only has one list item. Within that list, only the `px` and `py` keys are specified, with values of `-1` and `1`, respectively. Because these are equal in magnitude, after normalization, they will contribute equally to the target function for a *p*-like orbital rotated 45° with respect to the y- axis.
+
+Next, the `lcao` list specifies which atoms participate in the each raMO in the sequence. Each item in the list must be a vector of integers that must have an equal number of items to the number of list items in target. In the example above, since AOs on only one atom are targeted, the vectors have only one integer in them. The integers in these vectors correspond to the order of atoms in the periodic atom list of the supercell. For the example above, the first raMO of the sequence will target a LCAO of ``p_x`` and ``p_y`` orbitals on atom 1. The second raMO will target an analogous LCAO on atom 2. And so on.
+
+### LCAOs on multiple atomic sites
+
+To target contributions from multiple atoms in a single raMO (e.g. σ-bonds, π-bonds), the `target` list should have multiple items, and each vector in the `lcao` list should increase accordingly.
+
+```yaml
+target:
+    - px: -1
+      py: 1
+    - px: -1
+      py: 1
+lcao:
+    - [1, 2]
+    - [17, 18]
+    - [33, 34]
+    - [49, 50]
+    - [65, 66]
+    - [81, 82]
+    - [97, 98]
+    - [113, 114]
+```
+
+In the example given above, target has two items in its list (both rotated *p*-orbitals) and each vector in the `lcao` list contains two integers. These integers, in order, correspond to the items in the `target` list.

docs/src/usage/in-yaml.md

@@ -0,0 +1,124 @@
+# The Instructional YAML file
+
+!!! note
+    See also [Keys for the Instructional YAML](in-yaml-keys.md)
+
+DFT raMO.jl requires an instructions file to customize and perform the analysis. This file specifies input files, checkpoint files, and other necessary parameters. The input file must be written in YAML format (with the .yml or .yaml extension), which consists of a series of keys and values separated by colons. Lists are defined with a hyphen and spaces. Below is an example of inputs for the instructions file for DFT-raMO.jl.
+
+Example YAML file:
+```yaml
+checkpoint:
+software: vasp
+mode: auto_psphere
+emin: -100 eV
+emax:
+runs:
+   - name: 1_Ir_dx2y2
+     type: dx2y2
+     sites_file: 
+     sites: Ir
+     rsphere: 2.65
+   - name: 2_Ir_dz2
+     type: dz2
+     sites_file: 
+     sites: Ir
+     rsphere: 2.65
+```
+
+Here are some of the important components of this example file:
+  - The `checkpoint` key can be left blank when starting a new calculation to use an initial basis set generated from the DFT calculations. Checkpoint files are automatically written by DFT-raMO. A path to a file can be given to resume the calculation. 
+  - The `software` key specifies which DFT software generated the wavefunction information.
+  - The `mode` key is set to `auto_psphere` mode, allowing DFT-raMO to automatically reject functions that do not meet the criteria set by ``P_{sphere}`` analysis.
+  - The `emin` and `emax` keys allow the user to specify the energy range (in eV or Ha) of bands used in the initial basis set — leaving these values blank will default to using all bands below the Fermi energy.
+  - The `runs` key indicates a list of raMO sequences will follow. Each sequence is prepended with spaces and a hyphen. Keys within the list item are exclusive to that sequence.
+      + The `name` key requires a string which will be used to ame the directory that stores the sequence's output files. By default, the name is `run_<number>` where `<number>` is the number in the order.
+      + The `type` key determines the target orbital shapes to reconstruct: atomic orbitals (`s`, `px`, `py`, `pz`, `dx2y2` or `dx2-y2`, `dz2`, `dxy`, `dxz`, and `dyz`), sp-based orbitals built from a distance criteria (`sp`), linear combination of atomic orbitals (`lcao`), or displaced atomic orbitals (`displaced (AO)`).
+      + The `rsphere` key corresponds to the distance from the central site to consider for ``P_{sphere}`` analysis in Angstroms.
+
+A complete table of general keys and options are listed in the [Keys for the Instructional YAML](in-yaml-keys.md).
+
+## Atomic orbital-type runs
+
+Atomic orbital (AO)-type runs, as the name suggests, are for reconstructing raMOs that replicate atomic orbitals. For AO-type runs (type: `s`, `px`, `py`, `pz`, `dx2y2`, `dz2`, `dxy`, `dxz`, or `dyz`), the sites key specifies which atomic sites to generate the AO for. This can be a number of options.
+
+The most common option is to specify all atoms of a certain type.
+
+```yaml
+sites: Ir
+```
+
+It is also possible to specify the first site of that element only.
+
+```yaml
+sites: Ir 1
+```
+
+A range of atoms can also be selected specific to an atomic element,
+
+```yaml
+sites: Ir 1, 3:5, 12
+```
+
+or in order of the periodic atom list corresponding to the supercell.
+
+```yaml
+sites: 8, 10, 122:144
+```
+
+```@raw html
+<br><center><p><img src="assets/ao_options.png" width="200" alt="Example options for an atomic orbital-type run."></p>
+<p><i>Example options for an atomic orbital-type run.</i></p></center><br>
+```
+
+## *sp*-type runs
+
+The *sp*-type runs are generally used to build molecular orbital-like targets with a distance-based criteria. From a central site, DFT-raMO.jl will search for atoms within a specified radius whose *s* and *p* orbitals are expected to contribute to the raMO. The *sp*-type run option is typically used in the reconstruction of isolobal bonds or multicentered bonding functions. 
+
+For *sp*-type runs, the `radius` key is now required, and it specifies the distance (in Angstroms) from the central site to search for atoms to include in the generation of the bonding function. The `sites_file` key is also now required; it must be a string pointing to a text file (typically in .xyz format) that lists the sites. Below, the figure shows the content of an example sites file containing three sites: the first item in the line is a placeholder character and is ignored, and the next three items must correspond to the Cartesian coordinates of the sites.
+
+```@raw html
+<br><center><p><img src="assets/sp_options.png" width="200" alt="Example options for an sp-type run."></p>
+<p><i>Example options for an <i>sp</i>-type run.</i></p></center><br>
+```
+
+For *sp*-type runs, the sites key now is limited to integers that correspond to the lines in the .xyz file. Specific sites may be specified:
+```yaml
+sites: 1, 2, 4:8
+```
+or the `all` keyword may be used to indicate that the whole list will be used in the sequence.
+```yaml
+sites: all
+```
+
+```@raw html
+<br><center><p><img src="assets/xyz.png" width="300" alt="Example content of an .xyz file for the sites_file key."></p>
+<p><i>Example content of an .xyz file for the </i><code>sites_file</code><i> key.</i></p></center><br>
+```
+
+## LCAO-type runs
+See [LCAOs](LCAO.md).
+
+## Displaced AO-type runs
+The displaced AO-type run is an experimental feature in which the targeted AO may be displaced from the atomic site by some specified direction and distance. This feature may be relevant to properties such as polarizability. To perform this type of run, the keyword `displaced` must be prepended on the type of AO run. In addition, the `discard` mode is recommended, as this feature usually used in an exploratory context and not in a typical DFT-raMO analysis. Below is a code block with an example of an instructional YAML for a displaced AO-type run.
+
+```yaml
+checkpoint:
+mode: discard
+emin: -100 eV
+emax: 
+software: vasp
+runs:
+  - name: Sc_custom_dxz
+    type: displaced dxz
+    sites: Sc
+    direction: [1, 1, 0]
+    radius: 1
+    rsphere: 2.2
+```
+
+Here, we are targeting displaced Sc ``d_{xz}`` atomic orbitals, as indicated by `type: displaced dxz` and `sites: Sc`. The direction of this displacement is given by `direction: [1, 1, 0]`, where the vector corresponds to the *a*, *b*, and *c* unit cell vectors, meaning any values of the vector must correspond to the fractional coordinate system. This vector is later normalized by DFT-raMO.jl to obtain a unit vector. The `radius` key specifies the displacement along the directional unit vector in Å. In the above example, we displace the ``d_{xz}`` atomic orbital by 1 Å. The raMO sequence can be executed normally and output files obtained.
+
+```@raw html
+<br><center><p><img src="assets/displaced_Sc_dxy.png" width="200" alt="A displaced Sc dxy raMO in AuCu3-type ScAl3."></p>
+<p><i>A displaced Sc d<sub>xy</sub> raMO in AuCu<sub>3</sub>-type ScAl<sub>3</sub>.</i></p></center><br>
+```