optiwindnet.interarraylib ========================= .. py:module:: optiwindnet.interarraylib Module Contents --------------- .. py:function:: describe_G(G) .. 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, **kwargs) -> networkx.Graph Create L from a location's attributes. :param VertexC: numpy.ndarray (V, 2) with x, y pos. of wtg + oss (total V) :param T: int number of wtg :param R: int number of oss :param \*\*kwargs: Additional relevant arguments, for example: * name: str site name * handle: str site identifier * B: int 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 :returns: Graph containing N = R + T nodes and no edges. All keyword arguments are made available as 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_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. :param Lʹ: input location :returns: location with a single root. .. py:function:: as_normalized(Aʹ: networkx.Graph, *, offset: float | 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: override graph's 'norm_offset' :param scale: 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:: 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:: 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()`).