cnit 2.1.0__tar.gz

cnit-2.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Gang Tang and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cnit-2.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: cnit
+Version: 2.1.0
+Summary: CNit: A Coupled Carbon-Nitrogen Cycle Model (Python)
+Author-email: Gang Tang <gang.tang.au@gmail.com>, Zebedee Nicholls <zebedee.nicholls@climate-energy-college.org>, Alexander Norton <alex.norton@csiro.au>, Sönke Zaehle <szaehle@bgc-jena.mpg.de>, Malte Meinshausen <malte.meinshausen@unimelb.edu.au>
+Maintainer-email: Gang Tang <gang.tang.au@gmail.com>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/gangtang-au/cnit
+Project-URL: Documentation, https://cnit.readthedocs.io
+Project-URL: Repository, https://github.com/gangtang-au/cnit
+Project-URL: Changelog, https://cnit.readthedocs.io/en/latest/changelog.html
+Keywords: cnit,carbon cycle,nitrogen cycle,simple climate model,magicc
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: xarray==2023.6.0
+Requires-Dist: netCDF4
+Requires-Dist: attrs
+Requires-Dist: openscm-units>=0.5.0
+Requires-Dist: pint>=0.19
+Provides-Extra: notebook
+Requires-Dist: notebook<7,>=6; extra == "notebook"
+Requires-Dist: matplotlib; extra == "notebook"
+Provides-Extra: docs
+Requires-Dist: sphinx>=1.4; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.22; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-regressions[dataframe]; extra == "tests"
+
+<p align="left">
+  <img src="docs/_static/CNit_logo.png" alt="CNit logo" width="100">
+</p>
+
+**CNit** (Carbon-Nitrogen Interactions in Terrestrial ecosystems) is a process-based 
+terrestrial biogeochemistry model that simulates coupled carbon and nitrogen cycles 
+in terrestrial ecosystems.  It is the land component of **MAGICC** (Model for the 
+Assessment of Greenhouse Gas Induced Climate Change). 
+
+## Features
+
+* Explicit carbon-nitrogen coupling with nitrogen limitation feedbacks
+* Four nitrogen pools (plant, litter, soil, mineral) and three carbon pools
+* Environmental modifiers: CO₂ fertilization, temperature, land use
+* Separation of deforestation and afforestation for CDR scenarios
+* Annual timestep with sub-annual process representation
+
+## Installation
+
+**For users:**
+
+```bash
+pip install cnit
+```
+
+**For developers:**
+
+To set up a development environment for this project, follow these steps:
+
+1. **Create a new conda environment** (replace `cnit` with your preferred name if desired):
+
+   ```bash
+   conda create --name cnit python=3.9
+   ```
+
+2. **Activate your environment**:
+
+   ```bash
+   conda activate cnit
+   ```
+
+3. **Install all dependencies and set up the package**:
+
+   ```bash
+   make env
+   ```
+
+This will install all required dependencies (including notebook, docs, and testing tools) and install the package in editable mode.
+
+> **Note:**  
+> The Makefile will check that you are not in the `base` environment and will refuse to run if you are.
+
+---
+
+**TL;DR:**
+```bash
+conda create --name cnit python=3.9
+conda activate cnit
+make env
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from cnit import CNitModel, CNitModelConfig, CNitExpConfig
+from cnit import Q # Local pint.quantity class for units handling
+
+# Create model with default parameters
+config = CNitModelConfig()
+model = CNitModel.from_config(config)
+
+# Set up time axis and forcing
+time_axis = Q(np.arange(1850, 2101), "yr")
+n_steps = len(time_axis)
+
+# Simple forcing (constant values for illustration)
+dT_s = Q(np.linspace(0, 2, n_steps), "K")  # 2°C warming
+CO2_s = Q(np.linspace(280, 560, n_steps), "ppm")  # CO2 doubling
+
+# Land use emissions (zero for simplicity)
+CemsLUnet_s = Q(np.zeros(n_steps), "GtC/yr")
+CemsLUgrs_s = Q(np.zeros(n_steps), "GtC/yr")
+
+# Nitrogen inputs
+NflxAD_s = Q(np.linspace(0.05, 0.15, n_steps), "GtN/yr")  # Increasing deposition
+NflxFT_s = Q(np.linspace(0, 0.1, n_steps), "GtN/yr")  # Increasing fertilizer
+
+# Nitrogen land use emissions
+NemsLUnet_s = Q(np.zeros(n_steps), "GtN/yr")
+NemsLUgrs_s = Q(np.zeros(n_steps), "GtN/yr")
+NemsLUmin_s = Q(np.zeros(n_steps), "GtN/yr")
+
+# Run the model
+res = model.run(
+    time_axis=time_axis,
+    dT_s=dT_s,
+    CO2_s=CO2_s,
+    CemsLUnet_s=CemsLUnet_s,
+    CemsLUgrs_s=CemsLUgrs_s,
+    NflxAD_s=NflxAD_s,
+    NflxFT_s=NflxFT_s,
+    NemsLUnet_s=NemsLUnet_s,
+    NemsLUgrs_s=NemsLUgrs_s,
+    NemsLUmin_s=NemsLUmin_s,
+)
+
+# Access results
+cveg, cveg_unit = res["CplsP"].data, res["CplsP"].units
+nveg, nveg_unit = res["NplsP"].data, res["NplsP"].units
+npp, npp_unit = res["CflxNPP"].data, res["CflxNPP"].units
+
+print(f"Final plant carbon: {cveg[-1]} {cveg_unit}")
+print(f"Final plant nitrogen: {nveg[-1]} {nveg_unit}")
+print(f"NPP change: {npp[0]} → {npp[-1]} {npp_unit}")
+```
+
+## Documentation
+The full documentation for CNit is available at 
+[https://cnit.readthedocs.io](https://cnit.readthedocs.io).
+
+## License
+BSD 3-Clause License. See LICENSE for details.
+
+Copyright (c) 2026, Gang Tang and contributors.
+
+## Authors and Contributors
+
+**Author, Developer, and Maintainer:**  
+Gang Tang  
+- gang.tang.au@gmail.com (primary)
+- gang.tang@student.unimelb.edu.au  
+- tgang@bgc-jena.mpg.de
+
+**Contributors:**
+- Zebedee Nicholls (zebedee.nicholls@climate-energy-college.org)
+- Alexander Norton (alex.norton@csiro.au)
+- Sönke Zaehle (szaehle@bgc-jena.mpg.de)
+- Malte Meinshausen (malte.meinshausen@unimelb.edu.au)
+
+## Citation
+If you use CNit in your research, please cite:
+
+- Tang, G., Nicholls, Z., Norton, A., Zaehle, S., and Meinshausen, M.: Synthesizing
+global carbon–nitrogen coupling effects – the MAGICC coupled carbon–nitrogen cycle
+model v1.0, Geosci. Model Dev., 18, 2193–2230,
+https://doi.org/10.5194/gmd-18-2193-2025, 2025.
+
+- Tang, G., Zaehle, S., Nicholls, Z., Norton, A., Ziehn, T., & Meinshausen, 
+M. Understanding the Drivers of Carbon-Nitrogen Cycle Variability in CMIP6 ESMs 
+with MAGICC CNit v2.0: Model and Calibration Updates. ESS Open Archive. 
+June 16, 2025. https://doi.org/10.22541/essoar.175008280.09297369/v1 
+[accepted by Journal of Advances in Modeling Earth Systems (JAMES)]
+
+## Related Projects
+
+MAGICC - Model for the Assessment of Greenhouse Gas Induced Climate Change,
+- https://magicc.org/
+- https://gitlab.com/magicc/magicc

cnit-2.1.0/README.md

@@ -0,0 +1,159 @@
+<p align="left">
+  <img src="docs/_static/CNit_logo.png" alt="CNit logo" width="100">
+</p>
+
+**CNit** (Carbon-Nitrogen Interactions in Terrestrial ecosystems) is a process-based 
+terrestrial biogeochemistry model that simulates coupled carbon and nitrogen cycles 
+in terrestrial ecosystems.  It is the land component of **MAGICC** (Model for the 
+Assessment of Greenhouse Gas Induced Climate Change). 
+
+## Features
+
+* Explicit carbon-nitrogen coupling with nitrogen limitation feedbacks
+* Four nitrogen pools (plant, litter, soil, mineral) and three carbon pools
+* Environmental modifiers: CO₂ fertilization, temperature, land use
+* Separation of deforestation and afforestation for CDR scenarios
+* Annual timestep with sub-annual process representation
+
+## Installation
+
+**For users:**
+
+```bash
+pip install cnit
+```
+
+**For developers:**
+
+To set up a development environment for this project, follow these steps:
+
+1. **Create a new conda environment** (replace `cnit` with your preferred name if desired):
+
+   ```bash
+   conda create --name cnit python=3.9
+   ```
+
+2. **Activate your environment**:
+
+   ```bash
+   conda activate cnit
+   ```
+
+3. **Install all dependencies and set up the package**:
+
+   ```bash
+   make env
+   ```
+
+This will install all required dependencies (including notebook, docs, and testing tools) and install the package in editable mode.
+
+> **Note:**  
+> The Makefile will check that you are not in the `base` environment and will refuse to run if you are.
+
+---
+
+**TL;DR:**
+```bash
+conda create --name cnit python=3.9
+conda activate cnit
+make env
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from cnit import CNitModel, CNitModelConfig, CNitExpConfig
+from cnit import Q # Local pint.quantity class for units handling
+
+# Create model with default parameters
+config = CNitModelConfig()
+model = CNitModel.from_config(config)
+
+# Set up time axis and forcing
+time_axis = Q(np.arange(1850, 2101), "yr")
+n_steps = len(time_axis)
+
+# Simple forcing (constant values for illustration)
+dT_s = Q(np.linspace(0, 2, n_steps), "K")  # 2°C warming
+CO2_s = Q(np.linspace(280, 560, n_steps), "ppm")  # CO2 doubling
+
+# Land use emissions (zero for simplicity)
+CemsLUnet_s = Q(np.zeros(n_steps), "GtC/yr")
+CemsLUgrs_s = Q(np.zeros(n_steps), "GtC/yr")
+
+# Nitrogen inputs
+NflxAD_s = Q(np.linspace(0.05, 0.15, n_steps), "GtN/yr")  # Increasing deposition
+NflxFT_s = Q(np.linspace(0, 0.1, n_steps), "GtN/yr")  # Increasing fertilizer
+
+# Nitrogen land use emissions
+NemsLUnet_s = Q(np.zeros(n_steps), "GtN/yr")
+NemsLUgrs_s = Q(np.zeros(n_steps), "GtN/yr")
+NemsLUmin_s = Q(np.zeros(n_steps), "GtN/yr")
+
+# Run the model
+res = model.run(
+    time_axis=time_axis,
+    dT_s=dT_s,
+    CO2_s=CO2_s,
+    CemsLUnet_s=CemsLUnet_s,
+    CemsLUgrs_s=CemsLUgrs_s,
+    NflxAD_s=NflxAD_s,
+    NflxFT_s=NflxFT_s,
+    NemsLUnet_s=NemsLUnet_s,
+    NemsLUgrs_s=NemsLUgrs_s,
+    NemsLUmin_s=NemsLUmin_s,
+)
+
+# Access results
+cveg, cveg_unit = res["CplsP"].data, res["CplsP"].units
+nveg, nveg_unit = res["NplsP"].data, res["NplsP"].units
+npp, npp_unit = res["CflxNPP"].data, res["CflxNPP"].units
+
+print(f"Final plant carbon: {cveg[-1]} {cveg_unit}")
+print(f"Final plant nitrogen: {nveg[-1]} {nveg_unit}")
+print(f"NPP change: {npp[0]} → {npp[-1]} {npp_unit}")
+```
+
+## Documentation
+The full documentation for CNit is available at 
+[https://cnit.readthedocs.io](https://cnit.readthedocs.io).
+
+## License
+BSD 3-Clause License. See LICENSE for details.
+
+Copyright (c) 2026, Gang Tang and contributors.
+
+## Authors and Contributors
+
+**Author, Developer, and Maintainer:**  
+Gang Tang  
+- gang.tang.au@gmail.com (primary)
+- gang.tang@student.unimelb.edu.au  
+- tgang@bgc-jena.mpg.de
+
+**Contributors:**
+- Zebedee Nicholls (zebedee.nicholls@climate-energy-college.org)
+- Alexander Norton (alex.norton@csiro.au)
+- Sönke Zaehle (szaehle@bgc-jena.mpg.de)
+- Malte Meinshausen (malte.meinshausen@unimelb.edu.au)
+
+## Citation
+If you use CNit in your research, please cite:
+
+- Tang, G., Nicholls, Z., Norton, A., Zaehle, S., and Meinshausen, M.: Synthesizing
+global carbon–nitrogen coupling effects – the MAGICC coupled carbon–nitrogen cycle
+model v1.0, Geosci. Model Dev., 18, 2193–2230,
+https://doi.org/10.5194/gmd-18-2193-2025, 2025.
+
+- Tang, G., Zaehle, S., Nicholls, Z., Norton, A., Ziehn, T., & Meinshausen, 
+M. Understanding the Drivers of Carbon-Nitrogen Cycle Variability in CMIP6 ESMs 
+with MAGICC CNit v2.0: Model and Calibration Updates. ESS Open Archive. 
+June 16, 2025. https://doi.org/10.22541/essoar.175008280.09297369/v1 
+[accepted by Journal of Advances in Modeling Earth Systems (JAMES)]
+
+## Related Projects
+
+MAGICC - Model for the Assessment of Greenhouse Gas Induced Climate Change,
+- https://magicc.org/
+- https://gitlab.com/magicc/magicc

cnit-2.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cnit"
+version = "2.1.0"
+description = "CNit: A Coupled Carbon-Nitrogen Cycle Model (Python)"
+keywords = ["cnit", "carbon cycle", "nitrogen cycle", "simple climate model", "magicc"]
+authors = [
+    {name="Gang Tang", email="gang.tang.au@gmail.com"},
+    {name="Zebedee Nicholls", email="zebedee.nicholls@climate-energy-college.org"},
+    {name="Alexander Norton", email="alex.norton@csiro.au"},
+    {name="Sönke Zaehle", email="szaehle@bgc-jena.mpg.de"},
+    {name="Malte Meinshausen", email="malte.meinshausen@unimelb.edu.au"},
+]
+maintainers = [
+    {name="Gang Tang", email="gang.tang.au@gmail.com"}
+]
+license = {text = "BSD-3-Clause"}
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering"
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "xarray ==2023.6.0",
+    "netCDF4",
+    "attrs",
+    "openscm-units >=0.5.0",
+    "pint >=0.19"
+]
+
+[project.optional-dependencies]
+notebook = [
+    "notebook >=6,<7",
+    "matplotlib",
+]
+docs = [
+    "sphinx >=1.4",
+    "sphinx-rtd-theme >=1.0",
+    "sphinx-autodoc-typehints >=1.22",
+    "sphinxcontrib-bibtex",
+]
+tests = [
+    "pytest",
+    "pytest-regressions[dataframe]"
+]
+
+[project.urls]
+Homepage = "https://github.com/gangtang-au/cnit"
+Documentation = "https://cnit.readthedocs.io"
+Repository = "https://github.com/gangtang-au/cnit"
+Changelog = "https://cnit.readthedocs.io/en/latest/changelog.html"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+license-files = []
+
+[tool.setuptools.packages.find]
+where = ["src"]

cnit-2.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cnit-2.1.0/src/cnit/__init__.py

@@ -0,0 +1,57 @@
+"""
+CNit - Carbon-Nitrogen Interactions in Terrestrial ecosystems.
+
+CNit is a process-based terrestrial biogeochemistry model that simulates
+coupled carbon and nitrogen cycles in terrestrial ecosystems.
+"""
+
+# Version
+try:
+    from importlib.metadata import version, PackageNotFoundError
+except ImportError:
+    from importlib_metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("cnit")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# Suppress expected warnings
+import warnings
+
+try:
+    from pint import UnitStrippedWarning
+    warnings.filterwarnings('ignore', category=UnitStrippedWarning)
+except ImportError:
+    pass
+
+# Core model classes
+from cnit.physics.carbon_nitrogen_cycle import (
+    CarbonNitrogenCycleModel,
+    CarbonNitrogenCycleModelConfig,
+    CarbonNitrogenCycleExperimentConfig,
+)
+
+# Convenient aliases
+CNitModel = CarbonNitrogenCycleModel
+CNitModelConfig = CarbonNitrogenCycleModelConfig
+CNitExpConfig = CarbonNitrogenCycleExperimentConfig
+
+# Utility imports
+from cnit.utils.units import Q
+
+# Define public API
+__all__ = [
+    # Version
+    "__version__",
+    # Main classes (full names)
+    "CarbonNitrogenCycleModel",
+    "CarbonNitrogenCycleModelConfig",
+    "CarbonNitrogenCycleExperimentConfig",
+    # Convenient aliases
+    "CNitModel",
+    "CNitModelConfig",
+    "CNitExpConfig",
+    # Utilities
+    "Q",
+]

cnit-2.1.0/src/cnit/configs/experiment_config.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass
+from typing import Optional, Dict
+import pint
+
+
+@dataclass(slots=True)
+class CarbonNitrogenCycleExperimentConfig:
+    """
+    Configuration for a Carbon-Nitrogen Cycle experiment.
+
+    Attributes:
+        name: Name of the experiment.
+        time_axis: Time axis for the experiment [years].
+        dT_s: Temperature anomaly time series [K].
+        CO2_s: Atmospheric CO2 concentration time series [ppm].
+        CemsLUnet_s: Net carbon emissions from land use [PgC/yr].
+        CemsLUgrs_s: Gross carbon emissions from land use [PgC/yr].
+        NflxAD_s: Nitrogen flux from atmospheric deposition [TgN/yr].
+        NflxFT_s: Nitrogen flux from fertilizer [TgN/yr].
+        NemsLUnet_s: Net nitrogen emissions from land use [TgN/yr].
+        NemsLUgrs_s: Gross nitrogen emissions from land use [TgN/yr].
+        NemsLUmin_s: Nitrogen emissions from mineralization [TgN/yr].
+        metadata: Optional dictionary for additional metadata.
+    """
+    name: str
+    switch_N: pint.Quantity
+    time_axis: pint.Quantity
+    dT_s: pint.Quantity
+    CO2_s: pint.Quantity
+    CemsLUnet_s: pint.Quantity
+    CemsLUgrs_s: pint.Quantity
+    NflxAD_s: pint.Quantity
+    NflxFT_s: pint.Quantity
+    NemsLUnet_s: pint.Quantity
+    NemsLUgrs_s: pint.Quantity
+    NemsLUmin_s: pint.Quantity
+    metadata: Optional[Dict[str, object]] = None
+
+    def to_input_dict(self):
+        return dict(
+            time_axis=self.time_axis,
+            dT_s=self.dT_s,
+            CO2_s=self.CO2_s,
+            CemsLUnet_s=self.CemsLUnet_s,
+            CemsLUgrs_s=self.CemsLUgrs_s,
+            NflxAD_s=self.NflxAD_s,
+            NflxFT_s=self.NflxFT_s,
+            NemsLUnet_s=self.NemsLUnet_s,
+            NemsLUgrs_s=self.NemsLUgrs_s,
+            NemsLUmin_s=self.NemsLUmin_s,
+        )