### 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
```

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

### 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 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.

```

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

### 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)
```

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

### Import and run the original CO2SYS clone

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

Use this to access the legacy CO2SYS function. Note that this version has restricted input and output capabilities compared to the Pythonised version.

```python
# Import the original CO2SYS clone
from PyCO2SYS.original import CO2SYS

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

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

### Basic pyco2.sys syntax

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

The recommended way to run PyCO2SYS from v1.6.0. Requires values for two carbonate system parameters (par1 and par2) and their types (par1_type and par2_type). All other arguments use default values unless overridden via kwargs.

```python
import PyCO2SYS as pyco2
results = pyco2.sys(
    par1=None, par2=None, par1_type=None, par2_type=None, **kwargs
)
```

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

### PyCO2SYS.CO2SYS Inputs

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

Documentation of the input parameters for the PyCO2SYS.CO2SYS function, including carbonate system parameters, hydrographic conditions, and nutrients.

```APIDOC
## PyCO2SYS.CO2SYS Inputs

### Description
This function calculates the full carbonate system from two known parameters and hydrographic conditions. Inputs can be scalar values or NumPy arrays of the same size.

### Parameters
#### Carbonate system parameters
- **PAR1** (float or array) - Required - Value of the first carbonate system parameter.
- **PAR2** (float or array) - Required - Value of the second carbonate system parameter.
- **PAR1TYPE** (int) - Required - Type of PAR1 (1: Total alkalinity, 2: Dissolved inorganic carbon, 3: pH, 4: Partial pressure of CO2, 5: Fugacity of CO2, 6: Carbonate ion, 7: Bicarbonate ion, 8: Aqueous CO2).
- **PAR2TYPE** (int) - Required - Type of PAR2 (same options as PAR1TYPE).

#### Hydrographic conditions
- **SAL** (float or array) - Required - Practical salinity (dimensionless).
- **TEMPIN** (float or array) - Required - Temperature at which PAR1 and PAR2 are provided, in °C.
- **TEMPOUT** (float or array) - Required - Temperature at which output results are calculated, in °C.
- **PRESIN** (float or array) - Required - Pressure at which PAR1 and PAR2 are provided, in dbar.
- **PRESOUT** (float or array) - Required - Pressure at which output results are calculated, in dbar.

#### Nutrients and other solutes
- **SI** (float or array) - Required - Total silicate in μmol·kg−1.
- **PO4** (float or array) - Required - Total phosphate in μmol·kg−1.
- **NH3** (float or array) - Optional - Total ammonia in μmol·kg−1 (defaults to 0).
- **H2S** (float or array) - Optional - Total hydrogen sulfide in μmol·kg−1 (defaults to 0).

### Notes
- All concentrations in μmol·kg−1 refer to the total solution, not H2O.
- pH scale is specified by the input pHSCALEIN (not listed here).
- If arrays are used, they must all be the same size; scalars can be combined with arrays.
```

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

### Totals Estimated from Salinity Output Options

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

Output options for total concentrations estimated from salinity.

```APIDOC
## Totals Estimated from Salinity Output Options

### Description
Total concentrations estimated from salinity.

### Options
- `"total_borate"`: total borate in umol/kg.
- `"total_fluoride"`: total fluoride in umol/kg.
- `"total_sulfate"`: total sulfate in umol/kg.
- `"total_calcium"`: total calcium in umol/kg.
```

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

### Buffer Factors Output Options

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

Output options for buffer factors, controlled by the opt_buffers_mode input. Each option has an input key and an output key (with _out suffix) for input and output conditions.

```APIDOC
## Buffer Factors Output Options

### Description
These output options are controlled by the input `opt_buffers_mode`. Each option has an input key and an output key (with `_out` suffix) for input and output conditions.

### Options
- `"revelle_factor"` / `"revelle_factor_out"`: Revelle factor at input/output conditions.
- `"psi"` / `"psi_out"`: psi of FCG94 at input/output conditions.
- `"gamma_dic"` / `"gamma_dic_out"`: buffer factor gamma DIC of ESM10 at input/output conditions.
- `"beta_dic"` / `"beta_dic_out"`: buffer factor beta DIC of ESM10 at input/output conditions.
- `"omega_dic"` / `"omega_dic_out"`: buffer factor omega DIC of ESM10 at input/output conditions.
- `"gamma_alk"` / `"gamma_alk_out"`: buffer factor gamma TA of ESM10 at input/output conditions.
- `"beta_alk"` / `"beta_alk_out"`: buffer factor beta TA of ESM10 at input/output conditions.
- `"omega_alk"` / `"omega_alk_out"`: buffer factor omega TA of ESM10 at input/output conditions.
- `"isocapnic_quotient"` / `"isocapnic_quotient_out"`: isocapnic quotient of HDW18 at input/output conditions.
- `"isocapnic_quotient_approx"` / `"isocapnic_quotient_approx_out"`: isocapnic quotient approximation of HDW18 at input/output conditions.
- `"dlnpCO2_dT"` / `"dlnpCO2_dT_out"`: temperature derivative of ln(fCO2) at input/output conditions (see TOG93).
- `"dlnpCO2_dT"` / `"dlnpCO2_dT_out"`: temperature derivative of ln(pCO2) at input/output conditions (see TOG93).
```

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

