revrt.routing.cli.point_to_feature.compute_lcp_routes#

compute_lcp_routes(cost_fpath, out_dir, job_name, routing_options, route_table_fpath='PIPELINE', features_fpath='PIPELINE', drivers=None, transition_costs=None, tracked_layers=None, transmission_config=None, save_paths=False, save_routing_layer=False, invalid_costs_block_routing=False, connection_identifier_column='end_feat_id', algorithm='bidirectional_long_range_dijkstra', memory_utilization_limit=0.9, system_mem_limit_gb=5, _split_params=None)[source]#

Run least-cost path routing for points mapped to features

Given a table that defines each route as a start point (via latitude and longitude input or preferably a row/column index into the data) and a feature ID representing the feature to connect to, compute the least-cost paths (LCPs) for each route using the routing layers defined in routing_options.

Parameters:

cost_fpath (path-like) – Path to layered Zarr file containing cost and other required routing layers.
out_dir (path-like) – Directory where routing outputs should be written.
job_name (str) – Label used to name the generated output file.
route_table_fpath (path-like, str, or list, default "PIPELINE") –
Route-table input defining all route start points and end features.

If set to "PIPELINE", then features_fpath must also be "PIPELINE" and the route tables will be pulled from the previous pipeline step. Pipeline inputs require previous outputs containing matching CSV route tables and GPKG feature files.

Otherwise, provide either a single CSV path or a list of CSV paths. When a list is provided, features_fpath must also be a list with the same length, and each route table is paired with the feature file at the same list index.

Each route table must have the following columns:
- ”start_lat”: Stating point latitude (can alternatively use “start_col” to define the start point column index in the cost raster).
- ”start_lon”: Stating point longitude (can alternatively use “start_row” to define the start point row index in the cost raster).
- connection_identifier_column: ID of the feature that should be mapped to. This ID should match at least one of the feature IDs in the features_fpath input; otherwise, no route will be computed for that point.
  
  You can also specify polarity and voltage columns which apply to every routing option. If you want to provide per-option polarity and voltage, use polarity_<option> and voltage_<option>. Options that are omitted will use polarity and voltage column values.
features_fpath (path-like, str, or list, default "PIPELINE") –
Feature input containing the vector geometries to map points to.

If set to "PIPELINE", then route_table_fpath must also be "PIPELINE" and the feature files will be pulled from the previous pipeline step.

Otherwise, provide either a single vector path or a list of vector paths. When a list is provided, route_table_fpath must also be a list with the same length, and each feature file is paired with the route table at the same list index.

Each feature file must have a column matching the connection_identifier_column parameter that maps each feature back to the starting points defined in the route_table.
routing_options (dict) – Mapping of routing-option names to dictionaries describing the cost, friction, barrier, and option-level multiplier inputs for each option. See RoutingOptionConfig for details.
drivers (dict, optional) – Optional driver-rule configuration keyed by routing option. See DriverConfig for details.
transition_costs (dict, optional) – Optional transition-cost configuration between routing options. See TransitionCostsConfig for details.
tracked_layers (list, optional) – List of dictionaries defining route-characterization layers. These layers do not influence the routing objective and are only summarized for output characterization. See TrackedLayer for details.
transmission_config (path-like or dict, optional) –
Dictionary of transmission cost configuration values, or path to JSON/JSON5 file containing this dictionary. The dictionary should have a subset of the following keys:
- base_line_costs
- iso_lookup
- iso_multipliers
- land_use_classes
- new_substation_costs
- power_classes
- power_to_voltage
- transformer_costs
- upgrade_substation_costs
- voltage_polarity_mult
- row_width
Each of these keys should point to another dictionary or path to JSON/JSON5 file containing a dictionary of configurations for each section. For the expected contents of each dictionary, see the default config. If None, values from the default config are used. By default, None.
save_paths (bool, default False) – Save outputs as a GeoPackage with path geometries when True. Defaults to False.
save_routing_layer (bool, default False) – Save Rust routing layer outputs to out_dir/extra_outputs when True. Defaults to False.
invalid_costs_block_routing (bool, optional) – Optional flag to treat any invalid cost values (<= 0) as impassable (i.e. no paths can ever cross this). If False, invalid cost values (<= 0) are set to a large value to simulate a strong but permeable “quasi-barrier”. By default, False.
connection_identifier_column (str, default "end_feat_id") – Column in the features_fpath data used to uniquely identify each feature. This column is also expected to be in the route_table input to map points to features. If a column name is given that does not exist in the data, an error will be raised. By default, "end_feat_id".
algorithm (str, default "bidirectional_long_range_dijkstra") – Routing algorithm implementation to use. Supported values are "astar", "long_range_astar", "long_range_dijkstra", "bidirectional_long_range_dijkstra", and "dijkstra". "astar" and "dijkstra" are in-memory implementations that do not respect the memory limit. Prefer a long-range option unless you know for a fact that your route computations will not need much memory and speed is very important to you. By default, "bidirectional_long_range_dijkstra".
memory_utilization_limit (float, default 0.9) – Fraction of system_mem_limit_gb to utilize for routing. Should be a value between 0 and 1. By default, 0.9.
system_mem_limit_gb (int or float, default 5) – Maximum amount of system memory (in GB) to utilize for routing. This is used in conjunction with memory_utilization_limit to determine the memory limit for routing. By default, 5 GB.

Returns:

str or None – Path to the output table if any routes were computed.