PyCO2SYS

https://pyco2sys.readthedocs.io/
Admin
PyCO2SYS is a Python toolbox for solving the marine carbonate system and calculating related...
Tokens:37,354
Snippets:192
Trust Score:9.6
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install PyCO2SYS with pip

Source: https://pyco2sys.readthedocs.io

Install the package from the Python Package Index.

```bash
pip install PyCO2SYS
```

--------------------------------

### Partial calculations with pyco2.sys

Source: https://pyco2sys.readthedocs.io/en/latest/co2sys_nd

From v1.7.0, pyco2.sys can be run without providing any carbonate system parameters or with just one parameter. These examples show converting a pH value to all pH scales, converting an fCO2 value to another temperature, and evaluating all equilibrium constants and total salts at default conditions.

```python
# Convert a pH value to all pH scales, but don't solve the whole system:
results = pyco2.sys(par1=8.1, par1_type=3, **kwargs)
```

```python
# Convert an fCO2 value to another temperature, but don't solve:
results = pyco2.sys(
    par1=400, par1_type=5, temperature=12, temperature_out=25, **kwargs
)
```

```python
# Evaluate all equilibrium constants and total salts at default conditions:
results = pyco2.sys()
```

--------------------------------

### pyco2.sys with uncertainty propagation

Source: https://pyco2sys.readthedocs.io/en/latest/uncertainty

Example of running PyCO2SYS with uncertainty propagation by adding uncertainty_into and uncertainty_from keyword arguments to pyco2.sys.

```APIDOC
## pyco2.sys with uncertainty propagation

### Description
Run PyCO2SYS with uncertainty propagation by providing uncertainty_into and uncertainty_from keyword arguments to pyco2.sys. This calculates the total uncertainty in specified results and the individual contributions from each specified argument.

### Method
Function call

### Endpoint
pyco2.sys(**kwargs, uncertainty_into=[...], uncertainty_from={...})

### Parameters
#### Keyword Arguments
- **kwargs** (dict) - Required - All necessary keyword arguments for pyco2.sys, such as par1, par2, par1_type, par2_type, temperature, etc.
- **uncertainty_into** (list of str) - Required - List of result keys to propagate uncertainties into.
- **uncertainty_from** (dict) - Required - Dictionary of uncertainties in input arguments. Keys must match pyco2.sys argument names. Values are standard deviations (single value or array). Append "__f" to a key for fractional uncertainty. Prefix with "p" for pK values. Append "_both" to input condition key for covarying equilibrium constant uncertainties.

### Request Example
```python
import PyCO2SYS as pyco2

kwargs = {
    "par1": 2150.0,
    "par2": 8.1,
    "par1_type": 2,
    "par2_type": 3,
    "temperature": 10,
}

results = pyco2.sys(
    **kwargs,
    uncertainty_into=["alkalinity", "k_carbonic_1"],
    uncertainty_from={
        "par1": 2.0,
        "temperature": 0.05,
    }
)
```

### Response
#### Success Response
Returns the standard results dict with additional keys:
- **u_<into>** (float or array) - Total uncertainty in the result from all arguments combined.
- **u_<into>__<from>** (float or array) - Uncertainty in the result from only the specified argument.

#### Response Example
```python
# results dict includes standard keys plus:
# results['u_alkalinity'] = ...
# results['u_alkalinity__par1'] = ...
# results['u_alkalinity__temperature'] = ...
# results['u_k_carbonic_1'] = ...
# results['u_k_carbonic_1__par1'] = ...
# results['u_k_carbonic_1__temperature'] = ...
```
```

--------------------------------

### pyco2.sys with grads_of and grads_wrt

Source: https://pyco2sys.readthedocs.io/en/latest/uncertainty

Example of calling PyCO2SYS with derivative calculation options to obtain forward finite-difference derivatives of specified results with respect to specified arguments.

