flode 0.60.3__py3-none-any.whl

flode/analysis/stability.py

@@ -0,0 +1,229 @@
+"""安定性解析 (固有値 / 漸近安定性 / 根軌跡) — ADR-0027 §(1)B / §(6)(7)。
+
+``LinearSystem`` (ADR-0026) を入力に取る:
+
+- :func:`eigenvalues` / :func:`is_stable` は **numpy のみで動く** (extras 不要、
+  ADR-0027 §Decision Option 3 hybrid)。
+- :func:`root_locus` は ``python-control`` 経由 (`flode[control]` extras 必須、
+  未インストール時は ``ImportError`` で誘導、ADR-0027 §(10) E4)。
+
+MIMO 入力に対する :func:`root_locus` は ``input_idx`` / ``output_idx`` で SISO
+抽出する (ADR-0027 §(7))。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import numpy.typing as npt
+
+from ..exceptions import BlockSpecError
+from .linearize import LinearSystem
+
+if TYPE_CHECKING:  # pragma: no cover - optional matplotlib type
+    from matplotlib.axes import Axes
+
+_FLODE_CONTROL_HINT = "Install via `pip install flode[control]` or `pip install python-control`."
+
+
+def _import_control() -> Any:
+    """``python-control`` を遅延 import (extras 未インストール時に案内付き)。"""
+    try:
+        import control as _control
+    except ImportError as e:
+        raise ImportError(
+            f"This function requires the optional `python-control` package. {_FLODE_CONTROL_HINT}"
+        ) from e
+    return _control
+
+
+# ---------------------------------------------------------------------------
+# 固有値 / 漸近安定性 (numpy のみ)
+# ---------------------------------------------------------------------------
+
+
+def eigenvalues(ls: LinearSystem) -> npt.NDArray[Any]:
+    """A 行列の固有値を返す (`np.linalg.eig` の薄ラッパ)。
+
+    Args:
+        ls: :class:`LinearSystem`。
+
+    Returns:
+        複素 1D ndarray、shape ``(n,)``。順序は LAPACK ``geev`` の依存。
+
+    Raises:
+        BlockSpecError: 空の状態空間 (``A.shape[0] == 0``)。
+    """
+    if ls.A.shape[0] == 0:
+        raise BlockSpecError(
+            "eigenvalues: empty state-space (A.shape[0] == 0). "
+            "Linearise a model with at least one continuous state first."
+        )
+    eig_values, _ = np.linalg.eig(ls.A)
+    return np.asarray(eig_values, dtype=complex)
+
+
+def is_stable(ls: LinearSystem, *, tol: float = 1e-9) -> bool:
+    """連続系の漸近安定性判定 (ADR-0027 §(6))。
+
+    全固有値の実部 < ``-tol`` のとき ``True``。境界値 (``Re(λ) ∈ [-tol, +tol]``)
+    は **不安定として扱う** (= 限界安定 / 中立安定は False、純虚軸極を含むモデルは
+    False)。
+
+    第三状態 (``"marginal"``) を返さない理由は ADR-0027 §(6) 参照: API の単純さを
+    優先し、境界値が必要な利用者は :func:`eigenvalues` 直接利用。
+
+    Args:
+        ls: :class:`LinearSystem`。
+        tol: マージン (default ``1e-9``、LAPACK ``geev`` の数値誤差を吸収)。
+
+    Returns:
+        ``True`` (漸近安定) / ``False`` (それ以外)。
+
+    Raises:
+        BlockSpecError: 空の状態空間。
+        ValueError: ``tol < 0``。
+    """
+    if tol < 0.0:
+        raise ValueError(f"is_stable: tol must be >= 0, got {tol}")
+    eig_values = eigenvalues(ls)
+    return bool(np.all(np.real(eig_values) < -tol))
+
+
+# ---------------------------------------------------------------------------
+# 根軌跡 (python-control 経由)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, eq=False)
+class RootLocus:
+    """根軌跡データ (SISO のみ、ADR-0027 §(2)/§(7))。
+
+    Attributes:
+        roots: 各 K 値での閉ループ極の位置、shape ``(n_K, n_states)``、dtype complex。
+        gains: 対応する K 値、shape ``(n_K,)``。
+        input_idx: SISO 抽出に用いた入力 idx (= ``ls.B`` の列)。
+        output_idx: SISO 抽出に用いた出力 idx (= ``ls.C`` の行)。
+    """
+
+    roots: npt.NDArray[Any]
+    gains: npt.NDArray[Any]
+    input_idx: int
+    output_idx: int
+
+    def plot(
+        self,
+        ax: Axes | None = None,
+        *,
+        show: bool = False,
+    ) -> Axes:
+        """根軌跡を複素平面に描画する (各極の K sweep を line plot)。"""
+        import matplotlib.pyplot as plt
+
+        if ax is None:
+            _, ax = plt.subplots()
+        for j in range(self.roots.shape[1]):
+            ax.plot(
+                np.real(self.roots[:, j]),
+                np.imag(self.roots[:, j]),
+                marker=".",
+                markersize=2,
+                linewidth=0.7,
+            )
+        ax.axhline(0.0, color="gray", linewidth=0.5)
+        ax.axvline(0.0, color="gray", linewidth=0.5)
+        ax.set_xlabel("Re")
+        ax.set_ylabel("Im")
+        ax.grid(True, linestyle=":")
+        ax.set_title(f"Root locus (input[{self.input_idx}] → output[{self.output_idx}])")
+        if show:
+            plt.show()
+        return ax
+
+
+def _siso_extract(
+    ls: LinearSystem, input_idx: int, output_idx: int
+) -> tuple[npt.NDArray[Any], npt.NDArray[Any], npt.NDArray[Any], npt.NDArray[Any]]:
+    """``ls`` から ``(input_idx, output_idx)`` SISO サブシステムを抽出する。
+
+    A はそのまま、B は対象列のみ、C は対象行のみ、D は対象要素のみ。
+    """
+    n_in = ls.B.shape[1]
+    n_out = ls.C.shape[0]
+    if input_idx < 0 or input_idx >= n_in:
+        raise BlockSpecError(
+            f"root_locus: input_idx={input_idx} out of range (LinearSystem has {n_in} input(s))"
+        )
+    if output_idx < 0 or output_idx >= n_out:
+        raise BlockSpecError(
+            f"root_locus: output_idx={output_idx} out of range (LinearSystem has {n_out} output(s))"
+        )
+    A = np.asarray(ls.A, dtype=float)
+    B = np.asarray(ls.B[:, input_idx : input_idx + 1], dtype=float)
+    C = np.asarray(ls.C[output_idx : output_idx + 1, :], dtype=float)
+    D = np.asarray(ls.D[output_idx : output_idx + 1, input_idx : input_idx + 1], dtype=float)
+    return A, B, C, D
+
+
+def root_locus(
+    ls: LinearSystem,
+    *,
+    k_range: tuple[float, float] | npt.NDArray[Any] | None = None,
+    input_idx: int = 0,
+    output_idx: int = 0,
+) -> RootLocus:
+    """SISO 抽出した伝達関数の根軌跡を計算する (ADR-0027 §(7))。
+
+    MIMO ``LinearSystem`` の場合は ``input_idx`` / ``output_idx`` で SISO 抽出。
+
+    Args:
+        ls: :class:`LinearSystem`。
+        k_range: K sweep 範囲。``(k_min, k_max)`` または明示 ndarray。``None`` で
+            ``python-control`` のデフォルト (極零点の絶対値から推定された対数スケール)。
+        input_idx: SISO 抽出する入力 idx (default ``0``)。
+        output_idx: SISO 抽出する出力 idx (default ``0``)。
+
+    Returns:
+        :class:`RootLocus`。
+
+    Raises:
+        ImportError: ``flode[control]`` extras 未インストール。
+        BlockSpecError: ``input_idx`` / ``output_idx`` 範囲外、空の状態空間。
+    """
+    if ls.A.shape[0] == 0:
+        raise BlockSpecError(
+            "root_locus: empty state-space (A.shape[0] == 0). "
+            "Linearise a model with at least one continuous state first."
+        )
+    A, B, C, D = _siso_extract(ls, input_idx, output_idx)
+    control = _import_control()
+    siso = control.ss(A, B, C, D)
+    # python-control 0.10 では ``root_locus_map`` が SISO 用、戻り値の構造は
+    # ``(roots, gains)`` を持つ ``ContourList``-like オブジェクト or tuple。
+    # ``rlocus`` (legacy) は figure を作る副作用ありなので ``root_locus_map`` を選択。
+    if k_range is None:
+        rl_data = control.root_locus_map(siso)
+    elif isinstance(k_range, tuple) and len(k_range) == 2:
+        # k_min, k_max を対数スケールで sweep
+        k_min, k_max = float(k_range[0]), float(k_range[1])
+        if k_min <= 0.0 or k_max <= k_min:
+            raise BlockSpecError(
+                f"root_locus: invalid k_range={k_range}; expect (k_min, k_max) with "
+                f"0 < k_min < k_max"
+            )
+        gains = np.logspace(np.log10(k_min), np.log10(k_max), 50)
+        rl_data = control.root_locus_map(siso, gains=gains)
+    else:
+        rl_data = control.root_locus_map(siso, gains=np.asarray(k_range, dtype=float))
+
+    roots = np.asarray(rl_data.loci, dtype=complex)
+    gains = np.asarray(rl_data.gains, dtype=float)
+    # python-control では loci shape が ``(n_K, n_states)``。numpy default 形式。
+    return RootLocus(
+        roots=roots,
+        gains=gains,
+        input_idx=int(input_idx),
+        output_idx=int(output_idx),
+    )

flode/blocks/__init__.py

@@ -0,0 +1,107 @@
+from .cast import Cast
+from .continuous import (
+    Derivative,
+    Integrator,
+    MimoTransferFunction,
+    StateSpace,
+    TransferFunction,
+)
+from .discontinuities import RateLimiter, Relay
+from .discrete import (
+    DiscreteIntegrator,
+    DiscreteStateSpace,
+    DiscreteTransferFunction,
+    RateTransition,
+    UnitDelay,
+    ZeroOrderHoldDirect,
+)
+from .logic import LogicalOperator, RelationalOperator
+from .lookup import (
+    InterpolationUsingPrelookup,
+    LookupTable1D,
+    LookupTable2D,
+    LookupTableND,
+    Prelookup,
+)
+from .mathops import (
+    Abs,
+    CompareToConstant,
+    CompareToZero,
+    DeadZone,
+    Divide,
+    Gain,
+    MathFunction,
+    MinMax,
+    Product,
+    Saturation,
+    Sign,
+    Sum,
+    TrigFunction,
+)
+from .pythonfunc import PythonFunction
+from .random_source import RandomSource
+from .rounding import Rounding
+from .routing import Demux, From, Goto, Merge, MultiportSwitch, Mux, Switch
+from .sinks import Display, Scope, Terminator, XYGraph
+from .sources import Clock, Constant, PulseGenerator, Ramp, Sine, Step
+from .transport_delay import TransportDelay
+from .userfunc import Fcn
+
+__all__ = [
+    "Abs",
+    "Cast",
+    "Clock",
+    "CompareToConstant",
+    "CompareToZero",
+    "Constant",
+    "DeadZone",
+    "Demux",
+    "Derivative",
+    "Display",
+    "DiscreteIntegrator",
+    "DiscreteStateSpace",
+    "DiscreteTransferFunction",
+    "Divide",
+    "Fcn",
+    "From",
+    "Gain",
+    "Goto",
+    "Integrator",
+    "InterpolationUsingPrelookup",
+    "LogicalOperator",
+    "LookupTable1D",
+    "LookupTable2D",
+    "LookupTableND",
+    "MathFunction",
+    "Merge",
+    "MimoTransferFunction",
+    "MinMax",
+    "MultiportSwitch",
+    "Mux",
+    "Prelookup",
+    "Product",
+    "PulseGenerator",
+    "PythonFunction",
+    "Ramp",
+    "RandomSource",
+    "RateLimiter",
+    "RateTransition",
+    "RelationalOperator",
+    "Relay",
+    "Rounding",
+    "Saturation",
+    "Scope",
+    "Sign",
+    "Sine",
+    "StateSpace",
+    "Step",
+    "Sum",
+    "Switch",
+    "Terminator",
+    "TransferFunction",
+    "TransportDelay",
+    "TrigFunction",
+    "UnitDelay",
+    "XYGraph",
+    "ZeroOrderHoldDirect",
+]

flode/blocks/_lti_utils.py

@@ -0,0 +1,121 @@
+"""LTI ブロック共通ユーティリティ (ADR-0006、ADR-0010 §(6))。
+
+連続版と離散版の SS / TF ブロックで共有する定数とヘルパーを置く。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from ..exceptions import BlockSpecError
+
+# ADR-0006 §(6): D 行列の最大絶対値がこの閾値を超えたら direct_feedthrough = True
+_DF_TOLERANCE = 1e-12
+
+
+def build_companion_form_siso(
+    numerator: npt.NDArray[Any], denominator: npt.NDArray[Any]
+) -> tuple[npt.NDArray[Any], npt.NDArray[Any], npt.NDArray[Any], npt.NDArray[Any]]:
+    """SISO 伝達関数 ``H(s) = num(s) / den(s)`` を controllable canonical form に変換。
+
+    ADR-0010 §(6) で予告された companion form 自前構築実装。``scipy.signal.tf2ss`` の
+    ゼロ多項式 (off-diagonal の `numerators[i][j] = [0.0]`) で BadCoefficients warning
+    を出す問題を回避する。MIMO 共通分母 TF を SISO ごとに realize して結合する用途
+    (`MimoTransferFunction`) で使う。
+
+    係数の慣習:
+        ``numerator``、``denominator`` は **s の降べき** で表現
+        (numpy / scipy convention)。例: ``[1, 2, 3]`` は ``s^2 + 2*s + 3``。
+
+    Controllable canonical form:
+        分母 ``d(s) = a_n s^n + a_{n-1} s^{n-1} + ... + a_1 s + a_0`` (a_n = 1 に正規化) と
+        分子 ``b(s) = b_n s^n + b_{n-1} s^{n-1} + ... + b_0`` に対し:
+
+        A = [[0, 1, 0, ..., 0],
+             [0, 0, 1, ..., 0],
+             ...
+             [0, 0, 0, ..., 1],
+             [-a_0, -a_1, ..., -a_{n-1}]]    shape (n, n)
+        B = [0, 0, ..., 1]^T                  shape (n, 1)
+        C = [b_0 - b_n*a_0, ..., b_{n-1} - b_n*a_{n-1}]  shape (1, n)
+        D = [b_n]                             shape (1, 1)
+
+        biproper (deg(num) == deg(den)) のとき D = b_n/a_n、strict proper のとき
+        D = 0 になる (b_n = 0)。
+
+    Args:
+        numerator: 分子多項式の係数 (shape ``(m+1,)``、``m = deg(num)``)。
+        denominator: 分母多項式の係数 (shape ``(n+1,)``、``n = deg(den)``)。
+
+    Returns:
+        (A, B, C, D) tuple。shape はそれぞれ ``(n, n)``、``(n, 1)``、``(1, n)``、``(1, 1)``。
+
+    Raises:
+        BlockSpecError: ``num`` / ``den`` が空、``den[0] == 0``、improper
+            (``deg(num) > deg(den)``) の場合。
+    """
+    num = np.asarray(numerator, dtype=float).ravel()
+    den = np.asarray(denominator, dtype=float).ravel()
+    if num.size == 0 or den.size == 0:
+        raise BlockSpecError("build_companion_form_siso: numerator/denominator must be non-empty")
+    if den[0] == 0.0:
+        raise BlockSpecError(
+            "build_companion_form_siso: leading coefficient of denominator must be non-zero"
+        )
+    deg_num = num.size - 1
+    deg_den = den.size - 1
+    if deg_num > deg_den:
+        raise BlockSpecError(
+            f"build_companion_form_siso: improper system "
+            f"(deg(num)={deg_num} > deg(den)={deg_den}). "
+            f"Only proper or biproper systems are supported."
+        )
+    n = deg_den
+    if n == 0:
+        # H(s) = b_0 / a_0 (定数ゲイン)。state 不要だが、本ヘルパーは状態を持つ
+        # SS 表現を返す契約なので呼び出し側で n>=1 のみを許可する想定。
+        raise BlockSpecError(
+            "build_companion_form_siso: deg(den)=0 (pure gain) is not supported by SS realization; "
+            "use a static block (e.g. Gain) instead"
+        )
+
+    # 分母を monic 化: a_n = 1
+    den_monic = den / den[0]
+    # a = [a_0, a_1, ..., a_{n-1}] (係数昇べきで参照しやすくするため反転)
+    # den_monic の格納は降べき: den_monic[0]=1, den_monic[1]=a_{n-1}, ..., den_monic[n]=a_0
+    # よって a_i = den_monic[n - i]
+    a_asc = den_monic[::-1].copy()  # a_asc[i] = a_i (昇べき)、a_asc[n]=1
+
+    # 分子を分母と同じ正規化で除して、長さを n+1 に左 0 パディング
+    num_normed = num / den[0]
+    if num_normed.size < n + 1:
+        num_padded = np.concatenate([np.zeros(n + 1 - num_normed.size, dtype=float), num_normed])
+    else:
+        num_padded = num_normed
+    # b_asc[i] = b_i (昇べき)、b_asc[n] = b_n (= biproper 時の D)
+    b_asc = num_padded[::-1].copy()
+
+    # A: companion matrix (controllable canonical form)
+    A = np.zeros((n, n), dtype=float)
+    if n > 1:
+        # 上三角の 1 つ上のサブダイアゴナルに 1 を配置
+        for i in range(n - 1):
+            A[i, i + 1] = 1.0
+    # 最終行: -a_0, -a_1, ..., -a_{n-1}
+    A[n - 1, :] = -a_asc[:n]
+
+    # B: 末尾要素のみ 1
+    B = np.zeros((n, 1), dtype=float)
+    B[n - 1, 0] = 1.0
+
+    # D: b_n (biproper のとき非ゼロ、proper のとき 0)
+    D = np.array([[b_asc[n]]], dtype=float)
+
+    # C: c_i = b_i - b_n * a_i (i = 0..n-1)、shape (1, n)
+    c_row = b_asc[:n] - b_asc[n] * a_asc[:n]
+    C = c_row.reshape(1, n)
+
+    return A, B, C, D

