pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/core/block_source.py

@@ -0,0 +1,94 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+import numpy as np
+
+from pySimBlocks.core.block import Block
+
+
+class BlockSource(Block):
+    """
+    Base class for all source blocks (Constant, Step, Ramp, Sinusoidal, ...).
+
+    Provides:
+        - normalization utilities for source parameters to produce 2D signals
+        - strict scalar-only broadcasting to a common 2D shape
+        - no state update by default
+    """
+
+    direct_feedthrough = False
+    is_source = True
+
+    def __init__(self, name: str, sample_time: float | None = None):
+        super().__init__(name, sample_time)
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        pass  # all sources are stateless
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _resolve_common_shape(self, params: dict[str, np.ndarray]) -> tuple[int, int]:
+        """
+        Determine the common target shape among parameters.
+
+        Policy:
+            - scalars (1,1) are broadcastable
+            - any non-scalar (2D not (1,1)) fixes the target shape
+            - if multiple non-scalars exist, all must have exactly the same shape
+            - if all are scalars -> target shape is (1,1)
+        """
+        non_scalar_shapes = {a.shape for a in params.values() if not self._is_scalar_2d(a)}
+
+        if len(non_scalar_shapes) == 0:
+            return (1, 1)
+
+        if len(non_scalar_shapes) == 1:
+            return next(iter(non_scalar_shapes))
+
+        details = ", ".join(f"{k}={v.shape}" for k, v in params.items())
+        raise ValueError(
+            f"[{self.name}] Inconsistent parameter shapes. "
+            f"All non-scalar parameters must have the same (m,n) shape. Got: {details}"
+        )
+
+    # ------------------------------------------------------------------
+    def _broadcast_scalar_only(self, param_name: str, arr: np.ndarray, target_shape: tuple[int, int]) -> np.ndarray:
+        """
+        Broadcast only scalar (1,1) to target_shape.
+        Any non-scalar must already match target_shape exactly.
+        """
+        if self._is_scalar_2d(arr):
+            if target_shape == (1, 1):
+                return arr.astype(float, copy=False)
+            return np.full(target_shape, float(arr[0, 0]), dtype=float)
+
+        if arr.shape != target_shape:
+            raise ValueError(
+                f"[{self.name}] '{param_name}' shape {arr.shape} is incompatible with "
+                f"target shape {target_shape}. Only scalar-to-shape broadcasting is allowed."
+            )
+
+        return arr.astype(float, copy=False)

pySimBlocks/core/config.py

@@ -0,0 +1,90 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+# ---------------------------------------------------------------------
+# Classes
+# ---------------------------------------------------------------------
+@dataclass(frozen=True)
+class SimulationConfig:
+    """
+    Simulation execution configuration.
+
+    This object contains ONLY execution-related parameters.
+    It must not contain any model or block-specific information.
+    """
+
+    dt: float
+    T: float
+    t0: float = 0.0
+    solver: str = "fixed"
+    logging: List[str] = field(default_factory=list)
+    clock: str = "internal" # "internal" or "external"
+
+    def validate(self) -> None:
+        """Verify that the configuration is valid.
+        (ie: dt > 0, T > t0, solver is known)
+        """
+        if self.dt <= 0.0:
+            raise ValueError("SimulationConfig.dt must be > 0")
+
+        if self.T <= self.t0:
+            raise ValueError("SimulationConfig.T must be > t0")
+
+        if self.solver not in {"fixed", "variable"}:
+            raise ValueError(
+                f"Unknown solver '{self.solver}'. "
+                "Allowed values: {'fixed', 'variable'}"
+            )
+
+        if self.clock not in {"internal", "external"}:
+            raise ValueError(
+                f"Unknown clock '{self.clock}'. "
+                "Allowed values: {'internal', 'external'}"
+            )
+
+
+@dataclass
+class PlotConfig:
+    """
+    Plot configuration.
+
+    Describes how logged signals should be visualized.
+    This object contains NO plotting logic.
+    """
+
+    plots: List[Dict[str, Any]]
+
+    def validate(self) -> None:
+        """Verify that the configuration is valid.
+        (ie: each plot has required fields)
+        """
+        for i, plot in enumerate(self.plots):
+            if "signals" not in plot:
+                raise ValueError(
+                    f"Plot #{i} is missing required field 'signals'"
+                )
+            if not isinstance(plot["signals"], list):
+                raise ValueError(
+                    f"'signals' in plot #{i} must be a list"
+                )

pySimBlocks/core/fixed_time_manager.py

