Cycles-utils 4.0.4__tar.gz → 4.0.6__tar.gz

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/Cycles_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.4
+Version: 4.0.6
 Summary: Python scripts to build Cycles input files and post-process Cycles output files
 Home-page: https://github.com/PSUmodeling/Cycles-utils
 Author: Yuning Shi
@@ -21,6 +21,7 @@ Requires-Dist: rasterio>=1.2.3; extra == "soilgrids"
 Requires-Dist: shapely>=1.7.1; extra == "soilgrids"
 Provides-Extra: gssurgo
 Requires-Dist: shapely>=1.7.1; extra == "gssurgo"
+Requires-Dist: fiona>=1.8.20; extra == "gssurgo"
 Provides-Extra: weather
 Requires-Dist: netCDF4>=1.5.7; extra == "weather"
 Requires-Dist: tqdm>=4.60.0; extra == "weather"
@@ -60,5 +61,6 @@ pip install Cycles-utils
 
 | Cycles-utils version | Cycles version |
 | -------------------- | -------------- |
+| 4.0.6                | 1.5.20         |
+| 4.0.5                | 1.5.20         |
 | 4.0.4                | 1.5.20         |
-

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/Cycles_utils.egg-info/SOURCES.txt

@@ -25,6 +25,11 @@ cycles/data/GLDASp5_elevation_025d.nc4
 cycles/data/GLDASp5_landmask_025d.nc4
 cycles/data/NLDAS_elevation.nc4
 cycles/data/NLDAS_masks-veg-soil.nc4
+cycles/data/cb_2018_us_state_20m.cpg
+cycles/data/cb_2018_us_state_20m.dbf
+cycles/data/cb_2018_us_state_20m.prj
+cycles/data/cb_2018_us_state_20m.shp
+cycles/data/cb_2018_us_state_20m.shx
 cycles/data/fips_gid_conversion.csv
 cycles/data/gridMET_elevation_mask.nc
 cycles/data/metdata_elevationdata.nc

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/Cycles_utils.egg-info/requires.txt

@@ -6,6 +6,7 @@ matplotlib>=3.4.2
 
 [gssurgo]
 shapely>=1.7.1
+fiona>=1.8.20
 
 [soilgrids]
 rioxarray>=0.5.0

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Cycles-utils
-Version: 4.0.4
+Version: 4.0.6
 Summary: Python scripts to build Cycles input files and post-process Cycles output files
 Home-page: https://github.com/PSUmodeling/Cycles-utils
 Author: Yuning Shi
@@ -21,6 +21,7 @@ Requires-Dist: rasterio>=1.2.3; extra == "soilgrids"
 Requires-Dist: shapely>=1.7.1; extra == "soilgrids"
 Provides-Extra: gssurgo
 Requires-Dist: shapely>=1.7.1; extra == "gssurgo"
+Requires-Dist: fiona>=1.8.20; extra == "gssurgo"
 Provides-Extra: weather
 Requires-Dist: netCDF4>=1.5.7; extra == "weather"
 Requires-Dist: tqdm>=4.60.0; extra == "weather"
@@ -60,5 +61,6 @@ pip install Cycles-utils
 
 | Cycles-utils version | Cycles version |
 | -------------------- | -------------- |
+| 4.0.6                | 1.5.20         |
+| 4.0.5                | 1.5.20         |
 | 4.0.4                | 1.5.20         |
-

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/README.md

@@ -22,5 +22,6 @@ pip install Cycles-utils
 
 | Cycles-utils version | Cycles version |
 | -------------------- | -------------- |
+| 4.0.6                | 1.5.20         |
+| 4.0.5                | 1.5.20         |
 | 4.0.4                | 1.5.20         |
-

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/cycles/__init__.py

@@ -8,6 +8,7 @@ from .cycles_tools import read_soil_file
 from .cycles_tools import read_weather_file
 from .cycles_tools import read_output
 from .cycles_tools import read_operation_file
+from .cycles_tools import generate_operation_file
 from .cycles_tools import SoilLayer
 from .cycles_tools import plot_yield
 from .cycles_tools import plot_operations

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/cycles/cycles.py

@@ -29,6 +29,11 @@ class Cycles:
     Provides methods to run simulations, read outputs, and inspect soil/weather/operation configurations. Automatically
     loads the control file upon initialization.
 
