brushline.optimization.evaluator

The exact schedule evaluator, segment context, evaluation result, objective scalarization, and the conservative incremental wrapper.

Exact schedule evaluation and a conservative incremental path.

The evaluator replays a formulation assignment through the P4 growth and treatment models. It returns the four-objective vector, hard and soft violations, cost accounts, and a per-segment period trail. The incremental wrapper applies and undoes typed assignment changes and always recomputes exactly; global budget, capacity, service, and coupled growth make an unproved delta unsafe, so the full-evaluation fallback is the declared rule.

class brushline.optimization.evaluator.AssignmentChange(*, variable: Annotated[int, Ge(ge=0)], before: Annotated[int, Ge(ge=0)], after: Annotated[int, Ge(ge=0)], kind: str = 'toggle', size: Annotated[int, Ge(ge=1)] = 1)[source]

Bases: BaseModel

One reversible assignment change.

Parameters:
  • variable (int) – Variable index.

  • before (int) – Previous option index.

  • after (int) – Proposed option index.

  • kind (str, optional) – Move kind. Defaults to toggle.

  • size (int, optional) – Move size. Defaults to one.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.evaluator.EvaluationConfig(*, discount_rate: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, base_year: int | None = None)[source]

Bases: BaseModel

Discount and uncertainty settings.

Parameters:
  • discount_rate (float) – Annual discount rate from 0 to 1.

  • base_year (int or None) – Discount base year. Defaults to the first period.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.optimization.evaluator.EvaluationResult(*, schema_version: ~typing.Literal['brushline.optimization-evaluation.v1'] = 'brushline.optimization-evaluation.v1', formulation_id: str, assignment: dict[int, int], objective_vector: dict[str, float], feasible: bool, violations: list[~brushline.optimization.evaluator.EvaluationViolation] = <factory>, soft_violations: list[~brushline.optimization.evaluator.EvaluationViolation] = <factory>, total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], discounted_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], treatment_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], monitoring_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], period_results: list[~brushline.optimization.evaluator.SegmentPeriodResult] = <factory>)[source]

Bases: BaseModel

The exact result of one schedule.

Parameters:
  • schema_version ({"brushline.optimization-evaluation.v1"}) – Schema version.

  • formulation_id (str) – Formulation id.

  • assignment (dict of int to int) – Variable-to-option assignment.

  • objective_vector (dict of str to float) – Four objectives.

  • feasible (bool) – Whether all hard constraints hold.

  • violations (list of EvaluationViolation) – Hard violations.

  • soft_violations (list of EvaluationViolation) – Soft violations.

  • total_cost (float) – Undiscounted total cost.

  • discounted_cost (float) – Discounted total cost.

  • treatment_cost (float) – Treatment cost.

  • monitoring_cost (float) – Monitoring cost.

  • period_results (list of SegmentPeriodResult) – Segment-period trail.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scalar_objective(weights: dict[str, float]) → float[source]

Return a weighted scalar objective, lower is better.

Parameters:

weights (dict of str to float) – Non-negative objective weights.

Returns:

float – Weighted sum after direction normalization.

Raises:

EvaluatorError – When a weight is unknown or negative.

class brushline.optimization.evaluator.EvaluationViolation(*, code: Annotated[str, MinLen(min_length=1)], message: Annotated[str, MinLen(min_length=1)], kind: Annotated[str, MinLen(min_length=1)], period_id: str | None = None, target_id: str | None = None, variable_index: int | None = None)[source]

Bases: BaseModel

One named hard or soft violation.

Parameters:
  • code (str) – Stable violation code.

  • message (str) – Human explanation.

  • kind (str) – Constraint kind.

  • period_id (str or None) – Period id.

  • target_id (str or None) – Segment or span id.

  • variable_index (int or None) – Variable index.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception brushline.optimization.evaluator.EvaluatorError[source]

Bases: ValueError

Raised when the evaluator or a context is inconsistent.

class brushline.optimization.evaluator.IncrementalEvaluator(evaluator: ScheduleEvaluator, assignment: dict[int, int] | None = None)[source]

Bases: object

Resident assignment with exact apply/undo and a declared full fallback.

Parameters:
  • evaluator (ScheduleEvaluator) – Exact evaluator.

  • assignment (dict of int to int or None, optional) – Starting assignment. None uses the no-action assignment.

property assignment: dict[int, int]

