Metadata-Version: 2.4
Name: scm4opt
Version: 4.1.1
Summary: SCM4OPT: Simple Climate Model for OPTimization (Python version)
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/SooClimate/SCM4OPT_PY
Project-URL: Source, https://github.com/SooClimate/SCM4OPT_PY
Project-URL: Documentation, https://github.com/SooClimate/SCM4OPT_PY/tree/main/docs
Project-URL: Issues, https://github.com/SooClimate/SCM4OPT_PY/issues
Project-URL: Data, https://doi.org/10.5281/zenodo.23718272
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: scm4opt/data/MAGICC6/NOTICE.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# SCM4OPT_PY

[![PyPI](https://img.shields.io/pypi/v/scm4opt)](https://pypi.org/project/scm4opt/)

The Python implementation of SCM4OPT (RCMIP3 model name `SCM4OPT(PY)v4.0`).
SCM4OPT — **S**imple **C**limate **M**odel for **OPT**imization — is a reduced-complexity
coupled climate model: carbon cycle (land, ocean, atmosphere), atmospheric chemistry,
radiative forcing and the DOECLIM energy-balance model, at a 1/6-year time step.
It runs scenario experiments (contribution analysis, RCMIP3) and parameter ensembles.

Version 4.1.1.

## Documentation

`docs/`: the [user guide](docs/user_guide.md), the [developer guide](docs/developer_guide.md),
and references generated from the code: [options](docs/options.md),
[variables](docs/variables.md) and the [API](docs/api/README.md).

## Install

```bash
pip install scm4opt         # from PyPI
# or, from a clone of this repository:
pip install -e .            # numpy, pandas, scipy
pip install -e ".[test]"    # pytest
```

Python >= 3.10. Ensembles also need GNU parallel. All inputs and outputs are CSV.

## Data

The parameter tables (CMIP6 calibrations, natural forcing, RCMIP3 output mapping,
ensemble members, ...) are in `scm4opt/data/`, tracked in git and installed with the
package. This repository also holds 80 scenario input files, in
`scm4opt/data/RCMIP3/`, `contrib/` (land cover), `AGAGE/` and `NOAA/`: those of the tests
and of the RCMIP3 experiments
`historical`, `esm-hist`, `esm-allGHG-hist`,
from 1850 and, with `--first_year=1750`, from 1750. They are listed with their size and
SHA-256 checksum in `scm4opt/data/inputs_manifest.csv` and installed with the package
(also by `pip install scm4opt`). These runs need no other download:

```bash
scm4opt --scen=rcmip3 --rname=historical --load_conc=all --rout3=out/
scm4opt --scen=rcmip3 --rname=esm-hist --load_conc=nco2 --first_year=1750 --rout3=out/
scm4opt ensemble --rname=esm-allGHG-hist -j 8 --cases=0-49
scm4opt data verify                              # files against inputs_manifest.csv
```

The inputs of the other experiments and of the contribution runs are distributed
separately as SCM4OPT_PY_DAT, published on Zenodo:
[doi:10.5281/zenodo.23718272](https://doi.org/10.5281/zenodo.23718272) (from 1850 only so
far). Download it into a folder and point the model to that folder with
`export SCM4OPT_DATA=/path/to/SCM4OPT_PY_DAT` (or `--dat_dir=...` per run); parameter tables
missing there are taken from `scm4opt/data/`. Further input files copied into
`scm4opt/data/` are git-ignored.

## Run

```bash
scm4opt --scen=contrib --psrc=IAMC --psce=SSP1_19
scm4opt --scen=rcmip3 --rname=ssp585 --load_conc=all --rout3=out/
scm4opt --scen=rcmip3 --rname=ssp126 --ocean_model=hector --cm6mdl=MIROC6
scm4opt ensemble --rname=ssp585 -j 8 --cases=0-49
scm4opt export --sce=ssp585 --out_dir=ens/      # members -> RCMIP3 ensemble file
bash scm4opt/run_rcmip3_all_py.sh -j 8          # every RCMIP3 experiment (--help)
python3 -m scm4opt --help
```

Options are given as `--name=value` flags; see `scm4opt/scenarios/forward.py` and
`scm4opt/core/config.py` for all of them.

## Names

* Output variables: `<prefix>_<name>`, with the prefix of the producing module:
  `scm_` (coupling between modules), `chm_` (chemistry), `rfc_` / `erf_` (radiative
  forcing / effective radiative forcing), `doe_` (DOECLIM), `lnd_` (land), `ocn_`
  (OSCAR ocean), `hct_` (Hector ocean), `dat_` (inputs).
  `D_` marks an anomaly against the pre-industrial state (e.g. `chm_D_CH4`).
* Parameters: snake_case, `<quantity>_<species/box>_<qualifier>` (e.g. `tau_ch4_oh`,
  `alpha_n2o`, `d_ch4_1850` for an anomaly); values per model step end in `_per_step`.
* `scm4opt/data/registry/registry.csv` lists every output and parameter with its
  module, dimensions, unit, time basis (state / per_step / per_year / none),
  description and position in the model report. The report symbol list and the
  RCMIP3 export's time aggregation are generated from it; `python3 -m
  scm4opt.core.registry` checks the units (grammar in `scm4opt/core/units.py`) and
  every RCMIP3 export conversion against them.

## Package layout

| Subpackage | Contents |
|---|---|
| `core` | run configuration (`config`), constants, index sets |
| `physics` | atmosphere, chemistry, forcing, DOECLIM, land, ocean (OSCAR, Hector) |
| `scenarios` | coupled forward run (`forward`), RCMIP3 experiment tables (`rcmip3_data`) |
| `io` | inputs (CSV), report, RCMIP3 rows and ensemble export (`rcmip_export`) |
| `ensemble`, `cli` | ensemble driver, command line |

## Reference compatibility (`--ref_compat`)

By default (`--ref_compat=1`) the model reproduces the SCM4OPT v4.1 reference results
bit for bit, including a few known quirks. `--ref_compat=0` uses the corrected
behaviour instead:

* ocean carbon (OSCAR): the air-sea flux is computed from the outflows that drive the
  box integration, so ocean and atmosphere carbon are mass-consistent (the reference
  form loses about 2 GtC by 2100);
* Hector ocean with `--scen=tcre/tcre2`: the transport rates are recomputed;
* ocean heat diagnostics: the mixed-layer heat uptake is a flux in W/m2 and the heat
  content is the sum of the mixed-layer and interior heat (temperatures are unchanged);
* RCMIP3 export: ocean heat content and uptake converted with the factors implied by
  their units (1e22 J = 10 ZJ; the uptake as an annual mean); yearly means over all
  steps and every row kept;
* the temperature derivatives of the OH and photolysis attribution helpers.

Submitted RCMIP3 results use the default. `tests/test_compat.py` checks the corrected
branches.

## Tests

```bash
pytest tests/
```

The regression tests compare against reference outputs written by the export; the
registry tests check units and the RCMIP3 export conversions. GitHub Actions runs
them on Python 3.10 and 3.13 (`.github/workflows/tests.yml`).

## License and citation

The code is licensed under the GNU General Public License, version 3 or later
(`LICENSE`). It contains parts derived from Hector (GPL-3.0), OSCAR (CeCILL 2.1),
DOECLIM and MAGICC6; see `NOTICE` for the credits and references. To cite SCM4OPT, see
`CITATION.cff`.

`scm4opt/data/MAGICC6/land_c4mip_bern.csv` (the land parameters of the MAGICC6-defaults
mode, used when no `--cm6mdl` calibration is selected) comes from the configuration
files distributed with the MAGICC6 executable and keeps their license, Creative Commons
Attribution-NonCommercial-ShareAlike 3.0 (see `scm4opt/data/MAGICC6/NOTICE.txt`; cite
Meinshausen et al., 2011, doi:10.5194/acp-11-1417-2011). It is not covered by the code
license.
