dertwin 0.1.0__py3-none-any.whl

dertwin/controllers/device_controller.py

@@ -0,0 +1,77 @@
+from typing import List, Dict
+from dertwin.core.device import SimulatedDevice
+from dertwin.core.registers import RegisterMap
+from dertwin.protocol.modbus import (
+    collect_write_instructions,
+    write_telemetry_registers,
+    write_command_registers,
+)
+
+class DeviceController:
+
+    def __init__(
+        self,
+        device: SimulatedDevice,
+        protocols: List,
+        register_map: RegisterMap,
+    ):
+        self.device = device
+        self.protocols = protocols
+        self.register_map = register_map
+        self._last_commands: Dict[str, float] = {}
+        self._initialized = False
+
+    def step(self, dt: float):
+        commands = self.collect_commands()
+
+        # First run: initialize baseline without applying
+        if not self._initialized:
+            self._last_commands = dict(commands)
+            self.device.init_applied_commands(commands)
+            self._initialized = True
+
+        elif commands and commands != self._last_commands:
+            applied = self.device.apply_commands(commands)
+            self.write_protocol_commands(applied)
+            self._last_commands = dict(commands)
+
+        self.device.update(dt)
+
+        telemetry = self.device.get_telemetry().to_dict()
+        self.apply_telemetry(telemetry)
+
+    def collect_commands(self) -> Dict[str, float]:
+        merged: Dict[str, float] = {}
+
+        for proto in self.protocols:
+            raw_cmds = collect_write_instructions(
+                self.register_map.writes,
+                proto.context,
+                proto.unit_id,
+            )
+
+            for vendor_name, value in raw_cmds.items():
+                reg = self.register_map.get_by_name(vendor_name)
+
+                internal_name = reg.internal_name or reg.name
+                merged[internal_name] = value
+
+        return merged
+
+    def apply_telemetry(self, telemetry: Dict[str, float]) -> None:
+        for proto in self.protocols:
+            write_telemetry_registers(
+                self.register_map.reads,
+                proto.context,
+                proto.unit_id,
+                telemetry,
+            )
+
+    def write_protocol_commands(self, commands: Dict[str, float]) -> None:
+        for proto in self.protocols:
+            write_command_registers(
+                self.register_map.writes,
+                proto.context,
+                proto.unit_id,
+                commands,
+            )

dertwin/controllers/site_controller.py

