Cycles class

cycles.Cycles(path, simulation, 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. This is required to run simulations using the run method.
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 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.).

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.

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.

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, crop_colors=None, fontsize=None)

Plot grain and forage yields from harvest output.

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

    Optional axes to draw on.

  • crop_colors (dict | None, default: None ) –

    Optional mapping from crop names to plot colors.

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

    Optional global font size override.
Returns:
  • Axes –

    Axes containing the yield plot.

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

Plot operation timelines grouped by rotation year.

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

    Optional axes object(s) to draw on.

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

    Optional global matplotlib font size override.
Returns:
  • –

    The axes used for plotting.