```APIDOC
## pyco2.sys

### Description
Calculates carbonate system parameters and optionally forward finite-difference derivatives of specified results with respect to specified arguments.

### Parameters
#### Request Body
- **par1** (float) - Required - First carbonate system parameter.
- **par2** (float) - Required - Second carbonate system parameter.
- **par1_type** (int) - Required - Type code for par1.
- **par2_type** (int) - Required - Type code for par2.
- **temperature** (float) - Required - Temperature in degrees Celsius.
- **grads_of** (list of str) - Optional - List of result names for which derivatives are calculated.
- **grads_wrt** (list or dict) - Optional - List or dict of argument names with respect to which derivatives are calculated. Values are ignored if dict.

### Request Example
```python
import PyCO2SYS as pyco2

kwargs = {
    "par1": 2150.0,
    "par2": 8.1,
    "par1_type": 2,
    "par2_type": 3,
    "temperature": 10,
}

results = pyco2.sys(
    **kwargs,
    grads_of=["alkalinity", "k_carbonic_1"],
    grads_wrt=["par1", "temperature"],
)
```

### Response
#### Success Response (200)
- **results** (dict) - Dictionary containing calculated carbonate system parameters and derivative keys.
- **d_<into>__d_<from>** (float) - Derivative of the result specified in grads_of with respect to the argument specified in grads_wrt.

#### Response Example
```python
# results dict includes keys like 'd_alkalinity__d_par1', 'd_alkalinity__d_temperature', etc.
```
```

--------------------------------

### Check PyCO2SYS version

Source: https://pyco2sys.readthedocs.io

Use the hello function to display the version of the installed PyCO2SYS package.

```python
import PyCO2SYS as pyco2
pyco2.hello()
```

--------------------------------

### Install PyCO2SYS with conda/mamba

Source: https://pyco2sys.readthedocs.io

Install the package from the conda-forge channel.

```bash
conda install PyCO2SYS -c conda-forge
```

--------------------------------

### Import and run the original CO2SYS clone

Source: https://pyco2sys.readthedocs.io/en/latest/co2sys

Shows how to import the original CO2SYS clone and run it with the required inputs, returning DATA, HEADERS, and NICEHEADERS.

```APIDOC
## Import and run the original CO2SYS clone

### Description
Import the original CO2SYS clone and run it with the required inputs.

### Usage
```python
from PyCO2SYS.original import CO2SYS

DATA, HEADERS, NICEHEADERS = CO2SYS(PAR1, PAR2, PAR1TYPE, PAR2TYPE,
    SAL, TEMPIN, TEMPOUT, PRESIN, PRESOUT, SI, PO4,
    pHSCALEIN, K1K2CONSTANTS, KSO4CONSTANTS)
```

### Parameters
- **PAR1** (float) - Required - First carbonate system parameter.
- **PAR2** (float) - Required - Second carbonate system parameter.
- **PAR1TYPE** (int) - Required - Type of PAR1, must be from 1 to 5 inclusive.
- **PAR2TYPE** (int) - Required - Type of PAR2, must be from 1 to 5 inclusive.
- **SAL** (float) - Required - Salinity.
- **TEMPIN** (float) - Required - Input temperature.
- **TEMPOUT** (float) - Required - Output temperature.
- **PRESIN** (float) - Required - Input pressure.
- **PRESOUT** (float) - Required - Output pressure.
- **SI** (float) - Required - Silicate concentration.
- **PO4** (float) - Required - Phosphate concentration.
- **pHSCALEIN** (int) - Required - pH scale for input.
- **K1K2CONSTANTS** (int) - Required - Choice of K1 and K2 constants.
- **KSO4CONSTANTS** (int) - Required - Choice of KSO4 constants.

### Returns
- **DATA** (numpy.ndarray) - Matrix of all calculated values.
- **HEADERS** (list) - Variable names for each column of DATA.
- **NICEHEADERS** (list) - Alternative headers with more information.

### Notes
- PAR1TYPE and PAR2TYPE can only take values from 1 to 5 inclusive.
- Optional extra inputs (NH3, H2S, KFCONSTANT) are not allowed.
- Outputs do not include buffer factors other than the Revelle factor, no Peng correction, KSO4CONSTANTS is not split, no NH3/H2S outputs, TCa is not provided.

```

--------------------------------

