routing.core.harness

Harness generation: one user-facing settings surface, staged optimization orchestrated above it.

HarnessSettings is the single declaration surface of RoutePlanner.generate_harness(), mirroring the pipeline — routing, bundling, unlock, consolidate, shape — plus the optimization workshop shared by the stages. Fields derived from the computation cadmap stay None until HarnessSettings.complete() resolves them. HarnessOptimizer drives the enabled stages on a bundle, one GA pass at a time, every pass recorded in a HarnessOptimizationHistory.

class routing.core.harness.ConsolidationSettings(*, name: str = '', enabled: bool = False, max_iterations: int = 5, ga: GAConfig | None = None)

Bases: Model

Consolidate stage (experimental, disabled by default): rerun coarse passes until the topology freezes.

max_iterations caps the reruns; ga is the stage’s GA recipe (None = production_ga() at completion).

enabled: bool

ga: GAConfig | None

max_iterations: int

static production_ga(max_shift: float) → GAConfig

Consolidation recipe (2026-07 campaign): the GAConfig verdict seeded with a jitter of one max_shift.

class routing.core.harness.HarnessOptimizer(settings: HarnessSettings, terms: list[OptimizationTerm] | None = None, name: str = '')

Bases: object

Drive the enabled optimization stages of a completed HarnessSettings on a bundle.

Coarse consolidation reruns until the topology freezes (two successive reruns share the same Bundle.topology_signature()), then precise shaping with the design-rule terms active. One pass = attach_local_cadmaps → clear_port_cad_margin → interactions → BundleProblem.from_terms → SeedRelaxer → GA: preparation builds and poses, the snapshot and the terms then read the posed state. The GA only moves points (topology fixed); Bundle.repaired() between passes re-consolidates the topology (the only step that changes it). A design-rule term is antagonistic to consolidation, so it only joins the stages its RuleEnforcement declares (the shaping stage by default).

terms is the runtime expert override of the bundle-derived terms (OptimizationTerm.from_bundle()) — phenomenon factories are callables, so the override lives on the orchestrator, never on the serialized settings.

consolidate(bundle: Bundle, history: HarnessOptimizationHistory | None = None) → Bundle

Rerun the consolidation pass until the topology freezes; return the frozen, repaired() bundle.

Manche 1 of the study: the returned bundle is the last repaired() output (clean, frozen topology) — the intermediate seed the shaping stage starts from. No design-rule terms here.

diagnose(bundle: Bundle, stage: str, attach: bool = False) → list[ViolatedEntry]

Print the bundle’s per-entity violation report at its current geometry; return the violated entries.

attach=False reuses the local cadmaps the last pass left on the lines (attaching only when missing), so the diagnosed geometry is exactly the stuck one; attach=True forces a re-prepare (re-snaps points and re-accumulates bounds — may move the state). stage selects the verdict’s constraint set: the terms active in that stage (stage="shape" = the full design-rule verdict).

optimize(bundle: Bundle) → HarnessOptimizationHistory

Run the enabled stages in canonical unlock → consolidate → shape order, all recorded in one history.

shape(bundle: Bundle, history: HarnessOptimizationHistory | None = None) → HarnessOptimizationHistory

Shaping pass(es) (design-rule terms active) on the frozen bundle.

Manche 2 of the study: optimizes the harness shape under the full constraint set. max_iterations passes chain on the improved seed (relaxation and GA rerun each time); no repaired() after — this is the final result. Returns the history, displayable via HarnessOptimizationHistory.volume_models().

With shaping.repair armed the passes run on a structural twin: the JunctionFixer changes the topology in place, which would strand every record already posed on bundle (their values were captured on the old topology). The shaped harness is then history.final().bundle — the same contract as consolidate() returning its own bundle.

unlock(bundle: Bundle, history: HarnessOptimizationHistory | None = None) → SolverResult

One unlock pass under the unlocking recipe: drive the bundle to feasibility, no objective polishing.

Stage 1 of the robust pipeline. The unlocking criteria should carry stop_when_feasible (reaching feasibility is the whole objective) and a violation_stall (a plateau means the harness is stuck and the caller must react — lock the cramped zones and regenerate).

