extended components lib

Author: networmix

ngraph/components.py

@@ -9,83 +9,153 @@
 @dataclass(slots=True)
 class Component:
     """
-    A generic component with a name, cost, power, and optional children.
-
-    This can represent items such as chassis, line cards, optic modules, etc.
+    A generic component that can represent chassis, line cards, optics, etc.
+    Components can have nested children, each with their own cost, power, etc.
 
     Attributes:
         name (str): Name of the component (e.g., "SpineChassis" or "400G-LR4").
-        component_type (str): An optional string label ("chassis", "linecard", "optic", etc.).
-        cost (float): Base capex cost for the component.
-        power_watts (float): Power consumption of the component in watts.
+        component_type (str): A string label (e.g., "chassis", "linecard", "optic").
+        description (str): A human-readable description of this component.
+        cost (float): Cost (capex) of a single instance of this component.
+        power_watts (float): Typical/nominal power usage (watts) for one instance.
+        power_watts_max (float): Maximum/peak power usage (watts) for one instance.
+        capacity (float): A generic capacity measure (e.g., platform capacity).
         ports (int): Number of ports if relevant for this component.
-        children (Dict[str, Component]): Child components keyed by their names.
+        count (int): How many identical copies of this component are present.
+        attrs (Dict[str, Any]): Arbitrary key-value attributes for extra metadata.
+        children (Dict[str, Component]): Nested child components (e.g., line cards
+            inside a chassis), keyed by child name.
     """
 
     name: str
     component_type: str = "generic"
+    description: str = ""
     cost: float = 0.0
-    power_watts: float = 0.0
+
+    power_watts: float = 0.0  # Typical power usage
+    power_watts_max: float = 0.0  # Peak power usage
+
+    capacity: float = 0.0
     ports: int = 0
+    count: int = 1
+
+    attrs: Dict[str, Any] = field(default_factory=dict)
     children: Dict[str, Component] = field(default_factory=dict)
 
     def total_cost(self) -> float:
         """
-        Calculates the total cost including all nested children.
+        Computes the total (recursive) cost of this component, including children,
+        multiplied by this component's count.
 
         Returns:
-            float: Recursive sum of costs for this component and its children.
+            float: The total cost.
         """
-        total = self.cost
+        single_instance_cost = self.cost
         for child in self.children.values():
-            total += child.total_cost()
-        return total
+            single_instance_cost += child.total_cost()
+        return single_instance_cost * self.count
 
     def total_power(self) -> float:
         """
-        Calculates the total power consumption including all nested children.
+        Computes the total *typical* (recursive) power usage of this component,
+        including children, multiplied by this component's count.
+
+        Returns:
+            float: The total typical power in watts.
+        """
+        single_instance_power = self.power_watts
+        for child in self.children.values():
+            single_instance_power += child.total_power()
+        return single_instance_power * self.count
+
+    def total_power_max(self) -> float:
+        """
+        Computes the total *peak* (recursive) power usage of this component,
+        including children, multiplied by this component's count.
+
+        Returns:
+            float: The total maximum (peak) power in watts.
+        """
+        single_instance_power_max = self.power_watts_max
+        for child in self.children.values():
+            single_instance_power_max += child.total_power_max()
+        return single_instance_power_max * self.count
+
+    def total_capacity(self) -> float:
+        """
+        Computes the total (recursive) capacity of this component,
+        including children, multiplied by this component's count.
 
         Returns:
-            float: Recursive sum of power for this component and its children.
+            float: The total capacity (dimensionless or user-defined units).
         """
-        total = self.power_watts
+        single_instance_capacity = self.capacity
         for child in self.children.values():