+    Args:
+        path: Path to the simulation directory (containing input/ and output/ subdirs).
+        simulation: Name of the simulation (base name of control file without extension).
+        executable: Optional absolute path to the Cycles executable binary. This is required to run simulations using the `run` method.
+
     Attributes:
         path: Path to the simulation directory (containing input/ and output/ subdirs).
         simulation: Name of the simulation (base name of control file without extension).
@@ -44,14 +49,14 @@ class Cycles:
 
     path: Path | str
     simulation: str
-    output: dict[str, Output] = field(default_factory=dict[str, Output])
-    control: ControlConfig | None = None
-    operations: list | None = None
-    soil_profile: list[SoilLayer] | None = None
-    curve_number: int | None = None
-    slope: float | None = None
-    weather: pd.DataFrame | None = None
     executable: Path | str | None = None
+    output: dict[str, Output] = field(init=False, default_factory=dict[str, Output])
+    control: ControlConfig | None = field(init=False, default=None)
+    operations: list | None = field(init=False, default=None)
+    soil_profile: list[SoilLayer] | None = field(init=False, default=None)
+    curve_number: int | None = field(init=False, default=None)
+    slope: float | None = field(init=False, default=None)
+    weather: pd.DataFrame | None = field(init=False, default=None)
 
 
     def __post_init__(self):
@@ -65,6 +70,10 @@ class Cycles:
     def run(self, options: str, silence: bool=False) -> tuple[int, str]:
         """Run the Cycles executable for this simulation.
 
+        To use the `run` method, the `executable` attribute must be set to the path of the Cycles executable. The
+        `options` string is passed directly to the command line when invoking Cycles, allowing you to specify any
+        command-line options supported by Cycles (e.g., `-s` for spin-up, etc.).
+
         Args:
             options: Command-line options passed to Cycles.
             silence: If True, suppress stdout and stderr printing.
@@ -89,6 +98,9 @@ class Cycles:
     def read_output(self, output_types: Collection) -> None:
         """Read one or more output tables into memory.
 
+        When reading multiple output tables, the `output_types` argument can be a list or tuple of table names. Each
+        table is read into a pandas DataFrame and stored in the `output` dictionary with its corresponding units.
+
         Args:
             output_types: Output table name or collection of names.
         """
@@ -130,32 +142,40 @@ class Cycles:
         self.weather = _read_weather_file(self.path / 'input' / self.control.input_files.weather_file, start_year=start_year, end_year=end_year, subdaily=subdaily)
 
 
-    def generate_reinit_file(self, doy: int, *, reinit: str | None=None) -> None:
+    def generate_reinit_file(self, doy: int, *, reinit_name: str | None=None) -> None:
         """Generate a reinitialization file from model output.
 
         Args:
             doy: Day-of-year to extract from reinit output.
-            reinit: Optional output stem for the reinit file.
+            reinit_name: Optional output stem for the reinit file.
         """
         assert isinstance(self.path, Path)
-        _generate_reinit_file(self.path / 'input' / f'{self.simulation if reinit is None else reinit}.reinit', self.path / 'output' / self.simulation, doy)
+        _generate_reinit_file(self.path / 'input' / f'{self.simulation if reinit_name is None else reinit_name}.reinit', self.path / 'output' / self.simulation, doy)
 
 
-    def plot_yield(self, *, ax: Axes | None=None, fontsize: int | None=None) -> Axes:
-        """Plot grain and forage yields from harvest output."""
+    def plot_yield(self, *, ax: Axes | None=None, crop_colors: dict | None=None, fontsize: int | None=None) -> Axes:
+        """Plot grain and forage yields from harvest output.
+
+        Args:
+            ax: Optional axes to draw on.
+            crop_colors: Optional mapping from crop names to plot colors.
+            fontsize: Optional global font size override.
+
+        Returns:
+            Axes containing the yield plot.
+        """
         if 'harvest' not in self.output:
             self.read_output('harvest')
 
-        return _plot_yield(self.output['harvest'].data, ax=ax, fontsize=fontsize)
+        return _plot_yield(self.output['harvest'].data, ax=ax, crop_colors=crop_colors, fontsize=fontsize)
 
 
     def plot_operations(self, *, axs: Axes | np.ndarray | None=None, fontsize: int | None=None):
         """Plot operation timelines grouped by rotation year.
 
         Args:
-            rotation_size: Number of years in the plotted rotation.
             axs: Optional axes object(s) to draw on.
-            fontsize: Global matplotlib font size override.
+            fontsize: Optional global matplotlib font size override.
 
         Returns:
             The axes used for plotting.

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/cycles/cycles_runner.py

@@ -16,6 +16,18 @@ INPUT_DIR: Path = Path('input')
 OUTPUT_DIR: Path = Path('output')
 SUMMARY_DIR: Path = Path('summary')
 
+OUTPUT_CONTROL_FLAGS: dict = {
+    'dailyEnviron': 'daily_weather_out',
+    'dailyResidue': 'daily_residue_out',
+    'dailyWater': 'daily_water_out',
+    'dailyN': 'daily_nitrogen_out',
+    'dailySoilC': 'daily_soil_carbon_out',
+    'dailySoilLayersCN': 'daily_soil_lyr_cn_out',
+    'annualSOM': 'annual_soil_out',
+    'annualSoilProfileC': 'annual_profile_out',
+    'annualN': 'annual_nflux_out',
+}
+
 @dataclass
 class SimulationContext:
     name: str
@@ -32,36 +44,131 @@ class CyclesRunner:
     Manages batch execution of Cycles simulations by generating control files, operation files, and nudge files from
     templates and parameter dictionaries.  Consolidates results into a summary CSV file.
 
-    Attributes:
+    Args:
         executable: Absolute path to the Cycles executable binary.
-        rotation_builder: If True, disables spin-up option and enables rotation features.
     """
 
     executable: str
-    rotation_builder: bool = False
 
     def __post_init__(self):
         self.executable = str(Path(self.executable).resolve())
 
 
     def run(self, simulations: SimulationConfig, control_dict: dict[str, Any], *,
-        summary: str='summary.csv', operation_template: Path | str | None=None, operation_dict: dict[str, Any] | None=None, calibration_dict: dict[str, Any] | None=None,
+        summary: str | dict[str, str] | None=None,
+        operation_template: Path | str | None=None, operation_dict: dict[str, Any] | None=None,
+        calibration_dict: dict[str, Any] | None=None,
         options: str='', rm_input: bool=False, rm_output: bool=False, rm_steady_state_soil: bool=True, silence: bool=True, user_comment: str='') -> None:
         """Execute a batch of simulations and write a consolidated summary.
 
         Args:
-            simulations: Simulation rows as list of dicts or a DataFrame.
-            control_dict: Control-file values or callables evaluated per row.
-            summary: Summary CSV name written under summary directory.
+            simulations: Simulation configurations as list of dicts or a DataFrame. Each dict or DataFrame row should be
+                corresponding to a single simulation and contain values to support the control, operation, and
+                calibration dictionaries.
+            control_dict: Control-file values or callables evaluated per simulation.
+            summary: Summary CSV name for the summary harvest file written under summary directory. If a dictionary is provided, the keys are output file types and the values are
+                summary CSV names. If None, only the harvest summary is written into `summary/summary.csv`.
             operation_template: Template file for generated operation files.
             operation_dict: Substitutions used with operation template.
-            calibration_dict: Nudge-file values or callables per row.
+            calibration_dict: Nudge-file values or callables per simulation.
             options: Cycles command options.
             rm_input: Remove generated input files after each run.
             rm_output: Remove run output directory after each run.
             rm_steady_state_soil: Remove generated steady-state soil file.
             silence: If True, suppress simulation screen output.
             user_comment: Optional text prefixed to summary header comments.
