optiwindnet.interarraylib
=========================

.. py:module:: optiwindnet.interarraylib




Module Contents
---------------

.. py:function:: 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.

   :param G: networkx graph with edges having a 'load' attribute (use calcload(G))
   :param cables: [(«capacity», «cost»), ...] in increasing capacity order (each
                  cable entry must be a tuple)
   :param currency: symbol representing the unit of the cost


.. py:function:: 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

   :param G: route set instance
   :param 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.
   :rtype: Text lines


.. py:function:: pathdist(G, path)

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

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


.. py:function:: count_diagonals(S: networkx.Graph, A: networkx.Graph) -> int

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

   :param S: solution topology
   :param 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.


.. py:function:: bfs_subtree_loads(G, parent, children, subtree)

   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.

   :returns: Total number of descendant nodes


.. py:function:: calcload(G)

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

   Perform a breadth-first-traversal of each root's subtree. As each node is
   visited, its subtree id and the load leaving it are stored as its
   attribute (keys 'subtree' and 'load', respectively). Also the edges'
   'load' attributes are updated accordingly.


.. py:function:: site_fingerprint(VertexC: numpy.ndarray, boundary: numpy.ndarray) -> tuple[bytes, dict[str, bytes]]

.. py:function:: fun_fingerprint(fun=None) -> dict[str, bytes | str]

.. py:function:: 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.

   :param VertexC: numpy.ndarray (V, 2) with all (x, y) coordinates (V = R + T + B)
   :param T: int number of wtg
   :param R: int number of oss
   :param B: number of border and obstacle zones' vertices
   :param border: array (B,) of VertexC indices that define the border (ccw)
   :param obstacles: sequence of numpy.ndarray of VertexC indices
   :param name: site name
   :param handle: site identifier

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


.. py:function:: 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).


.. py:function:: 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()`: for branching (tree) models
   * `as_hooked_to_head()`: for non-branching (path) models

   This ensures that topology S is feasible (if non-branching) and not
   trivially suboptimal (if branching).

   :param G: must contain a feasible solution (either tree or path)

   :returns: topology of `G`


.. py:function:: 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`.

   :param G: routeset graph to extract site data from.

   :returns: Site graph (no edges) with lean attributes.


.. py:function:: S_from_terse_links(terse_links, **kwargs)

   Create a solution topology graph `S` from its `terse_links` encoding.

   Inverse function of `terse_links_from_S()`.

   :param terse_links: tree links encoded as 1D array (edges are: i->terse_links[i])

   :returns: Solution topology S.


.. py:function:: terse_links_from_S(S)

   Make a terse representation of the topology `S` as a 1D array.

   Inverse function of `S_from_terse_links()`.

   :param S: solution topology (must be a tree)

   :returns: i->terse_links[i])
   :rtype: 1D array representing the links of S (edges are


.. py:function:: 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).

   :param Lʹ: input location

   :returns: location without obstacles.


.. py:function:: 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.

   :param Lʹ: input location

   :returns: location with a single root.


.. py:function:: 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).

   :param Aʹ: (or Gʹ) any instance that has inherited 'scale' from an
              edgeset `Aʹ`.
   :param offset: coordinates (2,) offset to override graph's 'norm_offset'
   :param scale: multiplicative scaling factor to override graph's 'norm_scale'

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


.. py:function:: as_rescaled(Gʹ: networkx.Graph, L: networkx.Graph) -> networkx.Graph

   Revert normalization done by `as_normalized()`.

   :param Gʹ: routeset to rescale to pre-normalization size.
   :param 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.


.. py:function:: 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 applyed 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).


.. py:function:: 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.

   :param G: routeset or topology S
   :param d2roots: distance from nodes to roots (e.g. A.graph['d2roots'])


.. py:function:: 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 all 'tentative' gates' subtrees and re-hook that path to
   the one of its end-nodes that is neares 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.

   :param S: solution topology
   :param d2roots: distance from nodes to roots (e.g. A.graph['d2roots'])


.. py:function:: 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.

   :param L: location geometry to be stratified

   :returns: New location geometry with stratified vertices


.. py:function:: 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.

   :param G: routeset with obsolete representation.
   :param refG: two nodes to used as references.
   :param H: routeset with valid representation.
   :param refH: two nodes corresponding to `refG`


.. py:function:: add_terminal_closest_root(A: networkx.Graph) -> None

   Add node attribute 'root' to terminals and graph attribute 'rootmap__' to A.

   Changes A in-place.
   'root' is the index of the root closest to node
   'rootmap__' is an R-long list of T-long bitarrays.

   :param A: available-links graph


.. py:function:: 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.

   Notes:
   - this function neglects borders and countours.
   - the space taken scales with R × T × num_edges(A)


.. py:function:: 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).


.. py:function:: 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`.

   :param G: network graph for location
   :param P: planar embedding of location

   :returns: Merged graph (pass to `plotting.gplot()` or 'svg.svgplot()`).