Optimization evaluator

The exact evaluator replays a formulation assignment through the P4 growth and treatment models and returns the four-objective vector, feasibility, named violations, cost accounts, and a per-segment period trail.

from brushline.optimization.evaluator import (
    EvaluationConfig,
    ScheduleEvaluator,
    SegmentContext,
)

evaluator = ScheduleEvaluator(formulation, contexts, EvaluationConfig(discount_rate=0.03))
result = evaluator.evaluate(evaluator.initial_assignment())
assert set(result.objective_vector) == {
    "present_cost",
    "service_risk",
    "service_attainment",
    "uncertainty",
}

Context

SegmentContext supplies the initial StateDistribution, functional group, service standard, segment length, growth environment, swath width, and optional asset height. The context length must match the formulation segment length.

Each period is a growth step of end_year - start_year + 1 years. A selected treatment is applied at the period start with a post-delay regrowth horizon of one year less than the period length. A period without a treatment grows the current state for the full period. An unknown group or out-of-domain environment is a named hard violation; it is never extrapolated.

Costs

Treatment cost is the formulation option’s cost_per_ha * area_ha + fixed_cost, where area_ha = length_m * treatment_width_m / 10000. Monitoring cost is charged once per selected span and period, then allocated evenly across the span’s segments for the period trail. The total is not multiplied by the number of segments.

total_cost is undiscounted. discounted_cost divides each period’s cost by (1 + discount_rate) ** (period_start - base_year). present_cost is the discounted total.

Service and uncertainty

For each segment and period, the evaluator records:

  • the service height margin;

  • the clearance margin, when an asset height is known;

  • the probability that mean height exceeds the service height or the clearance threshold, using a normal height interval;

  • whether the mean state attains the service standard;

  • one minus state confidence after monitoring.

The objective vector weights these results by segment length and the number of periods:

Objective

Definition

present_cost

Discounted treatment and monitoring cost.

service_risk

Length- and period-weighted exceedance probability.

service_attainment

Length- and period-weighted share of periods that meet the standard.

uncertainty

Length- and period-weighted one-minus-confidence after the last period.

Monitoring reduces the height, cover, and density standard deviations by 1 - 0.5 * sampling_intensity and raises confidence by the same factor. This is a transparent prototype rule, not a sensor-specific measurement model.

Feasibility and named violations

Hard violations make feasible false:

  • EVALUATION-ASSIGNMENT: missing or extra variables.

  • EVALUATION-OPTION: an option index is outside the variable’s options.

  • EVALUATION-ACCESS: a treatment is selected in an inaccessible segment/period.

  • EVALUATION-BUDGET: treatment cost exceeds the period budget.

  • EVALUATION-MONITORING-BUDGET: monitoring cost exceeds the period budget.

  • EVALUATION-CAPACITY: treated area exceeds a method capacity.

  • EVALUATION-TREATMENT: the treatment transition is blocked or invalid.

  • EVALUATION-GROWTH: the growth step is blocked or invalid.

  • EVALUATION-SERVICE: the service standard is missed and the service constraint is hard.

A service miss is soft when the matching service constraint has hard = false. Soft violations are reported in soft_violations and do not make the plan infeasible.

Incremental path

IncrementalEvaluator wraps the exact evaluator with a resident assignment and typed AssignmentChange apply/undo. Budgets, capacities, service, and coupled growth make an unproved delta unsafe, so the declared rule is full exact recomputation. The wrapper caches exact results, reports mode = "full_fallback", and counts new recomputations in fallbacks. Apply/undo restores the exact prior assignment and result.

Limits

  • The evaluator is a decision-support prototype; it is not an engineering clearance or safety model.

  • The risk probability uses a normal height interval and ignores serial correlation.

  • Monitoring is a cost and uncertainty rule, not a full sensor simulator.

  • The exact evaluator is the reference for the P5.3 operators and P5.4 search.