flode/blocks/cast.py

@@ -0,0 +1,66 @@
+"""``Cast`` — 実 dtype 変換ブロック (SPEC-0028 / ADR-0077 SM-D)。
+
+v0.56.0 で ``output_type`` (値の意味論、旧 SPEC-0026) は撤去され、型概念は
+``dtype`` に一本化された。``Cast`` は**常に実変換する**ブロックであり、恒等
+パススルー (旧 ``dtype="auto"``) は存在しない — 「置いたのに何も変わらない」
+Cast を許さないため。
+
+旧 ``output_type`` の等価機能は既存ブロックで表現する (schema 0.12 migration が
+自動変換する対応):
+
+* ``output_type="int"`` (偶数丸め) → :class:`~flode.blocks.rounding.Rounding`
+  (``mode="round"``)
+* ``output_type="bool"`` (``u != 0`` → 0/1) →
+  :class:`~flode.blocks.mathops.CompareToZero` (``op="!="``)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from ..core.block import Block
+from ..core.dtypes import DTYPE_VOCABULARY, cast_value
+from ..exceptions import BlockSpecError
+
+
+class Cast(Block):
+    """実 dtype 変換 ``y = cast(u, dtype)``。
+
+    出力は**実際にその numpy dtype** になる (SPEC-0028)。``dtype="float64"``
+    (既定) も恒等ではなく実変換 (``astype``)。float → 整数は**ゼロ方向切り捨て**、
+    nan → 0 / ±inf → 飽和は決定的 (規則の SSOT は
+    :func:`flode.core.dtypes.cast_value`)。
+
+    Cast を含むモデルは常に dtype 宣言モデルとして実行される
+    (:func:`flode.core.dtypes.has_declared_dtype`)。
+
+    Args:
+        dtype: 出力 dtype。``"float64"`` (既定) / ``"bool"`` / ``"uint8"`` /
+            ``"int32"`` / ``"int64"``。``"auto"`` は存在しない (Cast は常に変換)。
+
+    Raises:
+        BlockSpecError: ``dtype`` が語彙外。
+    """
+
+    _param_enums = {"dtype": DTYPE_VOCABULARY}
+
+    def __init__(
+        self,
+        dtype: str = "float64",
+        *,
+        id: str | None = None,
+        name: str | None = None,
+    ) -> None:
+        if dtype not in DTYPE_VOCABULARY:
+            raise BlockSpecError(f"Cast: dtype must be one of {DTYPE_VOCABULARY}, got {dtype!r}")
+        super().__init__(id=id, name=name, n_inputs=1, n_outputs=1)
+        self.dtype = dtype
+        self._params = {"dtype": dtype}
+
+    def output(self, t: float, x: npt.NDArray[Any], u: npt.NDArray[Any]) -> npt.NDArray[Any]:
+        # 実 dtype 変換 (SPEC-0028 §2.2)。float() を経由しないことで
+        # int64 の精度 (> 2^53) を守る。
+        return cast_value(np.asarray(u).reshape(-1)[:1], self.dtype)