+
+        The following fields are required in `control_dict`:
+
+        - `simulation_name`
+        - `simulation_start_year`
+        - `simulation_end_year`
+        - `rotation_size`
+        - `operation_file`
+        - `soil_file`
+        - `weather_file`
+
+        The default values for other fields are:
+
+        - `crop_file`: `GenericCrops.crop`
+        - `reinit_file`: `N/A`
+        - `soil_layers`: inferred from the soil file (if not provided)
+        - `co2_level`: `-999`
+        - `use_reinitialization`: `0`
+        - `adjusted_yields`: `0`
+        - `hydrology_option`: `1`
+        - `automatic_nitrogen`: `0`
+        - `automatic_phosphorus`: `0`
+        - `automatic_sulfur`: `0`
+
+        All output control fields default to `0`.
+
+        Note that `simulation_name` is used to generate the control file name for each simulation. The `simulation_name`
+        should be unique for each simulation in the batch.
+
+        #### Example:
+
+        To run a batch simulation of continuous corn in different counties of Iowa, you can use the following code snippet:
+        ```python
+        from cycles import CyclesRunner
+
+        runner = CyclesRunner(executable='/path/to/Cycles')
+
+        simulations: list[dict] = [
+            'GID': 'USA.16.1_1', 'weather': 'NLDAS_41.438Nx94.562W', 'soil': 'maize_rainfed_SoilGrids_USA.16.1_1.soil', 'plant_start': 112, 'plant_end': 154, 'maturity_group': 100,
+            'GID': 'USA.16.2_1', 'weather': 'NLDAS_40.938Nx94.688W', 'soil': 'maize_rainfed_SoilGrids_USA.16.2_1.soil', 'plant_start': 112, 'plant_end': 154, 'maturity_group': 100,
+            'GID': 'USA.16.3_1', 'weather': 'NLDAS_43.188Nx91.562W', 'soil': 'maize_rainfed_SoilGrids_USA.16.3_1.soil', 'plant_start': 112, 'plant_end': 154, 'maturity_group': 90,
+        ]
+        ```
+
+        The control dictionary should work with the simulation configurations to generate the appropriate control files for each simulation:
+
+        ```python
+        control_dict: dict = {
+            'simulation_name': lambda x: x['GID'],
+            'simulation_start_year': 1981,
+            'simulation_end_year': 2016,
+            'rotation_size': 1,
+            'crop_file': 'GenericCrops.crop',
+            'operation_file': lambda x: f'{x["GID"]}.operation',
+            'soil_file': lambda x: f'path/to/{x["soil"]}',
+            'weather_file': lambda x: f'path/to/{x["gridMET_weather"]}.weather',
+        }
+        ```
+
+        The operation dictionary should work with a template operation file to generate the appropriate operation files for each simulation. In the template operation file, use
+        placeholders for planting `DOY`, `END_DOY`, and `CROP` like below:
+
+        ```
+        DOY         $PD1
+        END_DOY     $PD2
+        CROP        $CROP
+        ```
+
+        Then define the operation dictionary to substitute the placeholders with values from the simulation configurations:
+
+        ```python
+        operation_dict: dict = {
+            'PD1': lambda x: x['plant_start'],
+            'PD2': lambda x: x['plant_end'],
+            'CROP': lambda x: f'CornRM.{x["relative_maturity_group"]}',
+        }
+        ```
+
+        Finally, run the simulations with the following code snippet:
+
+        ```python
+        cycles_runner.run(
+            simulations=simulations,
+            control_dict=control_dict,
+            operation_template='path/to/template.operation',
+            operation_dict=operation_dict,
+            summary='summary.csv',
+            options='-s',
+        )
+        ```
+
+        The `-s` option enables spin-up for the simulations. The results will be consolidated into `summary/summary.csv`.
         """
         if isinstance(simulations, pd.DataFrame):
             simulations = simulations.to_dict(orient='records')
@@ -74,13 +181,22 @@ class CyclesRunner:
                 f"operation_dict={'None' if operation_dict is None else '...'}"
             )
 
-        if 's' in options and self.rotation_builder:
-            raise ValueError('Spin-up cannot be used with rotation builder.')
-
         operation_template = Path(operation_template) if operation_template is not None else None
+        if user_comment:
+            user_comment = f'# {user_comment.lstrip("# ").rstrip()}\n'
         comment = user_comment + _generate_comment(self.executable, options)
         first_run = True
 
+        if summary is None:
+            summary = {'harvest': 'summary.csv'}
+        elif isinstance(summary, str):
+            summary = {'harvest': summary}
+        assert isinstance(summary, dict)
+
+        for key in summary.keys():
+            if key == 'harvest': continue
+            control_dict[OUTPUT_CONTROL_FLAGS[key]] = 1
+
         SUMMARY_DIR.mkdir(exist_ok=True)
 
         for s in simulations:
@@ -104,7 +220,9 @@ class CyclesRunner:
                 self._remove_inputs(cxt)
             if rm_output:
                 shutil.rmtree(OUTPUT_DIR / cxt.name, ignore_errors=True)
-            if rm_steady_state_soil:
+            if rm_steady_state_soil and 's' in options:
+                # Steady-state soil should only be removed if generated during this run (i.e., spin-up was requested).
+                # If using an existing steady-state soil file, it should not be removed.
                 (INPUT_DIR / f'{cxt.name}_ss.soil').unlink(missing_ok=True)
 
 
@@ -135,15 +253,16 @@ class CyclesRunner:
             cxt.operation_fn.unlink(missing_ok=True)
 
 
-    def _write_summary(self, cycles: Cycles, summary: str, *, header: bool, comment: str) -> None:
-        cycles.read_output('harvest')
-        cycles.output['harvest'].data.insert(0, 'simulation', cycles.simulation)
+    def _write_summary(self, cycles: Cycles, summary: dict, *, header: bool, comment: str) -> None:
+        cycles.read_output(summary.keys())
+        for key, fn in summary.items():
+            cycles.output[key].data.insert(0, 'simulation', cycles.simulation)
 
-        mode = 'w' if header else 'a'
-        with open(SUMMARY_DIR / summary, mode) as f:
-            if header:
-                f.write(comment)
-            cycles.output['harvest'].data.to_csv(f, header=header, index=False)
+            mode = 'w' if header else 'a'
+            with open(SUMMARY_DIR / fn, mode) as f:
+                if header:
+                    f.write(comment)
+                cycles.output[key].data.to_csv(f, header=header, index=False)
 
 
 def _render_template(template_fn: Path, dest_fn: Path, substitutions: dict) -> None:

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/cycles/cycles_tools/__init__.py

@@ -3,6 +3,8 @@ from .control_file import read_control_file
 from .control_file import ControlConfig
 from .nudge_file import generate_nudge_file
 from .operation_file import read_operation_file
+from .operation_file import format_operation
+from .operation_file import generate_operation_file
 from .operation_file import Operation, Planting, Tillage, Harvest, Kill, FixedFertilization, FixedIrrigation, AutoIrrigation
 from .output_file import read_output
 from .soil_file import MAPPABLE_PARAMETERS
@@ -16,12 +18,14 @@ from .plot_tools import plot_operations
 from .plot_tools import plot_map
 from .plot_tools import plot_satellite_map
 from ._base_file import resolve_dict_values
+from ._base_file import read_geospatial_file
 
 __all__ = [
     "generate_control_file",
     "read_control_file",
     "generate_nudge_file",
     "read_operation_file",
+    "generate_operation_file",
     "read_output",
     "generate_soil_file",
     "read_soil_file",

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/cycles/cycles_tools/_base_file.py

@@ -1,4 +1,7 @@
 from __future__ import annotations
+import fiona
+import geopandas as gpd
+import pandas as pd
 import types
 from dataclasses import fields
 from pathlib import Path
@@ -7,7 +10,11 @@ from typing import Union, Any
 def _format_block(label: str, block) -> str:
     lines = [f'## {label.replace("_", " ").upper()} ##']
     for f in fields(block):
-        lines.append('%-27s\t%s' % (f.name.upper(), getattr(block, f.name)))
+        val = getattr(block, f.name)
+        if isinstance(val, float) and val == -999.0:
+            val = '-999'
+        description = f.metadata.get('description', '')
+        lines.append(f'{f.name.upper():<28}{val:<8}# {description}' if description else f'{f.name.upper():<28}{val}')
     lines.append('')
 
     return '\n'.join(lines)
@@ -45,3 +52,24 @@ def unwrap_optional(t) -> type:
     if origin is Union or origin is types.UnionType or isinstance(t, types.UnionType):
         return next(arg for arg in t.__args__ if arg is not type(None))
     return t
+
+
+def read_geospatial_file(file_path: str | Path) -> gpd.GeoDataFrame:
+    file_path = Path(file_path)
+    ext = file_path.suffix.lstrip('.').lower()
+    match ext:
+        case 'shp':
+            return gpd.read_file(file_path)
+        case 'kml':
+            return _read_kml(file_path)
+        case _:
+            raise ValueError(f"Unsupported boundary format: '.{ext}'")
+
+
+def _read_kml(file_path: Path) -> gpd.GeoDataFrame:
+    return gpd.GeoDataFrame(
+        pd.concat(
+            [gpd.read_file(file_path, driver='KML', layer=layer) for layer in fiona.listlayers(file_path)],
+            ignore_index=True,
+        )
+    )

{cycles_utils-4.0.4 → cycles_utils-4.0.6}/cycles/cycles_tools/control_file.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 import warnings
-from dataclasses import dataclass, fields
+from dataclasses import dataclass, field, fields
 from pathlib import Path
 from typing import Any, get_type_hints
 from ._base_file import write_file, resolve_dict_values, extract, parse_value, unwrap_optional
@@ -22,10 +22,10 @@ class InputFiles:
 @dataclass(kw_only=True)
 class SimulationOptions:
     soil_layers: int
-    co2_level: float = -999
+    co2_level: float = field(default=-999, metadata={'description': 'atmospheric CO2 concentration (ppm). Use co2.txt file if set to -999'})
     use_reinitialization: int = 0
     adjusted_yields: int = 0
-    hydrology_option: int = 1
+    hydrology_option: int = field(default=1, metadata={'description': "1: gravity driven, 2: Richards' equation with Crank-Nicholson, 3: Richards' equation with CVode"})
     automatic_nitrogen: int = 0
     automatic_phosphorus: int = 0
     automatic_sulfur: int = 0
@@ -65,23 +65,23 @@ def _build_control_config(control_dict: dict, simulation_dict: dict[str, Any] |
     )
 
 
-def _get_soil_layers(fn: Path) -> int:
+def _get_soil_layers(file_path: Path) -> int:
     NUM_HEADER_LINES = 2
     try:
-        lines = [line for line in fn.read_text().splitlines() if line.strip() and not line.strip().startswith('#')]
+        lines = [line for line in file_path.read_text().splitlines() if line.strip() and not line.strip().startswith('#')]
         return len(lines) - NUM_HEADER_LINES - 1
     except FileNotFoundError:
-        warnings.warn(f"Soil file not found: {fn}")
+        warnings.warn(f"Soil file not found: {file_path}")
         return -999
 
 
-def generate_control_file(fn: str | Path, user_dict: dict, *, simulation_dict: dict[str, Any] | None=None) -> ControlConfig:
+def generate_control_file(file_path: str | Path, user_dict: dict[str, Any], *, simulation_dict: dict[str, Any] | None=None) -> ControlConfig:
     """Generate and write a Cycles control file.
 