-            total += child.total_power()
-        return total
+            single_instance_capacity += child.total_capacity()
+        return single_instance_capacity * self.count
+
+    def as_dict(self, include_children: bool = True) -> Dict[str, Any]:
+        """
+        Returns a dictionary containing all properties of this component.
+
+        Args:
+            include_children (bool): If True, recursively includes children.
+
+        Returns:
+            Dict[str, Any]: Dictionary representation of this component.
+        """
+        data = {
+            "name": self.name,
+            "component_type": self.component_type,
+            "description": self.description,
+            "cost": self.cost,
+            "power_watts": self.power_watts,
+            "power_watts_max": self.power_watts_max,
+            "capacity": self.capacity,
+            "ports": self.ports,
+            "count": self.count,
+            "attrs": dict(self.attrs),  # shallow copy
+        }
+        if include_children:
+            data["children"] = {
+                child_name: child.as_dict(True)
+                for child_name, child in self.children.items()
+            }
+        return data
 
 
 @dataclass(slots=True)
 class ComponentsLibrary:
     """
     Holds a collection of named Components. Each entry is a top-level "template"
-    that can be referenced for cost/power lookups, possibly with nested children.
+    that can be referenced for cost/power/capacity lookups, possibly with nested children.
 
-    Example:
+    Example (YAML-like):
         components:
           BigSwitch:
             component_type: chassis
             cost: 20000
-            power_watts: 1000
+            power_watts: 1750
+            capacity: 25600
             children:
-              LC-48x10G:
+              PIM16Q-16x200G:
                 component_type: linecard
-                cost: 5000
-                power_watts: 300
-                ports: 48
-          400G-LR4:
+                cost: 1000
+                power_watts: 10
+                ports: 16
+                count: 8
+          200G-FR4:
             component_type: optic
             cost: 2000
-            power_watts: 15
-
-    Attributes:
-        components (Dict[str, Component]): A dictionary of component name -> Component.
+            power_watts: 6
+            power_watts_max: 6.5
     """
 
     components: Dict[str, Component] = field(default_factory=dict)
 
     def get(self, name: str) -> Optional[Component]:
         """
-        Retrieves a Component by its name.
+        Retrieves a Component by its name from the library.
 
         Args:
             name (str): Name of the component.
@@ -104,7 +174,7 @@ def merge(
 
         Args:
             other (ComponentsLibrary): Another library to merge into this one.
-            override (bool): Whether components in `other` override existing ones.
+            override (bool): If True, components in `other` override existing ones.
 
         Returns:
             ComponentsLibrary: This instance, updated in place.
@@ -154,19 +224,45 @@ def _build_component(cls, name: str, definition_data: Dict[str, Any]) -> Compone
         comp_type = definition_data.get("component_type", "generic")
         cost = float(definition_data.get("cost", 0.0))
         power = float(definition_data.get("power_watts", 0.0))
+        power_max = float(definition_data.get("power_watts_max", 0.0))
+        capacity = float(definition_data.get("capacity", 0.0))
         ports = int(definition_data.get("ports", 0))
+        count = int(definition_data.get("count", 1))
 
-        children_map: Dict[str, Component] = {}
         child_definitions = definition_data.get("children", {})
+        children_map: Dict[str, Component] = {}
         for child_name, child_data in child_definitions.items():
             children_map[child_name] = cls._build_component(child_name, child_data)
 
+        recognized_keys = {
+            "component_type",
+            "cost",
+            "power_watts",
+            "power_watts_max",
+            "capacity",
+            "ports",
+            "children",
+            "attrs",
+            "count",
+            "description",
+        }
+        attrs: Dict[str, Any] = dict(definition_data.get("attrs", {}))
+        leftover_keys = {
+            k: v for k, v in definition_data.items() if k not in recognized_keys
+        }
+        attrs.update(leftover_keys)
+
         return Component(
             name=name,
             component_type=comp_type,
+            description=definition_data.get("description", ""),
             cost=cost,
             power_watts=power,
+            power_watts_max=power_max,
+            capacity=capacity,
             ports=ports,
+            count=count,
+            attrs=attrs,
             children=children_map,
         )
 
@@ -175,7 +271,7 @@ def from_yaml(cls, yaml_str: str) -> ComponentsLibrary:
         """
         Constructs a ComponentsLibrary from a YAML string. If the YAML contains
         a top-level 'components' key, that key is used; otherwise the entire
-        top-level of the YAML is treated as component definitions.
+        top-level is treated as component definitions.
 
         Args:
             yaml_str (str): A YAML-formatted string of component definitions.