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

model_parser/frontends/expr_parser.py

@@ -0,0 +1,183 @@
+"""Parse ExprTk-style expression strings into the canonical expression IR.
+
+This is a small, explicit tokenizer + precedence-climbing parser. It exists
+instead of regex string rewrites so that operator precedence, associativity,
+and conditional semantics are defined in *one* place (ADR 0003). The output is
+an :data:`model_parser.ir.expr.Expr` tree that every backend lowers from.
+
+Supported surface (the ExprTk subset used by the authoring INI format):
+
+- numeric literals (``1``, ``1.5``, ``1e-3``);
+- identifiers (symbol references);
+- binary operators ``+ - * / ^`` and unary minus;
+- comparisons ``< > <= >= == !=``;
+- function calls ``f(a, b, ...)``;
+- the ExprTk spellings ``pow(a, b)`` and ``if(c, a, b)``, normalized to ``^``
+  and ``ifelse`` respectively.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from model_parser.ir.expr import Call, Expr, Num, Sym
+
+# ExprTk function/operator spellings that map onto canonical IR op names.
+_FUNCTION_ALIASES: dict[str, str] = {"pow": "^", "if": "ifelse"}
+
+# Binary operators: name -> (left binding power, right binding power).
+# Right binding power lower than left means right-associative (used for ``^``).
+_BINARY: dict[str, tuple[int, int]] = {
+    "==": (10, 11),
+    "!=": (10, 11),
+    "<": (10, 11),
+    ">": (10, 11),
+    "<=": (10, 11),
+    ">=": (10, 11),
+    "+": (20, 21),
+    "-": (20, 21),
+    "*": (30, 31),
+    "/": (30, 31),
+    "^": (51, 50),
+}
+
+_UNARY_BP = 40
+
+_TOKEN_RE = re.compile(
+    r"""
+    \s*(?:
+        (?P<number>\d+\.\d+(?:[eE][+-]?\d+)?|\d+(?:[eE][+-]?\d+)?|\.\d+)
+      | (?P<ident>[A-Za-z_]\w*)
+      | (?P<op><=|>=|==|!=|[-+*/^<>(),])
+    )
+    """,
+    re.VERBOSE,
+)
+
+
+class ExprParseError(ValueError):
+    """Raised when an expression string cannot be parsed."""
+
+
+@dataclass(frozen=True)
+class _Token:
+    kind: str  # "number" | "ident" | "op" | "end"
+    text: str
+    pos: int
+
+
+def _tokenize(source: str) -> list[_Token]:
+    tokens: list[_Token] = []
+    pos = 0
+    n = len(source)
+    while pos < n:
+        if source[pos].isspace():
+            pos += 1
+            continue
+        match = _TOKEN_RE.match(source, pos)
+        if match is None or match.start() == match.end():
+            raise ExprParseError(
+                f"unexpected character {source[pos]!r} at position {pos} in {source!r}"
+            )
+        kind = match.lastgroup
+        assert kind is not None
+        text = match.group(kind)
+        tokens.append(_Token(kind=kind, text=text, pos=match.start(kind)))
+        pos = match.end()
+    tokens.append(_Token(kind="end", text="", pos=n))
+    return tokens
+
+
+class _Parser:
+    def __init__(self, source: str) -> None:
+        self.source = source
+        self.tokens = _tokenize(source)
+        self.index = 0
+
+    @property
+    def current(self) -> _Token:
+        return self.tokens[self.index]
+
+    def advance(self) -> _Token:
+        token = self.tokens[self.index]
+        self.index += 1
+        return token
+
+    def expect_op(self, text: str) -> None:
+        token = self.current
+        if token.kind != "op" or token.text != text:
+            raise ExprParseError(
+                f"expected {text!r} but found {token.text!r} at position "
+                f"{token.pos} in {self.source!r}"
+            )
+        self.advance()
+
+    def parse(self) -> Expr:
+        expr = self._parse_expr(0)
+        if self.current.kind != "end":
+            raise ExprParseError(
+                f"unexpected trailing token {self.current.text!r} at position "
+                f"{self.current.pos} in {self.source!r}"
+            )
+        return expr
+
+    def _parse_expr(self, min_bp: int) -> Expr:
+        left = self._parse_prefix()
+        while True:
+            token = self.current
+            if token.kind != "op" or token.text not in _BINARY:
+                break
+            left_bp, right_bp = _BINARY[token.text]
+            if left_bp < min_bp:
+                break
+            self.advance()
+            right = self._parse_expr(right_bp)
+            left = Call(op=token.text, args=[left, right])
+        return left
+
+    def _parse_prefix(self) -> Expr:
+        token = self.current
+        if token.kind == "op" and token.text == "-":
+            self.advance()
+            operand = self._parse_expr(_UNARY_BP)
+            return Call(op="neg", args=[operand])
+        if token.kind == "op" and token.text == "+":
+            self.advance()
+            return self._parse_expr(_UNARY_BP)
+        if token.kind == "op" and token.text == "(":
+            self.advance()
+            inner = self._parse_expr(0)
+            self.expect_op(")")
+            return inner
+        if token.kind == "number":
+            self.advance()
+            return Num(value=float(token.text))
+        if token.kind == "ident":
+            self.advance()
+            if self.current.kind == "op" and self.current.text == "(":
+                return self._parse_call(token.text)
+            return Sym(name=token.text)
+        raise ExprParseError(
+            f"unexpected token {token.text!r} at position {token.pos} in {self.source!r}"
+        )
+
+    def _parse_call(self, name: str) -> Expr:
+        self.expect_op("(")
+        args: list[Expr] = []
+        if not (self.current.kind == "op" and self.current.text == ")"):
+            args.append(self._parse_expr(0))
+            while self.current.kind == "op" and self.current.text == ",":
+                self.advance()
+                args.append(self._parse_expr(0))
+        self.expect_op(")")
+        op = _FUNCTION_ALIASES.get(name, name)
+        return Call(op=op, args=args)
+
+
+def parse_expression(source: str) -> Expr:
+    """Parse a single ExprTk-style expression string into an IR expression tree."""
+    text = source.strip().rstrip(";").strip()
+    if not text:
+        raise ExprParseError("empty expression")
+    return _Parser(text).parse()

model_parser/frontends/exprtk_ini.py

@@ -0,0 +1,204 @@
+"""ExprTk INI frontend: parse an INI-style model file into the canonical IR.
+
+This implements the ``parse`` + ``normalize`` transformations for the INI
+authoring format used by the existing MPC / simulation toolchain. The grammar is
+section-oriented:
+
+- ``[ModelInfo]``        — ``Name``, ``Description``, ``Version`` key/values.
+- ``[Dimensions]``       — ``num_states``, ``num_inputs``, ``num_outputs``.
+- ``[Parameters]``       — ``name = value`` with optional trailing ``; comment``.
+- ``[StateEquationLocals]`` — ``var name := expr;`` intermediate expressions.
+- ``[StateEquations]``   — ``dxN = expr`` differential equations.
+- ``[OutputEquations]``  — ``yN = expr`` plus inline ``name := expr`` locals.
+- ``[x0]`` / ``[u0]``    — initial values. **Dropped from the scaffold** with a
+  warning: initial values belong to a scenario, not the model scaffold
+  (org contracts §3). They bootstrap simulation but are not IR semantics.
+
+States are named ``x0..x{n-1}``, inputs ``u0..``, and outputs ``y0..`` to match
+the authoring convention; locals keep their authored names.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from model_parser.frontends.expr_parser import parse_expression
+from model_parser.ir import (
+    DiffEq,
+    Equations,
+    IRModel,
+    Local,
+    ModelInfo,
+    OutputEq,
+    Parameter,
+    Provenance,
+    Variable,
+)
+
+SOURCE_FORMAT = "exprtk-ini"
+
+_SECTION_RE = re.compile(r"^\[(.+)\]$")
+_KV_RE = re.compile(r"^(\S+)\s*=\s*(.+)$")
+_LOCAL_RE = re.compile(r"^(?:var\s+)?(\w+)\s*:=\s*(.+)$")
+_DIFF_RE = re.compile(r"^dx(\d+)\s*=\s*(.+)$")
+_OUTPUT_RE = re.compile(r"^y(\d+)\s*=\s*(.+)$")
+
+
+class IniParseError(ValueError):
+    """Raised when an INI model file cannot be parsed."""
+
+
+@dataclass
+class ParseResult:
+    """The outcome of parsing an authoring file: the IR plus diagnostics."""
+
+    ir: IRModel
+    warnings: list[str] = field(default_factory=list)
+
+
+def _strip_comment(line: str) -> str:
+    """Strip a trailing ``; ...`` comment / statement terminator from a line.
+
+    A leading ``;`` means the whole line is a comment. Otherwise everything from
+    the first ``;`` (statement terminator or comment) onward is removed; the
+    authoring format never embeds ``;`` inside an expression.
+    """
+    stripped = line.strip()
+    if not stripped or stripped[0] == ";":
+        return ""
+    idx = stripped.find(";")
+    return stripped if idx < 0 else stripped[:idx].strip()
+
+
+def parse_ini_sections(text: str) -> dict[str, list[str]]:
+    """Split INI text into a mapping of section name -> content lines."""
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    for raw in text.splitlines():
+        line = _strip_comment(raw)
+        if not line:
+            continue
+        match = _SECTION_RE.match(line)
+        if match is not None:
+            current = match.group(1)
+            sections.setdefault(current, [])
+        elif current is not None:
+            sections[current].append(line)
+    return sections
+
+
+def _parse_kv(lines: list[str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for line in lines:
+        match = _KV_RE.match(line)
+        if match is not None:
+            result[match.group(1)] = match.group(2).strip()
+    return result
+
+
+def parse_ini_text(text: str, *, source_file: str | None = None) -> ParseResult:
+    """Parse INI model text into an :class:`IRModel` with diagnostics."""
+    sections = parse_ini_sections(text)
+    warnings: list[str] = []
+
+    info = _parse_kv(sections.get("ModelInfo", []))
+    dims = _parse_kv(sections.get("Dimensions", []))
+
+    def _dim(key: str) -> int:
+        if key not in dims:
+            raise IniParseError(f"[Dimensions] missing required key {key!r}")
+        return int(dims[key])
+
+    n_states = _dim("num_states")
+    n_inputs = _dim("num_inputs")
+    n_outputs = _dim("num_outputs")
+
+    states = [Variable(name=f"x{i}") for i in range(n_states)]
+    inputs = [Variable(name=f"u{i}") for i in range(n_inputs)]
+    outputs = [Variable(name=f"y{i}") for i in range(n_outputs)]
+
+    parameters: list[Parameter] = []
+    for line in sections.get("Parameters", []):
+        match = _KV_RE.match(line)
+        if match is None:
+            warnings.append(f"ignored unparsable parameter line: {line!r}")
+            continue
+        parameters.append(Parameter(name=match.group(1), default=float(match.group(2).strip())))
+
+    locals_list: list[Local] = []
+    for line in sections.get("StateEquationLocals", []):
+        match = _LOCAL_RE.match(line)
+        if match is None:
+            raise IniParseError(f"cannot parse local line: {line!r}")
+        locals_list.append(Local(name=match.group(1), expr=parse_expression(match.group(2))))
+
+    differential: list[DiffEq] = []
+    for line in sections.get("StateEquations", []):
+        match = _DIFF_RE.match(line)
+        if match is None:
+            warnings.append(f"ignored unparsable state equation: {line!r}")
+            continue
+        idx = int(match.group(1))
+        differential.append(DiffEq(state=f"x{idx}", rhs=parse_expression(match.group(2))))
+
+    output_eqs: list[OutputEq] = []
+    for line in sections.get("OutputEquations", []):
+        out_match = _OUTPUT_RE.match(line)
+        if out_match is not None:
+            idx = int(out_match.group(1))
+            output_eqs.append(OutputEq(output=f"y{idx}", rhs=parse_expression(out_match.group(2))))
+            continue
+        local_match = _LOCAL_RE.match(line)
+        if local_match is not None:
+            locals_list.append(
+                Local(
+                    name=local_match.group(1),
+                    expr=parse_expression(local_match.group(2)),
+                )
+            )
+            continue
+        warnings.append(f"ignored unparsable output line: {line!r}")
+
+    for section in ("x0", "u0"):
+        if sections.get(section):
+            warnings.append(
+                f"dropped [{section}] initial values from the scaffold: initial "
+                "values belong to a scenario, not the model IR"
+            )
+
+    ir = IRModel(
+        model=ModelInfo(
+            name=info.get("Name", "unnamed_model"),
+            description=info.get("Description"),
+            source_version=info.get("Version"),
+        ),
+        parameters=parameters,
+        states=states,
+        inputs=inputs,
+        outputs=outputs,
+        locals=locals_list,
+        equations=Equations(differential=differential, outputs=output_eqs),
+        provenance=Provenance(
+            tool=_tool_id(),
+            created_at=datetime.now(UTC).isoformat(),
+            source_format=SOURCE_FORMAT,
+            source_file=source_file,
+        ),
+    )
+    return ParseResult(ir=ir, warnings=warnings)
+
+
+def parse_ini_file(path: str) -> ParseResult:
+    """Parse an INI model file from disk into an :class:`IRModel`."""
+    from pathlib import Path
+
+    text = Path(path).read_text(encoding="utf-8")
+    return parse_ini_text(text, source_file=str(path))
+
+
+def _tool_id() -> str:
+    from model_parser import __version__
+
+    return f"model-parser@{__version__}"

model_parser/io.py

@@ -0,0 +1,48 @@
+"""Load, save, and hash canonical IR files.
+
+IR files are JSON. Each IR carries a content hash over its semantic body
+(everything except the ``provenance`` block, which itself stores the hash) so
+that downstream artifacts can reference a scaffold by hash rather than by path
+(org contract: "hashes over file paths").
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from model_parser.ir import IRModel
+
+
+def compute_content_hash(ir: IRModel) -> str:
+    """Return the SHA-256 hash of the IR's semantic body (excluding provenance)."""
+    body = ir.model_dump(mode="json", exclude={"provenance"})
+    canonical = json.dumps(body, sort_keys=True, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def with_content_hash(ir: IRModel) -> IRModel:
+    """Return a copy of ``ir`` with its provenance ``content_hash`` populated."""
+    digest = compute_content_hash(ir)
+    if ir.provenance is None:
+        return ir
+    updated = ir.model_copy(deep=True)
+    updated.provenance.content_hash = digest
+    return updated
+
+
+def dumps_ir(ir: IRModel) -> str:
+    """Serialize an IR to a stable, pretty JSON string."""
+    return json.dumps(ir.model_dump(mode="json"), indent=2, sort_keys=False) + "\n"
+
+
+def save_ir(ir: IRModel, path: str | Path) -> None:
+    """Write an IR to ``path`` as JSON."""
+    Path(path).write_text(dumps_ir(ir), encoding="utf-8")
+
+
+def load_ir(path: str | Path) -> IRModel:
+    """Load and structurally validate an IR JSON file from ``path``."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    return IRModel.model_validate(data)

model_parser/ir/__init__.py

@@ -0,0 +1,55 @@
+"""Canonical IR: data model and expression tree."""
+
+from model_parser.ir.expr import (
+    ALLOWED_OPS,
+    ARITHMETIC_OPS,
+    COMPARISON_OPS,
+    FUNCTIONS,
+    UNARY_OPS,
+    Call,
+    Expr,
+    Num,
+    Sym,
+    call,
+    free_symbols,
+    num,
+    sym,
+)
+from model_parser.ir.model import (
+    IR_VERSION,
+    DiffEq,
+    Equations,
+    IRModel,
+    Local,
+    ModelInfo,
+    OutputEq,
+    Parameter,
+    Provenance,
+    Variable,
+)
+
+__all__ = [
+    "ALLOWED_OPS",
+    "ARITHMETIC_OPS",
+    "COMPARISON_OPS",
+    "FUNCTIONS",
+    "UNARY_OPS",
+    "Call",
+    "DiffEq",
+    "Equations",
+    "Expr",
+    "IRModel",
+    "IR_VERSION",
+    "Local",
+    "ModelInfo",
+    "Num",
+    "OutputEq",
+    "Parameter",
+    "Provenance",
+    "Sym",
+    "Variable",
+    "call",
+    "free_symbols",
+    "num",
+    "sym",
+]

model_parser/ir/expr.py

@@ -0,0 +1,87 @@
+"""Expression IR: a small, explicit, backend-independent expression tree.
+
+The expression sub-language is represented as a tagged tree rather than as a
+backend-specific string. This is the core of ADR 0003 (explicit expression IR):
+every backend lowers from the *same* tree, so conditional and numeric semantics
+are defined once instead of being re-derived per target via string rewrites.
+
+Three node kinds exist:
+
+- :class:`Num` — a numeric literal.
+- :class:`Sym` — a reference to a declared symbol (state, input, output,
+  parameter, or local).
+- :class:`Call` — an operator or function applied to argument expressions. All
+  arithmetic operators, comparisons, unary negation, and named functions are
+  represented uniformly as calls keyed by :attr:`Call.op`.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+# Canonical operator/function names used in ``Call.op``. Frontends normalize
+# authoring-format spellings (e.g. ExprTk ``pow``/``if``) into these names so the
+# IR carries one vocabulary. Backends own the mapping from these names to their
+# own syntax. Keep this list aligned with ``docs/design/ir-specification.md``.
+ARITHMETIC_OPS: frozenset[str] = frozenset({"+", "-", "*", "/", "^"})
+UNARY_OPS: frozenset[str] = frozenset({"neg"})
+COMPARISON_OPS: frozenset[str] = frozenset({"<", ">", "<=", ">=", "==", "!="})
+FUNCTIONS: frozenset[str] = frozenset({"max", "min", "sqrt", "exp", "log", "abs", "ifelse"})
+ALLOWED_OPS: frozenset[str] = ARITHMETIC_OPS | UNARY_OPS | COMPARISON_OPS | FUNCTIONS
+
+
+class Num(BaseModel):
+    """A numeric literal."""
+
+    kind: Literal["num"] = "num"
+    value: float
+
+
+class Sym(BaseModel):
+    """A reference to a declared symbol by canonical name."""
+
+    kind: Literal["sym"] = "sym"
+    name: str
+
+
+class Call(BaseModel):
+    """An operator or function applied to argument expressions."""
+
+    kind: Literal["call"] = "call"
+    op: str
+    args: list[Expr] = Field(default_factory=list)
+
+
+Expr = Annotated[Num | Sym | Call, Field(discriminator="kind")]
+"""Any expression node, discriminated on the ``kind`` tag."""
+
+Call.model_rebuild()
+
+
+def num(value: float) -> Num:
+    """Construct a numeric literal node."""
+    return Num(value=value)
+
+
+def sym(name: str) -> Sym:
+    """Construct a symbol-reference node."""
+    return Sym(name=name)
+
+
+def call(op: str, *args: Expr) -> Call:
+    """Construct an operator/function call node."""
+    return Call(op=op, args=list(args))
+
+
+def free_symbols(expr: Expr) -> set[str]:
+    """Return the set of symbol names referenced anywhere in ``expr``."""
+    if isinstance(expr, Sym):
+        return {expr.name}
+    if isinstance(expr, Call):
+        out: set[str] = set()
+        for arg in expr.args:
+            out |= free_symbols(arg)
+        return out
+    return set()