-    Provide either direct values or callables that accept a simulation row and return a value in `user_dict`. The
-    parameter names should be in lowercase and correspond to the fields in Cycles simulation control files. If a field
-    is not provided, it will be filled with a default value. If a field's value is a callable, it will be called with
-    the `simulation_dict` to resolve its value.
+    Provide either direct values or callables that accept a simulation configuration and return a value in `user_dict`.
+    The parameter names should be in lowercase and correspond to the fields in Cycles simulation control files. If a
+    field is not provided, it will be filled with a default value. If a field's value is a callable, it will be called
+    with the `simulation_dict` to resolve its value.
 
     The following fields are required in `user_dict`:
 
@@ -108,30 +108,30 @@ def generate_control_file(fn: str | Path, user_dict: dict, *, simulation_dict: d
     All output control fields default to `0`.
 
     Args:
-        fn: Destination control file path.
+        file_path: Destination control file path.
         user_dict: Values or callables for control fields.
         simulation_dict: Optional simulation row for callable resolution.
 
     Returns:
         The generated control configuration.
     """
-    fn = Path(fn)
-    config = _build_control_config(user_dict, simulation_dict, fn.parent)
-    write_file(fn, config)
+    file_path = Path(file_path)
+    config = _build_control_config(user_dict, simulation_dict, file_path.parent)
+    write_file(file_path, config)
 
     return config
 
 
-def read_control_file(control: str | Path) -> ControlConfig:
-    """Parse a Cycles control file into a ControlConfig instance.
+def read_control_file(file_path: str | Path) -> ControlConfig:
+    """Parse a Cycles control file into a `ControlConfig` dataclass instance.
 
     Args:
-        control: Path to a Cycles control file path.
+        file_path: Path to a Cycles control file path.
 
     Returns:
         Control configuration.
     """
-    with open(Path(control)) as f:
+    with open(Path(file_path)) as f:
         lines = f.read().splitlines()
     lines = iter([line for line in lines if (not line.strip().startswith('#')) and line.strip()])
 

cycles_utils-4.0.6/cycles/cycles_tools/nudge_file.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from ._base_file import write_file, resolve_dict_values, extract
+
+@dataclass(kw_only=True)
+class CalibrationMultipliers:
+    soc_decomp_rate: float = field(default=1.0, metadata={'description': 'soil organic carbon decomposition rate'})
+    residue_decomp_rate: float = field(default=1.0, metadata={'description': 'residue decomposition rate'})
+    root_decomp_rate: float = field(default=1.0, metadata={'description': 'root decomposition rate'})
+    rhizo_decomp_rate: float = field(default=1.0, metadata={'description': 'rhizodeposit decomposition rate'})
+    manure_decomp_rate: float = field(default=1.0, metadata={'description': 'manure decomposition rate'})
+    ferment_decomp_rate: float = field(default=1.0, metadata={'description': 'ferment decomposition rate'})
+    microb_decomp_rate: float = field(default=1.0, metadata={'description': 'microbe decomposition rate'})
+    soc_humif_power: float = field(default=1.0, metadata={'description': 'soil organic carbon humification exponent'})
+    nitrif_rate: float = field(default=1.0, metadata={'description': 'nitrification rate'})
+    pot_denitrif_rate: float = field(default=1.0, metadata={'description': 'potential denitrification rate'})
+    denitrif_half_rate: float = field(default=1.0, metadata={'description': 'half saturation constant for denitrification'})
+    decomp_half_resp: float = field(default=1.0, metadata={'description': 'decomposition half response to saturation (default 0.22)'})
+    decomp_resp_power: float = field(default=1.0, metadata={'description': 'decomposition exponential response to saturation (default 3.0)'})
+    root_progression: float = field(default=1.0, metadata={'description': 'rooting depth progression rate'})
+    radiation_use_efficiency: float = field(default=1.0, metadata={'description': 'crop radiation use efficiency'})
+
+@dataclass(kw_only=True)
+class ParameterValues:
+    kd_no3: float = field(default=0.0, metadata={'description': 'adsorption coefficient for NO3 (default 0.0 cm3/g)'})
+    kd_nh4: float = field(default=5.6, metadata={'description': 'adsorption coefficient for NH4 (default 5.6 cm3/g)'})
+
+@dataclass
+class NudgeConfig:
+    calibration_multipliers: CalibrationMultipliers
+    parameter_values: ParameterValues
+
+
+def _build_nudge_config(user_dict: dict[str, Any], calibration_dict: dict[str, Any] | None) -> NudgeConfig:
+    resolved = resolve_dict_values(user_dict, calibration_dict)
+
+    return NudgeConfig(
+        calibration_multipliers=CalibrationMultipliers(**extract(CalibrationMultipliers, resolved)),
+        parameter_values=ParameterValues(**extract(ParameterValues, resolved)),
+    )
+
+
+def generate_nudge_file(file_path: str | Path, user_dict: dict[str, Any], *, calibration_dict: dict[str, Any] | None=None) -> None:
+    """Write a Cycles nudge file from user-provided values.
+
+    Provide either direct values or callables that accept a calibration configuration and return a value in `user_dict`.
+    The parameter names should be in lowercase and correspond to the fields in Cycles nudge (calibration) files. If a
+    field is not provided, it will be filled with a default value. If a field's value is a callable, it will be called
+    with the `calibration_dict` to resolve its value.
+
+    The default values for all calibration multipliers are `1.0`, and the default values for `kd_no3` and `kd_nh4` are
+    `0.0` and `5.6`, respectively.
+
+    Args:
+        file_path: Destination nudge file path.
+        user_dict: Values or callables for nudge parameters.
+        calibration_dict: Optional simulation row for callable resolution.
+    """
+    file_path = Path(file_path)
+    config = _build_nudge_config(user_dict, calibration_dict)
+    write_file(file_path, config)