reVX.least_cost_xmission.least_cost_xmission.RegionalXmission

class RegionalXmission(cost_fpath, features_fpath, regions, region_identifier_column, resolution=128, xmission_config=None, min_line_length=0, tb_layer_name='transmission_barrier', iso_regions_layer_name='ISO_regions')

Bases: LeastCostXmission

Compute Least Cost tie-line paths and full transmission cap cost for all supply curve points to all possible connections within the region containing the supply curve point.

This class also offers a bit more flexibility than it’s base (LeastCostXmission):

• costs can be specified for region values of 0.

• the trans_gid, min_volt and max_volt columns are no longer required in the features input.

Parameters:

• cost_fpath (str) – Path to h5 file with cost rasters and other required layers.

• features_fpath (str) – Path to GeoPackage with transmission features. All features except substations will be dropped. This table must have a region_identifier column which matches one of the region_identifier ID’s in the regions GeoPackage.

• regions (str | GeoDataFrame) – Path to GeoPackage with regions or GeoDataFrame defining regions. This table must have the specified region_identifier column which matches the region_identifier column ID’s in the features_fpath GeoPackage.

• region_identifier_column (str) – Name of column in regions GeoPackage containing a unique identifier for each region.

• resolution (int, optional) – SC point resolution. By default, 128.

• xmission_config (str | dict | XmissionConfig, optional) – Path to Xmission config .json, dictionary of Xmission config .jsons, or preloaded XmissionConfig objects. By default, None.

• min_line_length (int | float, optional) – Minimum line length in km. By default, 0.

• tb_layer_name (str, default=:obj:BARRIER_H5_LAYER_NAME) – Name of transmission barrier layer in cost_fpath file. This layer defines the multipliers applied to the cost layer to determine LCP routing (but does not actually affect output costs). By default, BARRIER_H5_LAYER_NAME.

• iso_regions_layer_name (str, default=:obj:ISO_H5_LAYER_NAME) – Name of ISO regions layer in cost_fpath file. The layer maps pixels to ISO region ID’s (1, 2, 3, 4, etc.) . By default, ISO_H5_LAYER_NAME. least cost tie-line path, by default 100

Methods

process_least_cost_paths(cost_layers[, ...])	Find Least Cost Paths between all pairs of provided features for the given tie-line capacity class
process_sc_points(capacity_class, cost_layers)	Compute Least Cost Transmission for desired sc_points
run(cost_fpath, features_fpath, ...[, ...])	Find Least Cost Transmission connections between desired sc_points and substations in their region.

Attributes

end_features	GeoDataFrame containing the transmission features to compute the least cost paths to, starting from the start_indices (typically the centroid of the supply curve cell under consideration).
end_indices	Tuple (row, col) index or list of (row, col) indices in the cost array indicating the end location(s) to compute least cost paths to (typically transmission feature locations).
features	Table of features to compute paths for
sc_points	Table of supply curve points
sink_coords	Inf sink coordinates (row, col)
sink_tree	cKDTree for infinite sinks
start_indices	Tuple of (row_idx, col_idx) in the cost array indicating the start position of all paths to compute (typically, this is the centroid of the supply curve cell under consideration).
sub_lines_mapping	Series mapping substations to the transmission lines connected to each substation

classmethod run(cost_fpath, features_fpath, regions_fpath, region_identifier_column, capacity_class, cost_layers, resolution=128, xmission_config=None, min_line_length=0, sc_point_gids=None, clipping_buffer=1.05, tb_layer_name='transmission_barrier', barrier_mult=100, iso_regions_layer_name='ISO_regions', max_workers=None, simplify_geo=None, save_paths=False, radius=None, expand_radius=True, mp_delay=3, length_invariant_cost_layers=None, tracked_layers=None, length_mult_kind='linear', cell_size=90)

Find Least Cost Transmission connections between desired sc_points and substations in their region.

Parameters:

• cost_fpath (str) – Path to h5 file with cost rasters and other required layers

• features_fpath (str) – Path to GeoPackage with transmission features. All features except substations will be dropped. This table must have a region_identifier column which matches one of the region_identifier ID’s in the regions GeoPackage.

• regions (str | GeoDataFrame) – Path to GeoPackage with regions or GeoDataFrame defining regions. This table must have the specified region_identifier column which matches the region_identifier column ID’s in the features_fpath GeoPackage.

• region_identifier_column (str) – Name of column in regions GeoPackage containing a unique identifier for each region.

• capacity_class (str | int) – Capacity class of transmission features to connect supply curve points to.

• cost_layers (List[str]) – List of layers in H5 that are summed to determine total cost raster used for routing. Layer names may have curly brackets ({}), which will be filled in based on the capacity_class input (e.g. “tie_line_costs_{}MW”).

• resolution (int, optional) – SC point resolution. By default, 128.

• xmission_config (str | dict | XmissionConfig, optional) – Path to Xmission config .json, dictionary of Xmission config .jsons, or preloaded XmissionConfig objects. By default, None.

• min_line_length (int | float, optional) – Minimum line length in km. By default, 0.

• sc_point_gids (list, optional) – List of sc_point_gids to connect to. By default, None, which processes all points.

• clipping_buffer (float, optional) – Buffer to expand clipping radius by. By default, 1.05.

• tb_layer_name (str, default=:obj:BARRIER_H5_LAYER_NAME) – Name of transmission barrier layer in cost_fpath file. This layer defines the multipliers applied to the cost layer to determine LCP routing (but does not actually affect output costs). By default, BARRIER_H5_LAYER_NAME.

• barrier_mult (int, optional) – Multiplier on transmission barrier costs. By default, 100.

• iso_regions_layer_name (str, default=:obj:ISO_H5_LAYER_NAME) – Name of ISO regions layer in cost_fpath file. The layer maps pixels to ISO region ID’s (1, 2, 3, 4, etc.) . By default, ISO_H5_LAYER_NAME. least cost tie-line path, by default 100

• max_workers (int, optional) – Number of workers to use for processing. If 1 run in serial, if None use all available cores. By default, None.

• simplify_geo (float | None, optional) – If float, simplify geometries using this value.

• save_paths (bool, optional) – Flag to save spur line path as a multi-line geometry. By default, False.

• radius (None | int, optional) – Force clipping radius. Substations beyond this radius will not be considered for connection with supply curve point. If None, no radius is forced, and connections to all available transmission features are computed. By default, None.

• expand_radius (bool, optional) – Option to expand radius to include at least one connection feature. Has no effect if radius=None. By default, True.

• mp_delay (float, optional) – Delay in seconds between starting multi-process workers. Useful for reducing memory spike at working startup.

• length_invariant_cost_layers (List[str] | None, optional) – List of layers in H5 to be added to the ‘base’ greenfield cost raster. The costs specified by these layers are not scaled with distance traversed across the cell (i.e. fixed one-time costs for crossing these cells).

