optiwindnet.interarraylib

Module Contents

class optiwindnet.interarraylib.TerseLinks

Bases: collections.abc.Sequence[int]

Compact links plus the metadata needed to reconstruct their graph.

RADIAL and BRANCHED values use one parent target per non-root node. RINGED values use the flattened route representation. A topology value represents S; a routeset value additionally carries the clone mapping needed to reproduce G against its location graph. Either scope can be bound to an exact location geometry with nodeset_digest.

links: tuple[int, Ellipsis]

topology: optiwindnet.types.Topology

scope: LinkScope

T: int

R: int

B: int = 0

C: int = 0

D: int = 0

clone2prime: tuple[int, Ellipsis] = ()

nodeset_digest: bytes | None = None

__post_init__()

__len__() → int

__iter__() → collections.abc.Iterator[int]

__getitem__(index)

__array__(dtype=None, copy=None) → numpy.ndarray

__repr__() → str

tolist() → list[int]

Return the encoded links as a plain list.

to_dict() → dict[str, Any]

Return a versioned representation suitable for JSON serialization.

classmethod from_dict(data: collections.abc.Mapping[str, Any]) → TerseLinks

Restore a value created by to_dict().

classmethod from_topology(S: networkx.Graph, *, nodeset_digest: bytes | None = None) → TerseLinks

Encode solution topology S, optionally bound to a node set.

classmethod from_routeset(G: networkx.Graph) → TerseLinks

Encode routed solution G, including its clone mapping.

classmethod from_array(links: collections.abc.Sequence[int], *, topology: optiwindnet.types.Topology | str | None = None, R: int | None = None, T: int | None = None) → TerseLinks

Adapt a legacy topology array to a self-describing value.

to_topology(**graph_attrs) → networkx.Graph

Reconstruct topology S.

to_routeset(L: networkx.Graph, **graph_attrs) → networkx.Graph

Reconstruct routeset G against location graph L.

optiwindnet.interarraylib.assign_cables(G: networkx.Graph, cables: list[tuple[int, float | int]], currency: str = '€')

Assign a cable type to each edge of G and update attribute 'cost'.

Each edge is assigned the cheapest cable type that can carry its load. The edge attribute 'cable' is the index in cables of the type chosen.

Changes G in place.

Parameters:

• G – networkx graph with edges having a 'load' attribute (use calcload(G))

• cables – [(«capacity», «cost»), …] in increasing capacity order (each cable entry must be a tuple)

• currency – symbol representing the unit of the cost

optiwindnet.interarraylib.describe_G(G: networkx.Graph, significant_digits: int = 5) → list[str]

Create a 3-4 line summary of G’s properties.

significant_digits applies only to total length and is enforced only when the integer part has fewer significant digits than significant_digits.

Parameters:

• G – route set instance

• significant_digits – minimum number of significant digits used for total length

Returns:

capacity and T, excess feeders and feeders per root, total length,

total cost.

Return type:

Text lines

optiwindnet.interarraylib.pathdist(G, path)

Calculate the total length of a path of nodes in G.

Uses the nodes’ coordinates (does not rely on edge attributes).

optiwindnet.interarraylib.count_diagonals(S: networkx.Graph, A: networkx.Graph) → int

Count the number of Delaunay diagonals (extended edges) of A in S.

Parameters:

• S – solution topology

• A – available edges used in creating S

Returns:

number of non-gate edges of S that are of kind 'extended' or

'contour_extended' (kind is read from A).

Raises:

ValueError – if an edge of unknown kind is found.

optiwindnet.interarraylib.bfs_subtree_loads(G, parent, children, subtree, visited=None)

Recurse down the subtree, updating edge and node attributes.

Meant to be called by calcload(), but can be used independently (e.g. from PathFinder). Nodes must not have a 'load' attribute.

Parameters:

• G – graph to traverse.

• parent – node the recursion descends from.

• children – nodes of G to descend into.

• subtree – subtree id to assign to every node visited.

• visited – nodes already claimed by this traversal; pass one set across several calls to keep them from claiming a node twice. A fresh set is used when omitted.

Returns:

Total number of descendant nodes

Raises:

ValueError – a node is reached twice, so the traversal is not descending a tree – G holds a cycle, or two roots reach the same node.

optiwindnet.interarraylib.split_rings_and_calc_loads(S: networkx.Graph, A: networkx.Graph) → None

Close path-form ring arms into canonical rings and compute their loads.

Only the ringed builders (HGS, LKH and the method='ringed' constructor) call this, on a solution S that is still a set of simple root → … → root paths missing their zero-load links. Each path is walked and closed into a canonical ring (see add_ring_to_S()), using A to pick the longer zero-load link on odd-length rings; a tail already touching a root bridges two roots (r1, r2). Every ring receives exactly one zero-load link (load=0, no current flows through it), and each node’s subtree id and load, the edges’ loads, and the graph’s max_load / has_loads / root loads are set.

All ringed solvers must call this before returning a solution, so that every ringed S carries exactly one load=0 link per ring.

optiwindnet.interarraylib.calcload(G: networkx.Graph) → None

Calculate link loads and update edge and node attributes of G.

G must already be in final form (a forest, or a ring-form graph whose load=0 zero-load links are present). A breadth-first traversal of each root’s subtree propagates the loads, treating load=0 links (ring zero-load links) as breaks. Each node’s subtree id and outgoing load land on its 'subtree' / 'load' attributes, the edges’ 'load' attributes are updated, and the graph’s 'max_load', 'has_loads' and root loads are set.

Ring construction — closing path-form arms into rings — lives in split_rings_and_calc_loads(), which the ringed builders call instead.

optiwindnet.interarraylib.add_ring_to_S(S: networkx.Graph, roots: tuple[int, int], ordered: list[int], subtree: int, A: networkx.Graph | None = None) → None

Add a single ring to topology graph S in canonical form.

A ring is the union of two radial arms, fed by r1 and r2 and joined at their tail ends; it bridges two substations when r1 != r2. ordered is the terminal sequence [t1, ..., tn] walked along the ring, so that t1 and tn are the feeder-connected terminals. Both feeders (r1, t1) and (r2, tn) are real, load-bearing cables; the ring’s single zero-load link is the edge at the load midpoint, marked by load=0 (a real cable, no current flows through it).

Arm 1 (the t1 side) gets m = ceil(n / 2) terminals, so each arm holds at most ceil(n / 2) — i.e. half of the doubled ring capacity. When the ring has an even number of nodes (odd n), the middle terminal has two candidate split edges yielding balanced arms; if A is provided, the longer of the two is chosen as the zero-load link.

Node 'load'/'subtree' and edge 'load'/'reverse' are all set here; the caller is responsible for the root node’s aggregate load.

Parameters:

• S – topology graph to add the ring to (modified in place).

• roots – the pair (r1, r2) of (negative) root node ids, equal when both feeders share one root.

• ordered – terminal sequence [t1, ..., tn] along the ring.

• subtree – subtree id to assign to every node of the ring (both arms).

• A – optional available-links graph, used to pick the longer split edge on odd-node rings.

optiwindnet.interarraylib.rings_from_S(S: networkx.Graph) → list[tuple[tuple[int, int], list[int]]]

Recover ordered ring terminal sequences from a RINGED solution graph.

Each ring is returned as ((r1, r2), [t1, ..., tn]) with t1 and tn the feeder-connected terminals, obtained by walking the terminal adjacency from the head subroot to the tail one; r1 feeds t1 and r2 feeds tn. The ring bridges two substations when r1 != r2.

Feeders are identified by having exactly one negative (root) endpoint; a ring with a single terminal (n == 1) has both feeders on that terminal.

optiwindnet.interarraylib.validate_topology(S: networkx.Graph, capacity: int | None = None) → list[str]

Check S against the invariants of the topology it declares.

The canonical shape of a solution is a contract of the library, not of the test suite, so the invariants live next to the builders that establish them.

Together these invariants make S representable: a topology that passes survives a round-trip through its terse_links encoding unchanged, which is what makes it storable and usable as a MILP warm start.

Parameters:

• S – topology graph to check. S.graph['topology'] is mandatory: it is one of 'ringed', 'radial' or 'branched'. Loads are mandatory too – S without them is reported as a violation.

• capacity – cable capacity; defaults to S.graph['capacity']. Capacity checks are skipped when neither is available.

Returns:

list of human-readable violations; S is valid if it is empty.

Example:

violations = validate_topology(S, capacity)
if violations:
    print('\n'.join(violations))

optiwindnet.interarraylib.validate_routeset(G: networkx.Graph) → list[str]

Check a routeset G for load, topology and crossing violations.

Orchestrates the specific checkers: the loads G carries are compared against those its links imply (calcload() on a copy, so G is left untouched), the topology is checked against the shape it declares (validate_topology()), and the routes are checked for crossings and branch splits (find_routeset_crossings()).

Every routeset producer emits loads, so they are verified rather than recomputed: a routeset whose loads disagree with its links is reported, not silently corrected.

Crossings are geometry alone, so they are reported even when the loads are unusable.

Parameters:

G – routeset graph to evaluate.

Returns:

list of human-readable violations; G is valid if it is empty.

Example:

violations = validate_routeset(G)
if violations:
    print('\n'.join(violations))

optiwindnet.interarraylib.directed_links(S: networkx.Graph) → collections.abc.Iterator[tuple[int, int, int]]

Yield (source, sink, flow) for every link of S.

Forest topologies read each link’s orientation off its 'reverse' flag (see the note above bfs_subtree_loads()), so flow is just the link’s load.

A RINGED S – as declared by S.graph['topology'] – stores each ring split into two arms at a zero-load link, which is not how a flow formulation sees it: there a ring is one directed chain of its n terminals, fed by a flowless closing feeder at one end and draining through a feeder carrying the whole ring at the other. Such rings are radialized into that chain here (walking across the zero-load link with rings_from_S()), so the zero-load link becomes an ordinary flow-carrying link.

A ring bridging two roots drains through the one feeding the head of the walk and closes on the other; which of the two drains is arbitrary, as it moves no cable.

Parameters:

S – solution topology.

Yields:

(source, sink, flow) per link, current flowing source -> sink. flow is 0 for links carrying no current: a ring’s closing feeder.

optiwindnet.interarraylib.L_from_site(*, VertexC: numpy.ndarray, T: int, R: int, B: int = 0, border: numpy.ndarray | None = None, obstacles: list[numpy.ndarray] | None = None, name: str = '', handle: str = 'L_from_site', landscape_angle: float | None = None) → networkx.Graph

Create L from a location’s attributes.

Parameters:

• VertexC – numpy.ndarray (V, 2) with all (x, y) coordinates (V = R + T + B)

• T – int number of wtg

• R – int number of oss

• B – number of border and obstacle zones’ vertices

• border – array (B,) of VertexC indices that define the border (ccw)

• obstacles – sequence of numpy.ndarray of VertexC indices

• name – site name

• handle – site identifier

Returns:

Graph containing N = R + T nodes and no edges (all args become graph attributes).

optiwindnet.interarraylib.G_from_S(S: networkx.Graph, A: networkx.Graph) → networkx.Graph

Create G from S and A.

Graph S contains the topology of a routeset network (nodes only, no contours or detours). S must have been created from the available edges in A, whose contour information is used to obtain a routeset G (possibly with contours, but not with detours – use PathFinder afterward).

optiwindnet.interarraylib.S_from_G(G: networkx.Graph) → networkx.Graph

Get G’s topology (contours, detours, lengths, coords are dropped).

If using S to warm-start a MILP model, call after S_from_G():

• as_hooked_to_nearest(): if the model uses topology='branched'

• as_hooked_to_head(): if the model uses topology='radial'

This ensures that topology S is feasible (if radial) and not trivially suboptimal (if branched).

RINGED routesets are supported: the rings’ cycle-closing links are preserved (see the traversal note below), so S keeps the ring partition of G.

Parameters:

G – must contain a feasible solution (tree, path or ring)

Returns:

Topology of G

optiwindnet.interarraylib.L_from_G(G: networkx.Graph) → networkx.Graph

Return new location with nodes and site attributes from G.

The returned location graph L retains only roots, nodes and basic graph attributes. All edges and remaining attributes are not carried from G.

Parameters:

G – routeset graph to extract site data from.

Returns:

Site graph (no edges) with lean attributes.

optiwindnet.interarraylib.S_from_terse_links(terse_links, R=None, T=None, topology=None, **kwargs)

Create topology S from a self-describing or legacy encoding.

optiwindnet.interarraylib.terse_links_from_S(S)

Return the self-describing compact representation of topology S.

optiwindnet.interarraylib.as_obstacle_free(Lʹ: networkx.Graph) → networkx.Graph

Make a shallow copy of an instance and remove its obstacles.

The vertices that are used only by obstacles are also removed. To be used on locations (edge-less graphs).

Parameters:

Lʹ – input location

Returns:

location without obstacles.

optiwindnet.interarraylib.as_single_root(Lʹ: networkx.Graph) → networkx.Graph

Make a shallow copy of an instance and reduce its roots to one.

The output’s root is the centroid of the input’s roots. This may not work well for locations with obstacles, use as_obstacle_free() first.

Parameters:

Lʹ – input location

Returns:

location with a single root.

optiwindnet.interarraylib.as_normalized(Aʹ: networkx.Graph, *, offset: optiwindnet.geometric.CoordPair | None = None, scale: float | None = None) → networkx.Graph

Make a shallow copy of an instance and shift and scale its geometry.

Coordinates are subtracted by graph attribute 'norm_offset'. All lengths and coordinates are multiplied by graph attribute 'norm_scale'. Graph attribute 'is_normalized' is set to True. Affected linear attributes: 'VertexC', 'd2roots' (graph); 'length' (edge).

Parameters:

• Aʹ – (or Gʹ) any instance that has inherited 'scale' from an edgeset Aʹ.

• offset – coordinates (2,) offset to override graph’s 'norm_offset'

• scale – multiplicative scaling factor to override graph’s 'norm_scale'

Returns:

A copy of the instance with changed coordinates and linear metrics.

optiwindnet.interarraylib.as_rescaled(Gʹ: networkx.Graph, L: networkx.Graph) → networkx.Graph

Revert normalization done by as_normalized().

Parameters:

• Gʹ – routeset to rescale to pre-normalization size.

• L – (or G or A) locations or routeset to get 'VertexC' from (also 'd2roots', if available).

Returns:

Routeset with coordinates and lengths at site scale.

optiwindnet.interarraylib.as_undetoured(Gʹ: networkx.Graph) → networkx.Graph

Create an undetoured version of Gʹ.

Creates a shallow copy of Gʹ without detour nodes (and possibly with the resulting crossings). Changed links’ 'kind' become 'tentative'.

This is to be applied to a routeset that already has detours. It serves to re-run PathFinder on a detoured routeset, but it is not the best solution to prepare a routeset to be used as warmstart (re-hooking is missing).

optiwindnet.interarraylib.as_hooked_to_nearest(Gʹ: networkx.Graph, d2roots: numpy.ndarray) → networkx.Graph

Make tentative feeders link to the nearest-to-root node of each subtree.

Output may be branched (use with care with path routesets).

Sifts through all 'tentative' gates’ subtrees and choose the hook closest to the respective root according to d2roots.

Should be called after as_undetoured() if the goal is to use G as a warmstart for MILP models.

Parameters:

• G – routeset or topology S

• d2roots – distance from nodes to roots (e.g. A.graph['d2roots'])

optiwindnet.interarraylib.as_hooked_to_head(Sʹ: networkx.Graph, d2roots: numpy.ndarray) → networkx.Graph

Make tentative feeders link to the nearest-to-root end of each string.

Only works with solutions where subtrees are paths (radial topology).

Sifts through the subtrees of 'tentative' feeders and re-hook the subtree via the end-node that is nearest to the respective root according to d2roots.

Should be called after as_undetoured() if the goal is to use S as a warmstart for MILP models.

Parameters:

• S – solution topology

• d2roots – distance from nodes to roots (e.g. A.graph['d2roots'])

optiwindnet.interarraylib.as_stratified_vertices(Lʹ: networkx.Graph) → networkx.Graph

Ensure border-vertices are all in the B-range of VertexC.

Apply this to L when terminal or root coordinates are to be updated by writting to the array elements of VertexC. In order to keep the borders in place, they must not rely on vertices in the terminal or root sections (T-range, R-range). This function creates duplicates of any terminal-vertex or root-vertex used by borders/obstacles.

Parameters:

L – location geometry to be stratified

Returns:

New location geometry with stratified vertices

optiwindnet.interarraylib.make_remap(G, refG, H, refH)

Create a mapping between two representations of the same site.

CAUTION: only WTG node remapping is implemented.

If the nodes in G and in H represent the same site, but have different orientation, scale and node order, the mapping produced here can be used with NetworkX.relabel_nodes(G, remap) to translate a routeset in G to a routeset in H.

Parameters:

• G – routeset with obsolete representation.

• refG – two nodes to used as references.

• H – routeset with valid representation.

• refH – two nodes corresponding to refG

optiwindnet.interarraylib.add_terminal_closest_root(A: networkx.Graph) → None

Add attributes 'root' to terminals and 'rootmap__' to A.

Changes A in-place.

• node attribute 'root' is the index of the root closest to node.

• graph attribute 'rootmap__' is an R-long list of T-long bitarrays.

Parameters:

A – available-links graph

optiwindnet.interarraylib.add_link_blockmap(A: networkx.Graph)

Add edge attributes 'blocked__'.

Edges’ attribute 'blocked__' are R-long list of T-long bitarray maps.

If an edge’s blocked__[r][t] == 1, then this edge crosses the line-of-sight t-r.

Changes A in place. A should have no feeder edges.

Note

• this function neglects borders and contours.

• the space taken scales with R × T × num_edges(A)

optiwindnet.interarraylib.add_link_cosines(A: networkx.Graph)

Add cosine of the angle wrt each root to all links of A as attribute 'cos_'.

Changes A in-place. The cosine is of the acute angle between the link line and the line that contains the mid-point of the link and the root (for each root).

optiwindnet.interarraylib.scaffolded(G: networkx.Graph, P: networkx.PlanarEmbedding) → networkx.Graph

Create a new graph merging G and P.

Useful for visualizing the funnels explored by pathfinding.PathFinder. G must have been created using P.

Parameters:

• G – network graph for location

• P – planar embedding of location

Returns:

Merged graph (pass to plotting.gplot() or svg.svgplot()).