brushline.build and brushline.sim
The prototype compiler, simulator, schedule, and run writer.
Compile the synthetic corridor fixture into a validated Brushline dataset.
The compiler reads the fixture’s dataset, corridor graph, and state contract, joins the service standards and corridor attributes onto the segments, and writes the compiled segments and states tables plus a dataset manifest. It is the smallest end-to-end compile path; the production compiler is P2 and P3.
- class brushline.build.compiler.CompiledDataset(root: Path, manifest: DatasetManifest, segments: DataFrame, states: DataFrame)[source]
Bases:
objectThe output of one fixture compile.
- Parameters:
root (Path) – Compiled dataset directory.
manifest (DatasetManifest) – Dataset manifest.
segments (pandas.DataFrame) – Compiled segment table.
states (pandas.DataFrame) – Compiled state table.
- brushline.build.compiler.compile_fixture(fixture_root: Path, out: Path, *, force: bool = False) CompiledDataset[source]
Compile the synthetic fixture into a validated dataset.
- Parameters:
fixture_root (Path) – Fixture directory, such as
examples/synthetic-corridor.out (Path) – Compiled dataset directory.
force (bool, optional) – Overwrite an existing dataset directory. Defaults to
False.
- Returns:
CompiledDataset – The compiled directory, manifest, segments, and states.
- Raises:
FileExistsError – When the output directory is not empty and
forceis false.ValueError – When a source contract fails validation.
Deterministic prototype simulator.
The prototype uses a linear growth rule and a fractional treatment transition. It is not the calibrated P4 model. Its job is to exercise the compiled dataset, the plan or schedule, the run writer, and the studio artifact contract end to end.
- class brushline.sim.engine.SimulationResult(run_dir: Path, accounts: DataFrame, schedule: DataFrame, state_values: DataFrame, summary: dict[str, object])[source]
Bases:
objectThe output of one prototype simulation.
- Parameters:
run_dir (Path) – Run directory.
accounts (pandas.DataFrame) – Long account values, one row per year and account.
schedule (pandas.DataFrame) – Replayed schedule with status.
state_values (pandas.DataFrame) – Per-segment, per-year state values.
summary (dict of str to object) – Run summary.
- brushline.sim.engine.read_run_summary(run_dir: Path) RunManifest[source]
Read a run manifest.
- Parameters:
run_dir (Path) – Run directory.
- Returns:
RunManifest – The parsed run manifest.
- brushline.sim.engine.simulate_dataset(dataset: Path, out: Path, *, plan: Path | None = None, schedule: Path | None = None, years: int = 5, start_year: int = 2026, force: bool = False) SimulationResult[source]
Replay a plan or schedule against a compiled dataset.
- Parameters:
dataset (Path) – Compiled dataset directory.
out (Path) – Run directory.
plan (Path or None, optional) – Plan artifact. Exactly one of
planandscheduleis required.schedule (Path or None, optional) – Schedule CSV. Exactly one of
planandscheduleis required.years (int, optional) – Number of simulation years. Defaults to
5.start_year (int, optional) – First simulation year. Defaults to
2026.force (bool, optional) – Overwrite a non-empty run directory. Defaults to
False.
- Returns:
SimulationResult – The run directory, accounts, schedule, state values, and summary.
- Raises:
ValueError – When the input selection is invalid, the dataset is invalid, or a schedule references an unknown segment.
FileExistsError – When the output directory is not empty and
forceis false.
Schedule rows and conversion from a plan.
A schedule is the minimal action list the simulator replays: segment, year, method, intensity, efficacy, and cost. The prototype accepts a CSV or a plan artifact. The calibrated production path will add the richer plan contract.
- class brushline.sim.schedule.ScheduleRow(*, segment_id: Annotated[str, MinLen(min_length=1)], year: Annotated[int, Ge(ge=1900), Le(le=2200)], action_id: Annotated[str, MinLen(min_length=1)], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], intensity: Annotated[float, Ge(ge=0), Le(le=1)], efficacy: Annotated[float, Ge(ge=0), Le(le=1)], cost: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne treatment action in a schedule.
- Parameters:
segment_id (str) – Segment identifier.
year (int) – Treatment year.
action_id (str) – Action identifier.
method ({"manual", "mechanical", "chemical", "mowing", "grazing", "prescribed_fire", "other"}) – Treatment method.
intensity (float) – Intensity from 0 to 1.
efficacy (float) – Efficacy from 0 to 1.
cost (float) – Action cost. Must be non-negative.
- model_config = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.sim.schedule.load_schedule(path: Path) list[ScheduleRow][source]
Load a schedule CSV.
- Parameters:
path (Path) – CSV file with the columns
segment_id,year,action_id,method,intensity,efficacy, andcost.- Returns:
list of ScheduleRow – Validated schedule rows.
- Raises:
ValueError – When a required column is missing or a row is invalid.
- brushline.sim.schedule.schedule_from_plan(plan: Plan) list[ScheduleRow][source]
Convert a plan’s actions into schedule rows.
- Parameters:
plan (Plan) – Plan artifact.
- Returns:
list of ScheduleRow – One row per plan action, in plan order.
Write a run manifest and its artifact index.
- class brushline.run.RunArtifactSpec(name: str, path: str, schema_version: str, media_type: str)[source]
Bases:
objectOne artifact to include in a run manifest.
- Parameters:
name (str) – Artifact name.
path (str) – Run-relative path.
schema_version (str) – Artifact schema version.
media_type (str) – Media type.
- brushline.run.write_run_manifest(run_dir: Path, *, run_id: str, run_type: Literal['build', 'simulate', 'plan', 'monitor', 'compare', 'demo'], status: Literal['running', 'complete', 'failed'], data_version: str, model_versions: dict[str, str], configuration: dict[str, object], summary: dict[str, object], artifacts: list[RunArtifactSpec], created_utc: datetime | None = None, seed: int | None = None) Path[source]
Write a run’s
run.json.- Parameters:
run_dir (Path) – Run directory. It must already contain the artifacts.
run_id (str) – Run identifier.
run_type ({"build", "simulate", "plan", "monitor", "compare", "demo"}) – Run type.
status ({"running", "complete", "failed"}) – Run status.
data_version (str) – Dataset version or digest.
model_versions (dict of str to str) – Model ids and versions.
configuration (dict of str to object) – Run configuration.
summary (dict of str to object) – Run summary.
artifacts (list of RunArtifactSpec) – Artifacts to index.
created_utc (datetime or None, optional) – Timezone-aware creation time. Defaults to the current UTC time.
seed (int or None, optional) – Random seed.
- Returns:
Path – The written
run.json.- Raises:
FileNotFoundError – When an indexed artifact is missing.
RuntimeError – When the manifest fails its own validator.