@@ -0,0 +1,206 @@
+import asyncio
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Callable
+
+from dertwin.core.clock import SimulationClock
+from dertwin.core.engine import SimulationEngine
+from dertwin.controllers.device_controller import DeviceController
+from dertwin.core.registers import RegisterMap
+
+from dertwin.devices.bess.simulator import BESSSimulator
+from dertwin.devices.pv.simulator import PVSimulator
+from dertwin.devices.energy_meter.simulator import EnergyMeterSimulator
+
+from dertwin.devices.external.external_models import ExternalModels
+
+from dertwin.protocol.modbus import ModbusSimulator
+
+logger = logging.getLogger(__name__)
+
+
+class SiteController:
+    """
+    Config-driven site runtime orchestrator.
+    Fully owns lifecycle of engine + protocols.
+    """
+
+    def __init__(self, config: Dict):
+        self.config = config
+        self.register_map_root = Path(config.get("register_map_root", "."))
+
+        self.clock = SimulationClock(
+            step=config.get("step", 0.1),
+            real_time=config.get("real_time", True),
+        )
+
+        self.engine: Optional[SimulationEngine] = None
+        self.controllers: List[DeviceController] = []
+        self.protocols: List[ModbusSimulator] = []
+
+        self._tasks: List[asyncio.Task] = []
+        self._built = False
+        self._running = False
+
+        self.external_models: Optional[ExternalModels] = None
+
+    # ==========================================================
+    # BUILD SITE
+    # ==========================================================
+
+    def build(self) -> None:
+        logger.info("Building site: %s", self.config.get("site_name", "unnamed"))
+
+
+        if self.config.get("external_models"):
+            self.external_models = ExternalModels.from_config(self.config.get("external_models"))
+        else:
+            self.external_models = ExternalModels.build_default()
+
+        devices_by_type: Dict[str, List] = {}
+        devices: List = []
+
+        # Create devices
+        for asset in [a for a in self.config["assets"] if a["type"] != "energy_meter"]:
+            device = self._create_device(asset)
+            devices.append(device)
+            devices_by_type.setdefault(asset["type"], []).append(device)
+
+        self.external_models.power_model = ExternalModels.build_power_model(devices_by_type, self.config.get("external_models"))
+
+
+        # ------------------------------------------------------
+        # Create Energy Meters
+        # ------------------------------------------------------
+
+        for _ in [a for a in self.config["assets"] if a["type"] == "energy_meter"]:
+            meter = EnergyMeterSimulator(
+                power_model=self.external_models.power_model,
+                grid_model=self.external_models.grid_frequency_model,
+                grid_voltage_model=self.external_models.grid_voltage_model,
+            )
+
+            devices.append(meter)
+            devices_by_type.setdefault("energy_meter", []).append(meter)
+
+        # Create controllers + protocols
+        for asset, device in zip(self.config["assets"], devices):
+
+            for proto_cfg in asset.get("protocols", []):
+
+                if proto_cfg["kind"] != "modbus_tcp":
+                    raise ValueError(f"Unsupported protocol kind: {proto_cfg['kind']}")
+
+                map_path = Path(proto_cfg["register_map"])
+                if not map_path.is_absolute():
+                    map_path = self.register_map_root / map_path
+
+                register_map = RegisterMap.from_yaml(map_path)
+
+                modbus = ModbusSimulator(
+                    address=proto_cfg["ip"],
+                    port=proto_cfg["port"],
+                    unit_id=proto_cfg.get("unit_id", 1),
+                )
+
+                self.protocols.append(modbus)
+
+                controller = DeviceController(
+                    device=device,
+                    protocols=[modbus],
+                    register_map=register_map,
+                )
+
+                self.controllers.append(controller)
+
+        self.engine = SimulationEngine(
+            devices=self.controllers,
+            clock=self.clock,
+            external_models=self.external_models,
+        )
+        # Set simulation start time if specified (e.g. start_time_h: 12.0 for noon)
+        start_time_h = self.config.get("start_time_h", 0.0)
+        if start_time_h:
+            self.clock.time = start_time_h * 3600.0
+
+        self._built = True
+
+        self._built = True
+
+    async def start(self):
+        if not self._built:
+            raise RuntimeError("Site must be built before start()")
+
+        if self._running:
+            return
+
+        logger.info("Starting site runtime")
+        self._running = True
+
+        # Start protocol servers
+        for proto in self.protocols:
+            task = asyncio.create_task(proto.run_server())
+            self._tasks.append(task)
+
+        # Only run engine loop in real-time mode
+        if self.clock.real_time:
+            engine_task = asyncio.create_task(self.engine.run())
+            self._tasks.append(engine_task)
+
+            try:
+                await asyncio.gather(*self._tasks)
+            except asyncio.CancelledError:
+                logger.info("Site tasks cancelled")
+
+    async def stop(self):
+        if not self._running:
+            return
+
+        logger.info("Stopping site runtime")
+
+        # Stop engine loop
+        if self.engine:
+            self.engine.stop()
+
+        # Graceful protocol shutdown
+        for proto in self.protocols:
+            await proto.shutdown()
+
+        # Cancel remaining tasks
+        for task in self._tasks:
+            task.cancel()
+
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+
+        self._tasks.clear()
+        self._running = False
+
+    # ------------------------------------------------------------------
+
+    def _create_device(self, asset_cfg: Dict):
+        dtype = asset_cfg["type"]
+
+        if dtype == "bess":
+            return BESSSimulator(
+                capacity_kwh=asset_cfg.get("capacity_kwh", 100.0),
+                initial_soc=asset_cfg.get("initial_soc", 50.0),
+                max_charge_kw=asset_cfg.get("max_charge_kw", 20.0),
+                max_discharge_kw=asset_cfg.get("max_discharge_kw", 20.0),
+                ramp_rate_kw_per_s=asset_cfg.get("ramp_rate_kw_per_s", 100.0),
+                ambient_temp_model=self.external_models.ambient_temperature_model,
+                grid_voltage_model=self.external_models.grid_voltage_model,
+                grid_frequency_model=self.external_models.grid_frequency_model,
+            )
+
+        if dtype == "inverter":
+            return PVSimulator(
+                rated_kw=asset_cfg.get("rated_kw", 10.0),
+                module_efficiency=asset_cfg.get("module_efficiency", 0.20),
+                area_m2=asset_cfg.get("area_m2", None),
+                ambient_temp_model=self.external_models.ambient_temperature_model,
+                grid_voltage_model=self.external_models.grid_voltage_model,
+                grid_frequency_model=self.external_models.grid_frequency_model,
+                irradiance_model=self.external_models.irradiance_model,
+            )
+
+        raise ValueError(f"Unknown or unsupported asset type: {dtype}")