### PyCO2SYS.CO2SYS Settings

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

Configuration parameters for the PyCO2SYS.CO2SYS function, including required and optional settings.

```APIDOC
## PyCO2SYS.CO2SYS Settings

### Description
Configuration parameters for the PyCO2SYS.CO2SYS function, including required and optional settings.

### Required Parameters
- **pHSCALEIN** (int) - Required - pH scale used for pH entries in PAR1 or PAR2. Options: 1 (Total), 2 (Seawater), 3 (Free), 4 (NBS).
- **K1K2CONSTANTS** (int) - Required - Set of equilibrium constants for carbonic acid dissociation. Options: 1-17, each with specific temperature and salinity ranges.
- **KSO4CONSTANTS** (int) - Required - Combination of bisulfate dissociation constant and boron:salinity relationship. Options: 1-4.

### Optional Parameters
- **KFCONSTANT** (int) - Optional - Equilibrium constant for hydrogen fluoride dissociation. Options: 1 (DR79, default), 2 (PF87).
- **opt_buffers_mode** (int) - Optional - How to calculate buffer factors. Options: 1 (automatic differentiation, default), 2 (explicit equations), 0 (not at all).
- **WhichR** (int) - Optional - Value for the ideal gas constant R. Options: 1 (DOEv2, default), 2 (DOEv3), 3 (2018 CODATA).

### Internal Overrides
- **totals** (dict) - Optional - Override totals estimated from salinity. Keys correspond to output variables in Totals estimated from salinity.
- **equilibria_in** (dict) - Optional - Override equilibrium constants, fugacity factor, and activity coefficient of H+ at input conditions. Keys correspond to output variables with 'input' removed.
- **equilibria_out** (dict) - Optional - Same as equilibria_in but for output conditions.

### Notes
- All parameters can be a single value or a NumPy array of the same size as other input arrays.
- For opt_buffers_mode, 1 is recommended and most accurate; if 0 is selected, corresponding outputs are nan.
```

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

### Convert MATLAB-style outputs to a dictionary

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

Converts the matrix-based output from the original CO2SYS clone into a dictionary format comparable to CO2dict.

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

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

### pyco2.sys

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

The top-level function to calculate everything you need at once for the marine carbonate system. It requires at least two carbonate system parameters and their types, with optional kwargs for overriding defaults.

```APIDOC
## pyco2.sys

### Description
Calculate everything you need at once for the marine carbonate system. Requires values for two carbonate system parameters (par1 and par2) and their types (par1_type and par2_type). All other parameters are optional and can be provided as keyword arguments.

### Syntax
```
import PyCO2SYS as pyco2
results = pyco2.sys(
    par1=None, par2=None, par1_type=None, par2_type=None, **kwargs
)
```

### Parameters
- **par1** (float or array-like) - Required - First carbonate system parameter value.
- **par2** (float or array-like) - Required - Second carbonate system parameter value.
- **par1_type** (int) - Required - Type code for par1.
- **par2_type** (int) - Required - Type code for par2.
- **kwargs** - Optional - Additional keyword arguments to override default conditions (e.g., temperature, salinity, pressure).

### Notes
- `pyco2.sys` is identical to `pyco2.CO2SYS_nd`.
- From v1.7.0, it is possible to run without any or with just one carbonate system parameter; in that case, the results dict contains equilibrium constants and total salt contents under the specified conditions.
- Can be used to propagate uncertainties through calculations.

### Examples
```
# Basic usage
results = pyco2.sys(par1=8.1, par1_type=3, par2=400, par2_type=5)

# 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)

# 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
)

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

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

### Chemical Speciation Output Options

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

