Cycles runner class

cycles.CyclesRunner(executable) dataclass

Run one or many Cycles simulations with templated inputs.

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.

Parameters:
  • executable (str) –

    Absolute path to the Cycles executable binary.

run(simulations, control_dict, *, summary='summary.csv', operation_template=None, operation_dict=None, calibration_dict=None, options='', rm_input=False, rm_output=False, rm_steady_state_soil=True, silence=True, user_comment='')

Execute a batch of simulations and write a consolidated summary.

Parameters:
  • simulations (SimulationConfig) –

    Simulation rows as list of dicts or a DataFrame.

  • control_dict (dict[str, Any]) –

    Control-file values or callables evaluated per row.

  • summary (str, default: 'summary.csv' ) –

    Summary CSV name written under summary directory.

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

    Template file for generated operation files.

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

    Substitutions used with operation template.

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

    Nudge-file values or callables per row.

  • options (str, default: '' ) –

    Cycles command options.

  • rm_input (bool, default: False ) –

    Remove generated input files after each run.

  • rm_output (bool, default: False ) –

    Remove run output directory after each run.

  • rm_steady_state_soil (bool, default: True ) –

    Remove generated steady-state soil file.

  • silence (bool, default: True ) –

    If True, suppress simulation screen output.

  • user_comment (str, default: '' ) –

    Optional text prefixed to summary header comments.