routing.core.route_planner

Module to plan the routing problem and use its result.

class routing.core.route_planner.RoutePlanner(cadmap: CadMap, finder: SmartFinder, name: str = '')

Bases: Object3D

A class representing the main planner for routing problems.

Coordinates pathfinding and optimization for pipe routing. It combines a CadMap (spatial representation) with a SmartFinder (pathfinding algorithm) to generate and optimize routing solutions.

Parameters:

• cadmap – The CadMap object containing the routing space, volumes, and design rules.

• finder – The SmartFinder object implementing the pathfinding algorithm (e.g., AStarFinder, DijkstraFinder).

• name – The name to identify this route planner. Defaults to ‘’.

find_paths(grid: SmartGridInterface, solution: Solution, n_iterations: int, overweighted_voxels: ndarray | None = None) → list[GridPath]

Find routing paths for a solution.

Updates the CadMap with pipe type information, computes weights, and searches for paths using the finder algorithm.

Parameters:

• grid – SmartGridInterface representing the searchable grid

• solution – Solution object defining the routing problem (ports, pipe type)

• n_iterations – Number of pathfinding iterations (for k-shortest paths)

• overweighted_voxels – Optional array of voxels with additional weight penalties

Returns:

List of GridPath objects representing found paths

generate(specifications: list[Specification], n_iterations: int = 0, steady_mode: bool = False) → RoutingResults

Generate routing paths for multiple specifications.

Performs pathfinding for each specification in the list: 1. Builds the search grid from CadMap 2. Builds pooling matrices for all pipe types 3. For each specification:

• Creates a Solution from port couple and pipe type

• Finds grid paths using the finder algorithm

• Updates solution with found paths

• Updates CadMap packs with the solution

If steady_mode is False, raises exceptions on routing failures. If steady_mode is True, continues processing other specifications even if one fails.

Parameters:

• specifications – List of Specification objects, each defining a routing problem (port couple and pipe type).

• n_iterations – Number of pathfinding iterations (k-shortest paths). Defaults to 0 (single best path).

• steady_mode – If True, continues processing even if a specification fails. If False, raises exceptions on failure. Defaults to False.

Returns:

RoutingResults object containing all generated solutions and the CadMap used for routing.

optimize(costs: Costs, settings: Settings, picked_path: str = 'best', max_refinements: int = 5) → RoutingResults

Optimize all routing solutions using post-processing refinement.

Performs optimization on all solutions in the CadMap: 1. Creates an Optimizer from the CadMap 2. For each solution:

• Runs global 3D optimization to refine the path

• Identifies problematic voxels and constraint violations

• If max_refinements > 0 and problems found: - Attempts to restart pathfinding avoiding dead ends - Tries multiple refinement iterations with adjusted costs

The optimization improves path quality by minimizing length, bends, and constraint violations while respecting design rules.

Parameters:

• costs – Costs object with cost weights for optimization (length, bends, constraints, etc.).

• settings – Settings object with optimization parameters (voxel_size, max_shift, max_iter, etc.).

• picked_path – Path identifier to optimize (“best” or “last”). Defaults to “best”.

• max_refinements – Maximum number of refinement iterations when problems are detected. If 0, no refinements are attempted. Defaults to 5.

Returns:

RoutingResults object containing all optimized solutions and the CadMap used for routing.

optimize_with_new_costs(failed_constraints: dict[str, int], solution: Solution, optimizer: Optimizer, costs: Costs, settings: Settings, init_max_shift: float, picked_path: str) → tuple[list[ndarray], dict[str, int]]

Optimize a solution with adjusted cost weights based on constraint violations.

When initial optimization fails to satisfy constraints, this method: 1. Creates a copy of the cost object 2. Adjusts cost weights based on failed constraints:

• is_short: Multiplies short_line cost by (violations + 1)

• gravity: Multiplies gravity cost by (violations + 1)

• clampable: Multiplies constraint cost by 5

3. Increases max_shift by 50% to allow larger movements

4. Re-runs optimization with the adjusted costs

This adaptive approach helps the optimizer find valid solutions when initial attempts fail by prioritizing constraint satisfaction.

Parameters:

• failed_constraints – Dictionary mapping constraint names to violation counts (e.g., {“is_short”: 2, “gravity”: 1, “clampable”: 1}).

• solution – Solution object to optimize.

• optimizer – Optimizer instance with current settings.

• costs – Original Costs object (will be copied and modified).

• settings – Settings object with optimization parameters.

• init_max_shift – Original max_shift value (will be increased by 50%).