Output options for the molality of each individual chemical species involved in pH equilibria.

```APIDOC
## Chemical Speciation Output Options

### Description
Molality of each individual chemical species involved in pH equilibria. Each option has an input key and an output key (with `_out` suffix) for input and output conditions.

### Options
- `"HCO3"` / `"HCO3_out"`: bicarbonate [HCO3-] at input/output conditions in umol/kg.
- `"CO3"` / `"CO3_out"`: carbonate [CO3^2-] at input/output conditions in umol/kg.
- `"CO2"` / `"CO2_out"`: aqueous carbon dioxide [CO2(aq)] at input/output conditions in umol/kg.
- `"BOH4"` / `"BOH4_out"`: tetrahydroxyborate [B(OH)4-] at input/output conditions in umol/kg.
- `"BOH3"` / `"BOH3_out"`: boric acid [B(OH)3] at input/output conditions in umol/kg.
- `"OH"` / `"OH_out"`: hydroxide [OH-] at input/output conditions in umol/kg.
- `"Hfree"` / `"Hfree_out"`: "free" protons [H+] at input/output conditions in umol/kg.
- `"H3PO4"` / `"H3PO4_out"`: phosphoric acid [H3PO4] at input/output conditions in umol/kg.
- `"H2PO4"` / `"H2PO4_out"`: dihydrogen phosphate [H2PO4-] at input/output conditions in umol/kg.
- `"HPO4"` / `"HPO4_out"`: monohydrogen phosphate [HPO4^2-] at input/output conditions in umol/kg.
- `"PO4"` / `"PO4_out"`: phosphate [PO4^3-] at input/output conditions in umol/kg.
- `"H4SiO4"` / `"H4SiO4_out"`: orthosilicic acid [Si(OH)4] at input/output conditions in umol/kg.
- `"H3SiO4"` / `"H3SiO4_out"`: trihydrogen orthosilicate [SiO(OH)3-] at input/output conditions in umol/kg.
- `"NH3"` / `"NH3_out"`: ammonia [NH3] at input/output conditions in umol/kg.
- `"NH4"` / `"NH4_out"`: ammonium [NH4+] at input/output conditions in umol/kg.
- `"HS"` / `"HS_out"`: bisulfide [HS-] at input/output conditions in umol/kg.
- `"H2S"` / `"H2S_out"`: hydrogen sulfide [H2S] at input/output conditions in umol/kg.
- `"HSO4"` / `"HSO4_out"`: bisulfate [HSO4-] at input/output conditions in umol/kg.
- `"SO4"` / `"SO4_out"`: sulfate [SO4^2-] at input/output conditions in umol/kg.
- `"HF"` / `"HF_out"`: hydrofluoric acid [HF] at input/output conditions in umol/kg.
- `"F"` / `"F_out"`: fluoride [F-] at input/output conditions in umol/kg.
```

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

### Calculate carbonate system variables using MATLAB-style syntax

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

Use the top-level CO2SYS function to calculate all variables at once. Inputs can be scalars or NumPy arrays, and the output is a dictionary of NumPy arrays.

```python
# Import the function
from PyCO2SYS import CO2SYS

# Run CO2SYS
CO2dict = CO2SYS(PAR1, PAR2, PAR1TYPE, PAR2TYPE, SAL, TEMPIN, TEMPOUT,
    PRESIN, PRESOUT, SI, PO4, pHSCALEIN, K1K2CONSTANTS, KSO4CONSTANTS,
    NH3=0.0, H2S=0.0, KFCONSTANT=1, opt_buffers_mode=1,
    totals=None, equilibria_in=None, equilibria_out=None, WhichR=1)

# Get (e.g.) aragonite saturation state, output conditions
OmegaARout = CO2dict["OmegaARout"]
```

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

### CO2SYS_wrap (Pythonic API)

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

Pythonic wrapper that returns a Pandas DataFrame. Uses keyword arguments and only requires the specified marine carbonate system parameters.

