dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/backends/common/statistics.py

@@ -0,0 +1,39 @@
+"""The zero-count rule: a system-size list's summaries, written and read in
+one place."""
+
+from __future__ import annotations
+
+SUMMARIES = ("count", "total", "max")
+
+
+def summaries(key: str, values: list[int]) -> dict[str, int]:
+    """`<key>_count/_total/_max` of a system-size list — 0, 0, 0 for an empty
+    one. The parser writes these ALWAYS: code that writes never leaves a
+    field out (a reader would have to guess what its absence means)."""
+    return {
+        f"{key}_count": len(values),
+        f"{key}_total": sum(values),
+        f"{key}_max": max(values, default=0),
+    }
+
+
+def sizes_systems(value: object) -> bool:
+    """Is ``value`` a system-size list — the sizes the parser summarizes
+    (``nonlinear: [3, 5, 1]``, or ``[]``)? A list of whole numbers; a list
+    of names (``state_names``) is not one."""
+    return isinstance(value, list) and all(
+        isinstance(v, int) and not isinstance(v, bool) for v in value
+    )
+
+
+def read_summary(category: dict, key: str) -> int | None:
+    """A summary a baseline written before `summaries` lacks: 0 where
+    `key` is `<list>_count|_total|_max` and `<list>` is present AND EMPTY in
+    the same category. Anything else stays missing — a stats path absent
+    from a side hard-fails its leaf (tree_eval: a path that silently scored
+    0 would be a green test measuring nothing), and only an empty list
+    says what its summary is."""
+    base, _, field = key.rpartition("_")
+    if field not in SUMMARIES or key in category:
+        return None
+    return 0 if category.get(base) == [] else None

dstf/backends/cross_backend.py

@@ -0,0 +1,193 @@
+"""Cross-backend orchestration (4.B.3). **EXPERIMENTAL** (D65).
+
+Helpers that chain backends to produce a **soft_check** baseline (D66).
+Today the only chain is **dymola-via-fmpy**: Dymola exports the model as
+an FMU, FMPy simulates the FMU, and the FMPy result is stored as a
+soft_check (`"dymola-via-fmpy"` by convention) that MetricTree leaves
+can score against via ``"against": "dymola-via-fmpy"`` — always inside
+a ``warn`` combinator, enforced by the validator.
+
+EXPERIMENTAL — scope limits (D65):
+  - **Semantics**: the chain is only meaningful for *autonomous* tests —
+    models with no external inputs, no python driver stepping the FMU, no
+    need to choose between co-simulation and model-exchange. For a test
+    that is fundamentally "a python script driving an FMU with a scheduled
+    input sequence", this chain will produce a baseline whose values do
+    NOT reflect what the test actually does — the comparison against the
+    primary run becomes meaningless. Opt-in via ``requested_baselines``
+    should be reserved for autonomous tests until generalization lands.
+  - **Validation**: the Dymola export step requires Windows + Dymola + the
+    FMI export license option. Cannot be exercised in CI on Linux WSL —
+    tests mock the `export_fmu` step. End-to-end validation on real Dymola
+    is deferred to a dedicated phase.
+
+Generalization (input schedules, CS/ME choice, start-value overrides,
+python-driver tests) is deferred to a future "FMU-path semantic gap
+closure" phase.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import replace
+from pathlib import Path
+
+from ..config import Config
+from ..discovery.test_registry import TestModel
+from ..storage.reference_store import ReferenceStore
+from .base import Backend
+from .types import Capability, TestResult
+
+logger = logging.getLogger(__name__)
+
+
+# Convention name for the cross-backend baseline. Users reference this via
+# ``{"metric": ..., "against": "dymola-via-fmpy"}`` in a MetricTree leaf.
+CROSS_BACKEND_BASELINE_NAME = "dymola-via-fmpy"
+
+
+def produce_dymola_via_fmpy_baseline(
+    test: TestModel,
+    primary_backend: Backend,
+    config: Config,
+    store: ReferenceStore,
+    *,
+    fmu_dir: Path | None = None,
+) -> bool:
+    """Run the Dymola → FMPy chain for one test and store the result.
+
+    Steps:
+      1. ``primary_backend.export_fmu(test, fmu_dir)`` produces a .fmu.
+      2. Build a clone of the test pointing at the FMU.
+      3. Construct an :class:`FmpyBackend` (config tweaked to source_type="fmu").
+      4. Run FMPy on the FMU + read back the result.
+      5. Persist the FMPy result as a soft_check via
+         :meth:`ReferenceStore.add_soft_check` (D66).
+
+    Returns True on success, False if any step fails (logs the reason).
+    Requires the model to already have a primary baseline on disk —
+    soft_checks augment primary, they do not replace it.
+    """
+    work = fmu_dir or (config.work_dir / f"chain_{test.model_id.replace('.', '_')}")
+
+    # Step 1 — export the FMU via the primary backend. Gate on the declared
+    # capability rather than catching NotImplementedError: "this backend
+    # can't export" is a configuration fact knowable before we do any work,
+    # and the flag is the framework's single source of truth for it (batch
+    # Dymola, for instance, can't — only the persistent variant can).
+    if Capability.FMU_EXPORT not in primary_backend.capabilities:
+        logger.warning(
+            "cross-backend chain: %s does not declare Capability.FMU_EXPORT; "
+            "skipping %s",
+            type(primary_backend).__name__,
+            test.model_id,
+        )
+        return False
+    work.mkdir(parents=True, exist_ok=True)
+    try:
+        fmu_path = primary_backend.export_fmu(test, work)
+    except (NotImplementedError, RuntimeError) as exc:
+        logger.warning(
+            "cross-backend chain: export_fmu failed for %s: %s",
+            test.model_id,
+            exc,
+        )
+        return False
+
+    # Step 2 — clone the test with source_file pointing at the new FMU.
+    chain_test = replace(test, source_file=fmu_path)
+
+    # Step 3 — construct an FmpyBackend. We don't go through get_backend()
+    # because that uses config.backend; we just want a temporary
+    # FMPy backend regardless of what the primary is.
+    from .fmpy.backend import FmpyBackend
+
+    fmpy_config = replace(
+        config,
+        backend_name="FMPy",
+        source_type="fmu",
+        # Reuse work_dir; FmpyBackend persists result.npz under <work_dir>/<test_key>.
+    )
+    try:
+        fmpy_backend = FmpyBackend(fmpy_config)
+    except RuntimeError as exc:
+        # The constructor's "fmpy not installed" is a RuntimeError, the same
+        # unavailable-backend signal `backends._instantiate` translates.
+        logger.warning(
+            "cross-backend chain: FMPy not installed (%s); skipping %s",
+            exc,
+            test.model_id,
+        )
+        return False
+
+    # Step 4 — run FMPy on the exported FMU. Use a deterministic test_key
+    # that doesn't collide with the primary run's keys.
+    test_key = f"chain_{test.model_id.replace('.', '_')}"
+    run_result = fmpy_backend.run_single_test(
+        chain_test,
+        test_key,
+        index=1,
+        total=1,
+    )
+    if not run_result.success:
+        logger.warning(
+            "cross-backend chain: FMPy sim failed for %s: %s",
+            test.model_id,
+            run_result.error_message,
+        )
+        return False
+
+    fmpy_result: TestResult = fmpy_backend.read_result(chain_test, test_key, run_result)
+    if not fmpy_result.success:
+        logger.warning(
+            "cross-backend chain: FMPy read_result failed for %s: %s",
+            test.model_id,
+            fmpy_result.error_message,
+        )
+        return False
+
+    # Step 5 — store FMPy result as a named baseline.
+    if not fmpy_result.variables:
+        logger.warning(
+            "cross-backend chain: FMPy produced no variables for %s; "
+            "skipping baseline write",
+            test.model_id,
+        )
+        return False
+
+    # All FMPy variables share the same time vector; pull from the first.
+    time_vec = list(fmpy_result.variables[0].time)
+    variables_payload = [
+        {
+            "index": v.index,
+            "name": v.name,
+            "expression": v.expression,
+            "values": list(v.values),
+        }
+        for v in fmpy_result.variables
+    ]
+    try:
+        store.add_soft_check(
+            test.model_id,
+            CROSS_BACKEND_BASELINE_NAME,
+            time=time_vec,
+            variables=variables_payload,
+            provenance={
+                "source": "cross-backend chain",
+                "primary_backend": type(primary_backend).__name__,
+                "secondary_backend": "FMPy",
+                "fmu_path": str(fmu_path),
+            },
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        # review 2026-07-06 (finding 76): add_soft_check also raises
+        # ValueError (e.g. name collides with an existing companion) — the
+        # documented contract is "failures are logged + skipped", not an
+        # abort of the whole run after simulation completed.
+        logger.warning(
+            "cross-backend chain: cannot store baseline for %s: %s",
+            test.model_id,
+            exc,
+        )
+        return False
+    return True

dstf/backends/dymola/__init__.py

@@ -0,0 +1,5 @@
+"""Dymola backend."""
+
+from .backend import DymolaBackend, DymolaConfig
+
+__all__ = ["DymolaConfig", "DymolaBackend"]