dertwin/core/clock.py

@@ -0,0 +1,24 @@
+import asyncio
+from time import monotonic
+
+
+class SimulationClock:
+    def __init__(self, step: float = 0.1, real_time: bool = True):
+        self.time = 0.0
+        self.step = step
+        self.real_time = real_time
+        self._last_wall_time = monotonic()
+
+    async def tick(self):
+        self.time += self.step
+
+        if self.real_time:
+            target = self._last_wall_time + self.step
+            now = monotonic()
+            sleep_time = max(0.0, target - now)
+            self._last_wall_time = target
+            await asyncio.sleep(sleep_time)
+
+    def reset(self):
+        self.time = 0.0
+        self._last_wall_time = monotonic()

dertwin/core/device.py

@@ -0,0 +1,23 @@
+from abc import ABC, abstractmethod
+from typing import Dict
+
+from dertwin.telemetry.base import TelemetryBase
+
+
+class SimulatedDevice(ABC):
+
+    @abstractmethod
+    def update(self, dt: float) -> None:
+        pass
+
+    @abstractmethod
+    def get_telemetry(self) -> TelemetryBase:
+        pass
+
+    @abstractmethod
+    def apply_commands(self, commands: Dict[str, float]) -> Dict[str, float]:
+        pass
+
+    @abstractmethod
+    def init_applied_commands(self, commands: Dict[str, float]) -> Dict[str, float]:
+        pass

dertwin/core/engine.py

@@ -0,0 +1,100 @@
+import logging
+from typing import List, Optional
+
+from dertwin.controllers.device_controller import DeviceController
+from dertwin.core.clock import SimulationClock
+from dertwin.devices.external.external_models import ExternalModels
+
+logger = logging.getLogger(__name__)
+
+
+class SimulationEngine:
+    """
+    Deterministic simulation engine.
+
+    Execution order per tick:
+
+        1. external_models.update()
+        2. device_controller.step()
+        3. clock.tick()
+    """
+
+    def __init__(
+        self,
+        devices: List[DeviceController],
+        clock: SimulationClock,
+        external_models: Optional[ExternalModels] = None,
+    ):
+        self.devices = devices
+        self.clock = clock
+        self.external_models = external_models
+        self.sim_time = self.clock.time
+
+        self._running = False
+        self._tick_count = 0
+
+    # ---------------------------------------------------------
+    # REAL TIME LOOP
+    # ---------------------------------------------------------
+
+    async def run(self):
+
+        if not self.clock.real_time:
+            raise RuntimeError(
+                "Engine.run() should not be used in deterministic mode"
+            )
+
+        logger.info(
+            "Simulation engine started | step=%.3fs",
+            self.clock.step,
+        )
+
+        self._running = True
+
+        while self._running:
+            await self.step_once()
+
+    # ---------------------------------------------------------
+    # SINGLE STEP (Deterministic Safe)
+    # ---------------------------------------------------------
+
+    async def step_once(self):
+
+        dt = self.clock.step
+        self.sim_time = self.clock.time
+
+        # =====================================================
+        # STEP EXTERNAL FIRST
+        # =====================================================
+
+        if self.external_models:
+            self.external_models.update(self.sim_time, dt)
+
+        # =====================================================
+        # STEP DEVICES
+        # =====================================================
+
+        for device in self.devices:
+            device.step(dt)
+
+        # =====================================================
+        # LOGGING
+        # =====================================================
+
+        self._tick_count += 1
+
+        if self._tick_count % 100 == 0:
+            logger.info(
+                "Simulation tick | t=%.2fs | ticks=%d",
+                self.sim_time,
+                self._tick_count,
+            )
+
+        # =====================================================
+        # ADVANCE CLOCK
+        # =====================================================
+
+        await self.clock.tick()
+
+    def stop(self):
+        self._running = False

dertwin/core/registers.py