### Upgrade PyCO2SYS with pip

Source: https://pyco2sys.readthedocs.io

Update an existing installation of the package.

```bash
pip install PyCO2SYS --upgrade --no-cache-dir
```

--------------------------------

### Import and Function Syntax

Source: https://pyco2sys.readthedocs.io/en/latest/versions

Demonstrates the import of the PyCO2SYS library and the usage of both the new Pythonic syntax and the legacy MATLAB-style syntax.

```python
import PyCO2SYS as pyco2
results = pyco2.sys(*args, **kwargs)  # new Pythonic syntax
results = pyco2.CO2SYS(*args, **kwargs)  # old MATLAB syntax
```

--------------------------------

### Calculate derivatives with PyCO2SYS

Source: https://pyco2sys.readthedocs.io/en/latest/uncertainty

Demonstrates how to calculate derivatives alongside standard PyCO2SYS results by specifying the target results and input arguments.

```python
import PyCO2SYS as pyco2

# Example arguments: known DIC and pH, at 10 degC
kwargs = {
    "par1": 2150.0,
    "par2": 8.1,
    "par1_type": 2,
    "par2_type": 3,
    "temperature": 10,
}

# Normal way to run PyCO2SYS, without derivatives:
results = pyco2.sys(**kwargs)

# Alternatively, calculate derivatives at the same time:
results = pyco2.sys(
    **kwargs,
    grads_of=["alkalinity", "k_carbonic_1"],
    grads_wrt=["par1", "temperature"],
)
```

--------------------------------

### Convert MATLAB-style outputs to CO2dict

Source: https://pyco2sys.readthedocs.io/en/latest/co2sys

Shows how to convert the MATLAB-style outputs (DATA and HEADERS) into a dictionary comparable to CO2dict.

```APIDOC
## Convert MATLAB-style outputs to CO2dict

### Description
Convert the MATLAB-style outputs from the original CO2SYS clone into a dictionary comparable to CO2dict.

### Usage
```python
CO2dict = {header: DATA[:, h] for h, header in enumerate(HEADERS)}
```

### Parameters
- **DATA** (numpy.ndarray) - Matrix of all calculated values from CO2SYS.
- **HEADERS** (list) - Variable names for each column of DATA.

### Returns
- **CO2dict** (dict) - Dictionary mapping header names to arrays of values.

```

--------------------------------

### Run a round-robin test with PyCO2SYS

Source: https://pyco2sys.readthedocs.io/en/latest/validate

This script demonstrates how to use PyCO2SYS.test.roundrobin to verify the internal consistency of carbonate system calculations for a given set of conditions.

```python
# Import PyCO2SYS
import PyCO2SYS as pyco2

# Define test conditions
par1 = 2300  # parameter 1, here total alkalinity in μmol/kg-sw
par2 = 8.1  # parameter 2, here pH on the Total scale
par1type = 1  # "parameter 1 is total alkalinity"
par2type = 3  # "parameter 2 is pH"
sal = 33  # practical salinity
temp = 22  # temperature in °C
pres = 1000  # pressure in dbar
si = 10  # total silicate in μmol/kg-sw
phos = 1  # total phosphate in μmol/kg-sw
nh3 = 2  # total ammonia in μmol/kg-sw
h2s = 3  # total sulfide in μmol/kg-sw
pHscale = 1  # "input pH is on the Total scale"
k1k2c = 10  # "use LDK00 constants for carbonic acid dissociation"
kso4c = 3  # "use D90a for bisulfate dissociation & LKB10 for borate:sal"

# Run the test
res, diff = pyco2.test.roundrobin(par1, par2, par1type, par2type,
    sal, temp, pres, si, phos, pHscale, k1k2c, kso4c, NH3=nh3, H2S=h2s,
    opt_buffers_mode=0)
```

--------------------------------

### Import and use PyCO2SYS

Source: https://pyco2sys.readthedocs.io

Standard import convention and the primary function call for calculations.

```python
import PyCO2SYS as pyco2
```

```python
results = pyco2.sys(**kwargs)
```
Tokens:
Raw