Update docs

Author: Andrew-S-Rosen

docs/examples.md

@@ -154,53 +154,3 @@ atoms.get_potential_energy()
 1. This file is provided in `raspa_ase/docs/files/MFI_SI.cif` for the sake of this tutorial. The `Atoms` object represents the framework to be studied and will be written out to the current working directory to be used by RASPA.
 
 2. The framework parameters are to be specified as `info` attributes of the `Atoms` object. You do not need to include the framework number or framework name. These will be included automatically.
-
-## Example 8: Adsorption isotherm of CO2 in Cu-BTC
-
-!!! Note
-
-    This example is not ready yet since support for charges is ongoing.
-
-```python
-from ase.io import read
-from raspa_ase import Raspa
-
-atoms = read("Cu-BTC.cif")  # (1)!
-atoms.info = {  # (2)!
-    "HeliumVoidFraction": 0.29,
-    "ExternalTemperature": 323.0,
-    "ExternalPressure": 100000.0,
-}
-atoms.set_initial_charges([1.0])  # (3)!
-
-components = [
-    {
-        "MoleculeName": "CO2",
-        "MoleculeDefinition": "ExampleDefinitions",
-        "FugacityCoefficient": 1.0,
-        "TranslationProbability": 0.5,
-        "RotationProbability": 0.5,
-        "ReinsertionProbability": 0.5,
-        "SwapProbability": 1.0,
-        "CreateNumberOfMolecules": 0,
-    }
-]
-parameters = {
-    "SimulationType": "MonteCarlo",
-    "NumberOfCycles": 10000,
-    "NumberOfInitializationCycles": 5000,
-    "PrintEvery": 1000,
-    "RestartFile": False,
-    "Forcefield": "ExampleMOFsForceField",
-}
-calc = Raspa(components=components, parameters=parameters)
-
-atoms.calc = calc
-atoms.get_potential_energy()
-```
-
-1. This file is provided in `raspa_ase/docs/files/Cu-BTC.cif` for the sake of this tutorial. The `Atoms` object represents the framework to be studied and will be written out to the current working directory to be used by RASPA.
-
-2. If you do not specify the "UnitCells" parameter, the calculator will automatically determine an appropriate value based on the size of the unit cell and the chosen cutoff (taken as 12.0 Angstroms if not specified) to account for the minimum image convention.
-
-3. This will set `_atom_site_charge` label in the CIF file and will automatically enable "UseChargesFromCIFFile" in the `parameters` block.

docs/install.md

@@ -2,7 +2,7 @@
 
 ## RASPA
 
-First, install RASPA based on the [official instructions](https://iraspa.org/raspa/).
+First, install RASPA based on the [official instructions](https://iraspa.org/raspa/) and set the `$RASPA_DIR` environment variable as instructed.
 
 !!! Tip
 

docs/intro.md

@@ -0,0 +1,123 @@
+# Overview
+
+The calculator is quite straightforward to use. For details on each parameter, refer to the RASPA manual.
+
+## Instantiating the Calculator
+
+The calculator is applied to an `Atoms` object, representing the framework under investigation. To run a RASPA calculator, call the `.get_potential_energy()` method like so:
+
+```python
+from ase.io import read
+from raspa_ase import Raspa
+
+atoms = read("my_framework.cif")
+atoms.calc = Raspa()
+atoms.get_potential_energy()
+```
+
+## Parameters
+
+Of course, you need to actually provide some input parameters. In short, the calculator takes an `Atoms` object and three optional keyword arguments. The parameters are case-insensitive, booleans will be converted to "Yes" or "No" as appropriate, lists will be converted to space-separated strings, and dictionaries will be converted to properly formatted key-value pairs.
+
+### Framework Properties
+
+The calculator is applied to an `Atoms` object. If you want to run a calculation without a framework (i.e. with just a box of molecules), you can use an empty `Atoms` object, defined as `Atoms()`.
+
+For framework-specific properties, they should be attached to the `Atoms` object's `.info` attribute.
+
+For instance:
+
+```python
+atoms.info["HeliumVoidFraction"] = 0.149
+```
+
+would be equivalent to
+
+```python
+Framework 0
+    FrameworkName framework0
+    HeliumVoidFraction 0.149
+```
+
+You never need to specify the framework number or the framework name, and the the CIF will be automatically written out for you based on the `Atoms` object. If you don't specify a "UnitCells" entry in `atoms.info`, `raspa_ase` will ensure that the minimum image convention is satisfied based on your "CutOff" value.
+
+If you want to run a calculation with partial atomic charges on the framework, you can set the initial charges:
+
+For instance:
+
+```python
+atoms.set_initial_charges([1.0, 2.0])
+```
+
+would write out the `_atom_site_charge` column in the CIF as 1.0 and 2.0 for atom number 0 and 1, respectively. It will also automatically set "UseChargesFromCIFFile" to "Yes".
+
+### Boxes
+
+The optional `boxes` keyword argument, of type `list[dict]`, is a list where each entry is a given set of box parameters formatted as a dictionary.
+
+For instance:
+
+```python
+boxes = [{"BoxLengths": [30, 30, 30]}, {"BoxLengths": [40, 40, 40], "BoxAngles": [90, 120, 120]}]
+Raspa(boxes=boxes)
+```
+
+is equivalent to
+
+```
+Box 0
+    BoxLengths 30 30 30
+Box 1
+    BoxLengths 40 40 40
+    BoxAngles 90 120 120
+```
+
+You never need to specify the box number. This is determined based on the index of the box in the list.
+
+### Components
+
+The optional `components` keyword argument, of type `list[dict]`, is a list where each entry is a given set of component parameters formatted as a dictionary.
+
+For instance:
+
+```python
+components = [
+    {"MoleculeName": "CO2", "MoleculeDefinition": "ExampleDefinitions"},
+    {"MoleculeName": "N2", "MoleculeDefinition": "ExampleDefinitions"},
+]
+```
+
+is equivalent to
+
+```
+Component 0 MoleculeName CO2
+    MoleculeDefinition ExampleDefinitions
+Component 1 MoleculeName N2
+    MoleculeDefinition ExampleDefinitions
+```
+
+You never need to specify the component number. This is determined based on the index of the component in the list. The "MoleculeName" will also be formatted automatically for you.
+
+### Keywords
+
+The optional `keywords` keyword argument, of type `dict`, is a dictionary of all other parameters to be passed to RASPA.
+
+For instance:
+
+```python
+keywords = {
+    "SimulationType": "MonteCarlo",
+    "NumberOfCycles": 10000,
+    "NumberOfInitializationCycles": 1000,
+    "Movies": True,
+}
+```
+
+is equivalent to
+
+```
+SimulationType MonteCarlo
+NumberOfCycles 10000
+NumberOfInitializationCycles 1000
+Movies Yes
+```

mkdocs.yml

@@ -6,6 +6,7 @@ site_url: https://quantum-accelerators.github.io/raspa_ase/
 nav:
   - Home: index.md
   - install.md
+  - intro.md
   - examples.md
   - Code Documentation: reference/ # keep me!
   - About: