fram-core 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

framcore/utils/isolate_subnodes.py

@@ -0,0 +1,172 @@
+"""Demo to show how we can use the core to write some functions we need."""
+
+from collections import defaultdict
+from copy import copy
+from time import time
+
+from framcore import Model
+from framcore.components import Component, Flow, Node
+from framcore.events import send_debug_event
+from framcore.utils import get_node_to_commodity, get_supported_components, is_transport_by_commodity
+
+
+def _is_boundary_flow(flow: Flow, nodes: set[str]) -> bool:
+    arrows = flow.get_arrows()
+    x, y = tuple(arrows)  # has len 2
+    return int(x.get_node() in nodes) + int(y.get_node() in nodes) == 1
+
+
+def _is_member(node: Node, meta_key: str, members: set[str]) -> bool:
+    meta = node.get_meta(meta_key)
+    value = meta.get_value()
+    return value in members
+
+
+def isolate_subnodes(model: Model, commodity: str, meta_key: str, members: list[str]) -> None:  # noqa: PLR0915, C901
+    """
+    For components in model, delete all nodes of commodity except member nodes, and their flows and boundary nodes.
+
+    - Keep member nodes and all flows between them.
+    - Set boundary nodes exogenous and keep boundary flows into or out from member nodes.
+    - Delete all other nodes of commodity and all other flows pointing to them.
+
+    Args:
+        model (Model): Model to modify
+        commodity (str): Commodity of nodes to consider
+        meta_key (str): Meta key to use to identify members
+        members (List[str]): List of meta key values identifying member nodes
+
+    """
+    t = time()
+
+    data = model.get_data()
+    counts_before = model.get_content_counts()
+
+    has_not_converged = True
+    num_iterations = 0
+
+    while has_not_converged:
+        num_iterations += 1
+
+        n_data_before = len(data)
+
+        # We need copy of components to set _parent None so component becomes top_parent in upcoming code
+        components: dict[str, Component] = {k: copy(v) for k, v in data.items() if isinstance(v, Component)}
+        for c in components.values():
+            c: Component
+            c._parent = None  # noqa: SLF001
+
+        node_to_commodity = get_node_to_commodity(components)
+
+        parent_keys: dict[Component, str] = {v: k for k, v in components.items()}
+
+        graph: dict[str, Node | Flow] = get_supported_components(components, (Node, Flow), tuple())
+
+        parent_to_components = defaultdict(set)
+        for c in graph.values():
+            parent_to_components[c.get_top_parent()].add(c)
+
+        nodes: dict[str, Node] = {k: v for k, v in graph.items() if isinstance(v, Node)}
+        flows: dict[str, Flow] = {k: v for k, v in graph.items() if isinstance(v, Flow)}
+
+        commodity_nodes: dict[str, Node] = {k: v for k, v in nodes.items() if commodity == v.get_commodity()}
+        for k, v in commodity_nodes.items():
+            assert v.get_meta(meta_key), f"missing meta_key {meta_key} node_id {k}"
+
+        inside_nodes: dict[str, Node] = {k: v for k, v in commodity_nodes.items() if _is_member(v, meta_key, members)}
+
+        transports: dict[str, Flow] = {k: v for k, v in flows.items() if is_transport_by_commodity(v, node_to_commodity, commodity)}
+
+        boundary_flows: dict[str, Flow] = {k: v for k, v in transports.items() if _is_boundary_flow(v, inside_nodes.keys())}
+
+        boundary_nodes: dict[str, Node] = dict()
+        for flow_id, flow in boundary_flows.items():
+            for a in flow.get_arrows():
+                node_id = a.get_node()
+                if node_id not in inside_nodes:
+                    boundary_nodes[node_id] = nodes[node_id]
+
+        outside_nodes: dict[str, Node] = {k: v for k, v in commodity_nodes.items() if not (k in inside_nodes or k in boundary_nodes)}
+
+        deletes: set[str] = set()
+
+        deletes.update(outside_nodes.keys())
+        deletes.update(boundary_nodes.keys())  # will be kept in delete step below
+        deletes.update(boundary_flows.keys())  # will be kept in delete step below
+
+        # delete flows delivering to deleted node
+        for k, flow in flows.items():
+            for a in flow.get_arrows():
+                if a.get_node() in deletes:
+                    deletes.add(k)
+                    break  # goto next k, flow
+
+        # needed for next two steps
+        node_to_flows: dict[str, set[str]] = defaultdict(set)
+        flow_to_nodes: dict[str, set[str]] = defaultdict(set)
+        for flow_id, flow in flows.items():
+            for arrow in flow.get_arrows():
+                node_id = arrow.get_node()
+                node_to_flows[node_id].add(flow_id)
+                flow_to_nodes[flow_id].add(node_id)
+
+        # delete disconnected subgraphs
+        remaining = set(n for n in nodes if n not in commodity_nodes)
+        while remaining:
+            is_disconnected_subgraph = True
+            subgraph = set()
+            possible_members = set()
+            possible_members.add(remaining.pop())
+            while possible_members:
+                member = possible_members.pop()
+                if member in subgraph:  # avoid cycle
+                    continue
+                if member in flows:
+                    subgraph.add(member)
+                    for node in flow_to_nodes[member]:
+                        if node not in outside_nodes or node not in boundary_nodes:
+                            possible_members.add(node)
+                            if node in inside_nodes:
+                                is_disconnected_subgraph = False
+                else:
+                    subgraph.add(member)
+                    for flow in node_to_flows[member]:
+                        possible_members.add(flow)
+            if is_disconnected_subgraph:
+                deletes.update(subgraph)
+
+        for key in deletes:
+            if (key in boundary_flows) or (key in boundary_nodes):
+                continue
+
+            if key not in graph:
+                continue
+
+            parent_key = parent_keys[graph[key].get_top_parent()]
+
+            if parent_key in data:
+                del data[parent_key]
+
+        n_data_after = len(data)
+
+        if n_data_after == n_data_before:
+            has_not_converged = False
+
+    counts_after = model.get_content_counts()
+
+    added_components = counts_after["components"] - counts_before["components"]
+    if added_components.total() > 0:
+        message = f"Expected only deleted components. Got additions {added_components}"
+        raise RuntimeError(message)
+
+    deleted_components = counts_before["components"] - counts_after["components"]
+
+    for node_id in boundary_nodes:
+        if node_id in data:
+            node: Node = data[node_id]
+            node.set_exogenous()
+            if not node.get_price().has_level():
+                message = f"{node_id} set to be exogenous, but no price is available."
+                raise RuntimeError(message)
+
+    send_debug_event(isolate_subnodes, f"Used {num_iterations} iterations and {round(time() - t, 2)} seconds and deleted {deleted_components}")

framcore/utils/loaders.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from framcore.events import send_warning_event
+
+if TYPE_CHECKING:
+    from framcore import Model
+    from framcore.loaders import Loader
+
+
+def add_loaders_if(loaders: set, value: object | None) -> None:
+    """Call value.add_loaders(loaders) if value is not None."""
+    _check_type(loaders, "loaders", set)
+    if value is None:
+        return
+    value.add_loaders(loaders)
+
+
+def add_loaders(loaders: set[Loader], model: Model) -> None:
+    """Add all loaders stored in Model to loaders set."""
+    from framcore import Model
+    from framcore.components import Component, Flow, Node
+    from framcore.curves import Curve
+    from framcore.expressions import Expr
+    from framcore.timevectors import TimeVector
+    from framcore.utils import get_supported_components
+
+    _check_type(loaders, "loaders", set)
+    _check_type(model, "model", Model)
+
+    data = model.get_data()
+    components = dict()
+
+    for key, value in data.items():
+        if isinstance(value, Expr):
+            value.add_loaders(loaders)
+
+        elif isinstance(value, TimeVector | Curve):
+            loader = value.get_loader()
+            if loader is not None:
+                loaders.add(loader)
+
+        elif isinstance(value, Component):
+            components[key] = value
+
+    graph: dict[str, Flow | Node] = get_supported_components(components, (Flow, Node), tuple())
+
+    for c in graph.values():
+        c.add_loaders(loaders)
+
+
+def replace_loader_path(loaders: set[Loader], old: Path, new: Path) -> None:
+    """Replace old path with new for all loaders using old path."""
+    from framcore.loaders import FileLoader
+
+    _check_type(loaders, "loaders", set)
+
+    new = _check_path(new, "new", make_absolute=True)
+    old = _check_path(old, "old", error_if_not_absolute=True)
+
+    for loader in loaders:
+        try:
+            source = loader.get_source()
+        except Exception:
+            send_warning_event(f"loader.get_source() failed for {loader}. Skipping this one.")
+            continue
+
+        if isinstance(source, Path) and old in source.parents:
+            loader.set_source(new_source=new / source.relative_to(old))
+
+        if isinstance(loader, FileLoader) and not isinstance(source, Path):
+            send_warning_event(f"FileLoader.get_source() does not return Path as it should for loader {loader}. Instead of Path, got {source}")
+
+
+def _check_type(value, name, expected) -> None:  # noqa: ANN001
+    if not isinstance(value, expected):
+        message = f"Expected {name} to be {type(expected).__name__}. Got Got {type(value).__name__}"
+        raise TypeError(message)
+
+
+def _check_path(
+    path: Path,
+    new_old: str,
+    make_absolute: bool = False,
+    error_if_not_absolute: bool = False,
+) -> Path:
+    if not isinstance(path, Path):
+        message = f"{new_old} must be Path. Got {path}"
+        raise ValueError(message)
+    if make_absolute and not path.is_absolute():
+        path = path.resolve()
+    if error_if_not_absolute and not path.is_absolute():
+        message = f"{new_old} must be an absolute Path. Got {path}"
+        raise ValueError(message)
+    return path