• picked_path – Path identifier to optimize (“best” or “last”).

Returns:

Tuple of (overweighted_voxels, failed_constraints) where: - overweighted_voxels: List of arrays with problematic voxel indices - failed_constraints: Dictionary of remaining constraint violations

restart_avoiding_dead_ends(overweighted_voxels: list[ndarray], failed_constraints: dict[str, int], solution: Solution, picked_path: str, grid: SmartGrid, optimizer: Optimizer, costs: Costs, settings: Settings, max_refinements: int = 5) → None

Restart pathfinding and optimization to avoid problematic regions.

When optimization fails to find valid solutions, this method attempts multiple refinement iterations:

1. For each iteration (up to max_refinements): - Tries optimization with adjusted costs (via optimize_with_new_costs) - If still failing, generates a new path avoiding overweighted voxels - Updates solution with the new path - Re-optimizes with increased max_iter (3x original)

2. If problems persist after all iterations: - Makes a final attempt with adjusted costs - Logs a warning if no valid solution is found

The overweighted voxels are accumulated across iterations to build a comprehensive map of problematic regions that should be avoided.

Parameters:

• overweighted_voxels – List of arrays with problematic voxel indices from previous optimization attempts.

• failed_constraints – Dictionary mapping constraint names to violation counts from previous optimization.

• solution – Solution object to refine.

• picked_path – Path identifier to optimize (“best” or “last”).

• grid – SmartGrid object for pathfinding.

• optimizer – Optimizer instance with current settings.

• costs – Costs object with cost weights.

• settings – Settings object with optimization parameters.

• max_refinements – Maximum number of refinement iterations to attempt. Defaults to 5.

Returns:

None (modifies solution in place).

volmdlr_primitives() → list[Primitive3D]

Get volmdlr primitives for visualization.

Returns primitives from the CadMap for 3D visualization.

Returns:

List of Primitive3D objects from the CadMap

class routing.core.route_planner.RoutingResults(solutions: list[Solution], cadmap: CadMap | None = None, name: str = '')

Bases: Object3D

A class representing routing results containing multiple solutions and the CadMap.

Contains all routing solutions generated by RoutePlanner along with the CadMap used for routing. It provides methods for visualization and analysis.

Parameters:

• solutions – The list of Solution objects from routing.

• cadmap – The optional CadMap object used for routing. Defaults to None.

• name – The name to identify this routing results. Defaults to ‘’.

collect_packs(only_optimized: bool = True) → list[Pack]

Collect all pipeline packs from optimized solutions.

Gathers Pack objects that group aligned PipeLine segments from multiple solutions. Packs are created when pipes share similar paths and can be routed together for efficiency. The method:

1. Iterates through all packs in the CadMap

2. For each pack, collects pipe lines from solutions that: - Are well optimized (if only_optimized=True) or all solutions (if False) - Have pipe lines that belong to the pack (within offset distance)

3. Creates new Pack objects containing only the best pipe lines from each solution that match the pack’s alignment and proximity criteria

Packs are used for: - Collision detection between aligned pipes - Pooling optimization (routing pipes together) - Managing pipe clusters in voxelized space

Parameters:

• offset – Maximum distance tolerance for considering a pipe line as part of a pack. Pipe lines must be within this distance from the pack’s alignment vector to be included. Typically set to a small fraction of the voxel size.

• only_optimized – If True, only collects packs from solutions that are well optimized (is_well_optimized=True). If False, includes packs from all solutions regardless of optimization status. Defaults to True.

Returns:

List of Pack objects, each containing aligned pipe lines from multiple solutions that can be routed together. Each pack includes the best pipe lines from matching solutions and maintains the pack’s alignment vector and parallel status.

plot_data_generated

plot_data_optimized

specific_packs_cad_view(packs: list[Pack]) → None

Display 3D CAD view of solutions with specific packs highlighted.

Creates a combined visualization showing: - All solutions from the CadMap - The specified packs (highlighted) - The CadMap voxelization (if available)

Opens an interactive 3D viewer (BabylonJS) for inspection.

Parameters:

packs – List of Pack objects to highlight in the visualization.

Returns:

None (opens interactive 3D viewer).

volmdlr_primitives() → list[Primitive3D]

Get volmdlr primitives for 3D visualization.

Collects primitives from all solutions and optionally from the CadMap to create a complete 3D visualization of the routing results.

Returns:

List of Primitive3D objects combining: - All primitives from all solutions in the results - Primitives from the CadMap (if available)