class routing.core.harness.HarnessSettings(clearance: float = 0.0, harness_rules: list[DesignRule] | None = None, n_candidate_paths: int = 1, steady_mode: bool = True, bundling: SkeletonSettings | None = None, optimization: OptimizationSettings | None = None, unlocking: UnlockSettings | None = None, consolidation: ConsolidationSettings | None = None, shaping: ShapingSettings | None = None, name: str = '')

Bases: DessiaObject

Every knob of RoutePlanner.generate_harness(), grouped by pipeline stage.

clearance is the CAD safety margin in world units (metres), padding every pipe radius — the single source both the port-base preparation and the CAD-interference constraint read. harness_rules are the design rules added on top of the cadmap’s own (always carried); a rule controls its optimization form through DesignRule.enforcement. n_candidate_paths grid paths are searched per specification (the cheapest kept) and steady_mode keeps routing the remaining specifications when one fails. bundling is the skeletonization recipe, optimization the workshop shared by the stages, unlocking / consolidation / shaping the stages themselves — each runs when enabled, in canonical order.

Fields derived from the computation cadmap (voxel sizes, max_shift, GA recipes) stay None until complete() resolves them; everything here is platform-serializable.

complete(cadmap: CadMap, run_name: str = '') → HarnessSettings

Return a copy where every derived field is made explicit against cadmap.

Explicit values pass through untouched. The derivations — the single place they live: skeletonization and optimizer-window voxel sizes default to half the routing voxel (the recipe validated on the window case), max_shift to 5 routing voxels, and each stage’s ga to its production_ga seeded with the resolved max_shift. An unnamed settings takes "<run_name>_settings".

class routing.core.harness.OptimizationSettings(*, name: str = '', max_shift: float | None = None, voxel_size: float | None = None, exclude_tree_hops: int = 2, relaxation: RelaxationConfig = RelaxationConfig(name='', enabled=True, max_search=2, max_passes=8), out_of_grid_penalty: float = 1000.0)

Bases: Model

The optimization workshop shared by every stage: search space, voxel step and seed repair.

max_shift is the per-point movement budget in world units (None = 5 routing voxels); voxel_size is the optimizer-window voxel step (None = half the routing voxel — the window recipe validated on the window case). exclude_tree_hops is the collision-pair kinship exemption depth; relaxation drives the SeedRelaxer before each pass; out_of_grid_penalty charges the weighted-length samples leaving the grid.

exclude_tree_hops: int

max_shift: float | None

out_of_grid_penalty: float

relaxation: RelaxationConfig

voxel_size: float | None

class routing.core.harness.ShapingSettings(*, name: str = '', enabled: bool = True, max_iterations: int = 1, repair: bool = False, ga: GAConfig | None = None)

Bases: Model

Shape stage: refine the frozen topology with the design-rule terms active.

max_iterations chains that many shape passes on the improved seed (default 1 — the final result); repair arms the JunctionFixer at the head of each pass. ga is the stage’s GA recipe (None = production_ga() at completion).

enabled: bool

ga: GAConfig | None

max_iterations: int

static production_ga(max_shift: float) → GAConfig

Shaping recipe (2026-07 campaign): the GAConfig verdict seeded with a jitter of one max_shift.

repair: bool

class routing.core.harness.UnlockSettings(*, name: str = '', enabled: bool = True, max_iterations: int = 3, lock_dilation_voxels: float = 5.0, lock_strength: float = 100.0, ga: GAConfig | None = None)

Bases: Model

Unlock stage: reach feasibility, locking and regenerating the cramped zones on a plateau.

max_iterations caps the lock + regenerate rounds; each cramped free line is dilated by lock_dilation_voxels routing voxels and repelled with lock_strength on the cadmap. ga is the stage’s GA recipe (None = production_ga() at completion).

enabled: bool

ga: GAConfig | None

lock_dilation_voxels: float

lock_strength: float

max_iterations: int

static production_ga(max_shift: float) → GAConfig

Unlock recipe (2026-07 campaign): jittered seed, stop when feasible, trip on a violation plateau.