Final docs updates for testers

docs/detail.md

@@ -230,7 +230,9 @@ See [Advanced results access](results.md) for a more detailed overview of the di
 
 ### `pyco2.sys` arguments
 
-All [keyword arguments](#keyword-arguments) that can be provided to `pyco2.sys` are also available as results with the same keyword.
+All [keyword arguments](#keyword-arguments) that can be provided to `pyco2.sys` and are not settings (i.e., do not begin with `opt_`) are also available as results with the same keyword.
+
+Settings arguments can be found at `co2s.opts`.  They should not be modified there - doing so will have unpredictable consequences for future calculations.
 
 ### pH
 

docs/index.md

@@ -4,9 +4,13 @@
 
     These are the docs for the forthcoming PyCO2SYS v2!
 
-    These instructions will not work for the current version 1.8 that can be installed through pip and conda.
+    **These instructions will not work for the current version 1.8** that can be installed through pip and conda - please see [PyCO2SYS.readthedocs.io](https://pyco2sys.readthedocs.io/en/latest/) for documentation for the latest release.
 
-    Please see [PyCO2SYS.readthedocs.io](https://pyco2sys.readthedocs.io/en/latest/) for documentation for the latest release.
+    **If you are here to test PyCO2SYS v2**, then create a test environment with Python v3.10 or greater, and then in that environment run
+
+        pip install git+https://github.com/mvdh7/PyCO2SYS@jax
+
+    This installs PyCO2SYS and its core requirements: JAX and NetworkX.  If you wish to try out using PyCO2SYS with pandas and/or xarray, you'll need to install those into the environment separately.
 
 PyCO2SYS is a Python toolbox for solving the marine carbonate system and calculating related seawater properties.  It was originally based on CO2SYS for MATLAB[^1].
 

docs/quick.md

@@ -30,24 +30,36 @@ results = co2s[["pCO2", "fCO2"]]
 
 Each call of `pyco2.sys` may include a maximum of two known marine carbonate system parameters.
 
-## Propagate uncertainties
+## Calculations without solving the system
 
-Uncertainty propagation uses the `propagate` method.  To get the total uncertainty in pH from independent uncertainties in alkalinity and DIC in the example above, use:
+Some properties (mainly equilibrium constants and total salt contents) can be calculated without solving the marine carbonate system, so `pyco2.sys` can be run with no marine carbonate system parameters:
 
 ```python
-# Uncertainties in alkalinity and DIC are both 2 µmol/kg
-co2s.propagate("pH", {"alkalinity": 2, "dic": 2})
-pH_uncertainty = co2s.uncertainty["pH"]["total"]
+# Set up a CO2System under default conditions 
+# (temperature 25 °C, salinity 35, hydrostatic pressure 0 dbar
+#   - other values could be specified with the appropriate kwargs)
+co2s = pyco2.sys()
+
+# Get water dissociation constant
+k_H2O = co2s["k_H2O"]
 ```
 
-The individual components of the total uncertainty can also be found, for example:
+## Use different parameterisations
+
+PyCO2SYS contains many different options for the parameterisations of equilibrium constants and total salt contents.  These can be selected using `kwargs` beginning with `opt_`, for example:
 
 ```python
-pH_uncertainty_from_dic = co2s.uncertainty["pH"]["dic"]
+# Set up a CO2System with non-default equilibrium constants for carbonic acid
+# and non-default total borate from salinity
+co2s = pyco2.sys(opt_k_carbonic=3, opt_total_borate=2)
 ```
 
+All settings arguments must be single scalar values.
+
 ## Convert to different temperatures and/or pressures
 
+> Discussed in more detail in [Adjust conditions](adjust.md).
+
 ### With two known parameters
 
 To convert parameters to different temperatures and/or pressures, use the `adjust` method.  For example, if we had measured alkalinity and pH in the laboratory at 25 °C, but wanted to calculate the saturation state with respect to aragonite under in situ conditions:
@@ -74,30 +86,22 @@ co2s_insitu = co2s_lab.adjust(temperature=10, pressure=1500)
 pCO2_insitu = co2s_insitu["pCO2"]
 ```
 
-## Use different parameterisations
+## Propagate uncertainties
 
-PyCO2SYS contains many different options for the parameterisations of equilibrium constants and total salt contents.  These can be selected using `kwargs` beginning with `opt_`, for example:
+> Discussed in more detail in [Uncertainty propagation](uncertainty.md).
+
+Uncertainty propagation uses the `propagate` method.  To get the total uncertainty in pH from independent uncertainties in alkalinity and DIC in the example above, use:
 
 ```python
-# Set up a CO2System with non-default equilibrium constants for carbonic acid
-# and non-default total borate from salinity
-co2s = pyco2.sys(opt_k_carbonic=3, opt_total_borate=2)
+# Uncertainties in alkalinity and DIC are both 2 µmol/kg
+co2s.propagate("pH", {"alkalinity": 2, "dic": 2})
+pH_uncertainty = co2s.uncertainty["pH"]["total"]
 ```
 
-All settings arguments must be single scalar values.
-
-## Calculations without solving the system
-
-Some properties (mainly equilibrium constants and total salt contents) can be calculated without solving the marine carbonate system, so `pyco2.sys` can be run with no marine carbonate system parameters:
+The individual components of the total uncertainty can also be found, for example:
 
 ```python
-# Set up a CO2System under default conditions 
-# (temperature 25 °C, salinity 35, hydrostatic pressure 0 dbar
-#   - other values could be specified with the appropriate kwargs)
-co2s = pyco2.sys()
-
-# Get water dissociation constant
-k_H2O = co2s["k_H2O"]
+pH_uncertainty_from_dic = co2s.uncertainty["pH"]["dic"]
 ```
 
 ## Multidimensional data

docs/versions.md

@@ -33,7 +33,14 @@ Switches from Autograd to JAX for automatic differentiation.  Internal mechanism
 
 !!! new-version "Changes in v2.0"
 
-    * Major internal revisions.
+    * Calculations performed only when needed for specifically requested parameters.
+    * Only one combination of known marine carbonate system parameters allowed per calculation.
+    * Only one combination of optional settings allowed per calculation.
+    * Optional settings each only affect one parameterisation, so there are more of them.  (In v1, `opt_k_carbonic` could alter several other parameterisations beyond just the carbonic acid equilibrium.)
+    * "Input" and "output" conditions deprecated in favour of the `adjust` method.
+    * Uncertainty propagation uses automatic differentiation instead of finite differences.
+    * Simple tests suggest calculations including iterative pH solving are on the order of 100 times faster and have about 100 times lower peak memory demand.
+    * Differences in calculated values from v1.8 should all be at the level of computer precision (i.e., negligible).
 
 ## 1.8
 

mkdocs.yml

@@ -43,7 +43,8 @@ theme:
     text: Noto Sans
     code: Noto Sans Mono
   features:
-    navigation.footer
+    - navigation.footer
+    - content.code.copy
 
 # Extensions
 markdown_extensions: