apc-model-parser 0.1.0__py3-none-any.whl

model_parser/ir/model.py

@@ -0,0 +1,133 @@
+"""Canonical IR data model.
+
+The IR describes a model **scaffold** only: structure, declarations, and
+equations. Concrete numeric parameter values are carried as *defaults* for
+bootstrap convenience, but fitted parameter sets and execution scenarios
+(initial values, input trajectories, horizons) are deliberately *out of scope*
+here — they are sibling contracts (see ADR 0006 and the org contracts page).
+
+The model is a Pydantic v2 model so that the JSON Schema and structural
+validation come for free; semantic checks live in :mod:`model_parser.validation`.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from model_parser.ir.expr import Expr
+
+IR_VERSION = "0.1.0"
+"""SemVer of the IR schema. Major bumps require migration tooling and an ADR."""
+
+
+class Parameter(BaseModel):
+    """A time-independent model parameter declaration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    default: float | None = None
+    unit: str | None = None
+    description: str | None = None
+
+
+class Variable(BaseModel):
+    """A declared state, input, or output variable.
+
+    ``roles`` carries optional tags such as ``measured``, ``manipulated``,
+    ``disturbance``, or ``estimated``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    unit: str | None = None
+    description: str | None = None
+    roles: list[str] = Field(default_factory=list)
+
+
+class Local(BaseModel):
+    """A named intermediate expression (an algebraic/observed equation)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    expr: Expr
+    unit: str | None = None
+    description: str | None = None
+
+
+class DiffEq(BaseModel):
+    """A differential equation ``d(state)/dt = rhs``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    state: str
+    rhs: Expr
+
+
+class OutputEq(BaseModel):
+    """An output equation ``output = rhs``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    output: str
+    rhs: Expr
+
+
+class Equations(BaseModel):
+    """The differential and output equations of the scaffold."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    differential: list[DiffEq] = Field(default_factory=list)
+    outputs: list[OutputEq] = Field(default_factory=list)
+
+
+class ModelInfo(BaseModel):
+    """Identity and free-form metadata for the model."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str | None = None
+    source_version: str | None = None
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+
+class Provenance(BaseModel):
+    """Where this IR came from and which tool produced it."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tool: str
+    created_at: str
+    source_format: str | None = None
+    source_file: str | None = None
+    content_hash: str | None = None
+
+
+class IRModel(BaseModel):
+    """The canonical intermediate representation of a process-model scaffold."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ir_version: str = IR_VERSION
+    model: ModelInfo
+    independent_variable: str = "t"
+    parameters: list[Parameter] = Field(default_factory=list)
+    states: list[Variable] = Field(default_factory=list)
+    inputs: list[Variable] = Field(default_factory=list)
+    outputs: list[Variable] = Field(default_factory=list)
+    locals: list[Local] = Field(default_factory=list)
+    equations: Equations = Field(default_factory=Equations)
+    profiles: list[str] = Field(default_factory=lambda: ["julia-analysis"])
+    provenance: Provenance | None = None
+
+    def symbol_names(self) -> set[str]:
+        """Return all declared symbol names (states, inputs, outputs, params, locals)."""
+        names: set[str] = set()
+        for group in (self.states, self.inputs, self.outputs, self.parameters):
+            names |= {item.name for item in group}
+        names |= {local.name for local in self.locals}
+        return names

model_parser/schema.py

@@ -0,0 +1,29 @@
+"""JSON Schema export for the canonical IR.
+
+The schema is generated from the Pydantic model so there is a single source of
+truth for the IR shape. ``schemas/canonical-ir.schema.json`` is the committed,
+versioned artifact that other repositories and languages validate against.
+"""
+
+from __future__ import annotations
+
+import json
+
+from model_parser.ir import IR_VERSION, IRModel
+
+SCHEMA_ID = "https://advanced-process-control.github.io/model-parser/canonical-ir.schema.json"
+
+
+def ir_json_schema() -> dict:
+    """Return the JSON Schema for the canonical IR as a dict."""
+    schema = IRModel.model_json_schema()
+    schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+    schema["$id"] = SCHEMA_ID
+    schema["title"] = "Canonical Process-Model IR"
+    schema["x-ir-version"] = IR_VERSION
+    return schema
+
+
+def dumps_schema() -> str:
+    """Return the IR JSON Schema as a pretty JSON string."""
+    return json.dumps(ir_json_schema(), indent=2) + "\n"

model_parser/validation/__init__.py

@@ -0,0 +1,9 @@
+"""Validation: semantic and profile checks over a canonical IR."""
+
+from model_parser.validation.validators import (
+    Diagnostic,
+    ValidationReport,
+    validate_ir,
+)
+
+__all__ = ["Diagnostic", "ValidationReport", "validate_ir"]

model_parser/validation/validators.py

@@ -0,0 +1,195 @@
+"""Core and profile validators for the canonical IR.
+
+Structural validation (types, required fields) is handled by Pydantic at load
+time. This module adds *semantic* checks (do referenced symbols exist? are
+dimensions consistent?) and *profile* checks (is this IR within a backend's
+supported subset?). Validation answers "is this model acceptable?"; it is
+distinct from the conformance suite, which answers "do backends agree?".
+
+Profiles currently understood:
+
+- ``julia-analysis`` — permissive; the full IR is allowed.
+- ``realtime-cpp`` — restricted: only the deterministic operator/function subset
+  and no unsupported constructs (a first-cut placeholder for the PLC target).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from model_parser.ir import (
+    ALLOWED_OPS,
+    Call,
+    Expr,
+    IRModel,
+    free_symbols,
+)
+
+# Operators/functions a real-time C++ target is willing to emit deterministically.
+_REALTIME_CPP_OPS: frozenset[str] = frozenset(
+    {
+        "+",
+        "-",
+        "*",
+        "/",
+        "^",
+        "neg",
+        "<",
+        ">",
+        "<=",
+        ">=",
+        "==",
+        "!=",
+        "max",
+        "min",
+        "sqrt",
+        "exp",
+        "log",
+        "abs",
+        "ifelse",
+    }
+)
+
+_KNOWN_PROFILES: frozenset[str] = frozenset({"julia-analysis", "realtime-cpp"})
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """A single validation finding."""
+
+    level: str  # "ERROR" | "WARN"
+    code: str
+    message: str
+
+
+@dataclass
+class ValidationReport:
+    """The result of validating an IR: a list of diagnostics."""
+
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+
+    @property
+    def errors(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.level == "ERROR"]
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.level == "WARN"]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def _add(self, level: str, code: str, message: str) -> None:
+        self.diagnostics.append(Diagnostic(level=level, code=code, message=message))
+
+
+def _iter_ops(expr: Expr) -> list[str]:
+    if isinstance(expr, Call):
+        ops = [expr.op]
+        for arg in expr.args:
+            ops.extend(_iter_ops(arg))
+        return ops
+    return []
+
+
+def _all_expressions(ir: IRModel) -> list[tuple[str, Expr]]:
+    items: list[tuple[str, Expr]] = []
+    for local in ir.locals:
+        items.append((f"local {local.name}", local.expr))
+    for diff in ir.equations.differential:
+        items.append((f"d({diff.state})/dt", diff.rhs))
+    for out in ir.equations.outputs:
+        items.append((f"output {out.output}", out.rhs))
+    return items
+
+
+def validate_ir(ir: IRModel, *, profile: str | None = None) -> ValidationReport:
+    """Validate ``ir`` semantically and, optionally, against a backend ``profile``."""
+    report = ValidationReport()
+    declared = ir.symbol_names()
+
+    # Duplicate declarations.
+    seen: set[str] = set()
+    for group in (ir.states, ir.inputs, ir.outputs, ir.parameters, ir.locals):
+        for item in group:
+            if item.name in seen:
+                report._add(
+                    "ERROR", "duplicate-symbol", f"symbol {item.name!r} is declared more than once"
+                )
+            seen.add(item.name)
+
+    # Referenced-but-undeclared symbols.
+    for label, expr in _all_expressions(ir):
+        for ref in sorted(free_symbols(expr)):
+            if ref not in declared:
+                report._add(
+                    "ERROR", "undeclared-symbol", f"{label} references undeclared symbol {ref!r}"
+                )
+        for op in _iter_ops(expr):
+            if op not in ALLOWED_OPS:
+                report._add("ERROR", "unknown-op", f"{label} uses unknown operator/function {op!r}")
+
+    # Every state needs a differential equation; outputs need output equations.
+    diff_states = {d.state for d in ir.equations.differential}
+    for state in ir.states:
+        if state.name not in diff_states:
+            report._add(
+                "WARN",
+                "missing-state-equation",
+                f"state {state.name!r} has no differential equation",
+            )
+    out_defs = {o.output for o in ir.equations.outputs}
+    for out in ir.outputs:
+        if out.name not in out_defs:
+            report._add(
+                "WARN", "missing-output-equation", f"output {out.name!r} has no output equation"
+            )
+
+    # Local ordering / cyclic dependency check (locals must be resolvable in order).
+    _check_local_ordering(ir, report)
+
+    if profile is not None:
+        _validate_profile(ir, profile, report)
+
+    return report
+
+
+def _check_local_ordering(ir: IRModel, report: ValidationReport) -> None:
+    base = (
+        {v.name for v in ir.states} | {v.name for v in ir.inputs} | {p.name for p in ir.parameters}
+    )
+    available = set(base)
+    pending = {local.name for local in ir.locals}
+    for local in ir.locals:
+        deps = free_symbols(local.expr) & pending
+        unresolved = {d for d in deps if d not in available and d != local.name}
+        if unresolved:
+            report._add(
+                "WARN",
+                "local-ordering",
+                f"local {local.name!r} references later/cyclic locals "
+                f"{sorted(unresolved)}; backends may require topological ordering",
+            )
+        available.add(local.name)
+
+
+def _validate_profile(ir: IRModel, profile: str, report: ValidationReport) -> None:
+    if profile not in _KNOWN_PROFILES:
+        report._add(
+            "WARN",
+            "unknown-profile",
+            f"profile {profile!r} is not recognized; skipping profile checks",
+        )
+        return
+    if profile == "julia-analysis":
+        return  # permissive
+    if profile == "realtime-cpp":
+        for label, expr in _all_expressions(ir):
+            for op in _iter_ops(expr):
+                if op not in _REALTIME_CPP_OPS:
+                    report._add(
+                        "ERROR",
+                        "profile-realtime-cpp",
+                        f"{label} uses {op!r}, not in the realtime-cpp subset",
+                    )