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

area

The patch area in the size class, in hectares.

size

The area in the class as a percentage of the total patch area.

shape

The mean compactness of the patches in the class, 0 to 100 (100 is a circle).

frequency

The number of patches in the class.

attractor

A flag that draws the average patch size toward the class; its value mimics size.

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_violations

Patches whose area exceeds a maximum opening size.

green_up_violations

Adjacent blocks disturbed within a green-up interval.

core_area_violations

Patches 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

kind

opening, green_up, or core_area.

year

The year of the violation.

area_ha

The patch area (an opening violation), else 0.

limit

The violated limit (maximum opening area, or the green-up interval).

block_a, block_b

The adjacent blocks (a green-up violation), else -1.

years

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

largest_component

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.

percolation_reach

The area-weighted mean compartment area, sum(area**2) / sum(area): what a random hectare sees.

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 break b and "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, and limit.

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 years is 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, and limit.

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_m metres around the patch perimeter (see ws4.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), and limit.

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) contributes abs(v1(A)*v2(B) - v1(B)*v2(A)) * shared_length: it is nonzero exactly when the two sides differ in type. A scale factor weights 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_m removed around the perimeter, so core = 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, and core_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 factor column 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 account and value.

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 -9999 marks a boundary and is dropped. WS4’s names are src_block,dst_block with distance_m or length_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.0 joins 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 own search_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, block and area_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.

write(out_dir: Path) → None[source]

Write patch_accounts.csv, and patch_membership.csv when it was kept, into a run.

Parameters:

out_dir (Path) – The run directory; it is created when missing.

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_component and percolation_reach, keyed by the account name, plus TOTAL.area and TOTAL.blocks for 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_150 or 150_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 accounts list; each entry has name, criteria, and any of threshold, bearing, tolerance and search_distance. A search_distance of null considers 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 x and a y column; the names are matched loosely, so a table with BLOCK,X,Y or block_id,easting,northing reads 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, x or y column.