Cycles I/O and plotting tools

generate_control_file(fn, user_dict, *, simulation_dict=None)

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.

The following fields are required in user_dict:

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

Parameters:
  • fn (str | Path) –

    Destination control file path.

  • user_dict (dict) –

    Values or callables for control fields.

  • simulation_dict (dict[str, Any] | None, default: None ) –

    Optional simulation row for callable resolution.
Returns:
  • ControlConfig –

    The generated control configuration.

read_control_file(control)

Parse a Cycles control file into a ControlConfig instance.

Parameters:
  • control (str | Path) –

    Path to a Cycles control file path.
Returns:
  • ControlConfig –

    Control configuration.

generate_nudge_file(fn, user_dict, *, simulation_dict=None)

Write a Cycles nudge file from user-provided values.

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

Parameters:
  • fn (str | Path) –

    Destination nudge file path.

  • user_dict (dict) –

    Values or callables for nudge parameters.

  • simulation_dict (dict[str, Any] | None, default: None ) –

    Optional simulation row for callable resolution.

read_operation_file(operation)

Parse a Cycles operation file into operation objects.

Parameters:
  • operation (str | Path) –

    Path to a Cycles operation file.
Returns:
  • list –

    A list of operation dataclass instances.

generate_operation_file(path, operations, *, desc='')

Write a Cycles operation file from structured operation records.

The optional description is written as the first line when provided. Each operation is serialized with to preserves Cycles field naming and relative day-of-year formatting.

Parameters:
  • path (Path) –

    Destination operation file path.

  • operations (list[Operation]) –

    Ordered operation records to serialize.

  • desc (str, default: '' ) –

    Optional header or description line to place at the top of the file.

read_output(path, output_type)

Read one Cycles output file and associated unit strings.

Parameters:
  • path (str | Path) –

    Directory containing output CSV files.

  • output_type (str) –

    Output file type, such as harvest.
Returns:
  • tuple[DataFrame, dict[str, str]] –

    Parsed DataFrame and a column-to-unit mapping.

generate_soil_file(fn, profile, *, target=DEFAULT_PROFILE, parameters=MAPPABLE_PARAMETERS, soil_depth=None, desc='', slope=None, curve_number=None, hsg='')

Generate a Cycles-formatted soil file from a list of soil layers.

The input profile is first mapped to the target layering scheme, then rendered to Cycles soil-file format and written to fn.

Parameters:
  • fn (str | Path) –

    Output soil file path.

  • profile (list[SoilLayer]) –

    Soil profile layers in depth order.

  • target (list[SoilLayer], default: DEFAULT_PROFILE ) –

    Target layer structure to map onto.

  • parameters (list[str], default: MAPPABLE_PARAMETERS ) –

    Soil parameters to map from measured profile.

  • soil_depth (float | None, default: None ) –

    Optional maximum depth (m) to include in mapping.

  • desc (str, default: '' ) –

    Optional description/comment line written at file top.

  • slope (float | None, default: None ) –

    Optional slope value written to the header.

  • curve_number (float | None, default: None ) –

    Optional explicit curve number value.

  • hsg (str, default: '' ) –

    Optional hydrologic soil group used to infer curve number.
Returns:
  • list[SoilLayer] –

    The mapped soil layers written to the output file.
Raises:
  • ValueError –

    If both curve_number and hsg are provided.

read_soil_file(fn)

Read a Cycles soil file into structured objects.

Parameters:
  • fn (str | Path) –

    Soil file path to read.
Returns:
  • tuple[list[SoilLayer], dict] –

    A tuple containing: - List of parsed SoilLayer objects. - Header metadata dictionary with keys such as curve_number and slope.

read_weather_file(fn, *, start_year=-9999, end_year=9999, subdaily=False)

Read weather file records and filter by year range.

Parameters:
  • fn (str | Path) –

    Weather file path.

  • start_year (int, default: -9999 ) –

    Inclusive first year to keep.

  • end_year (int, default: 9999 ) –

    Inclusive last year to keep.

  • subdaily (bool, default: False ) –

    If True, parse hourly weather schema.
