Skip to content

Commit

Permalink
Continue updating docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mvdh7 committed Jan 7, 2025
1 parent 530b0f9 commit 7e9237a
Show file tree
Hide file tree
Showing 6 changed files with 17 additions and 471 deletions.
338 changes: 0 additions & 338 deletions docs/co2sys_nd.md

This file was deleted.

4 changes: 2 additions & 2 deletions docs/co2sys.md → docs/howto.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ co2s = pyco2.sys(
)
# (If necessary) solve for and retrieve a calculated parameter
dic = co2s["dic"]
# Solve for and retrieve multiple parameters
# Solve for and retrieve multiple parameters as a dict
params = co2s[["fCO2", "k_H2CO3"]]
```

Expand Down Expand Up @@ -96,7 +96,7 @@ To adjust the system to a different set of temperature and/or pressure condition
co2s_adj = co2s.adjust(temperature=25, pressure=1000)
```

The result `co2s_adj` is a new `CO2System` with all values at the new conditions (temperature of 25 °C and hydrostatic pressure of 1000 dbar).
The result `co2s_adj` is a new `CO2System` with all values at the new conditions (above, temperature of 25 °C and hydrostatic pressure of 1000 dbar).

The `adjust` method can be used if any two carbonate system parameters are known, but also if only one of pCO<sub>2</sub>, fCO<sub>2</sub>, [CO<sub>2</sub>(aq)] or *x*CO<sub>2</sub> is known. In this case, `adjust` can take additional kwargs:

Expand Down
115 changes: 0 additions & 115 deletions docs/uncertainty.md

This file was deleted.

6 changes: 4 additions & 2 deletions docs/v1_to_v2.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Switching from v1 to v2

This explanation is designed as a detailed overview of differences for those who are already familiar with using PyCO2SYS with the `pyco2.sys` syntax from v1. New or casual users may find the [general instructions for v2](V2LINK) more helpful.
This explanation is designed as a detailed overview of differences for those who are already familiar with using PyCO2SYS with the `pyco2.sys` syntax from v1. New or casual users may find the [general instructions for v2](../howto) more helpful.

## Solving the carbonate system

