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:
BaseModelOne 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:
BaseModelDiscount 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:
BaseModelThe 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:
BaseModelOne 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:
ValueErrorRaised when the evaluator or a context is inconsistent.
- class brushline.optimization.evaluator.IncrementalEvaluator(evaluator: ScheduleEvaluator, assignment: dict[int, int] | None = None)[source]
Bases:
objectResident 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 –
exactorfull_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:
objectExact evaluator for one formulation and its segment contexts.
- Parameters:
formulation (Formulation) – Optimization formulation.
contexts (list of SegmentContext) – One context per segment.
config (EvaluationConfig, optional) – Discount settings.
- 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.
- 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:
BaseModelInitial 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:
BaseModelThe 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].