docs update part 1

Author: rkingsbury

.gitignore

@@ -42,7 +42,9 @@ coverage.xml
 build/*
 dist/*
 sdist/*
-docs/*
+docs/_build/*
+docs/_static/*
+docs/api/*
 cover/*
 MANIFEST
 

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Significant documentation updates.
 - `Solution.components` is now automatically sorted in descending order of amount, for
   consistency with `anions`, `cations`, and `neutrals`.
 

docs/amounts.md

@@ -0,0 +1,108 @@
+# Solute Amounts
+
+## See all components in the solution
+
+You can inspect the solutes present in the solution via the `components` attribute. This comprises a dictionary of solute formula: moles, where 'moles' is the number of moles of that solute in the `Solution`. Note that the solvent (water) is present in `components`, too.
+`components` is reverse sorted, with the most predominant component (i.e., the solvent)
+listed first.
+
+```python
+>>> from pyEQL import Solution
+>>> s = Solution({"Mg+2": "0.5 mol/L", "Cl-": "1.0 mol/L"})
+>>> s.components
+{'H2O(aq)': 54.83678280993063, 'Cl[-1]': 1.0, 'Mg[+2]': 0.5, 'H[+1]': 1e-07, 'OH[-1]': 1e-07}
+```
+
+Similarly, you can use the properties `anions`, `cations`, `neutrals`, and `solvent` to
+retrieve subsets of `components`:
+
+```python
+>>> s.anions
+{'Cl[-1]': 1.0, 'OH[-1]': 1e-07}
+>>> s.cations
+{'Mg[+2]': 0.5, 'H[+1]': 1e-07}
+>>> s.neutrals
+{'H2O(aq)': 54.83678280993063}
+>>> s.solvent
+'H2O(aq)'
+```
+
+Like `components`, all of the above dicts are sorted in order of decreasing amount.
+
+## Get the amount of a specific solute
+
+To get the amount of a specific solute, use `get_amount()` and specify the units you want:
+
+```python
+>>> from pyEQL import Solution
+>>> s = Solution({"Mg+2": "0.5 mol/L", "Cl-": "1.0 mol/L"})
+>>> s.get_amount('Mg[+2]', 'mol')
+<Quantity(0.5, 'mole')>
+```
+
+`get_amount` is highly flexible with respect to the types of units it can interpret. You
+can request amounts in moles, mass, or equivalents (i.e., charge-weighted moles) per
+unit of mass or volume.
+
+```python
+>>> s.get_amount('Mg[+2]', 'M')
+<Quantity(0.5, 'molar')>
+>>> s.get_amount('Mg[+2]', 'm')
+<Quantity(0.506124103, 'mole / kilogram')>
+>>> s.get_amount('Mg[+2]', 'eq/L')
+<Quantity(1.0, 'mole / liter')>
+>>> s.get_amount('Mg[+2]', 'ppm')
+<Quantity(12152.5, 'milligram / liter')>
+>>> s.get_amount('Mg[+2]', 'ppb')
+<Quantity(12152500.0, 'microgram / liter')>
+>>> s.get_amount('Mg[+2]', 'ppt')
+<Quantity(1.21525e+10, 'nanogram / liter')>
+```
+
+:::{important}
+The unit `'ppt'` is ambiguous in the water community. To most researchers, it means
+"parts per trillion" or ng/L, while to many engineers and operators it means "parts
+per THOUSAND" or g/L. `pyEQL` interprets `ppt` as **parts per trillion**.
+:::
+
+You can also request dimensionless concentrations as weight percent (`'%'`),
+mole fraction (`'fraction'`) or the total _number_
+of particles in the solution (`'count'`, useful for setting up simulation boxes).
+
+```python
+>>> s.get_amount('Mg[+2]', '%')
+<Quantity(1.17358141, 'dimensionless')>
+>>> s.get_amount('Mg[+2]', 'fraction')
+<Quantity(0.00887519616, 'dimensionless')>
+>>> s.get_amount('Mg[+2]', 'count')
+<Quantity(3.01107038e+23, 'dimensionless')>
+```
+
+## Total Element Concentrations
+
+"Total" concentrations (i.e., concentrations of all species containing a particular
+element) are important for certain types of equilibrium calculations. These can
+be retrieved via `get_total_amount`. `get_total_amount` takes an element name as
+the first argument, and a unit as the second.
+
+```python
+>>> from pyEQL import Solution
+>>> s = Solution({"Mg+2": "0.5 mol/L", "Cl-": "1.0 mol/L"})
+>>> s.equilibrate()
+>>> s.components
+{'H2O(aq)': 54.85346847938828, 'Cl[-1]': 0.9186683796593457, 'Mg[+2]': 0.41866839204646417, 'MgCl[+1]': 0.08133160795194606, 'OH[-1]': 1.4679440802358093e-07, 'H[+1]': 1.1833989847708719e-07, 'HCl(aq)': 1.2388705241250352e-08, 'MgOH[+1]': 3.9747494391744955e-13, 'O2(aq)': 7.027122927701743e-25, 'HClO(aq)': 1.5544872892067526e-27, 'ClO[-1]': 6.339364938003202e-28, 'H2(aq)': 5.792559717610837e-35, 'ClO2[-1]': 0.0, 'ClO3[-1]': 0.0, 'ClO4[-1]': 0.0, 'HClO2(aq)': 0.0}
+>>> s.get_total_amount('Mg', 'mol')
+<Quantity(0.5, 'mole')>
+```
+
+## Elements present in a `Solution`
+
+If you just want to know the elements present in the `Solution`, use `elements`. This
+returns a list of elements, sorted alphabetically.
+
+```python
+>>> from pyEQL import Solution
+>>> s = Solution({"Mg+2": "0.5 mol/L", "Cl-": "1.0 mol/L"})
+>>> s.elements
+['Cl', 'H', 'Mg', 'O']
+```

docs/arithmetic.md

@@ -0,0 +1,55 @@
+# Arithmetic Operations
+
+## Addition and Subtraction
+
+You can use the `+` operator to mix (combine) two solutions. The moles of each component
+in the two solutions will be added together, and the volume of the mixed solution will
+be _approximately_ equal to the sum of the two volumes, depending on the electrolyte
+modeling engine used.
+
+```python
+>>> from pyEQL import Solution
+>>> s1 = Solution({"Na+": "0.5 mol/L", "Cl-": "0.5 mol/L"})
+>>> s2 = Solution({"Na+": "0.1 mol/L", "Cl-": "0.1 mol/L"})
+>>> s1+s2
+<pyEQL.solution.Solution object at 0x7f171aee3af0>
+>>> (s1+s2).get_amount('Na+', 'mol')
+<Quantity(0.6, 'mole')>
+>>> (s1+s2).volume
+<Quantity(1.99989659, 'liter')>
+```
+
+:::{note}
+Both `Solution` involved in an addition operation must use the same [electrolyte
+modeling engine](engines.md).
+:::
+
+Subtraction is not implemented and will raise a `NotImplementedError`.
+
+```
+>>> s1-s2
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+  File "/home/ryan/mambaforge/envs/pbx/code/pyEQL/src/pyEQL/solution.py", line 2481, in __sub__
+    raise NotImplementedError("Subtraction of solutions is not implemented.")
+NotImplementedError: Subtraction of solutions is not implemented.
+```
+
+## Multiplication and Division
+
+The `*` and `/` operators scale the volume and all component amounts by a factor.
+
+```python
+from pyEQL import Solution
+>>> s = Solution({"Na+": "0.2 mol/L", "Cl-": "0.2 mol/L"})
+>>> s.volume
+<Quantity(1, 'liter')>
+>>> s.get_amount('Cl-', 'mol')
+<Quantity(0.2, 'mole')>
+>>> s*=1.5
+<Quantity(1.5, 'liter')>
+s.get_amount('Cl-', 'mol')
+<Quantity(0.3, 'mole')>
+```
+
+The modulo operator `//` is not implemented.

docs/chemistry.md

@@ -2,10 +2,10 @@
 
 # Chemical Formulas
 
-pyEQL interprets the chemical formula of a substance to calculate its molecular
+`pyEQL` interprets the chemical formula of a substance to calculate its molecular
 weight and formal charge. The formula is also used as a key to search the
-database for parameters (e.g. diffusion coefficient) that are used in subsequent
-calculations.
+[property database](database.md) for parameters (e.g. diffusion coefficient) that are
+used in subsequent calculations.
 
 ## How to Enter Valid Chemical Formulas
 
@@ -32,8 +32,7 @@ by `(aq)` to disambiguate them from solids.
 
 :::{important}
 **When writing multivalent ion formulas, it is strongly recommended that you put the charge number AFTER the + or -
-sign** (e.g., type "Mg+2" NOT "Mg2+"). The latter formula is ambiguous - it could mean $`Mg_2^+`$ or $`Mg^{+2}`$ and
-it will be processed incorrectly into `Mg[+0.5]`
+sign** (e.g., type "Mg+2" NOT "Mg2+"). The latter formula is ambiguous - it could mean $Mg_2^+$ or $Mg^{+2}$ and it will be processed incorrectly into `Mg[+0.5]`
 :::
 
 (manual-testing)=
@@ -56,11 +55,11 @@ When using the `Solution` class,
 - However, the `components` attribute is a special dictionary that automatically standardizes formulas when accessed. So, you can still enter the formula
   however you want. For example, the following all access or modify the same element in `components`:
 
-  ```
-  Solution.components.get('Na+')
-  Solution.components["Na+1"]
-  Solution.components.update("Na[+]": 2)
-  Solution.components["Na[+1]"]
+  ```python
+  >>> Solution.components.get('Na+')
+  >>> Solution.components["Na+1"]
+  >>> Solution.components.update("Na[+]": 2)
+  >>> Solution.components["Na[+1]"]
   ```
 
 - Arguments to `Solution.get_property` can be entered in any format you prefer. When `pyEQL` queries the database, it will automatically standardize the formula.

docs/class_solution.md

@@ -1,74 +1,10 @@
 (class-solution)=
 
-# The Solution Class
+# `Solution` API Reference
 
-The `Solution` class defines a pythonic interface for **creating**, **modifying**, and **estimating properties** of
-electrolyte solutions. It is the core feature of `pyEQL` and the primary user-facing class.
+This page contains detailed information on each of the methods, attributes, and properties in `Solution`. Use the sidebar on the right for easier navigation.
 
-## Creating a solution
-
-A `Solution` created with no arguments will default to pure water at pH=7, T=25 degrees Celsius, and 1 atm pressure.
-
-```
->>> from pyEQL import Solution
->>> s1 = Solution()
->>> s1.pH
-6.998877352386266
-```
-
-Alternatively, you can use the `autogenerate()` function to easily create common solutions like seawater:
-
-```
->>> from pyEQL.functions import autogenerate
->>> s2 = autogenerate('seawater')
-<pyEQL.solution.Solution object at 0x7f057de6b0a0>
-```
-
-You can inspect the solutes present in the solution via the `components` attribute. This comprises a dictionary of solute formula: moles, where 'moles' is the number of moles of that solute in the `Solution`. Note that the solvent (water) is present in `components`, too.
-
-```
->>> s2.components
-{'H2O': 55.34455401423017,
- 'H+': 7.943282347242822e-09,
- 'OH-': 8.207436858780226e-06,
- 'Na+': 0.46758273714962967,
- 'Mg+2': 0.052661180523467986,
- 'Ca+2': 0.010251594148212318,
- 'K+': 0.010177468379526856,
- 'Sr+2': 9.046483353663286e-05,
- 'Cl-': 0.54425785619973,
- 'SO4-2': 0.028151873448454025,
- 'HCO3-': 0.001712651176926199,
- 'Br-': 0.0008395244921424563,
- 'CO3-2': 0.00023825904349479546,
- 'B(OH)4': 0.0001005389715937341,
- 'F-': 6.822478260456777e-05,
- 'B(OH)3': 0.0003134669156396757,
- 'CO2': 9.515218476861175e-06
- }
-```
-
-To get the amount of a specific solute, use `get_amount()` and specify the units you want:
-
-```
->>> s2.get_amount('Na+', 'g/L')
-<Quantity(10.6636539, 'gram / liter')>
-```
-
-Finally, you can manually create a solution with any list of solutes, temperature, pressure, etc. that you need:
-
-```
->>> from pyEQL import Solution
->>> s1 = Solution(solutes={'Na+':'0.5 mol/kg', 'Cl-': '0.5 mol/kg'},
-                  pH=8,
-                  temperature = '20 degC',
-                  volume='8 L'
-                  )
-```
-
-## Class reference
-
-The remainder of this page contains detailed information on each of the methods, attributes, and properties in `Solution`. Use the sidebar on the right for easier navigation.
+## Solution
 
 ```{eval-rst}
 .. autoclass:: pyEQL.Solution

docs/creating.md

@@ -0,0 +1,74 @@
+# Creating a `Solution`
+
+The `Solution` class defines a pythonic interface for **creating**, **modifying**, and **estimating properties** of electrolyte solutions. It is the core feature of `pyEQL` and the primary user-facing class. There are several ways to create a `Solution`.
+
+
+## Empty solution
+
+With no input arguments, you get an empty `Solution` at pH 7 and 1 atm pressure.
+
+```python
+>>> from pyEQL import Solution
+>>> s = Solution()
+>>> print(s)
+Volume: 1.000 l
+Pressure: 1.000 atm
+Temperature: 298.150 K
+Components: ['H2O(aq)', 'H[+1]', 'OH[-1]']
+```
+
+## Manual Creation
+
+Typically, you will create a solution by specifying a list of solutes. Solutes are
+passed as a `dict` with amounts given **as strings** that include units (see [units](units.md)). Any unit that can be understood by `get_amount` is valid.
+
+```python
+>>> from pyEQL import Solution
+>>> s = Solution({"Na+": "0.5 mol/L", "Cl-": "0.5 mol/L"})
+```
+
+You can also specify conditions such as temperature, pressure, pH, and pE (redox potential).
+
+
+Finally, you can manually create a solution with any list of solutes, temperature, pressure, etc. that you need:
+
+```python
+>>> from pyEQL import Solution
+>>> s1 = Solution(solutes={'Na+':'0.5 mol/kg', 'Cl-': '0.5 mol/kg'},
+                  pH=8,
+                  temperature = '20 degC',
+                  volume='8 L',
+                  pE = 4,
+                  )
+```
+
+## Using a preset
+
+Alternatively, you can use the `pyEQL.functions.autogenerate()` function to easily create common solutions like seawater:
+
+```
+>>> from pyEQL.functions import autogenerate
+>>> s2 = autogenerate('seawater')
+<pyEQL.solution.Solution object at 0x7f057de6b0a0>
+```
+
+## From a dictionary
+
+If you have [converted a `Solution` to a `dict`](serialization.md#serialization-to-dict),
+you can re-instantiate it using the `Solution.from_dict()` class method.
+
+## From a file
+
+If you [save a `Solution` to a `.json` file](serialization.md#saving-to-a-json-file),
+you can [recreate it](serialization.md#loading-from-a-json-file) using
+[monty.serialization.loadfn](https://pythonhosted.org/monty/monty.html#module-monty.serialization)
+
+```python
+>>> from monty.serialization import loadfn
+>>> s = loadfn('test.json')
+print(s)
+Volume: 1.000 l
+Pressure: 1.000 atm
+Temperature: 298.150 K
+Components: ['H2O(aq)', 'H[+1]', 'OH[-1]']
+```

docs/engines.md

@@ -0,0 +1,14 @@
+# Electrolyte Modeling Engines
+
+## Overview
+
+## The `'native'` engine (Default)
+
+:::{warning}
+experimental - speciation + activity model
+:::
+
+## The ``phreeqc'` engine
+
+The `phreeqc` engine uses [`phreeqpython`](https://github.com/Vitens/phreeqpython)
+for speciation, activity, and volume calculations.