```APIDOC
## CO2SYS_wrap (Pythonic API)

### Description
Pythonic wrapper for CO2SYS that returns a Pandas DataFrame. Uses keyword arguments and only requires the specified marine carbonate system parameters. Accepts NumPy arrays, pandas.Series, or xarray.DataArrays as inputs.

### Function Signature
CO2SYS_wrap(dic=None, alk=None, pco2=None, fco2=None, pH=None, carb=None, bicarb=None, co2aq=None, temp_in=25, temp_out=25, pres_in=0, pres_out=0, sal=35, si=0, po4=0, nh3=0, h2s=0, K1K2_constants=4, KSO4_constants=1, KF_constant=1, pHscale_in=1, opt_buffers_mode=1, verbose=True)

### Parameters
#### Keyword Parameters
- **dic** (float or array) - Optional - Dissolved inorganic carbon.
- **alk** (float or array) - Optional - Alkalinity.
- **pco2** (float or array) - Optional - Partial pressure of CO2.
- **fco2** (float or array) - Optional - Fugacity of CO2.
- **pH** (float or array) - Optional - pH value.
- **carb** (float or array) - Optional - Carbonate ion concentration.
- **bicarb** (float or array) - Optional - Bicarbonate ion concentration.
- **co2aq** (float or array) - Optional - Aqueous CO2 concentration.
- **temp_in** (float, optional) - Default 25 - Input temperature.
- **temp_out** (float, optional) - Default 25 - Output temperature.
- **pres_in** (float, optional) - Default 0 - Input pressure.
- **pres_out** (float, optional) - Default 0 - Output pressure.
- **sal** (float, optional) - Default 35 - Salinity.
- **si** (float, optional) - Default 0 - Silicate concentration.
- **po4** (float, optional) - Default 0 - Phosphate concentration.
- **nh3** (float, optional) - Default 0 - Ammonia concentration.
- **h2s** (float, optional) - Default 0 - Hydrogen sulfide concentration.
- **K1K2_constants** (int, optional) - Default 4 - K1K2 constants option.
- **KSO4_constants** (int, optional) - Default 1 - KSO4 constants option.
- **KF_constant** (int, optional) - Default 1 - KF constant option.
- **pHscale_in** (int, optional) - Default 1 - pH scale input.
- **opt_buffers_mode** (int, optional) - Default 1 - Buffer mode option.
- **verbose** (bool, optional) - Default True - Whether to print verbose output.

### Returns
- **pandas.DataFrame** - A DataFrame with the same output names as the dict from CO2SYS.

### Limitations
- Only a single input pair combination per call; other parameters must be set to None.
- Does not support the totals, equilibria_in, and equilibria_out optional inputs.

### Example
```python
from PyCO2SYS.api import CO2SYS_wrap as co2sys

df1 = co2sys(dic=2103, alk=2360)
```
```

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

### pyco2.sys

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

The main function of the PyCO2SYS package for solving the marine carbonate system. It accepts various carbonate system parameters, hydrographic conditions, and nutrient concentrations, and returns a dictionary of results.

