Cycles rotation builder class

cycles.CyclesRotationBuilder(simulation, executable, crops, control_dict, *, build_yield_matrix=True) dataclass

Run Cycles iteratively and append economically optimal operations.

Executes Cycles simulations for candidate crop-operation combinations, selects the highest-return option at each break-point, and iteratively builds a multi-year rotation. Integrates economic scoring with agronomic constraints (e.g., minimum planting interval, crop group penalties).

Attributes:
  • simulation (str) –

    Base simulation name for generated input/output directories.

  • executable (str) –

    Absolute path to the Cycles executable binary.

  • crops (list[Crop]) –

    List of Crop objects with available operations for rotation.

  • control_dict (dict) –

    Base control file parameters (simulation years, options, etc.).

  • build_yield_matrix (bool) –

    Optional flag: If True, run simulations to build yield matrix; else read from disk.
Attributes:
  • simulation (str) –

    Base simulation name for generated input/output directories.

  • executable (str) –

    Absolute path to the Cycles executable binary.

  • crops (list[Crop]) –

    List of Crop objects with available operations for rotation.

  • control_dict (dict) –

    Base control file parameters (simulation years, options, etc.).

  • fertilizers (dict[str, Fertilizer]) –

    Dictionary mapping fertilizer names to Fertilizer objects.

  • yield_matrix (dict[str, DataFrame]) –

    Dictionary mapping crop names to yield prediction DataFrames.

  • build_yield_matrix (bool) –

    If True, run simulations to build yield matrix; else read from disk.

  • crop_price_data (DataFrame | None) –

    DataFrame of crop prices indexed by calendar year.

  • fertilizer_price_data (DataFrame | None) –

    DataFrame of fertilizer prices indexed by year, or None.

  • production_cost_data (DataFrame | None) –

    DataFrame of production costs indexed by year, or None.

  • rotation_frequency (dict[str, tuple[float, float]] | None) –

    Dictionary mapping crop names to (min, max) frequency tuples.

run(*, crop_price, fertilizer_price=None, production_cost=None, rotation_frequency=None)

Run the dynamic rotation-building loop.

Parameters:
  • crop_price (str | Path) –

    CSV file of crop prices indexed by year.

  • fertilizer_price (str | Path | None, default: None ) –

    Optional fertilizer price table indexed by year.

  • production_cost (str | Path | None, default: None ) –

    Optional crop production cost table indexed by year.

  • rotation_frequency (dict[str, tuple[float, float]] | None, default: None ) –

    Optional min/max frequency constraints per crop symbol.