feat: add possibility for optional meta information

Fixes #120

psdm/base.py

@@ -18,11 +18,6 @@
 U = t.TypeVar("U", bound=t.Hashable)
 
 
-class VoltageSystemType(enum.Enum):
-    AC = "AC"
-    DC = "DC"
-
-
 def _validate_unique_list(v: tuple[U]) -> tuple[U]:
     if len(v) != len(set(v)):
         error_type = "unique_list"
@@ -78,3 +73,14 @@ def validate_deprecated(self: U, attr_dpr: str, attr_new: str) -> U:
         warnings.warn(msg, DeprecationWarning, stacklevel=4)
 
     return self
+
+
+class VoltageSystemType(enum.Enum):
+    AC = "AC"
+    DC = "DC"
+
+
+class AttributeData(Base):
+    name: str  # attribute key
+    value: str | bool | int | float | UniqueTuple[t.Any]
+    description: str | None = None

psdm/topology/branch.py

@@ -6,7 +6,9 @@
 
 from enum import Enum
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 from psdm.base import UniqueTuple
 from psdm.base import VoltageSystemType
 from psdm.quantities.multi_phase import Phase
@@ -63,3 +65,4 @@ class Branch(Base):
     xpn: ImpedanceNat | None = None  # neutral-line couple values
     gpn: AdmittanceNat | None = None  # neutral-line couple values
     bpn: AdmittanceNat | None = None  # neutral-line couple values
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None

psdm/topology/coupler.py

@@ -4,7 +4,9 @@
 
 from __future__ import annotations
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 
 
 class Coupler(Base):
@@ -13,3 +15,4 @@ class Coupler(Base):
     element: str
     node: str
     state: bool  # 0:opened; 1:closed
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None

psdm/topology/external_grid.py

@@ -6,7 +6,9 @@
 
 from enum import Enum
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 from psdm.base import UniqueTuple
 from psdm.quantities.multi_phase import Phase
 from psdm.quantities.single_phase import ApparentPower
@@ -31,3 +33,4 @@ class ExternalGrid(Base):
     short_circuit_power_max: ApparentPower
     short_circuit_power_min: ApparentPower
     type: GridType
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None

psdm/topology/fuse.py

@@ -4,7 +4,9 @@
 
 from __future__ import annotations
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 
 
 class Fuse(Base):
@@ -13,3 +15,4 @@ class Fuse(Base):
     element: str
     node: str
     state: bool  # 0:opened; 1:closed
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None

psdm/topology/load.py

@@ -10,7 +10,9 @@
 
 import pydantic
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 from psdm.base import VoltageSystemType
 from psdm.quantities.multi_phase import ActivePower
 from psdm.quantities.multi_phase import ApparentPower
@@ -152,6 +154,7 @@ class Load(Base):  # including assets of type load and generator
     system_type: SystemType
     voltage_system_type: VoltageSystemType
     description: str | None = None
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None
 
     @pydantic.model_validator(mode="after")
     def validate_length(self) -> Load:

psdm/topology/node.py

@@ -2,7 +2,9 @@
 # :copyright: Copyright (c) Institute of Electrical Power Systems and High Voltage Engineering - TU Dresden, 2022-2023.
 # :license: BSD 3-Clause
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 from psdm.base import UniqueTuple
 from psdm.quantities.multi_phase import Phase
 from psdm.quantities.single_phase import Voltage
@@ -15,3 +17,4 @@ class Node(Base):
     u_n: Voltage
     phases: UniqueTuple[Phase]
     description: str | None = None
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None

psdm/topology/switch.py

@@ -4,7 +4,9 @@
 
 from __future__ import annotations
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 
 
 class Switch(Base):
@@ -13,3 +15,4 @@ class Switch(Base):
     element: str
     node: str
     state: bool  # 0:opened; 1:closed
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None

psdm/topology/transformer.py

@@ -7,7 +7,9 @@
 
 import enum
 
+from psdm.base import AttributeData
 from psdm.base import Base
+from psdm.base import UniqueNonEmptyTuple
 from psdm.base import UniqueTuple
 from psdm.quantities.multi_phase import Phase
 from psdm.quantities.single_phase import Angle
@@ -94,3 +96,4 @@ class Transformer(Base):
     tap_min: int | None = None  # lower position of tap for tap control
     tap_neutral: int | None = None  # initial position where rated transformation ratio is specified
     tap_side: TapSide | None = None  # transformer side of where tap changer is installed
+    meta: UniqueNonEmptyTuple[AttributeData] | None = None