Execution and run folders

vcsmd.execution is the file-writing application boundary, surfaced through the top-level vcsmd facade. The numerical API does not access files or emit progress output. run creates a documented run folder with configuration provenance, CSV streams, checkpoints, and metadata; resume continues a native checkpoint for additional steps.

class vcsmd.RunStatus(*values)

Bases: Enum

COMPLETE = 'complete'
FAILED = 'failed'
class vcsmd.RunReport(directory: pathlib.Path, status: vcsmd.execution.RunStatus, completed_steps: int, requested_steps: int, final_state: vcsmd.simulation.SimulationState | None, error: str | None = None)

Bases: object

Parameters:

  • directory (Path)

  • status (RunStatus)

  • completed_steps (int)

  • requested_steps (int)

  • final_state (SimulationState | None)

  • error (str | None)

directory: Path
status: RunStatus
completed_steps: int
requested_steps: int
final_state: SimulationState | None
error: str | None = None
vcsmd.run(config, *, output_root=Path('runs'), purpose='simulation', source_file=None, checkpoint_interval=100, progress=None)

Execute all configured steps and write a documented native run folder.

This application boundary owns file access: it snapshots inputs, streams CSV series, and writes periodic and final checkpoints. progress is an optional callback receiving completed and requested step counts. The report contains completion status and the public final state; execution failures preserve available outputs and the last valid state for inspection.

Parameters:

  • config (SimulationConfig)

  • output_root (Path)

  • purpose (str)

  • source_file (Path | None)

  • checkpoint_interval (int)

  • progress (Callable[[int, int], None] | None)

Return type:

RunReport

vcsmd.resume(checkpoint, *, steps, output_root=Path('runs'), purpose='continuation', output_interval=1, checkpoint_interval=100, progress=None)

Continue a native checkpoint for steps additional integration steps.

The checkpoint supplies the model, velocities, acceleration histories, reference cell, and controller accumulators. No thermal reinitialization occurs. Outputs go into a new documented run folder. Bitwise continuation assumes the same numerical implementation and software environment.

Parameters:

  • checkpoint (Path)

  • steps (int)

  • output_root (Path)

  • purpose (str)

  • output_interval (int)

  • checkpoint_interval (int)

  • progress (Callable[[int, int], None] | None)

Return type:

RunReport

resume preserves acceleration history, reference geometry, running accumulators, and controller state from the checkpoint. Exact continuation is expected within the same numerical software environment; changes to numerical libraries, hardware, or code can change floating-point rounding.

The installed vcsmd command exposes run, resume, import-legacy, and convert-legacy. See the guides for command examples and the generated output layout.