Cycles class

cycles.Cycles(path, simulation, output=dict[str, Output](), control=None, operations=None, soil_profile=None, curve_number=None, slope=None, weather=None, executable=None) dataclass

Interface for executing one Cycles simulation and reading its files.

Provides methods to run simulations, read outputs, and inspect soil/weather/operation configurations. Automatically loads the control file upon initialization.

Parameters:
  • path (Path | str) –

    Path to the simulation directory (containing input/ and output/ subdirs).

  • simulation (str) –

    Name of the simulation (base name of control file without extension).

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

    Optional absolute path to the Cycles executable binary.
Attributes:
  • path (Path | str) –

    Path to the simulation directory (containing input/ and output/ subdirs).

  • simulation (str) –

    Name of the simulation (base name of control file without extension).

  • output (dict[str, Output]) –

    Dictionary mapping output table names to Output objects with data and units.

  • control (ControlConfig | None) –

    Parsed control file configuration from the input directory.

  • operations (list | None) –

    List of parsed operation records from the operation file.

  • soil_profile (list[SoilLayer] | None) –

    List of SoilLayer objects describing the soil profile.

  • curve_number (int | None) –

    Runoff curve number for hydrologic calculations.

  • slope (float | None) –

    Land slope used in erosion and runoff models.

  • weather (DataFrame | None) –

    DataFrame of weather forcing data (temperature, precipitation, etc.).

  • executable (Path | str | None) –

    Absolute path to the Cycles executable binary.

run(options, silence=False)

Run the Cycles executable for this simulation.

To use the run method, the executable attribute must be set to the absolute path of the Cycles binary. 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.).

Parameters:
  • options (str) –

    Command-line options passed to Cycles.

  • silence (bool, default: False ) –

    If True, suppress stdout and stderr printing.
Returns:
  • tuple[int, str] –

    A tuple with process return code and stdout text.

read_output(output_types)

Read one or more output tables into memory.

Parameters:
  • output_types (Collection) –

    Output table name or collection of names.

read_operation_file()

Load operation records defined in the control file.

read_soil_file()

Load soil profile layers and metadata from the configured soil file.

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

Read weather forcing data for the configured weather file.

Parameters:
  • 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 format instead of daily.

generate_reinit_file(doy, *, reinit_name=None)

Generate a reinitialization file from model output.

Parameters:
  • doy (int) –

    Day-of-year to extract from reinit output.

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

    Optional output stem for the reinit file.

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

Plot grain and forage yields from harvest output.

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

Plot operation timelines grouped by rotation year.

Parameters:
  • rotation_size –

    Number of years in the plotted rotation.

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

    Optional axes object(s) to draw on.

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

    Global matplotlib font size override.
Returns:
  • –

    The axes used for plotting.