```APIDOC
## pyco2.sys

### Description
Solves the marine carbonate system from user-provided parameters. Accepts either two, one, or no carbonate system parameters, along with hydrographic conditions and optional nutrient concentrations.

### Method
Function call

### Endpoint
pyco2.sys

### Parameters
#### Carbonate system parameters
- **par1** (float or numpy.ndarray) - Required - Value of the first carbonate system parameter.
- **par2** (float or numpy.ndarray) - Optional - Value of the second carbonate system parameter. Required if two parameters are provided.
- **par1_type** (int) - Required - Type of the first parameter. See parameter types below.
- **par2_type** (int) - Optional - Type of the second parameter. Required if two parameters are provided.

Parameter types:
- 1: Total alkalinity (μmol·kg−1)
- 2: Dissolved inorganic carbon (μmol·kg−1)
- 3: pH (on Total, Seawater, Free, or NBS scale, specified by opt_pH_scale)
- 4: Partial pressure of CO2 (μatm)
- 5: Fugacity of CO2 (μatm)
- 6: Carbonate ion (μmol·kg−1)
- 7: Bicarbonate ion (μmol·kg−1)
- 8: Aqueous CO2 (μmol·kg−1)
- 9: Dry mole fraction of CO2 (ppm)
- 10: Saturation state w.r.t. calcite
- 11: Saturation state w.r.t. aragonite

#### Hydrographic conditions
- **salinity** (float or numpy.ndarray) - Optional - Practical salinity. Default: 35.
- **temperature** (float or numpy.ndarray) - Optional - Temperature at which par1 and par2 are provided, in °C. Default: 25 °C.
- **pressure** (float or numpy.ndarray) - Optional - Water pressure at which par1 and par2 are provided, in dbar. Default: 0 dbar.
- **temperature_out** (float or numpy.ndarray) - Optional - Temperature at which results will be calculated, in °C. If not provided, calculations are only at input conditions.
- **pressure_out** (float or numpy.ndarray) - Optional - Water pressure at which results will be calculated, in dbar. If not provided, calculations are only at input conditions.

#### Nutrients and other solutes
- **total_silicate** (float or numpy.ndarray) - Optional - Total silicate in μmol·kg−1. Default: 0.
- **total_phosphate** (float or numpy.ndarray) - Optional - Total phosphate in μmol·kg−1. Default: 0.
- **total_ammonia** (float or numpy.ndarray) - Optional - Total ammonia in μmol·kg−1. Default: 0.
- **total_sulfide** (float or numpy.ndarray) - Optional - Total hydrogen sulfide in μmol·kg−1. Default: 0.
- **total_alpha** (float or numpy.ndarray) - Optional - Total Hα (user-defined extra contributor to alkalinity) in μmol·kg−1. Default: 0.
- **total_beta** (float or numpy.ndarray) - Optional - Total Hβ (user-defined extra contributor to alkalinity) in μmol·kg−1. Default: 0.
- **k_alpha** (float or numpy.ndarray) - Optional - Equilibrium constant for total_alpha. Required if total_alpha is non-zero.
- **k_beta** (float or numpy.ndarray) - Optional - Equilibrium constant for total_beta. Required if total_beta is non-zero.
- **total_borate** (float or numpy.ndarray) - Optional - Total borate in μmol·kg−1. If not provided, estimated from salinity. If provided, opt_total_borate is ignored.
- **total_calcium** (float or numpy.ndarray) - Optional - Total calcium in μmol·kg−1. If not provided, estimated from salinity.
- **total_fluoride** (float or numpy.ndarray) - Optional - Total fluoride in μmol·kg−1. If not provided, estimated from salinity.
- **total_sulfate** (float or numpy.ndarray) - Optional - Total sulfate in μmol·kg−1. If not provided, estimated from salinity.

### Request Example
pyco2.sys(par1=2300, par2=2000, par1_type=1, par2_type=2, salinity=35, temperature=25, pressure=0)

### Response
Returns a dictionary (CO2_results) containing calculated carbonate system parameters and related quantities. If temperature_out or pressure_out are provided, results with keys ending with '_out' are also returned.

### Notes
- All arguments can be scalars or NumPy arrays, and must be broadcastable with each other.
- All concentrations are in μmol·kg−1, where kg refers to the total solution, not H2O.
- If one parameter is provided, only some results can be calculated; pH is converted to all scales, and CO2 parameters are calculated at input conditions.
- If no parameters are provided, all equilibrium constants and total salt contents are returned.
```

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

### Biological Properties Output Options

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

Output options for seawater properties related to the marine carbonate system that have a primarily biological application.

```APIDOC
## Biological Properties Output Options

### Description
Seawater properties related to the marine carbonate system that have a primarily biological application.

### Options
- `"substrate_inhibitor_ratio"` / `"substrate_inhibitor_ratio_out"`: substrate:inhibitor ratio of B15 at input/output conditions in mol(HCO3-) * umol(H+)^-1.
```

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

### Calculate carbonate system variables using the Pythonic API

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

The CO2SYS_wrap function provides a more Pythonic interface that returns a Pandas DataFrame. It uses keyword arguments, allowing you to specify only the necessary parameters.

```python
from PyCO2SYS.api import CO2SYS_wrap as co2sys

# Call with defaults
df1 = co2sys(dic=2103, alk=2360)

# The above is equivalent to:
df1 = co2sys(
    dic=2103, alk=2360, pco2=None, fco2=None, pH=None,
    carb=None, bicarb=None, co2aq=None,
    temp_in=25, temp_out=25, pres_in=0, pres_out=0,
    sal=35, si=0, po4=0, nh3=0, h2s=0,
    K1K2_constants=4, KSO4_constants=1, KF_constant=1, pHscale_in=1,
    opt_buffers_mode=1, verbose=True)
```

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

### Override equilibrium constants

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

All the equilibrium constants needed by PyCO2SYS are estimated internally from temperature, salinity and pressure, and returned in the results. However, you can also directly provide your own values for any of these constants instead. To do this, the arguments have the same keywords as the corresponding results dict keys.

