Spatial structure and constraints
Space is part of the model, not a post-processing step (notes/adr/0003). The compiled matrix is
fragment-level; blocks are the runtime aggregate view that patch metrics and spatial constraints
operate on. Spatial structure enters through a block topology: an undirected adjacency edgelist
src_block,dst_block,distance_m.
Patch metrics
ws4.patch.metrics groups the disturbed blocks of a year into connected patches over the topology
and reports:
the patch count;
the mean patch area;
the largest opening (the maximum patch area);
the size-class distribution (the default breaks are 5, 10, and 50 hectares).
The simulator writes these to patch_metrics.csv when it is given a topology:
# Python API
Simulator.from_dataset(dataset).run(schedule_csv, years, out_dir, topology_csv=topology)
Patch accounts
A patch account describes the size distribution of connected patches over the topology, for a
patch criteria attribute and a threshold (ws4.patch.accounts). A block joins a patch when
its criterion value exceeds the threshold, and its contribution to the patch area is the criterion
value times its block area (a half disturbed block contributes half its area). For each size class
the account reports five sub-accounts:
Sub-account |
Meaning |
|---|---|
|
The patch area in the size class, in hectares. |
|
The area in the class as a percentage of the total patch area. |
|
The mean compactness of the patches in the class, 0 to 100 (100 is a circle). |
|
The number of patches in the class. |
|
A flag that draws the average patch size toward the class; its value mimics |
The criteria value per block comes from a feature curve (Simulator.block_criteria), so the
patch membership changes over time as stands age and are treated. When a topology and patch
accounts are given, the simulator writes patch_accounts.csv with one row per period.
from ws4.patch.accounts import PatchAccount
account = PatchAccount(name="patch.disturbance", criteria="feature.Seral.young", threshold=0.5)
Simulator.from_dataset(dataset).run(
schedule, years, out_dir, topology_csv=topology, patch_accounts=[account]
)
The topology loader (load_patch_edges) accepts the established columns
(BLOCK1,BLOCK2,DISTANCE,LENGTH) and drops the -9999 boundary sentinel, as well as the WS4
columns (src_block,dst_block,distance_m).
Constraints
ws4.patch.constraints reports two kinds of violation:
opening_violationsPatches whose area exceeds a maximum opening size.
green_up_violationsAdjacent blocks disturbed within a green-up interval.
core_area_violationsPatches whose core area is below a minimum (see below).
spatial_penalty combines them into a single penalty, and schedule_years splits a schedule into
per-year blocks and each block’s first disturbance year. The simulator writes the violations to
spatial_violations.csv:
Column |
Meaning |
|---|---|
|
|
|
The year of the violation. |
|
The patch area (an opening violation), else 0. |
|
The violated limit (maximum opening area, or the green-up interval). |
|
The adjacent blocks (a green-up violation), else -1. |
|
The gap between the two disturbances (a green-up violation), else 0. |
Core-area rule
A core-area rule requires interior habitat, not just disturbed area. The core area of a patch
removes a strip of buffer_m metres around its perimeter
(core = area - perimeter * buffer + pi * buffer**2, clipped at zero), so a patch of the same area
with a longer, more dendritic edge has less core. core_area_violations reports each patch whose
core is below min_core_area_ha; the optimizer adds the shortfall to its penalty
(OptimizeConfig.core_buffer_m / min_core_area_ha or --core-buffer-m /
--min-core-area-ha).
Edge contrast
An edge contrast account measures the juxtaposition of one forest type beside another (the established edge-target API). For each shared edge it takes the boundary where one side matches the first attribute and the other matches the second, weighted by the per-unit values and the shared edge length, and sums it into a named account:
# edges.csv
account,attribute1,attribute2,factor
feature.Edge.OldYoung,feature.Seral.old,feature.Seral.young,1
Adjacent blocks of the same type contribute nothing; a hard boundary between two contrasting types
contributes the shared edge length. The per-block attribute values come from feature curves
(Simulator.block_criteria), so the account changes over time. The simulator writes
edge_metrics.csv and adds the edge accounts to account_values.csv (so the optimizer can target
them, for example a minimum on feature.Edge.OldYoung). load_edge_elements loads the
specifications from CSV.
Spread connectivity
A spread-connectivity account measures how fragmented the fuel body a fire could run through is
(ws4.spread.accounts). It exists because the patch accounts can point the wrong way: on the TSA23
bridge instance a wind-perpendicular barrier burned least of three equal-area patterns while having the
largest large-patch share. A patch target penalizes the arrangement that works.
The account needs a block topology and a table of block coordinates (block,x,y, in metres),
because the topology carries distances but no bearings. Each account names a criterion, a bearing
(degrees clockwise from north — the direction the fire travels, which is the wind direction) and a
tolerance. An edge lying within the tolerance of the bearing and no longer than search_distance
is fast; a treated block transmits nothing. The fast edges are then traversed as an undirected
graph: a fire goes around an obstacle as well as through it, so what confines it is the connected fuel
body, not a one-way corridor.
# spread.yaml
accounts:
- name: spread.ft
criteria: product.Treated.managed.FT
bearing: 225
tolerance: 60
search_distance: null
Two sub-accounts, both lower-is-better and both in hectares:
Sub-account |
Meaning |
|---|---|
|
The area of the largest connected set of untreated blocks over the fast edges: the fuel body a fire can wander through from one ignition. |
|
The area-weighted mean compartment area, |
The account also reports TOTAL.area and TOTAL.blocks for the untreated set. The landscape is
every block with a coordinate, not only the blocks the criterion mentions: a product criterion holds
only the blocks that produced in the period, and every other block is untreated fuel.
The simulator also writes spread_membership.csv beside the metrics when the same inputs are given.
It has one row per untreated block and offset: offset,account,compartment,compartment_class,block,area_ha,compartment_area_ha.
Components are numbered from the largest, so compartment 0 is the fuel body a fire can wander through
from one ignition; compartment_class is the component area class (0–10, 10–50, 50–150, 150+ ha).
The web map serves this file as the Spread compartments layer, with treated breaks drawn
separately; it is a model layer, not a source attribute.
from ws4.spread.accounts import SpreadAccount
account = SpreadAccount(
name="spread.ft", criteria="product.Treated.managed.FT", bearing=225, tolerance=60
)
Simulator.from_dataset(dataset).run(
schedule,
years,
out_dir,
topology_csv=topology,
spread_accounts=[account],
block_coordinates=coordinates,
)
What the measure can and cannot say. Direction lives in the cone (which edges are fast), not in the traversal. A full-span band along the wind fragments the fuel body just as much as one across it, which the synthetic oracle pins deliberately. Separating those two needs anisotropic spread rates and a burn duration — a fire model, not an account.
On the TSA23 bridge instance the largest compartment orders the three equal-area patterns as the fire model did at its original 177,088 ha treatment (82,874 / 105,020 / 196,767 ha against 19,640 / 19,870 / 20,298 ha burned). That comparison does not survive a matched footprint. When the fire model is run on the ~54,000 ha WS4 can actually treat, the ranking flips across seeds and the largest mean gap (0.38%) is far inside the seed noise (15%). The account is therefore a fragmentation measure with no demonstrated relationship to this fire model at the intervention WS4 can represent; the report is notes/reports/p16-bridge-matched.md. A bounded, 20%-treated study footprint does not restore the ordering either: there the largest compartment reads 23 / 94 / 6 ha at a 60° cone and 49 / 105 / 10 ha at 90° (barrier / clumped / random), so no cone width produces barrier < clumped < random. The ordering of the compartment itself holds from a 60° to a 90° cone, with a magnitude that depends on how near the cone sits to the percolation threshold.
Enforcement in the optimizer
The optimizer adds a weighted spatial penalty to its objective (OptimizeConfig.spatial_weight)
when a topology and a limit are given, so a searched schedule is pushed away from violations. The
penalty is disabled only by the explicit allow_spatial_override flag (--spatial-override on
the command line).
API
- ws4.patch.metrics.load_topology(csv_path: Path) DataFrame[source]
Load a proximal topology edgelist:
src_block,dst_block,distance_m.The edges are treated as undirected.
- Parameters:
csv_path (Path) – The topology CSV.
- Returns:
pandas.DataFrame – The edge list.
- ws4.patch.metrics.connected_patches(selected: Iterable[int], edges: Iterable[tuple[int, int]]) list[set[int]][source]
Group selected blocks into connected patches.
- Parameters:
selected (iterable of int) – The selected block ids.
edges (iterable of (int, int)) – The adjacency edges (undirected).
- Returns:
list of set of int – One set of block ids per patch.
- ws4.patch.metrics.patch_size_classes(patches: Sequence[set[int]], block_area: Mapping[int, float], breaks: Sequence[float]) dict[str, int][source]
Count patches by area size class.
- Parameters:
patches (sequence of set of int) – The patches, from
connected_patches().block_area (mapping of int to float) – The area of each block, in hectares.
breaks (sequence of float) – The upper bounds of the classes, ascending. A patch whose area is at or below a break belongs to that class; a patch above the last break is
"over".
- Returns:
dict of str to int – The patch count per class. Class names are
"le<b>"for a breakband"over"for the last class.
- ws4.patch.metrics.patch_metrics(selected: Iterable[int], edges: Iterable[tuple[int, int]], block_area: Mapping[int, float], breaks: Sequence[float]) dict[str, float][source]
Compute patch count, mean size, and the size-class distribution.
- Parameters:
selected (iterable of int) – The selected block ids.
edges (iterable of (int, int)) – The adjacency edges.
block_area (mapping of int to float) – The area of each block.
breaks (sequence of float) – The size-class upper bounds.
- Returns:
dict of str to float –
patch_count,mean_patch_area,max_patch_area(the largest opening), and one entry per size class.
- ws4.patch.constraints.openings_by_year(selected_by_year: Mapping[int, Iterable[int]], edges: Iterable[tuple[int, int]], block_area: Mapping[int, float]) dict[int, float][source]
Return the largest opening area per year.
- Parameters:
selected_by_year (mapping of int to iterable of int) – The blocks disturbed in each year.
edges (iterable of (int, int)) – The adjacency edges (undirected).
block_area (mapping of int to float) – The area of each block, in hectares.
- Returns:
dict of int to float – The largest connected opening area in each year that had a disturbance.
- ws4.patch.constraints.opening_violations(selected_by_year: Mapping[int, Iterable[int]], edges: Iterable[tuple[int, int]], block_area: Mapping[int, float], max_opening_ha: float) list[dict[str, object]][source]
Return one record per patch whose area exceeds the maximum opening size.
- Parameters:
selected_by_year (mapping of int to iterable of int) – The blocks disturbed in each year.
edges (iterable of (int, int)) – The adjacency edges.
block_area (mapping of int to float) – The area of each block.
max_opening_ha (float) – The maximum permitted opening area.
- Returns:
list of dict – Each record has
kind("opening"),year,area_ha, andlimit.
- ws4.patch.constraints.green_up_violations(disturbance_years: Mapping[int, Sequence[int]], edges: Iterable[tuple[int, int]], min_years: int) list[dict[str, object]][source]
Return one record per adjacent pair disturbed within the green-up interval.
A block may be disturbed several times (rotations). A pair is a violation when the closest of their disturbance years is within the interval, and the record’s
yearsis that closest gap.- Parameters:
disturbance_years (mapping of int to sequence of int) – The years each block is disturbed.
edges (iterable of (int, int)) – The adjacency edges (undirected).
min_years (int) – The minimum number of years between disturbances of adjacent blocks.
- Returns:
list of dict – Each record has
kind("green_up"),block_a,block_b,years, andlimit.
- ws4.patch.constraints.spatial_penalty(selected_by_year: Mapping[int, Iterable[int]], disturbance_years: Mapping[int, Sequence[int]], edges: Iterable[tuple[int, int]], block_area: Mapping[int, float], max_opening_ha: float | None, min_green_up_years: int | None) float[source]
Return a penalty for the spatial violations of a schedule.
The penalty is the summed excess opening area plus the summed green-up shortfall, so a schedule that respects the constraints scores zero.
- Parameters:
selected_by_year (mapping of int to iterable of int) – The blocks disturbed in each year.
disturbance_years (mapping of int to sequence of int) – The years each block is disturbed.
edges (iterable of (int, int)) – The adjacency edges.
block_area (mapping of int to float) – The area of each block.
max_opening_ha (float or None) – The maximum opening size, or None to skip the opening check.
min_green_up_years (int or None) – The green-up interval, or None to skip the green-up check.
- Returns:
float – The penalty; zero when the schedule respects every active constraint.
- ws4.patch.constraints.core_area_violations(selected_by_year: Mapping[int, Iterable[int]], edges: Iterable[tuple[int, int, float]], block_area: Mapping[int, float], buffer_m: float, min_core_area_ha: float) list[dict[str, object]][source]
Return one record per patch whose core area is below the minimum.
The core area removes a strip of
buffer_mmetres around the patch perimeter (seews4.patch.metrics.core_area()), so a core-area rule keeps interior habitat, not just the disturbed area.- Parameters:
selected_by_year (mapping of int to iterable of int) – The blocks disturbed in each year.
edges (iterable of (int, int, float)) – The adjacency edges
(src, dst, shared_length).block_area (mapping of int to float) – The area of each block, in hectares.
buffer_m (float) – The buffer width, in metres.
min_core_area_ha (float) – The minimum core area, in hectares.
- Returns:
list of dict – Each record has
kind("core_area"),year,area_ha(the core), andlimit.
- ws4.patch.constraints.core_area_penalty(selected_by_year: Mapping[int, Iterable[int]], edges: Iterable[tuple[int, int, float]], block_area: Mapping[int, float], buffer_m: float, min_core_area_ha: float) float[source]
Return the summed core-area shortfall of a schedule.
- Parameters:
selected_by_year (mapping of int to iterable of int) – The blocks disturbed in each year.
edges (iterable of (int, int, float)) – The adjacency edges
(src, dst, shared_length).block_area (mapping of int to float) – The area of each block, in hectares.
buffer_m (float) – The buffer width, in metres.
min_core_area_ha (float) – The minimum core area, in hectares.
- Returns:
float – The summed shortfall; zero when every patch’s core is at least the minimum.
- ws4.patch.constraints.edge_contrast(values1: Mapping[int, float], values2: Mapping[int, float], edges: Iterable[tuple[int, int, float]], factor: float = 1.0) float[source]
Return the contrast edge between two attributes over an adjacency.
Following the established edge metric, the contrast is the shared edge where one side matches the first attribute and the other side matches the second, weighted by the per-unit values and the shared edge length. Formally, an edge
(A, B)contributesabs(v1(A)*v2(B) - v1(B)*v2(A)) * shared_length: it is nonzero exactly when the two sides differ in type. A scalefactorweights some edge types more heavily.- Parameters:
values1 (mapping of int to float) – The per-block value of the first attribute.
values2 (mapping of int to float) – The per-block value of the second attribute.
edges (iterable of (int, int, float)) – The adjacency edges
(src, dst, shared_length).factor (float, optional) – A scaling factor applied to the difference.
- Returns:
float – The contrast edge (a length), zero when no adjacent pair contrasts.
- ws4.patch.constraints.schedule_years(schedule: Sequence[tuple[int, int]]) tuple[dict[int, set[int]], dict[int, list[int]]][source]
Split a schedule into per-year blocks and each block’s disturbance years.
A block may be disturbed more than once (rotations), so the second result maps each block to every year it is disturbed, sorted.
- Parameters:
schedule (sequence of (int, int)) –
(block_id, year)pairs.- Returns:
tuple of (dict, dict) – The blocks disturbed in each year, and the disturbance years per block.
- ws4.patch.metrics.core_area(area_ha: float, perimeter_m: float, buffer_m: float) float[source]
Return the core area of a patch: its area beyond a buffer from the edge.
The core is the patch area with a strip of width
buffer_mremoved around the perimeter, socore = area - perimeter * buffer + pi * buffer**2(the last term restores the rounded corners). The result is clipped at zero.- Parameters:
area_ha (float) – The patch area, in hectares.
perimeter_m (float) – The patch perimeter, in metres.
buffer_m (float) – The buffer width, in metres.
- Returns:
float – The core area, in hectares (zero when the buffer consumes the patch).
- ws4.patch.metrics.patch_core_areas(patches: Sequence[set[int]], edges: Iterable[tuple[int, int, float]], block_area: Mapping[int, float], buffer_m: float) list[dict[str, float]][source]
Return each patch’s area, perimeter, and core area.
- Parameters:
patches (sequence of set of int) – The patches.
edges (iterable of (int, int, float)) – The adjacency edges
(src, dst, shared_length).block_area (mapping of int to float) – The area of each block, in hectares.
buffer_m (float) – The buffer width, in metres.
- Returns:
list of dict – One record per patch, with
area_ha,perimeter_m, andcore_area_ha.
- ws4.patch.metrics.patch_perimeter(patch: Iterable[int], edges: Iterable[tuple[int, int, float]]) float[source]
Return a patch’s boundary length (edges with one member end).
- Parameters:
patch (iterable of int) – The patch’s block ids.
edges (iterable of (int, int, float)) – The adjacency edges
(src, dst, shared_length).
- Returns:
float – The summed length of the edges on the patch boundary.
- ws4.patch.edge.load_edge_elements(path: Path) tuple[EdgeElement, ...][source]
Load edge elements from a CSV (
account,attribute1,attribute2,factor).- Parameters:
path (Path) – The edge-element CSV. The
factorcolumn is optional (default 1).- Returns:
tuple of EdgeElement – The edge elements, in file order.
- ws4.patch.edge.edge_values(elements: Sequence[EdgeElement], edges: Sequence[tuple[int, int, float]], criteria: Mapping[str, Mapping[int, float]]) list[dict[str, object]][source]
Return one record per edge element for a single period.
- Parameters:
elements (sequence of EdgeElement) – The edge elements.
edges (sequence of (int, int, float)) – The adjacency edges
(src, dst, shared_length).criteria (mapping of str to mapping of int to float) – The per-block criterion values, keyed by feature label.
- Returns:
list of dict – One record per element, with
accountandvalue.
- class ws4.patch.edge.EdgeElement(account: str, attribute1: str, attribute2: str, factor: float = 1.0)[source]
One edge contrast specification (
addEdgeElement).- account
The account the contrast is summed into.
- Type:
str
- attribute1
The first feature label.
- Type:
str
- attribute2
The second feature label.
- Type:
str
- factor
A scale factor applied to the difference.
- Type:
float
- ws4.patch.accounts.load_patch_edges(csv_path: Path) list[tuple[int, int, float]][source]
Load a proximal topology edge list, accepting the established column names.
The established file is
BLOCK1,BLOCK2,DISTANCE,LENGTH; the sentinel block-9999marks a boundary and is dropped. WS4’s names aresrc_block,dst_blockwithdistance_morlength_m.- Parameters:
csv_path (Path) – The topology CSV.
- Returns:
list of (int, int, float) – The undirected edges with their shared boundary length.
- ws4.patch.accounts.size_class_labels(size_classes: Sequence[float]) tuple[str, ...][source]
Return the size-class labels, such as
('0_50', '50_150', ..., '2500_9999999').- Parameters:
size_classes (sequence of float) – The upper bounds, ascending.
- Returns:
tuple of str – One label per class.
- ws4.patch.accounts.patch_account_values(account: PatchAccount, values: Mapping[int, float], edges: Sequence[tuple[int, int, float]], block_area: Mapping[int, float]) dict[str, float][source]
Compute one period’s patch sub-account values.
- Parameters:
account (PatchAccount) – The account definition.
values (mapping of int to float) – The criterion value per block, in
[0, 1].edges (sequence of (int, int, float)) – The adjacency edges
(src, dst, shared_length).block_area (mapping of int to float) – The area of each block.
- Returns:
dict of str to float – The sub-account values, keyed
"<class>.<sub>"plus"TOTAL.area"and"TOTAL.frequency".
- class ws4.patch.accounts.PatchAccount(name: str, criteria: str, threshold: float = 0.0, size_classes: tuple[float, ...] = (50.0, 150.0, 250.0, 2500.0, inf), search_distance: float | None = 0.0)[source]
A patch account definition.
- name
The account name.
- Type:
str
- criteria
The feature label used as the patch membership criterion.
- Type:
str
- threshold
The criterion value a block must exceed to join a patch.
- Type:
float
- size_classes
The size-class upper bounds, in hectares, ascending. The last may be
inf.- Type:
tuple of float
- search_distance
The topology search distance, in metres: only edges whose endpoints are no further apart than it join a patch. The default
0.0joins only blocks that literally touch (their polygons share a vertex); None considers every edge in the topology.- Type:
float or None
- class ws4.patch.accounts.PatchLedger(accounts: ~collections.abc.Sequence[~ws4.patch.accounts.PatchAccount], edges: ~collections.abc.Sequence[tuple[int, int, float, float]], block_area: ~collections.abc.Mapping[int, float], period_width: int = 1, membership: bool = False, _records: list[dict[str, float]] = <factory>, _components: list[~ws4.patch.accounts.PatchComponent] = <factory>)[source]
Accumulate patch accounts over a run.
- Parameters:
accounts (sequence of PatchAccount) – The patch account definitions.
edges (sequence of (int, int, float, float)) – The adjacency edges
(src, dst, shared_length, distance). Each account keeps only the edges within its ownsearch_distance.block_area (mapping of int to float) – The area of each block.
period_width (int, optional) – The planning-period width, in years.
membership (bool, optional) – When True, also keep which blocks formed which patch, and write it beside the accounts. A run wants it — the membership is what a component comparison reads — while a search prices the accounts alone, and keeping it costs a second pass over the topology a period.
- record(year: int, criteria: Mapping[str, Mapping[int, float]]) None[source]
Record one period’s patch accounts.
- Parameters:
year (int) – The year.
criteria (mapping of str to mapping of int to float) – The criterion values per block, keyed by the criteria feature label.
- frame() DataFrame[source]
Return the patch accounts as a frame, one row per period.
- Returns:
pandas.DataFrame – One row per accounted period, with the patch sub-account columns.
- membership_frame() DataFrame[source]
Return the patch membership: one row per member block of every patch.
- Returns:
pandas.DataFrame –
period,year,account,class,patch,blockandarea_ha, where a patch’s area is repeated on each of its members’ rows. The patch ids are WS4’s own and mean nothing to another tool: what two listings are compared on is the partition, not the labels.
- class ws4.spread.accounts.SpreadAccount(name: str, criteria: str, threshold: float = 0.5, bearing: float = 225.0, tolerance: float = 60.0, search_distance: float | None = 500.0)[source]
A spread-connectivity account definition.
- name
The account name, used as the prefix of its sub-account cells.
- Type:
str
- criteria
The criterion label marking the treated blocks: a feature or a product, resolved the way a patch criterion is. A block is treated when its value exceeds
threshold.- Type:
str
- threshold
The criterion value a block must exceed to count as treated (default 0.5, a block at least half covered by the criterion).
- Type:
float
- bearing
The spread direction, in degrees clockwise from north — the direction the fire travels, which is the wind direction. Default 225, the bridge test’s wind.
- Type:
float
- tolerance
How far off the bearing an edge may lie and still count as a fast edge, in degrees (default 60, a cone 60 degrees wide each side of the bearing). At 90 every edge is fast and the cone stops selecting; the oracle pins what that does to the measure.
- Type:
float
- search_distance
The longest hop an edge may span, in metres; None considers every edge (default 500, a generous hop for a block topology whose edges are shared boundaries).
- Type:
float | None
- ws4.spread.accounts.spread_account_values(account: SpreadAccount, values: Mapping[int, float], edges: Sequence[tuple[int, int, float]], points: Mapping[int, tuple[float, float]], block_area: Mapping[int, float], membership: list[dict[str, object]] | None = None) dict[str, float][source]
Compute one period’s spread-connectivity sub-accounts.
- Parameters:
account (SpreadAccount) – The account definition.
values (mapping of int to float) – The criterion value per block; a block is treated when it exceeds the threshold. A block absent from the mapping has no criterion value and is untreated — which matters for a product criterion, where only the blocks that produced in the period appear.
edges (sequence of (int, int, float)) – The topology edges
(src, dst, distance_m).points (mapping of int to tuple of float) – The
(x, y)centroid of each block, in metres, which is where an edge’s bearing is read.block_area (mapping of int to float) – The area of each block, in hectares.
membership (list of dict or None, optional) – When given, receives one row per untreated block: the account, compartment index, compartment class and area, block, and block area. The largest compartment is index 0.
- Returns:
dict of str to float –
largest_componentandpercolation_reach, keyed by the account name, plusTOTAL.areaandTOTAL.blocksfor the untreated set.
- ws4.spread.accounts.compartment_class(area: float) str[source]
Return the size class of a spread compartment, in hectares.
- Parameters:
area (float) – The compartment area.
- Returns:
str –
0_10,10_50,50_150or150_9999999.
- ws4.spread.accounts.transmitting_edges(edges: Sequence[tuple[int, int, float]], points: Mapping[int, tuple[float, float]], account: SpreadAccount) list[tuple[int, int]][source]
Return the topology edges inside the spread cone, as undirected pairs.
An edge transmits when it spans no more than the account’s search distance and lies within the account’s tolerance of the spread direction, measured without regard to which end is which. The direction selects whether an edge is fast; the traversal over the selected edges is undirected, because a fire goes around an obstacle as well as through it.
- Parameters:
edges (sequence of (int, int, float)) – The topology edges
(src, dst, distance_m).points (mapping of int to tuple of float) – The
(x, y)centroid of each block, in metres.account (SpreadAccount) – The account definition: its bearing, tolerance and search distance.
- Returns:
list of (int, int) – The transmitting edges, as
(src, dst)pairs in their input order.
- ws4.spread.accounts.load_spread_accounts(path: Path) tuple[SpreadAccount, ...][source]
Load spread-connectivity account definitions from YAML.
The file is a mapping with an
accountslist; each entry hasname,criteria, and any ofthreshold,bearing,toleranceandsearch_distance. Asearch_distanceofnullconsiders every edge.- Parameters:
path (Path) – The YAML file.
- Returns:
tuple of SpreadAccount – The definitions.
- ws4.spread.accounts.load_block_coordinates(path: Path) dict[int, tuple[float, float]][source]
Load block centroids from a CSV, in metres.
The table carries a block id and an
xand aycolumn; the names are matched loosely, so a table withBLOCK,X,Yorblock_id,easting,northingreads the same way.- Parameters:
path (Path) – The CSV file.
- Returns:
dict of int to tuple of float – The
(x, y)centroid per block.- Raises:
ValueError – When the table has no block id,
xorycolumn.