Return a copy of the current assignment.

Returns:

dict of int to int – Assignment copy.

property evaluation: EvaluationResult

Return the current exact evaluation.

Returns:

EvaluationResult – Current evaluation.

property mode: str

Return the last evaluation mode.

Returns:

str – exact or full_fallback.

property fallbacks: int

Return the full-recomputation count.

Returns:

int – Number of fallback evaluations.

apply(change: AssignmentChange) → EvaluationResult[source]

Apply one change and recompute exactly.

Parameters:

change (AssignmentChange) – Change to apply.

Returns:

EvaluationResult – New exact result.

Raises:

EvaluatorError – When the change does not match the resident assignment.

undo(change: AssignmentChange) → EvaluationResult[source]

Undo one change and recompute exactly.

Parameters:

change (AssignmentChange) – Change to undo.

Returns:

EvaluationResult – Restored exact result.

Raises:

EvaluatorError – When the change does not match the resident assignment.

class brushline.optimization.evaluator.ScheduleEvaluator(formulation: Formulation, contexts: list[SegmentContext], config: EvaluationConfig | None = None)[source]

Bases: object

Exact evaluator for one formulation and its segment contexts.

Parameters:
Raises:

EvaluatorError – When a segment context is missing, duplicated, or unknown.

evaluate(assignment: dict[int, int]) → EvaluationResult[source]

Evaluate one complete assignment exactly.

Parameters:

assignment (dict of int to int) – Variable-to-option assignment.

Returns:

EvaluationResult – Exact objectives, feasibility, costs, violations, and trail.

evaluate_batch(assignments: list[dict[int, int]]) → list[EvaluationResult][source]

Evaluate a batch exactly and in order.

Parameters:

assignments (list of dict of int to int) – Assignments.

Returns:

list of EvaluationResult – One result per assignment.

initial_assignment() → dict[int, int][source]

Return the no-action assignment.

Returns:

dict of int to int – Every variable at option 0.

class brushline.optimization.evaluator.SegmentContext(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], functional_group: ~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], initial: ~brushline.vegetation.state_space.StateDistribution, service_standard: ~brushline.model.corridor.ServiceStandard, length_m: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], environment: ~brushline.vegetation.growth.GrowthEnvironment = <factory>, treatment_width_m: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)] = 10.0, asset_height_m: ~typing.Annotated[float | None, ~annotated_types.Gt(gt=0)] = None)[source]

Bases: BaseModel

Initial state and site context for one segment.

Parameters:
  • segment_id (str) – Segment id.

  • functional_group (str) – Functional group.

  • initial (StateDistribution) – Initial distribution.

  • service_standard (ServiceStandard) – Service standard.

  • length_m (float) – Segment length in metres.

  • environment (GrowthEnvironment, optional) – Growth environment.

  • treatment_width_m (float, optional) – Swath width for area and cost. Defaults to 10.

  • asset_height_m (float or None, optional) – Conductor or asset height for clearance.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property area_ha: float

Return the treated area in hectares.

Returns:

float – Segment length times swath width in hectares.

class brushline.optimization.evaluator.SegmentPeriodResult(*, segment_id: str, period_id: str, start_state: StateDistribution, end_state: StateDistribution, treatment_option_id: str | None = None, monitoring_option_id: str | None = None, treatment_cost: Annotated[float, Ge(ge=0)], monitoring_cost: Annotated[float, Ge(ge=0)], service_attainment: bool, risk_probability: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)], height_margin_m: float, clearance_margin_m: float | None = None)[source]

Bases: BaseModel

The state and service result for one segment and period.

Parameters:
  • segment_id (str) – Segment id.

  • period_id (str) – Period id.

  • start_state (StateDistribution) – State at period start.

  • end_state (StateDistribution) – State at period end.

  • treatment_option_id (str or None) – Selected treatment option.

  • monitoring_option_id (str or None) – Selected monitoring option.

  • treatment_cost (float) – Treatment cost.

  • monitoring_cost (float) – Monitoring cost.

  • service_attainment (bool) – Whether the mean state meets the service standard.

  • risk_probability (float) – Height or clearance exceedance probability.

  • uncertainty (float) – One minus confidence at period end.

  • height_margin_m (float) – Service height margin, negative when exceeded.

  • clearance_margin_m (float or None) – Clearance margin, or None without an asset height.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].