@@ -0,0 +1,46 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+class FixedStepTimeManager:
+    """A time manager for fixed-step simulations.
+    Handle multiple sample times by ensuring they are multiples of the base time step.
+    """
+    def __init__(self, dt_base: float, sample_times: list[float]):
+
+        if dt_base <= 0:
+            raise ValueError("Base time step must be strictly positive.")
+
+        self.dt = dt_base
+        self._check_sample_times(sample_times)
+
+    def _check_sample_times(self, sample_times):
+        """Ensure all sample times are multiples of the base time step."""
+        eps = 1e-12
+        for st in sample_times:
+            ratio = st / self.dt
+            if abs(ratio - round(ratio)) > eps:
+                raise ValueError(
+                    f"In fixed-step mode, sample_time={st} "
+                    f"is not a multiple of base dt={self.dt}."
+                )
+
+    def next_dt(self, t):
+        """Get the next time step (always fixed)."""
+        return self.dt

pySimBlocks/core/model.py

@@ -0,0 +1,250 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+from collections import deque
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from pySimBlocks.core.block import Block
+
+# A connection is:
+#    ( (src_block, src_port), (dst_block, dst_port) )
+Connection = Tuple[Tuple[str, str], Tuple[str, str]]
+
+
+class Model:
+    """
+    Discrete-time block-diagram model (Simulink-like).
+
+    Responsibilities:
+      - Store blocks.
+      - Store signal connections.
+      - Build execution order (topological sort).
+      - Provide fast access to downstream connections.
+
+    Notes:
+      * Topological sorting is applied only to the combinational graph.
+      * Blocks with state (i.e., blocks where next_state is non-empty)
+        are treated as "cycle breakers" (delay elements),
+        exactly like Simulink does for algebraic loops.
+    """
+
+    def __init__(
+            self,
+            name: str = "model",
+            model_data: Dict[str, Any] | None = None,
+            params_dir: Path | None = None,
+            verbose: bool = False,
+        ):
+        self.name = name
+        self.verbose = verbose
+
+        self.blocks: Dict[str, Block] = {}
+        self.connections: List[Connection] = []
+
+        self._output_execution_order: List[Block] = []
+        self._state_execution_order: List[Block] = []
+
+        self._downstream_map: Dict[str, List[Connection]] = {}
+        self._connections_dirty: bool = True
+
+        if model_data is not None:
+            from pySimBlocks.project.build_model import build_model_from_dict
+            build_model_from_dict(self, model_data, params_dir=params_dir)
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def add_block(self, block: Block) -> Block:
+        """Add a block to the model."""
+        if block.name in self.blocks:
+            raise ValueError(f"Block name '{block.name}' already exists.")
+
+        self.blocks[block.name] = block
+        return block
+
+    # ------------------------------------------------------------------
+    def get_block_by_name(self, name: str) -> Block:
+        """Get a block by its name."""
+        if name not in self.blocks:
+            raise ValueError(
+                f"Block name '{name}' not found. Known blocks: {list(self.blocks.keys())}"
+            )
+        return self.blocks[name]
+
+    # ------------------------------------------------------------------
+    def connect(self, src_block: str, src_port: str,
+                      dst_block: str, dst_port: str) -> None:
+        """
+        Connect:
+            blocks[src_block].outputs[src_port]
+        to:
+            blocks[dst_block].inputs[dst_port]
+        """
+        if src_block not in self.blocks:
+            raise ValueError(
+                    f"Unknown source block '{src_block}'. "
+                    f"Known blocks: {list(self.blocks.keys())}"
+                )
+        if dst_block not in self.blocks:
+            raise ValueError(
+                    f"Unknown destination block '{dst_block}'. "
+                    f"Known blocks: {list(self.blocks.keys())}"
+                )
+
+        self.connections.append(
+            ((src_block, src_port), (dst_block, dst_port))
+        )
+        self._connections_dirty = True
+
+    # ------------------------------------------------------------------
+    def build_execution_order(self):
+        """
+        Build Simulink-like execution order based solely on direct-feedthrough
+        causal dependencies (Simulink PDF p.7).
+        """
+
+        blocks = self.blocks
+        names = list(blocks.keys())
+
+        vprint = print if self.verbose else (lambda *a, **k: None)
+
+        vprint("\n================= BUILD EXECUTION ORDER =================")
+        vprint(f"Blocks in model: {names}")
+
+        # STEP 1 — Build dependency graph
+        vprint("\n--- STEP 1: CONNECTION ANALYSIS (direct-feedthrough rules) ---")
+
+        graph = {name: [] for name in names}
+        indegree = {name: 0 for name in names}
+
+        for (src, dst) in self.connections:
+            src_block, src_port = src
+            dst_block, dst_port = dst
+
+            block_dist = blocks[dst_block]
+
+            if block_dist.direct_feedthrough:
+                graph[src_block].append(dst_block)
+                indegree[dst_block] += 1
+                vprint(f"  DEPENDENCY: {src_block}.{src_port} -> {dst_block}.{dst_port} "
+                       f"(direct-feedthrough)")
+            else:
+                vprint(f"  NO DEPENDENCY: {src_block}.{src_port} -> {dst_block}.{dst_port} "
+                       f"(destination NOT direct-feedthrough)")
+
+        # Show resulting graph
+        vprint("\nGraph adjacency list:")
+        for k, v in graph.items():
+            vprint(f"  {k}: {v}")
+
+        vprint("\nInitial indegree:")
+        for k, v in indegree.items():
+            vprint(f"  {k}: {v}")
+
+        # STEP 2 — Kahn topological sort
+        vprint("\n--- STEP 2: TOPOLOGICAL SORT ---")
+
+        ready = deque([b for b in names if indegree[b] == 0])
+
+        vprint(f"Initial READY queue: {list(ready)}")
+
+        execution_order = []
+
+        while ready:
+            current = ready.popleft()
+            execution_order.append(current)
+
+            vprint(f"\n==> EXECUTE: '{current}'")
+
+            # Decrease indegree for successors
+            for succ in graph[current]:
+                indegree[succ] -= 1
+                vprint(f"    indegree[{succ}] -> {indegree[succ]}")
+                if indegree[succ] == 0:
+                    ready.append(succ)
+                    vprint(f"    '{succ}' added to READY")
+
+        # STEP 3 — Detect algebraic loops
+        if len(execution_order) != len(names):
+            vprint("\n!!! ALGEBRAIC LOOP DETECTED !!!")
+            raise RuntimeError(
+                "Algebraic loop detected: direct-feedthrough cycle exists."
+            )
+
+        # STEP 4 — Final result
+        vprint("\n--- FINAL SIMULINK-LIKE EXECUTION ORDER ---")
+        for i, b in enumerate(execution_order, 1):
+            vprint(f"  {i}. {b}")
+        vprint("========================================================\n")
+
+        # Final storage
+        self._output_execution_order = [blocks[n] for n in execution_order]
+
+        return self._output_execution_order
+
+    # ------------------------------------------------------------------
+    def downstream_of(self, block_name: str):
+        """
+        Returns all connections where block_name is the source.
+        """
+        if self._connections_dirty or not self._downstream_map:
+            self._rebuild_downstream_map()
+        return self._downstream_map.get(block_name, [])
+
+    # ------------------------------------------------------------------
+    def execution_order(self):
+        """Get execution order, building it if necessary."""
+        if not self._output_execution_order:
+            return self.build_execution_order()
+        return self._output_execution_order
+
+    # ------------------------------------------------------------------
+    def predecessors_of(self, block_name):
+        """Get all blocks that feed into block_name."""
+        for (src, dst) in self.connections:
+            if dst[0] == block_name:
+                yield src[0]
+
+    # ------------------------------------------------------------------
+    def resolve_sample_times(self, dt):
+        """
+        Resolve effective sample times for all blocks.
+
+        Returns:
+            has_explicit_rate (bool): True if at least one block defines a sample_time.
+        """
+
+        for b in self.blocks.values():
+            if b.sample_time is None:
+                b._effective_sample_time = dt
+            else:
+                b._effective_sample_time = b.sample_time
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _rebuild_downstream_map(self) -> None:
+        downstream = {name: [] for name in self.blocks.keys()}
+        for (src, dst) in self.connections:
+            downstream[src[0]].append((src, dst))
+        self._downstream_map = downstream
+        self._connections_dirty = False

pySimBlocks/core/scheduler.py

@@ -0,0 +1,30 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+from pySimBlocks.core.task import Task
+
+class Scheduler:
+    """A simple scheduler for managing tasks based on their start times."""
+    def __init__(self, tasks: list[Task]):
+        self.tasks = sorted(tasks, key=lambda t: t.sample_time)
+
+    def active_tasks(self, t):
+        """Return the list of tasks that should run at time t."""
+        return [task for task in self.tasks if task.should_run(t)]