• tracked_layers (dict, optional) – Dictionary mapping layer names to strings, where the strings are numpy methods that should be applied to the layer along the LCP. For example, tracked_layers={'layer_1': 'mean', 'layer_2': 'max} would report the average of layer_1 values along the least cost path and the max of layer_2 values along the least cost path. Examples of numpy methods (non-exhaustive):

  • mean

  • max

  • min

  • mode

  • median

  • std

  By default, None, which does not track any extra layers.

• length_mult_kind ({“step”, “linear”}, default=”linear”) – Type of length multiplier calcualtion. “step” computes length multipliers using a step function, while “linear” computes the length multiplier using a linear interpolation between 0 amd 10 mile spur-line lengths. By default, "linear".

• cell_size (int, optional) – Side length of each cell, in meters. Cells are assumed to be square. By default, CELL_SIZE.

Returns:

least_costs (pandas.DataFrame | gpd.DataFrame) – Least cost connections between all supply curve points and the substations in their region with the given capacity class.

property end_features

GeoDataFrame containing the transmission features to compute the least cost paths to, starting from the start_indices (typically the centroid of the supply curve cell under consideration).

Returns:

pandas.DataFrame

property end_indices

Tuple (row, col) index or list of (row, col) indices in the cost array indicating the end location(s) to compute least cost paths to (typically transmission feature locations). Paths are computed from the start_indices (typically the centroid of the supply curve cell under consideration) to each of the individual pairs of end_indices.

Returns:

tuple | list

property features

Table of features to compute paths for

Returns:

pandas.DataFrame

process_least_cost_paths(cost_layers, barrier_mult=100, indices=None, max_workers=None, save_paths=False, length_invariant_cost_layers=None, tracked_layers=None, cell_size=90)

Find Least Cost Paths between all pairs of provided features for the given tie-line capacity class

Parameters:

• cost_layers (List[str]) – List of layers in H5 that are summed to determine total costs raster used for routing. Costs and distances for each individual layer are also reported (e.g. wet and dry costs). deteremining path using main cost layer.

• barrier_mult (int, optional) – Transmission barrier multiplier, used when computing the least cost tie-line path, by default 100

• indices (iterable, optonal) – Indices of the transmission features input that should be processed. By default None, which process all transmission features.

• max_workers (int, optional) – Number of workers to use for processing, if 1 run in serial, if None use all available cores, by default None

• save_paths (bool, optional) – Flag to save least cost path as a multi-line geometry, by default False

• length_invariant_cost_layers (List[str] | None, optional) – List of layers in H5 to be added to the cost raster. The costs specified by these layers are not scaled with distance traversed across the cell (i.e. fixed one-time costs for crossing these cells).

• tracked_layers (dict, optional) – Dictionary mapping layer names to strings, where the strings are numpy methods that should be applied to the layer along the LCP. For example, tracked_layers={'layer_1': 'mean', 'layer_2': 'max} would report the average of layer_1 values along the least cost path and the max of layer_2 values along the least cost path. Examples of numpy methods (non-exhaustive):

  • mean

  • max

  • min

  • mode

  • median

  • std

  By default, None, which does not track any extra layers.

• cell_size (int, optional) – Side length of each cell, in meters. Cells are assumed to be square. By default, CELL_SIZE.

Returns:

least_cost_paths (pandas.DataFrame | gpd.GeoDataFrame) – DataFrame of lengths and costs for each path or GeoDataFrame of length, cost, and geometry for each path

process_sc_points(capacity_class, cost_layers, sc_point_gids=None, nn_sinks=2, clipping_buffer=1.05, barrier_mult=100, max_workers=None, save_paths=False, radius=None, expand_radius=True, mp_delay=3, simplify_geo=None, length_invariant_cost_layers=None, tracked_layers=None, length_mult_kind='linear', cell_size=90)

Compute Least Cost Transmission for desired sc_points

Parameters:

• capacity_class (str | int) – Capacity class of transmission features to connect supply curve points to

• cost_layers (List[str]) – List of layers in H5 that are summed to determine total costs raster used for routing. Costs and distances for each individual layer are also reported (e.g. wet and dry costs). Layer names may have curly brackets ({}), which will be filled in based on the capacity class input (e.g. “tie_line_costs_{}MW”).

• sc_point_gids (list, optional) – List of sc_point_gids to connect to, by default connect to all

• nn_sinks (int, optional) – Number of nearest neighbor sinks to use for clipping radius calculation, by default 2

• clipping_buffer (float, optional) – Buffer to expand clipping radius by, by default 1.05

• barrier_mult (int, optional) – Transmission barrier multiplier, used when computing the least cost tie-line path, by default 100

• max_workers (int, optional) – Number of workers to use for processing, if 1 run in serial, if None use all available cores, by default None

• save_paths (bool, optional) – Flag to return least cost paths as a multi-line geometry, by default False

• radius (None | int, optional) – Force clipping radius. Trasmission features beyond this radius will not be considered for connection with supply curve point. If None, no radius is forced, and connections to all available transmission features are computed. By default, None.

• expand_radius (bool, optional) – Option to expand radius to include at least one connection feature. Has no effect if radius=None. By default, True.

• mp_delay (float, optional) – Delay in seconds between starting multi-process workers. Useful for reducing memory spike at working startup.

• simplify_geo (float | None, optional) – If float, simplify geometries using this value

• length_invariant_cost_layers (List[str] | None, optional) – List of layers in H5 to be added to the cost raster. The costs specified by these layers are not scaled with distance traversed across the cell (i.e. fixed one-time costs for crossing these cells).

• tracked_layers (dict, optional) – Dictionary mapping layer names to strings, where the strings are numpy methods that should be applied to the layer along the LCP. For example, tracked_layers={'layer_1': 'mean', 'layer_2': 'max} would report the average of layer_1 values along the least cost path and the max of layer_2 values along the least cost path. Examples of numpy methods (non-exhaustive):

  • mean

  • max

  • min

  • mode

  • median

  • std

  By default, None, which does not track any extra layers.

• length_mult_kind ({“step”, “linear”}, default=”linear”) – Type of length multiplier calcualtion. “step” computes length multipliers using a step function, while “linear” computes the length multiplier using a linear interpolation between 0 amd 10 mile spur-line lengths. By default, "linear".

• cell_size (int, optional) – Side length of each cell, in meters. Cells are assumed to be square. By default, CELL_SIZE.

Returns:

least_costs (pandas.DataFrame | gpd.GeoDataFrame) – Least cost connections between all supply curve points and the transmission features with the given capacity class that are within “nn_sink” nearest infinite sinks

property sc_points

Table of supply curve points

Returns:

gpd.GeoDataFrame

property sink_coords

Inf sink coordinates (row, col)

Returns:

ndarray

property sink_tree

cKDTree for infinite sinks

Returns:

cKDTree

property start_indices

Tuple of (row_idx, col_idx) in the cost array indicating the start position of all paths to compute (typically, this is the centroid of the supply curve cell under consideration). Paths will be computed from this start location to each of the end_indices, which are also locations in the cost array (typically transmission feature locations).

Returns:

tuple

property sub_lines_mapping

Series mapping substations to the transmission lines connected to each substation

Returns:

pandas.Series