Expand Down Expand Up @@ -159,7 +159,7 @@ In v1, a second set of temperature and/or pressure conditions could be specified
fCO2_adj = co2s["fCO2_out"]
```

The result `co2s_adj` is a separate `CO2System` at the requested temperature and pressure. If the original `co2s` had two known parameters, then both are used to make the adjustment (via DIC and alkalinity). Temperature can also be adjusted with only one known parameter, if its one of pCO<sub>2</sub>, fCO<sub>2</sub>, [CO<sub>2</sub>(aq)] or *x*CO<sub>2</sub>. The kwargs `method_fCO2`, `opt_which_fCO2_insitu` and `bh_upsilon` allow for finer control of the one-parameter adjustment (see the [v2 general instructions](V2LINK) for details).
The result `co2s_adj` is a separate `CO2System` at the requested temperature and pressure. If the original `co2s` had two known parameters, then both are used to make the adjustment (via DIC and alkalinity). Temperature can also be adjusted with only one known parameter, if its one of pCO<sub>2</sub>, fCO<sub>2</sub>, [CO<sub>2</sub>(aq)] or *x*CO<sub>2</sub>. The kwargs `method_fCO2`, `opt_which_fCO2_insitu` and `bh_upsilon` allow for finer control of the one-parameter adjustment (see the [v2 general instructions](../howto) for details).

## Uncertainty propagation

Expand Down Expand Up @@ -218,7 +218,9 @@ An example:

## Settings

Before v2, changing `opt_k_carbonic` to a different set of carbonic acid dissociation constants could also cause other parameterisations to be switched behind the scenes (for e.g. the borate equilibrium constant and some pressure correction factors). This behaviour was inherited from CO2SYS-MATLAB, but it has been eliminated in PyCO2SYS v2. Instead, every parameterisation that has multiple options is controlled independently with its own setting.

This affects only `opt_k_carbonic` values `6`, `7`, and `8`, i.e., the GEOSECS and freshwater cases. All other `opt_k_carbonic` options used the set of parameterisations that are now the defaults in v2.

## Summary of differences

Expand Down
20 changes: 10 additions & 10 deletions docs/validate.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,19 +183,19 @@ PyCO2SYS now calculates a wider array of properties than this version of CO2SYS

We cannot compare calculations with carbonate ion, bicarbonate ion or aqueous CO<sub>2</sub> as one of the input marine carbonate system parameters, because these options are not available in CO2SYS v2.0.5 for MATLAB.

We also cannot test the [PF87](../refs/#p) input option for the hydrogen fluoride [dissociation constant](../co2sys/#settings).
We also cannot test the [PF87](../refs/#p) input option for the hydrogen fluoride [dissociation constant](../howto/#settings).

The PyCO2SYS outputs either not calculated or not returned by CO2SYS v2.0.5 for MATLAB are:

* All of the [buffer factors](../co2sys/#buffer-factors) except for the Revelle factor.
* All properties associated with [NH<sub>3</sub> and H<sub>2</sub>S](../co2sys/#alkalinity-and-its-components).
* [Total calcium](../co2sys/#totals-estimated-from-salinity) molinity (although this is indirectly tested by the calcite/aragonite saturation state calculations).
* All of the [buffer factors](../howto/#buffer-factors) except for the Revelle factor.
* All properties associated with [NH<sub>3</sub> and H<sub>2</sub>S](../howto/#alkalinity-and-its-components).
* [Total calcium](../howto/#totals-estimated-from-salinity) molinity (although this is indirectly tested by the calcite/aragonite saturation state calculations).

**Against CO2SYS v3 for MATLAB:**

The new extended MATLAB version includes the full range of input marine carbonate system parameters, NH<sub>3</sub> and H<sub>2</sub>S, and the [PF87](../refs/#p) input option for the hydrogen fluoride [dissociation constant](../co2sys/#settings).
The new extended MATLAB version includes the full range of input marine carbonate system parameters, NH<sub>3</sub> and H<sub>2</sub>S, and the [PF87](../refs/#p) input option for the hydrogen fluoride [dissociation constant](../howto/#settings).

However, it still cannot be used to validate the [buffer factors](../co2sys/#buffer-factors) (again, except for the Revelle factor), nor directly the [total calcium](../co2sys/#totals-estimated-from-salinity) molinity.
However, it still cannot be used to validate the [buffer factors](../howto/#buffer-factors) (again, except for the Revelle factor), nor directly the [total calcium](../howto/#totals-estimated-from-salinity) molinity.

!!! tip "Do it yourself"

Expand All @@ -208,7 +208,7 @@ PyCO2SYS now calculates a wider array of properties than this version of CO2SYS

If you don't have a MATLAB license, you can run those scripts with the free and open source [GNU Octave](https://www.gnu.org/software/octave/). Alternatively, the CSV files generated by the MATLAB scripts are available [from GitHub](https://github.com/mvdh7/PyCO2SYS/blob/master/validate/results/).

In these tests, the marine carbonate system is solved from every possible combination of [input parameter pair](../co2sys/#carbonate-system-parameters) and [CO2SYS settings](../co2sys/#settings), with non-zero nutrients and pressure. The results calculated by CO2SYS are then subtracted from those of PyCO2SYS for comparison.
In these tests, the marine carbonate system is solved from every possible combination of [input parameter pair](../howto/#carbonate-system-parameters) and [CO2SYS settings](../howto/#settings), with non-zero nutrients and pressure. The results calculated by CO2SYS are then subtracted from those of PyCO2SYS for comparison.

!!! success "PyCO2SYS vs CO2SYS-MATLAB"
* Every variable computed by `PyCO2SYS.CO2SYS` is negligibly different from its counterpart in CO2SYS v2.0.5 for MATLAB, except for the Revelle factor ([see discussion below](#revelle-factor-discrepancy)).
Expand All @@ -221,10 +221,10 @@ In these tests, the marine carbonate system is solved from every possible combin
* These variables in the PyCO2SYS output `CO2dict` are set to zero where appropriate (as of v1.4.0). This means that the values you see in `CO2dict` are those that were actually used in the calculations.
* However, in MATLAB and in earlier versions of PyCOSYS, the outputs simply repeated the user inputs.

We've also compared the [original CO2SYS clone](../co2sys/#the-original-co2sys-clone) in `PyCO2SYS.original.CO2SYS` against CO2SYS for MATLAB. It is important to remember that this module stands in isolation. It has its own self-contained set of functions for evaluating equilibrium constants and solving the marine carbonate system that do not interact with the rest of PyCO2SYS. Agreement between this module and CO2SYS for MATLAB tells us nothing about the performance of `PyCO2SYS.CO2SYS` or any of its underlying functions (and the opposite).
We've also compared the [original CO2SYS clone](../howto/#the-original-co2sys-clone) in `PyCO2SYS.original.CO2SYS` against CO2SYS for MATLAB. It is important to remember that this module stands in isolation. It has its own self-contained set of functions for evaluating equilibrium constants and solving the marine carbonate system that do not interact with the rest of PyCO2SYS. Agreement between this module and CO2SYS for MATLAB tells us nothing about the performance of `PyCO2SYS.CO2SYS` or any of its underlying functions (and the opposite).

!!! success "The original CO2SYS clone vs CO2SYS-MATLAB"
* Every variable computed by the [original CO2SYS clone](../co2sys/#the-original-co2sys-clone) in `PyCO2SYS.original.CO2SYS` is virtually identical to its counterpart in CO2SYS v2.0.5 for MATLAB.
* Every variable computed by the [original CO2SYS clone](../howto/#the-original-co2sys-clone) in `PyCO2SYS.original.CO2SYS` is virtually identical to its counterpart in CO2SYS v2.0.5 for MATLAB.
* The absolute differences in all compared variables under the test conditions range from 0 to a maximum less than 10<sup>−9</sup>%.

#### Revelle factor discrepancy
Expand All @@ -249,6 +249,6 @@ With `opt_buffers_mode=2`, PyCO2SYS does use the finite-difference approach but

[^1]: The pH tolerance threshold for all iterative solvers is controlled by `PyCO2SYS.solve.get.pH_tolerance`.

[^2]: The [default conditions](../co2sys/#using-the-pythonic-api) for `PyCO2SYS.api.CO2SYS_wrap` with total alkalinity = 2300 μmol/kg-sw and DIC = 2150 μmol/kg-sw.
[^2]: The [default conditions](../howto/#using-the-pythonic-api) for `PyCO2SYS.api.CO2SYS_wrap` with total alkalinity = 2300 μmol/kg-sw and DIC = 2150 μmol/kg-sw.

[^3]: The [OEG15](../refs/#o) intercomparison used CO2SYS v1.1 of [HPR11](../refs/#HPR11), but the only difference between v2.0.5 and this in terms of solving the marine carbonate system is the addition of an extra set of carbonic acid dissociation constants.
5 changes: 1 addition & 4 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,11 @@ repo_url: https://github.com/mvdh7/PyCO2SYS
# Navigation
nav:
- Overview: index.md
- How to use PyCO2SYS: co2sys_nd.md
- How to use PyCO2SYS: howto.md
- Switching from v1 to v2: v1_to_v2.md
- Uncertainty propagation: uncertainty.md
- Validation: validate.md
- References: refs.md
- Version history: versions.md
- Alternative interfaces:
- MATLAB-style CO2SYS: co2sys.md

# Appearance
theme:
Expand Down

0 comments on commit 7e9237a

Please sign in to comment.