```APIDOC
## Override equilibrium constants

### Description
All the equilibrium constants needed by PyCO2SYS are estimated internally from temperature, salinity and pressure, and returned in the results. However, you can also directly provide your own values for any of these constants instead. To do this, the arguments have the same keywords as the corresponding results dict keys.

### Parameters
- **k_water** (float) - Optional - Water dissociation constant value at input conditions. Example: k_water=1e-14.
- **k_alpha** (float) - Optional - Stoichiometric dissociation constant value for alpha. Required if total_alpha is non-zero.
- **k_alpha_out** (float) - Optional - Stoichiometric dissociation constant value for alpha at output conditions. Required if total_alpha is non-zero.
- **k_beta** (float) - Optional - Stoichiometric dissociation constant value for beta. Required if total_beta is non-zero.
- **k_beta_out** (float) - Optional - Stoichiometric dissociation constant value for beta at output conditions. Required if total_beta is non-zero.

### Notes
- If k_alpha/k_alpha_out and/or k_beta/k_beta_out are not provided, they default to pK = 7.
```

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

### CO2SYS (MATLAB-style)

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

Top-level function that calculates all carbonate system variables using MATLAB-style syntax. Accepts scalar or NumPy array inputs and returns a dict of NumPy arrays.

```APIDOC
## CO2SYS (MATLAB-style)

### Description
Calculates all carbonate system variables using MATLAB-style syntax. Accepts scalar or NumPy array inputs and returns a dict of NumPy arrays.

### Function Signature
CO2SYS(PAR1, PAR2, PAR1TYPE, PAR2TYPE, SAL, TEMPIN, TEMPOUT, PRESIN, PRESOUT, SI, PO4, pHSCALEIN, K1K2CONSTANTS, KSO4CONSTANTS, NH3=0.0, H2S=0.0, KFCONSTANT=1, opt_buffers_mode=1, totals=None, equilibria_in=None, equilibria_out=None, WhichR=1)

### Parameters
#### Positional Parameters
- **PAR1** (float or array) - Required - First carbonate system parameter.
- **PAR2** (float or array) - Required - Second carbonate system parameter.
- **PAR1TYPE** (int) - Required - Type of PAR1.
- **PAR2TYPE** (int) - Required - Type of PAR2.
- **SAL** (float or array) - Required - Salinity.
- **TEMPIN** (float or array) - Required - Input temperature.
- **TEMPOUT** (float or array) - Required - Output temperature.
- **PRESIN** (float or array) - Required - Input pressure.
- **PRESOUT** (float or array) - Required - Output pressure.
- **SI** (float or array) - Required - Silicate concentration.
- **PO4** (float or array) - Required - Phosphate concentration.
- **pHSCALEIN** (int) - Required - pH scale input.
- **K1K2CONSTANTS** (int) - Required - K1K2 constants option.
- **KSO4CONSTANTS** (int) - Required - KSO4 constants option.

#### Keyword Parameters
- **NH3** (float, optional) - Default 0.0 - Ammonia concentration.
- **H2S** (float, optional) - Default 0.0 - Hydrogen sulfide concentration.
- **KFCONSTANT** (int, optional) - Default 1 - KF constant option.
- **opt_buffers_mode** (int, optional) - Default 1 - Buffer mode option.
- **totals** (dict, optional) - Default None - Internal overrides.
- **equilibria_in** (dict, optional) - Default None - Internal overrides.
- **equilibria_out** (dict, optional) - Default None - Internal overrides.
- **WhichR** (int, optional) - Default 1 - Which R constant to use.

### Returns
- **dict** - A dict containing NumPy arrays with all calculated variables. For example, 'OmegaARout' for aragonite saturation state at output conditions.

### Example
```python
from PyCO2SYS import CO2SYS

CO2dict = CO2SYS(PAR1, PAR2, PAR1TYPE, PAR2TYPE, SAL, TEMPIN, TEMPOUT,
    PRESIN, PRESOUT, SI, PO4, pHSCALEIN, K1K2CONSTANTS, KSO4CONSTANTS,
    NH3=0.0, H2S=0.0, KFCONSTANT=1, opt_buffers_mode=1,
    totals=None, equilibria_in=None, equilibria_out=None, WhichR=1)

OmegaARout = CO2dict["OmegaARout"]
```
```

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

### Propagate uncertainties with pyco2.sys

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

Perform uncertainty propagation by passing uncertainty_into and uncertainty_from keyword arguments to the pyco2.sys function.

```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 uncertainties:
results = pyco2.sys(**kwargs)

# Alternatively, calculate uncertainties at the same time:
results = pyco2.sys(
    **kwargs,
    uncertainty_into=["alkalinity", "k_carbonic_1"],
    uncertainty_from={
        "par1": 2.0,
        "temperature": 0.05,
    }
)
```