@@ -0,0 +1,156 @@
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional
+
+import yaml
+
+
+# ==========================================================
+# ENUMS
+# ==========================================================
+
+class RegisterDirection(str, Enum):
+    READ = "read"
+    WRITE = "write"
+
+
+# ==========================================================
+# REGISTER DEFINITION
+# ==========================================================
+
+@dataclass(frozen=True)
+class RegisterDefinition:
+    name: str
+    internal_name: str
+    address: int
+    func: int
+    direction: RegisterDirection
+    type: str
+    count: int
+    scale: float = 1.0
+    unit: str = ""
+    options: Optional[Dict[int, str]] = None
+    description: Optional[str] = None
+
+    @property
+    def key(self) -> Tuple[int, int, RegisterDirection]:
+        """
+        Unique identifier inside protocol space.
+        """
+        return self.address, self.func, self.direction
+
+
+class RegisterMap:
+    """
+    Immutable container for device register definitions.
+    Provides validation and fast lookup.
+    """
+
+    def __init__(self, registers: List[RegisterDefinition]):
+        self._registers = registers
+
+        # Lookup tables
+        self._by_key: Dict[Tuple[int, int, RegisterDirection], RegisterDefinition] = {}
+        self._by_name: Dict[str, RegisterDefinition] = {}
+        self._reads: Dict[int, RegisterDefinition] = {}
+        self._writes: Dict[int, RegisterDefinition] = {}
+
+        self._build_indexes()
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "RegisterMap":
+        if not path.exists():
+            raise FileNotFoundError(f"Register map not found: {path}")
+
+        with open(path, "r") as f:
+            data = yaml.safe_load(f)
+
+        raw_registers = data.get("registers", [])
+        definitions: List[RegisterDefinition] = []
+
+        for entry in raw_registers:
+            definitions.append(cls._parse_entry(entry))
+
+        return cls(definitions)
+
+    @staticmethod
+    def _parse_entry(entry: Dict) -> RegisterDefinition:
+        try:
+            direction = RegisterDirection(entry["direction"])
+        except ValueError:
+            raise ValueError(f"Invalid register direction: {entry['direction']}")
+
+        if "count" not in entry:
+            raise ValueError(f"Missing 'count' for register: {entry['name']}")
+
+        return RegisterDefinition(
+            name=entry["name"],
+            internal_name=entry["internal_name"],
+            address=entry["address"],
+            func=entry["func"],
+            direction=direction,
+            type=entry["type"],
+            count=entry["count"],
+            scale=entry.get("scale", 1.0),
+            unit=entry.get("unit", ""),
+            options=entry.get("options"),
+            description=entry.get("description"),
+        )
+
+    def _build_indexes(self):
+        for reg in self._registers:
+
+            # Check duplicate key
+            if reg.key in self._by_key:
+                raise ValueError(
+                    f"Duplicate register definition: {reg.key}"
+                )
+
+            # Check duplicate name
+            if reg.name in self._by_name:
+                raise ValueError(
+                    f"Duplicate register name: {reg.name}"
+                )
+
+            self._by_key[reg.key] = reg
+            self._by_name[reg.name] = reg
+
+            # Simple address-based lookup (per direction)
+            if reg.direction == RegisterDirection.READ:
+                if reg.address in self._reads:
+                    raise ValueError(
+                        f"Overlapping READ register at address {reg.address}"
+                    )
+                self._reads[reg.address] = reg
+
+            if reg.direction == RegisterDirection.WRITE:
+                if reg.address in self._writes:
+                    raise ValueError(
+                        f"Overlapping WRITE register at address {reg.address}"
+                    )
+                self._writes[reg.address] = reg
+
+    def get_by_name(self, name: str) -> RegisterDefinition:
+        return self._by_name[name]
+
+    def get(self, address: int, func: int, direction: RegisterDirection) -> Optional[RegisterDefinition]:
+        return self._by_key.get((address, func, direction))
+
+    def read_register(self, address: int) -> Optional[RegisterDefinition]:
+        return self._reads.get(address)
+
+    def write_register(self, address: int) -> Optional[RegisterDefinition]:
+        return self._writes.get(address)
+
+    @property
+    def all(self) -> List[RegisterDefinition]:
+        return list(self._registers)
+
+    @property
+    def reads(self) -> List[RegisterDefinition]:
+        return [r for r in self._registers if r.direction == RegisterDirection.READ]
+
+    @property
+    def writes(self) -> List[RegisterDefinition]:
+        return [r for r in self._registers if r.direction == RegisterDirection.WRITE]