Returns:
  • DataFrame –

    Weather data indexed by datetime.

generate_reinit_file(out_path, in_path, doy)

Write a re-initialization file from Cycles output for all years at a selected day-of-year.

Parameters:
  • out_path (str | Path) –

    Destination re-initialization file path.

  • in_path (str | Path) –

    Simulation output directory that contains Cycles output files.

  • doy (int) –

    Day-of-year extracted from re-initialization.

plot_yield(harvest_df, *, ax=None, fontsize=None)

Plot grain and forage yields by crop.

Parameters:
  • harvest_df (DataFrame) –

    Harvest output DataFrame.

  • ax (Axes | None, default: None ) –

    Optional axes to draw on.

  • fontsize (int | None, default: None ) –

    Optional global font size override.
Returns:
  • Axes –

    Axes containing the yield plot.

plot_operations(operations, rotation_size, *, axs=None, fontsize=None)

Plot operations by day-of-year for each rotation year.

Parameters:
  • operations (list) –

    Sequence of parsed operation objects.

  • rotation_size (int) –

    Number of years in the rotation.

  • axs (Axes | ndarray | None, default: None ) –

    Optional axes object(s) for rendering.

  • fontsize (int | None, default: None ) –

    Optional global font size override.
Returns:
  • ndarray –

    Axes array used to render timelines.

plot_map(gdf, column, *, projection=ccrs.PlateCarree(), ax=None, cmap='viridis', vmin=None, vmax=None, colorbar=True, cb_axes=None, extend='neither', cb_orientation='horizontal', label=None, title=None, fontsize=None, frameon=False)

Render a thematic map from a GeoDataFrame column.

Parameters:
  • gdf (GeoDataFrame) –

    GeoDataFrame to visualize.

  • column (str) –

    Column name to visualize.

  • projection (Projection, default: PlateCarree() ) –

    Map projection for output axes.

  • ax (Sequence[float] | GeoAxes | None, default: None ) –

    Existing GeoAxes or add_axes rectangle.

  • cmap (Colormap | str, default: 'viridis' ) –

    Matplotlib colormap.

  • vmin (float | None, default: None ) –

    Optional lower bound for colormap normalization.

  • vmax (float | None, default: None ) –

    Optional upper bound for colormap normalization.

  • colorbar (bool, default: True ) –

    Whether to draw a colorbar.

  • cb_axes (tuple[float, float, float, float] | None, default: None ) –

    Optional colorbar axes rectangle.

  • extend (str, default: 'neither' ) –

    Colorbar extension mode.

  • cb_orientation (str, default: 'horizontal' ) –

    Colorbar orientation.

  • label (str | None, default: None ) –

    Optional colorbar label.

  • title (str | None, default: None ) –

    Optional plot title.

  • fontsize (float | None, default: None ) –

    Optional global font size override.

  • frameon (bool, default: False ) –

    Whether to draw map frame and grid labels.
Returns:
  • tuple[Figure, GeoAxes] –

    Tuple of figure and GeoAxes.

plot_satellite_map(fig, extent, *, alpha=1.0, ax=None, desired_pixels=1024, style=None)

Render a satellite basemap over a geographic extent.

Parameters:
  • fig (Figure) –

    Matplotlib figure used to create the map axes.

  • extent (tuple[float, float, float, float]) –

    Geographic bounds as (west, east, south, north) in degrees.

  • alpha (float, default: 1.0 ) –

    Basemap transparency where 1.0 is fully opaque.

  • ax (tuple[float, float, float, float] | None, default: None ) –

    Optional axes rectangle passed to Figure.add_axes. If omitted, a full-figure subplot is created.

  • desired_pixels (int, default: 1024 ) –

    Target figure resolution in pixels used to estimate tile zoom.

  • style (str | None, default: None ) –

    Optional Cartopy GoogleTiles style string. If omitted, ArcGIS World Imagery tiles are used.
Returns:
  • tuple[GeoAxes, Projection] –

    Tuple containing: - GeoAxes with the satellite basemap. - Projection associated with the tile source.