framcore/utils/node_flow_utils.py

@@ -0,0 +1,236 @@
+from __future__ import annotations  # NB! added for type hint to work
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from framcore import Base
+from framcore.components import Component, Flow, Node
+from framcore.utils import get_supported_components
+
+if TYPE_CHECKING:
+    from framcore import Model
+
+
+class FlowInfo(Base):
+    """Holds info about one or two related Arrows of a Flow."""
+
+    def __init__(
+        self,
+        category: str,
+        node_out: str | None = None,
+        commodity_out: str | None = None,
+        node_in: str | None = None,
+        commodity_in: str | None = None,
+    ) -> None:
+        """
+        Based on its arrows, we derive properties about a Flow.
+
+        We use this class to store such info.
+        """
+        self.category = category
+        self.node_out = node_out
+        self.commodity_out = commodity_out
+        self.node_in = node_in
+        self.commodity_in = commodity_in
+
+
+def _check_type(value: object, expected) -> None:  # noqa: ANN001
+    assert isinstance(value, expected), f"Expected {expected}. Got {type(value.__name__)}."
+
+
+def get_node_to_commodity(data: dict[str, object]) -> dict[str, str]:
+    """Return dict with commodity (str) for each node id (str) in data."""
+    _check_type(data, dict)
+
+    components = {k: v for k, v in data.items() if isinstance(v, Component)}
+    for k in components:
+        assert isinstance(k, str), f"Got invalid key {k}"
+
+    g = get_supported_components(components, (Node, Flow), tuple())
+
+    out = dict()
+    for k, v in g.items():
+        if isinstance(v, Node):
+            _check_type(k, str)
+            out[k] = v.get_commodity()
+    return out
+
+
+def get_flow_infos(flow: Flow, node_to_commodity: dict[str, str]) -> list[FlowInfo]:  # noqa: C901
+    """Get flow infos from analysis of all its arrows."""
+    _check_type(flow, Flow)
+    _check_type(node_to_commodity, dict)
+
+    arrows = flow.get_arrows()
+
+    if len(arrows) == 1:
+        arrow = next(iter(arrows))
+        node_id = arrow.get_node()
+
+        if node_id not in node_to_commodity:
+            message = f"node_id {node_id} missing from node_to_commodity for flow\n{flow}"
+            raise RuntimeError(message)
+
+        commodity = node_to_commodity[node_id]
+        if arrow.is_ingoing():
+            info = FlowInfo(
+                "direct_in",
+                node_in=node_id,
+                commodity_in=commodity,
+            )
+        else:
+            info = FlowInfo(
+                "direct_out",
+                node_out=node_id,
+                commodity_out=commodity,
+            )
+        return [info]
+
+    seen: set[tuple[str, str]] = set()
+    infos: list[FlowInfo] = []
+    for x in arrows:
+        for y in arrows:
+            if x is y:
+                continue
+
+            if x.is_ingoing() != y.is_ingoing():
+                arrow_in = x if x.is_ingoing() else y
+                arrow_out = x if y.is_ingoing() else y
+
+                node_in = arrow_in.get_node()
+                node_out = arrow_out.get_node()
+
+                if node_in not in node_to_commodity:
+                    message = f"node_in {node_in} missing from node_to_commodity for flow\n{flow}"
+                    raise RuntimeError(message)
+
+                if node_out not in node_to_commodity:
+                    message = f"node_out {node_out} missing from node_to_commodity for flow\n{flow}"
+                    raise RuntimeError(message)
+
+                commodity_in = node_to_commodity[node_in]
+                commodity_out = node_to_commodity[node_out]
+
+                info = FlowInfo(
+                    category="transport" if commodity_in == commodity_out else "conversion",
+                    node_in=node_in,
+                    commodity_in=commodity_in,
+                    node_out=node_out,
+                    commodity_out=commodity_out,
+                )
+                key = (node_in, node_out)
+                if key in seen:
+                    continue
+
+                infos.append(info)
+                seen.add(key)
+
+    for arrow in arrows:
+        node = arrow.get_node()
+        if any(node in [info.node_in, info.node_out] for info in infos):
+            continue
+        node_id = arrow.get_node()
+        commodity = node_to_commodity[node_id]
+        if arrow.is_ingoing():
+            info = FlowInfo(
+                "direct_in",
+                node_in=node_id,
+                commodity_in=commodity,
+            )
+        else:
+            info = FlowInfo(
+                "direct_out",
+                node_out=node_id,
+                commodity_out=commodity,
+            )
+        infos.append(info)
+
+    return infos
+
+
+def get_component_to_nodes(data: Model | dict[str, object]) -> dict[str, set[str]]:
+    """For each str key in data where value is a Component find all Node id str in data directly connected to the Component."""
+    from framcore import Model
+
+    _check_type(data, Model | dict)
+
+    if isinstance(data, Model):
+        data = data.get_data()
+
+    components = {k: v for k, v in data.items() if isinstance(v, Component)}
+    for k in components:
+        assert isinstance(k, str), f"Got invalid key {k}"
+
+    g = get_supported_components(components, (Node, Flow), tuple())
+
+    nodes = {k: v for k, v in g.items() if isinstance(v, Node)}
+    flows = {k: v for k, v in g.items() if isinstance(v, Flow)}
+
+    domain_nodes = {k: v for k, v in nodes.items() if (k in components) and isinstance(v, Node)}
+    assert all(isinstance(v, Node) for v in domain_nodes.values())
+
+    parent_keys = {v: k for k, v in components.items()}
+
+    out = defaultdict(set)
+    for flow in flows.values():
+        parent_key = parent_keys[flow.get_top_parent()]
+        for a in flow.get_arrows():
+            node_id = a.get_node()
+            if node_id in domain_nodes:
+                out[parent_key].add(node_id)
+
+    return out
+
+
+def get_transports_by_commodity(data: Model | dict[str, object], commodity: str) -> dict[str, tuple[str, str]]:
+    """Return dict with key component_id and value (from_node_id, to_node_id) where both nodes belong to given commodity."""
+    from framcore import Model
+
+    _check_type(data, Model | dict)
+    _check_type(commodity, str)
+
+    if isinstance(data, Model):
+        data = data.get_data()
+
+    components = {k: v for k, v in data.items() if isinstance(v, Component)}
+    for k in components:
+        assert isinstance(k, str), f"Got invalid key {k}"
+
+    node_to_commodity = get_node_to_commodity(components)
+
+    g = get_supported_components(components, (Node, Flow), tuple())
+
+    flows = {k: v for k, v in g.items() if isinstance(v, Flow)}
+
+    parent_keys = {v: k for k, v in components.items()}
+
+    out = dict()
+    for flow in flows.values():
+        parent_key = parent_keys[flow.get_top_parent()]
+        infos = get_flow_infos(flow, node_to_commodity)
+        if len(infos) != 1:
+            continue
+        info = infos[0]
+        if info.category != "transport":
+            continue
+        if info.commodity_in != commodity:
+            continue
+        out[parent_key] = (info.node_out, info.node_in)
+
+    return out
+
+
+def is_transport_by_commodity(flow: Flow, node_to_commodity: dict[str, str], commodity: str) -> bool:
+    """Return True if flow is a transport of the given commodity."""
+    _check_type(flow, Flow)
+    _check_type(node_to_commodity, dict)
+    arrows = flow.get_arrows()
+    try:
+        x, y = tuple(arrows)
+        opposite_directions = x.is_ingoing() != y.is_ingoing()
+        x_commodity = node_to_commodity[x.get_node()]
+        y_commodity = node_to_commodity[y.get_node()]
+        correct_commodity = x_commodity == y_commodity == commodity
+        return opposite_directions and correct_commodity
+    except Exception:
+        return False

framcore/utils/storage_subsystems.py

@@ -0,0 +1,106 @@
+from __future__ import annotations  # NB! added for type hint to work
+
+from collections import defaultdict
+
+from framcore import Model
+from framcore.components import Component, Flow, Node
+from framcore.utils import get_supported_components
+
+
+# TODO: Finish implementation, test and demo
+def get_storage_subsystems(domain_components: dict[str, Component] | Model) -> dict[str, set[str]]:  # noqa: D103
+    if isinstance(domain_components, Model):
+        domain_components = {k: v for k, v in domain_components.get_data() if isinstance(v, Component)}
+
+    # translate domain_components to graph consisting of just Flow and Node components
+    graph: dict[str, Flow | Node] = get_supported_components(
+        components=domain_components,
+        supported_types=(Node, Flow),
+    )
+
+    abstract_subsystems, __ = get_one_commodity_storage_subsystems(graph, include_boundaries=True)
+
+    # TODO: Use Component.get_top_level to lift abstract_subsystems back to domain_components
+    return abstract_subsystems
+
+
+
+def get_one_commodity_storage_subsystems(  # noqa: C901
+    graph: dict[str, Node | Flow],
+    include_boundaries: bool,
+) -> dict[str, tuple[str, set[str], set[str]]]:
+    """
+    Group all storage subsystems belonging to same commodity.
+
+    Returns dict[subsystem_id, (domain_commodity, member_component_ids, boundary_domain_commodities)]
+
+    The boundary_domain_commodities of the output is a set of boundary commodities.
+    Some algorithms can only handle one boundary commodity, so this output is useful
+    to verify that those conditions apply, and to derive conversion factor unit,
+    which need both storage_commodity unit and boundray_commodity unit.
+
+    If include_boundaries is False only nodes with same commodity as storage_node will
+    be included in the subsystem.
+    """
+    if not all(isinstance(c, Flow | Node) for c in graph.values()):
+        invalid = {k: v for k, v in graph.items() if not isinstance(v, Flow | Node)}
+        message = f"All values in graph must be Flow or Node objects. Found invalid objects: {invalid}"
+        raise ValueError(message)
+
+    flows: dict[str, Flow] = {k: v for k, v in graph.items() if isinstance(v, Flow)}
+    nodes: dict[str, Node] = {k: v for k, v in graph.items() if isinstance(v, Node)}
+
+    storage_nodes: dict[str, Node] = {k: v for k, v in nodes.items() if v.get_storage()}
+
+    node_to_flows: dict[str, set[str]] = defaultdict(set)
+    flow_to_nodes: dict[str, set[str]] = defaultdict(set)
+    for flow_id, flow in flows.items():
+        for arrow in flow.get_arrows():
+            node_id = arrow.get_node()
+            node_to_flows[node_id].add(flow_id)
+            flow_to_nodes[flow_id].add(node_id)
+
+    out = dict()
+    allocated: set[str] = set()
+    for storage_node_id, storage_node in storage_nodes.items():
+        if storage_node_id in allocated:
+            continue
+
+        subsystem_id = storage_node_id
+        storage_commodity = storage_node.get_commodity()
+
+        member_component_ids: set[str] = set()
+        boundary_commodities: set[str] = set()
+
+        visited: set[str] = set()
+        remaining: set[str] = set()
+
+        remaining.add(storage_node_id)
+
+        while remaining:
+            component_id = remaining.pop()
+            if component_id in visited:
+                continue
+
+            visited.add(component_id)
+
+            if component_id in nodes:
+                node: Node = nodes[component_id]
+                node_commodity = node.get_commodity()
+
+                if node_commodity == storage_commodity:
+                    allocated.add(component_id)
+                    remaining.update(node_to_flows.get(component_id, set()))
+                else:
+                    boundary_commodities.add(node_commodity)
+
+                if include_boundaries or node_commodity == storage_commodity:
+                    member_component_ids.add(component_id)
+
+            else:
+                remaining.update(flow_to_nodes.get(component_id, set()))
+                member_component_ids.add(component_id)
+
+        out[subsystem_id] = (storage_commodity, member_component_ids, boundary_commodities)
+
+    return out

fram_core-0.0.0.dist-info/METADATA

@@ -1,5 +0,0 @@
-Metadata-Version: 2.4
-Name: fram-core
-Version: 0.0.0
-Summary: Coming soon...
-Author-email: NVE <alro@nve.no>

fram_core-0.0.0.dist-info/RECORD

@@ -1,4 +0,0 @@
-fram_core-0.0.0.dist-info/METADATA,sha256=MXr1hQAqr_E4d7YDIhkuSeF-G0jYcTZJKTqr5fwOxPo,114
-fram_core-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fram_core-0.0.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-fram_core-0.0.0.dist-info/RECORD,,

fram_core-0.0.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-