From a87e3ae2e4f6df5f36f6cb3dd1741eb0909bca4f Mon Sep 17 00:00:00 2001 From: Evan Gress <106449014+evangress@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:27:41 -0500 Subject: [PATCH 1/4] Close the corpus holes: printf/fprintf/sprintf/disp, filter, stdout verify io/printf (new, mechanical both ways) turns a literal printf format into an f-string field by field and carries out the format's recycling statically; one array argument recycles it per element or per column as a loop (or a "".join for sprintf). %d of a value not known to be a whole number, %s of a number, %x/%c/%u, * widths, file ids other than 1, empty arrays and disp of a number are declined by name. io/display keeps the missing-semicolon case and stays guided. builtins/filter (new) is scipy.signal.lfilter, axis=0 for a matrix; SciPy becomes a dependency. types/double (new) covers double()/logical() and x.astype(float)/astype(bool), which the filter translation needs. verify gains `% dualect: stdout`, comparing printed text exactly (the .m side captured with evalc), and `% dualect: shape r` for random values; translations that print add the directive themselves. -0 now keeps its sign. corpus/beam_deflection.m and corpus/signal_filter.m translate fully and verify in both directions. Co-Authored-By: Claude Opus 5.5 --- docs/design.md | 7 + dualect/compare.py | 23 + dualect/emit.py | 25 +- dualect/infer.py | 8 + dualect/lift.py | 15 +- dualect/lower.py | 17 +- dualect/pipeline.py | 11 +- dualect/pyconstructs.py | 10 + dualect/pyinfer.py | 24 +- dualect/runners.py | 54 ++- dualect/verify.py | 115 ++++- llms.txt | 5 +- pyproject.toml | 3 + rules/builtins/filter/cases/basic.m | 8 + rules/builtins/filter/cases/basic.py | 11 + rules/builtins/filter/cases/columns.m | 5 + rules/builtins/filter/cases/columns.py | 8 + rules/builtins/filter/rule.yaml | 40 ++ rules/builtins/filter/translate.py | 99 ++++ rules/io/display/cases/basic.m | 8 +- rules/io/display/cases/basic.py | 9 +- rules/io/display/rule.yaml | 40 +- rules/io/printf/cases/basic.m | 13 + rules/io/printf/cases/basic.py | 13 + rules/io/printf/cases/integers.m | 6 + rules/io/printf/cases/integers.py | 8 + rules/io/printf/cases/recycling.m | 9 + rules/io/printf/cases/recycling.py | 13 + rules/io/printf/rule.yaml | 53 ++ rules/io/printf/translate.py | 613 ++++++++++++++++++++++++ rules/operators/arithmetic/translate.py | 4 + rules/types/double/cases/basic.m | 6 + rules/types/double/cases/basic.py | 8 + rules/types/double/rule.yaml | 33 ++ rules/types/double/translate.py | 76 +++ tests/test_adversarial.py | 33 ++ tests/test_corpus.py | 14 + tests/test_reverse.py | 4 +- tests/test_verify.py | 54 ++- uv.lock | 3 + 40 files changed, 1442 insertions(+), 66 deletions(-) create mode 100644 rules/builtins/filter/cases/basic.m create mode 100644 rules/builtins/filter/cases/basic.py create mode 100644 rules/builtins/filter/cases/columns.m create mode 100644 rules/builtins/filter/cases/columns.py create mode 100644 rules/builtins/filter/rule.yaml create mode 100644 rules/builtins/filter/translate.py create mode 100644 rules/io/printf/cases/basic.m create mode 100644 rules/io/printf/cases/basic.py create mode 100644 rules/io/printf/cases/integers.m create mode 100644 rules/io/printf/cases/integers.py create mode 100644 rules/io/printf/cases/recycling.m create mode 100644 rules/io/printf/cases/recycling.py create mode 100644 rules/io/printf/rule.yaml create mode 100644 rules/io/printf/translate.py create mode 100644 rules/types/double/cases/basic.m create mode 100644 rules/types/double/cases/basic.py create mode 100644 rules/types/double/rule.yaml create mode 100644 rules/types/double/translate.py diff --git a/docs/design.md b/docs/design.md index 5880ae0..b5b4022 100644 --- a/docs/design.md +++ b/docs/design.md @@ -511,6 +511,13 @@ How `dualect verify a.m a.py` and the rule-case tests decide two scripts agree: `.m`, 0-based in Python, compared as `m - 1`) and `% dualect: ignore k` (e.g. a loop variable whose final value legitimately differs). Unknown directives are errors, so a typo cannot silently weaken a check. +- Printing is compared only on request, `% dualect: stdout`: then the text + both scripts print must be identical, character for character (the `.m` + side is captured with `evalc`, which keeps trailing spaces and a last line + without a newline). Most scripts print incidentally, so it is opt-in; a + translation that prints (rule `io/printf`) writes the directive into its + output itself. `% dualect: shape r` compares `r` by shape and + logical-ness only, for random values (`rand`) that no two runs share. - `.m` case scripts that define functions start with `1;` and define them before use: Octave does not accept functions at the end of a script. - A case file must not be named like a function it calls (`round.m`): the diff --git a/dualect/compare.py b/dualect/compare.py index 85e2801..a1841b9 100644 --- a/dualect/compare.py +++ b/dualect/compare.py @@ -88,6 +88,29 @@ def compare_values( return _compare_arrays(m_value=m_value, py_value=py_value, tolerance=tolerance, index=index) +def compare_shapes(*, m_value: Any, py_value: Any) -> str | None: + """Compare only what two random results must share: shape and logical-ness. + + ``rand(3)`` and ``np.random.rand(3, 3)`` never agree by value; a + translation is still wrong if it draws a different number of values or + returns a different kind of array. + + :param m_value: value pulled from Octave. + :param py_value: value from the Python namespace. + :returns: ``None`` if they agree, otherwise a short reason. + """ + m_array, py_array = np.asarray(m_value), np.asarray(py_value) + if m_array.dtype.kind not in _NUMERIC_KINDS or py_array.dtype.kind not in _NUMERIC_KINDS: + return f"cannot compare {m_array.dtype} with {py_array.dtype}" + if (m_array.dtype.kind == "b") != (py_array.dtype.kind == "b"): + return f"logical vs numeric: {m_array.dtype} vs {py_array.dtype}" + if m_array.size == 0 and py_array.size == 0: + return None + if _squeezed_shape(m_array) != _squeezed_shape(py_array): + return f"shape differs: {m_array.shape} vs {py_array.shape}" + return None + + def _compare_mappings(*, m_value: Any, py_value: Any, tolerance: Tolerance) -> str | None: """Compare a struct with a dict field by field.""" if not (isinstance(m_value, dict) and isinstance(py_value, dict)): diff --git a/dualect/emit.py b/dualect/emit.py index 0f51308..b10fb83 100644 --- a/dualect/emit.py +++ b/dualect/emit.py @@ -153,6 +153,9 @@ def __init__( self.indent = 0 self.reports: list[StmtReport] = [] self.directives: set[str] = set() + #: File-level verification directives (``stdout``, ``shape r``) that + #: the translation needs, written below the imports. + self.file_directives: list[str] = [] self.source_lines = scan.program_text.splitlines() if scan.program_text else [] # --- facts ------------------------------------------------------------- @@ -172,6 +175,15 @@ def index_directive(self, name: str) -> list[Line]: self.directives.add(name) return [self.line(f"# dualect: index {name}")] + def file_directive(self, text: str) -> None: + """Ask for a ``# dualect: `` line at the top of the output. + + A translation that prints adds ``stdout`` so verification compares the + printed text; one that draws random numbers adds ``shape ``. + """ + if text not in self.file_directives: + self.file_directives.append(text) + def is_index_var(self, name: str) -> bool: """Whether ``name`` is stored 0-based in the output (see :func:`index_variables`).""" return name in self.scope.index_vars @@ -375,14 +387,18 @@ def statement(self, stmt: ir.Stmt) -> list[Line]: return self.hole(stmt, report) saved_imports = set(self.imports) saved_directives = set(self.directives) + saved_file_directives = list(self.file_directives) # Nested statements record their own assumptions; a compound statement's # note must only carry what was assumed for its own header. outer_assumptions = self.assumptions self.assumptions = [] try: - return self._translate_planned(stmt, report, saved_imports, saved_directives) + lines = self._translate_planned(stmt, report, saved_imports, saved_directives) finally: self.assumptions = outer_assumptions + if report.status is not Status.MECHANICAL: + self.file_directives = saved_file_directives + return lines def _translate_planned( self, @@ -434,6 +450,13 @@ def translate_statement(self, stmt: ir.Stmt) -> list[Line]: case ir.ExprStmt(value=value): if "syntax:script-marker" in stmt.syntax: return [] + if isinstance(value, ir.Call) and not (value.local or value.handle): + # A call made for its effect (printing) may need statements, + # such as a loop that recycles a format over an array. + module = self.stmt_translator(primary_tag(value, self.analysis) or "") + hook = getattr(module, "translate_call_statement", None) + if hook is not None: + return self._lines(hook(stmt, self)) return [Line(self.indent, ast.unparse(self.expr(value)))] primary = primary_tag(stmt, self.analysis) if primary is None: diff --git a/dualect/infer.py b/dualect/infer.py index 7c79101..a0255b5 100644 --- a/dualect/infer.py +++ b/dualect/infer.py @@ -758,6 +758,8 @@ def binop(self, op: str, a: Info, b: Info) -> Info: integer = a.integer and b.integer and b.nonneg finite = a.finite and b.finite and b.nonneg and b.integer value = _fold(op, a, b) if a.is_scalar and b.is_scalar else None + if isinstance(value, int | float) and math.isfinite(value): + finite = True # a constant-folded value is known exactly keeps_ints = op in ("plus", "minus", "times", "mtimes") or ( op in ("power", "mpower") and b.integer and b.nonneg ) @@ -931,6 +933,12 @@ def call(self, node: ir.Call, env: Env, *, nargout: int) -> Info: ) if name in ("num2str", "sprintf", "strcat", "upper", "lower", "strtrim"): return Info(kind=Kind.STRING, rows=1, elem=Elem.CHAR) + if name in ("double", "logical") and len(args) == 1: + elem = Elem.REAL if name == "double" else Elem.LOGICAL + return replace(first, elem=elem, value=None, func=None, int_dtype=False) + if name == "filter" and len(args) >= 3: + # The output has the shape of the data (the third argument). + return replace(args[2], elem=Elem.REAL, finite=False, value=None, func=None) if name in ("cumsum", "cumprod", "sort", "flip", "fliplr", "flipud", "diff"): return replace(first, value=None, func=None) return UNKNOWN diff --git a/dualect/lift.py b/dualect/lift.py index 656ef76..8df0f31 100644 --- a/dualect/lift.py +++ b/dualect/lift.py @@ -121,6 +121,9 @@ def __init__( self.function: ast.FunctionDef | None = None self.outputs: list[str] = [] self.loop_depth = 0 + #: File-level verification directives the ``.m`` output needs + #: (``stdout`` when it prints, ``shape r`` for random values). + self.file_directives: list[str] = [] self._used_comments: set[int] = set() self._plan(module.body) @@ -166,6 +169,11 @@ def loc(node: ast.AST) -> ir.Loc: """The IR location of a Python node.""" return loc_of(node) + def file_directive(self, text: str) -> None: + """Ask for a ``% dualect: `` line at the top of the ``.m`` output.""" + if text not in self.file_directives: + self.file_directives.append(text) + def assume(self, text: str) -> None: """Record an assumption; it is printed as ``% dualect: assumed ...``.""" if text not in self.assumptions: @@ -359,17 +367,20 @@ def statement(self, stmt: ast.stmt) -> list[ir.Stmt]: self.assumptions = [] mark = len(self.reports) used = set(self._used_comments) + file_directives = list(self.file_directives) try: lifted = self.translate_statement(stmt) except Decline as exc: del self.reports[mark:] self._used_comments = used + self.file_directives = file_directives report.status = Status.GUIDED report.reason = f"translator declined: {exc.reason}" return self.hole(stmt, report) except _Unsupported as exc: del self.reports[mark:] self._used_comments = used + self.file_directives = file_directives status = Status.UNSUPPORTED if exc.rule is not None and exc.rule.python_status is not None: status = exc.rule.python_status @@ -408,7 +419,9 @@ def translate_statement(self, stmt: ast.stmt) -> list[ir.Stmt]: return [ir.Comment(loc=loc, text=line.strip()) for line in text.strip().split("\n")] case ast.Expr(value=value): return [ir.ExprStmt(loc=loc, value=self.expr(value))] - case ast.Import() | ast.Pass(): + case ast.Import() | ast.ImportFrom() | ast.Pass(): + # Planning already required a mechanical rule for every module + # imported other than numpy (`py:import:scipy.signal`). return [] tag = _statement_tag(stmt) if tag is None: diff --git a/dualect/lower.py b/dualect/lower.py index 21ed195..4e0de4c 100644 --- a/dualect/lower.py +++ b/dualect/lower.py @@ -274,7 +274,7 @@ def statement(self, node: TSNode, *, display: bool) -> list[ir.Stmt]: self.pending_comments = [] self.collect_continuations(node) stmt = self.simple_statement(node, display=display) - if display and not isinstance(stmt, ir.OpaqueStmt): + if display and not isinstance(stmt, ir.OpaqueStmt) and not _prints_nothing(stmt): stmt.syntax.append("syntax:display") stmt.syntax.extend(self.pending_syntax) if self.pending_comments: @@ -734,6 +734,21 @@ def power_operand(self) -> ir.Expr: return value +#: Functions that return nothing when called as a statement, so a missing +#: semicolon after them displays nothing (they may print by themselves). +_NO_RESULT_CALLS = frozenset({"disp", "printf", "fprintf", "puts", "fputs", "fdisp", "tic"}) + + +def _prints_nothing(stmt: ir.Stmt) -> bool: + """A statement whose missing ``;`` has no effect: a call that returns nothing.""" + return ( + isinstance(stmt, ir.ExprStmt) + and isinstance(stmt.value, ir.Call) + and not (stmt.value.local or stmt.value.handle) + and stmt.value.func in _NO_RESULT_CALLS + ) + + def _reject_stray_until(body: list[ir.Stmt]) -> None: """Turn an ``until`` that closed no ``do`` into a parse error, in place.""" for index, stmt in enumerate(body): diff --git a/dualect/pipeline.py b/dualect/pipeline.py index d47fa29..11ea3d6 100644 --- a/dualect/pipeline.py +++ b/dualect/pipeline.py @@ -156,7 +156,12 @@ def translate_scan( ctx.enter_script() lines = ctx.statements(scan.program.body) body = render(lines) - imports = "".join(f"{line}\n" for line in sorted(ctx.imports)) + # isort's order within one section: `import x` lines, then `from x import y`. + ordered = sorted(ctx.imports, key=lambda line: (line.startswith("from "), line)) + imports = "".join(f"{line}\n" for line in ordered) + directives = "".join(f"# dualect: {text}\n" for text in ctx.file_directives) + if directives: + body = f"{directives}\n{body}" code = format_python(f"{imports}\n{body}" if imports else body) return Translation( source_name=scan.source_name, @@ -202,9 +207,11 @@ def translate_python_text( translators = TranslatorSet(rules=rules) lifted = lift_python(text=text, name=name, rules=rules, translator_for=translators.get) scan = scan_python_text(text=text, name=name, rules=rules) + code = memit.program(lifted.body) + directives = "".join(f"% dualect: {text}\n" for text in lifted.context.file_directives) result = Translation( source_name=name, - code=memit.program(lifted.body), + code=f"{directives}{code}" if directives else code, statements=lifted.reports, scan=scan, rules_used=scan.needed_rules(), diff --git a/dualect/pyconstructs.py b/dualect/pyconstructs.py index 80c1088..8b42e7a 100644 --- a/dualect/pyconstructs.py +++ b/dualect/pyconstructs.py @@ -211,7 +211,17 @@ def _walk(self, node: ast.AST, uses: list[PyUse]) -> None: func = node.func if isinstance(func, ast.Attribute) and dotted(func, self.alias) is None: self._walk(func.value, uses) # the receiver of a method + joining = isinstance(func, ast.Attribute) and func.attr == "join" for arg in node.args: + if joining and isinstance(arg, ast.ListComp | ast.GeneratorExp): + # `"".join([... for v in x])` is one construct, the join's: + # only the pieces of the comprehension are tagged. + self._walk(arg.elt, uses) + for generator in arg.generators: + self._walk(generator.iter, uses) + for condition in generator.ifs: + self._walk(condition, uses) + continue self._walk(arg, uses) for keyword in node.keywords: self._walk(keyword.value, uses) diff --git a/dualect/pyinfer.py b/dualect/pyinfer.py index 880993b..4605872 100644 --- a/dualect/pyinfer.py +++ b/dualect/pyinfer.py @@ -455,8 +455,17 @@ def _expr(self, node: ast.expr, env: Env) -> PyInfo: return self.call(node, env) case ast.Lambda(): return PyInfo(kind=PyKind.FUNC, func=node) - case ast.JoinedStr(): + case ast.JoinedStr(values=values): + for piece in values: + if isinstance(piece, ast.FormattedValue): + self.expr(piece.value, env) return PyInfo(kind=PyKind.STRING) + case ast.ListComp(elt=elt, generators=[generator]) if not generator.ifs: + # One `for` clause: the element is analysed with its target bound. + item = self.element(self.expr(generator.iter, env), generator.iter) + bound = self.bind(generator.target, item, dict(env), None) + self.expr(elt, bound) + return PyInfo(kind=PyKind.LIST) for child in ast.iter_child_nodes(node): if isinstance(child, ast.expr): self.expr(child, env) @@ -594,7 +603,15 @@ def call(self, node: ast.Call, env: Env) -> PyInfo: return self.numpy_call(name[3:], node, args, keywords) if isinstance(func, ast.Attribute): receiver = self.expr(func.value, env) - return self.method(func.attr, receiver, args, keywords) + result = self.method(func.attr, receiver, args, keywords) + target = node.args[0] if node.args else None + if func.attr == "astype" and isinstance(target, ast.Name): + # x.astype(float): the element type is the one named. + dtypes = {"float": DType.FLOAT, "bool": DType.BOOL, "int": DType.INT} + result = replace(result, dtype=dtypes.get(target.id, DType.UNKNOWN)) + if target.id == "bool": + result = replace(result, finite=True, nonneg=True) + return result if isinstance(func, ast.Name): fname = func.id self.analysis.infos[id(func)] = env.get(fname, UNKNOWN) @@ -922,6 +939,9 @@ def _builtin(name: str, args: list[PyInfo]) -> PyInfo: return scalar(DType.BOOL, nonneg=True) if name == "print": return PyInfo(kind=PyKind.NONE) + if name == "lfilter" and len(args) >= 3: + # scipy.signal.lfilter: the shape of the data, in floating point. + return replace(_as_array(args[2]), dtype=DType.FLOAT, finite=False, value=None, view=False) return UNKNOWN diff --git a/dualect/runners.py b/dualect/runners.py index f1d6d9b..77b2b92 100644 --- a/dualect/runners.py +++ b/dualect/runners.py @@ -31,6 +31,10 @@ #: Names never treated as outputs: Octave's implicit result variable. _M_IMPLICIT = frozenset({"ans"}) +#: The variable that briefly holds a script's printed output (cleared before +#: the workspace is collected). +_OUTPUT_VAR = "dualect_printed_output__" + @dataclass(frozen=True) class CallableValue: @@ -95,23 +99,40 @@ def run(self, *, path: Path) -> dict[str, Any]: ``bool`` arrays and function handles as :class:`CallableValue`. :raises ExecutionError: if Octave reports an error. """ + outputs, _printed = self.run_capturing(path=path) + return outputs + + def run_capturing(self, *, path: Path) -> tuple[dict[str, Any], str]: + """Like :meth:`run`, and also return what the script printed. + + :param path: the script. + :returns: ``(variables, standard output)``; the output text is exact, + including a final line without a newline. + :raises ExecutionError: if Octave reports an error. + """ from oct2py import Oct2PyError session = self._ensure_session() path = path.resolve() - printed: list[str] = [] + ignored: list[str] = [] try: # Change directory first: the previous script's folder may have been # a temporary one that is gone now, and Octave refuses to run # anything from a working directory that no longer exists. - session.eval(f"cd({_quote_m_string(str(path.parent))});", stream_handler=printed.append) + session.eval(f"cd({_quote_m_string(str(path.parent))});", stream_handler=ignored.append) # A fresh workspace per script: leftovers from an earlier script # (variables or command-line functions) would otherwise leak in. - session.eval("clear all; close all; more off;", stream_handler=printed.append) - session.eval(f"source({_quote_m_string(str(path))});", stream_handler=printed.append) - return self._collect(session=session) + session.eval("clear all; close all; more off;", stream_handler=ignored.append) + # evalc captures the output exactly; oct2py's own stream drops + # trailing spaces and a last line without a newline. + source = _quote_m_string(f"source({_quote_m_string(str(path))});") + session.eval(f"{_OUTPUT_VAR} = evalc({source});", stream_handler=ignored.append) + printed = session.pull(_OUTPUT_VAR) + session.eval(f"clear {_OUTPUT_VAR};", stream_handler=ignored.append) + outputs = self._collect(session=session) except Oct2PyError as exc: raise ExecutionError(side="m", path=path, message=str(exc)) from exc + return outputs, printed if isinstance(printed, str) else "" @staticmethod def _collect(*, session: Any) -> dict[str, Any]: @@ -157,17 +178,30 @@ def run_py_script(*, path: Path) -> dict[str, Any]: Standard output is captured and discarded so verification output stays clean. :param path: the script. - :returns: variable name -> value. Names starting with ``_``, modules, - classes and ``def`` functions are dropped (they are scaffolding, not - outputs); lambdas become :class:`CallableValue`. + :returns: see :func:`run_py_script_capturing`. + :raises ExecutionError: if the script raises. + """ + outputs, _printed = run_py_script_capturing(path=path) + return outputs + + +def run_py_script_capturing(*, path: Path) -> tuple[dict[str, Any], str]: + """Execute a Python script; return its variables and what it printed. + + :param path: the script. + :returns: ``(variables, standard output)``. Variables map name -> value; + names starting with ``_``, modules, classes and ``def`` functions are + dropped (they are scaffolding, not outputs); lambdas become + :class:`CallableValue`. :raises ExecutionError: if the script raises. """ path = path.resolve() source = path.read_text(encoding="utf-8") namespace: dict[str, Any] = {"__name__": "__main__", "__file__": str(path)} + printed = io.StringIO() try: code = compile(source, str(path), "exec") - with contextlib.redirect_stdout(io.StringIO()): + with contextlib.redirect_stdout(printed): exec(code, namespace) except Exception as exc: # any failure of user code is reported, not raised raw last = traceback.format_exception_only(exc)[-1].strip() @@ -184,4 +218,4 @@ def run_py_script(*, path: Path) -> dict[str, Any]: outputs[name] = CallableValue(description="lambda") continue outputs[name] = value - return outputs + return outputs, printed.getvalue() diff --git a/dualect/verify.py b/dualect/verify.py index a6f0cd0..e5f2e55 100644 --- a/dualect/verify.py +++ b/dualect/verify.py @@ -13,6 +13,12 @@ % dualect: index idx k -- 1-based on the .m side, 0-based in Python % dualect: ignore tmp -- legitimately differs (e.g. a loop counter) + % dualect: shape r -- random values: compare shape and type only + % dualect: stdout -- also compare what the scripts print, exactly + +Printing is a result too, but most scripts print incidentally (a missing +semicolon, a progress line), so standard output is only compared when a +script asks for it; a translation that prints adds the directive itself. """ import re @@ -20,13 +26,34 @@ from dataclasses import dataclass, field from pathlib import Path -from dualect.compare import Tolerance, compare_values +from dualect.compare import Tolerance, compare_shapes, compare_values from dualect.errors import DirectiveError -from dualect.runners import MRunner, run_py_script +from dualect.runners import MRunner, run_py_script_capturing _DIRECTIVE = re.compile(r"^\s*[%#]+\s*dualect:\s*(?P.*)$") _IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") -_KNOWN_DIRECTIVES = ("index", "ignore") +_KNOWN_DIRECTIVES = ("index", "ignore", "shape", "stdout") +#: Directives that take no variable names. +_FLAG_DIRECTIVES = ("stdout",) +#: The name standard output is reported under (not a valid identifier, so it +#: cannot clash with a variable). +STDOUT = "(stdout)" + + +@dataclass(frozen=True) +class Directives: + """The ``dualect:`` directives of one script. + + :param index: names holding positions (1-based in ``.m``, 0-based in Python). + :param ignore: names excluded from comparison. + :param shape: names compared by shape and type only (random values). + :param stdout: whether standard output is compared. + """ + + index: frozenset[str] = frozenset() + ignore: frozenset[str] = frozenset() + shape: frozenset[str] = frozenset() + stdout: bool = False @dataclass(frozen=True) @@ -36,11 +63,16 @@ class VerifyOptions: :param tolerance: allclose tolerances. :param index_vars: names holding indices (1-based in ``.m``, 0-based in Python). :param ignore: names excluded from comparison. + :param shape_only: names compared by shape and type only, not by value + (the results of ``rand``, which no two runs share). + :param stdout: compare the printed output too, exactly. """ tolerance: Tolerance = field(default_factory=Tolerance) index_vars: frozenset[str] = frozenset() ignore: frozenset[str] = frozenset() + shape_only: frozenset[str] = frozenset() + stdout: bool = False @dataclass(frozen=True) @@ -93,15 +125,27 @@ def report(self) -> str: def parse_directives(*, text: str, path: Path) -> tuple[frozenset[str], frozenset[str]]: - """Read ``dualect:`` comment directives from a script. + """Read the ``index`` and ``ignore`` directives of a script. :param text: the script source. :param path: used in error messages. :returns: ``(index_vars, ignore)``. + :raises DirectiveError: see :func:`read_directives`. + """ + found = read_directives(text=text, path=path) + return found.index, found.ignore + + +def read_directives(*, text: str, path: Path) -> Directives: + """Read every ``dualect:`` comment directive of a script. + + :param text: the script source. + :param path: used in error messages. :raises DirectiveError: for an unknown directive or a malformed name, so a typo cannot silently weaken a comparison. """ found: dict[str, set[str]] = {key: set() for key in _KNOWN_DIRECTIVES} + flags: set[str] = set() for line_number, line in enumerate(text.splitlines(), start=1): match = _DIRECTIVE.match(line) if match is None: @@ -113,10 +157,20 @@ def parse_directives(*, text: str, path: Path) -> tuple[frozenset[str], frozense f"expected one of {', '.join(_KNOWN_DIRECTIVES)}" ) names = words[1:] + if words[0] in _FLAG_DIRECTIVES: + if names: + raise DirectiveError(f"{path}:{line_number}: {words[0]} takes no names") + flags.add(words[0]) + continue if not names or not all(_IDENTIFIER.match(name) for name in names): raise DirectiveError(f"{path}:{line_number}: expected variable names after {words[0]}") found[words[0]].update(names) - return frozenset(found["index"]), frozenset(found["ignore"]) + return Directives( + index=frozenset(found["index"]), + ignore=frozenset(found["ignore"]), + shape=frozenset(found["shape"]), + stdout="stdout" in flags, + ) def options_for_pair( @@ -131,14 +185,20 @@ def options_for_pair( """ index_vars: set[str] = set(extra_index) ignore: set[str] = set() + shape: set[str] = set() + stdout = False for path in (m_path, py_path): - found_index, found_ignore = parse_directives( - text=path.read_text(encoding="utf-8"), path=path - ) - index_vars |= found_index - ignore |= found_ignore + found = read_directives(text=path.read_text(encoding="utf-8"), path=path) + index_vars |= found.index + ignore |= found.ignore + shape |= found.shape + stdout = stdout or found.stdout return VerifyOptions( - tolerance=tolerance, index_vars=frozenset(index_vars), ignore=frozenset(ignore) + tolerance=tolerance, + index_vars=frozenset(index_vars), + ignore=frozenset(ignore), + shape_only=frozenset(shape), + stdout=stdout, ) @@ -165,16 +225,24 @@ def verify_pair( if runner is None: with MRunner() as own_runner: - m_outputs = own_runner.run(path=m_path) + m_outputs, m_printed = own_runner.run_capturing(path=m_path) else: - m_outputs = runner.run(path=m_path) - py_outputs = run_py_script(path=py_path) + m_outputs, m_printed = runner.run_capturing(path=m_path) + py_outputs, py_printed = run_py_script_capturing(path=py_path) results = [] + if options.stdout: + results.append(_compare_printed(m_printed, py_printed)) for name in sorted(set(m_outputs) - options.ignore): if name not in py_outputs: results.append(VarResult(name=name, ok=False, detail="missing on the Python side")) continue + if name in options.shape_only: + reason = compare_shapes(m_value=m_outputs[name], py_value=py_outputs[name]) + results.append( + VarResult(name=name, ok=reason is None, detail=reason or "shape and type only") + ) + continue reason = compare_values( m_value=m_outputs[name], py_value=py_outputs[name], @@ -188,3 +256,22 @@ def verify_pair( return VerifyResult( m_path=m_path, py_path=py_path, variables=tuple(results), python_only=python_only ) + + +def _compare_printed(m_printed: str, py_printed: str) -> VarResult: + """Standard output must match character for character.""" + if m_printed == py_printed: + lines = m_printed.count("\n") + (not m_printed.endswith("\n") and bool(m_printed)) + return VarResult(name=STDOUT, ok=True, detail=f"{lines} line(s), identical") + m_lines, py_lines = m_printed.split("\n"), py_printed.split("\n") + for number, (m_line, py_line) in enumerate(zip(m_lines, py_lines, strict=False), start=1): + if m_line != py_line: + return VarResult( + name=STDOUT, ok=False, detail=f"line {number}: {m_line!r} vs {py_line!r}" + ) + return VarResult( + name=STDOUT, + ok=False, + detail=f"{len(m_lines)} vs {len(py_lines)} lines, ending " + f"{m_printed[-20:]!r} vs {py_printed[-20:]!r}", + ) diff --git a/llms.txt b/llms.txt index 91c5f60..910cb79 100644 --- a/llms.txt +++ b/llms.txt @@ -18,6 +18,7 @@ Generated by `dualect llms-txt`; do not edit by hand. - [builtins/constants](rules/builtins/constants/rule.yaml): Constants: `pi`, `Inf`, `NaN`, `eps`, `true`, `false`, `i` (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [builtins/elementwise-math](rules/builtins/elementwise-math/rule.yaml): Element-wise math: `abs`, `sqrt`, `exp`, `floor`, `mod`, `rem`, `isnan`, ... (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/filter](rules/builtins/filter/rule.yaml): `filter`: one-dimensional digital filter (`scipy.signal.lfilter`) (.m to Python: mechanical; Python to .m: mechanical; 2 cases) - [builtins/find](rules/builtins/find/rule.yaml): `find`: 1-based, column-major indices (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [builtins/isempty](rules/builtins/isempty/rule.yaml): `isempty` (.m to Python: mechanical; Python to .m: n/a; 1 case) - [builtins/linspace](rules/builtins/linspace/rule.yaml): `linspace` default count and edge cases (.m to Python: mechanical; Python to .m: mechanical; 2 cases) @@ -37,7 +38,8 @@ Generated by `dualect llms-txt`; do not edit by hand. - [indexing/logical](rules/indexing/logical/rule.yaml): Logical (mask) indexing (.m to Python: mechanical; Python to .m: mechanical; 2 cases) - [indexing/one-based](rules/indexing/one-based/rule.yaml): One-based indexing and column-major linear indices (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [indexing/ranges](rules/indexing/ranges/rule.yaml): Colon ranges `a:b` and `a:step:b` (.m to Python: mechanical; Python to .m: mechanical; 2 cases) -- [io/display](rules/io/display/rule.yaml): Printing: missing `;`, `disp`, `printf` / `fprintf` (.m to Python: guided; Python to .m: guided; 1 case) +- [io/display](rules/io/display/rule.yaml): Display of results: a missing `;` and `display` (.m to Python: guided; Python to .m: n/a; 1 case) +- [io/printf](rules/io/printf/rule.yaml): Formatted output: `printf`, `fprintf`, `sprintf`, `disp` (.m to Python: mechanical; Python to .m: mechanical; 3 cases) - [operators/arithmetic](rules/operators/arithmetic/rule.yaml): `+`, `-`, comparisons and implicit expansion (.m to Python: mechanical; Python to .m: mechanical; 2 cases) - [operators/augmented-assignment](rules/operators/augmented-assignment/rule.yaml): `x += e`, `x++` and friends (Octave only) (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [operators/division](rules/operators/division/rule.yaml): `/`, `./` and `\`: true division and linear solves (.m to Python: mechanical; Python to .m: mechanical; 1 case) @@ -51,3 +53,4 @@ Generated by `dualect llms-txt`; do not edit by hand. - [syntax/comments](rules/syntax/comments/rule.yaml): Comments: `%`, `#`, and `%{ ... %}` blocks (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [syntax/line-continuation](rules/syntax/line-continuation/rule.yaml): Line continuation with `...` (.m to Python: mechanical; Python to .m: n/a; 1 case) - [types/char-strings](rules/types/char-strings/rule.yaml): Char arrays `'...'` and double-quoted strings (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [types/double](rules/types/double/rule.yaml): `double` and `logical`: converting between numbers and truth values (.m to Python: mechanical; Python to .m: mechanical; 1 case) diff --git a/pyproject.toml b/pyproject.toml index 8ab9b51..26b7b19 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,6 +35,9 @@ dependencies = [ "ruff>=0.8", # The official Model Context Protocol SDK, for `dualect mcp` (2.x API: MCPServer). "mcp>=2.3,<3", + # The translation target for signal processing (docs/design.md section 9): + # `filter` becomes scipy.signal.lfilter. + "scipy>=1.13", ] [project.scripts] diff --git a/rules/builtins/filter/cases/basic.m b/rules/builtins/filter/cases/basic.m new file mode 100644 index 0000000..d86f0f7 --- /dev/null +++ b/rules/builtins/filter/cases/basic.m @@ -0,0 +1,8 @@ +% Moving average (FIR) and a first-order low-pass (IIR) of a short signal. +x = [1 4 2 8 5 7 3 6]; +b = ones(1, 3) / 3; +y_fir = filter(b, 1, x); +alpha = 0.25; +y_iir = filter(alpha, [1, alpha - 1], x); +% a(1) need not be 1: both sides divide through by it. +y_scaled = filter([2 2], [4 1], x); diff --git a/rules/builtins/filter/cases/basic.py b/rules/builtins/filter/cases/basic.py new file mode 100644 index 0000000..ea07020 --- /dev/null +++ b/rules/builtins/filter/cases/basic.py @@ -0,0 +1,11 @@ +import numpy as np +from scipy.signal import lfilter + +# Moving average (FIR) and a first-order low-pass (IIR) of a short signal. +x = np.array([1, 4, 2, 8, 5, 7, 3, 6]) +b = np.ones(3) / 3 +y_fir = lfilter(b, 1, x) +alpha = 0.25 +y_iir = lfilter(alpha, [1, alpha - 1], x) +# a(1) need not be 1: both sides divide through by it. +y_scaled = lfilter([2, 2], [4, 1], x.astype(float)) diff --git a/rules/builtins/filter/cases/columns.m b/rules/builtins/filter/cases/columns.m new file mode 100644 index 0000000..6f7fc76 --- /dev/null +++ b/rules/builtins/filter/cases/columns.m @@ -0,0 +1,5 @@ +% A matrix is filtered column by column; a column vector stays a column. +X = [1 2; 3 4; 5 6; 7 8]; +Y = filter([1 -1], 1, X); % first differences down each column +c = [1; 0; 0; 0]; +h = filter(1, [1 -0.5], c); % impulse response: 1, 0.5, 0.25, 0.125 diff --git a/rules/builtins/filter/cases/columns.py b/rules/builtins/filter/cases/columns.py new file mode 100644 index 0000000..62f4884 --- /dev/null +++ b/rules/builtins/filter/cases/columns.py @@ -0,0 +1,8 @@ +import numpy as np +from scipy.signal import lfilter + +# A matrix is filtered column by column; a column vector stays a column. +X = np.array([[1, 2], [3, 4], [5, 6], [7, 8]]) +Y = lfilter([1, -1], 1, X.astype(float), axis=0) # first differences down each column +c = np.array([1, 0, 0, 0]) +h = lfilter(1, [1, -0.5], c) # impulse response: 1, 0.5, 0.25, 0.125 diff --git a/rules/builtins/filter/rule.yaml b/rules/builtins/filter/rule.yaml new file mode 100644 index 0000000..38435b1 --- /dev/null +++ b/rules/builtins/filter/rule.yaml @@ -0,0 +1,40 @@ +id: builtins/filter +title: "`filter`: one-dimensional digital filter (`scipy.signal.lfilter`)" +status: mechanical +dialects: [octave, matlab] +match: [call:filter] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:import:scipy.signal + - py:call:lfilter +octave: | + y = filter(b, a, x); % b: numerator, a: denominator + Y = filter(b, 1, X); % a matrix: each column is filtered +python: | + from scipy.signal import lfilter + + y = lfilter(b, a, x) + Y = lfilter(b, 1, X, axis=0) +why: > + `filter(b, a, x)` computes the difference equation + `a(1) y(n) = b(1) x(n) + b(2) x(n-1) + ... - a(2) y(n-1) - ...` with zero + initial conditions, which is exactly `scipy.signal.lfilter(b, a, x)`: same + argument order, same normalisation by `a(1)`, same output length. They + differ in the dimension: `filter` runs down the first non-singleton + dimension (the columns of a matrix), `lfilter` along the last axis (the + rows), so a matrix needs `axis=0`. +pitfalls: + - >- + On a matrix `lfilter` filters each *row* by default; `filter` filters each + column. Pass `axis=0`. + - >- + `[y, zf] = filter(b, a, x, zi)` carries filter state between calls; + `lfilter` takes `zi=` and returns `(y, zf)` only when it is given. Its + state convention matches, but the call shape differs, so only the + three-argument form is translated. + - >- + NumPy's `np.convolve(x, b)` is the FIR part only and returns + `len(x) + len(b) - 1` samples; `filter` keeps `len(x)`. +related: [builtins/sum-mean-max] +python_imports: [import numpy as np, from scipy.signal import lfilter] diff --git a/rules/builtins/filter/translate.py b/rules/builtins/filter/translate.py new file mode 100644 index 0000000..6002fef --- /dev/null +++ b/rules/builtins/filter/translate.py @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/filter: ``filter(b, a, x)`` is ``scipy.signal.lfilter``. + +The arguments keep their order and meaning (``lfilter`` rejects integer +input, so all-integer data is converted to floats). A vector (1-D in NumPy) is +filtered as it is; a matrix is filtered down its columns, ``axis=0``, because +``lfilter`` works along the last axis. The forms with initial conditions, a +dimension or a second output are declined: they change the call's shape. + +From Python, ``lfilter`` imported from ``scipy.signal`` becomes ``filter``; +on a 2-D array its default axis (the rows) is ``filter(b, a, X, [], 2)``. +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.lift import LiftContext + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``filter(b, a, x)``.""" + if len(node.args) != 3: + ctx.decline("filter with initial conditions or a dimension") + b, a, x = node.args + for coefficients in (b, a): + info = ctx.info(coefficients) + if not (info.is_scalar or info.is_vector): + ctx.decline("filter coefficients that are not a vector") + data = ctx.info(x) + if "lfilter" in ctx.scope.variables: + ctx.decline("a variable named lfilter would hide scipy's lfilter") + ctx.imports.add("from scipy.signal import lfilter") + args = [ctx.arg(b), ctx.arg(a), ctx.arg(x)] + if all(ctx.info(arg).int_dtype for arg in node.args): + # lfilter rejects integer input; the source computes in doubles. + data_expr = args[2] + if isinstance(data_expr, ast.Name | ast.Attribute | ast.Subscript): + args[2] = ctx.method(data_expr, "astype", ast.Name("float")) + else: + args[2] = ctx.call(ctx.np("asarray"), data_expr, dtype=ast.Name("float")) + if data.is_matrix: + # lfilter runs along the last axis (rows); filter down the columns. + return ctx.call(ast.Name("lfilter"), *args, axis=ast.Constant(0)) + if not data.is_vector or data.kind.value == "empty": + # lfilter needs at least one dimension: a scalar is declined too. + ctx.decline("filter of a value that is not known to be a vector or a matrix") + return ctx.call(ast.Name("lfilter"), *args) + + +# --- Python -> .m ------------------------------------------------------------ + + +def _imported_from_scipy(ctx: LiftContext) -> bool: + """``lfilter`` is the name ``from scipy.signal import lfilter`` binds.""" + for stmt in ctx.module.body: + if ( + isinstance(stmt, ast.ImportFrom) + and stmt.module == "scipy.signal" + and any(alias.name == "lfilter" and alias.asname is None for alias in stmt.names) + ): + return True + return False + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``lfilter(b, a, x)`` (and ``axis=``).""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if not _imported_from_scipy(ctx): + ctx.decline("lfilter that is not scipy.signal's") + if len(node.args) != 3: + ctx.decline("lfilter with these arguments") + axis: int | None = None + for keyword in node.keywords: + value = ctx.info(keyword.value).value + if keyword.arg != "axis" or not isinstance(value, int): + ctx.decline(f"lfilter with {keyword.arg}=") + axis = value + b, a, x = node.args + for coefficients in (b, a): + info = ctx.info(coefficients) + if not (info.is_scalar or info.is_vector or isinstance(coefficients, ast.List)): + ctx.decline("lfilter coefficients that are not 1-D") + literals = ctx.module_for("syntax/array-literals") + args = [literals.lift_items(arg, ctx) for arg in node.args] + data = ctx.info(x) + if data.is_matrix: + if axis in (0, -2): + return ctx.call("filter", *args, loc=loc) + if axis in (None, 1, -1): + empty = ir.Matrix(loc=loc, rows=[]) + return ctx.call("filter", *args, empty, ctx.num(2), loc=loc) + ctx.decline(f"lfilter along axis {axis}") + if not (data.is_vector or isinstance(x, ast.List)) or axis not in (None, 0, -1): + ctx.decline("lfilter of a value that is not known to be 1-D or 2-D") + return ctx.call("filter", *args, loc=loc) diff --git a/rules/io/display/cases/basic.m b/rules/io/display/cases/basic.m index d8cdba0..8a3a2a7 100644 --- a/rules/io/display/cases/basic.m +++ b/rules/io/display/cases/basic.m @@ -1,4 +1,4 @@ -x = 3 % no semicolon: prints the value -disp(x) -fprintf('%d items\n', x); -y = x + 1; +x = 3 % no semicolon: displays "x = 3" +y = x / 4 % displays "y = 0.7500" +z = x + 1; +% dualect: stdout diff --git a/rules/io/display/cases/basic.py b/rules/io/display/cases/basic.py index f217f03..cae5f85 100644 --- a/rules/io/display/cases/basic.py +++ b/rules/io/display/cases/basic.py @@ -1,5 +1,6 @@ x = 3 -print(f"x = {x}") # what the missing semicolon printed -print(x) -print(f"{x} items") -y = x + 1 +print(f"x = {x}") # what the missing semicolon displayed +y = x / 4 +print(f"y = {y:.4f}") +z = x + 1 +# dualect: stdout diff --git a/rules/io/display/rule.yaml b/rules/io/display/rule.yaml index 099f422..100df9e 100644 --- a/rules/io/display/rule.yaml +++ b/rules/io/display/rule.yaml @@ -1,34 +1,30 @@ id: io/display -title: "Printing: missing `;`, `disp`, `printf` / `fprintf`" +title: "Display of results: a missing `;` and `display`" status: guided dialects: [octave, matlab] -match: [syntax:display, call:disp, call:display, call:printf, call:fprintf] -from_python: # the Python -> .m direction - status: guided - match: - - py:call:print - - py:fstring +match: [syntax:display, call:display] octave: | x = 3 % no semicolon: prints "x = 3" - disp(x) - fprintf('%d items\n', n); + y = x / 4 % prints "y = 0.7500" python: | - print(f"x = {x}") - print(x) - print(f"{n} items") + print(f"x = {x}") # only if the output was wanted + print(f"y = {y:.4f}") why: > - A statement without a terminating semicolon prints its result, which is easy - to leave in by accident; decide whether the output was intended. `disp(x)` - is `print(x)`. `printf`/`fprintf` formats look like C's and map to f-strings, - but they cycle the format over all elements of array arguments. + A statement without a terminating semicolon displays its result, which is + easy to leave in by accident: decide whether the output was intended, and + usually drop it. When it was, write the print explicitly. The display format + depends on the value (`x = 3`, `y = 0.7500`, a matrix as aligned columns with + a common scale factor), so there is no one Python expression for it; this + rule stays guided. Formatted output is io/printf. pitfalls: - >- - `fprintf('%d\n', [1 2 3])` prints three lines (the format repeats for - every element); Python needs an explicit loop or `"\n".join(...)`. + Number formatting differs (`y = 0.7500` but Python's `0.75`); compare + values, not printed text. - >- - `fprintf(fid, ...)` with a file id writes to a file: `print(..., file=f)`. + A call that returns nothing (`disp(x)`, `fprintf(...)`) displays nothing + extra without a semicolon; only results are displayed. - >- - Number formatting differs (`disp(0.1)` shows `0.1000`); compare values, not - printed text. -related: [syntax/command-syntax] + `x` alone on a line (no assignment) displays `x = ...` too, and an + expression displays `ans = ...`. +related: [io/printf, syntax/command-syntax] python_imports: [] diff --git a/rules/io/printf/cases/basic.m b/rules/io/printf/cases/basic.m new file mode 100644 index 0000000..c53e95b --- /dev/null +++ b/rules/io/printf/cases/basic.m @@ -0,0 +1,13 @@ +% Each conversion becomes an f-string field; '\n' ends print's line. +x = 3.14159; +n = 12; +name = 'beam'; +fprintf('x = %.2f, n = %d\n', x, n); +printf('[%8.3f|%-8.3f|%+.2e|%08.3f]\n', x, x, x, -x); +fprintf('%5s|%-6s|%s\n', name, name, 'ok'); +fprintf(1, '100%% done\t(%g)\n', x); +fprintf('no newline: %d', n); +fprintf('\n'); +label = sprintf('%s has %d parts', name, n); +disp(label) +% dualect: stdout diff --git a/rules/io/printf/cases/basic.py b/rules/io/printf/cases/basic.py new file mode 100644 index 0000000..467c778 --- /dev/null +++ b/rules/io/printf/cases/basic.py @@ -0,0 +1,13 @@ +# Each conversion becomes an f-string field; '\n' ends print's line. +x = 3.14159 +n = 12 +name = "beam" +print(f"x = {x:.2f}, n = {int(n)}") +print(f"[{x:8.3f}|{x:<8.3f}|{x:+.2e}|{-x:08.3f}]") +print(f"{name:>5}|{name:<6}|ok") +print(f"100% done\t({x:g})") +print(f"no newline: {int(n)}", end="") +print() +label = f"{name} has {int(n)} parts" +print(label) +# dualect: stdout diff --git a/rules/io/printf/cases/integers.m b/rules/io/printf/cases/integers.m new file mode 100644 index 0000000..d05118b --- /dev/null +++ b/rules/io/printf/cases/integers.m @@ -0,0 +1,6 @@ +% %d needs a whole number: a computed count is one, a quotient may not be. +k = floor(7 / 2); +total = sum([1 2 3]); +fprintf('k = %d, total = %i, padded = %04d\n', k, total, k); +fprintf('big: %d\n', 2^40); +% dualect: stdout diff --git a/rules/io/printf/cases/integers.py b/rules/io/printf/cases/integers.py new file mode 100644 index 0000000..f4f11bc --- /dev/null +++ b/rules/io/printf/cases/integers.py @@ -0,0 +1,8 @@ +import numpy as np + +# %d needs a whole number: a computed count is one, a quotient may not be. +k = np.floor(7 / 2) +total = np.array([1, 2, 3]).sum() +print(f"k = {int(k)}, total = {int(total)}, padded = {int(k):04d}") +print(f"big: {int(2**40)}") +# dualect: stdout diff --git a/rules/io/printf/cases/recycling.m b/rules/io/printf/cases/recycling.m new file mode 100644 index 0000000..75c61cc --- /dev/null +++ b/rules/io/printf/cases/recycling.m @@ -0,0 +1,9 @@ +% The format repeats while values remain; an array recycles it per element. +v = [1 2 3]; +fprintf('%d\n', v); +A = [1 2 3; 4 5 6]; +fprintf('%d-%d\n', A); % one pass per column: 1-4, 2-5, 3-6 +fprintf('%d %d\n', 7, 8, 9); % prints "7 8", then "9 " and stops +fprintf('\n'); +csv = sprintf('%.1f,', [0.5 1.5]); +% dualect: stdout diff --git a/rules/io/printf/cases/recycling.py b/rules/io/printf/cases/recycling.py new file mode 100644 index 0000000..b8b8711 --- /dev/null +++ b/rules/io/printf/cases/recycling.py @@ -0,0 +1,13 @@ +import numpy as np + +# The format repeats while values remain; an array recycles it per element. +v = np.array([1, 2, 3]) +for value in v: + print(f"{int(value)}") +A = np.array([[1, 2, 3], [4, 5, 6]]) +for column in A.T: + print(f"{int(column[0])}-{int(column[1])}") # one pass per column: 1-4, 2-5, 3-6 +print("7 8\n9 ", end="") # prints "7 8", then "9 " and stops +print() +csv = "".join([f"{value:.1f}," for value in np.array([0.5, 1.5])]) +# dualect: stdout diff --git a/rules/io/printf/rule.yaml b/rules/io/printf/rule.yaml new file mode 100644 index 0000000..a820d39 --- /dev/null +++ b/rules/io/printf/rule.yaml @@ -0,0 +1,53 @@ +id: io/printf +title: "Formatted output: `printf`, `fprintf`, `sprintf`, `disp`" +status: mechanical +dialects: [octave, matlab] +match: [call:printf, call:fprintf, call:sprintf, call:disp] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:print + - py:fstring + - py:method:join +octave: | + fprintf('%5.2f m\n', x); + fprintf('%d\n', [1 2 3]); % the format repeats per element + s = sprintf('%d items', n); + disp(s) +python: | + print(f"{x:5.2f} m") + for value in np.array([1, 2, 3]): + print(f"{int(value)}") + s = f"{int(n)} items" + print(s) +why: > + A printf format maps onto an f-string field by field: `%5.2f` is + `{x:5.2f}`, `%-8s` is `{s:<8}`, `%+.3e` is `{x:+.3e}`, `%%` is `%`, and the + `\n` that ends a line becomes print's own newline. The difference is + recycling: printf repeats its format while values remain, so one call with an + array prints once per element (column-major) and needs a loop in Python, and + output stops at the first conversion that has no value left. +pitfalls: + - >- + `%d` of a value that is not a whole number does not round or truncate: + Octave prints it in another format (`sprintf('%d', 1.5)` is `1.5`). Only + values known to be whole numbers are translated, as `{int(x)}`. + - >- + `fprintf('%d %d\n', 1, 2, 3)` prints `1 2` and then `3 ` with no newline: + output stops at the first conversion without a value. + - >- + Octave prints `Inf` and `NaN`; Python prints `inf` and `nan`. + - >- + `%s` of a number prints it as a character code (`sprintf('%s', 65)` is + `A`), and `%d` of a string prints its character codes. + - >- + Python left-aligns strings in a field and printf right-aligns them: + `%5s` is `{s:>5}`. + - >- + `disp` of a number uses the interpreter's display format (`disp(0.1)` + prints `0.1000`), not `str`; format it explicitly instead. + - >- + `fprintf(fid, ...)` with a file id writes to a file: `print(..., file=f)`. + Only `fprintf(1, ...)` (standard output) is translated. +related: [io/display, types/char-strings] +python_imports: [] diff --git a/rules/io/printf/translate.py b/rules/io/printf/translate.py new file mode 100644 index 0000000..444cb2c --- /dev/null +++ b/rules/io/printf/translate.py @@ -0,0 +1,613 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for io/printf: ``printf``, ``fprintf``, ``sprintf`` and ``disp``. + +A literal format becomes an f-string. The format is read at translation time: +its escapes (``\\n``, ``\\t``, ...) are resolved, each conversion is mapped to +a Python format spec, and the source's *recycling* is carried out statically: +the format is repeated while values remain and output stops at the first +conversion that has no value left (``fprintf('%d %d\\n', 1, 2, 3)`` prints +``1 2`` and ``3 ``). A single array argument recycles the format once per +element (column-major) or per column; that becomes a ``for`` loop (or a +``"".join`` for ``sprintf``). + +Declined, by name: conversions without an exact Python counterpart (``%x``, +``%c``, ``%u``, ``*`` widths, ``%.3d``), ``%d`` of a value not known to be a +whole number (Octave silently switches to a ``%f``/``%g`` style there), ``%s`` +of a number, a format that is not a literal, a file id other than 1, and +``disp`` of a number (its display format is not Python's ``str``). Values not +known to be finite are assumed finite out loud: Octave prints ``Inf``/``NaN`` +where Python prints ``inf``/``nan``. Every translation that prints asks +verification to compare standard output (``# dualect: stdout``). +""" + +import ast +import math +import re +from dataclasses import dataclass + +from dualect import ir +from dualect.emit import Context, Line +from dualect.infer import Elem, Info, Kind +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyKind + +# --- the format string ------------------------------------------------------- + +_ESCAPES = {"n": "\n", "t": "\t", "\\": "\\", "a": "\a", "r": "\r", '"': '"', "'": "'"} +_CONVERSION = re.compile( + r"%(?P[-+ 0#]*)(?P\d+|\*)?(?:\.(?P\d*|\*))?(?P[A-Za-z%])" +) +_NUMERIC = frozenset("dieEfFgG") + + +@dataclass(frozen=True) +class Conversion: + """One ``%`` conversion of a format. + + :param flags: the flag characters (``-+ 0#``). + :param width: minimum field width, or ``None``. + :param precision: digits after the point (or significant digits), or ``None``. + :param kind: the conversion letter. + """ + + flags: str + width: int | None + precision: int | None + kind: str + + +Piece = str | Conversion + + +def parse_format(text: str) -> list[Piece]: + """Split a printf format into literal text and conversions. + + Escapes are resolved first, as printf does for single-quoted formats. + + :raises ValueError: for an escape or conversion with no exact Python form. + """ + unescaped = re.sub(r"\\(.)", lambda m: _escape(m.group(1)), text) + pieces: list[Piece] = [] + position = 0 + for match in _CONVERSION.finditer(unescaped): + if match.start() > position: + pieces.append(unescaped[position : match.start()]) + position = match.end() + kind = match.group("type") + if kind == "%": + if match.group(0) != "%%": + raise ValueError("a %% with flags") + pieces.append("%") + continue + width, precision = match.group("width"), match.group("precision") + if width == "*" or precision == "*": + raise ValueError("a * width or precision (taken from the arguments)") + if kind not in _NUMERIC and kind != "s": + raise ValueError(f"the %{kind} conversion") + pieces.append( + Conversion( + flags=match.group("flags"), + width=int(width) if width else None, + precision=int(precision or 0) if precision is not None else None, + kind=kind, + ) + ) + if "%" in unescaped[position:]: + raise ValueError("an incomplete % conversion") + if position < len(unescaped): + pieces.append(unescaped[position:]) + return pieces + + +def _escape(char: str) -> str: + if char not in _ESCAPES: + raise ValueError(f"the escape \\{char}") + return _ESCAPES[char] + + +def python_spec(conversion: Conversion, *, is_string: bool) -> str: + """The Python format spec that prints like ``conversion``. + + :raises ValueError: when there is none. + """ + flags, width, precision, kind = ( + conversion.flags, + conversion.width, + conversion.precision, + conversion.kind, + ) + left = "-" in flags + if is_string: + if "0" in flags or "+" in flags or " " in flags: + raise ValueError("numeric flags on %s") + # Python left-aligns strings by default, C right-aligns them. + align = ("<" if left else ">") if width is not None else "" + spec = f"{align}{width or ''}" + return spec + (f".{precision}" if precision is not None else "") + spec = "<" if left else "" + spec += "+" if "+" in flags else " " if " " in flags else "" + spec += "#" if "#" in flags and kind not in "di" else "" + spec += "0" if "0" in flags and not left else "" + spec += str(width) if width is not None else "" + if kind in "di": + if precision is not None: + raise ValueError("a precision on %d (a minimum digit count)") + return spec + ("d" if spec else "") + spec += f".{precision}" if precision is not None else "" + return spec + ("f" if kind == "F" else kind) + + +# --- .m -> Python --------------------------------------------------------------- + + +def _format_and_args(node: ir.Call, ctx: Context) -> tuple[list[Piece], list[ir.Expr]]: + """The parsed format and the value arguments of a printing call.""" + args = list(node.args) + if node.func == "fprintf" and args and not isinstance(args[0], ir.Str): + fid = ctx.info(args[0]).value + if fid != 1: + ctx.decline("fprintf to a file id other than 1 (standard output)") + args = args[1:] + if not args or not isinstance(args[0], ir.Str): + ctx.decline(f"{node.func} with a format that is not a literal string") + try: + pieces = parse_format(args[0].value) + except ValueError as exc: + ctx.decline(f"{node.func} with {exc}") + return pieces, args[1:] + + +def _plan(pieces: list[Piece], count: int, ctx: Context) -> list[str | tuple[Conversion, int]]: + """Walk the format the way printf does for ``count`` scalar values. + + The format repeats while values remain; output stops at the first + conversion with no value left, and after a full pass that used the last one. + """ + conversions = sum(isinstance(p, Conversion) for p in pieces) + if conversions == 0: + if count: + ctx.decline("values given to a format without conversions") + return [p for p in pieces if isinstance(p, str)] + if count == 0: + ctx.decline("a format with conversions but no values") + planned: list[str | tuple[Conversion, int]] = [] + used = 0 + while True: + for piece in pieces: + if isinstance(piece, Conversion): + if used == count: + return planned + planned.append((piece, used)) + used += 1 + else: + planned.append(piece) + if used == count: + return planned + + +def _field(conversion: Conversion, value: ast.expr, info: Info, ctx: Context) -> ast.expr | str: + """One ``{value:spec}`` field of the f-string (a literal value: its text).""" + is_string = info.kind is Kind.STRING + if conversion.kind == "s" and not is_string: + ctx.decline("%s of a value not known to be a string (a number prints as a character)") + if conversion.kind != "s": + if is_string or not info.is_scalar: + ctx.decline(f"%{conversion.kind} of a value that is not a known numeric scalar") + if not info.is_real: + ctx.decline(f"%{conversion.kind} of a value that may be complex") + if isinstance(info.value, int | float) and not math.isfinite(info.value): + ctx.decline("printing Inf or NaN (Octave prints Inf/NaN, Python inf/nan)") + if not info.finite: + ctx.assume("finite values printed (Octave prints Inf/NaN, Python inf/nan)") + if conversion.kind in "di": + if not info.integer: + ctx.decline( + f"%{conversion.kind} of a value not known to be a whole number " + "(Octave prints a fraction in another format)" + ) + if isinstance(info.value, int | float) and abs(info.value) >= 2**63: + ctx.decline(f"%{conversion.kind} of a whole number beyond 64-bit integers") + if info.value is None and not info.int_dtype: + # A computed double may be huge; Octave prints those as %g (1e+20). + ctx.assume(f"|value| < 2^63 under %{conversion.kind}") + if not (isinstance(value, ast.Constant) and isinstance(value.value, int | float)): + value = ctx.call(ast.Name("int"), value) + elif isinstance(value.value, float): + value = ast.Constant(int(value.value)) + if _has_string(value) and not (isinstance(value, ast.Constant) and info.kind is Kind.STRING): + ctx.decline("a string expression inside an f-string field") + try: + spec = python_spec(conversion, is_string=is_string) + except ValueError as exc: + ctx.decline(str(exc)) + if isinstance(value, ast.Constant) and isinstance(value.value, int | float | str): + # A literal is formatted now: `fprintf('%d %s\n', 3, 'ok')` prints fixed text. + return format(value.value, spec) + format_spec = ast.JoinedStr(values=[ast.Constant(spec)]) if spec else None + return ast.FormattedValue(value=value, conversion=-1, format_spec=format_spec) + + +def _has_string(node: ast.expr) -> bool: + return any(isinstance(n, ast.Constant) and isinstance(n.value, str) for n in ast.walk(node)) + + +def _joined(parts: list[str | ast.expr]) -> ast.expr: + """An f-string of literal text and fields; a plain string when there are no fields.""" + values: list[ast.expr] = [] + for part in parts: + if isinstance(part, str): + if values and isinstance(values[-1], ast.Constant): + previous = values[-1].value + assert isinstance(previous, str) + values[-1] = ast.Constant(previous + part) + elif part: + values.append(ast.Constant(part)) + else: + values.append(part) + if not any(isinstance(v, ast.FormattedValue) for v in values): + return ast.Constant("".join(str(v.value) for v in values if isinstance(v, ast.Constant))) + return ast.JoinedStr(values=values) + + +def _scalars(pieces: list[Piece], args: list[ir.Expr], ctx: Context) -> list[str | ast.expr]: + """The printed text for scalar (and string) arguments, recycled statically.""" + for arg in args: + info = ctx.info(arg) + if not (info.is_scalar or info.kind is Kind.STRING): + ctx.decline("recycling a format over arrays mixed with other values") + values = [ctx.expr(arg) for arg in args] + parts: list[str | ast.expr] = [] + for item in _plan(pieces, len(args), ctx): + if isinstance(item, str): + parts.append(item) + else: + conversion, k = item + parts.append(_field(conversion, values[k], ctx.info(args[k]), ctx)) + return parts + + +@dataclass +class _Loop: + """A format recycled over one array: ``for in ``.""" + + target: str + iterable: ast.expr + parts: list[str | ast.expr] + + +def _array_loop(pieces: list[Piece], array: ir.Expr, ctx: Context) -> _Loop: + """One pass of the format per element (one conversion) or per column (one per row).""" + info = ctx.info(array) + conversions = [p for p in pieces if isinstance(p, Conversion)] + if not conversions: + ctx.decline("an array given to a format without conversions") + if info.numel == 0 or info.kind is Kind.EMPTY: + ctx.decline("an empty array given to a format (the source prints it once, empty)") + if info.numel is None: + # An empty array prints the format once with empty fields; a loop, nothing. + ctx.assume("a non-empty array") + name = _fresh("value", ctx) + element = Info( + kind=Kind.SCALAR, + rows=1, + cols=1, + elem=info.elem, + finite=info.finite, + nonneg=info.nonneg, + integer=info.integer, + ) + expr = ctx.expr(array) + if len(conversions) == 1: + if info.is_matrix: + iterable = ctx.method(expr, "ravel", order=ast.Constant("F")) + elif info.is_vector: + iterable = expr + else: + ctx.decline("recycling a format over a value whose shape is unknown") + fields: list[ast.expr] = [ast.Name(name)] + else: + if not (info.is_matrix and info.rows == len(conversions)): + ctx.decline( + "recycling a format with several conversions over an array that does not " + "have one row per conversion" + ) + iterable = ast.Attribute(value=expr, attr="T") + name = _fresh("column", ctx) + fields = [ + ast.Subscript(value=ast.Name(name), slice=ast.Constant(k)) + for k in range(len(conversions)) + ] + if element.elem is Elem.UNKNOWN: + ctx.decline("recycling a format over values of unknown type") + parts: list[str | ast.expr] = [] + k = 0 + for piece in pieces: + if isinstance(piece, Conversion): + parts.append(_field(piece, fields[k], element, ctx)) + k += 1 + else: + parts.append(piece) + return _Loop(target=name, iterable=iterable, parts=parts) + + +def _fresh(base: str, ctx: Context) -> str: + name = base + while name in ctx.scope.variables: + name += "_" + return name + + +def _is_array_call(args: list[ir.Expr], ctx: Context) -> bool: + return len(args) == 1 and ctx.info(args[0]).is_array + + +def _print(parts: list[str | ast.expr], ctx: Context) -> ast.expr: + """``print(...)`` of the text, its trailing newline as print's own.""" + ends_line = bool(parts) and isinstance(parts[-1], str) and parts[-1].endswith("\n") + if ends_line: + last = parts[-1] + assert isinstance(last, str) + parts = [*parts[:-1], last[:-1]] + text = _joined(parts) + args = [] if isinstance(text, ast.Constant) and text.value == "" else [text] + keywords = {} if ends_line else {"end": ast.Constant("")} + if not args and not ends_line: + ctx.decline("printing nothing") + return ctx.call(ast.Name("print"), *args, **keywords) + + +def translate_call_statement(stmt: ir.ExprStmt, ctx: Context) -> list[Line]: + """``printf``/``fprintf``/``disp`` as a statement; a loop when an array recycles.""" + node = stmt.value + assert isinstance(node, ir.Call) + ctx.file_directive("stdout") + if node.func == "disp": + return [ctx.line(ast.unparse(_disp(node, ctx)))] + if node.func not in ("printf", "fprintf"): + return [ctx.line(ast.unparse(translate(node, ctx)))] + pieces, args = _format_and_args(node, ctx) + if _is_array_call(args, ctx): + loop = _array_loop(pieces, args[0], ctx) + header = f"for {loop.target} in {ast.unparse(loop.iterable)}:" + return [ctx.line(header), ctx.line(ast.unparse(_print(loop.parts, ctx)), extra=1)] + return [ctx.line(ast.unparse(_print(_scalars(pieces, args, ctx), ctx)))] + + +def _disp(node: ir.Call, ctx: Context) -> ast.expr: + if len(node.args) != 1: + ctx.decline("disp with more than one argument") + if ctx.info(node.args[0]).kind is not Kind.STRING: + ctx.decline("disp of a value that is not a string (its number format is not Python's)") + return ctx.call(ast.Name("print"), ctx.expr(node.args[0])) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``sprintf`` as a value; the printing functions only as statements.""" + if node.func != "sprintf": + ctx.decline(f"{node.func} used as a value") + pieces, args = _format_and_args(node, ctx) + if _is_array_call(args, ctx): + loop = _array_loop(pieces, args[0], ctx) + generator = ast.ListComp( + elt=_joined(loop.parts), + generators=[ + ast.comprehension( + target=ast.Name(loop.target), iter=loop.iterable, ifs=[], is_async=0 + ) + ], + ) + return ctx.method(ast.Constant(""), "join", generator) + return _joined(_scalars(pieces, args, ctx)) + + +def format_text(fmt: str, args: list[ir.Expr], ctx: Context) -> ast.expr: + """``sprintf(fmt, args...)`` for other rules (``num2str(x, fmt)``).""" + try: + pieces = parse_format(fmt) + except ValueError as exc: + ctx.decline(f"a format with {exc}") + return _joined(_scalars(pieces, args, ctx)) + + +# --- Python -> .m ------------------------------------------------------------ +# +# print() of literal text, strings and f-strings becomes fprintf with the +# matching format (disp for a single string); an f-string used as a value is +# sprintf. Each {value:spec} field maps to a conversion when Python and printf +# format it the same way: d, f, e, g (and E, G) with width, precision, sign, +# zero padding and alignment, and strings. A number without a spec prints +# with Python's repr, which no printf format reproduces, so it is declined, +# except an integer, whose digits are the same under %d. + +_PY_SPEC = re.compile( + r"^(?:(?P.)?(?P[<>=^]))?(?P[-+ ])?(?P#)?(?P0)?" + r"(?P\d+)?(?P[,_])?(?:\.(?P\d+))?(?P[A-Za-z%])?$" +) + + +def _m_literal(text: str, ctx: LiftContext) -> str: + """Python text as printf format text: ``%`` doubled, control characters escaped.""" + out = [] + for char in text: + if char == "%": + out.append("%%") + elif char == "\\": + out.append("\\\\") + elif char == "\n": + out.append("\\n") + elif char == "\t": + out.append("\\t") + elif ord(char) < 32 or ord(char) == 127: + ctx.decline("printing a control character") + else: + out.append(char) + return "".join(out) + + +def _m_conversion(spec: str, value: ast.expr, ctx: LiftContext) -> tuple[str, ir.Expr]: + """``%...`` and the value for one f-string field.""" + info = ctx.info(value) + is_string = info.kind is PyKind.STRING + match = _PY_SPEC.match(spec) + if match is None: + ctx.decline(f"the format spec {spec!r}") + if isinstance(value, ast.Call) and isinstance(value.func, ast.Name) and value.func.id == "int": + # f"{int(x):5d}": an integer, the same digits as %5d of fix(x). + if match.group("type") not in (None, "d") or len(value.args) != 1 or value.keywords: + ctx.decline("int() with this format spec inside an f-string") + if ctx.info(value.args[0]).kind is PyKind.STRING: + ctx.decline("int() of a string") + inner = value.args[0] + fixed = ( + ctx.expr(inner) + if ctx.info(inner).dtype is DType.INT # already whole: int() changes nothing + else ctx.call("fix", ctx.expr(inner), loc=ctx.loc(value)) + ) + flags = "-" if match.group("align") == "<" else "" + flags += match.group("sign") if match.group("sign") in ("+", " ") else "" + flags += "0" if match.group("zero") and match.group("align") != "<" else "" + align = match.group("align") + if match.group("precision") or match.group("grouping") or align in ("=", "^"): + ctx.decline(f"the format spec {spec!r} on an integer") + return f"%{flags}{match.group('width') or ''}d", fixed + fill, align, sign = match.group("fill"), match.group("align"), match.group("sign") + kind, width, precision = match.group("type"), match.group("width"), match.group("precision") + if (fill not in (None, " ")) or align in ("=", "^") or match.group("grouping"): + ctx.decline(f"the format spec {spec!r} (fill, centring or grouping)") + flags = "" + if is_string: + if kind not in (None, "s") or sign or match.group("zero") or match.group("alt"): + ctx.decline(f"the format spec {spec!r} on a string") + if align != ">" and width: + flags = "-" # Python left-aligns strings, printf right-aligns them + dot = f".{precision}" if precision else "" + return f"%{flags}{width or ''}{dot}s", ctx.expr(value) + if not info.is_scalar or info.dtype is DType.COMPLEX: + ctx.decline("formatting a value that is not a real scalar") + if kind is None and not precision and info.dtype in (DType.INT, DType.BOOL): + if info.dtype is DType.BOOL: + ctx.decline("formatting a bool (Python prints True/False)") + kind = "d" + if kind not in ("d", "f", "e", "E", "g", "G"): + ctx.decline(f"the format spec {spec!r} (Python's own number format)") + if kind == "d" and info.dtype not in (DType.INT, DType.BOOL): + ctx.decline("{:d} of a value that is not an integer") + if kind == "d" and precision: + ctx.decline("a precision on an integer") + if not info.finite: + ctx.assume("finite values printed (Python prints inf/nan, the .m side Inf/NaN)") + flags += "-" if align == "<" else "" + flags += sign if sign in ("+", " ") else "" + flags += "#" if match.group("alt") else "" + flags += "0" if match.group("zero") and align != "<" else "" + dot = f".{precision}" if precision else "" + return f"%{flags}{width or ''}{dot}{kind}", ctx.expr(value) + + +def _m_format(parts: list[ast.expr], ctx: LiftContext) -> tuple[str, list[ir.Expr]]: + """The printf format and values for a sequence of printed Python values.""" + fmt: list[str] = [] + values: list[ir.Expr] = [] + for part in parts: + if isinstance(part, ast.Constant) and isinstance(part.value, str): + fmt.append(_m_literal(part.value, ctx)) + elif isinstance(part, ast.JoinedStr): + for piece in part.values: + if isinstance(piece, ast.Constant) and isinstance(piece.value, str): + fmt.append(_m_literal(piece.value, ctx)) + continue + assert isinstance(piece, ast.FormattedValue) + if piece.conversion != -1: + ctx.decline("a !r/!s/!a conversion in an f-string") + spec = "" + if piece.format_spec is not None: + inner = piece.format_spec + assert isinstance(inner, ast.JoinedStr) + if not all( + isinstance(v, ast.Constant) and isinstance(v.value, str) + for v in inner.values + ): + ctx.decline("a computed format spec") + spec = "".join( + str(v.value) for v in inner.values if isinstance(v, ast.Constant) + ) + conversion, value = _m_conversion(spec, piece.value, ctx) + fmt.append(conversion) + values.append(value) + else: + conversion, value = _m_conversion("", part, ctx) + fmt.append(conversion) + values.append(value) + return "".join(fmt), values + + +def _lift_join(node: ast.Call, ctx: LiftContext) -> ir.Expr: + """``"".join([f"..." for v in values])``: ``sprintf`` recycles its format per element.""" + loc = ctx.loc(node) + receiver = node.func.value if isinstance(node.func, ast.Attribute) else None + comprehension = node.args[0] if len(node.args) == 1 and not node.keywords else None + if not ( + isinstance(receiver, ast.Constant) + and receiver.value == "" + and isinstance(comprehension, ast.ListComp | ast.GeneratorExp) + and len(comprehension.generators) == 1 + and not comprehension.generators[0].ifs + and isinstance(comprehension.generators[0].target, ast.Name) + and isinstance(comprehension.elt, ast.JoinedStr) + ): + ctx.decline("str.join of anything but f-strings over one array") + generator = comprehension.generators[0] + assert isinstance(generator.target, ast.Name) + if not ctx.info(generator.iter).is_vector: + ctx.decline("joining over a value that is not a 1-D array") + fields = [p for p in comprehension.elt.values if isinstance(p, ast.FormattedValue)] + loop_name = generator.target.id + for field in fields: + value = field.value + if isinstance(value, ast.Call) and isinstance(value.func, ast.Name): + value = value.args[0] if value.func.id == "int" and value.args else value + if not (isinstance(value, ast.Name) and value.id == loop_name) or len(fields) != 1: + ctx.decline("a joined f-string with fields other than the one loop value") + fmt, _values = _m_format([comprehension.elt], ctx) + values = ctx.module_for("syntax/array-literals").lift_items(generator.iter, ctx) + return ctx.call("sprintf", ir.Str(loc=loc, value=fmt, quote="'"), values, loc=loc) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``print(...)`` as ``fprintf``/``disp``; an f-string value as ``sprintf``.""" + loc = ctx.loc(node) + if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute): + return _lift_join(node, ctx) + if isinstance(node, ast.JoinedStr): + fmt, values = _m_format([node], ctx) + return ctx.call("sprintf", ir.Str(loc=loc, value=fmt, quote="'"), *values, loc=loc) + assert isinstance(node, ast.Call) + sep, end = " ", "\n" + for keyword in node.keywords: + if keyword.arg not in ("sep", "end") or not ( + isinstance(keyword.value, ast.Constant) and isinstance(keyword.value.value, str) + ): + ctx.decline(f"print with {keyword.arg}=") + if keyword.arg == "sep": + sep = str(keyword.value.value) + else: + end = str(keyword.value.value) + ctx.file_directive("stdout") + args = list(node.args) + if ( + len(args) == 1 + and end == "\n" + and ctx.info(args[0]).kind is PyKind.STRING + and not isinstance(args[0], ast.JoinedStr) + ): + return ctx.call("disp", ctx.expr(args[0]), loc=loc) + parts: list[ast.expr] = [] + for k, arg in enumerate(args): + if k: + parts.append(ast.Constant(sep)) + parts.append(arg) + parts.append(ast.Constant(end)) + fmt, values = _m_format(parts, ctx) + return ctx.call("fprintf", ir.Str(loc=loc, value=fmt, quote="'"), *values, loc=loc) diff --git a/rules/operators/arithmetic/translate.py b/rules/operators/arithmetic/translate.py index bcb5874..dc98dcb 100644 --- a/rules/operators/arithmetic/translate.py +++ b/rules/operators/arithmetic/translate.py @@ -93,6 +93,10 @@ def translate(node: ir.BinOp | ir.UnOp, ctx: Context) -> ast.expr: if node.op == "uplus": return operand if node.op == "uminus": + if isinstance(node.operand, ir.Num) and node.operand.value == 0: + # -0 is a negative zero in the source (doubles); Python's int + # 0 has no sign, which shows when it is printed or divided by. + return ast.UnaryOp(op=ast.USub(), operand=ast.Constant(0.0)) return ast.UnaryOp(op=ast.USub(), operand=operand) ctx.decline(f"unary {node.op}") a, b = expand(node, ctx) diff --git a/rules/types/double/cases/basic.m b/rules/types/double/cases/basic.m new file mode 100644 index 0000000..3677a5f --- /dev/null +++ b/rules/types/double/cases/basic.m @@ -0,0 +1,6 @@ +mask = [1 5 3] > 2; +counts = double(mask); % 0 1 1, as numbers +n = double(true) + 1; +flags = logical([2 0 -1]); % nonzero is true +x = [1 2 3]; +y = double(x) / 2; % already a double: no change diff --git a/rules/types/double/cases/basic.py b/rules/types/double/cases/basic.py new file mode 100644 index 0000000..2d8f64f --- /dev/null +++ b/rules/types/double/cases/basic.py @@ -0,0 +1,8 @@ +import numpy as np + +mask = np.array([1, 5, 3]) > 2 +counts = mask.astype(float) # 0 1 1, as numbers +n = float(True) + 1 +flags = np.array([2, 0, -1]).astype(bool) # nonzero is true +x = np.array([1, 2, 3]) +y = x / 2 # already a double: no change diff --git a/rules/types/double/rule.yaml b/rules/types/double/rule.yaml new file mode 100644 index 0000000..ae269eb --- /dev/null +++ b/rules/types/double/rule.yaml @@ -0,0 +1,33 @@ +id: types/double +title: "`double` and `logical`: converting between numbers and truth values" +status: mechanical +dialects: [octave, matlab] +match: [call:double, call:logical] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:method:astype + - py:call:float +octave: | + counts = double(mask); % true/false -> 1/0 + flags = logical([2 0 -1]); % nonzero -> true +python: | + counts = mask.astype(float) + flags = np.array([2, 0, -1]).astype(bool) +why: > + Every plain number in `.m` code is already a double, so `double(x)` only + changes logical (and char) values: a mask becomes 1s and 0s, which then add + up and multiply as numbers. NumPy spells the conversion `astype`; `float(x)` + for a single value. `logical(x)` is `x.astype(bool)`: nonzero is true. +pitfalls: + - >- + `logical(NaN)` is an error in `.m` code, while `np.nan.astype(bool)` is + `True`. + - >- + `double('A')` is the character code 65; `float('A')` is an error in + Python. Character data is not translated. + - >- + `x.astype(int)` truncates toward zero, while `int32(x)` rounds and + saturates: the integer types are not translated. +related: [operators/arithmetic, builtins/constants] +python_imports: [import numpy as np] diff --git a/rules/types/double/translate.py b/rules/types/double/translate.py new file mode 100644 index 0000000..a4f4e2d --- /dev/null +++ b/rules/types/double/translate.py @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for types/double: ``double(x)`` and ``logical(x)``. + +``double`` of a value that is already a number is that value; of a logical +array it is ``x.astype(float)`` (of a scalar, ``float(x)``). ``logical(x)`` +is ``x.astype(bool)`` (``bool(x)`` for a scalar). Character data is declined: +it converts to character codes, which Python does not do implicitly. + +From Python, ``x.astype(float)`` and ``float(x)`` are ``double(x)``, and +``x.astype(bool)`` is ``logical(x)`` for data known to hold no NaN (NumPy +makes NaN true, the ``.m`` side raises). Integer types are declined: they +round and saturate on the ``.m`` side and truncate and wrap in NumPy. +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Kind +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyKind + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``double(x)`` or ``logical(x)``.""" + if len(node.args) != 1: + ctx.decline(f"{node.func} with these arguments") + info = ctx.info(node.args[0]) + if info.kind is Kind.STRING or info.elem in (Elem.CHAR, Elem.COMPLEX): + ctx.decline(f"{node.func} of characters or complex values") + if info.elem is Elem.UNKNOWN or not (info.is_scalar or info.is_array): + ctx.decline(f"{node.func} of a value of unknown type") + expr = ctx.expr(node.args[0]) + if node.func == "double": + if info.elem is Elem.REAL: + return expr # every plain number is a double already + if info.is_scalar: + return ctx.call(ast.Name("float"), expr) + return ctx.method(expr, "astype", ast.Name("float")) + if info.elem is Elem.LOGICAL: + return expr + if not info.finite: + ctx.assume("no NaN in logical() (NumPy makes NaN true; the source raises)") + if info.is_scalar: + return ctx.call(ast.Name("bool"), expr) + return ctx.method(expr, "astype", ast.Name("bool")) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``x.astype(float)``, ``x.astype(bool)``, ``float(x)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if node.keywords or len(node.args) != 1: + ctx.decline("a conversion with these arguments") + if isinstance(node.func, ast.Name): # float(x) + info = ctx.info(node.args[0]) + if info.kind is PyKind.STRING or not info.is_scalar: + ctx.decline("float() of a string or of a value that is not a number") + return ctx.call("double", ctx.expr(node.args[0]), loc=loc) + assert isinstance(node.func, ast.Attribute) + receiver = node.func.value + target = node.args[0] + name = target.id if isinstance(target, ast.Name) else None + info = ctx.info(receiver) + if not info.is_array or info.dtype is DType.COMPLEX: + ctx.decline("astype of a value that is not a real array") + value = ctx.module_for("syntax/array-literals").lift_items(receiver, ctx) + if name == "float": + return ctx.call("double", value, loc=loc) + if name == "bool": + if not info.finite: + ctx.decline("astype(bool) of data that may hold NaN (the .m logical() raises)") + return ctx.call("logical", value, loc=loc) + ctx.decline(f"astype({ast.unparse(target)}) (integer types round and saturate in .m code)") diff --git a/tests/test_adversarial.py b/tests/test_adversarial.py index 3600d00..26a0683 100644 --- a/tests/test_adversarial.py +++ b/tests/test_adversarial.py @@ -75,6 +75,25 @@ "cnt = 0;\nfor i = 5:-1:1\n cnt = cnt + i;\nend\n" ), "lambda-same-shapes": ("f = @(x) x * x';\nb = [1; 2; 3];\na1 = f(b);\na2 = f(2 * b);\n"), + # Printing is compared character for character (`# dualect: stdout`). + "printf-formats": ( + "x = 3.14159;\nfprintf('%#g %#.3e %+05d [% +d] [%-05d]\\n', 2, 3, 4, 3, 3);\n" + "fprintf('%e %E %G\\n', 1.5e-300, 2.5e10, 1e-10);\ns = 'abcdef';\n" + "fprintf('[%8.3s][%-8.3s]\\n', s, s);\nfprintf('{x} = %d {} 50%%\\n', 3);\n" + "fprintf('a\\\\b\\n');\nfprintf(\"tab\\there %d\\n\", 4);\nz = -0;\n" + "fprintf('%d|%.1f\\n', z, z);\nn = 2^62;\nfprintf('%d\\n', n);\n" + "m = 3 > 2;\nfprintf('%d %f\\n', m, m);\n" + ), + "printf-recycling": ( + "A = [1 2; 3 4];\nfprintf('%d,', A);\nfprintf('\\n');\nc = [1; 2; 3];\n" + "fprintf('%d\\n', c);\nt = sprintf('%d;', A);\nfor k = 1:3\n" + " printf('%d:%d\\n', k, k^2);\nend\nfprintf('%d %d\\n', 7, 8, 9);\n" + ), + "filter-forms": ( + "y1 = filter([1 1], 2, [1 2 3]);\nX = [1 2 3; 4 5 6];\nY = filter(1, [1 -0.5], X);\n" + "1;\nfunction y = f(x)\n y = filter([1 1], 1, x);\nend\na = f([1 2 3]);\n" + "b = f([1; 2; 3]);\n" + ), } #: Snippets whose given (1-based) line must become a hole, not a guess. @@ -89,6 +108,20 @@ "r = [4 5 6];\no1 = op(b, r);\no2 = op(r, b);\n", 3), "mod-by-zero": ("m = mod(-1, 0);\n", 1), "empty-loop": ("z = 0;\nfor j = 1:0\n z = z + 1;\nend\n", 2), + # %d of a fraction prints it in another format, not rounded or truncated. + "printf-d-of-fraction": ("x = 7 / 2;\nfprintf('%d\\n', x);\n", 2), + "printf-s-of-number": ("fprintf('%s\\n', 65);\n", 1), + "printf-d-of-string": ("fprintf('%d\\n', 'ab');\n", 1), + "printf-file-id": ("fid = 2;\nfprintf(fid, 'x\\n');\n", 2), + "printf-hex": ("fprintf('%x\\n', 255);\n", 1), + "printf-inf": ("fprintf('%f %g\\n', Inf, -Inf);\n", 1), + "printf-huge-integer": ("n = 1e20;\nfprintf('%d\\n', n);\n", 2), + "printf-empty-array": ("s = sprintf('x%dy', []);\n", 1), + "printf-mixed-array": ("v = [1 2];\nfprintf('%d %d\\n', 3, v);\n", 2), + "printf-rows-per-pass": ("A = [1 2 3; 4 5 6];\nfprintf('%d %d %d\\n', A);\n", 2), + "disp-of-number": ("disp(0.1)\n", 1), + "filter-scalar-data": ("y = filter(2, 1, 5);\n", 1), + "filter-state": ("[y, z] = filter([1 1], 1, [1 2 3]);\n", 1), } # fmt: skip diff --git a/tests/test_corpus.py b/tests/test_corpus.py index 6ea54a1..a6bf02d 100644 --- a/tests/test_corpus.py +++ b/tests/test_corpus.py @@ -82,3 +82,17 @@ def test_corpus_statements_are_all_lowered() -> None: program = lower_source(text=source.read_text(encoding="utf-8"), name=source.name) opaque = [s for s in ir.walk_stmts(program.body) if isinstance(s, ir.OpaqueStmt)] assert opaque == [], source.name + + +#: Corpus files every statement of which has a mechanical translation (both +#: directions are then verified by the tests above and in test_reverse.py). +COMPLETE = {"beam_deflection", "ode_rk4", "signal_filter"} + + +@pytest.mark.parametrize("name", sorted(COMPLETE)) +def test_corpus_file_translates_completely(name: str, tmp_path: Path) -> None: + source = REPO_ROOT / "corpus" / f"{name}.m" + result = translate_file( + source=source, output=tmp_path / f"{name}.py", rules=RULES, dialect=Dialect(), verify=False + ) + assert result.complete, result.report() diff --git a/tests/test_reverse.py b/tests/test_reverse.py index dc8f4b4..0301d8e 100644 --- a/tests/test_reverse.py +++ b/tests/test_reverse.py @@ -200,9 +200,9 @@ def test_scan_and_context_read_python(tmp_path: Path) -> None: source.write_text("import numpy as np\nx = np.zeros(3)\nprint(x)\n", encoding="utf-8") result = scan_file(path=source, rules=RULES, dialect=Dialect()) ids = {rule.id for rule in result.needed_rules()} - assert {"builtins/zeros-ones-eye", "io/display"} <= ids + assert {"builtins/zeros-ones-eye", "io/printf"} <= ids assert result.as_json()["direction"] == "from-python" - assert result.status_of(next(r for r in RULES if r.id == "io/display")) is Status.GUIDED + assert result.status_of(next(r for r in RULES if r.id == "io/printf")) is Status.MECHANICAL @pytest.mark.octave diff --git a/tests/test_verify.py b/tests/test_verify.py index f6260a8..67bcbf0 100644 --- a/tests/test_verify.py +++ b/tests/test_verify.py @@ -9,8 +9,8 @@ from conftest import DATA_DIR from dualect.errors import DirectiveError, ExecutionError -from dualect.runners import MRunner, run_py_script -from dualect.verify import parse_directives, verify_pair +from dualect.runners import MRunner, run_py_script, run_py_script_capturing +from dualect.verify import STDOUT, parse_directives, read_directives, verify_pair def test_parse_directives_both_comment_styles() -> None: @@ -107,3 +107,53 @@ def test_octave_failure_is_named(m_runner: MRunner, tmp_path: Path) -> None: ok_file = tmp_path / "ok.m" ok_file.write_text("z = 2;\n") assert m_runner.run(path=ok_file) == {"z": 2.0} + + +def test_flag_directives() -> None: + text = "% dualect: stdout\n% dualect: shape r s\nx = 1;\n" + found = read_directives(text=text, path=Path("t.m")) + assert found.stdout and found.shape == {"r", "s"} + with pytest.raises(DirectiveError): + read_directives(text="% dualect: stdout x\n", path=Path("t.m")) + + +def test_python_runner_captures_output(tmp_path: Path) -> None: + script = tmp_path / "s.py" + script.write_text("x = 1\nprint('a ')\nprint('b', end='')\n") + outputs, printed = run_py_script_capturing(path=script) + assert outputs == {"x": 1} and printed == "a \nb" + + +@pytest.mark.octave +def test_printed_output_is_compared_exactly(m_runner: MRunner, tmp_path: Path) -> None: + # Trailing spaces and a last line without a newline both count. + m_file = tmp_path / "t.m" + m_file.write_text("x = 1;\nprintf('a \\n');\nprintf('b');\n% dualect: stdout\n") + good, bad, silent = (tmp_path / name for name in ("good.py", "bad.py", "silent.py")) + good.write_text("x = 1\nprint('a ')\nprint('b', end='')\n") + bad.write_text("x = 1\nprint('a')\nprint('b')\n") + silent.write_text("x = 1\n") + assert verify_pair(m_path=m_file, py_path=good, runner=m_runner).ok + result = verify_pair(m_path=m_file, py_path=bad, runner=m_runner) + assert not result.ok and STDOUT in result.report() + assert not verify_pair(m_path=m_file, py_path=silent, runner=m_runner).ok + + +@pytest.mark.octave +def test_output_is_not_compared_without_the_directive(m_runner: MRunner, tmp_path: Path) -> None: + m_file = tmp_path / "t.m" + m_file.write_text("x = 1\n") # displays "x = 1" + py_file = tmp_path / "t.py" + py_file.write_text("x = 1\n") + assert verify_pair(m_path=m_file, py_path=py_file, runner=m_runner).ok + + +@pytest.mark.octave +def test_shape_directive_compares_shape_only(m_runner: MRunner, tmp_path: Path) -> None: + m_file = tmp_path / "t.m" + m_file.write_text("r = rand(2, 3);\n% dualect: shape r\n") + right, wrong = tmp_path / "right.py", tmp_path / "wrong.py" + right.write_text("import numpy as np\nr = np.random.rand(2, 3)\n") + wrong.write_text("import numpy as np\nr = np.random.rand(3, 2)\n") + assert verify_pair(m_path=m_file, py_path=right, runner=m_runner).ok + assert not verify_pair(m_path=m_file, py_path=wrong, runner=m_runner).ok diff --git a/uv.lock b/uv.lock index a926209..5cee9a3 100644 --- a/uv.lock +++ b/uv.lock @@ -356,6 +356,8 @@ dependencies = [ { name = "oct2py" }, { name = "pyyaml" }, { name = "ruff" }, + { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" }, + { name = "scipy", version = "1.18.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" }, { name = "tree-sitter" }, { name = "tree-sitter-matlab" }, ] @@ -377,6 +379,7 @@ requires-dist = [ { name = "oct2py", specifier = ">=5.8" }, { name = "pyyaml", specifier = ">=6.0" }, { name = "ruff", specifier = ">=0.8" }, + { name = "scipy", specifier = ">=1.13" }, { name = "tree-sitter", specifier = ">=0.24" }, { name = "tree-sitter-matlab", specifier = ">=1.3.3,<2" }, ] From ce16506ccd6c190b345d0933e9dbbc0064228f44 Mon Sep 17 00:00:00 2001 From: Evan Gress <106449014+evangress@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:57:09 -0500 Subject: [PATCH 2/4] Widen built-in coverage: 22 new rule folders, inference hooks per rule Rules teach the analysis what their built-ins return (infer_call, infer_outputs, pyinfer_call in translate.py), so a new built-in stays one folder; multi-output built-ins lift through their own rule's lift_multi. New rules, with cases in both languages: cumsum-cumprod, diff, any-all, sort (stable index output), unique, flip, reshape (column-major), repmat, concatenation-functions (cat/horzcat/vertcat), meshgrid, rand-randn (compared by shape), norm, dot-cross-kron, linear-algebra (inv/det/trace/ rank), std-var (N-1), median, interp1 (NaN outside the range), polyfit- polyval, trapz, type-tests, num2str, tic-toc (guided). Extended: constants (true/false/Inf/NaN with sizes), elementwise-math (floor division, real/imag/conj/log1p/expm1, mod/rem sign rules), size-numel- length (ndims), sum-mean-max (min case, dtype=float lift). Forms that cannot be proved are declined by name. The Octave runner resets `format` between scripts (a `format long` leaked into later display output), and Python-to-.m verification honours the source's shape and stdout directives. Co-Authored-By: Claude Opus 5.5 --- dualect/emit.py | 4 + dualect/infer.py | 40 ++- dualect/lift.py | 20 +- dualect/pipeline.py | 13 +- dualect/pyinfer.py | 73 ++++- dualect/runners.py | 5 +- dualect/scan.py | 9 +- dualect/translators.py | 16 + llms.txt | 30 +- rules/builtins/any-all/cases/basic.m | 9 + rules/builtins/any-all/cases/basic.py | 11 + rules/builtins/any-all/cases/empty.m | 8 + rules/builtins/any-all/cases/empty.py | 10 + rules/builtins/any-all/rule.yaml | 39 +++ rules/builtins/any-all/translate.py | 73 +++++ .../concatenation-functions/cases/basic.m | 14 + .../concatenation-functions/cases/basic.py | 16 + .../concatenation-functions/rule.yaml | 35 +++ .../concatenation-functions/translate.py | 137 +++++++++ rules/builtins/constants/cases/filled.m | 7 + rules/builtins/constants/cases/filled.py | 9 + rules/builtins/constants/rule.yaml | 7 +- rules/builtins/constants/translate.py | 111 ++++++- rules/builtins/cumsum-cumprod/cases/basic.m | 8 + rules/builtins/cumsum-cumprod/cases/basic.py | 10 + .../builtins/cumsum-cumprod/cases/overflow.m | 5 + .../builtins/cumsum-cumprod/cases/overflow.py | 7 + rules/builtins/cumsum-cumprod/rule.yaml | 40 +++ rules/builtins/cumsum-cumprod/translate.py | 159 ++++++++++ rules/builtins/diff/cases/basic.m | 8 + rules/builtins/diff/cases/basic.py | 10 + rules/builtins/diff/rule.yaml | 36 +++ rules/builtins/diff/translate.py | 201 +++++++++++++ rules/builtins/dot-cross-kron/cases/basic.m | 12 + rules/builtins/dot-cross-kron/cases/basic.py | 14 + rules/builtins/dot-cross-kron/rule.yaml | 42 +++ rules/builtins/dot-cross-kron/translate.py | 171 +++++++++++ .../elementwise-math/cases/sign-rules.m | 14 + .../elementwise-math/cases/sign-rules.py | 16 + rules/builtins/elementwise-math/rule.yaml | 20 ++ rules/builtins/elementwise-math/translate.py | 85 +++++- .../filter/cases/{columns.m => matrix.m} | 0 .../filter/cases/{columns.py => matrix.py} | 0 rules/builtins/flip/cases/basic.m | 12 + rules/builtins/flip/cases/basic.py | 14 + rules/builtins/flip/rule.yaml | 38 +++ rules/builtins/flip/translate.py | 147 ++++++++++ rules/builtins/interp1/cases/basic.m | 9 + rules/builtins/interp1/cases/basic.py | 13 + rules/builtins/interp1/rule.yaml | 33 +++ rules/builtins/interp1/translate.py | 188 ++++++++++++ rules/builtins/linear-algebra/cases/basic.m | 11 + rules/builtins/linear-algebra/cases/basic.py | 15 + rules/builtins/linear-algebra/rule.yaml | 39 +++ rules/builtins/linear-algebra/translate.py | 102 +++++++ rules/builtins/median/cases/basic.m | 8 + rules/builtins/median/cases/basic.py | 10 + rules/builtins/median/rule.yaml | 36 +++ rules/builtins/median/translate.py | 109 +++++++ rules/builtins/meshgrid/cases/basic.m | 7 + rules/builtins/meshgrid/cases/basic.py | 9 + rules/builtins/meshgrid/rule.yaml | 34 +++ rules/builtins/meshgrid/translate.py | 159 ++++++++++ rules/builtins/norm/cases/basic.m | 10 + rules/builtins/norm/cases/basic.py | 12 + rules/builtins/norm/rule.yaml | 33 +++ rules/builtins/norm/translate.py | 146 ++++++++++ rules/builtins/num2str/cases/basic.m | 11 + rules/builtins/num2str/cases/basic.py | 13 + rules/builtins/num2str/rule.yaml | 42 +++ rules/builtins/num2str/translate.py | 150 ++++++++++ rules/builtins/polyfit-polyval/cases/basic.m | 8 + rules/builtins/polyfit-polyval/cases/basic.py | 10 + rules/builtins/polyfit-polyval/rule.yaml | 36 +++ rules/builtins/polyfit-polyval/translate.py | 111 +++++++ rules/builtins/rand-randn/cases/basic.m | 9 + rules/builtins/rand-randn/cases/basic.py | 11 + rules/builtins/rand-randn/rule.yaml | 42 +++ rules/builtins/rand-randn/translate.py | 197 +++++++++++++ rules/builtins/repmat/cases/basic.m | 12 + rules/builtins/repmat/cases/basic.py | 14 + rules/builtins/repmat/rule.yaml | 33 +++ rules/builtins/repmat/translate.py | 160 ++++++++++ rules/builtins/reshape/cases/basic.m | 8 + rules/builtins/reshape/cases/basic.py | 10 + rules/builtins/reshape/cases/write-after.m | 5 + rules/builtins/reshape/cases/write-after.py | 7 + rules/builtins/reshape/rule.yaml | 36 +++ rules/builtins/reshape/translate.py | 229 +++++++++++++++ .../builtins/size-numel-length/cases/basic.m | 4 + .../builtins/size-numel-length/cases/basic.py | 4 + rules/builtins/size-numel-length/rule.yaml | 8 +- rules/builtins/size-numel-length/translate.py | 18 +- rules/builtins/sort/cases/basic.m | 7 + rules/builtins/sort/cases/basic.py | 9 + rules/builtins/sort/cases/nan-values.m | 6 + rules/builtins/sort/cases/nan-values.py | 10 + rules/builtins/sort/cases/positions.m | 7 + rules/builtins/sort/cases/positions.py | 13 + rules/builtins/sort/rule.yaml | 44 +++ rules/builtins/sort/translate.py | 275 ++++++++++++++++++ rules/builtins/std-var/cases/basic.m | 9 + rules/builtins/std-var/cases/basic.py | 11 + rules/builtins/std-var/cases/one-element.m | 4 + rules/builtins/std-var/cases/one-element.py | 6 + rules/builtins/std-var/rule.yaml | 42 +++ rules/builtins/std-var/translate.py | 193 ++++++++++++ rules/builtins/sum-mean-max/cases/min-nan.m | 9 + rules/builtins/sum-mean-max/cases/min-nan.py | 12 + rules/builtins/sum-mean-max/rule.yaml | 6 +- rules/builtins/sum-mean-max/translate.py | 5 + rules/builtins/tic-toc/cases/basic.m | 5 + rules/builtins/tic-toc/cases/basic.py | 9 + rules/builtins/tic-toc/rule.yaml | 41 +++ rules/builtins/trapz/cases/basic.m | 10 + rules/builtins/trapz/cases/basic.py | 12 + rules/builtins/trapz/rule.yaml | 33 +++ rules/builtins/trapz/translate.py | 105 +++++++ rules/builtins/type-tests/cases/basic.m | 14 + rules/builtins/type-tests/cases/basic.py | 16 + rules/builtins/type-tests/rule.yaml | 29 ++ rules/builtins/type-tests/translate.py | 44 +++ rules/builtins/unique/cases/basic.m | 8 + rules/builtins/unique/cases/basic.py | 10 + rules/builtins/unique/rule.yaml | 33 +++ rules/builtins/unique/translate.py | 96 ++++++ rules/functions/multiple-returns/translate.py | 11 +- rules/io/printf/cases/integers.py | 2 +- 128 files changed, 5031 insertions(+), 51 deletions(-) create mode 100644 rules/builtins/any-all/cases/basic.m create mode 100644 rules/builtins/any-all/cases/basic.py create mode 100644 rules/builtins/any-all/cases/empty.m create mode 100644 rules/builtins/any-all/cases/empty.py create mode 100644 rules/builtins/any-all/rule.yaml create mode 100644 rules/builtins/any-all/translate.py create mode 100644 rules/builtins/concatenation-functions/cases/basic.m create mode 100644 rules/builtins/concatenation-functions/cases/basic.py create mode 100644 rules/builtins/concatenation-functions/rule.yaml create mode 100644 rules/builtins/concatenation-functions/translate.py create mode 100644 rules/builtins/constants/cases/filled.m create mode 100644 rules/builtins/constants/cases/filled.py create mode 100644 rules/builtins/cumsum-cumprod/cases/basic.m create mode 100644 rules/builtins/cumsum-cumprod/cases/basic.py create mode 100644 rules/builtins/cumsum-cumprod/cases/overflow.m create mode 100644 rules/builtins/cumsum-cumprod/cases/overflow.py create mode 100644 rules/builtins/cumsum-cumprod/rule.yaml create mode 100644 rules/builtins/cumsum-cumprod/translate.py create mode 100644 rules/builtins/diff/cases/basic.m create mode 100644 rules/builtins/diff/cases/basic.py create mode 100644 rules/builtins/diff/rule.yaml create mode 100644 rules/builtins/diff/translate.py create mode 100644 rules/builtins/dot-cross-kron/cases/basic.m create mode 100644 rules/builtins/dot-cross-kron/cases/basic.py create mode 100644 rules/builtins/dot-cross-kron/rule.yaml create mode 100644 rules/builtins/dot-cross-kron/translate.py create mode 100644 rules/builtins/elementwise-math/cases/sign-rules.m create mode 100644 rules/builtins/elementwise-math/cases/sign-rules.py rename rules/builtins/filter/cases/{columns.m => matrix.m} (100%) rename rules/builtins/filter/cases/{columns.py => matrix.py} (100%) create mode 100644 rules/builtins/flip/cases/basic.m create mode 100644 rules/builtins/flip/cases/basic.py create mode 100644 rules/builtins/flip/rule.yaml create mode 100644 rules/builtins/flip/translate.py create mode 100644 rules/builtins/interp1/cases/basic.m create mode 100644 rules/builtins/interp1/cases/basic.py create mode 100644 rules/builtins/interp1/rule.yaml create mode 100644 rules/builtins/interp1/translate.py create mode 100644 rules/builtins/linear-algebra/cases/basic.m create mode 100644 rules/builtins/linear-algebra/cases/basic.py create mode 100644 rules/builtins/linear-algebra/rule.yaml create mode 100644 rules/builtins/linear-algebra/translate.py create mode 100644 rules/builtins/median/cases/basic.m create mode 100644 rules/builtins/median/cases/basic.py create mode 100644 rules/builtins/median/rule.yaml create mode 100644 rules/builtins/median/translate.py create mode 100644 rules/builtins/meshgrid/cases/basic.m create mode 100644 rules/builtins/meshgrid/cases/basic.py create mode 100644 rules/builtins/meshgrid/rule.yaml create mode 100644 rules/builtins/meshgrid/translate.py create mode 100644 rules/builtins/norm/cases/basic.m create mode 100644 rules/builtins/norm/cases/basic.py create mode 100644 rules/builtins/norm/rule.yaml create mode 100644 rules/builtins/norm/translate.py create mode 100644 rules/builtins/num2str/cases/basic.m create mode 100644 rules/builtins/num2str/cases/basic.py create mode 100644 rules/builtins/num2str/rule.yaml create mode 100644 rules/builtins/num2str/translate.py create mode 100644 rules/builtins/polyfit-polyval/cases/basic.m create mode 100644 rules/builtins/polyfit-polyval/cases/basic.py create mode 100644 rules/builtins/polyfit-polyval/rule.yaml create mode 100644 rules/builtins/polyfit-polyval/translate.py create mode 100644 rules/builtins/rand-randn/cases/basic.m create mode 100644 rules/builtins/rand-randn/cases/basic.py create mode 100644 rules/builtins/rand-randn/rule.yaml create mode 100644 rules/builtins/rand-randn/translate.py create mode 100644 rules/builtins/repmat/cases/basic.m create mode 100644 rules/builtins/repmat/cases/basic.py create mode 100644 rules/builtins/repmat/rule.yaml create mode 100644 rules/builtins/repmat/translate.py create mode 100644 rules/builtins/reshape/cases/basic.m create mode 100644 rules/builtins/reshape/cases/basic.py create mode 100644 rules/builtins/reshape/cases/write-after.m create mode 100644 rules/builtins/reshape/cases/write-after.py create mode 100644 rules/builtins/reshape/rule.yaml create mode 100644 rules/builtins/reshape/translate.py create mode 100644 rules/builtins/sort/cases/basic.m create mode 100644 rules/builtins/sort/cases/basic.py create mode 100644 rules/builtins/sort/cases/nan-values.m create mode 100644 rules/builtins/sort/cases/nan-values.py create mode 100644 rules/builtins/sort/cases/positions.m create mode 100644 rules/builtins/sort/cases/positions.py create mode 100644 rules/builtins/sort/rule.yaml create mode 100644 rules/builtins/sort/translate.py create mode 100644 rules/builtins/std-var/cases/basic.m create mode 100644 rules/builtins/std-var/cases/basic.py create mode 100644 rules/builtins/std-var/cases/one-element.m create mode 100644 rules/builtins/std-var/cases/one-element.py create mode 100644 rules/builtins/std-var/rule.yaml create mode 100644 rules/builtins/std-var/translate.py create mode 100644 rules/builtins/sum-mean-max/cases/min-nan.m create mode 100644 rules/builtins/sum-mean-max/cases/min-nan.py create mode 100644 rules/builtins/tic-toc/cases/basic.m create mode 100644 rules/builtins/tic-toc/cases/basic.py create mode 100644 rules/builtins/tic-toc/rule.yaml create mode 100644 rules/builtins/trapz/cases/basic.m create mode 100644 rules/builtins/trapz/cases/basic.py create mode 100644 rules/builtins/trapz/rule.yaml create mode 100644 rules/builtins/trapz/translate.py create mode 100644 rules/builtins/type-tests/cases/basic.m create mode 100644 rules/builtins/type-tests/cases/basic.py create mode 100644 rules/builtins/type-tests/rule.yaml create mode 100644 rules/builtins/type-tests/translate.py create mode 100644 rules/builtins/unique/cases/basic.m create mode 100644 rules/builtins/unique/cases/basic.py create mode 100644 rules/builtins/unique/rule.yaml create mode 100644 rules/builtins/unique/translate.py diff --git a/dualect/emit.py b/dualect/emit.py index b10fb83..056cf2f 100644 --- a/dualect/emit.py +++ b/dualect/emit.py @@ -150,6 +150,8 @@ def __init__( s.name: s for s in scan.program.body if isinstance(s, ir.FunctionDef) } self.loop_stack: list[ir.Stmt] = [] + #: The statement being translated (a rule may need its target's name). + self.current: ir.Stmt | None = None self.indent = 0 self.reports: list[StmtReport] = [] self.directives: set[str] = set() @@ -392,10 +394,12 @@ def statement(self, stmt: ir.Stmt) -> list[Line]: # note must only carry what was assumed for its own header. outer_assumptions = self.assumptions self.assumptions = [] + outer_stmt, self.current = self.current, stmt try: lines = self._translate_planned(stmt, report, saved_imports, saved_directives) finally: self.assumptions = outer_assumptions + self.current = outer_stmt if report.status is not Status.MECHANICAL: self.file_directives = saved_file_directives return lines diff --git a/dualect/infer.py b/dualect/infer.py index a0255b5..fb64eed 100644 --- a/dualect/infer.py +++ b/dualect/infer.py @@ -15,6 +15,12 @@ a fixed point, and specializes each local function once, for the join of the argument facts at all of its call sites in the file. +What a built-in returns is known here for the core ones; a rule can teach it +about its own built-ins with ``infer_call(node, args, nargout)`` (the facts +of the result, or ``None``) and ``infer_outputs(node, args, nargout)`` (the +facts of each output of a multi-output call) in its ``translate.py``, so a +new built-in needs no engine change. + All facts describe the *source* (``.m``) semantics: shapes are ``rows x cols``. How a fact maps to NumPy (a ``1xN`` row is a 1-D array) is the emitter's business. @@ -23,8 +29,10 @@ from __future__ import annotations import math +from collections.abc import Callable from dataclasses import dataclass, field, replace from enum import StrEnum +from types import ModuleType from typing import TypedDict from dualect import ir @@ -368,9 +376,16 @@ def info(self, expr: ir.Expr) -> Info: return self.infos.get(id(expr), UNKNOWN) +#: Built-in name -> the translator module of the rule that covers it, if any. +CallHook = Callable[[str], ModuleType | None] + + class _Inferrer: - def __init__(self, program: ir.Program) -> None: + def __init__(self, program: ir.Program, hook: CallHook | None = None) -> None: self.program = program + self.hook = hook + # id(call) of the calls whose facts came from a rule (int_dtype included). + self.hooked: set[int] = set() self.analysis = Analysis() self.defs: dict[str, ir.FunctionDef] = { s.name: s for s in program.body if isinstance(s, ir.FunctionDef) @@ -588,6 +603,9 @@ def multi_outputs(self, value: ir.Expr, env: Env, count: int) -> list[Info]: first = self.expr(value, env, nargout=count) if isinstance(value, ir.Call): arg_infos = [self.analysis.info(arg) for arg in value.args] + hooked = self._hook(value, "infer_outputs", arg_infos, count) + if isinstance(hooked, list): + return [*hooked[:count], *[UNKNOWN] * (count - len(hooked))] if value.local and value.func in self.analysis.functions: outputs = self.analysis.functions[value.func].outputs return [outputs[k] if k < len(outputs) else UNKNOWN for k in range(count)] @@ -862,6 +880,10 @@ def call(self, node: ir.Call, env: Env, *, nargout: int) -> Info: self.expr(lam.body, {**captured, **dict(zip(lam.params, joined, strict=True))}) return result return UNKNOWN + hooked = self._hook(node, "infer_call", args, nargout) + if isinstance(hooked, Info): + self.hooked.add(id(node)) + return hooked if not node.args and name in CONSTANTS: return CONSTANTS[name] if name in ("nargin", "nargout"): @@ -943,9 +965,17 @@ def call(self, node: ir.Call, env: Env, *, nargout: int) -> Info: return replace(first, value=None, func=None) return UNKNOWN + def _hook(self, node: ir.Call, name: str, args: list[Info], nargout: int) -> object: + """Ask the rule covering a built-in for its facts (``None``: it does not know).""" + if self.hook is None or node.local or node.handle: + return None + module = self.hook(node.func) + function = getattr(module, name, None) if module is not None else None + return function(node, args, nargout) if callable(function) else None + def int_result(self, node: ir.Call, result: Info) -> bool: """Whether the NumPy translation of a call may hold integers.""" - if node.local or node.handle: + if node.local or node.handle or id(node) in self.hooked: return result.int_dtype if node.func in ("find", "size", "numel", "length", "ndims", "nargin", "nargout"): return True @@ -1113,9 +1143,11 @@ def _is_end_plus(arg: ir.Expr) -> bool: return False -def analyze(program: ir.Program) -> Analysis: +def analyze(program: ir.Program, *, hook: CallHook | None = None) -> Analysis: """Infer facts about every expression of ``program``. :param program: lowered source. + :param hook: built-in name -> the module of its rule, whose + ``infer_call``/``infer_outputs`` describe what the built-in returns. """ - return _Inferrer(program).run() + return _Inferrer(program, hook).run() diff --git a/dualect/lift.py b/dualect/lift.py index 8df0f31..91e4b51 100644 --- a/dualect/lift.py +++ b/dualect/lift.py @@ -45,6 +45,7 @@ from dualect.pyinfer import PyAnalysis, PyInfo, PyKind, analyze_python from dualect.rulebook import FROM_PYTHON, Rule, Status from dualect.scan import Finding +from dualect.translators import shared_translator #: Comment directives the verify harness reads; they are never copied over, #: because their meaning (a 0-based position) belongs to the source pairing. @@ -73,6 +74,11 @@ def rule_for(self, tag: str) -> Rule | None: """The rule covering ``tag``, or ``None``.""" return self.by_tag.get(tag) + def call_hook(self, tag: str) -> ModuleType | None: + """The translator of the rule covering a call tag (for inference hooks).""" + rule = self.by_tag.get(tag) + return shared_translator(rule) if rule is not None else None + @dataclass class ScopeInfo: @@ -124,6 +130,8 @@ def __init__( #: File-level verification directives the ``.m`` output needs #: (``stdout`` when it prints, ``shape r`` for random values). self.file_directives: list[str] = [] + #: The statement being lifted (a rule may need its target's name). + self.current: ast.stmt | None = None self._used_comments: set[int] = set() self._plan(module.body) @@ -368,6 +376,7 @@ def statement(self, stmt: ast.stmt) -> list[ir.Stmt]: mark = len(self.reports) used = set(self._used_comments) file_directives = list(self.file_directives) + outer_stmt, self.current = self.current, stmt try: lifted = self.translate_statement(stmt) except Decline as exc: @@ -391,6 +400,7 @@ def statement(self, stmt: ast.stmt) -> list[ir.Stmt]: finally: mine = self.assumptions self.assumptions = outer + self.current = outer_stmt notes = [] comment = self.comments.get(getattr(stmt, "end_lineno", None) or stmt.lineno) if comment is None: @@ -688,12 +698,13 @@ def lift_python( :raises PythonSyntaxError: when the text is not valid Python. """ module = parse_python(text=text, name=name) - analysis = analyze_python(module) + index = PyRuleIndex(rules=rules) + analysis = analyze_python(module, hook=index.call_hook) ctx = LiftContext( module=module, text=text, analysis=analysis, - index=PyRuleIndex(rules=rules), + index=index, translator_for=translator_for, ) body = ctx.block(module.body) @@ -710,11 +721,12 @@ def plan_python(*, text: str, name: str, rules: list[Rule]) -> list[Finding]: :raises DualectError: when the text is not valid Python. """ module = parse_python(text=text, name=name) + index = PyRuleIndex(rules=rules) ctx = LiftContext( module=module, text=text, - analysis=analyze_python(module), - index=PyRuleIndex(rules=rules), + analysis=analyze_python(module, hook=index.call_hook), + index=index, translator_for=lambda _rule_id: None, ) return ctx.findings diff --git a/dualect/pipeline.py b/dualect/pipeline.py index 11ea3d6..f163f01 100644 --- a/dualect/pipeline.py +++ b/dualect/pipeline.py @@ -32,7 +32,7 @@ from dualect.runners import MRunner from dualect.scan import RuleIndex, ScanResult, scan_python_text, scan_text from dualect.translators import TranslatorSet -from dualect.verify import VerifyResult, options_for_pair, parse_directives, verify_pair +from dualect.verify import VerifyResult, options_for_pair, read_directives, verify_pair UNVERIFIED = "UNVERIFIED" @@ -257,12 +257,17 @@ def verify_translation( m_path, py_path = output, source # The source's own `index` directives describe its pairing with some # other .m file; the generated .m keeps Python's values, so only its - # own directives (and either side's `ignore`) apply. + # own directives (and either side's `ignore`, `shape`, `stdout`) apply. generated = options_for_pair( m_path=m_path, py_path=m_path, tolerance=tolerance_for(result.rules_used) ) - _index, ignored = parse_directives(text=source.read_text(encoding="utf-8"), path=source) - options = dataclasses.replace(generated, ignore=generated.ignore | ignored) + found = read_directives(text=source.read_text(encoding="utf-8"), path=source) + options = dataclasses.replace( + generated, + ignore=generated.ignore | found.ignore, + shape_only=generated.shape_only | found.shape, + stdout=generated.stdout or found.stdout, + ) try: result.verify = verify_pair(m_path=m_path, py_path=py_path, options=options, runner=runner) except RuntimeMissingError as exc: diff --git a/dualect/pyinfer.py b/dualect/pyinfer.py index 4605872..4a6043a 100644 --- a/dualect/pyinfer.py +++ b/dualect/pyinfer.py @@ -16,14 +16,21 @@ array. The analysis is flow-sensitive within a body, joins branches, runs loop bodies to a fixed point and analyses each function (and lambda) once for the join of the arguments at its call sites, like :mod:`dualect.infer`. + +A rule teaches the analysis what its calls return with +``pyinfer_call(tag, node, args, keywords, receiver)`` in its ``translate.py`` +(``tag`` is the call's construct tag, ``py:call:np.cumsum`` or +``py:method:cumsum``; ``receiver`` the facts of a method's object). """ from __future__ import annotations import ast import math +from collections.abc import Callable from dataclasses import dataclass, field, replace from enum import StrEnum +from types import ModuleType class PyKind(StrEnum): @@ -232,9 +239,14 @@ def dotted(node: ast.expr, alias: str | None) -> str | None: return None +#: Python construct tag of a call -> the translator module of its rule, if any. +PyCallHook = Callable[[str], ModuleType | None] + + class _Inferrer: - def __init__(self, module: ast.Module) -> None: + def __init__(self, module: ast.Module, hook: PyCallHook | None = None) -> None: self.module = module + self.hook = hook self.analysis = PyAnalysis() self.defs: dict[str, ast.FunctionDef] = {} for stmt in module.body: @@ -599,10 +611,16 @@ def call(self, node: ast.Call, env: Env) -> PyInfo: keywords = {k.arg: self.expr(k.value, env) for k in node.keywords if k.arg is not None} func = node.func name = dotted(func, alias) + receiver: PyInfo | None = None + if name is None and isinstance(func, ast.Attribute): + receiver = self.expr(func.value, env) + hooked = self._hook(node, args, keywords, receiver) + if hooked is not None: + return hooked if name is not None: return self.numpy_call(name[3:], node, args, keywords) if isinstance(func, ast.Attribute): - receiver = self.expr(func.value, env) + assert receiver is not None result = self.method(func.attr, receiver, args, keywords) target = node.args[0] if node.args else None if func.attr == "astype" and isinstance(target, ast.Name): @@ -627,6 +645,33 @@ def call(self, node: ast.Call, env: Env) -> PyInfo: return _builtin(fname, args) return UNKNOWN + def _hook( + self, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, + ) -> PyInfo | None: + """Ask the rule covering a call for the facts of its result.""" + if self.hook is None: + return None + func = node.func + name = dotted(func, self.analysis.numpy_alias) + if name is not None: + tag = f"py:call:{name}" + elif isinstance(func, ast.Attribute): + tag = f"py:method:{func.attr}" + elif isinstance(func, ast.Name) and func.id not in self.defs: + tag = f"py:call:{func.id}" + else: + return None + module = self.hook(tag) + function = getattr(module, "pyinfer_call", None) if module is not None else None + if not callable(function): + return None + result = function(tag, node, args, keywords, receiver) + return result if isinstance(result, PyInfo) else None + def lambda_call(self, lam: ast.Lambda, args: list[PyInfo], env: Env) -> PyInfo: """A lambda's result for this call; its body is annotated for every call.""" params = [a.arg for a in lam.args.args] @@ -678,7 +723,7 @@ def numpy_call( PyKind.VECTOR, DType.INT if ints else DType.FLOAT, finite=True, nonneg=nonneg ) if name in ELEMENTWISE: - shape = _broadcast(first, args[1]) if len(args) == 2 else _as_array(first) + shape = _broadcast(first, args[1]) if len(args) == 2 else as_array(first) if shape.kind is PyKind.UNKNOWN: return UNKNOWN dtype = DType.BOOL if name in _BOOL_RESULT else DType.FLOAT @@ -702,7 +747,7 @@ def numpy_call( return scalar(DType.INT, nonneg=True) if name in ("maximum", "minimum", "fmax", "fmin"): second = args[1] if len(args) > 1 else UNKNOWN - shape = _broadcast(_as_array(first), _as_array(second)) + shape = _broadcast(as_array(first), as_array(second)) return replace( shape, dtype=_promote(first.dtype, second.dtype), @@ -711,11 +756,11 @@ def numpy_call( view=False, ) if name == "clip": - return replace(_as_array(first), finite=all(a.finite for a in args), view=False) + return replace(as_array(first), finite=all(a.finite for a in args), view=False) if name in ("logical_and", "logical_or", "logical_xor", "logical_not"): - shape = _as_array(first) + shape = as_array(first) for other in args[1:]: - shape = _broadcast(shape, _as_array(other)) + shape = _broadcast(shape, as_array(other)) return replace( shape, dtype=DType.BOOL, finite=True, nonneg=True, value=None, view=False ) @@ -873,7 +918,7 @@ def _array_literal(first: PyInfo) -> PyInfo: return UNKNOWN -def _as_array(info: PyInfo) -> PyInfo: +def as_array(info: PyInfo) -> PyInfo: """A list argument is a 1-D array (or a 2-D one for a list of lists).""" if info.kind is PyKind.LIST: return _array_literal(info) @@ -881,7 +926,7 @@ def _as_array(info: PyInfo) -> PyInfo: def _broadcast(a: PyInfo, b: PyInfo) -> PyInfo: - a, b = _as_array(a), _as_array(b) + a, b = as_array(a), as_array(b) if a.is_scalar and b.is_scalar: return replace(a, value=None, view=False) if a.is_scalar and b.is_array: @@ -895,7 +940,7 @@ def _broadcast(a: PyInfo, b: PyInfo) -> PyInfo: def _matmul(a: PyInfo, b: PyInfo) -> PyInfo: - a, b = _as_array(a), _as_array(b) + a, b = as_array(a), as_array(b) if not (a.is_array and b.is_array): return UNKNOWN if a.is_vector and b.is_vector: @@ -941,7 +986,7 @@ def _builtin(name: str, args: list[PyInfo]) -> PyInfo: return PyInfo(kind=PyKind.NONE) if name == "lfilter" and len(args) >= 3: # scipy.signal.lfilter: the shape of the data, in floating point. - return replace(_as_array(args[2]), dtype=DType.FLOAT, finite=False, value=None, view=False) + return replace(as_array(args[2]), dtype=DType.FLOAT, finite=False, value=None, view=False) return UNKNOWN @@ -951,9 +996,11 @@ def _is_newaxis(node: ast.expr, alias: str | None) -> bool: ) == "np.newaxis" -def analyze_python(module: ast.Module) -> PyAnalysis: +def analyze_python(module: ast.Module, *, hook: PyCallHook | None = None) -> PyAnalysis: """Infer facts about every expression of a Python module. :param module: the parsed source. + :param hook: a call's construct tag -> the module of its rule, whose + ``pyinfer_call`` describes what the call returns. """ - return _Inferrer(module).run() + return _Inferrer(module, hook).run() diff --git a/dualect/runners.py b/dualect/runners.py index 77b2b92..a352282 100644 --- a/dualect/runners.py +++ b/dualect/runners.py @@ -121,8 +121,9 @@ def run_capturing(self, *, path: Path) -> tuple[dict[str, Any], str]: # anything from a working directory that no longer exists. session.eval(f"cd({_quote_m_string(str(path.parent))});", stream_handler=ignored.append) # A fresh workspace per script: leftovers from an earlier script - # (variables or command-line functions) would otherwise leak in. - session.eval("clear all; close all; more off;", stream_handler=ignored.append) + # (variables, command-line functions, a `format long`) would + # otherwise leak in; `format` alone restores the default display. + session.eval("clear all; close all; more off; format;", stream_handler=ignored.append) # evalc captures the output exactly; oct2py's own stream drops # trailing spaces and a last line without a newline. source = _quote_m_string(f"source({_quote_m_string(str(path))});") diff --git a/dualect/scan.py b/dualect/scan.py index a557523..2b0d302 100644 --- a/dualect/scan.py +++ b/dualect/scan.py @@ -14,6 +14,7 @@ from collections.abc import Iterable from dataclasses import dataclass, field from pathlib import Path +from types import ModuleType from typing import Any from dualect import ir @@ -25,6 +26,7 @@ from dualect.parse import parse_m from dualect.rulebook import FROM_PYTHON, TO_PYTHON, Rule, Status from dualect.source import OctaveFeature +from dualect.translators import shared_translator #: Tag for Octave-only syntax found while scanning for the matlab dialect. OCTAVE_ONLY_TAG = "dialect:octave-only" @@ -58,6 +60,11 @@ def rule_for(self, tag: str) -> Rule | None: """The rule covering ``tag``, or ``None``.""" return self.by_tag.get(tag) + def call_hook(self, name: str) -> ModuleType | None: + """The translator of the rule covering ``call:`` (for inference hooks).""" + rule = self.by_tag.get(f"call:{name}") + return shared_translator(rule) if rule is not None else None + def rule_by_id(self, rule_id: str) -> Rule | None: """An applicable rule by id, or ``None`` (absent, or not for this dialect).""" for rule in self.by_tag.values(): @@ -214,7 +221,7 @@ def scan_text(*, text: str, name: str, index: RuleIndex) -> ScanResult: """ parsed = parse_m(text) program = lower_parsed(parsed=parsed, name=name, dialect=index.dialect.name) - analysis = analyze(program) + analysis = analyze(program, hook=index.call_hook) result = ScanResult( source_name=name, program=program, diff --git a/dualect/translators.py b/dualect/translators.py index 5e967a6..6c0072b 100644 --- a/dualect/translators.py +++ b/dualect/translators.py @@ -21,6 +21,7 @@ """ import importlib.util +from pathlib import Path from types import ModuleType from dualect.errors import RuleError @@ -46,6 +47,21 @@ def get(self, rule_id: str) -> ModuleType | None: return self._modules[rule_id] +_SHARED: dict[Path, ModuleType | None] = {} + + +def shared_translator(rule: Rule) -> ModuleType | None: + """A rule's translator, loaded once per process (for inference hooks). + + Inference runs on every scan; reloading every rule's module each time + would cost more than the scan itself. + """ + path = rule.path / TRANSLATOR_FILE + if path not in _SHARED: + _SHARED[path] = load_translator(rule) + return _SHARED[path] + + def load_translator(rule: Rule) -> ModuleType | None: """Import ``translate.py`` from a rule folder. diff --git a/llms.txt b/llms.txt index 910cb79..0ee9cd7 100644 --- a/llms.txt +++ b/llms.txt @@ -16,14 +16,36 @@ Generated by `dualect llms-txt`; do not edit by hand. ## Rules -- [builtins/constants](rules/builtins/constants/rule.yaml): Constants: `pi`, `Inf`, `NaN`, `eps`, `true`, `false`, `i` (.m to Python: mechanical; Python to .m: mechanical; 1 case) -- [builtins/elementwise-math](rules/builtins/elementwise-math/rule.yaml): Element-wise math: `abs`, `sqrt`, `exp`, `floor`, `mod`, `rem`, `isnan`, ... (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/any-all](rules/builtins/any-all/rule.yaml): `any`, `all`: is any or every element nonzero? (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/concatenation-functions](rules/builtins/concatenation-functions/rule.yaml): `horzcat`, `vertcat` and `cat`: concatenation as functions (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/constants](rules/builtins/constants/rule.yaml): Constants: `pi`, `Inf`, `NaN`, `eps`, `true`, `false`, `i`, and arrays of them (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/cumsum-cumprod](rules/builtins/cumsum-cumprod/rule.yaml): `cumsum`, `cumprod`: running sums and products (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/diff](rules/builtins/diff/rule.yaml): `diff`: differences between neighbouring elements (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/dot-cross-kron](rules/builtins/dot-cross-kron/rule.yaml): `dot`, `cross` and `kron`: products of vectors and matrices (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/elementwise-math](rules/builtins/elementwise-math/rule.yaml): Element-wise math: `abs`, `sqrt`, `exp`, `floor`, `mod`, `rem`, `isnan`, ... (.m to Python: mechanical; Python to .m: mechanical; 3 cases) - [builtins/filter](rules/builtins/filter/rule.yaml): `filter`: one-dimensional digital filter (`scipy.signal.lfilter`) (.m to Python: mechanical; Python to .m: mechanical; 2 cases) - [builtins/find](rules/builtins/find/rule.yaml): `find`: 1-based, column-major indices (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/flip](rules/builtins/flip/rule.yaml): `fliplr`, `flipud`, `flip`: reversing the order of elements (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/interp1](rules/builtins/interp1/rule.yaml): `interp1`: linear interpolation (`np.interp`) (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [builtins/isempty](rules/builtins/isempty/rule.yaml): `isempty` (.m to Python: mechanical; Python to .m: n/a; 1 case) +- [builtins/linear-algebra](rules/builtins/linear-algebra/rule.yaml): `inv`, `det`, `trace`, `rank` (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [builtins/linspace](rules/builtins/linspace/rule.yaml): `linspace` default count and edge cases (.m to Python: mechanical; Python to .m: mechanical; 2 cases) -- [builtins/size-numel-length](rules/builtins/size-numel-length/rule.yaml): `size`, `numel`, `length` (.m to Python: mechanical; Python to .m: mechanical; 1 case) -- [builtins/sum-mean-max](rules/builtins/sum-mean-max/rule.yaml): `sum`, `mean`, `max`, `min`: dimensions and index outputs (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/median](rules/builtins/median/rule.yaml): `median`: middle value, down the columns of a matrix (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/meshgrid](rules/builtins/meshgrid/rule.yaml): `meshgrid`: coordinate grids (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/norm](rules/builtins/norm/rule.yaml): `norm`: vector and matrix norms (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/num2str](rules/builtins/num2str/rule.yaml): `num2str`: numbers as text (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/polyfit-polyval](rules/builtins/polyfit-polyval/rule.yaml): `polyfit` and `polyval`: polynomial fit and evaluation (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/rand-randn](rules/builtins/rand-randn/rule.yaml): `rand` and `randn`: random numbers (compared by shape only) (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/repmat](rules/builtins/repmat/rule.yaml): `repmat`: tiling rows, columns and matrices (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/reshape](rules/builtins/reshape/rule.yaml): `reshape`: column-major order (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/size-numel-length](rules/builtins/size-numel-length/rule.yaml): `size`, `numel`, `length`, `ndims` (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/sort](rules/builtins/sort/rule.yaml): `sort`: ascending or descending, with 1-based positions (.m to Python: mechanical; Python to .m: mechanical; 3 cases) +- [builtins/std-var](rules/builtins/std-var/rule.yaml): `std` and `var`: N - 1 by default (.m to Python: mechanical; Python to .m: mechanical; 2 cases) +- [builtins/sum-mean-max](rules/builtins/sum-mean-max/rule.yaml): `sum`, `mean`, `max`, `min`: dimensions and index outputs (.m to Python: mechanical; Python to .m: mechanical; 3 cases) +- [builtins/tic-toc](rules/builtins/tic-toc/rule.yaml): `tic` / `toc`: timing (.m to Python: guided; Python to .m: guided; 1 case) +- [builtins/trapz](rules/builtins/trapz/rule.yaml): `trapz`: trapezoidal integration (`np.trapezoid`) (.m to Python: mechanical; Python to .m: mechanical; 1 case) +- [builtins/type-tests](rules/builtins/type-tests/rule.yaml): `isnumeric`, `islogical`, `ischar`: what kind of value is this? (.m to Python: mechanical; Python to .m: n/a; 1 case) +- [builtins/unique](rules/builtins/unique/rule.yaml): `unique`: the distinct values, sorted (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [builtins/zeros-ones-eye](rules/builtins/zeros-ones-eye/rule.yaml): `zeros`, `ones`, `eye` (.m to Python: mechanical; Python to .m: mechanical; 1 case) - [control-flow/for-columns](rules/control-flow/for-columns/rule.yaml): `for` loops iterate over columns (.m to Python: mechanical; Python to .m: mechanical; 2 cases) - [control-flow/if-elseif](rules/control-flow/if-elseif/rule.yaml): `if` / `elseif` / `else` and array conditions (.m to Python: mechanical; Python to .m: mechanical; 2 cases) diff --git a/rules/builtins/any-all/cases/basic.m b/rules/builtins/any-all/cases/basic.m new file mode 100644 index 0000000..dde245a --- /dev/null +++ b/rules/builtins/any-all/cases/basic.m @@ -0,0 +1,9 @@ +v = [1 5 2]; +hit = any(v > 3); +none = all(v > 3); +A = [1 0 2; 3 4 0]; +cols = any(A); % one answer per column: 1 1 1 +cols_all = all(A); % 1 0 0 +rows_all = all(A, 2); % 0; 0 +every = all(A(:) > -1); % every element +nonzero = any([0 0 7]); % numbers: nonzero counts as true diff --git a/rules/builtins/any-all/cases/basic.py b/rules/builtins/any-all/cases/basic.py new file mode 100644 index 0000000..78f61e7 --- /dev/null +++ b/rules/builtins/any-all/cases/basic.py @@ -0,0 +1,11 @@ +import numpy as np + +v = np.array([1, 5, 2]) +hit = (v > 3).any() +none = (v > 3).all() +A = np.array([[1, 0, 2], [3, 4, 0]]) +cols = A.any(axis=0) # one answer per column: 1 1 1 +cols_all = A.all(axis=0) # 1 0 0 +rows_all = A.all(axis=1) # 0; 0 +every = (A.ravel(order="F") > -1).all() # every element +nonzero = np.array([0, 0, 7]).any() # numbers: nonzero counts as true diff --git a/rules/builtins/any-all/cases/empty.m b/rules/builtins/any-all/cases/empty.m new file mode 100644 index 0000000..ad8fb7f --- /dev/null +++ b/rules/builtins/any-all/cases/empty.m @@ -0,0 +1,8 @@ +% On empty data any is false and all is true. +e = []; +a1 = any(e); +a2 = all(e); +x = [3 4 5]; +small = x(x < 0); % no element: empty +all_small_neg = all(small < 0); +any_small = any(small); diff --git a/rules/builtins/any-all/cases/empty.py b/rules/builtins/any-all/cases/empty.py new file mode 100644 index 0000000..4d2d542 --- /dev/null +++ b/rules/builtins/any-all/cases/empty.py @@ -0,0 +1,10 @@ +import numpy as np + +# On empty data any is false and all is true. +e = np.array([]) +a1 = e.any() +a2 = e.all() +x = np.array([3, 4, 5]) +small = x[x < 0] # no element: empty +all_small_neg = (small < 0).all() +any_small = small.any() diff --git a/rules/builtins/any-all/rule.yaml b/rules/builtins/any-all/rule.yaml new file mode 100644 index 0000000..d2ca3fc --- /dev/null +++ b/rules/builtins/any-all/rule.yaml @@ -0,0 +1,39 @@ +id: builtins/any-all +title: "`any`, `all`: is any or every element nonzero?" +status: mechanical +dialects: [octave, matlab] +match: [call:any, call:all] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:method:all + - py:method:any + - py:call:np.all + - py:call:np.any +octave: | + hit = any(v > 3); + ok = all(A > 0); % one answer per column + rows_ok = all(A > 0, 2); +python: | + hit = (v > 3).any() + ok = (A > 0).all(axis=0) + rows_ok = (A > 0).all(axis=1) +why: > + Like the other reductions, `any` and `all` work down the columns of a + matrix and give one logical per column, while NumPy's `.any()` and `.all()` + without an axis reduce every element to a single value: a matrix needs + `axis=0`, and `any(A(:))` is `A.any()`. On empty data `any` is false and + `all` is true, in both. +pitfalls: + - >- + `any(A)` of a matrix is a row of answers, one per column; `A.any()` is a + single value. + - >- + `any` does not count NaN as true (`any([0 NaN])` is false), while NumPy + does (`np.any([0, np.nan])` is True). `any` of data that may hold NaN is + not translated; comparisons and masks never hold NaN. + - >- + `all([])` is true and `any([])` is false: an `if all(x > 0)` on empty + data takes the branch. +related: [builtins/sum-mean-max, indexing/logical] +python_imports: [import numpy as np] diff --git a/rules/builtins/any-all/translate.py b/rules/builtins/any-all/translate.py new file mode 100644 index 0000000..a61ffb5 --- /dev/null +++ b/rules/builtins/any-all/translate.py @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/any-all: ``any`` and ``all``. + +They reduce like ``sum`` (builtins/sum-mean-max does the work): a vector to a +single logical (``v.any()``), a matrix down its columns (``axis=0``) unless a +dimension is given, ``any(A(:))`` over every element. ``any`` does not count +NaN as true in the source while NumPy does, so ``any`` of data that may hold +NaN is declined; ``all`` treats NaN as nonzero in both. + +From Python, ``x.any()``/``np.any(x)`` and ``all`` reduce the same way (the +same helpers as ``sum``), with the same NaN check for ``any``. +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array, scalar +from dualect.lift import LiftContext + + +def _data(node: ir.Call) -> ir.Expr: + """The reduced data (``A`` of ``any(A(:))``).""" + data = node.args[0] + if isinstance(data, ir.Index) and len(data.args) == 1 and isinstance(data.args[0], ir.Colon): + return data.target + return data + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``any(x)``, ``all(x)``, ``any(x, dim)``.""" + if not node.args or len(node.args) > 2: + ctx.decline(f"{node.func} with these arguments") + info = ctx.info(_data(node)) + if node.func == "any" and not info.finite: + ctx.decline("any of data that may hold NaN (the source ignores NaN, NumPy counts it)") + if info.elem not in (Elem.REAL, Elem.LOGICAL): + ctx.decline(f"{node.func} of values that may be complex or characters") + result: ast.expr = ctx.module("builtins/sum-mean-max").translate(node, ctx) + return result + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A logical scalar per vector, a row per matrix (a column along dimension 2).""" + if not args: + return None + first = args[0] + facts = {"elem": Elem.LOGICAL, "finite": True, "nonneg": True, "integer": True} + dim = args[1].value if len(args) > 1 else None + if first.is_matrix and dim in (None, 1): + return array(1, first.cols, kind=Kind.ROW, **facts) # type: ignore[arg-type] + if first.is_matrix and dim == 2: + return array(first.rows, 1, kind=Kind.COL, **facts) # type: ignore[arg-type] + if first.is_vector and dim is None: + return scalar(**facts) # type: ignore[arg-type] + if first.is_scalar: + return scalar(**facts) # type: ignore[arg-type] + return None + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``x.any()``, ``np.all(x, axis=...)``: the reduction rule's lift.""" + assert isinstance(node, ast.Call) + reductions = ctx.module_for("builtins/sum-mean-max") + func, data, _rest = reductions._name(node, ctx) + if data is None: + ctx.decline(f"{func} without arguments") + if func == "any" and not reductions._finite(data, ctx): + ctx.decline("any of data that may hold NaN (NumPy counts NaN as true, the .m any not)") + result: ir.Expr = reductions.lift(node, ctx) + return result diff --git a/rules/builtins/concatenation-functions/cases/basic.m b/rules/builtins/concatenation-functions/cases/basic.m new file mode 100644 index 0000000..7ef230e --- /dev/null +++ b/rules/builtins/concatenation-functions/cases/basic.m @@ -0,0 +1,14 @@ +% The function forms join like the bracket literals. +a = [1 2]; +b = [3 4 5]; +r = horzcat(a, b); % a longer row +c = [1; 2]; +d = [3; 4]; +C2 = horzcat(c, d); % two columns side by side +col = vertcat(c, d); % a longer column +A = [1 2; 3 4]; +B = [5 6; 7 8]; +V = vertcat(A, B); % 4x2 +H = cat(2, A, B); % 2x4 +S = cat(1, A, [9 9]); % a row stacked under a matrix +e = horzcat(a, [], b); % empty parts are skipped diff --git a/rules/builtins/concatenation-functions/cases/basic.py b/rules/builtins/concatenation-functions/cases/basic.py new file mode 100644 index 0000000..9c0c1fb --- /dev/null +++ b/rules/builtins/concatenation-functions/cases/basic.py @@ -0,0 +1,16 @@ +import numpy as np + +# The function forms join like the bracket literals. +a = np.array([1, 2]) +b = np.array([3, 4, 5]) +r = np.concatenate((a, b)) # a longer row +c = np.array([1, 2]) +d = np.array([3, 4]) +C2 = np.column_stack((c, d)) # two columns side by side +col = np.concatenate((c, d)) # a longer column +A = np.array([[1, 2], [3, 4]]) +B = np.array([[5, 6], [7, 8]]) +V = np.vstack((A, B)) # 4x2 +H = np.column_stack((A, B)) # 2x4 +S = np.vstack((A, np.array([9, 9]))) # a row stacked under a matrix +e = np.concatenate((a, np.array([]), b)) # empty parts are skipped diff --git a/rules/builtins/concatenation-functions/rule.yaml b/rules/builtins/concatenation-functions/rule.yaml new file mode 100644 index 0000000..8184d11 --- /dev/null +++ b/rules/builtins/concatenation-functions/rule.yaml @@ -0,0 +1,35 @@ +id: builtins/concatenation-functions +title: "`horzcat`, `vertcat` and `cat`: concatenation as functions" +status: mechanical +dialects: [octave, matlab] +match: [call:horzcat, call:vertcat, call:cat] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.hstack +octave: | + r = horzcat(a, b); % [a, b] + C = vertcat(A, B); % [A; B] + D = cat(2, A, B); % [A, B] +python: | + r = np.concatenate((a, b)) + C = np.vstack((A, B)) + D = np.column_stack((A, B)) +why: > + These are the bracket literals spelled as functions: `horzcat(a, b)` is + `[a, b]`, `vertcat(a, b)` is `[a; b]`, and `cat(dim, ...)` joins along + dimension `dim` (1 down, 2 across). In NumPy the right function depends on + what is joined, because rows and columns are both 1-D: two rows joined + across are `np.concatenate`, two columns joined down too, but columns joined + across are `np.column_stack`. +pitfalls: + - >- + `np.hstack` of two 1-D columns joins them end to end into one longer 1-D + array, not a two-column matrix: that is `np.column_stack`. + - >- + `cat(1, ...)` stacks vertically: dimension 1 is the rows, NumPy's + `axis=0`. + - >- + Empty parts (`[]`) are skipped in either direction. +related: [syntax/array-literals, builtins/repmat] +python_imports: [import numpy as np] diff --git a/rules/builtins/concatenation-functions/translate.py b/rules/builtins/concatenation-functions/translate.py new file mode 100644 index 0000000..00adab8 --- /dev/null +++ b/rules/builtins/concatenation-functions/translate.py @@ -0,0 +1,137 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/concatenation-functions: ``horzcat``, ``vertcat``, ``cat``. + +``horzcat(a, b, ...)`` is ``[a, b, ...]`` and ``vertcat(a, b, ...)`` is +``[a; b; ...]``; ``cat(1, ...)`` stacks vertically and ``cat(2, ...)`` +horizontally. They are translated as those bracket literals, by +syntax/array-literals, so rows, columns (both 1-D in NumPy) and matrices are +joined the same way in both spellings. ``cat`` along a third or computed +dimension is declined. + +From Python, ``np.hstack`` of 1-D arrays (and scalars) joins them end to end, +``[a, b]``; of 2-D arrays side by side, also ``[A, B]``. A mix of 1-D and +2-D parts is declined: NumPy would refuse it or read the 1-D part as a row. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind +from dualect.pyinfer import array as py_array + + +def _layout(node: ir.Call, dim_value: object) -> tuple[str, list[ir.Expr]] | None: + """``("horizontal" | "vertical", parts)`` of a call, or ``None``.""" + if node.func == "horzcat": + return "horizontal", list(node.args) + if node.func == "vertcat": + return "vertical", list(node.args) + if node.func == "cat" and node.args: + if dim_value == 1: + return "vertical", list(node.args[1:]) + if dim_value == 2: + return "horizontal", list(node.args[1:]) + return None + + +def _matrix(direction: str, parts: list[ir.Expr], loc: ir.Loc) -> ir.Matrix: + rows = [parts] if direction == "horizontal" else [[part] for part in parts] + return ir.Matrix(loc=loc, rows=rows if parts else []) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The joined dimensions, when every part's are known.""" + layout = _layout(node, args[0].value if args else None) + if layout is None: + return None + direction, _parts = layout + infos = args[1:] if node.func == "cat" else args + infos = [i for i in infos if i.kind is not Kind.EMPTY] + if not infos: + return array(0, 0, finite=True, nonneg=True, integer=True) + if any(i.kind in (Kind.UNKNOWN, Kind.ARRAY, Kind.VECTOR, Kind.STRING) for i in infos): + return None + along = [i.cols if direction == "horizontal" else i.rows for i in infos] + across = {i.rows if direction == "horizontal" else i.cols for i in infos} + total = sum(a for a in along if a is not None) if None not in along else None + other = across.pop() if len(across) == 1 else None + rows, cols = (other, total) if direction == "horizontal" else (total, other) + elem = Elem.LOGICAL if all(i.elem is Elem.LOGICAL for i in infos) else Elem.REAL + if any(i.elem in (Elem.UNKNOWN, Elem.COMPLEX, Elem.CHAR) for i in infos): + elem = Elem.UNKNOWN + result = array( + rows, + cols, + elem=elem, + finite=all(i.finite for i in infos), + nonneg=all(i.nonneg for i in infos), + integer=all(i.integer for i in infos), + ) + return replace(result, int_dtype=all(i.int_dtype for i in infos)) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``horzcat``, ``vertcat`` or ``cat(dim, ...)``, as the bracket literal.""" + dim_value = ctx.info(node.args[0]).value if node.args else None + layout = _layout(node, dim_value) + if layout is None: + ctx.decline(f"{node.func} along a dimension other than 1 or 2") + direction, parts = layout + if not parts: + ctx.decline(f"{node.func} of nothing") + literals = ctx.module("syntax/array-literals") + result = literals.translate(_matrix(direction, parts, node.loc), ctx) + assert isinstance(result, ast.expr) + return result + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.hstack((a, b, ...))``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if len(node.args) != 1 or node.keywords or not isinstance(node.args[0], ast.Tuple | ast.List): + ctx.decline("np.hstack with these arguments") + parts = list(node.args[0].elts) + if not parts: + ctx.decline("np.hstack of nothing") + infos = [ctx.info(p) for p in parts] + literals = ctx.module_for("syntax/array-literals") + lifted = [literals.lift_items(p, ctx) for p in parts] + one_d = all( + i.is_vector or i.is_scalar or isinstance(p, ast.List) + for i, p in zip(infos, parts, strict=True) + ) + if one_d or all(i.is_matrix for i in infos): + return ir.Matrix(loc=loc, rows=[lifted]) + ctx.decline("np.hstack of 1-D and 2-D parts, or of unknown dimensions") + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.hstack``: 1-D parts give 1-D, 2-D parts 2-D.""" + if tag != "py:call:np.hstack" or len(args) != 1 or not args[0].items: + return None + parts = args[0].items + dtype = DType.BOOL + for part in parts: + if part.dtype is DType.UNKNOWN: + dtype = DType.UNKNOWN + break + order = [DType.BOOL, DType.INT, DType.FLOAT, DType.COMPLEX] + dtype = max(dtype, part.dtype, key=order.index) + kind = PyKind.MATRIX if all(p.is_matrix for p in parts) else PyKind.VECTOR + return py_array(kind, dtype, finite=all(p.finite for p in parts)) diff --git a/rules/builtins/constants/cases/filled.m b/rules/builtins/constants/cases/filled.m new file mode 100644 index 0000000..606d283 --- /dev/null +++ b/rules/builtins/constants/cases/filled.m @@ -0,0 +1,7 @@ +% With dimensions, the constants fill arrays; one dimension means a square. +n = 3; +mask = true(n); % 3x3, not 1x3 +none = false(2, 4); +gaps = NaN(1, n); % a row +lo = -Inf(2, 1); % a column +cnt = sum(mask(:)); diff --git a/rules/builtins/constants/cases/filled.py b/rules/builtins/constants/cases/filled.py new file mode 100644 index 0000000..258dd7e --- /dev/null +++ b/rules/builtins/constants/cases/filled.py @@ -0,0 +1,9 @@ +import numpy as np + +# With dimensions, the constants fill arrays; one dimension means a square. +n = 3 +mask = np.full((n, n), True) # 3x3, not 1x3 +none = np.full((2, 4), False) +gaps = np.full(n, np.nan) # a row +lo = -np.full(2, np.inf) # a column +cnt = mask.sum() diff --git a/rules/builtins/constants/rule.yaml b/rules/builtins/constants/rule.yaml index 52d9f6e..5c96e67 100644 --- a/rules/builtins/constants/rule.yaml +++ b/rules/builtins/constants/rule.yaml @@ -1,5 +1,5 @@ id: builtins/constants -title: "Constants: `pi`, `Inf`, `NaN`, `eps`, `true`, `false`, `i`" +title: "Constants: `pi`, `Inf`, `NaN`, `eps`, `true`, `false`, `i`, and arrays of them" status: mechanical dialects: [octave, matlab] match: [call:pi, call:e, call:Inf, call:inf, call:NaN, call:nan, call:eps, call:true, call:false, call:i, call:j] @@ -13,6 +13,7 @@ from_python: # the Python -> .m direction - py:call:np.finfo - py:attr:eps - py:complex + - py:call:np.full octave: | c = 2 * pi * r; m = NaN; @@ -32,6 +33,10 @@ pitfalls: hides the constant, and then it is just a variable. - >- `NaN == NaN` is false in both languages; test with `isnan` / `np.isnan`. + - >- + With dimensions they build arrays, and one dimension means a square: + `true(3)` is 3x3 (`np.full((3, 3), True)`), `NaN(1, n)` is a row + (`np.full(n, np.nan)`). - >- `eps(x)` with an argument is the spacing at `x`: `np.spacing(x)`. related: [builtins/elementwise-math] diff --git a/rules/builtins/constants/translate.py b/rules/builtins/constants/translate.py index 43a46de..0df11fe 100644 --- a/rules/builtins/constants/translate.py +++ b/rules/builtins/constants/translate.py @@ -3,21 +3,73 @@ """Translator for builtins/constants: ``pi``, ``Inf``, ``NaN``, ``eps``, ``true``, ... -Only the argument-free forms are constants; ``eps(x)``, ``Inf(2, 3)`` and -``true(n)`` build arrays and are declined. +Only the argument-free forms are constants. With dimensions, ``Inf``, +``NaN``, ``true`` and ``false`` fill an array: ``np.full`` with the same +value, 1-D when one dimension is 1 (like ``zeros``); ``true(n)`` is n x n. +``eps(x)`` (the spacing at ``x``) is declined. """ import ast from dualect import ir from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind _NUMPY = {"pi": "pi", "e": "e", "Inf": "inf", "inf": "inf", "NaN": "nan", "nan": "nan"} +_FILLS = {"Inf", "inf", "NaN", "nan", "true", "false"} + + +def _is_one(node: ir.Expr, ctx: Context) -> bool: + return ctx.info(node).value == 1 + + +def _fill(node: ir.Call, ctx: Context) -> ast.expr: + """``Inf(m, n)``, ``true(n)``, ...: ``np.full(shape, value)``.""" + args = node.args + if any(not ctx.info(a).is_scalar or isinstance(a, ir.Str) for a in args) or len(args) > 2: + ctx.decline(f"{node.func} with a size vector or a class argument") + name = node.func + value = ctx.np(_NUMPY[name]) if name in _NUMPY else ast.Constant(name == "true") + full = ctx.np("full") + if len(args) == 1: + n = ctx.expr(args[0]) + return ctx.call(full, ast.Tuple(elts=[n, n]), value) + rows, cols = args + if _is_one(rows, ctx): + return ctx.call(full, ctx.expr(cols), value) + if _is_one(cols, ctx): + return ctx.call(full, ctx.expr(rows), value) + if ctx.info(rows).value is None or ctx.info(cols).value is None: + ctx.assume("neither dimension is 1") + return ctx.call(full, ast.Tuple(elts=[ctx.expr(rows), ctx.expr(cols)]), value) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """Facts for the filled arrays (the argument-free constants are core facts).""" + if node.func not in _FILLS or not args or len(args) > 2: + return None + dims = [int(a.value) if isinstance(a.value, int | float) else None for a in args] + rows, cols = (dims[0], dims[0]) if len(dims) == 1 else (dims[0], dims[1]) + logical = node.func in ("true", "false") + facts = { + "elem": Elem.LOGICAL if logical else Elem.REAL, + "finite": logical, + "nonneg": node.func not in ("NaN", "nan"), + "integer": logical, + } + if rows != 1 and cols != 1: + return array(rows, cols, kind=Kind.MATRIX, **facts) # type: ignore[arg-type] + return array(rows, cols, **facts) # type: ignore[arg-type] + + def translate(node: ir.Call, ctx: Context) -> ast.expr: - """One constant.""" + """One constant, or an array filled with one.""" + if node.args and node.func in _FILLS: + return _fill(node, ctx) if node.args: ctx.decline(f"{node.func} with arguments") name = node.func @@ -41,9 +93,60 @@ def translate(node: ir.Call, ctx: Context) -> ast.expr: _FROM_NUMPY = {"np.pi": "pi", "np.inf": "Inf", "np.nan": "NaN"} +_FILL_FROM = {"np.inf": "Inf", "np.nan": "NaN"} + + +def _lift_full(node: ast.Call, ctx: LiftContext) -> ir.Expr: + """``np.full(shape, np.inf)`` and friends: ``Inf(m, n)``, ``true(1, n)``, ...""" + loc = ctx.loc(node) + if len(node.args) != 2 or node.keywords: + ctx.decline("np.full with these arguments") + shape, value = node.args + if isinstance(value, ast.Constant) and isinstance(value.value, bool): + name = "true" if value.value else "false" + else: + tag = ctx.tag(value) or "" + name = _FILL_FROM.get(tag.removeprefix("py:const:"), "") + if not name: + ctx.decline("np.full with a value other than inf, nan, True or False") + if isinstance(shape, ast.Tuple): + if len(shape.elts) != 2: + ctx.decline("np.full with other than two dimensions") + dims = [ctx.expr(e) for e in shape.elts] + else: + if not ctx.info(shape).is_scalar: + ctx.decline("np.full with a computed shape") + dims = [ctx.num(1), ctx.expr(shape)] # 1-D: a row + return ctx.call(name, *dims, loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.full``: an array of the shape given, holding the value given.""" + if tag != "py:call:np.full" or len(args) != 2: + return None + shape, value = args + if shape.kind is PyKind.TUPLE and shape.length == 2: + kind = PyKind.MATRIX + elif shape.is_scalar: + kind = PyKind.VECTOR + else: + return None + dtype = value.dtype if value.dtype is not DType.UNKNOWN else DType.FLOAT + length = shape.value if kind is PyKind.VECTOR and isinstance(shape.value, int) else None + return PyInfo(kind=kind, dtype=dtype, finite=value.finite, nonneg=value.nonneg, length=length) + + def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: - """A NumPy constant, machine epsilon or an imaginary literal.""" + """A NumPy constant, machine epsilon, an imaginary literal or ``np.full``.""" loc = ctx.loc(node) + if isinstance(node, ast.Call) and ctx.tag(node) == "py:call:np.full": + return _lift_full(node, ctx) if isinstance(node, ast.Constant) and isinstance(node.value, complex): return ir.Num(loc=loc, text="", value=node.value) tag = ctx.tag(node) diff --git a/rules/builtins/cumsum-cumprod/cases/basic.m b/rules/builtins/cumsum-cumprod/cases/basic.m new file mode 100644 index 0000000..7c1f03e --- /dev/null +++ b/rules/builtins/cumsum-cumprod/cases/basic.m @@ -0,0 +1,8 @@ +v = [1 2 3 4]; +c = cumsum(v); % 1 3 6 10 +p = cumprod(v); % 1 2 6 24 +A = [1 2; 3 4; 5 6]; +C = cumsum(A); % down each column +R = cumprod(A, 2); % along each row +col = cumsum([1; 2; 3]); % a column stays a column +e = cumsum([]); % empty in, empty out diff --git a/rules/builtins/cumsum-cumprod/cases/basic.py b/rules/builtins/cumsum-cumprod/cases/basic.py new file mode 100644 index 0000000..8767282 --- /dev/null +++ b/rules/builtins/cumsum-cumprod/cases/basic.py @@ -0,0 +1,10 @@ +import numpy as np + +v = np.array([1, 2, 3, 4]) +c = np.cumsum(v) # 1 3 6 10 +p = np.cumprod(v, dtype=float) # 1 2 6 24 +A = np.array([[1, 2], [3, 4], [5, 6]]) +C = np.cumsum(A, axis=0) # down each column +R = np.cumprod(A, axis=1, dtype=float) # along each row +col = np.cumsum(np.array([1, 2, 3])) # a column stays a column +e = np.cumsum(np.array([])) # empty in, empty out diff --git a/rules/builtins/cumsum-cumprod/cases/overflow.m b/rules/builtins/cumsum-cumprod/cases/overflow.m new file mode 100644 index 0000000..739ecec --- /dev/null +++ b/rules/builtins/cumsum-cumprod/cases/overflow.m @@ -0,0 +1,5 @@ +% A product of integer-valued data is computed in doubles: no wrap-around. +big = [100000 100000 100000 100000]; +p = cumprod(big); % 1e5 1e10 1e15 1e20 +m = (1:3) > 1; +s = cumsum(m); % a running count of true values: 0 1 2 diff --git a/rules/builtins/cumsum-cumprod/cases/overflow.py b/rules/builtins/cumsum-cumprod/cases/overflow.py new file mode 100644 index 0000000..3555d60 --- /dev/null +++ b/rules/builtins/cumsum-cumprod/cases/overflow.py @@ -0,0 +1,7 @@ +import numpy as np + +# A product of integer-valued data is computed in doubles: no wrap-around. +big = np.array([100000, 100000, 100000, 100000]) +p = np.cumprod(big, dtype=float) # 1e5 1e10 1e15 1e20 +m = np.arange(1, 4) > 1 +s = np.cumsum(m) # a running count of true values: 0 1 2 diff --git a/rules/builtins/cumsum-cumprod/rule.yaml b/rules/builtins/cumsum-cumprod/rule.yaml new file mode 100644 index 0000000..d0f5010 --- /dev/null +++ b/rules/builtins/cumsum-cumprod/rule.yaml @@ -0,0 +1,40 @@ +id: builtins/cumsum-cumprod +title: "`cumsum`, `cumprod`: running sums and products" +status: mechanical +dialects: [octave, matlab] +match: [call:cumsum, call:cumprod] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.cumsum + - py:call:np.cumprod + - py:method:cumsum + - py:method:cumprod +octave: | + c = cumsum(v); % running total along a vector + C = cumsum(A); % down each column + R = cumprod(A, 2); % along each row +python: | + c = np.cumsum(v) + C = np.cumsum(A, axis=0) + R = np.cumprod(A, axis=1) +why: > + Both run along the first non-singleton dimension: along a vector whatever + its orientation, down the columns of a matrix. `np.cumsum` without an axis + *flattens* a 2-D array (in row order) and returns one long vector, so a + matrix always needs `axis=0` (dimension `d` is `axis=d - 1`). The output has + the input's shape. +pitfalls: + - >- + `np.cumsum(A)` of a 2-D array is a 1-D running total over all elements in + row order, not the column-wise totals of `cumsum(A)`. + - >- + `cumprod` of a NumPy integer array wraps around on overflow; the source + multiplies doubles. Write `np.cumprod(x, dtype=float)`. + - >- + `cumsum(v, 1)` of a row vector runs along its singleton dimension and + returns `v` unchanged. + - >- + `cumsum([])` is empty, like `np.cumsum(np.array([]))`. +related: [builtins/sum-mean-max, builtins/diff] +python_imports: [import numpy as np] diff --git a/rules/builtins/cumsum-cumprod/translate.py b/rules/builtins/cumsum-cumprod/translate.py new file mode 100644 index 0000000..6c94fec --- /dev/null +++ b/rules/builtins/cumsum-cumprod/translate.py @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/cumsum-cumprod: ``cumsum`` and ``cumprod``. + +A vector runs along itself (``np.cumsum(v)``), a matrix down its columns +(``axis=0``) unless a dimension is given (``d`` is ``axis=d - 1``). A +dimension along which a vector is a singleton returns it unchanged in the +source and is declined. ``cumprod`` of data the translation may hold as +integers is taken in floating point (``dtype=float``): NumPy integers wrap +around on overflow where the source multiplies doubles. + +From Python, ``np.cumsum(x)`` of a 1-D array is ``cumsum(x)``; of a 2-D array +it needs an axis (without one NumPy flattens in row order, which is declined); +``axis=0`` is ``cumsum(A, 1)``, ``axis=1`` is ``cumsum(A, 2)``. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def _dim(node: ir.Call, ctx: Context) -> int | None: + if len(node.args) == 1: + return None + value = ctx.info(node.args[1]).value + if len(node.args) > 2 or not isinstance(value, int | float) or value not in (1, 2): + ctx.decline(f"{node.func} with these arguments (a computed or third dimension)") + return int(value) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``cumsum(x)``, ``cumprod(x)``, ``cumsum(x, dim)``.""" + if not node.args: + ctx.decline(f"{node.func} without arguments") + dim = _dim(node, ctx) + data = node.args[0] + info = ctx.info(data) + if info.elem not in (Elem.REAL, Elem.LOGICAL): + ctx.decline(f"{node.func} of values that may be complex or characters") + keywords: dict[str, ast.expr] = {} + if node.func == "cumprod" and info.int_dtype: + keywords["dtype"] = ast.Name("float") # the source multiplies doubles + func = ctx.np(node.func) + if info.is_matrix: + axis = 0 if dim in (None, 1) else 1 + return ctx.call(func, ctx.expr(data), axis=ast.Constant(axis), **keywords) + runs = ( + dim is None or (dim == 2 and info.kind is Kind.ROW) or (dim == 1 and info.kind is Kind.COL) + ) + if info.is_vector and runs: + return ctx.call(func, ctx.arg(data), **keywords) + ctx.decline(f"{node.func} of a value whose shape is unknown, or along a singleton dimension") + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The result has the shape of the data; a logical input counts as numbers.""" + if not args or node.func not in ("cumsum", "cumprod"): + return None + first = args[0] + product = node.func == "cumprod" + return replace( + first, + elem=Elem.REAL if first.elem is Elem.LOGICAL else first.elem, + finite=first.finite and not product, + value=None, + int_dtype=(first.int_dtype or first.is_logical) and not product, + func=None, + env=None, + ) + + +# --- Python -> .m ------------------------------------------------------------ + + +def _axis(node: ast.Call, args: list[ast.expr], ctx: LiftContext) -> int | None: + axis_node = args[0] if args else None + for keyword in node.keywords: + if keyword.arg == "axis": + axis_node = keyword.value + elif keyword.arg == "dtype" and isinstance(keyword.value, ast.Name): + if keyword.value.id != "float": + ctx.decline(f"dtype={keyword.value.id} in a running sum") + else: + ctx.decline(f"{keyword.arg}= in a running sum") + if axis_node is None: + return None + value = ctx.info(axis_node).value + if isinstance(value, bool) or value not in (0, 1, -1, -2): + ctx.decline("a running sum along a computed axis") + assert isinstance(value, int) + return value + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.cumsum(x, axis=...)`` or ``x.cumsum(...)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + tag = ctx.tag(node) or "" + func = tag.split(":")[-1].removeprefix("np.") + if tag.startswith("py:method:"): + assert isinstance(node.func, ast.Attribute) + data, rest = node.func.value, list(node.args) + else: + if not node.args: + ctx.decline(f"{func} without arguments") + data, rest = node.args[0], list(node.args[1:]) + axis = _axis(node, rest, ctx) + info = ctx.info(data) + if info.dtype is DType.COMPLEX: + ctx.decline(f"{func} of complex values") + if func == "cumprod" and info.dtype in (DType.INT, DType.BOOL): + ctx.assume("no integer overflow in the Python cumprod (the .m side multiplies doubles)") + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + if info.is_vector or isinstance(data, ast.List): + if axis not in (None, 0, -1): + ctx.decline(f"{func} of a 1-D array along axis 1") + return ctx.call(func, value, loc=loc) + if not info.is_matrix: + ctx.decline(f"{func} of a value whose dimensions are unknown") + if axis is None: + ctx.decline(f"{func} of a 2-D array without an axis (NumPy flattens it in row order)") + return ctx.call(func, value, ctx.num(1 if axis in (0, -2) else 2), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """1-D unless a 2-D array keeps its shape along an axis; booleans count as integers.""" + if receiver is not None: + data, rest = receiver, args + elif args: + data, rest = as_array(args[0]), args[1:] + else: + return None + if not data.is_array: + return None + has_axis = bool(rest) or "axis" in keywords + kind = PyKind.MATRIX if data.is_matrix and has_axis else PyKind.VECTOR + dtype = DType.INT if data.dtype is DType.BOOL else data.dtype + if any(isinstance(k.value, ast.Name) and k.value.id == "float" for k in node.keywords): + dtype = DType.FLOAT + product = tag.endswith("cumprod") + return PyInfo( + kind=kind, + dtype=dtype, + finite=data.finite and not product, + nonneg=data.nonneg, + length=data.length if data.is_vector else None, + ) diff --git a/rules/builtins/diff/cases/basic.m b/rules/builtins/diff/cases/basic.m new file mode 100644 index 0000000..c016b55 --- /dev/null +++ b/rules/builtins/diff/cases/basic.m @@ -0,0 +1,8 @@ +x = [1 4 9 16 25]; +d = diff(x); % 3 5 7 9: one element shorter +d2 = diff(x, 2); % 2 2 2 +A = [1 2; 4 8; 9 9]; +D = diff(A); % down each column: 3 6; 5 1 +E = diff(A, 1, 2); % along each row: 1; 4; 0 +m = [1 3 2 5] > 2; +steps = diff(m); % logical in, numbers out: 1 -1 1 diff --git a/rules/builtins/diff/cases/basic.py b/rules/builtins/diff/cases/basic.py new file mode 100644 index 0000000..cf020e1 --- /dev/null +++ b/rules/builtins/diff/cases/basic.py @@ -0,0 +1,10 @@ +import numpy as np + +x = np.array([1, 4, 9, 16, 25]) +d = np.diff(x) # 3 5 7 9: one element shorter +d2 = np.diff(x, n=2) # 2 2 2 +A = np.array([[1, 2], [4, 8], [9, 9]]) +D = np.diff(A, axis=0) # down each column: 3 6; 5 1 +E = np.diff(A, axis=1) # along each row: 1; 4; 0 +m = np.array([1, 3, 2, 5]) > 2 +steps = np.diff(m.astype(int)) # logical in, numbers out: 1 -1 1 diff --git a/rules/builtins/diff/rule.yaml b/rules/builtins/diff/rule.yaml new file mode 100644 index 0000000..c668e6c --- /dev/null +++ b/rules/builtins/diff/rule.yaml @@ -0,0 +1,36 @@ +id: builtins/diff +title: "`diff`: differences between neighbouring elements" +status: mechanical +dialects: [octave, matlab] +match: [call:diff] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.diff +octave: | + d = diff(x); % x(2:end) - x(1:end-1) + d2 = diff(x, 2); % second differences + D = diff(A); % down each column +python: | + d = np.diff(x) + d2 = np.diff(x, n=2) + D = np.diff(A, axis=0) +why: > + Each difference shortens the data by one along the first non-singleton + dimension: down the columns of a matrix. `np.diff` works along the *last* + axis by default (along the rows of a 2-D array), so a matrix needs + `axis=0`. The order is the second argument in both (`n=` in NumPy). +pitfalls: + - >- + `np.diff(A)` of a 2-D array differences along each row; `diff(A)` down + each column. Pass `axis=0`. + - >- + When the order reaches the length of the data, the source moves on to + the next dimension instead of returning an empty result + (`diff([1 4 9], 3)` is not empty), while NumPy returns an empty array. + Only orders known to be smaller than the length are translated. + - >- + `diff` of a logical array gives numbers; NumPy refuses to subtract + booleans, so convert first (`m.astype(int)`). +related: [builtins/cumsum-cumprod, builtins/sum-mean-max] +python_imports: [import numpy as np] diff --git a/rules/builtins/diff/translate.py b/rules/builtins/diff/translate.py new file mode 100644 index 0000000..36495fa --- /dev/null +++ b/rules/builtins/diff/translate.py @@ -0,0 +1,201 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/diff: ``diff(x)``, ``diff(x, n)``, ``diff(x, n, dim)``. + +A vector is differenced along itself, a matrix down its columns (``axis=0``, +since ``np.diff`` defaults to the last axis), and dimension ``d`` is +``axis=d - 1``. The order must be a known positive integer. When it reaches +the length of the data the source moves on to the next dimension while NumPy +returns an empty array, so an order known to be too large is declined and an +order above 1 on data of unknown length is assumed to fit, out loud. A +logical array is converted to integers first: NumPy refuses boolean +subtraction, the source differences numbers. + +From Python, ``np.diff(x, n, axis)`` is the same call with the axis as a +dimension; on a 2-D array the default axis is the last one, ``dim = 2``. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def _constant(node: ir.Expr, ctx: Context, what: str) -> int: + value = ctx.info(node).value + if not isinstance(value, int | float) or not float(value).is_integer() or value < 1: + ctx.decline(f"diff with a {what} that is not a known positive integer") + return int(value) + + +def _order_and_dim(node: ir.Call, ctx: Context) -> tuple[int, int | None]: + if not 1 <= len(node.args) <= 3: + ctx.decline("diff with these arguments") + order = _constant(node.args[1], ctx, "order") if len(node.args) > 1 else 1 + dim = _constant(node.args[2], ctx, "dimension") if len(node.args) > 2 else None + if dim is not None and dim > 2: + ctx.decline("diff along a third dimension") + return order, dim + + +def _check_length(length: int | None, order: int, ctx: Context) -> None: + if length is not None and order >= length and length > 0: + ctx.decline( + "diff of an order not below the length (the source moves to the next dimension)" + ) + if length is None and order > 1: + ctx.assume(f"more than {order} elements to difference") + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """One ``diff`` call.""" + order, dim = _order_and_dim(node, ctx) + data = node.args[0] + info = ctx.info(data) + if info.elem not in (Elem.REAL, Elem.LOGICAL): + ctx.decline("diff of values that may be complex or characters") + expr = ctx.expr(data) + if info.is_logical: + expr = ctx.method(expr, "astype", ast.Name("int")) # NumPy cannot subtract booleans + keywords: dict[str, ast.expr] = {} + if order != 1: + keywords["n"] = ast.Constant(order) + if info.is_matrix: + axis = 0 if dim in (None, 1) else 1 + _check_length(info.rows if axis == 0 else info.cols, order, ctx) + return ctx.call(ctx.np("diff"), expr, **keywords, axis=ast.Constant(axis)) + along = ( + dim is None or (dim == 2 and info.kind is Kind.ROW) or (dim == 1 and info.kind is Kind.COL) + ) + if info.is_vector and info.kind is not Kind.EMPTY and along: + _check_length(info.numel, order, ctx) + return ctx.call(ctx.np("diff"), expr, **keywords) + ctx.decline( + "diff of a scalar, an empty value, a value of unknown shape or a singleton dimension" + ) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """One element (row or column) shorter per order along the differenced dimension.""" + if not args: + return None + first = args[0] + order = 1 + if len(args) > 1 and isinstance(args[1].value, int | float): + order = int(args[1].value) + dim = int(args[2].value) if len(args) > 2 and isinstance(args[2].value, int | float) else None + rows, cols = first.rows, first.cols + if first.is_matrix: + if dim == 2: + cols = cols - order if cols is not None else None + else: + rows = rows - order if rows is not None else None + elif first.kind is Kind.ROW: + cols = cols - order if cols is not None else None + elif first.kind is Kind.COL: + rows = rows - order if rows is not None else None + else: + return None + return replace( + first, + rows=rows, + cols=cols, + elem=Elem.REAL, + nonneg=False, + value=None, + int_dtype=first.int_dtype or first.is_logical, + func=None, + env=None, + ) + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.diff(x, n=..., axis=...)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if not node.args or len(node.args) > 3: + ctx.decline("np.diff with these arguments") + named = {"n": node.args[1] if len(node.args) > 1 else None} + named["axis"] = node.args[2] if len(node.args) > 2 else None + for keyword in node.keywords: + if keyword.arg not in ("n", "axis"): + ctx.decline(f"np.diff with {keyword.arg}=") + named[keyword.arg] = keyword.value + order, axis = 1, None + for key, value_node in named.items(): + if value_node is None: + continue + value = ctx.info(value_node).value + if isinstance(value, bool) or not isinstance(value, int): + ctx.decline(f"np.diff with a computed {key}") + if key == "n": + order = value + else: + axis = value + if order < 1: + ctx.decline("np.diff of order 0") + data = node.args[0] + if ( + isinstance(data, ast.Call) + and isinstance(data.func, ast.Attribute) + and data.func.attr == "astype" + and len(data.args) == 1 + and isinstance(data.args[0], ast.Name) + and data.args[0].id == "int" + and ctx.info(data.func.value).is_bool + ): + # m.astype(int) of a mask: the .m diff takes the logical values as numbers. + data = data.func.value + info = ctx.info(data) + if info.dtype in (DType.COMPLEX, DType.BOOL) and data is node.args[0]: + ctx.decline("np.diff of complex or boolean values") + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + args: list[ir.Expr] = [value] + if info.is_vector or isinstance(data, ast.List): + if axis not in (None, 0, -1): + ctx.decline("np.diff of a 1-D array along axis 1") + length = info.length if info.is_vector else len(data.elts) # type: ignore[attr-defined] + if length is not None and order >= length: + ctx.decline("np.diff of an order not below the length") + if length is None and order > 1: + ctx.assume(f"more than {order} elements to difference") + if order != 1: + args.append(ctx.num(order)) + return ctx.call("diff", *args, loc=loc) + if not info.is_matrix: + ctx.decline("np.diff of a value whose dimensions are unknown") + if axis not in (None, 0, 1, -1, -2): + ctx.decline(f"np.diff along axis {axis}") + if order > 1: + ctx.assume(f"more than {order} elements to difference along the axis") + dim = 1 if axis in (0, -2) else 2 + return ctx.call("diff", value, ctx.num(order), ctx.num(dim), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """The data's kind and element type, shorter.""" + if not args: + return None + data = as_array(args[0]) + if not data.is_array: + return None + order = args[1].value if len(args) > 1 else keywords.get("n", PyInfo(value=1)).value + length = None + if data.is_vector and data.length is not None and isinstance(order, int): + length = max(data.length - order, 0) + kind = PyKind.MATRIX if data.is_matrix else PyKind.VECTOR + return PyInfo(kind=kind, dtype=data.dtype, finite=data.finite, length=length) diff --git a/rules/builtins/dot-cross-kron/cases/basic.m b/rules/builtins/dot-cross-kron/cases/basic.m new file mode 100644 index 0000000..ac058d0 --- /dev/null +++ b/rules/builtins/dot-cross-kron/cases/basic.m @@ -0,0 +1,12 @@ +% dot ignores orientation; kron needs it. +u = [1 2 3]; +v = [4; 5; 6]; +d = dot(u, v); % 32: a row and a column are fine +w = cross([1 0 0], [0 1 0]); % [0 0 1] +A = [1 2; 3 4]; +K = kron(A, eye(2)); % 4x4 block matrix +r = [1 2]; +c = [10; 20]; +M = kron(c, r); % 2x2: the outer product +L = kron(r, [1 1]); % two rows: a longer row +P = kron(c, A); % a column next to a matrix: 4x2 diff --git a/rules/builtins/dot-cross-kron/cases/basic.py b/rules/builtins/dot-cross-kron/cases/basic.py new file mode 100644 index 0000000..9ccdfd4 --- /dev/null +++ b/rules/builtins/dot-cross-kron/cases/basic.py @@ -0,0 +1,14 @@ +import numpy as np + +# dot ignores orientation; kron needs it. +u = np.array([1, 2, 3]) +v = np.array([4, 5, 6]) +d = np.dot(u, v) # 32: a row and a column are fine +w = np.cross([1, 0, 0], [0, 1, 0]) # [0 0 1] +A = np.array([[1, 2], [3, 4]]) +K = np.kron(A, np.eye(2)) # 4x4 block matrix +r = np.array([1, 2]) +c = np.array([10, 20]) +M = np.outer(c, r) # 2x2: the outer product +L = np.kron(r, [1, 1]) # two rows: a longer row +P = np.kron(c[:, np.newaxis], A) # a column next to a matrix: 4x2 diff --git a/rules/builtins/dot-cross-kron/rule.yaml b/rules/builtins/dot-cross-kron/rule.yaml new file mode 100644 index 0000000..4a5d66f --- /dev/null +++ b/rules/builtins/dot-cross-kron/rule.yaml @@ -0,0 +1,42 @@ +id: builtins/dot-cross-kron +title: "`dot`, `cross` and `kron`: products of vectors and matrices" +status: mechanical +dialects: [octave, matlab] +match: [call:dot, call:cross, call:kron] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.dot + - py:call:np.cross + - py:call:np.kron +octave: | + d = dot(u, v); % sum(u .* v), any orientation + w = cross(u, v); % 3-element vectors + K = kron(A, B); + M = kron(c, r); % a column and a row: their outer product +python: | + d = np.dot(u, v) + w = np.cross(u, v) + K = np.kron(A, B) + M = np.outer(c, r) +why: > + For real vectors `dot` is `np.dot` and `cross` is `np.cross`. `kron` is + `np.kron` for matrices, but vectors need their orientation, which NumPy's + 1-D arrays do not keep: the Kronecker product of a column and a row (either + order) is the matrix `np.outer(column, row)`, and a column next to a matrix + must become a 2-D column first (`c[:, np.newaxis]`). +pitfalls: + - >- + `dot` conjugates its first argument for complex data; `np.dot` does not + (`np.vdot` does). + - >- + `dot(A, B)` of matrices is a row of column-wise dot products; + `np.dot(A, B)` is the matrix product. + - >- + `np.kron(c, r)` of two 1-D arrays is a long 1-D array, not the matrix + `kron(c, r)` gives for a column and a row. + - >- + `np.cross` accepts 2-element vectors and returns a scalar; `cross` needs + 3 elements. +related: [builtins/norm, operators/matrix-multiply] +python_imports: [import numpy as np] diff --git a/rules/builtins/dot-cross-kron/translate.py b/rules/builtins/dot-cross-kron/translate.py new file mode 100644 index 0000000..63d794d --- /dev/null +++ b/rules/builtins/dot-cross-kron/translate.py @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/dot-cross-kron: ``dot``, ``cross`` and ``kron``. + +``dot(a, b)`` of two real vectors (either orientation) is ``np.dot(a, b)``. +The source conjugates its first argument, ``np.dot`` does not +(``np.vdot`` does), and ``dot`` of matrices works column by column where +``np.dot`` is a matrix product, so complex data and matrices are declined. +``cross(a, b)`` of two 3-element vectors of the same orientation is +``np.cross(a, b)``; NumPy also accepts 2-element vectors (returning a +scalar) where the source raises, so an unknown length is assumed to be 3, +out loud. + +``kron`` needs the orientation NumPy's 1-D arrays drop: two rows, two columns +or two matrices are ``np.kron(a, b)``; a column and a row (in either order) +make the matrix ``np.outer(c, r)``; a column next to a matrix gets its column +axis back, ``c[:, np.newaxis]``. + +From Python, ``np.dot`` and ``np.cross`` of 1-D arrays and ``np.kron`` (a 1-D +array is a row on both sides) map back. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind +from dualect.pyinfer import array as py_array +from dualect.pyinfer import scalar as py_scalar + + +def _times(a: int | None, b: int | None) -> int | None: + return a * b if a is not None and b is not None else None + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A scalar for ``dot``, the shape of ``a`` for ``cross``, the product for ``kron``.""" + if len(args) != 2: + return None + a, b = args + result = _shape(node, a, b) + # NumPy keeps integer inputs integer (np.kron, np.cross, np.outer, np.dot). + return replace(result, int_dtype=a.int_dtype and b.int_dtype) if result else None + + +def _shape(node: ir.Call, a: Info, b: Info) -> Info | None: + elem = Elem.REAL if a.is_real and b.is_real else Elem.UNKNOWN + finite = a.finite and b.finite + if node.func == "dot": + return scalar(elem=elem, finite=finite) if a.is_vector and b.is_vector else None + if node.func == "cross": + return array(a.rows, a.cols, elem=elem, finite=finite, kind=a.kind) + if node.func == "kron": + if a.kind in (Kind.UNKNOWN, Kind.ARRAY, Kind.VECTOR): + return None + if b.kind in (Kind.UNKNOWN, Kind.ARRAY, Kind.VECTOR): + return None + rows, cols = _times(a.rows, b.rows), _times(a.cols, b.cols) + kind = None + if {a.kind, b.kind} == {Kind.ROW, Kind.COL} or Kind.MATRIX in (a.kind, b.kind): + kind = Kind.MATRIX if rows != 1 and cols != 1 else None + return array(rows, cols, elem=elem, finite=finite, nonneg=a.nonneg and b.nonneg, kind=kind) + return None + + +def _column(expr: ast.expr, ctx: Context) -> ast.expr: + return ast.Subscript(value=expr, slice=ast.Tuple(elts=[ast.Slice(), ctx.np("newaxis")])) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``dot``, ``cross`` or ``kron`` of two arguments.""" + if len(node.args) != 2: + ctx.decline(f"{node.func} with a dimension argument") + a_node, b_node = node.args + a, b = ctx.info(a_node), ctx.info(b_node) + x, y = ctx.arg(a_node), ctx.arg(b_node) + if node.func == "dot": + if not (a.is_vector and b.is_vector): + ctx.decline("dot of values not known to be vectors (matrices go column by column)") + if not (a.is_real and b.is_real): + ctx.decline("dot of values that may be complex (the source conjugates the first)") + return ctx.call(ctx.np("dot"), x, y) + if node.func == "cross": + if not (a.kind is b.kind and a.kind in (Kind.ROW, Kind.COL)): + ctx.decline("cross of vectors not known to share an orientation") + if a.numel not in (3, None) or b.numel not in (3, None): + ctx.decline("cross of vectors that do not have 3 elements") + if a.numel is None or b.numel is None: + ctx.assume("3-element vectors (NumPy also accepts 2)") + return ctx.call(ctx.np("cross"), x, y) + # kron + known = (Kind.SCALAR, Kind.ROW, Kind.COL, Kind.MATRIX) + if a.kind not in known or b.kind not in known: + ctx.decline("kron of values whose orientation (row, column or matrix) is unknown") + if {a.kind, b.kind} == {Kind.ROW, Kind.COL}: + column, row = (x, y) if a.kind is Kind.COL else (y, x) + return ctx.call(ctx.np("outer"), column, row) + if a.kind is Kind.COL and b.kind is Kind.MATRIX: + x = _column(x, ctx) + if b.kind is Kind.COL and a.kind is Kind.MATRIX: + y = _column(y, ctx) + return ctx.call(ctx.np("kron"), x, y) + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.dot`` and ``np.cross`` of 1-D arrays, ``np.kron``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + func = (ctx.tag(node) or "").removeprefix("py:call:np.") + if len(node.args) != 2 or node.keywords: + ctx.decline(f"np.{func} with these arguments") + literals = ctx.module_for("syntax/array-literals") + infos = [ctx.info(arg) for arg in node.args] + one_d = [ + i.is_vector or isinstance(arg, ast.List) for i, arg in zip(infos, node.args, strict=True) + ] + values = [literals.lift_items(arg, ctx) for arg in node.args] + if func in ("dot", "cross"): + if not all(one_d): + ctx.decline(f"np.{func} of values not known to be 1-D") + if ( + func == "dot" + and any(i.dtype in (DType.COMPLEX, DType.UNKNOWN) for i in infos) + and not all(isinstance(arg, ast.List) for arg in node.args) + ): + ctx.decline("np.dot of data that may be complex (the .m dot conjugates)") + if func == "cross": + lengths = {i.length for i in infos} + if lengths - {3, None}: + ctx.decline("np.cross of vectors that do not have 3 elements") + if None in lengths: + ctx.assume("3-element vectors (the .m cross rejects others)") + return ctx.call(func, *values, loc=loc) + if not all(o or i.is_matrix or i.is_scalar for o, i in zip(one_d, infos, strict=True)): + ctx.decline("np.kron of values whose dimensions are unknown") + return ctx.call("kron", *values, loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.dot`` of 1-D arrays is a scalar; ``np.cross`` keeps the shape; ``np.kron``.""" + if len(args) != 2: + return None + a, b = args + # NumPy's result type: integer (or bool) inputs stay integer, which a later + # store of a fraction must know about. + order = [DType.BOOL, DType.INT, DType.FLOAT, DType.COMPLEX] + if DType.UNKNOWN in (a.dtype, b.dtype): + dtype = DType.UNKNOWN + else: + dtype = max(a.dtype, b.dtype, key=order.index) + if tag == "py:call:np.dot" and a.kind is PyKind.VECTOR and b.kind is PyKind.VECTOR: + return py_scalar(dtype, finite=a.finite and b.finite) + if tag == "py:call:np.cross": + return py_array(PyKind.VECTOR, dtype, length=a.length) + if tag == "py:call:np.kron": + kind = PyKind.MATRIX if PyKind.MATRIX in (a.kind, b.kind) else PyKind.VECTOR + return py_array(kind, dtype, finite=a.finite and b.finite) + return None diff --git a/rules/builtins/elementwise-math/cases/sign-rules.m b/rules/builtins/elementwise-math/cases/sign-rules.m new file mode 100644 index 0000000..52681fd --- /dev/null +++ b/rules/builtins/elementwise-math/cases/sign-rules.m @@ -0,0 +1,14 @@ +% Floor division, mod and rem with negative and fractional operands. +a = [-7 7 -7.5 7.5]; +q = floor(a / 2); % floors toward -Inf: -4 3 -4 3 +m = mod(a, 2); % the sign of the divisor +r = rem(a, 2); % the sign of the dividend +m_neg = mod(7.5, -2); % -0.5 +r_neg = rem(5, -3); % 2 +small = [1e-10 -1e-10]; +lp = log1p(small); % accurate near zero +em = expm1(small); +z = [3+4i, -1-2i]; +re = real(z); +im = imag(z); +c = conj(z); diff --git a/rules/builtins/elementwise-math/cases/sign-rules.py b/rules/builtins/elementwise-math/cases/sign-rules.py new file mode 100644 index 0000000..ea26d06 --- /dev/null +++ b/rules/builtins/elementwise-math/cases/sign-rules.py @@ -0,0 +1,16 @@ +import numpy as np + +# Floor division, mod and rem with negative and fractional operands. +a = np.array([-7, 7, -7.5, 7.5]) +q = a // 2 # floors toward -Inf: -4 3 -4 3 +m = np.mod(a, 2) # the sign of the divisor +r = np.fmod(a, 2) # the sign of the dividend +m_neg = np.mod(7.5, -2) # -0.5 +r_neg = np.fmod(5, -3) # 2 +small = np.array([1e-10, -1e-10]) +lp = np.log1p(small) # accurate near zero +em = np.expm1(small) +z = np.array([3 + 4j, -1 - 2j]) +re = np.real(z) +im = np.imag(z) +c = np.conj(z) diff --git a/rules/builtins/elementwise-math/rule.yaml b/rules/builtins/elementwise-math/rule.yaml index 82cc6e1..1761b74 100644 --- a/rules/builtins/elementwise-math/rule.yaml +++ b/rules/builtins/elementwise-math/rule.yaml @@ -30,6 +30,11 @@ match: - call:isnan - call:isinf - call:isfinite + - call:real + - call:imag + - call:conj + - call:log1p + - call:expm1 from_python: # the Python -> .m direction status: mechanical match: @@ -61,6 +66,10 @@ from_python: # the Python -> .m direction - py:call:np.hypot - py:call:np.round - py:call:abs + - py:call:np.real + - py:call:np.imag + - py:call:np.log1p + - py:call:np.expm1 - py:op:mod octave: | a = abs(x); @@ -91,6 +100,17 @@ pitfalls: `sqrt`, `log` and `asin` of out-of-domain values return complex numbers in `.m` code but NaN (with a warning) in NumPy; use `np.emath.sqrt` / `np.emath.log` when negative inputs are possible. + - >- + `floor(a / b)` is Python's `a // b`, which also floors toward minus + infinity for negative operands (`-7 // 2` is -4); but `inf // 2` is NaN + where `floor(Inf / 2)` is Inf, so it needs finite data and a nonzero + divisor. + - >- + `mod(-7.5, 2)` is 0.5 and `rem(-7.5, 2)` is -1.5: the sign rule holds for + fractions too. `np.mod`/`np.fmod` agree. + - >- + `log1p(x)` and `expm1(x)` keep precision near zero, as `np.log1p` and + `np.expm1` do; `log1p` below -1 is complex in the source. - >- `atan2(y, x)` keeps its argument order in `np.arctan2(y, x)`; the inverse trigonometric names gain an `arc` prefix (`asin` -> `np.arcsin`). diff --git a/rules/builtins/elementwise-math/translate.py b/rules/builtins/elementwise-math/translate.py index a9f5147..7a2d572 100644 --- a/rules/builtins/elementwise-math/translate.py +++ b/rules/builtins/elementwise-math/translate.py @@ -6,6 +6,7 @@ Most names map to their NumPy function; the renamed ones are listed in :data:`_NUMPY`. ``abs`` of a known scalar is Python's ``abs``. ``round`` rounds halves away from zero, written out from ``np.sign`` and ``np.floor``. +``floor(a / b)`` by a known nonzero scalar, of finite data, is ``a // b``. ``sqrt``/``log`` of a value not known to be non-negative is assumed to be in the real domain (docs/design.md section 5.2): NumPy returns NaN where the source returns a complex number, and verification catches that. ``mod(x, 0)`` @@ -14,10 +15,13 @@ """ import ast +from dataclasses import replace from dualect import ir from dualect.emit import Context +from dualect.infer import Elem, Info, Kind from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, as_array _NUMPY = { "asin": "arcsin", @@ -30,8 +34,10 @@ _DOMAIN = frozenset({"sqrt", "log", "log2", "log10", "asin", "acos"}) _SAME = frozenset( {"abs", "sqrt", "exp", "log", "log2", "log10", "sin", "cos", "tan", "sinh", "cosh", - "tanh", "hypot", "floor", "ceil", "sign", "isnan", "isinf", "isfinite", "mod"} + "tanh", "hypot", "floor", "ceil", "sign", "isnan", "isinf", "isfinite", "mod", "real", + "imag", "conj", "log1p", "expm1"} ) # fmt: skip +_DOMAIN_LOG1P = frozenset({"log1p"}) def translate(node: ir.Call, ctx: Context) -> ast.expr: @@ -49,6 +55,10 @@ def translate(node: ir.Call, ctx: Context) -> ast.expr: ast.BinOp(left=ctx.call(ctx.np("abs"), x), op=ast.Add(), right=ast.Constant(0.5)), ) return ast.BinOp(left=ctx.call(ctx.np("sign"), x), op=ast.Mult(), right=floor) + if name == "floor" and len(node.args) == 1: + quotient = _floor_division(node.args[0], ctx) + if quotient is not None: + return quotient if name == "abs" and first.is_scalar and len(node.args) == 1: return ctx.call(ast.Name("abs"), ctx.expr(node.args[0])) if name not in _SAME and name not in _NUMPY: @@ -62,10 +72,56 @@ def translate(node: ir.Call, ctx: Context) -> ast.expr: ctx.assume(f"nonzero divisor in {name}") if name in _DOMAIN and not first.nonneg: ctx.assume(f"{name} argument in the real domain") + if name == "log1p" and isinstance(first.value, int | float) and first.value < -1: + ctx.decline("log1p below -1 (complex in the source, NaN in NumPy)") + if name == "log1p" and not first.nonneg: + ctx.assume("log1p argument >= -1") args = [ctx.arg(arg) for arg in node.args] return ctx.call(ctx.np(_NUMPY.get(name, name)), *args) +def _floor_division(node: ir.Expr, ctx: Context) -> ast.expr | None: + """``floor(a / b)`` as ``a // b``, when that is exactly the same value. + + Python's ``//`` floors like the source, for negative operands too, but + ``inf // 2`` is NaN (the source gives Inf) and ``x // 0`` raises or is + NaN, so both operands must be known finite and the divisor nonzero. + """ + if not (isinstance(node, ir.BinOp) and node.op in ("rdivide", "mrdivide")): + return None + left, right = ctx.info(node.left), ctx.info(node.right) + divisor = right.value + if not (right.is_scalar and isinstance(divisor, int | float) and divisor != 0): + return None + if not (left.finite and right.finite) or not (left.is_scalar or left.is_array): + return None + if left.elem not in (Elem.REAL, Elem.LOGICAL) or left.is_logical: + return None + return ast.BinOp(left=ctx.expr(node.left), op=ast.FloorDiv(), right=ctx.expr(node.right)) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """Facts for the names the core analysis does not know (``log1p``, ``expm1``).""" + if node.func not in ("log1p", "expm1") or len(args) != 1: + return None + first = args[0] + if first.kind is Kind.UNKNOWN: + return None + elem = Elem.REAL if first.is_real and (node.func == "expm1" or first.nonneg) else first.elem + if node.func == "log1p" and not first.nonneg: + elem = Elem.UNKNOWN # below -1 the source returns a complex number + return replace( + first, + elem=elem, + finite=first.finite and node.func == "log1p" and first.nonneg, + nonneg=first.nonneg, + integer=False, + value=None, + func=None, + int_dtype=False, + ) + + # --- Python -> .m ------------------------------------------------------------ # # The same functions under their .m names (np.arcsin is asin, np.trunc fix, @@ -80,9 +136,10 @@ def translate(node: ir.Call, ctx: Context) -> ast.expr: "arccos": "acos", "arctan": "atan", "arctan2": "atan2", "sinh": "sinh", "cosh": "cosh", "tanh": "tanh", "floor": "floor", "ceil": "ceil", "trunc": "fix", "sign": "sign", "isnan": "isnan", "isinf": "isinf", "isfinite": "isfinite", - "mod": "mod", "fmod": "rem", "hypot": "hypot", "round": "round", + "mod": "mod", "fmod": "rem", "hypot": "hypot", "round": "round", "real": "real", + "imag": "imag", "log1p": "log1p", "expm1": "expm1", } # fmt: skip -_REAL_DOMAIN = frozenset({"sqrt", "log", "log2", "log10", "arcsin", "arccos"}) +_REAL_DOMAIN = frozenset({"sqrt", "log", "log2", "log10", "arcsin", "arccos", "log1p"}) def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: @@ -117,3 +174,25 @@ def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: if name in _REAL_DOMAIN and not first.nonneg: ctx.assume(f"{name} argument in the real domain") return ctx.call(_TO_M[name], *(literals.lift_items(a, ctx) for a in node.args), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.log1p`` and ``np.expm1``: element-wise, in floating point.""" + if tag not in ("py:call:np.log1p", "py:call:np.expm1") or len(args) != 1: + return None + first = as_array(args[0]) + if not (first.is_scalar or first.is_array): + return None + return replace( + first, + dtype=DType.COMPLEX if first.dtype is DType.COMPLEX else DType.FLOAT, + finite=first.finite and first.nonneg, + value=None, + view=False, + ) diff --git a/rules/builtins/filter/cases/columns.m b/rules/builtins/filter/cases/matrix.m similarity index 100% rename from rules/builtins/filter/cases/columns.m rename to rules/builtins/filter/cases/matrix.m diff --git a/rules/builtins/filter/cases/columns.py b/rules/builtins/filter/cases/matrix.py similarity index 100% rename from rules/builtins/filter/cases/columns.py rename to rules/builtins/filter/cases/matrix.py diff --git a/rules/builtins/flip/cases/basic.m b/rules/builtins/flip/cases/basic.m new file mode 100644 index 0000000..7d8405b --- /dev/null +++ b/rules/builtins/flip/cases/basic.m @@ -0,0 +1,12 @@ +v = [1 2 3]; +r = fliplr(v); % 3 2 1 +same_row = flipud(v); % a row has one row: unchanged +c = [1; 2; 3]; +rc = flipud(c); % 3; 2; 1 +same_col = fliplr(c); % a column has one column: unchanged +A = [1 2 3; 4 5 6]; +L = fliplr(A); % columns reversed +U = flipud(A); % rows reversed +F = flip(A); % first non-singleton dimension: the rows +G = flip(A, 2); % along dimension 2: the columns +w = flip(v); % a vector, whichever way it points diff --git a/rules/builtins/flip/cases/basic.py b/rules/builtins/flip/cases/basic.py new file mode 100644 index 0000000..a41daf5 --- /dev/null +++ b/rules/builtins/flip/cases/basic.py @@ -0,0 +1,14 @@ +import numpy as np + +v = np.array([1, 2, 3]) +r = np.flip(v) # 3 2 1 +same_row = v # a row has one row: unchanged +c = np.array([1, 2, 3]) +rc = np.flip(c) # 3; 2; 1 +same_col = c # a column has one column: unchanged +A = np.array([[1, 2, 3], [4, 5, 6]]) +L = np.fliplr(A) # columns reversed +U = np.flipud(A) # rows reversed +F = np.flip(A, axis=0) # first non-singleton dimension: the rows +G = np.fliplr(A) # along dimension 2: the columns +w = np.flip(v) # a vector, whichever way it points diff --git a/rules/builtins/flip/rule.yaml b/rules/builtins/flip/rule.yaml new file mode 100644 index 0000000..9be07b7 --- /dev/null +++ b/rules/builtins/flip/rule.yaml @@ -0,0 +1,38 @@ +id: builtins/flip +title: "`fliplr`, `flipud`, `flip`: reversing the order of elements" +status: mechanical +dialects: [octave, matlab] +match: [call:fliplr, call:flipud, call:flip] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.flip + - py:call:np.fliplr + - py:call:np.flipud +octave: | + r = fliplr(v); % a row, reversed + B = flipud(A); % rows in reverse order + c = flip(col); % along the first non-singleton dimension +python: | + r = np.flip(v) + B = np.flipud(A) + c = np.flip(col) +why: > + `fliplr` reverses the columns and `flipud` the rows. A NumPy 1-D array + stands for both a row and a column, so the orientation of the source vector + decides: `fliplr` of a row reverses it, but `fliplr` of a column leaves it + unchanged (it has one column), and the other way round for `flipud`. + `flip` works along the first non-singleton dimension: it reverses any + vector, and the rows of a matrix (`np.flip(A, axis=0)`). +pitfalls: + - >- + `fliplr` of a column vector and `flipud` of a row vector change nothing; + `np.flip` of the 1-D array that stands for it reverses it. + - >- + `np.fliplr` refuses a 1-D array, and `np.flip(A)` without an axis + reverses *both* axes of a matrix. + - >- + `np.flip` returns a view: writing into the result writes into the + original array. +related: [builtins/sort, indexing/ranges] +python_imports: [import numpy as np] diff --git a/rules/builtins/flip/translate.py b/rules/builtins/flip/translate.py new file mode 100644 index 0000000..3b8e2f7 --- /dev/null +++ b/rules/builtins/flip/translate.py @@ -0,0 +1,147 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/flip: ``fliplr``, ``flipud`` and ``flip``. + +The orientation of the source vector decides: ``fliplr`` of a row and +``flipud`` of a column reverse the 1-D array (``np.flip(v)``), while +``fliplr`` of a column and ``flipud`` of a row return it unchanged. A matrix +is ``np.fliplr``/``np.flipud``; ``flip`` works along the first non-singleton +dimension (any vector, the rows of a matrix: ``np.flip(A, axis=0)``) or the +dimension given. A vector of unknown orientation is declined for ``fliplr`` +and ``flipud``. A string is reversed with ``s[::-1]``. NumPy's flips are +views, so the result is copied when it or its input is later written into. + +From Python, ``np.flip`` of a 1-D array is ``flip`` of the row; of a 2-D +array it needs an axis (without one it reverses both). ``np.flipud`` of a +1-D array reverses it, which on the ``.m`` side (a row) is ``fliplr``. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Info, Kind +from dualect.lift import LiftContext, view_root +from dualect.pyinfer import PyInfo, as_array + +#: The dimension each function reverses (None: the first non-singleton one). +_DIM = {"fliplr": 2, "flipud": 1} + + +def _reversed(data: ir.Expr, info: Info, ctx: Context) -> ast.expr: + if info.kind is Kind.STRING: + step = ast.Slice(step=ast.UnaryOp(op=ast.USub(), operand=ast.Constant(1))) + return ast.Subscript(value=ctx.expr(data), slice=step) + return _private(ctx.call(ctx.np("flip"), ctx.arg(data)), data, ctx) + + +def _private(result: ast.expr, data: ir.Expr, ctx: Context) -> ast.expr: + """``result.copy()`` when the view NumPy returns could be written through. + + ``np.flip`` (and ``np.fliplr``/``np.flipud``) return views of their input; + the source's result is a separate array. + """ + stmt = ctx.current + target = stmt.targets[0] if isinstance(stmt, ir.Assign) and len(stmt.targets) == 1 else None + names = {data.id} if isinstance(data, ir.Name) else set() + if isinstance(target, ir.Name): + names.add(target.id) + if names & ctx.scope.mutated: + return ctx.method(result, "copy") + return result + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """One flip.""" + if not node.args or len(node.args) > (2 if node.func == "flip" else 1): + ctx.decline(f"{node.func} with these arguments") + data = node.args[0] + info = ctx.info(data) + dim = _DIM.get(node.func) + if len(node.args) == 2: + value = ctx.info(node.args[1]).value + if value not in (1, 2): + ctx.decline("flip along a computed or third dimension") + assert isinstance(value, int | float) + dim = int(value) + if info.is_scalar or info.kind is Kind.EMPTY: + return ctx.expr(data) # nothing to reverse + if info.is_matrix: + if dim is None: + result = ctx.call(ctx.np("flip"), ctx.expr(data), axis=ast.Constant(0)) + else: + result = ctx.call(ctx.np("fliplr" if dim == 2 else "flipud"), ctx.expr(data)) + return _private(result, data, ctx) + if info.kind in (Kind.ROW, Kind.STRING): + return _reversed(data, info, ctx) if dim in (None, 2) else ctx.expr(data) + if info.kind is Kind.COL: + return _reversed(data, info, ctx) if dim in (None, 1) else ctx.expr(data) + if info.kind is Kind.VECTOR and dim is None: + return _reversed(data, info, ctx) + ctx.decline(f"{node.func} of a value whose shape or orientation is unknown") + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The data's shape and type.""" + if not args: + return None + return replace(args[0], value=None, func=None, env=None) + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.flip(x, axis=...)``, ``np.fliplr(A)``, ``np.flipud(x)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + name = (ctx.tag(node) or "").removeprefix("py:call:np.") + if not node.args or len(node.args) > (2 if name == "flip" else 1): + ctx.decline(f"np.{name} with these arguments") + axis_node = node.args[1] if len(node.args) > 1 else None + for keyword in node.keywords: + if keyword.arg != "axis" or name != "flip": + ctx.decline(f"np.{name} with {keyword.arg}=") + axis_node = keyword.value + axis = ctx.info(axis_node).value if axis_node is not None else None + if axis_node is not None and not isinstance(axis, int): + ctx.decline("np.flip along a computed axis") + data = node.args[0] + root = view_root(data) + if root is not None and root in ctx.scope.mutated: + # The flipped array is a view: a later write into the original shows + # through it in NumPy, never on the .m side. + ctx.decline(f"np.{name} of {root}, which is written into (NumPy returns a view)") + info = ctx.info(data) + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + if info.is_vector or isinstance(data, ast.List): + if name == "fliplr": + ctx.decline("np.fliplr of a 1-D array (NumPy raises)") + if axis not in (None, 0, -1): + ctx.decline("np.flip of a 1-D array along axis 1") + return ctx.call("fliplr" if name == "flipud" else "flip", value, loc=loc) + if not info.is_matrix: + ctx.decline(f"np.{name} of a value whose dimensions are unknown") + if name == "flip": + if axis is None: + ctx.decline("np.flip of a 2-D array without an axis (it reverses both axes)") + name = "flipud" if axis in (0, -2) else "fliplr" + return ctx.call(name, value, loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """The data's facts; the result is a view of it.""" + if not args: + return None + data = as_array(args[0]) + if not data.is_array: + return None + return replace(data, value=None, view=True) diff --git a/rules/builtins/interp1/cases/basic.m b/rules/builtins/interp1/cases/basic.m new file mode 100644 index 0000000..0e520ae --- /dev/null +++ b/rules/builtins/interp1/cases/basic.m @@ -0,0 +1,9 @@ +% Query points come first in np.interp; outside the samples the result is NaN. +x = [0 1 2 4]; +y = [0 10 15 35]; +xi = [0.5 3 4]; +yi = interp1(x, y, xi); +outside = interp1(x, y, [-1 5]); % NaN NaN: no clamping +col = interp1(x, y, [1.5; 2.5], 'linear'); % the shape of the query points +t = 0:0.5:2; +v = interp1(t, t .^ 2, 1.25); diff --git a/rules/builtins/interp1/cases/basic.py b/rules/builtins/interp1/cases/basic.py new file mode 100644 index 0000000..9f8e075 --- /dev/null +++ b/rules/builtins/interp1/cases/basic.py @@ -0,0 +1,13 @@ +import numpy as np + +# Query points come first in np.interp; outside the samples the result is NaN. +x = np.array([0, 1, 2, 4]) +y = np.array([0, 10, 15, 35]) +xi = np.array([0.5, 3, 4]) +yi = np.interp(xi, x, y, left=np.nan, right=np.nan) +outside = np.interp([-1, 5], x, y, left=np.nan, right=np.nan) # NaN NaN: no clamping +col = np.interp( + np.array([1.5, 2.5]), x, y, left=np.nan, right=np.nan +) # the shape of the query points +t = np.linspace(0, 2, 5) +v = np.interp(1.25, t, t**2, left=np.nan, right=np.nan) diff --git a/rules/builtins/interp1/rule.yaml b/rules/builtins/interp1/rule.yaml new file mode 100644 index 0000000..dd20bcc --- /dev/null +++ b/rules/builtins/interp1/rule.yaml @@ -0,0 +1,33 @@ +id: builtins/interp1 +title: "`interp1`: linear interpolation (`np.interp`)" +status: mechanical +dialects: [octave, matlab] +match: [call:interp1] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.interp +octave: | + yi = interp1(x, y, xi); % NaN outside [x(1), x(end)] +python: | + yi = np.interp(xi, x, y, left=np.nan, right=np.nan) +why: > + Both interpolate linearly between samples and return the shape of the query + points. The argument order differs (`np.interp` takes the query points + first), and so do the edges: outside the sample range `interp1` returns NaN + while `np.interp` repeats the first or last value unless `left`/`right` say + otherwise. `np.interp` also requires increasing sample points; `interp1` + sorts them. +pitfalls: + - >- + `np.interp(xi, x, y)` clamps: a query beyond the last sample gets the last + value instead of NaN. Pass `left=np.nan, right=np.nan`. + - >- + Decreasing sample points give wrong values in `np.interp`, silently; + `interp1` accepts them. Sort first (`order = np.argsort(x)`). + - >- + `interp1(x, y, xi, 'spline')`, `'pchip'`, `'nearest'` and `'extrap'` have + no `np.interp` form: `scipy.interpolate` has them, and they are not + translated here. +related: [builtins/polyfit-polyval, builtins/linspace] +python_imports: [import numpy as np] diff --git a/rules/builtins/interp1/translate.py b/rules/builtins/interp1/translate.py new file mode 100644 index 0000000..3cc4ccf --- /dev/null +++ b/rules/builtins/interp1/translate.py @@ -0,0 +1,188 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/interp1: linear interpolation with ``np.interp``. + +``interp1(x, y, xi)`` (or with ``'linear'``) is ``np.interp(xi, x, y, +left=np.nan, right=np.nan)``: the query points come first in NumPy, and +outside ``[x(1), x(end)]`` the source returns NaN where ``np.interp`` would +repeat the end values. ``np.interp`` also needs increasing sample points +(the source sorts them; NumPy silently returns wrong values), so ``x`` that +is not a literal increasing vector, an increasing range or an increasing +``linspace`` is assumed increasing, out loud. Other methods, extrapolation +and a matrix of values are declined. + +From Python, ``np.interp(xi, x, y, left=np.nan, right=np.nan)`` is +``interp1(x, y, xi)``; plain ``np.interp`` clamps to the end values, which is +``interp1(x, y, min(max(xi, x(1)), x(end)))`` for NaN-free query points. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, as_array + + +def _assigned(node: ir.Name, ctx: Context) -> list[ir.Expr] | None: + """Every value a script variable is assigned, or ``None`` if it changes otherwise.""" + if not ctx.scope.is_script or node.id in ctx.scope.mutated: + return None + body = [s for s in ctx.scan.program.body if not isinstance(s, ir.FunctionDef)] + stmts = ir.walk_stmts(body) + if any(isinstance(s, ir.For) and s.var.id == node.id for s in stmts): + return None + if any(isinstance(s, ir.AugAssign) for s in stmts): + return None + values = [ + stmt.value + for stmt in stmts + if isinstance(stmt, ir.Assign) + and any(isinstance(t, ir.Name) and t.id == node.id for t in stmt.targets) + ] + if any( + isinstance(stmt, ir.Assign) + and len(stmt.targets) > 1 + and any(isinstance(t, ir.Name) and t.id == node.id for t in stmt.targets) + for stmt in stmts + ): + return None + return values or None + + +def _literal_values(node: ir.Expr, ctx: Context) -> bool: + """Sample points known to be a literal list of numbers (or a variable only ever one).""" + if isinstance(node, ir.Name): + values = _assigned(node, ctx) + return values is not None and all(_literal_values(v, ctx) for v in values) + return isinstance(node, ir.Matrix) and all( + isinstance(ctx.info(item).value, int | float) for row in node.rows for item in row + ) + + +def _increasing(node: ir.Expr, ctx: Context) -> bool: + """Whether sample points are known to be strictly increasing.""" + if isinstance(node, ir.Matrix): + values = [ctx.info(item).value for row in node.rows for item in row] + if all(isinstance(v, int | float) for v in values) and len(values) > 1: + return all(a < b for a, b in zip(values, values[1:], strict=False)) # type: ignore[operator] + return False + if isinstance(node, ir.Range): + step = ctx.info(node.step).value if node.step is not None else 1 + return isinstance(step, int | float) and step > 0 + if isinstance(node, ir.Call) and node.func == "linspace" and len(node.args) >= 2: + low, high = (ctx.info(a).value for a in node.args[:2]) + return isinstance(low, int | float) and isinstance(high, int | float) and low < high + if isinstance(node, ir.Name): + # A script variable only ever assigned increasing values (`t = 0:h:T`). + assigned = _assigned(node, ctx) + return assigned is not None and all(_increasing(v, ctx) for v in assigned) + return False + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``interp1(x, y, xi[, 'linear'])``.""" + args = node.args + if len(args) == 4: + method = args[3] + if not (isinstance(method, ir.Str) and method.value == "linear"): + ctx.decline("interp1 with a method other than linear, or with extrapolation") + elif len(args) != 3: + ctx.decline("interp1 with these arguments") + x, y, xi = args[:3] + for data in (x, y): + info = ctx.info(data) + if not info.is_vector or info.elem not in (Elem.REAL, Elem.LOGICAL): + ctx.decline("interp1 of sample points or values that are not a real vector") + query = ctx.info(xi) + if not (query.is_scalar or query.is_array) or not query.is_real: + ctx.decline("interp1 at query points that are not real numbers") + if not _increasing(x, ctx): + if _literal_values(x, ctx): + ctx.decline("interp1 with sample points that are not increasing (np.interp needs them)") + ctx.assume("increasing sample points (np.interp does not sort them)") + nan = ctx.np("nan") + return ctx.call( + ctx.np("interp"), ctx.arg(xi), ctx.arg(x), ctx.arg(y), left=nan, right=ctx.np("nan") + ) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The shape of the query points; NaN outside the samples.""" + if len(args) < 3: + return None + query = args[2] + if query.kind.value == "unknown": + return None + return replace( + query, + elem=Elem.REAL, + finite=False, + nonneg=False, + integer=False, + value=None, + func=None, + int_dtype=False, + ) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.interp(xi, x, y[, left=np.nan, right=np.nan])``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if len(node.args) != 3: + ctx.decline("np.interp with these arguments") + xi, x, y = node.args + bounds = {} + for keyword in node.keywords: + if keyword.arg not in ("left", "right") or ctx.tag(keyword.value) != "py:const:np.nan": + ctx.decline(f"np.interp with {keyword.arg}= other than np.nan") + bounds[keyword.arg] = keyword.value + for data in (x, y): + info = ctx.info(data) + if not (info.is_vector or isinstance(data, ast.List)) or info.dtype is DType.COMPLEX: + ctx.decline("np.interp of sample points or values that are not real 1-D arrays") + ctx.assume("increasing sample points (the .m interp1 would sort them)") + literals = ctx.module_for("syntax/array-literals") + points = literals.lift_items(x, ctx) + values = literals.lift_items(y, ctx) + query = literals.lift_items(xi, ctx) + if len(bounds) == 2: + return ctx.call("interp1", points, values, query, loc=loc) + if bounds: + ctx.decline("np.interp with only one of left= and right=") + # np.interp repeats the end values outside the samples: clamp the query. + if not isinstance(points, ir.Name): + ctx.decline("np.interp clamping with sample points that are not a variable") + finite = ( + all(ctx.info(item).finite for item in xi.elts) + if isinstance(xi, ast.List) + else ctx.info(xi).finite + ) + if not finite: + ctx.decline("np.interp of query points that may be NaN (the .m max skips NaN)") + first = ir.Index(loc=loc, target=points, args=[ctx.num(1)]) + last = ir.Index(loc=loc, target=points, args=[ir.End(loc=loc, target=points, dim=0, ndims=1)]) + clamped = ctx.call("min", ctx.call("max", query, first, loc=loc), last, loc=loc) + return ctx.call("interp1", points, values, clamped, loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """The shape of the query points, in floating point.""" + if not args: + return None + query = as_array(args[0]) + if not (query.is_scalar or query.is_array): + return None + clamped = not keywords + finite = clamped and all(a.finite for a in args[:3]) + return replace(query, dtype=DType.FLOAT, finite=finite, nonneg=False, value=None, view=False) diff --git a/rules/builtins/linear-algebra/cases/basic.m b/rules/builtins/linear-algebra/cases/basic.m new file mode 100644 index 0000000..1ede1b4 --- /dev/null +++ b/rules/builtins/linear-algebra/cases/basic.m @@ -0,0 +1,11 @@ +% Square matrices: the same LAPACK computations under NumPy names. +A = [4 7; 2 6]; +B = inv(A); +d = det(A); % 10 +t = trace(A); % 10 +S = [1 2; 2 4]; % singular: the second row is twice the first +r = rank(S); % 1 +r_full = rank(A); % 2 +r_tol = rank([1 0; 0 1e-8], 1e-6); % 1: the small singular value is below tol +W = [1 2 3; 4 5 6]; +r_wide = rank(W); % rank of a non-square matrix: 2 diff --git a/rules/builtins/linear-algebra/cases/basic.py b/rules/builtins/linear-algebra/cases/basic.py new file mode 100644 index 0000000..82da989 --- /dev/null +++ b/rules/builtins/linear-algebra/cases/basic.py @@ -0,0 +1,15 @@ +import numpy as np + +# Square matrices: the same LAPACK computations under NumPy names. +A = np.array([[4, 7], [2, 6]]) +B = np.linalg.inv(A) +d = np.linalg.det(A) # 10 +t = np.trace(A) # 10 +S = np.array([[1, 2], [2, 4]]) # singular: the second row is twice the first +r = np.linalg.matrix_rank(S) # 1 +r_full = np.linalg.matrix_rank(A) # 2 +r_tol = np.linalg.matrix_rank( + np.array([[1, 0], [0, 1e-8]]), 1e-6 +) # 1: the small singular value is below tol +W = np.array([[1, 2, 3], [4, 5, 6]]) +r_wide = np.linalg.matrix_rank(W) # rank of a non-square matrix: 2 diff --git a/rules/builtins/linear-algebra/rule.yaml b/rules/builtins/linear-algebra/rule.yaml new file mode 100644 index 0000000..78178eb --- /dev/null +++ b/rules/builtins/linear-algebra/rule.yaml @@ -0,0 +1,39 @@ +id: builtins/linear-algebra +title: "`inv`, `det`, `trace`, `rank`" +status: mechanical +dialects: [octave, matlab] +match: [call:inv, call:det, call:trace, call:rank] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.linalg.inv + - py:call:np.linalg.det + - py:call:np.trace + - py:call:np.linalg.matrix_rank +octave: | + B = inv(A); + d = det(A); + t = trace(A); + r = rank(A); +python: | + B = np.linalg.inv(A) + d = np.linalg.det(A) + t = np.trace(A) + r = np.linalg.matrix_rank(A) +why: > + These are the same LAPACK-based computations under NumPy names: `inv` is + `np.linalg.inv`, `det` `np.linalg.det`, `trace` `np.trace` and `rank` + `np.linalg.matrix_rank`, which uses the same default tolerance + (`max(size(A)) * eps` times the largest singular value). Solving a system + is still `A \ b` / `np.linalg.solve`, never `inv(A) * b`. +pitfalls: + - >- + A singular matrix: `inv` warns and returns Inf in the source, while + `np.linalg.inv` raises `LinAlgError`. + - >- + `det` of a near-singular matrix is tiny but rarely exactly 0 on either + side; test the rank or the condition number instead. + - >- + `np.trace` of a non-square matrix sums the main diagonal; `trace` raises. +related: [operators/division, builtins/norm] +python_imports: [import numpy as np] diff --git a/rules/builtins/linear-algebra/translate.py b/rules/builtins/linear-algebra/translate.py new file mode 100644 index 0000000..88a8d8b --- /dev/null +++ b/rules/builtins/linear-algebra/translate.py @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/linear-algebra: ``inv``, ``det``, ``trace``, ``rank``. + +Each is the NumPy function of the same meaning on a square (``rank``: any) +matrix: ``np.linalg.inv``, ``np.linalg.det``, ``np.trace`` and +``np.linalg.matrix_rank``. ``rank`` uses the same default tolerance on both +sides (``max(size(A)) * eps`` times the largest singular value), and +``rank(A, tol)`` is ``matrix_rank(A, tol)``. A singular matrix makes ``inv`` +warn and return ``Inf`` in the source but raise ``LinAlgError`` in NumPy, +which fails loudly. Values not known to be matrices are declined: ``inv`` and +``det`` of a scalar would be ``1 / x`` and ``x``, but NumPy's functions need +2-D input. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind +from dualect.pyinfer import array as py_array +from dualect.pyinfer import scalar as py_scalar + +_NUMPY = {"inv": "linalg.inv", "det": "linalg.det", "trace": "trace", "rank": "linalg.matrix_rank"} +_TO_M = { + "np.linalg.inv": "inv", + "np.linalg.det": "det", + "np.trace": "trace", + "np.linalg.matrix_rank": "rank", +} + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A matrix for ``inv``, a scalar for the rest.""" + if not args or node.func not in _NUMPY: + return None + a = args[0] + if node.func == "inv": + return array(a.rows, a.cols, elem=a.elem, kind=Kind.MATRIX if a.is_matrix else None) + if node.func == "rank": + return replace(scalar(nonneg=True, integer=True), int_dtype=True) + result = scalar(elem=a.elem if a.elem is not Elem.CHAR else Elem.UNKNOWN, finite=False) + # np.trace of an integer matrix is an integer; det is always a float. + return replace(result, int_dtype=node.func == "trace" and a.int_dtype) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``inv(A)``, ``det(A)``, ``trace(A)``, ``rank(A[, tol])``.""" + limit = 2 if node.func == "rank" else 1 + if not 1 <= len(node.args) <= limit: + ctx.decline(f"{node.func} with these arguments") + info = ctx.info(node.args[0]) + if not info.is_matrix: + ctx.decline(f"{node.func} of a value not known to be a matrix") + square = info.rows is None or info.cols is None or info.rows == info.cols + if not square and node.func != "rank": + ctx.decline(f"{node.func} of a matrix that is not square") + args = [ctx.expr(arg) for arg in node.args] + return ctx.call(ctx.np(_NUMPY[node.func]), *args) + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.linalg.inv/det/matrix_rank`` and ``np.trace`` of a 2-D array.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + name = (ctx.tag(node) or "").removeprefix("py:call:") + func = _TO_M.get(name) + limit = 2 if func == "rank" else 1 + if func is None or node.keywords or not 1 <= len(node.args) <= limit: + ctx.decline(f"{name} with these arguments") + if not ctx.info(node.args[0]).is_matrix: + ctx.decline(f"{name} of a value not known to be 2-D") + args = [ctx.expr(arg) for arg in node.args] + return ctx.call(func, *args, loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """A 2-D array for ``inv``; a scalar otherwise.""" + name = tag.removeprefix("py:call:") + if name not in _TO_M or not args: + return None + a = args[0] + if name == "np.linalg.inv": + return py_array(PyKind.MATRIX, DType.COMPLEX if a.dtype is DType.COMPLEX else DType.FLOAT) + if name == "np.linalg.matrix_rank": + return py_scalar(DType.INT, nonneg=True) + if name == "np.trace": + return py_scalar(a.dtype, finite=a.finite) + return py_scalar(DType.COMPLEX if a.dtype is DType.COMPLEX else DType.FLOAT, finite=False) diff --git a/rules/builtins/median/cases/basic.m b/rules/builtins/median/cases/basic.m new file mode 100644 index 0000000..ee7799e --- /dev/null +++ b/rules/builtins/median/cases/basic.m @@ -0,0 +1,8 @@ +% The middle value; an even count averages the two middle ones. +x = [7 1 3 10]; +m = median(x); % 5: (3 + 7) / 2 +odd = median([5 2 9]); % 5 +A = [1 8; 4 2; 9 3]; +col_m = median(A); % down each column: 4 3 +row_m = median(A, 2); % 4.5 3 6 +with_nan = median([1 NaN 3]); diff --git a/rules/builtins/median/cases/basic.py b/rules/builtins/median/cases/basic.py new file mode 100644 index 0000000..2984d9a --- /dev/null +++ b/rules/builtins/median/cases/basic.py @@ -0,0 +1,10 @@ +import numpy as np + +# The middle value; an even count averages the two middle ones. +x = np.array([7, 1, 3, 10]) +m = np.median(x) # 5: (3 + 7) / 2 +odd = np.median([5, 2, 9]) # 5 +A = np.array([[1, 8], [4, 2], [9, 3]]) +col_m = np.median(A, axis=0) # down each column: 4 3 +row_m = np.median(A, axis=1) # 4.5 3 6 +with_nan = np.median([1, np.nan, 3]) diff --git a/rules/builtins/median/rule.yaml b/rules/builtins/median/rule.yaml new file mode 100644 index 0000000..ed9e501 --- /dev/null +++ b/rules/builtins/median/rule.yaml @@ -0,0 +1,36 @@ +id: builtins/median +title: "`median`: middle value, down the columns of a matrix" +status: mechanical +dialects: [octave, matlab] +match: [call:median] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.median +octave: | + m = median(x); + col_m = median(A); % down each column + row_m = median(A, 2); +python: | + m = np.median(x) + col_m = np.median(A, axis=0) + row_m = np.median(A, axis=1) +why: > + The median is the middle value of the sorted data, the mean of the two + middle values for an even count, in both languages. Like `sum`, `median` of + a matrix works down the columns (dimension 1, `axis=0`), where + `np.median(A)` without an axis takes the median of all elements. NumPy + arrays have no `.median()` method; it is a function. +pitfalls: + - >- + `np.median(A)` of a matrix is one number (all elements); `median(A)` is a + row of column medians. + - >- + An even count averages the two middle values, so the median of integers + may be a fraction (`median([1 2 3 4])` is 2.5). + - >- + NaN anywhere makes the result NaN in both. An empty input gave NaN in old + Octave versions and still does, but with warnings and version-dependent + shapes; it is not translated. +related: [builtins/std-var, builtins/sum-mean-max] +python_imports: [import numpy as np] diff --git a/rules/builtins/median/translate.py b/rules/builtins/median/translate.py new file mode 100644 index 0000000..2f4473b --- /dev/null +++ b/rules/builtins/median/translate.py @@ -0,0 +1,109 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/median: ``np.median``. + +A vector reduces to a scalar, a matrix down its columns (``axis=0``) unless a +dimension is given. Both sides average the two middle values of an even +count and return NaN when the data holds one. An empty input is declined: +its result changed between Octave versions. From Python, ``np.median`` of a +1-D array is ``median(x)``, of a 2-D array without an axis ``median(A(:))``. +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``median(x)`` or ``median(x, dim)``.""" + if len(node.args) not in (1, 2): + ctx.decline("median with these arguments") + data = ctx.info(node.args[0]) + if data.elem is not Elem.REAL: + # Logical input: Octave keeps the class (or rejects it) where NumPy computes numbers. + ctx.decline("median of logical, complex or unknown values") + dim = None + if len(node.args) == 2: + value = ctx.info(node.args[1]).value + if not isinstance(value, int | float) or not float(value).is_integer(): + ctx.decline("median along a computed dimension") + dim = int(value) + expr = ctx.arg(node.args[0]) + if data.is_scalar and dim is None: + return ctx.call(ctx.np("median"), expr) + axis, _count = ctx.module("builtins/std-var").reduce_axis(node, data, dim, ctx) + if axis is None: + return ctx.call(ctx.np("median"), expr) + return ctx.call(ctx.np("median"), expr, axis=ast.Constant(axis)) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A scalar for a vector, a row (or a column, for dimension 2) for a matrix.""" + if not args: + return None + first = args[0] + dim = args[1].value if len(args) > 1 else None + facts = {"finite": first.finite, "nonneg": first.nonneg} + if first.is_vector or first.is_scalar: + return scalar(**facts) # type: ignore[arg-type] + if first.is_matrix: + if dim in (None, 1): + return array(1, first.cols, kind=Kind.ROW, **facts) # type: ignore[arg-type] + if dim == 2: + return array(first.rows, 1, kind=Kind.COL, **facts) # type: ignore[arg-type] + return None + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.median(x[, axis])``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if not node.args or len(node.args) > 2: + ctx.decline("np.median with these arguments") + data = node.args[0] + axis_node = node.args[1] if len(node.args) > 1 else None + for keyword in node.keywords: + if keyword.arg != "axis": + ctx.decline(f"np.median with {keyword.arg}=") + axis_node = keyword.value + axis = None if axis_node is None else ctx.info(axis_node).value + if axis is not None and axis not in (0, 1, -1, -2): + ctx.decline("np.median along a computed axis") + info = ctx.info(data) + if info.dtype in (DType.COMPLEX, DType.UNKNOWN) and not isinstance(data, ast.List): + ctx.decline("np.median of complex data or data of unknown type") + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + if info.is_scalar or info.is_vector or isinstance(data, ast.List): + if axis not in (None, 0, -1): + ctx.decline("np.median of a 1-D array along axis 1") + if info.length == 0: + ctx.decline("np.median of an empty array") + return ctx.call("median", value, loc=loc) + if not info.is_matrix: + ctx.decline("np.median of a value whose dimensions are unknown") + if axis is None: + return ctx.call("median", ir.Index(loc=loc, target=value, args=[ir.Colon(loc=loc)])) + dim = 1 if axis in (0, -2) else 2 + result = ctx.call("median", value, ctx.num(dim), loc=loc) + return result if dim == 1 else ctx.transpose(result) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """A scalar, or a 1-D array when a 2-D array is reduced along an axis.""" + data = as_array(args[0]) if args else None + if data is None or not (data.is_array or data.is_scalar): + return None + axis = keywords.get("axis") or (args[1] if len(args) > 1 else None) + kind = PyKind.VECTOR if axis is not None and data.is_matrix else PyKind.SCALAR + return PyInfo(kind=kind, dtype=DType.FLOAT, finite=data.finite, nonneg=data.nonneg) diff --git a/rules/builtins/meshgrid/cases/basic.m b/rules/builtins/meshgrid/cases/basic.m new file mode 100644 index 0000000..3db977a --- /dev/null +++ b/rules/builtins/meshgrid/cases/basic.m @@ -0,0 +1,7 @@ +% The grids are numel(y) x numel(x): X varies along rows, Y down columns. +x = [0 1 2]; +y = [10; 20]; +[X, Y] = meshgrid(x, y); % 2x3 each +Z = X + Y; +[P, Q] = meshgrid(1:4); % meshgrid(x) is meshgrid(x, x) +corner = X(2, 3); % x(3), from row 2 diff --git a/rules/builtins/meshgrid/cases/basic.py b/rules/builtins/meshgrid/cases/basic.py new file mode 100644 index 0000000..e43c567 --- /dev/null +++ b/rules/builtins/meshgrid/cases/basic.py @@ -0,0 +1,9 @@ +import numpy as np + +# The grids are numel(y) x numel(x): X varies along rows, Y down columns. +x = np.array([0, 1, 2]) +y = np.array([10, 20]) +X, Y = np.meshgrid(x, y) # 2x3 each +Z = X + Y +P, Q = np.meshgrid(np.arange(1, 5), np.arange(1, 5)) # meshgrid(x) is meshgrid(x, x) +corner = X[1, 2] # x(3), from row 2 diff --git a/rules/builtins/meshgrid/rule.yaml b/rules/builtins/meshgrid/rule.yaml new file mode 100644 index 0000000..493bb54 --- /dev/null +++ b/rules/builtins/meshgrid/rule.yaml @@ -0,0 +1,34 @@ +id: builtins/meshgrid +title: "`meshgrid`: coordinate grids" +status: mechanical +dialects: [octave, matlab] +match: [call:meshgrid] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.meshgrid +octave: | + [X, Y] = meshgrid(x, y); % numel(y) x numel(x) + Z = X.^2 + Y.^2; +python: | + X, Y = np.meshgrid(x, y) + Z = X**2 + Y**2 +why: > + `meshgrid(x, y)` returns two matrices with one row per element of `y` and + one column per element of `x`: `X` repeats `x` along each row, `Y` repeats + `y` down each column. `np.meshgrid` with its default `indexing="xy"` does + the same, so the result is the same shape and the same values. +pitfalls: + - >- + `np.meshgrid(x, y, indexing="ij")` (the `ndgrid` layout) returns the + transposes: `numel(x) x numel(y)`. Keep the default for `meshgrid`. + - >- + `meshgrid(x)` is `meshgrid(x, x)`, but `np.meshgrid(x)` returns a single + grid (a copy of `x`): pass the vector twice. + - >- + The grids are `numel(y) x numel(x)`, rows first: `X(i, j)` is `x(j)`. + - >- + A grid with one point along an axis is a row or column vector in the + source but a 2-D array in NumPy; it is not translated. +related: [builtins/repmat, operators/arithmetic] +python_imports: [import numpy as np] diff --git a/rules/builtins/meshgrid/translate.py b/rules/builtins/meshgrid/translate.py new file mode 100644 index 0000000..0d7c55d --- /dev/null +++ b/rules/builtins/meshgrid/translate.py @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/meshgrid: ``[X, Y] = meshgrid(x, y)``. + +``np.meshgrid`` with its default ``indexing="xy"`` builds the same grids +(given two vectors: ``np.meshgrid(x)`` returns one 1-D grid): +``X`` repeats ``x`` along each row and ``Y`` repeats ``y`` down each column, +both ``numel(y) x numel(x)``. ``meshgrid(x)`` is ``meshgrid(x, x)``. The +inputs must be vectors (a matrix is flattened in a different order on each +side); a grid with a single row or column would be 1-D on the ``.m`` side +and 2-D in NumPy, so a length known to be 1 is declined and an unknown one +assumed not to be, out loud. Three-dimensional grids are declined. + +From Python, ``X, Y = np.meshgrid(x, y)`` is ``[X, Y] = meshgrid(x, y)``; +``indexing="ij"`` (the transposed grids) is declined. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context, Line +from dualect.infer import Info, Kind, array +from dualect.lift import LiftContext +from dualect.pyinfer import PyInfo, PyKind +from dualect.pyinfer import array as py_array + + +def _grid(source: Info, rows: Info, cols: Info) -> Info: + # np.meshgrid keeps the dtype: integer inputs give integer grids, which + # element stores and powers must know about. + grid = array( + rows.numel, + cols.numel, + elem=source.elem, + finite=source.finite, + nonneg=source.nonneg, + integer=source.integer, + kind=Kind.MATRIX, + ) + return replace(grid, int_dtype=source.int_dtype) + + +def infer_outputs(node: ir.Call, args: list[Info], nargout: int) -> list[Info] | None: + """``X`` holds ``x`` and ``Y`` holds ``y``, both ``numel(y) x numel(x)``.""" + if node.func != "meshgrid" or len(args) not in (1, 2): + return None + x = args[0] + y = args[1] if len(args) == 2 else x + return [_grid(x, y, x), _grid(y, y, x)] + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The first output alone.""" + outputs = infer_outputs(node, args, nargout) + return outputs[0] if outputs else None + + +def _arguments(node: ir.Call, ctx: Context) -> list[ast.expr]: + if len(node.args) not in (1, 2): + ctx.decline("meshgrid with three inputs (a 3-D grid)") + for arg in node.args: + info = ctx.info(arg) + if not (info.is_vector or info.is_scalar): + ctx.decline("meshgrid of a value not known to be a vector") + if info.numel == 1 or info.is_scalar: + ctx.decline("meshgrid with a single point along an axis (a 1-D grid in the source)") + if info.numel is None: + ctx.assume("grid vectors longer than one element") + if len(node.args) == 1 and any( + isinstance(sub, ir.Call) and (sub.func in ("rand", "randn") or sub.local or sub.handle) + for sub in ir.walk_expr(node.args[0]) + ): + ctx.decline("meshgrid(x) of an expression that cannot be evaluated twice") + args = [ctx.arg(arg) for arg in node.args] + # np.meshgrid(x) returns a single 1-D grid; meshgrid(x) is meshgrid(x, x). + return args * 2 if len(args) == 1 else args + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``X = meshgrid(x, y)``: the first grid.""" + call = ctx.call(ctx.np("meshgrid"), *_arguments(node, ctx)) + return ast.Subscript(value=call, slice=ast.Constant(0)) + + +def translate_multi(stmt: ir.Assign, ctx: Context) -> list[Line]: + """``[X, Y] = meshgrid(x, y)``.""" + call = stmt.value + assert isinstance(call, ir.Call) + if len(stmt.targets) != 2: + ctx.decline("meshgrid with three outputs") + names = [] + for target in stmt.targets: + if isinstance(target, ir.Name): + names.append(target.id) + elif isinstance(target, ir.Ignore): + names.append("_") + else: + ctx.decline("assigning a grid into an element") + value = ctx.call(ctx.np("meshgrid"), *_arguments(call, ctx)) + return [ctx.line(f"{', '.join(names)} = {ast.unparse(value)}")] + + +# --- Python -> .m ------------------------------------------------------------ + + +def _lift_call(node: ast.Call, ctx: LiftContext) -> ir.Call: + for keyword in node.keywords: + value = keyword.value + if not (keyword.arg == "indexing" and isinstance(value, ast.Constant)): + ctx.decline(f"np.meshgrid with {keyword.arg}=") + if value.value != "xy": + ctx.decline('np.meshgrid with indexing="ij" (the transposed grids)') + if len(node.args) != 2: + ctx.decline("np.meshgrid of other than two vectors") + literals = ctx.module_for("syntax/array-literals") + for arg in node.args: + if not (ctx.info(arg).is_vector or isinstance(arg, ast.List)): + ctx.decline("np.meshgrid of a value not known to be 1-D") + args = [literals.lift_items(arg, ctx) for arg in node.args] + return ctx.call("meshgrid", *args, loc=ctx.loc(node)) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.meshgrid`` used as a value (a tuple of grids) is declined.""" + ctx.decline("np.meshgrid used other than unpacked into names") + + +def lift_multi(stmt: ast.Assign, ctx: LiftContext) -> list[ir.Stmt]: + """``X, Y = np.meshgrid(x, y)``.""" + target = stmt.targets[0] + value = stmt.value + assert isinstance(target, ast.Tuple | ast.List) and isinstance(value, ast.Call) + if len(target.elts) != 2 or len(value.args) != 2: + ctx.decline("unpacking a different number of grids than np.meshgrid returns") + targets: list[ir.Expr] = [] + for element in target.elts: + if not isinstance(element, ast.Name): + ctx.decline("unpacking a grid into an element") + if element.id == "_": + targets.append(ir.Ignore(loc=ctx.loc(element))) + else: + targets.append(ir.Name(loc=ctx.loc(element), id=element.id)) + return [ir.Assign(loc=ctx.loc(stmt), targets=targets, value=_lift_call(value, ctx))] + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.meshgrid``: a tuple of 2-D grids.""" + if tag != "py:call:np.meshgrid" or not args: + return None + grids = tuple(py_array(PyKind.MATRIX, a.dtype, finite=a.finite, nonneg=a.nonneg) for a in args) + return PyInfo(kind=PyKind.TUPLE, items=grids, length=len(grids)) diff --git a/rules/builtins/norm/cases/basic.m b/rules/builtins/norm/cases/basic.m new file mode 100644 index 0000000..e18b4a9 --- /dev/null +++ b/rules/builtins/norm/cases/basic.m @@ -0,0 +1,10 @@ +% Vector norms agree; the default matrix norm does not. +v = [3 -4 0]; +n2 = norm(v); % 5 +taxi = norm(v, 1); % 7 +peak = norm(v, Inf); % 4 +A = [1 2; 3 4]; +s = norm(A); % spectral norm (largest singular value) +f = norm(A, 'fro'); % NumPy's default for a matrix +c1 = norm(A, 1); % largest column sum +ri = norm(A, Inf); % largest row sum diff --git a/rules/builtins/norm/cases/basic.py b/rules/builtins/norm/cases/basic.py new file mode 100644 index 0000000..7637e4e --- /dev/null +++ b/rules/builtins/norm/cases/basic.py @@ -0,0 +1,12 @@ +import numpy as np + +# Vector norms agree; the default matrix norm does not. +v = np.array([3, -4, 0]) +n2 = np.linalg.norm(v) # 5 +taxi = np.linalg.norm(v, 1) # 7 +peak = np.linalg.norm(v, np.inf) # 4 +A = np.array([[1, 2], [3, 4]]) +s = np.linalg.norm(A, 2) # spectral norm (largest singular value) +f = np.linalg.norm(A) # NumPy's default for a matrix +c1 = np.linalg.norm(A, 1) # largest column sum +ri = np.linalg.norm(A, np.inf) # largest row sum diff --git a/rules/builtins/norm/rule.yaml b/rules/builtins/norm/rule.yaml new file mode 100644 index 0000000..450c019 --- /dev/null +++ b/rules/builtins/norm/rule.yaml @@ -0,0 +1,33 @@ +id: builtins/norm +title: "`norm`: vector and matrix norms" +status: mechanical +dialects: [octave, matlab] +match: [call:norm] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.linalg.norm +octave: | + n2 = norm(v); % Euclidean length + s = norm(A); % largest singular value + f = norm(A, 'fro'); +python: | + n2 = np.linalg.norm(v) + s = np.linalg.norm(A, 2) + f = np.linalg.norm(A) +why: > + For a vector both default to the Euclidean length, and `norm(v, p)` is + `np.linalg.norm(v, p)`. For a matrix the defaults differ: `norm(A)` is the + spectral norm (the largest singular value), but NumPy's default for a 2-D + array is the Frobenius norm, `norm(A, 'fro')`. Pass `2` to get the + spectral norm. The 1- and Inf-norms (largest column and row sums) agree. +pitfalls: + - >- + `np.linalg.norm(A)` of a matrix is the Frobenius norm, not `norm(A)`; + write `np.linalg.norm(A, 2)`. + - >- + `norm(v, Inf)` is the largest absolute value, `np.linalg.norm(v, np.inf)`. + - >- + A matrix p-norm other than 1, 2, Inf and Frobenius has no NumPy function. +related: [builtins/dot-cross-kron, builtins/linear-algebra] +python_imports: [import numpy as np] diff --git a/rules/builtins/norm/translate.py b/rules/builtins/norm/translate.py new file mode 100644 index 0000000..cf537b8 --- /dev/null +++ b/rules/builtins/norm/translate.py @@ -0,0 +1,146 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/norm: vector and matrix norms. + +``norm(v)`` of a vector is the Euclidean length, ``np.linalg.norm(v)``, and +``norm(v, p)`` the p-norm, ``np.linalg.norm(v, p)`` (``Inf`` is ``np.inf``; +``'fro'`` of a vector is its 2-norm). For a matrix the defaults differ: +``norm(A)`` is the *spectral* norm (largest singular value), +``np.linalg.norm(A, 2)``, while NumPy's default for a 2-D array is the +Frobenius norm, which is ``norm(A, 'fro')``. ``norm(A, 1)`` and ``norm(A, +Inf)`` are the largest column and row sums on both sides; other matrix +p-norms are declined (NumPy has none). + +From Python, ``np.linalg.norm(x[, ord])`` maps back the same way; ``axis=`` +and the nuclear norm are declined. +""" + +import ast +import math + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Info, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo +from dualect.pyinfer import scalar as py_scalar + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A non-negative real scalar.""" + if not args: + return None + return scalar(finite=args[0].finite, nonneg=True) + + +def _order(node: ir.Expr, ctx: Context) -> float | str: + if isinstance(node, ir.Str): + text = node.value.lower() + if text in ("fro", "inf", "-inf"): + return text + ctx.decline(f"norm with the option {node.value!r}") + value = ctx.info(node).value + if not isinstance(value, int | float) or isinstance(value, bool): + ctx.decline("norm with a computed order") + return float(value) + + +def _ord(value: float, ctx: Context) -> ast.expr: + if math.isinf(value): + return ctx.np("inf") if value > 0 else ast.UnaryOp(op=ast.USub(), operand=ctx.np("inf")) + return ctx.const(int(value) if value.is_integer() else value) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``norm(x)`` / ``norm(x, p)``.""" + if len(node.args) not in (1, 2): + ctx.decline("norm with these arguments") + info = ctx.info(node.args[0]) + order: float | str | None = _order(node.args[1], ctx) if len(node.args) == 2 else None + if order in ("inf", "-inf"): + order = math.inf if order == "inf" else -math.inf + func = ctx.np("linalg.norm") + x = ctx.arg(node.args[0]) + if info.is_vector or info.is_scalar: + if order is None or order == "fro" or order == 2: + return ctx.call(func, x) + assert isinstance(order, float) + if order <= 0 and not math.isinf(order): + ctx.decline("a vector norm of order 0 or below") + return ctx.call(func, x, _ord(order, ctx)) + if not info.is_matrix: + ctx.decline("norm of a value whose shape (vector or matrix) is unknown") + if order == "fro": + return ctx.call(func, x) + if order is None or order == 2: + return ctx.call(func, x, ast.Constant(2)) # the spectral norm, not NumPy's default + assert isinstance(order, float) + if order in (1, math.inf): + return ctx.call(func, x, _ord(order, ctx)) + ctx.decline("a matrix p-norm other than 1, 2, Inf and 'fro'") + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.linalg.norm(x[, ord])``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + args = list(node.args) + for keyword in node.keywords: + if keyword.arg != "ord" or len(args) != 1: + ctx.decline(f"np.linalg.norm with {keyword.arg}=") + args.append(keyword.value) + if len(args) not in (1, 2): + ctx.decline("np.linalg.norm with these arguments") + data = args[0] + info = ctx.info(data) + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + order_node = args[1] if len(args) == 2 else None + order: object = None + if order_node is not None: + if isinstance(order_node, ast.Constant) and order_node.value is None: + order_node = None + else: + order = ctx.info(order_node).value + if isinstance(order_node, ast.Constant) and isinstance(order_node.value, str): + order = order_node.value + if order is None: + ctx.decline("np.linalg.norm with a computed ord") + one_d = info.is_vector or isinstance(data, ast.List) + if not (one_d or info.is_matrix): + ctx.decline("np.linalg.norm of a value whose dimensions are unknown") + if order is None: + if one_d: + return ctx.call("norm", value, loc=loc) + return ctx.call("norm", value, ir.Str(loc=loc, value="fro", quote="'"), loc=loc) + if order == "fro" and not one_d: + return ctx.call("norm", value, ir.Str(loc=loc, value="fro", quote="'"), loc=loc) + if not isinstance(order, int | float) or isinstance(order, bool): + ctx.decline(f"np.linalg.norm with ord={order!r}") + if not one_d and order not in (1, 2, math.inf): + ctx.decline(f"a matrix norm with ord={order!r}") + if one_d and order <= 0 and not math.isinf(order): + ctx.decline("a vector norm of order 0 or below") + if order == 2: + return ctx.call("norm", value, loc=loc) + if math.isinf(order): + inf = ctx.call("Inf", loc=loc) + p = inf if order > 0 else ir.UnOp(loc=loc, op="uminus", operand=inf) + return ctx.call("norm", value, p, loc=loc) + return ctx.call("norm", value, ctx.num(order), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """A non-negative float.""" + if tag != "py:call:np.linalg.norm" or not args: + return None + return py_scalar(DType.FLOAT, finite=args[0].finite, nonneg=True) diff --git a/rules/builtins/num2str/cases/basic.m b/rules/builtins/num2str/cases/basic.m new file mode 100644 index 0000000..653810a --- /dev/null +++ b/rules/builtins/num2str/cases/basic.m @@ -0,0 +1,11 @@ +% Whole numbers print every digit; otherwise give a precision or a format. +n = 42; +label = ['n = ', num2str(n)]; +neg = num2str(-7); +big = num2str(123456789012); +flag = num2str(3 > 2); % '1', not 'True' +ratio = 1 / 3; +r = num2str(ratio, 4); % 0.3333 +p8 = num2str(pi, 8); % 3.1415927 +t = num2str(2.5, '%8.3f'); % trimmed: '2.500' +nz = num2str(-0); % '-0': the sign of zero is printed diff --git a/rules/builtins/num2str/cases/basic.py b/rules/builtins/num2str/cases/basic.py new file mode 100644 index 0000000..d27a9dd --- /dev/null +++ b/rules/builtins/num2str/cases/basic.py @@ -0,0 +1,13 @@ +import numpy as np + +# Whole numbers print every digit; otherwise give a precision or a format. +n = 42 +label = "n = " + f"{n:.0f}" +neg = f"{-7:.0f}" +big = f"{123456789012:.0f}" +flag = f"{3 > 2:.0f}" # '1', not 'True' +ratio = 1 / 3 +r = f"{ratio:.4g}" # 0.3333 +p8 = f"{np.pi:.8g}" # 3.1415927 +t = f"{2.5:8.3f}".strip() # trimmed: '2.500' +nz = f"{-0.0:.0f}" # '-0': the sign of zero is printed diff --git a/rules/builtins/num2str/rule.yaml b/rules/builtins/num2str/rule.yaml new file mode 100644 index 0000000..6041f5d --- /dev/null +++ b/rules/builtins/num2str/rule.yaml @@ -0,0 +1,42 @@ +id: builtins/num2str +title: "`num2str`: numbers as text" +status: mechanical +dialects: [octave, matlab] +match: [call:num2str] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:str + - py:method:strip + - py:call:int +octave: | + label = ['n = ', num2str(n)]; % a whole number: all digits + r = num2str(ratio, 4); % 4 significant digits + t = num2str(x, '%8.3f'); % a format, trimmed +python: | + label = "n = " + f"{n:.0f}" + r = f"{ratio:.4g}" + t = f"{x:8.3f}".strip() +why: > + `num2str` chooses a format from the value itself: a whole number prints + all its digits, anything else prints `max(floor(log10(|x|)) + 5, 5)` + significant digits (so `num2str(pi)` is `3.1416` but `num2str(123.456)` is + `123.456`). With a precision it is `%.g`; with a format it is + `sprintf` with the blanks around the result removed. Python's `str` of a + float is its shortest round-trip repr, which is none of these. +pitfalls: + - >- + `str(x)` of a float is not `num2str(x)`: `str(1/3)` is `0.3333333333333333` + but `num2str(1/3)` is `0.33333`. Give an explicit precision or format. + - >- + Whole numbers print every digit only below about 1e15; above that + `num2str` switches to exponent notation (`num2str(1e16)` is `1e+16`). + - >- + `num2str(x, '%8.3f')` trims the padding that `sprintf` would keep. + - >- + `num2str` of a logical prints `1`/`0`, not `True`/`False`. + - >- + `num2str(-0)` is `-0`: the sign of a negative zero is printed, which + `str(int(x))` would drop; `f"{x:.0f}"` keeps it. +related: [io/printf, types/char-strings] +python_imports: [] diff --git a/rules/builtins/num2str/translate.py b/rules/builtins/num2str/translate.py new file mode 100644 index 0000000..73b7b5b --- /dev/null +++ b/rules/builtins/num2str/translate.py @@ -0,0 +1,150 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/num2str: numbers as text. + +``num2str`` picks its format from the value: a whole number prints all its +digits (``f"{x:.0f}"``), any other number gets ``max(floor(log10(|x|)) + 5, +5)`` significant digits, which depends on the magnitude and so has no fixed +Python spelling: that form is declined. ``num2str(x, prec)`` is +``f"{x:.{prec}g}"`` and ``num2str(x, fmt)`` is the ``sprintf`` of ``fmt`` +(rule io/printf) with surrounding blanks trimmed. Whole numbers of 1e15 or +more switch to exponent notation in the source, so a value not known to be +smaller is assumed so, out loud. Arrays, which print as padded rows, are +declined. + +From Python, ``str(n)`` of an integer is ``num2str(n)`` (``str`` of a float +uses Python's shortest repr, which no ``num2str`` form reproduces), and +``s.strip()`` of a string is ``strtrim(s)``; ``int(x)`` truncates toward +zero, ``fix(x)``. +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind + +_LIMIT = 1e15 + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``num2str(x)``, ``num2str(x, prec)`` or ``num2str(x, fmt)``.""" + if len(node.args) not in (1, 2): + ctx.decline("num2str with these arguments") + info = ctx.info(node.args[0]) + if info.kind is Kind.STRING: + if len(node.args) == 2: + ctx.decline("num2str of a string with a format") + return ctx.expr(node.args[0]) # text passes through unchanged + if not info.is_scalar: + ctx.decline("num2str of an array (it prints padded rows)") + if info.elem not in (Elem.REAL, Elem.LOGICAL): + ctx.decline("num2str of a complex value or a value of unknown type") + value = info.value + if isinstance(value, int | float) and value != value or value in (float("inf"), -float("inf")): + ctx.decline("num2str of Inf or NaN") + if len(node.args) == 2: + spec = node.args[1] + if isinstance(spec, ir.Str): + if "\\n" in spec.value or "\n" in spec.value: + ctx.decline("num2str with a format that prints several rows") + printf = ctx.module("io/printf") + return ctx.method(printf.format_text(spec.value, [node.args[0]], ctx), "strip") + digits = ctx.info(spec).value + if not isinstance(digits, int | float) or not float(digits).is_integer() or digits < 0: + ctx.decline("num2str with a precision that is not a literal whole number") + if not info.finite: + ctx.assume("a finite value (Octave prints Inf/NaN, Python inf/nan)") + field = ast.FormattedValue( + value=ctx.expr(node.args[0]), + conversion=-1, + format_spec=ast.JoinedStr(values=[ast.Constant(f".{int(digits)}g")]), + ) + return ast.JoinedStr(values=[field]) + if not info.integer: + ctx.decline( + "num2str of a value not known to be a whole number " + "(its significant digits depend on the magnitude; give a precision)" + ) + if isinstance(value, int | float): + if abs(value) >= _LIMIT: + ctx.decline("num2str of a whole number of 1e15 or more (exponent notation)") + elif not info.is_logical: + ctx.assume("|value| < 1e15 in num2str (larger whole numbers print with an exponent)") + # f"{x:.0f}": every digit of a whole number, int or float, and the sign of + # a negative zero (`num2str(-0)` is '-0'; str(int(-0.0)) would lose it). + field = ast.FormattedValue( + value=ctx.expr(node.args[0]), + conversion=-1, + format_spec=ast.JoinedStr(values=[ast.Constant(".0f")]), + ) + return ast.JoinedStr(values=[field]) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A char row vector.""" + return Info(kind=Kind.STRING, rows=1, elem=Elem.CHAR) + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``str(n)`` of an integer, ``s.strip()`` of a string.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if node.keywords or len(node.args) > 1: + ctx.decline("str()/strip() with these arguments") + if isinstance(node.func, ast.Name) and node.func.id == "int": + # int(x) truncates toward zero, as fix(x) does (a double on the .m side). + if len(node.args) != 1: + ctx.decline("int() without one argument") + inner = ctx.info(node.args[0]) + if not inner.is_scalar or inner.dtype not in (DType.INT, DType.FLOAT, DType.BOOL): + ctx.decline("int() of a value that is not a real number") + return ctx.call("fix", ctx.expr(node.args[0]), loc=loc) + if isinstance(node.func, ast.Attribute): # s.strip() + if node.args or ctx.info(node.func.value).kind is not PyKind.STRING: + ctx.decline("strip() of a value that is not a string, or with characters") + return ctx.call("strtrim", ctx.expr(node.func.value), loc=loc) + if len(node.args) != 1: + ctx.decline("str() without an argument") + arg = node.args[0] + if isinstance(arg, ast.Call) and isinstance(arg.func, ast.Name) and arg.func.id == "int": + # str(int(x)): the digits of x truncated, which fix(x) gives num2str. + if len(arg.args) != 1 or arg.keywords: + ctx.decline("int() with these arguments") + inner = ctx.info(arg.args[0]) + if not inner.is_scalar or inner.dtype not in (DType.INT, DType.FLOAT, DType.BOOL): + ctx.decline("str(int(x)) of a value that is not a real number") + if inner.dtype is not DType.BOOL: + ctx.assume("|value| < 1e15 (num2str prints larger whole numbers with an exponent)") + value = ctx.expr(arg.args[0]) + if inner.dtype is DType.FLOAT: + value = ctx.call("fix", value, loc=loc) + return ctx.call("num2str", value, loc=loc) + info = ctx.info(arg) + if info.kind is PyKind.STRING: + return ctx.expr(arg) + if not info.is_scalar or info.dtype is not DType.INT: + ctx.decline("str() of a value that is not an integer (Python's repr has no .m form)") + ctx.assume("|value| < 1e15 (num2str prints larger whole numbers with an exponent)") + return ctx.call("num2str", ctx.expr(arg), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``str(...)`` and ``s.strip()`` are strings.""" + if tag == "py:call:str" or (receiver is not None and receiver.kind is PyKind.STRING): + return PyInfo(kind=PyKind.STRING) + if tag == "py:call:int" and len(args) == 1: + return PyInfo(kind=PyKind.SCALAR, dtype=DType.INT, finite=True, nonneg=args[0].nonneg) + return None diff --git a/rules/builtins/polyfit-polyval/cases/basic.m b/rules/builtins/polyfit-polyval/cases/basic.m new file mode 100644 index 0000000..6f22d2e --- /dev/null +++ b/rules/builtins/polyfit-polyval/cases/basic.m @@ -0,0 +1,8 @@ +% A least-squares quadratic; coefficients are listed highest power first. +x = [0 1 2 3 4 5]; +y = [1.1 2.9 9.2 19.1 32.8 51.2]; +p = polyfit(x, y, 2); +y_fit = polyval(p, x); +residual = max(abs(y - y_fit)); +line = polyfit(x, 3 * x - 2, 1); % exact: 3 -2 +at_half = polyval([2 0 -1], 0.5); % 2x^2 - 1 at 0.5: -0.5 diff --git a/rules/builtins/polyfit-polyval/cases/basic.py b/rules/builtins/polyfit-polyval/cases/basic.py new file mode 100644 index 0000000..b82c79e --- /dev/null +++ b/rules/builtins/polyfit-polyval/cases/basic.py @@ -0,0 +1,10 @@ +import numpy as np + +# A least-squares quadratic; coefficients are listed highest power first. +x = np.array([0, 1, 2, 3, 4, 5]) +y = np.array([1.1, 2.9, 9.2, 19.1, 32.8, 51.2]) +p = np.polyfit(x, y, 2) +y_fit = np.polyval(p, x) +residual = np.nanmax(np.abs(y - y_fit)) +line = np.polyfit(x, 3 * x - 2, 1) # exact: 3 -2 +at_half = np.polyval([2, 0, -1], 0.5) # 2x^2 - 1 at 0.5: -0.5 diff --git a/rules/builtins/polyfit-polyval/rule.yaml b/rules/builtins/polyfit-polyval/rule.yaml new file mode 100644 index 0000000..569918c --- /dev/null +++ b/rules/builtins/polyfit-polyval/rule.yaml @@ -0,0 +1,36 @@ +id: builtins/polyfit-polyval +title: "`polyfit` and `polyval`: polynomial fit and evaluation" +status: mechanical +dialects: [octave, matlab] +match: [call:polyfit, call:polyval] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.polyfit + - py:call:np.polyval +octave: | + p = polyfit(x, y, 2); % highest power first + y_fit = polyval(p, x); +python: | + p = np.polyfit(x, y, 2) + y_fit = np.polyval(p, x) +why: > + `np.polyfit` and `np.polyval` are the same least-squares fit and Horner + evaluation, with the same argument order and the same coefficient order: + highest power first, so `[2 0 -1]` is 2x^2 - 1. Octave solves the + least-squares problem with a QR factorisation and NumPy with an SVD, so the + coefficients agree to rounding, not bit for bit. +pitfalls: + - >- + The newer `np.polynomial.Polynomial` API stores coefficients lowest power + first (and `Polynomial.fit` rescales x): do not mix the two orders. + - >- + `[p, S] = polyfit(...)` and `[p, S, mu] = polyfit(...)` return an error + structure and a centring/scaling; NumPy returns covariance or residuals + in other forms (`cov=True`, `full=True`). Only the single output is + translated. + - >- + A high degree on raw x is badly conditioned in both languages; centre and + scale x, or use a lower degree. +related: [builtins/interp1, operators/division] +python_imports: [import numpy as np] diff --git a/rules/builtins/polyfit-polyval/translate.py b/rules/builtins/polyfit-polyval/translate.py new file mode 100644 index 0000000..9dfa496 --- /dev/null +++ b/rules/builtins/polyfit-polyval/translate.py @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/polyfit-polyval: ``np.polyfit`` and ``np.polyval``. + +Both keep the source's argument order and its coefficient order (highest +power first), so they map one to one. ``polyfit`` needs vectors and a literal +whole degree; its extra outputs (``[p, S, mu]``, the error estimate and the +centring) and ``polyval``'s matching arguments are declined, because NumPy +returns them in different forms. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, array +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def _degree(node: ir.Expr, ctx: Context) -> None: + value = ctx.info(node).value + if not isinstance(value, int | float) or not float(value).is_integer() or value < 0: + ctx.decline("polyfit with a degree that is not a literal whole number") + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``polyfit(x, y, n)`` or ``polyval(p, x)``.""" + if node.func == "polyfit": + if len(node.args) != 3: + ctx.decline("polyfit with these arguments") + x, y, degree = node.args + for data in (x, y): + info = ctx.info(data) + if not info.is_vector or not info.is_real: + ctx.decline("polyfit of data that is not a real vector") + _degree(degree, ctx) + return ctx.call(ctx.np("polyfit"), ctx.arg(x), ctx.arg(y), ctx.expr(degree)) + if len(node.args) != 2: + ctx.decline("polyval with an error structure or centring") + p, x = node.args + coefficients = ctx.info(p) + if not (coefficients.is_vector or coefficients.is_scalar): + ctx.decline("polyval with coefficients that are not a vector") + if not (ctx.info(x).is_scalar or ctx.info(x).is_array): + ctx.decline("polyval at points of unknown type") + return ctx.call(ctx.np("polyval"), ctx.arg(p), ctx.arg(x)) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """``polyfit``: a row of n + 1 coefficients; ``polyval``: the shape of the points.""" + if node.func == "polyfit" and len(args) == 3: + degree = args[2].value + count = int(degree) + 1 if isinstance(degree, int | float) else None + return array(1, count, elem=Elem.REAL) + if node.func == "polyval" and len(args) == 2: + x = args[1] + return replace( + x, elem=Elem.REAL, finite=False, nonneg=False, integer=False, value=None, func=None + ) + return None + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.polyfit(x, y, deg)`` or ``np.polyval(p, x)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + name = (ctx.tag(node) or "").removeprefix("py:call:np.") + if node.keywords: + ctx.decline(f"np.{name} with keyword arguments") + literals = ctx.module_for("syntax/array-literals") + if name == "polyfit": + if len(node.args) != 3: + ctx.decline("np.polyfit with these arguments") + x, y, degree = node.args + for data in (x, y): + info = ctx.info(data) + if not (info.is_vector or isinstance(data, ast.List)) or info.dtype is DType.COMPLEX: + ctx.decline("np.polyfit of data that is not a real 1-D array") + value = ctx.info(degree).value + if not isinstance(value, int) or isinstance(value, bool) or value < 0: + ctx.decline("np.polyfit with a degree that is not a literal whole number") + args = [literals.lift_items(x, ctx), literals.lift_items(y, ctx), ctx.expr(degree)] + return ctx.call("polyfit", *args, loc=loc) + if len(node.args) != 2: + ctx.decline("np.polyval with these arguments") + p, x = node.args + if not (ctx.info(p).is_vector or isinstance(p, ast.List)): + ctx.decline("np.polyval with coefficients that are not 1-D") + return ctx.call("polyval", *(literals.lift_items(a, ctx) for a in node.args), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """1-D coefficients from ``np.polyfit``; the points' shape from ``np.polyval``.""" + if tag == "py:call:np.polyfit" and len(args) == 3: + degree = args[2].value + length = degree + 1 if isinstance(degree, int) else None + return PyInfo(kind=PyKind.VECTOR, dtype=DType.FLOAT, length=length) + if tag == "py:call:np.polyval" and len(args) == 2: + x = as_array(args[1]) + if x.is_scalar or x.is_array: + return replace(x, dtype=DType.FLOAT, finite=False, nonneg=False, value=None) + return None diff --git a/rules/builtins/rand-randn/cases/basic.m b/rules/builtins/rand-randn/cases/basic.m new file mode 100644 index 0000000..ba2a75c --- /dev/null +++ b/rules/builtins/rand-randn/cases/basic.m @@ -0,0 +1,9 @@ +% Random values are compared by shape: rand(n) is square, 1xn or nx1 is 1-D. +U = rand(3, 2); +S = rand(3); % 3x3, not three numbers +z = randn(1, 5); +c = randn(4, 1); +u = rand; % one number +in_range = min(U(:)) >= 0 && max(U(:)) < 1; +m = mean(z); % computed from random numbers +% dualect: shape U S z c u m diff --git a/rules/builtins/rand-randn/cases/basic.py b/rules/builtins/rand-randn/cases/basic.py new file mode 100644 index 0000000..47f856e --- /dev/null +++ b/rules/builtins/rand-randn/cases/basic.py @@ -0,0 +1,11 @@ +import numpy as np + +# Random values are compared by shape: rand(n) is square, 1xn or nx1 is 1-D. +U = np.random.default_rng().random((3, 2)) +S = np.random.default_rng().random((3, 3)) # 3x3, not three numbers +z = np.random.default_rng().standard_normal(5) +c = np.random.default_rng().standard_normal(4) +u = np.random.default_rng().random() # one number +in_range = U.min() >= 0 and U.max() < 1 +m = z.mean() # computed from random numbers +# dualect: shape m diff --git a/rules/builtins/rand-randn/rule.yaml b/rules/builtins/rand-randn/rule.yaml new file mode 100644 index 0000000..03a9d31 --- /dev/null +++ b/rules/builtins/rand-randn/rule.yaml @@ -0,0 +1,42 @@ +id: builtins/rand-randn +title: "`rand` and `randn`: random numbers (compared by shape only)" +status: mechanical +dialects: [octave, matlab] +match: [call:rand, call:randn] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.random.default_rng + - py:method:random + - py:method:standard_normal + - py:call:np.random.rand + - py:call:np.random.randn +octave: | + U = rand(3, 2); % uniform on (0, 1) + z = randn(1, 5); % standard normal, a row +python: | + U = np.random.default_rng().random((3, 2)) + z = np.random.default_rng().standard_normal(5) +why: > + NumPy's Generator API draws uniform numbers with `random(size)` and normal + ones with `standard_normal(size)`, where `size` is a tuple `(m, n)` or a + count for 1-D (the legacy `np.random.rand(m, n)` is discouraged). In a real + program create one generator, `rng = np.random.default_rng()`, and reuse it; + the translation writes it inline so each call stays one expression. Neither + draws the source's numbers. Because the numbers differ, verification + compares a random result by shape only: the translation adds a + `dualect: shape ` directive for a variable assigned straight from + `rand`/`randn`. Anything computed from random numbers still differs and + fails verification, unless annotated the same way by hand. +pitfalls: + - >- + `rand(3)` is 3x3, while `rng.random(3)` is three numbers. + - >- + The two languages' generators and seeds are unrelated: `rand('seed', 1)` + and `np.random.default_rng(1)` give different numbers. Seeding is not + translated. + - >- + Values derived from random numbers (a mean, a sum) cannot be checked by + value; mark them `% dualect: shape name` (or `ignore`) to verify the rest. +related: [builtins/zeros-ones-eye] +python_imports: [import numpy as np] diff --git a/rules/builtins/rand-randn/translate.py b/rules/builtins/rand-randn/translate.py new file mode 100644 index 0000000..466748e --- /dev/null +++ b/rules/builtins/rand-randn/translate.py @@ -0,0 +1,197 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/rand-randn: uniform and normal random numbers. + +``rand(m, n)`` is ``np.random.default_rng().random((m, n))`` and +``randn(m, n)`` ``np.random.default_rng().standard_normal((m, n))``: NumPy's +Generator API (its legacy ``np.random.rand`` is discouraged, and flagged by +linters), kept as one expression so no generator object has to be threaded +through the code. ``rand(n)`` is square, ``rand(1, n)`` and ``rand(n, 1)`` +are 1-D, and ``rand`` alone a scalar. A size that may be 1 is assumed not to be, out loud. +Seeding and class arguments (``rand('seed', 1)``, ``'single'``) are declined. + +The two sides draw different numbers, so a random result can only be checked +for its shape: when a call is the whole right-hand side of an assignment to a +script variable, the translation adds a ``dualect: shape `` directive. +Values computed from random numbers are compared as usual and fail +verification, loudly, unless they are annotated the same way. +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind +from dualect.pyinfer import array as py_array +from dualect.pyinfer import scalar as py_scalar + + +def _dims(node: ir.Call) -> list[ir.Expr] | None: + args = node.args + if len(args) == 1 and isinstance(args[0], ir.Matrix): + rows = args[0].rows + return list(rows[0]) if len(rows) == 1 and len(rows[0]) == 2 else None + if len(args) == 1: + return [args[0], args[0]] + if len(args) in (0, 2): + return list(args) + return None + + +def _value(node: ir.Expr, info: Info | None) -> int | None: + if isinstance(node, ir.Num) and isinstance(node.value, int | float): + return int(node.value) if float(node.value).is_integer() else None + if info is not None and isinstance(info.value, int | float): + return int(info.value) if float(info.value).is_integer() else None + return None + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A scalar, a vector or a matrix of finite doubles.""" + dims = _dims(node) + if dims is None or any(i.kind is Kind.STRING for i in args): + return None + nonneg = node.func == "rand" + if not dims: + return scalar(nonneg=nonneg) + infos: list[Info | None] = [None, None] + if len(args) == 2: + infos = list(args) + elif args and not isinstance(node.args[0], ir.Matrix): + infos = [args[0], args[0]] + rows, cols = (_value(d, i) for d, i in zip(dims, infos, strict=True)) + if rows == 1 and cols == 1: + return scalar(nonneg=nonneg) + kind = None if 1 in (rows, cols) else Kind.MATRIX + return array(rows, cols, elem=Elem.REAL, kind=kind, finite=True, nonneg=nonneg) + + +def _shape_directive(node: ir.Call, ctx: Context) -> None: + current = ctx.current + if ( + ctx.scope.is_script + and isinstance(current, ir.Assign) + and current.value is node + and len(current.targets) == 1 + and isinstance(current.targets[0], ir.Name) + ): + ctx.file_directive(f"shape {current.targets[0].id}") + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``rand``/``randn`` with zero, one or two sizes.""" + if any(isinstance(arg, ir.Str) for arg in node.args): + ctx.decline(f"{node.func} with a seed, state or class argument") + dims = _dims(node) + if dims is None: + ctx.decline(f"{node.func} with more than two dimensions") + for dim in dims: + if not ctx.info(dim).is_scalar: + ctx.decline(f"{node.func} with a size that is not a number") + generator = ctx.call(ctx.np("random.default_rng")) + method = "random" if node.func == "rand" else "standard_normal" + _shape_directive(node, ctx) + if not dims: + return ctx.method(generator, method) + rows, cols = (_value(d, ctx.info(d)) for d in dims) + if rows == 1 and cols == 1: + return ctx.method(generator, method) + if rows == 1: + return ctx.method(generator, method, ctx.expr(dims[1])) + if cols == 1: + return ctx.method(generator, method, ctx.expr(dims[0])) + if rows is None or cols is None: + ctx.assume("neither dimension is 1") + size = ast.Tuple(elts=[ctx.expr(dims[0]), ctx.expr(dims[1])]) + return ctx.method(generator, method, size) + + +# --- Python -> .m ------------------------------------------------------------ + + +_METHODS = {"random": "rand", "standard_normal": "randn"} + + +def _is_generator(node: ast.expr, ctx: LiftContext) -> bool: + """``np.random.default_rng()`` with no seed.""" + return ( + isinstance(node, ast.Call) + and ctx.tag(node) == "py:call:np.random.default_rng" + and not node.args + and not node.keywords + ) + + +def _sizes(node: ast.Call, ctx: LiftContext) -> list[ast.expr]: + """The size arguments of a generator method: ``n`` or ``(m, n)``.""" + if node.keywords or len(node.args) > 1: + ctx.decline("a generator method with these arguments") + if not node.args: + return [] + size = node.args[0] + parts = list(size.elts) if isinstance(size, ast.Tuple | ast.List) else [size] + if len(parts) > 2: + ctx.decline("random numbers in more than two dimensions") + return parts + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.random.default_rng().random(size)`` and friends; the legacy functions.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + tag = ctx.tag(node) or "" + if tag == "py:call:np.random.default_rng": + ctx.decline("a random generator object (only its random/standard_normal draws)") + if tag.startswith("py:method:"): + assert isinstance(node.func, ast.Attribute) + if not _is_generator(node.func.value, ctx) or node.func.attr not in _METHODS: + ctx.decline(f"{node.func.attr} of a generator other than np.random.default_rng()") + func = _METHODS[node.func.attr] + sizes = _sizes(node, ctx) + else: + func = tag.removeprefix("py:call:np.random.") + if node.keywords or len(node.args) > 2: + ctx.decline(f"np.random.{func} with these arguments") + sizes = list(node.args) + for arg in sizes: + if not ctx.info(arg).is_scalar: + ctx.decline(f"{func} with a size that is not a number") + current = ctx.current + if ( + ctx.function is None + and isinstance(current, ast.Assign) + and current.value is node + and len(current.targets) == 1 + and isinstance(current.targets[0], ast.Name) + ): + ctx.file_directive(f"shape {current.targets[0].id}") + args = [ctx.expr(arg) for arg in sizes] + if len(args) == 1: + return ctx.call(func, ctx.num(1), args[0], loc=loc) # 1-D: a row + return ctx.call(func, *args, loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """No size: a float; one: 1-D; two: 2-D.""" + if tag in ("py:method:random", "py:method:standard_normal"): + if args and args[0].kind is PyKind.TUPLE: + args = list(args[0].items or ()) + nonneg = tag == "py:method:random" + elif tag in ("py:call:np.random.rand", "py:call:np.random.randn"): + nonneg = tag.endswith(".rand") + else: + return None + if not args: + return py_scalar(DType.FLOAT, nonneg=nonneg) + kind = PyKind.VECTOR if len(args) == 1 else PyKind.MATRIX + length = args[0].value if len(args) == 1 and isinstance(args[0].value, int) else None + return py_array(kind, DType.FLOAT, finite=True, nonneg=nonneg, length=length) diff --git a/rules/builtins/repmat/cases/basic.m b/rules/builtins/repmat/cases/basic.m new file mode 100644 index 0000000..5221c95 --- /dev/null +++ b/rules/builtins/repmat/cases/basic.m @@ -0,0 +1,12 @@ +% Matrices, rows and columns tile differently in NumPy. +A = [1 2; 3 4]; +T = repmat(A, 2, 3); % 4x6 +S = repmat(A, 2); % 2x2 copies: 4x4 +v = [1 2 3]; +w = repmat(v, 1, 3); % a longer row +V = repmat(v, 2, 1); % two rows: a matrix +c = [5; 6]; +d = repmat(c, 3, 1); % a longer column +W = repmat(c, [1 3]); % three columns side by side +z = repmat(7, 1, 4); % a scalar +E = repmat(A, 0, 2); % zero copies: empty diff --git a/rules/builtins/repmat/cases/basic.py b/rules/builtins/repmat/cases/basic.py new file mode 100644 index 0000000..aa7d399 --- /dev/null +++ b/rules/builtins/repmat/cases/basic.py @@ -0,0 +1,14 @@ +import numpy as np + +# Matrices, rows and columns tile differently in NumPy. +A = np.array([[1, 2], [3, 4]]) +T = np.tile(A, (2, 3)) # 4x6 +S = np.tile(A, (2, 2)) # 2x2 copies: 4x4 +v = np.array([1, 2, 3]) +w = np.tile(v, 3) # a longer row +V = np.tile(v, (2, 1)) # two rows: a matrix +c = np.array([5, 6]) +d = np.tile(c, 3) # a longer column +W = np.tile(c[:, np.newaxis], (1, 3)) # three columns side by side +z = np.tile(7, 4) # a scalar +E = np.tile(A, (0, 2)) # zero copies: empty diff --git a/rules/builtins/repmat/rule.yaml b/rules/builtins/repmat/rule.yaml new file mode 100644 index 0000000..6627420 --- /dev/null +++ b/rules/builtins/repmat/rule.yaml @@ -0,0 +1,33 @@ +id: builtins/repmat +title: "`repmat`: tiling rows, columns and matrices" +status: mechanical +dialects: [octave, matlab] +match: [call:repmat] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.tile +octave: | + T = repmat(A, 2, 3); % 2 x 3 copies of A + w = repmat(v, 1, 3); % a row three times as long + W = repmat(c, 1, 3); % three copies of a column, side by side +python: | + T = np.tile(A, (2, 3)) + w = np.tile(v, 3) + W = np.tile(c[:, np.newaxis], (1, 3)) +why: > + `repmat(A, m, n)` tiles `A` m times down and n times across, which is + `np.tile(A, (m, n))` for a matrix. Vectors need care because NumPy's 1-D + arrays have no orientation and `np.tile` treats them as rows: a column + repeated sideways must first get its column axis (`c[:, np.newaxis]`), and a + row repeated across stays 1-D only with a single count, `np.tile(v, n)`. +pitfalls: + - >- + `np.tile(c, (1, 3))` of a 1-D column gives one long row, not a 3-column + matrix: NumPy reads a 1-D array as a row. + - >- + `repmat(A, n)` is n x n copies, not n copies side by side. + - >- + A count of 0 gives an empty result on both sides. +related: [builtins/concatenation-functions, builtins/meshgrid] +python_imports: [import numpy as np] diff --git a/rules/builtins/repmat/translate.py b/rules/builtins/repmat/translate.py new file mode 100644 index 0000000..bcf8a36 --- /dev/null +++ b/rules/builtins/repmat/translate.py @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/repmat: ``repmat`` is ``np.tile`` with care for 1-D. + +``repmat(A, m, n)`` (or ``repmat(A, [m n])``; ``repmat(A, n)`` is ``n x n`` +copies) is ``np.tile(A, (m, n))`` for a matrix or a scalar. A row (1-D) repeated +sideways only stays a row: ``np.tile(v, n)``; stacked (``m > 1``) it becomes +a matrix, ``np.tile(v, (m, n))``. A column (also 1-D) repeated downwards stays +a column, ``np.tile(c, m)``, and sideways needs its column axis first, +``np.tile(c[:, np.newaxis], (m, n))``, because NumPy reads a 1-D array as a +row. A count that might be 1 is assumed not to be, +out loud, where that would change the result's dimensions. + +From Python, ``np.tile(A, k)`` repeats along the last axis: ``repmat(A, 1, +k)``; ``np.tile(A, (m, n))`` is ``repmat(A, m, n)`` (a 1-D array is a row on +both sides). +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Info, Kind, array +from dualect.lift import LiftContext +from dualect.pyinfer import PyInfo, PyKind +from dualect.pyinfer import array as py_array + + +def _counts(node: ir.Call) -> list[ir.Expr] | None: + """The repeat counts ``[m, n]``.""" + args = node.args[1:] + if len(args) == 2: + return list(args) + if len(args) == 1: + arg = args[0] + if isinstance(arg, ir.Matrix) and len(arg.rows) == 1 and len(arg.rows[0]) == 2: + return list(arg.rows[0]) + if not isinstance(arg, ir.Matrix): + return [arg, arg] + return None + + +def _value(node: ir.Expr, info: Info | None) -> int | None: + if isinstance(node, ir.Num) and isinstance(node.value, int | float): + return int(node.value) if float(node.value).is_integer() else None + value = info.value if info is not None else None + if isinstance(value, int | float) and float(value).is_integer(): + return int(value) + return None + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The tiled dimensions.""" + if node.func != "repmat" or not args: + return None + counts = _counts(node) + if counts is None: + return None + data = args[0] + infos = args[1:] if len(args) == 3 else [args[1], args[1]] if len(node.args) == 2 else [] + m, n = (_value(c, infos[k] if k < len(infos) else None) for k, c in enumerate(counts)) + rows = data.rows * m if data.rows is not None and m is not None else None + cols = data.cols * n if data.cols is not None and n is not None else None + kind = None + if data.kind is Kind.ROW and m == 1: + kind = Kind.ROW + elif data.kind is Kind.COL and n == 1: + kind = Kind.COL + elif rows != 1 and cols != 1 and not (data.is_scalar and 1 in (m, n)): + kind = Kind.MATRIX # translated as 2-D (a count of 1 is assumed out) + result = array( + rows, + cols, + elem=data.elem, + finite=data.finite, + nonneg=data.nonneg, + integer=data.integer, + kind=kind, + ) + return replace(result, int_dtype=data.int_dtype) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``repmat(A, m, n)``.""" + counts = _counts(node) + if counts is None: + ctx.decline("repmat with these arguments") + data_node = node.args[0] + data = ctx.info(data_node) + m_node, n_node = counts + m, n = (_value(c, ctx.info(c)) for c in counts) + m_expr, n_expr = ctx.expr(m_node), ctx.expr(n_node) + both = ast.Tuple(elts=[m_expr, n_expr]) + if data.kind is Kind.STRING: + ctx.decline("repmat of a string") + expr = ctx.expr(data_node) + if data.is_scalar: + if m == 1: + return ctx.call(ctx.np("tile"), expr, n_expr) + if n == 1: + return ctx.call(ctx.np("tile"), expr, m_expr) + if m is None or n is None: + ctx.assume("neither count is 1") + return ctx.call(ctx.np("tile"), expr, both) + if data.is_matrix: + return ctx.call(ctx.np("tile"), expr, both) + if data.kind is Kind.ROW: + if m == 1: + return ctx.call(ctx.np("tile"), expr, n_expr) + if m is None: + ctx.assume("the row is stacked more than once (m is not 1)") + return ctx.call(ctx.np("tile"), expr, both) + if data.kind is Kind.COL: + if n == 1: + return ctx.call(ctx.np("tile"), expr, m_expr) + if n is None: + ctx.assume("the column is repeated sideways (n is not 1)") + column = ast.Subscript(value=expr, slice=ast.Tuple(elts=[ast.Slice(), ctx.np("newaxis")])) + return ctx.call(ctx.np("tile"), column, both) + ctx.decline("repmat of a value whose shape (row, column or matrix) is unknown") + + +# --- Python -> .m ------------------------------------------------------------ + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.tile(A, reps)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if len(node.args) != 2 or node.keywords: + ctx.decline("np.tile with these arguments") + data, reps = node.args + info = ctx.info(data) + if not (info.is_vector or info.is_matrix or info.is_scalar or isinstance(data, ast.List)): + ctx.decline("np.tile of a value whose dimensions are unknown") + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + parts = list(reps.elts) if isinstance(reps, ast.Tuple | ast.List) else [reps] + if not all(ctx.info(p).is_scalar for p in parts) or len(parts) not in (1, 2): + ctx.decline("np.tile to more than two dimensions") + if len(parts) == 1: + return ctx.call("repmat", value, ctx.num(1), ctx.expr(parts[0]), loc=loc) + return ctx.call("repmat", value, ctx.expr(parts[0]), ctx.expr(parts[1]), loc=loc) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.tile``: 2-D for two counts or a 2-D input, else 1-D.""" + if tag != "py:call:np.tile" or len(args) != 2: + return None + data, reps = args + two = reps.kind in (PyKind.TUPLE, PyKind.LIST) and reps.length == 2 + kind = PyKind.MATRIX if two or data.is_matrix else PyKind.VECTOR + return py_array(kind, data.dtype, finite=data.finite, nonneg=data.nonneg) diff --git a/rules/builtins/reshape/cases/basic.m b/rules/builtins/reshape/cases/basic.m new file mode 100644 index 0000000..9a0b67a --- /dev/null +++ b/rules/builtins/reshape/cases/basic.m @@ -0,0 +1,8 @@ +% Elements are taken and placed column by column. +B = reshape(1:6, 2, 3); % [1 3 5; 2 4 6] +A = [1 2 3; 4 5 6]; +C = reshape(A, 3, 2); % [1 5; 4 3; 2 6] +D = reshape(A, [], 2); % the [] size is numel(A) / 2 +E = reshape(A, [3 2]); % the sizes as one vector +r = reshape(A, 1, []); % 1 4 2 5 3 6, a row +c = reshape(B, [], 1); % 1 2 3 4 5 6, a column diff --git a/rules/builtins/reshape/cases/basic.py b/rules/builtins/reshape/cases/basic.py new file mode 100644 index 0000000..e7d893c --- /dev/null +++ b/rules/builtins/reshape/cases/basic.py @@ -0,0 +1,10 @@ +import numpy as np + +# Elements are taken and placed column by column. +B = np.reshape(np.arange(1, 7), (2, 3), order="F") # [1 3 5; 2 4 6] +A = np.array([[1, 2, 3], [4, 5, 6]]) +C = np.reshape(A, (3, 2), order="F") # [1 5; 4 3; 2 6] +D = np.reshape(A, (-1, 2), order="F") # the [] size is numel(A) / 2 +E = np.reshape(A, (3, 2), order="F") # the sizes as one vector +r = A.ravel(order="F") # 1 4 2 5 3 6, a row +c = B.ravel(order="F") # 1 2 3 4 5 6, a column diff --git a/rules/builtins/reshape/cases/write-after.m b/rules/builtins/reshape/cases/write-after.m new file mode 100644 index 0000000..a9e9c2d --- /dev/null +++ b/rules/builtins/reshape/cases/write-after.m @@ -0,0 +1,5 @@ +% Writing into a reshaped array must not change the original. +v = 1:6; +M = reshape(v, 2, 3); +M(1, 1) = 100; +first = v(1); % still 1 diff --git a/rules/builtins/reshape/cases/write-after.py b/rules/builtins/reshape/cases/write-after.py new file mode 100644 index 0000000..03ed92a --- /dev/null +++ b/rules/builtins/reshape/cases/write-after.py @@ -0,0 +1,7 @@ +import numpy as np + +# Writing into a reshaped array must not change the original. +v = np.arange(1, 7) +M = np.reshape(v, (2, 3), order="F").copy() +M[0, 0] = 100 +first = v[0] # still 1 diff --git a/rules/builtins/reshape/rule.yaml b/rules/builtins/reshape/rule.yaml new file mode 100644 index 0000000..2a6c215 --- /dev/null +++ b/rules/builtins/reshape/rule.yaml @@ -0,0 +1,36 @@ +id: builtins/reshape +title: "`reshape`: column-major order" +status: mechanical +dialects: [octave, matlab] +match: [call:reshape] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.reshape +octave: | + B = reshape(1:6, 2, 3); % [1 3 5; 2 4 6] + C = reshape(A, [], 2); % [] is worked out from numel(A) + r = reshape(A, 1, []); % all elements as a row, column by column +python: | + B = np.reshape(np.arange(1, 7), (2, 3), order="F") + C = np.reshape(A, (-1, 2), order="F") + r = A.ravel(order="F") +why: > + `reshape` keeps the elements in memory order and only changes the + dimensions, and `.m` arrays are stored column by column: `reshape(1:6, 2, 3)` + fills the first column with 1 and 2. NumPy's reshape fills rows unless told + `order="F"`. `[]` for one size is NumPy's `-1`. A `1xN` or `Nx1` result is a + 1-D array, which `ravel(order="F")` gives. +pitfalls: + - >- + `np.reshape(x, (2, 3))` without `order="F"` fills row by row: `[[1, 2, 3], [4, 5, + 6]]` instead of `[[1, 3, 5], [2, 4, 6]]`. + - >- + `A.ravel()` reads a matrix row by row; `A(:)` and `reshape(A, 1, [])` read + it column by column: `ravel(order="F")`. + - >- + NumPy's reshape returns a view where it can: writing into the result + writes into the original array. The translation copies when either is + written later. +related: [indexing/colon-all, indexing/one-based] +python_imports: [import numpy as np] diff --git a/rules/builtins/reshape/translate.py b/rules/builtins/reshape/translate.py new file mode 100644 index 0000000..a8c4148 --- /dev/null +++ b/rules/builtins/reshape/translate.py @@ -0,0 +1,229 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/reshape: ``reshape`` fills column by column. + +``reshape(x, m, n)`` (or ``reshape(x, [m n])``, with ``[]`` for the size to +be worked out) is ``np.reshape(x, (m, n), order="F")``: the elements are read +and written in column-major order, NumPy's ``order="F"``. A ``1xN`` or ``Nx1`` +result is a 1-D array, ``x.ravel(order="F")`` (a vector reshaped into a vector +keeps its elements in order, so it is the vector itself). A size that may be +1 is assumed not to be, out loud, as for ``zeros``. NumPy's reshape may return +a view; when either side is later written in place the result is copied. + +From Python, ``np.reshape(x, shape, order="F")`` is ``reshape(x, m, n)``; the +default row-major order is the transpose of a column-major reshape of the +transpose: ``np.reshape(A, (m, n))`` is ``reshape(A.', n, m).'``. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Info, Kind, array +from dualect.lift import LiftContext +from dualect.pyinfer import PyInfo, PyKind +from dualect.pyinfer import array as py_array + + +def _dims(node: ir.Call) -> list[ir.Expr] | None: + """The size arguments: two scalars, or one ``[m n]`` literal.""" + args = node.args[1:] + if len(args) == 2: + return list(args) + if len(args) == 1 and isinstance(args[0], ir.Matrix) and len(args[0].rows) == 1: + row = args[0].rows[0] + return list(row) if len(row) == 2 else None + return None + + +def _is_placeholder(node: ir.Expr) -> bool: + return isinstance(node, ir.Matrix) and not node.rows + + +def _known(node: ir.Expr, info: Info) -> int | None: + value = info.value + if isinstance(value, int | float) and float(value).is_integer(): + return int(value) + return None + + +def _sizes(node: ir.Call, args: list[Info], data: Info) -> tuple[int | None, int | None] | None: + """``(rows, cols)`` of the result, ``None`` entries when unknown; ``None`` if malformed.""" + dims = _dims(node) + if dims is None: + return None + # Separate size arguments have facts; the items of a literal are read below. + infos = [args[1], args[2]] if len(node.args) == 3 else [Info(), Info()] + values: list[int | None] = [] + for dim, info in zip(dims, infos, strict=True): + if _is_placeholder(dim): + values.append(None) + continue + if isinstance(dim, ir.Num) and isinstance(dim.value, int | float): + values.append(int(dim.value) if float(dim.value).is_integer() else None) + else: + values.append(_known(dim, info)) + rows, cols = values + total = data.numel + if total is not None: + if _is_placeholder(dims[0]) and cols: + rows = total // cols + if _is_placeholder(dims[1]) and rows: + cols = total // rows + return rows, cols + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The result's dimensions, as far as they are known.""" + if node.func != "reshape" or not args: + return None + data = args[0] + sizes = _sizes(node, args, data) + if sizes is None: + return None + rows, cols = sizes + dims = _dims(node) or [] + kind = None + one = [d for d in dims if isinstance(d, ir.Num) and d.value == 1] + if not one and (rows != 1 and cols != 1): + kind = Kind.MATRIX # translated as 2-D (a size of 1 is assumed out) + result = array( + rows, + cols, + elem=data.elem, + finite=data.finite, + nonneg=data.nonneg, + integer=data.integer, + kind=kind, + ) + return replace(result, int_dtype=data.int_dtype) + + +def _target_mutated(node: ir.Call, ctx: Context) -> bool: + """Whether the result or the reshaped variable is written in place later.""" + names = set() + if isinstance(node.args[0], ir.Name): + names.add(node.args[0].id) + current = ctx.current + if isinstance(current, ir.Assign) and current.value is node: + names.update(t.id for t in current.targets if isinstance(t, ir.Name)) + return bool(names & ctx.scope.mutated) + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``reshape(x, m, n)`` / ``reshape(x, [m n])``.""" + dims = _dims(node) + if dims is None: + ctx.decline("reshape to other than two dimensions") + data_node = node.args[0] + data = ctx.info(data_node) + if not (data.is_array or data.is_scalar) or data.kind is Kind.STRING: + ctx.decline("reshape of a value that is not a known numeric array") + if all(_is_placeholder(d) for d in dims): + ctx.decline("reshape with two [] sizes") + values = [None if _is_placeholder(d) else ctx.info(d).value for d in dims] + expr = ctx.expr(data_node) + if 1 in values: + # A 1xN or Nx1 result is 1-D; read column by column. + if data.is_vector or data.is_scalar: + result = expr + elif data.is_matrix: + result = ctx.method(expr, "ravel", order=ast.Constant("F")) + else: + ctx.decline("reshape of a value whose shape is unknown") + else: + resolved = list(values) + total = data.numel + for k, other in ((0, 1), (1, 0)): + known = resolved[other] + if _is_placeholder(dims[k]) and total is not None and isinstance(known, int | float): + resolved[k] = total / known if known else None + if not all(isinstance(v, int | float) and v != 1 for v in resolved): + ctx.assume("neither dimension is 1") + sizes = [ctx.const(-1) if _is_placeholder(d) else ctx.expr(d) for d in dims] + if not (data.is_array or data.is_scalar) or data.kind is Kind.UNKNOWN: + ctx.decline("reshape of a value whose shape is unknown") + result = ctx.call(ctx.np("reshape"), expr, ast.Tuple(elts=sizes), order=ast.Constant("F")) + if _target_mutated(node, ctx) and not ( + isinstance(result, ast.Call) + and isinstance(result.func, ast.Attribute) + and result.func.attr == "copy" + ): + result = ctx.method(result, "copy") + return result + + +# --- Python -> .m ------------------------------------------------------------ + + +def _shape_parts(node: ast.expr, ctx: LiftContext) -> list[ast.expr] | None: + if isinstance(node, ast.Tuple | ast.List): + return list(node.elts) + if ctx.info(node).is_scalar: + return [node] + return None + + +def _dim(node: ast.expr, ctx: LiftContext) -> ir.Expr: + value = ctx.info(node).value + if value == -1: + return ir.Matrix(loc=ctx.loc(node), rows=[]) + if isinstance(value, int | float) and value < 0: + ctx.decline("a negative size") + if value is None: + ctx.assume("a size that is not -1") + return ctx.expr(node) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.reshape(x, shape[, order])``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + order = "C" + for keyword in node.keywords: + if keyword.arg != "order" or not isinstance(keyword.value, ast.Constant): + ctx.decline(f"np.reshape with {keyword.arg}=") + order = str(keyword.value.value) + if len(node.args) != 2 or order not in ("C", "F"): + ctx.decline("np.reshape with these arguments") + data, shape = node.args + info = ctx.info(data) + if not (info.is_vector or info.is_matrix): + ctx.decline("np.reshape of a value whose dimensions are unknown") + parts = _shape_parts(shape, ctx) + if parts is None or len(parts) not in (1, 2): + ctx.decline("np.reshape to other than one or two dimensions") + value = ctx.expr(data) + empty = ir.Matrix(loc=loc, rows=[]) + if len(parts) == 1: + # A 1-D result: a row on the .m side, read in the given order. + if ctx.info(parts[0]).value != -1: + ctx.assume("the size is the element count") + source = value if order == "F" or info.is_vector else ctx.transpose(value) + return ctx.call("reshape", source, ctx.num(1), empty, loc=loc) + m, n = (_dim(p, ctx) for p in parts) + if order == "F": + return ctx.call("reshape", value, m, n, loc=loc) + # Row-major: reshape the transpose column by column, then transpose back. + source = value if info.is_vector else ctx.transpose(value) + return ctx.transpose(ctx.call("reshape", source, n, m, loc=loc)) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.reshape``: 1-D for one size, 2-D for two.""" + if tag != "py:call:np.reshape" or len(args) != 2: + return None + data, shape = args + count = shape.length if shape.kind in (PyKind.TUPLE, PyKind.LIST) else 1 + kind = PyKind.VECTOR if count == 1 else PyKind.MATRIX if count == 2 else PyKind.UNKNOWN + if kind is PyKind.UNKNOWN: + return None + return replace(py_array(kind, data.dtype, finite=data.finite, nonneg=data.nonneg), view=True) diff --git a/rules/builtins/size-numel-length/cases/basic.m b/rules/builtins/size-numel-length/cases/basic.m index 52f3370..425fb4b 100644 --- a/rules/builtins/size-numel-length/cases/basic.m +++ b/rules/builtins/size-numel-length/cases/basic.m @@ -10,3 +10,7 @@ e = []; Le = length(e); ne = numel(e); +dA = ndims(A); +dv = ndims(v); % 2, although v is 1-D in NumPy +name = 'beam'; +nc = numel(name); diff --git a/rules/builtins/size-numel-length/cases/basic.py b/rules/builtins/size-numel-length/cases/basic.py index 7552c47..1d35697 100644 --- a/rules/builtins/size-numel-length/cases/basic.py +++ b/rules/builtins/size-numel-length/cases/basic.py @@ -12,3 +12,7 @@ e = np.array([]) Le = max(e.shape) ne = e.size +dA = A.ndim +dv = 2 # 2, although v is 1-D in NumPy +name = "beam" +nc = len(name) diff --git a/rules/builtins/size-numel-length/rule.yaml b/rules/builtins/size-numel-length/rule.yaml index a878df2..9d03efc 100644 --- a/rules/builtins/size-numel-length/rule.yaml +++ b/rules/builtins/size-numel-length/rule.yaml @@ -1,8 +1,8 @@ id: builtins/size-numel-length -title: "`size`, `numel`, `length`" +title: "`size`, `numel`, `length`, `ndims`" status: mechanical dialects: [octave, matlab] -match: [call:size, call:numel, call:length] +match: [call:size, call:numel, call:length, call:ndims] from_python: # the Python -> .m direction status: mechanical match: @@ -10,6 +10,7 @@ from_python: # the Python -> .m direction - py:attr:shape - py:call:len - py:call:np.size + - py:attr:ndim octave: | [r, c] = size(A); r = size(A, 1); @@ -28,6 +29,9 @@ why: > pitfalls: - >- `length` of a 2x5 matrix is 5, while `len(A)` is 2. + - >- + `ndims` of a vector or a scalar is 2; the NumPy 1-D array's `ndim` is 1 + and a Python number has none. - >- Octave arrays are at least 2-D: for a row vector `size(v)` is `[1 n]` and `size(v, 1)` is 1, but a 1-D NumPy array has shape `(n,)` and diff --git a/rules/builtins/size-numel-length/translate.py b/rules/builtins/size-numel-length/translate.py index bcaafc0..b6f4aac 100644 --- a/rules/builtins/size-numel-length/translate.py +++ b/rules/builtins/size-numel-length/translate.py @@ -6,7 +6,8 @@ ``numel`` is ``x.size`` (``len`` for a string); ``size(A)`` and ``size(A, d)`` read ``A.shape`` for a matrix. A vector is 1-D in NumPy, so its sizes are spelled out from its known orientation (``size(v, 1)`` of a row is 1). -``length`` is the largest dimension. +``length`` is the largest dimension. ``ndims`` is 2 for every value but a +2-D (or larger) array, which reads ``A.ndim``. """ import ast @@ -52,6 +53,14 @@ def translate(node: ir.Call, ctx: Context) -> ast.expr: expr = ctx.expr(node.args[0]) if node.func == "numel" and len(node.args) == 1: return _count(expr, info, ctx) + if node.func == "ndims" and len(node.args) == 1: + # Every .m value has at least two dimensions; NumPy's 1-D vectors and + # Python scalars have fewer, so only a 2-D array reads its own ndim. + if info.is_matrix: + return ast.Attribute(value=expr, attr="ndim") + if info.is_vector or info.is_scalar or info.kind is Kind.STRING: + return ast.Constant(2) + ctx.decline("ndims of a value whose shape is unknown") if node.func == "length" and len(node.args) == 1: if info.is_matrix or info.kind is Kind.EMPTY: return ctx.call(ast.Name("max"), ast.Attribute(value=expr, attr="shape")) @@ -160,6 +169,13 @@ def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: if isinstance(node, ast.Attribute): if node.attr == "shape": return lift_shape(node, ctx) + if node.attr == "ndim": + dims = ctx.info(node.value) + if dims.is_matrix: + return ctx.call("ndims", ctx.expr(node.value), loc=loc) + if dims.is_vector: + return ctx.num(1, loc=loc) # NumPy's count; ndims would say 2 + ctx.decline(".ndim of a value that is not a known array") info = ctx.info(node.value) if not (info.is_array or info.is_scalar): ctx.assume(f"{ast.unparse(node.value)} is an array") diff --git a/rules/builtins/sort/cases/basic.m b/rules/builtins/sort/cases/basic.m new file mode 100644 index 0000000..83138c2 --- /dev/null +++ b/rules/builtins/sort/cases/basic.m @@ -0,0 +1,7 @@ +v = [3 1 2 1]; +s = sort(v); +d = sort(v, 'descend'); +A = [3 1; 2 5; 1 4]; +S = sort(A); % each column +R = sort(A, 2, 'descend'); % each row, largest first +c = sort([2; 3; 1]); % a column stays a column diff --git a/rules/builtins/sort/cases/basic.py b/rules/builtins/sort/cases/basic.py new file mode 100644 index 0000000..f96acae --- /dev/null +++ b/rules/builtins/sort/cases/basic.py @@ -0,0 +1,9 @@ +import numpy as np + +v = np.array([3, 1, 2, 1]) +s = np.sort(v) +d = np.flip(np.sort(v)) +A = np.array([[3, 1], [2, 5], [1, 4]]) +S = np.sort(A, axis=0) # each column +R = np.flip(np.sort(A, axis=1), axis=1) # each row, largest first +c = np.sort(np.array([2, 3, 1])) # a column stays a column diff --git a/rules/builtins/sort/cases/nan-values.m b/rules/builtins/sort/cases/nan-values.m new file mode 100644 index 0000000..e7abfe4 --- /dev/null +++ b/rules/builtins/sort/cases/nan-values.m @@ -0,0 +1,6 @@ +% NaN goes last ascending and first descending. +x = [3 NaN 1 NaN 2]; +up = sort(x); +down = sort(x, 'descend'); +[up2, k] = sort(x); % the NaN positions stay in order: 2 4 last +% dualect: index k diff --git a/rules/builtins/sort/cases/nan-values.py b/rules/builtins/sort/cases/nan-values.py new file mode 100644 index 0000000..2154059 --- /dev/null +++ b/rules/builtins/sort/cases/nan-values.py @@ -0,0 +1,10 @@ +import numpy as np + +# NaN goes last ascending and first descending. +x = np.array([3, np.nan, 1, np.nan, 2]) +up = np.sort(x) +down = np.flip(np.sort(x)) +# dualect: index k +k = np.argsort(x, kind="stable") +up2 = x[k] # the NaN positions stay in order: 2 4 last +# dualect: index k diff --git a/rules/builtins/sort/cases/positions.m b/rules/builtins/sort/cases/positions.m new file mode 100644 index 0000000..ba8567c --- /dev/null +++ b/rules/builtins/sort/cases/positions.m @@ -0,0 +1,7 @@ +% The second output holds 1-based positions; equal values keep their order. +v = [2 1 2 1]; +[s, i] = sort(v); % i = 2 4 1 3 +[d, j] = sort(v, 'descend'); % j = 1 3 2 4: ties in their original order +w = [10 20 30 40]; +w_by_v = w(i); % reorder another array the same way +% dualect: index i j diff --git a/rules/builtins/sort/cases/positions.py b/rules/builtins/sort/cases/positions.py new file mode 100644 index 0000000..2c644c8 --- /dev/null +++ b/rules/builtins/sort/cases/positions.py @@ -0,0 +1,13 @@ +import numpy as np + +# The second output holds 1-based positions; equal values keep their order. +v = np.array([2, 1, 2, 1]) +# dualect: index i +i = np.argsort(v, kind="stable") +s = v[i] # i = 2 4 1 3 +# dualect: index j +j = np.argsort(-v, kind="stable") +d = v[j] # j = 1 3 2 4: ties in their original order +w = np.array([10, 20, 30, 40]) +w_by_v = w[i] # reorder another array the same way +# dualect: index i j diff --git a/rules/builtins/sort/rule.yaml b/rules/builtins/sort/rule.yaml new file mode 100644 index 0000000..0edf1a4 --- /dev/null +++ b/rules/builtins/sort/rule.yaml @@ -0,0 +1,44 @@ +id: builtins/sort +title: "`sort`: ascending or descending, with 1-based positions" +status: mechanical +dialects: [octave, matlab] +match: [call:sort] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.sort + - py:call:np.argsort +octave: | + s = sort(v); + S = sort(A); % each column + d = sort(v, 'descend'); + [s, i] = sort(v); % i: 1-based positions +python: | + s = np.sort(v) + S = np.sort(A, axis=0) + d = np.flip(np.sort(v)) + i = np.argsort(v, kind="stable") + s = v[i] +why: > + `sort` orders a vector, and each column of a matrix (the first non-singleton + dimension); `np.sort` orders along the *last* axis, the rows of a 2-D + array, so a matrix needs `axis=0`. The positions output is 1-based where + `np.argsort` is 0-based. The source's sort is stable (equal values keep + their order), NumPy's default quicksort is not, hence `kind="stable"`. + NaN goes last ascending and first descending in both. +pitfalls: + - >- + `np.sort(A)` of a 2-D array sorts each row; `sort(A)` each column. + - >- + `np.argsort(v)` without `kind="stable"` may order equal values + differently, so the positions of ties differ. + - >- + The descending positions of equal values keep their original order + (`[~, i] = sort([2 1 2], 'descend')` is `1 3 2`), which reversing an + ascending sort does not give; `np.argsort(-v, kind="stable")` does, for + data without NaN. + - >- + Complex values are sorted by absolute value in the source and + lexicographically in NumPy; they are not translated. +related: [builtins/sum-mean-max, builtins/unique, builtins/find] +python_imports: [import numpy as np] diff --git a/rules/builtins/sort/translate.py b/rules/builtins/sort/translate.py new file mode 100644 index 0000000..e05c19b --- /dev/null +++ b/rules/builtins/sort/translate.py @@ -0,0 +1,275 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/sort: ``sort(x)``, ``sort(x, dim)``, ``'descend'``, positions. + +A vector sorts along itself, a matrix down its columns (``axis=0``; NumPy's +default is the last axis). Descending order is the ascending sort reversed +(``np.flip``), which puts NaN first as the source does. ``[s, i] = sort(v)`` takes the +positions from ``np.argsort(v, kind="stable")`` (the source's sort is stable; +NumPy's default quicksort is not) and stores them 0-based when ``i`` only +ever serves as a subscript, else adds 1. Descending positions must keep equal +values in their original order: ``np.argsort(-v, kind="stable")``, which is +only right for data without NaN (``-NaN`` sorts last), so other descending +positions are declined. Complex values (sorted by magnitude in the source) +and characters are declined. + +From Python, ``np.sort`` is ``sort`` (a 2-D array along its last axis is +``sort(A, 2)``), and ``i = np.argsort(v, kind="stable")`` of a 1-D array is +``[~, i] = sort(v); i = i - 1`` (values stay 0-based, as in Python). +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context, Line +from dualect.infer import Elem, Info, Kind +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def position_outputs(call: ir.Call, nargout: int) -> set[int]: + """The second output of ``sort`` holds positions.""" + return {1} if nargout >= 2 else set() + + +def _options(node: ir.Call, ctx: Context) -> tuple[int | None, bool]: + """``(dimension or None, descending)``.""" + dim: int | None = None + descending = False + for arg in node.args[1:]: + if isinstance(arg, ir.Str): + mode = arg.value.lower() + if mode not in ("ascend", "descend"): + ctx.decline(f"sort with the option {arg.value!r}") + descending = mode == "descend" + continue + value = ctx.info(arg).value + if dim is not None or value not in (1, 2): + ctx.decline("sort along a computed or third dimension") + assert isinstance(value, int | float) + dim = int(value) + if len(node.args) > 3: + ctx.decline("sort with these arguments") + return dim, descending + + +def _check_data(info: Info, ctx: Context) -> None: + if info.kind is Kind.STRING or info.elem in (Elem.CHAR, Elem.COMPLEX): + ctx.decline("sort of characters or complex values (sorted by magnitude in the source)") + if info.elem is Elem.UNKNOWN: + ctx.assume("real values to sort") + + +def _reverse(expr: ast.expr, axis: int, ctx: Context) -> ast.expr: + """``np.flip(expr)`` (along ``axis`` for a 2-D array).""" + if axis < 0: + return ctx.call(ctx.np("flip"), expr) + return ctx.call(ctx.np("flip"), expr, axis=ast.Constant(axis)) + + +def _sorted(data: ir.Expr, dim: int | None, descending: bool, ctx: Context) -> ast.expr: + info = ctx.info(data) + _check_data(info, ctx) + if info.is_matrix: + axis = 0 if dim in (None, 1) else 1 + result = ctx.call(ctx.np("sort"), ctx.expr(data), axis=ast.Constant(axis)) + return _reverse(result, axis, ctx) if descending else result + along = ( + dim is None or (dim == 2 and info.kind is Kind.ROW) or (dim == 1 and info.kind is Kind.COL) + ) + if not (info.is_vector and along): + ctx.decline("sort of a value whose shape is unknown, or along a singleton dimension") + result = ctx.call(ctx.np("sort"), ctx.arg(data)) + return _reverse(result, -1, ctx) if descending else result + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """The sorted values.""" + if not node.args: + ctx.decline("sort without arguments") + dim, descending = _options(node, ctx) + return _sorted(node.args[0], dim, descending, ctx) + + +def translate_multi(stmt: ir.Assign, ctx: Context) -> list[Line]: + """``[s, i] = sort(v)``: the sorted values and their 1-based positions.""" + call = stmt.value + assert isinstance(call, ir.Call) + if len(stmt.targets) != 2 or not call.args: + ctx.decline("sort with these outputs") + dim, descending = _options(call, ctx) + data = call.args[0] + info = ctx.info(data) + _check_data(info, ctx) + if not info.is_vector or info.kind is Kind.EMPTY or dim is not None: + ctx.decline("[s, i] = sort(x) of a matrix, a value of unknown shape or along a dimension") + expr = ctx.expr(data) + if descending: + if not info.finite or info.is_logical: + ctx.decline( + "descending positions of data that may hold NaN or is logical " + "(equal values must keep their order)" + ) + keyed: ast.expr = ast.UnaryOp(op=ast.USub(), operand=expr) + else: + keyed = expr + position = ctx.call(ctx.np("argsort"), keyed, kind=ast.Constant("stable")) + value_target, position_target = stmt.targets + if not isinstance(position_target, ir.Name | ir.Ignore): + ctx.decline("assigning positions into an element") + lines: list[Line] = [] + position_name = position_target.id if isinstance(position_target, ir.Name) else None + zero_based = position_name is not None and ctx.is_index_var(position_name) + if position_name is not None: + if zero_based: + lines.extend(ctx.index_directive(position_name)) + lines.append(ctx.line(f"{position_name} = {ast.unparse(position)}")) + else: + lines.append(ctx.line(f"{position_name} = {ast.unparse(position)} + 1")) + if isinstance(value_target, ir.Name): + if zero_based and position_name is not None: + value: ast.expr = ast.Subscript(value=expr, slice=ast.Name(position_name)) + else: + value = _sorted(data, None, descending, ctx) + lines.append(ctx.line(f"{value_target.id} = {ast.unparse(value)}")) + elif not isinstance(value_target, ir.Ignore): + ctx.decline("assigning sorted values into an element") + return lines + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """The data's shape and type.""" + if not args: + return None + return replace(args[0], value=None, func=None, env=None) + + +def infer_outputs(node: ir.Call, args: list[Info], nargout: int) -> list[Info] | None: + """The sorted values, then positions of the same shape.""" + if not args: + return None + first = replace(args[0], value=None, func=None, env=None) + positions = replace( + first, elem=Elem.REAL, finite=True, nonneg=True, integer=True, int_dtype=True + ) + return [first, positions] + + +# --- Python -> .m ------------------------------------------------------------ + + +def _keywords(node: ast.Call, ctx: LiftContext) -> tuple[ast.expr | None, str | None]: + """``(axis node, kind)`` of a NumPy sort call.""" + axis_node: ast.expr | None = node.args[1] if len(node.args) > 1 else None + kind: str | None = None + for keyword in node.keywords: + if keyword.arg == "axis": + axis_node = keyword.value + elif keyword.arg == "kind" and isinstance(keyword.value, ast.Constant): + kind = str(keyword.value.value) + else: + ctx.decline(f"{keyword.arg}= in a sort") + if len(node.args) > 2: + ctx.decline("a sort with these arguments") + return axis_node, kind + + +def _check_py_data(info: PyInfo, ctx: LiftContext) -> None: + if info.dtype is DType.COMPLEX or info.kind is PyKind.STRING: + ctx.decline("sorting complex values or text") + if info.dtype is DType.UNKNOWN: + ctx.assume("real values to sort") + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.sort(x, axis=...)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if ctx.tag(node) == "py:call:np.argsort": + ctx.decline("np.argsort inside an expression (it needs its own statement)") + if not node.args: + ctx.decline("np.sort without arguments") + axis_node, _kind = _keywords(node, ctx) + data = node.args[0] + info = ctx.info(data) + _check_py_data(info, ctx) + axis: object = -1 + if axis_node is not None: + axis = ctx.info(axis_node).value + if isinstance(axis_node, ast.Constant) and axis_node.value is None: + axis = None + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + if info.is_vector or isinstance(data, ast.List): + if axis not in (None, 0, -1): + ctx.decline("np.sort of a 1-D array along axis 1") + return ctx.call("sort", value, loc=loc) + if not info.is_matrix: + ctx.decline("np.sort of a value whose dimensions are unknown") + if axis in (0, -2): + return ctx.call("sort", value, loc=loc) + if axis in (1, -1): + return ctx.call("sort", value, ctx.num(2), loc=loc) + ctx.decline("np.sort of a 2-D array along a flattened or computed axis") + + +def lift_assign(stmt: ast.Assign, ctx: LiftContext) -> list[ir.Stmt] | None: + """``i = np.argsort(v, kind="stable")``: ``[~, i] = sort(v); i = i - 1``.""" + value = stmt.value + target = stmt.targets[0] + assert isinstance(value, ast.Call) + if ctx.tag(value) != "py:call:np.argsort": + return None + if not value.args or not isinstance(target, ast.Name): + ctx.decline("np.argsort with these arguments") + axis_node, kind = _keywords(value, ctx) + if kind not in ("stable", "mergesort"): + ctx.decline("np.argsort without kind='stable' (equal values may come in any order)") + data = value.args[0] + info = ctx.info(data) + _check_py_data(info, ctx) + if not (info.is_vector or isinstance(data, ast.List)): + ctx.decline("np.argsort of a value that is not 1-D") + if axis_node is not None and ctx.info(axis_node).value not in (0, -1): + ctx.decline("np.argsort along a computed axis") + loc = ctx.loc(stmt) + values = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + found = ir.Assign( + loc=loc, + targets=[ir.Ignore(loc=loc), ir.Name(loc=ctx.loc(target), id=target.id)], + value=ctx.call("sort", values, loc=loc), + ) + shifted = ir.Assign( + loc=loc, + targets=[ir.Name(loc=loc, id=target.id)], + value=ctx.binop("minus", ir.Name(loc=loc, id=target.id), ctx.num(1)), + ) + return [found, shifted] + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """``np.sort``: the data's facts (flattened without an axis); ``np.argsort``: positions.""" + if not args: + return None + data = as_array(args[0]) + if not data.is_array: + return None + if tag == "py:call:np.argsort": + return PyInfo( + kind=PyKind.VECTOR if data.is_vector else data.kind, + dtype=DType.INT, + finite=True, + nonneg=True, + length=data.length, + ) + axis = keywords.get("axis", args[1] if len(args) > 1 else None) + flattened = axis is not None and axis.kind is PyKind.NONE + kind = PyKind.VECTOR if flattened else data.kind + return replace(data, kind=kind, value=None, view=False) diff --git a/rules/builtins/std-var/cases/basic.m b/rules/builtins/std-var/cases/basic.m new file mode 100644 index 0000000..99a6f84 --- /dev/null +++ b/rules/builtins/std-var/cases/basic.m @@ -0,0 +1,9 @@ +% Sample statistics divide by N - 1; a weight of 1 divides by N. +x = [2 4 4 4 5 5 7 9]; +s = std(x); % N - 1: 2.1381 +s_pop = std(x, 1); % N: 2 +v = var(x); +A = [1 2; 3 5; 4 9]; +col_std = std(A); % down each column +row_var = var(A, 0, 2); % the third argument is the dimension +row_pop = var(A, 1, 2); diff --git a/rules/builtins/std-var/cases/basic.py b/rules/builtins/std-var/cases/basic.py new file mode 100644 index 0000000..b0187bd --- /dev/null +++ b/rules/builtins/std-var/cases/basic.py @@ -0,0 +1,11 @@ +import numpy as np + +# Sample statistics divide by N - 1; a weight of 1 divides by N. +x = np.array([2, 4, 4, 4, 5, 5, 7, 9]) +s = x.std(ddof=1) # N - 1: 2.1381 +s_pop = x.std() # N: 2 +v = x.var(ddof=1) +A = np.array([[1, 2], [3, 5], [4, 9]]) +col_std = A.std(axis=0, ddof=1) # down each column +row_var = A.var(axis=1, ddof=1) # the third argument is the dimension +row_pop = A.var(axis=1) diff --git a/rules/builtins/std-var/cases/one-element.m b/rules/builtins/std-var/cases/one-element.m new file mode 100644 index 0000000..2ba2fc6 --- /dev/null +++ b/rules/builtins/std-var/cases/one-element.m @@ -0,0 +1,4 @@ +% One value: N - 1 would divide by zero, but the source returns 0. +single = std(7); +single_var = var(7, 1); +pair = std([3 5]); % two elements: N - 1 = 1 diff --git a/rules/builtins/std-var/cases/one-element.py b/rules/builtins/std-var/cases/one-element.py new file mode 100644 index 0000000..49837f4 --- /dev/null +++ b/rules/builtins/std-var/cases/one-element.py @@ -0,0 +1,6 @@ +import numpy as np + +# One value: N - 1 would divide by zero, but the source returns 0. +single = np.std(7) +single_var = np.var(7) +pair = np.array([3, 5]).std(ddof=1) # two elements: N - 1 = 1 diff --git a/rules/builtins/std-var/rule.yaml b/rules/builtins/std-var/rule.yaml new file mode 100644 index 0000000..d7b3806 --- /dev/null +++ b/rules/builtins/std-var/rule.yaml @@ -0,0 +1,42 @@ +id: builtins/std-var +title: "`std` and `var`: N - 1 by default" +status: mechanical +dialects: [octave, matlab] +match: [call:std, call:var] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.std + - py:call:np.var + - py:method:std + - py:method:var +octave: | + s = std(x); % normalised by N - 1 + s0 = std(x, 1); % normalised by N + v = var(A); % down each column +python: | + s = x.std(ddof=1) + s0 = x.std() + v = A.var(axis=0, ddof=1) +why: > + The sample standard deviation and variance divide by N - 1 by default; NumPy + divides by N unless told `ddof=1` ("delta degrees of freedom"). The second + argument of `std`/`var` is a weight, not an axis: 0 (or `[]`) means N - 1, + 1 means N. The third argument is the dimension; like `sum`, a matrix + reduces down its columns by default (`axis=0`). +pitfalls: + - >- + `np.std(x)` is the population standard deviation (N); write + `ddof=1` to match `std(x)`. + - >- + `std(x, 2)` is not along dimension 2: the second argument is the weight. + `std(A, 0, 2)` is the row-wise standard deviation. + - >- + With N - 1, one element gives 0 in `.m` code but NaN (and a warning) in + NumPy, which divides by zero. Lengths that may be 1 are assumed out loud. + - >- + Octave 9 rewrote `std`/`var` (NaN flags, empty inputs); for finite, + non-empty data both old and new versions agree with NumPy. Empty inputs + are not translated. +related: [builtins/sum-mean-max, builtins/median] +python_imports: [import numpy as np] diff --git a/rules/builtins/std-var/translate.py b/rules/builtins/std-var/translate.py new file mode 100644 index 0000000..c23d9b8 --- /dev/null +++ b/rules/builtins/std-var/translate.py @@ -0,0 +1,193 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/std-var: ``std`` and ``var``. + +The source normalises by N - 1 by default (``std(x)``, ``std(x, 0)``) and by +N with ``std(x, 1)``; NumPy's default is N, so the translation always states +``ddof``: ``x.std(ddof=1)`` or ``x.std()``. A vector reduces to a scalar, a +matrix down its columns (``axis=0``) unless a dimension is given. With N - 1 +a single element gives 0 in the source and NaN in NumPy, so data not known +to have two or more elements along the reduced dimension is assumed to, +out loud. A weight vector, complex data and a reduction along a singleton +dimension are declined. + +From Python, ``ddof=1`` is the default form and no ``ddof`` is ``std(x, 1)``; +an axis becomes a dimension (``axis=1`` gives a column on the ``.m`` side, +so it is turned back into a row). +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def _int(node: ir.Expr | None, ctx: Context, what: str) -> int | None: + """A literal integer argument (``None`` when absent or ``[]``).""" + if node is None or (isinstance(node, ir.Matrix) and not node.rows): + return None + value = ctx.info(node).value + if not isinstance(value, int | float) or not float(value).is_integer(): + ctx.decline(f"{what} that is not a literal integer") + return int(value) + + +def reduce_axis( + node: ir.Call, data: Info, dim: int | None, ctx: Context +) -> tuple[int | None, int | None]: + """``(axis, count along it)`` for a reduction of ``data`` over ``dim``. + + ``axis`` is ``None`` for a vector reduced along its length. + """ + if data.is_matrix: + if dim in (None, 1): + return 0, data.rows + if dim == 2: + return 1, data.cols + ctx.decline(f"{node.func} along dimension {dim}") + if data.kind is Kind.EMPTY: + ctx.decline(f"{node.func} of an empty array (the result depends on the version)") + along = ( + dim is None or (dim == 2 and data.kind is Kind.ROW) or (dim == 1 and data.kind is Kind.COL) + ) + if data.is_vector and along: + return None, data.numel + ctx.decline(f"{node.func} of a scalar, an unknown shape or along a singleton dimension") + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``std(x[, w[, dim]])`` or ``var(...)``.""" + if not 1 <= len(node.args) <= 3: + ctx.decline(f"{node.func} with these arguments") + data = ctx.info(node.args[0]) + if data.elem is not Elem.REAL: + # Logical input: Octave keeps the class (or rejects it) where NumPy computes numbers. + ctx.decline(f"{node.func} of logical, complex or unknown values") + weight = _int(node.args[1] if len(node.args) > 1 else None, ctx, "a weight") + if weight not in (None, 0, 1): + ctx.decline(f"{node.func} with a weight vector") + dim = _int(node.args[2] if len(node.args) > 2 else None, ctx, "a dimension") + if data.is_scalar and dim is None: + # One value: 0 under either weight. NumPy's N - 1 would divide by zero, + # so the population form (ddof=0) is the one that gives 0. + return ctx.call(ctx.np(node.func), ctx.expr(node.args[0])) + axis, count = reduce_axis(node, data, dim, ctx) + ddof = 0 if weight == 1 else 1 + if ddof == 1 and (count is None or count < 2): + if count == 1: + ctx.decline(f"{node.func} of one element (0 in the source, NaN in NumPy)") + ctx.assume(f"at least two elements in {node.func} (one gives 0 here, NaN in NumPy)") + keywords: dict[str, ast.expr] = {} + if axis is not None: + keywords["axis"] = ast.Constant(axis) + if ddof: + keywords["ddof"] = ast.Constant(ddof) + return ctx.method(ctx.expr(node.args[0]), node.func, **keywords) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A scalar for a vector, a row (or a column, for dimension 2) for a matrix.""" + if not args: + return None + first = args[0] + dim = args[2].value if len(args) > 2 else None + facts = {"finite": first.finite, "nonneg": True} + if first.is_vector or first.is_scalar: + return scalar(**facts) # type: ignore[arg-type] + if first.is_matrix: + if dim in (None, 1): + return array(1, first.cols, kind=Kind.ROW, **facts) # type: ignore[arg-type] + if dim == 2: + return array(first.rows, 1, kind=Kind.COL, **facts) # type: ignore[arg-type] + return None + + +# --- Python -> .m ------------------------------------------------------------ + + +def _call_parts(node: ast.Call, ctx: LiftContext) -> tuple[str, ast.expr, list[ast.expr]]: + """``(function, data, positional arguments after the data)``.""" + tag = ctx.tag(node) or "" + if tag.startswith("py:method:"): + assert isinstance(node.func, ast.Attribute) + return tag.removeprefix("py:method:"), node.func.value, list(node.args) + if not node.args: + ctx.decline("a reduction without data") + return tag.removeprefix("py:call:np."), node.args[0], list(node.args[1:]) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.std(x, ddof=1)``, ``x.var(axis=0)``, ...""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + func, data, rest = _call_parts(node, ctx) + axis_node = rest[0] if rest else None + ddof = 0 + if len(rest) > 1: + ctx.decline(f"{func} with these positional arguments") + for keyword in node.keywords: + value = ctx.info(keyword.value).value + if keyword.arg == "axis": + axis_node = keyword.value + elif keyword.arg == "ddof" and value in (0, 1) and not isinstance(value, bool): + ddof = int(value) # type: ignore[arg-type] + else: + ctx.decline(f"{func} with {keyword.arg}=") + axis = None if axis_node is None else ctx.info(axis_node).value + if axis is not None and axis not in (0, 1, -1, -2): + ctx.decline(f"{func} along a computed axis") + info = ctx.info(data) + if info.dtype in (DType.COMPLEX, DType.UNKNOWN) and not isinstance(data, ast.List): + ctx.decline(f"{func} of complex data or data of unknown type") + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + weight = [] if ddof == 1 else [ctx.num(1)] + if info.is_scalar and axis is None: + if ddof == 1: + ctx.decline(f"{func} with ddof=1 of one value (NaN here, 0 in .m code)") + return ctx.call(func, value, loc=loc) + if info.is_vector or isinstance(data, ast.List): + if axis not in (None, 0, -1): + ctx.decline(f"{func} of a 1-D array along axis 1") + count = info.length + if isinstance(data, ast.List): + count = len(data.elts) + if ddof == 1 and count is None: + ctx.assume(f"at least two elements in {func} (one gives NaN here, 0 in .m code)") + if ddof == 1 and count == 1: + ctx.decline(f"{func} with ddof=1 of one element (NaN here, 0 in .m code)") + return ctx.call(func, value, *weight, loc=loc) + if not info.is_matrix: + ctx.decline(f"{func} of a value whose dimensions are unknown") + if ddof == 1: + ctx.assume(f"at least two elements per reduction in {func}") + if axis is None: + flat = ir.Index(loc=loc, target=value, args=[ir.Colon(loc=loc)]) + return ctx.call(func, flat, *weight, loc=loc) + dim = 1 if axis in (0, -2) else 2 + result = ctx.call(func, value, ctx.num(1 - ddof), ctx.num(dim), loc=loc) + return result if dim == 1 else ctx.transpose(result) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """A scalar, or a 1-D array when a 2-D array is reduced along an axis.""" + data = receiver if receiver is not None else (as_array(args[0]) if args else None) + if data is None or not data.is_array: + return None + axis = keywords.get("axis") or (args[0] if receiver is not None and args else None) + if receiver is None and len(args) > 1: + axis = args[1] + facts = PyInfo(kind=PyKind.SCALAR, dtype=DType.FLOAT, finite=data.finite, nonneg=True) + if axis is not None and data.is_matrix: + return replace(facts, kind=PyKind.VECTOR) + return facts diff --git a/rules/builtins/sum-mean-max/cases/min-nan.m b/rules/builtins/sum-mean-max/cases/min-nan.m new file mode 100644 index 0000000..149b4a6 --- /dev/null +++ b/rules/builtins/sum-mean-max/cases/min-nan.m @@ -0,0 +1,9 @@ +% min skips NaN like max: the value, its first position, rows and pairs. +w = [4 NaN 1 1]; +m = min(w); % 1: NaN is skipped +[m2, k] = min(w); % k is the first of the tied minima: 3 +A = [3 NaN; 2 5]; +col_min = min(A); % 2 5 +row_min = min(A, [], 2); % 3; 2 +pair = min([1 NaN 3], [2 2 NaN]); % 1 2 3: NaN only where both are NaN +% dualect: index k diff --git a/rules/builtins/sum-mean-max/cases/min-nan.py b/rules/builtins/sum-mean-max/cases/min-nan.py new file mode 100644 index 0000000..2a29d33 --- /dev/null +++ b/rules/builtins/sum-mean-max/cases/min-nan.py @@ -0,0 +1,12 @@ +import numpy as np + +# min skips NaN like max: the value, its first position, rows and pairs. +w = np.array([4, np.nan, 1, 1]) +m = np.nanmin(w) # 1: NaN is skipped +k = np.nanargmin(w) +m2 = w[k] # k is the first of the tied minima: 3 +A = np.array([[3, np.nan], [2, 5]]) +col_min = np.nanmin(A, axis=0) # 2 5 +row_min = np.nanmin(A, axis=1) # 3; 2 +pair = np.fmin([1, np.nan, 3], [2, 2, np.nan]) # 1 2 3: NaN only where both are NaN +# dualect: index k diff --git a/rules/builtins/sum-mean-max/rule.yaml b/rules/builtins/sum-mean-max/rule.yaml index 0e6aff1..9a150cb 100644 --- a/rules/builtins/sum-mean-max/rule.yaml +++ b/rules/builtins/sum-mean-max/rule.yaml @@ -11,8 +11,6 @@ from_python: # the Python -> .m direction - py:method:max - py:method:min - py:method:prod - - py:method:all - - py:method:any - py:method:argmax - py:method:argmin - py:call:np.sum @@ -32,8 +30,6 @@ from_python: # the Python -> .m direction - py:call:np.fmin - py:call:np.clip - py:call:np.count_nonzero - - py:call:np.all - - py:call:np.any - py:call:max - py:call:min octave: | @@ -66,5 +62,5 @@ pitfalls: - >- `max` and `min` skip NaN (`max([1 NaN 3])` is 3), while NumPy's propagate it: use `np.nanmax`/`np.nanargmax`. `sum` and `mean` propagate NaN in both. -related: [functions/multiple-returns, indexing/colon-all, builtins/find] +related: [functions/multiple-returns, indexing/colon-all, builtins/find, builtins/any-all] python_imports: [import numpy as np] diff --git a/rules/builtins/sum-mean-max/translate.py b/rules/builtins/sum-mean-max/translate.py index 5b59e03..b83bcb5 100644 --- a/rules/builtins/sum-mean-max/translate.py +++ b/rules/builtins/sum-mean-max/translate.py @@ -188,6 +188,11 @@ def _axis(node: ast.Call, rest: list[ast.expr], ctx: LiftContext) -> int | None: for keyword in node.keywords: if keyword.arg == "axis": axis_node = keyword.value + elif keyword.arg == "dtype" and isinstance(keyword.value, ast.Name): + # dtype=float is the .m side's own double arithmetic (and what the + # other direction writes for integer products); others are not. + if keyword.value.id != "float": + ctx.decline(f"dtype={keyword.value.id} in a reduction") else: ctx.decline(f"{keyword.arg}= in a reduction") if axis_node is None: diff --git a/rules/builtins/tic-toc/cases/basic.m b/rules/builtins/tic-toc/cases/basic.m new file mode 100644 index 0000000..369f3f0 --- /dev/null +++ b/rules/builtins/tic-toc/cases/basic.m @@ -0,0 +1,5 @@ +% The elapsed time differs on every run, so it is not compared. +tic; +total = sum(1:1000); +elapsed = toc; +% dualect: ignore elapsed diff --git a/rules/builtins/tic-toc/cases/basic.py b/rules/builtins/tic-toc/cases/basic.py new file mode 100644 index 0000000..4555e17 --- /dev/null +++ b/rules/builtins/tic-toc/cases/basic.py @@ -0,0 +1,9 @@ +# The elapsed time differs on every run, so it is not compared. +import time + +import numpy as np + +t0 = time.perf_counter() +total = np.arange(1, 1001).sum() +elapsed = time.perf_counter() - t0 +# dualect: ignore elapsed diff --git a/rules/builtins/tic-toc/rule.yaml b/rules/builtins/tic-toc/rule.yaml new file mode 100644 index 0000000..c01475b --- /dev/null +++ b/rules/builtins/tic-toc/rule.yaml @@ -0,0 +1,41 @@ +id: builtins/tic-toc +title: "`tic` / `toc`: timing" +status: guided +dialects: [octave, matlab] +match: [call:tic, call:toc] +from_python: # the Python -> .m direction + status: guided + match: + - py:import:time + - py:method:perf_counter +octave: | + tic; + run_model(); + elapsed = toc; % seconds since tic +python: | + import time + + t0 = time.perf_counter() + run_model() + elapsed = time.perf_counter() - t0 +why: > + `tic` starts a stopwatch held by the interpreter and `toc` reads it. + Python has no hidden stopwatch: keep the start time in a variable + (`time.perf_counter()`, a monotonic clock in seconds) and subtract. Timing + has no numeric effect on the results, and the elapsed time differs on every + run, so it is never compared; that is why this rule is not mechanical: the + translation needs a name for the start time, and a `toc` without a + semicolon prints a message rather than a value. Usually the timing is + simply dropped from a translated script. +pitfalls: + - >- + `toc` alone prints `Elapsed time is ... seconds.`; `t = toc` returns the + number and prints nothing. + - >- + `id = tic; ...; toc(id)` times one of several stopwatches: one start + variable each in Python. + - >- + `time.time()` is wall-clock time and can jump; use `time.perf_counter()` + for intervals. +related: [io/printf] +python_imports: [import time] diff --git a/rules/builtins/trapz/cases/basic.m b/rules/builtins/trapz/cases/basic.m new file mode 100644 index 0000000..75f7296 --- /dev/null +++ b/rules/builtins/trapz/cases/basic.m @@ -0,0 +1,10 @@ +% The sample points come first in trapz and second in np.trapezoid. +y = [1 4 9 16]; +unit = trapz(y); % unit spacing: 22 +x = [0 0.5 2 3]; +area = trapz(x, y); +t = linspace(0, pi, 101); +s = trapz(t, sin(t)); % close to 2 +Y = [1 2; 3 5; 4 9]; +cols = trapz(Y); % down each column +cols_x = trapz([0 1 3], Y); diff --git a/rules/builtins/trapz/cases/basic.py b/rules/builtins/trapz/cases/basic.py new file mode 100644 index 0000000..49f0743 --- /dev/null +++ b/rules/builtins/trapz/cases/basic.py @@ -0,0 +1,12 @@ +import numpy as np + +# The sample points come first in trapz and second in np.trapezoid. +y = np.array([1, 4, 9, 16]) +unit = np.trapezoid(y) # unit spacing: 22 +x = np.array([0, 0.5, 2, 3]) +area = np.trapezoid(y, x) +t = np.linspace(0, np.pi, 101) +s = np.trapezoid(np.sin(t), t) # close to 2 +Y = np.array([[1, 2], [3, 5], [4, 9]]) +cols = np.trapezoid(Y, axis=0) # down each column +cols_x = np.trapezoid(Y, [0, 1, 3], axis=0) diff --git a/rules/builtins/trapz/rule.yaml b/rules/builtins/trapz/rule.yaml new file mode 100644 index 0000000..9cc9dc3 --- /dev/null +++ b/rules/builtins/trapz/rule.yaml @@ -0,0 +1,33 @@ +id: builtins/trapz +title: "`trapz`: trapezoidal integration (`np.trapezoid`)" +status: mechanical +dialects: [octave, matlab] +match: [call:trapz] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.trapezoid +octave: | + area = trapz(y); % unit spacing + area = trapz(x, y); % sample points first + cols = trapz(x, Y); % down each column +python: | + area = np.trapezoid(y) + area = np.trapezoid(y, x) # sample points second + cols = np.trapezoid(Y, x, axis=0) +why: > + Both integrate with the trapezoidal rule. The argument order is reversed: + `trapz(x, y)` but `np.trapezoid(y, x)`, so a direct transcription + integrates the wrong thing (x over y) without any error. A matrix is + integrated down its columns in `.m` code and along its last axis (the rows) + in NumPy, hence `axis=0`. NumPy 2.0 renamed `np.trapz` to `np.trapezoid`. +pitfalls: + - >- + `np.trapezoid(x, y)` with the `.m` argument order silently integrates x + with respect to y. + - >- + `np.trapezoid(Y)` of a matrix integrates each row; `trapz(Y)` each column. + - >- + `trapz(y)` assumes unit spacing; pass the sample points for anything else. +related: [builtins/sum-mean-max, builtins/linspace] +python_imports: [import numpy as np] diff --git a/rules/builtins/trapz/translate.py b/rules/builtins/trapz/translate.py new file mode 100644 index 0000000..e6b9292 --- /dev/null +++ b/rules/builtins/trapz/translate.py @@ -0,0 +1,105 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/trapz: ``np.trapezoid``. + +``trapz(y)`` integrates with unit spacing; ``trapz(x, y)`` takes the sample +points first, while ``np.trapezoid(y, x)`` takes them second. A matrix is +integrated down its columns (``axis=0``); NumPy's default axis is the last. +A dimension argument, a scalar and an empty input are declined. (NumPy 2 +renamed ``np.trapz`` to ``np.trapezoid``.) +""" + +import ast + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Info, Kind, array, scalar +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``trapz(y)`` or ``trapz(x, y)``.""" + if len(node.args) not in (1, 2): + ctx.decline("trapz with a dimension") + y = node.args[-1] + info = ctx.info(y) + if not info.is_real: + ctx.decline("trapz of complex values or values of unknown type") + args = [ctx.arg(y)] + if len(node.args) == 2: + points = ctx.info(node.args[0]) + if not points.is_vector or points.kind is Kind.EMPTY: + ctx.decline("trapz with sample points that are not a vector") + args.append(ctx.arg(node.args[0])) + if info.is_matrix: + return ctx.call(ctx.np("trapezoid"), *args, axis=ast.Constant(0)) + if not info.is_vector or info.kind is Kind.EMPTY: + ctx.decline("trapz of a scalar, an empty array or a value of unknown shape") + return ctx.call(ctx.np("trapezoid"), *args) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A scalar for a vector, a row for a matrix.""" + if not args: + return None + y = args[-1] + finite = all(a.finite for a in args) + if y.is_vector: + return scalar(finite=finite) + if y.is_matrix: + return array(1, y.cols, kind=Kind.ROW, finite=finite) + return None + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.trapezoid(y[, x][, axis=...])``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if not 1 <= len(node.args) <= 2: + ctx.decline("np.trapezoid with these arguments") + y = node.args[0] + x = node.args[1] if len(node.args) > 1 else None + axis = None + for keyword in node.keywords: + if keyword.arg == "x" and x is None: + x = keyword.value + elif keyword.arg == "axis": + axis = ctx.info(keyword.value).value + else: + ctx.decline(f"np.trapezoid with {keyword.arg}=") + literals = ctx.module_for("syntax/array-literals") + info = ctx.info(y) + if info.dtype in (DType.COMPLEX, DType.UNKNOWN) and not isinstance(y, ast.List): + ctx.decline("np.trapezoid of complex data or data of unknown type") + args = [literals.lift_items(y, ctx)] + if x is not None: + if not (ctx.info(x).is_vector or isinstance(x, ast.List)): + ctx.decline("np.trapezoid with sample points that are not 1-D") + args.insert(0, literals.lift_items(x, ctx)) + if info.is_vector or isinstance(y, ast.List): + if axis not in (None, 0, -1): + ctx.decline("np.trapezoid of a 1-D array along axis 1") + return ctx.call("trapz", *args, loc=loc) + if not info.is_matrix or axis not in (0, -2, None, 1, -1): + ctx.decline("np.trapezoid of a value whose dimensions are unknown") + if axis in (0, -2): + return ctx.call("trapz", *args, loc=loc) + # NumPy's default: along the rows, dimension 2, a column on the .m side. + return ctx.transpose(ctx.call("trapz", *args, ctx.num(2), loc=loc)) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """A scalar of a 1-D array, a 1-D array of a 2-D one.""" + y = as_array(args[0]) if args else None + if y is None or not y.is_array: + return None + kind = PyKind.VECTOR if y.is_matrix else PyKind.SCALAR + return PyInfo(kind=kind, dtype=DType.FLOAT, finite=y.finite) diff --git a/rules/builtins/type-tests/cases/basic.m b/rules/builtins/type-tests/cases/basic.m new file mode 100644 index 0000000..d61d7bc --- /dev/null +++ b/rules/builtins/type-tests/cases/basic.m @@ -0,0 +1,14 @@ +% Logicals are not numeric; characters are neither; an empty array keeps its class. +x = 3.5; +mask = [1 5 2] > 2; +name = 'beam'; +e = []; +num_x = isnumeric(x); +num_mask = isnumeric(mask); % false +num_name = isnumeric(name); % false +num_e = isnumeric(e); % true +log_mask = islogical(mask); +log_x = islogical(x); +log_e = islogical(e); % false +chr_name = ischar(name); +chr_x = ischar(x); diff --git a/rules/builtins/type-tests/cases/basic.py b/rules/builtins/type-tests/cases/basic.py new file mode 100644 index 0000000..ea37229 --- /dev/null +++ b/rules/builtins/type-tests/cases/basic.py @@ -0,0 +1,16 @@ +import numpy as np + +# Logicals are not numeric; characters are neither; an empty array keeps its class. +x = 3.5 +mask = np.array([1, 5, 2]) > 2 +name = "beam" +e = np.array([]) +num_x = np.issubdtype(np.asarray(x).dtype, np.number) +num_mask = np.issubdtype(np.asarray(mask).dtype, np.number) # false +num_name = np.issubdtype(np.asarray(name).dtype, np.number) # false +num_e = np.issubdtype(np.asarray(e).dtype, np.number) # true +log_mask = np.asarray(mask).dtype == bool +log_x = np.asarray(x).dtype == bool +log_e = np.asarray(e).dtype == bool # false +chr_name = isinstance(name, str) +chr_x = isinstance(x, str) diff --git a/rules/builtins/type-tests/rule.yaml b/rules/builtins/type-tests/rule.yaml new file mode 100644 index 0000000..b698834 --- /dev/null +++ b/rules/builtins/type-tests/rule.yaml @@ -0,0 +1,29 @@ +id: builtins/type-tests +title: "`isnumeric`, `islogical`, `ischar`: what kind of value is this?" +status: mechanical +dialects: [octave, matlab] +match: [call:isnumeric, call:islogical, call:ischar] +octave: | + if ischar(arg), ... end + ok = islogical(mask) && isnumeric(x); +python: | + if isinstance(arg, str): ... + ok = np.asarray(mask).dtype == bool and np.issubdtype(np.asarray(x).dtype, np.number) +why: > + The tests ask about the class of a value. In Python the same question is + asked of the type: a char row vector is a `str`, a logical array has + `dtype == bool`, and a number is any NumPy integer, float or complex dtype. + `np.asarray` lets one test cover Python numbers, NumPy scalars and arrays. +pitfalls: + - >- + Logical values are not numeric: `isnumeric(true)` is false, and NumPy + agrees (`np.bool_` is not a subtype of `np.number`). A plain + `isinstance(x, (int, float))` would say `True` is numeric. + - >- + `isnumeric([])` is true and `islogical([])` false: an empty array keeps + its class. + - >- + `isnumeric('a')` is false: characters are not numbers, although they + convert to their codes in arithmetic. +related: [types/char-strings, types/double] +python_imports: [import numpy as np] diff --git a/rules/builtins/type-tests/translate.py b/rules/builtins/type-tests/translate.py new file mode 100644 index 0000000..fe0fd04 --- /dev/null +++ b/rules/builtins/type-tests/translate.py @@ -0,0 +1,44 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/type-tests: ``isnumeric``, ``islogical``, ``ischar``. + +Each becomes the runtime check that answers the same question of the Python +value, rather than an answer computed from what the translation knows: +``ischar(s)`` is ``isinstance(s, str)``, ``islogical(x)`` is +``np.asarray(x).dtype == bool``, ``isnumeric(x)`` is +``np.issubdtype(np.asarray(x).dtype, np.number)`` (NumPy's bool is not a +number, as logicals are not numeric in the source). A string's array is +`` ast.expr: + """One type test.""" + if len(node.args) != 1: + ctx.decline(f"{node.func} with these arguments") + info = ctx.info(node.args[0]) + if info.kind in (Kind.CELL, Kind.FUNC): + ctx.decline(f"{node.func} of a cell array or a function handle") + expr = ctx.expr(node.args[0]) + if node.func == "ischar": + if info.kind is Kind.UNKNOWN and info.elem is Elem.UNKNOWN: + ctx.decline("ischar of a value of unknown type") + return ctx.call(ast.Name("isinstance"), expr, ast.Name("str")) + dtype = ast.Attribute(value=ctx.call(ctx.np("asarray"), expr), attr="dtype") + if node.func == "islogical": + return ast.Compare(left=dtype, ops=[ast.Eq()], comparators=[ast.Name("bool")]) + return ctx.call(ctx.np("issubdtype"), dtype, ctx.np("number")) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A logical scalar.""" + return scalar(elem=Elem.LOGICAL, nonneg=True, integer=True) diff --git a/rules/builtins/unique/cases/basic.m b/rules/builtins/unique/cases/basic.m new file mode 100644 index 0000000..85f7fbe --- /dev/null +++ b/rules/builtins/unique/cases/basic.m @@ -0,0 +1,8 @@ +v = [3 1 3 2 1]; +u = unique(v); % 1 2 3, a row +c = unique([5; 4; 5]); % 4; 5, a column +A = [2 1; 1 3]; +w = unique(A); % 1; 2; 3: a matrix gives a column +m = unique([1 0 1] > 0); % logical values stay logical +e = unique([]); % empty +n = numel(unique(v)); % how many distinct values diff --git a/rules/builtins/unique/cases/basic.py b/rules/builtins/unique/cases/basic.py new file mode 100644 index 0000000..e7a9651 --- /dev/null +++ b/rules/builtins/unique/cases/basic.py @@ -0,0 +1,10 @@ +import numpy as np + +v = np.array([3, 1, 3, 2, 1]) +u = np.unique(v) # 1 2 3, a row +c = np.unique(np.array([5, 4, 5])) # 4; 5, a column +A = np.array([[2, 1], [1, 3]]) +w = np.unique(A) # 1; 2; 3: a matrix gives a column +m = np.unique(np.array([1, 0, 1]) > 0) # logical values stay logical +e = np.unique(np.array([])) # empty +n = np.unique(v).size # how many distinct values diff --git a/rules/builtins/unique/rule.yaml b/rules/builtins/unique/rule.yaml new file mode 100644 index 0000000..9805526 --- /dev/null +++ b/rules/builtins/unique/rule.yaml @@ -0,0 +1,33 @@ +id: builtins/unique +title: "`unique`: the distinct values, sorted" +status: mechanical +dialects: [octave, matlab] +match: [call:unique] +from_python: # the Python -> .m direction + status: mechanical + match: + - py:call:np.unique +octave: | + u = unique(v); % sorted, each value once + w = unique(A); % a matrix gives a column +python: | + u = np.unique(v) + w = np.unique(A) +why: > + Both return the distinct values in ascending order. The source keeps the + orientation of a vector and returns a column for a matrix; NumPy flattens + everything into a 1-D array, which stands for either. The extra outputs + differ in convention and are not translated. +pitfalls: + - >- + NaN is never equal to itself, so `unique([1 NaN NaN])` keeps both NaN, + while `np.unique` merges them into one (`equal_nan=True` by default). + Data that may hold NaN is not translated. + - >- + `[u, i, j] = unique(x)` returns 1-based positions, and which occurrence + `i` points at (first or last) has differed between versions; NumPy's + `return_index` is the first, 0-based. Only the first output is translated. + - >- + `np.unique` of a 2-D array is 1-D; `unique(A)` is a column. +related: [builtins/sort] +python_imports: [import numpy as np] diff --git a/rules/builtins/unique/translate.py b/rules/builtins/unique/translate.py new file mode 100644 index 0000000..4cebc11 --- /dev/null +++ b/rules/builtins/unique/translate.py @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Evan Gress + +"""Translator for builtins/unique: ``unique(x)`` is ``np.unique(x)``. + +Both sort the distinct values; NumPy returns a 1-D array, which stands for +the row or column the source returns. Only the plain one-output call is +translated: options (``'stable'``, ``'rows'``, ...) and the position outputs +are declined. ``np.unique`` merges NaNs, which the source keeps apart, so +data that may hold NaN is declined. Characters are declined. + +From Python, ``np.unique(x)`` of 1-D data is ``unique(x)``; of a 2-D array, +which NumPy flattens into a 1-D (row) result, ``unique(A).'``. +""" + +import ast +from dataclasses import replace + +from dualect import ir +from dualect.emit import Context +from dualect.infer import Elem, Info, Kind, array +from dualect.lift import LiftContext +from dualect.pyinfer import DType, PyInfo, PyKind, as_array + + +def translate(node: ir.Call, ctx: Context) -> ast.expr: + """``unique(x)``.""" + if len(node.args) != 1: + ctx.decline("unique with options") + info = ctx.info(node.args[0]) + if info.kind is Kind.STRING or info.elem not in (Elem.REAL, Elem.LOGICAL): + ctx.decline("unique of characters, complex values or values of unknown type") + if not info.finite: + ctx.decline("unique of data that may hold NaN (np.unique merges NaNs, the source not)") + if not (info.is_array or info.is_scalar): + ctx.decline("unique of a value whose shape is unknown") + return ctx.call(ctx.np("unique"), ctx.arg(node.args[0])) + + +def infer_call(node: ir.Call, args: list[Info], nargout: int) -> Info | None: + """A row for a row, a column otherwise; the elements' facts are kept.""" + if not args: + return None + first = args[0] + facts = { + "elem": first.elem, + "finite": first.finite, + "nonneg": first.nonneg, + "integer": first.integer, + } + if first.kind is Kind.ROW: + info = array(1, None, kind=Kind.ROW, **facts) # type: ignore[arg-type] + elif first.is_array: + info = array(None, 1, kind=Kind.COL, **facts) # type: ignore[arg-type] + else: + return None + return replace(info, int_dtype=first.int_dtype) + + +def lift(node: ast.expr, ctx: LiftContext) -> ir.Expr: + """``np.unique(x)``.""" + assert isinstance(node, ast.Call) + loc = ctx.loc(node) + if len(node.args) != 1 or node.keywords: + ctx.decline("np.unique with options or extra outputs") + data = node.args[0] + info = ctx.info(data) + if info.dtype in (DType.COMPLEX, DType.UNKNOWN) and not isinstance(data, ast.List): + ctx.decline("np.unique of complex values or values of unknown type") + finite = info.finite + if isinstance(data, ast.List): + finite = all(ctx.info(e).finite for e in data.elts) + if not finite: + ctx.decline("np.unique of data that may hold NaN (NumPy merges NaNs, the .m side not)") + value = ctx.module_for("syntax/array-literals").lift_items(data, ctx) + if info.is_vector or isinstance(data, ast.List): + return ctx.call("unique", value, loc=loc) + if not info.is_matrix: + ctx.decline("np.unique of a value whose dimensions are unknown") + return ctx.transpose(ctx.call("unique", value, loc=loc)) + + +def pyinfer_call( + tag: str, + node: ast.Call, + args: list[PyInfo], + keywords: dict[str, PyInfo], + receiver: PyInfo | None, +) -> PyInfo | None: + """A 1-D array of the data's element type.""" + if not args or node.keywords: + return None + data = as_array(args[0]) + if not data.is_array: + return None + return PyInfo(kind=PyKind.VECTOR, dtype=data.dtype, finite=data.finite, nonneg=data.nonneg) diff --git a/rules/functions/multiple-returns/translate.py b/rules/functions/multiple-returns/translate.py index 55219c1..65e2d98 100644 --- a/rules/functions/multiple-returns/translate.py +++ b/rules/functions/multiple-returns/translate.py @@ -44,8 +44,15 @@ def lift_multi(stmt: ast.Assign, ctx: LiftContext) -> list[ir.Stmt]: assert isinstance(target, ast.Tuple | ast.List) if isinstance(value, ast.Attribute) and value.attr == "shape": return ctx.module_for("builtins/size-numel-length").lift_multi(stmt, ctx) - if isinstance(value, ast.Call) and ctx.tag(value) == "py:call:np.nonzero": - return ctx.module_for("builtins/find").lift_multi(stmt, ctx) + tag = ctx.tag(value) if isinstance(value, ast.Call) else None + rule = ctx.index.rule_for(tag) if tag is not None else None + if rule is not None and rule.id != "functions/multiple-returns" and tag != "py:call-local": + # A built-in with several results (np.nonzero, np.meshgrid, ...) is + # its own rule's business: that rule's lift_multi. + hook = getattr(ctx.module_for(rule.id), "lift_multi", None) + if hook is None: + ctx.decline(f"unpacking the result of {tag}") + return list(hook(stmt, ctx)) if not ( isinstance(value, ast.Call) and isinstance(value.func, ast.Name) diff --git a/rules/io/printf/cases/integers.py b/rules/io/printf/cases/integers.py index f4f11bc..f0a7a20 100644 --- a/rules/io/printf/cases/integers.py +++ b/rules/io/printf/cases/integers.py @@ -1,7 +1,7 @@ import numpy as np # %d needs a whole number: a computed count is one, a quotient may not be. -k = np.floor(7 / 2) +k = 7 // 2 total = np.array([1, 2, 3]).sum() print(f"k = {int(k)}, total = {int(total)}, padded = {int(k):04d}") print(f"big: {int(2**40)}") From 2efc473b769c7d61be295a36ba050f1d0c68bb9c Mon Sep 17 00:00:00 2001 From: Evan Gress <106449014+evangress@users.noreply.github.com> Date: Sat, 14 Nov 2026 11:01:57 -0500 Subject: [PATCH 3/4] Promote guided rules, fix integer squares, adversarial pass, three corpus scripts Promoted to mechanical after `dualect rules check` qualified them: functions/multiple-returns (.m -> Python: tuple unpacking, `_`, output slices; nargout-dependent bodies split into a guided functions/nargout), functions/nargin (both ways: literal defaults in the header, None defaults with `is None`/isempty when no caller may pass an empty value), indexing/grow-on-assign (both ways: np.append, np.pad, np.zeros) and syntax/command-syntax (display-only commands dropped with a comment, `clear a b` is `del a, b`). io/display stays guided: the display format of a missing semicolon depends on the value. Integer powers: every exponent of 2 or more on an integer array, or on an element read out of one, is a float, and an integer matrix power works in floats (x .^ 2 wrapped around above 3037000499). A tall A \ b is a least-squares solve; [m, i] = max(A) of a matrix gives per-column rows. Adversarial probes of every new rule, both directions, against Octave: tests/test_adversarial*.py. New corpus scripts: least_squares_fit.m, data_statistics.m, grid_heat.m. README, docs/index.html, CLAUDE.md and design.md carry the new numbers. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 19 +- README.md | 62 ++-- corpus/data_statistics.m | 35 ++ corpus/grid_heat.m | 33 ++ corpus/least_squares_fit.m | 32 ++ docs/design.md | 35 +- docs/index.html | 31 +- dualect/emit.py | 5 +- dualect/infer.py | 10 +- llms.txt | 11 +- pyproject.toml | 2 + .../sum-mean-max/cases/matrix-positions.m | 4 + .../sum-mean-max/cases/matrix-positions.py | 10 + rules/builtins/sum-mean-max/translate.py | 20 +- rules/functions/definition/translate.py | 18 +- .../functions/multiple-returns/cases/basic.m | 13 +- .../functions/multiple-returns/cases/basic.py | 17 +- rules/functions/multiple-returns/rule.yaml | 14 +- rules/functions/multiple-returns/translate.py | 72 +++- rules/functions/nargin/rule.yaml | 4 +- rules/functions/nargin/translate.py | 339 ++++++++++++++++++ rules/functions/nargout/cases/basic.m | 10 + rules/functions/nargout/cases/basic.py | 10 + rules/functions/nargout/rule.yaml | 33 ++ rules/indexing/grow-on-assign/cases/basic.py | 11 +- rules/indexing/grow-on-assign/cases/matrix.py | 5 +- rules/indexing/grow-on-assign/rule.yaml | 15 +- rules/indexing/grow-on-assign/translate.py | 191 ++++++++++ rules/operators/division/rule.yaml | 3 + rules/operators/division/translate.py | 19 +- rules/operators/power/cases/basic.m | 3 + rules/operators/power/cases/basic.py | 13 +- rules/operators/power/rule.yaml | 7 +- rules/operators/power/translate.py | 36 +- rules/syntax/command-syntax/cases/basic.m | 5 +- rules/syntax/command-syntax/cases/basic.py | 11 +- rules/syntax/command-syntax/rule.yaml | 17 +- rules/syntax/command-syntax/translate.py | 60 ++++ tests/test_adversarial.py | 102 +++++- tests/test_adversarial_numerics.py | 174 +++++++++ tests/test_adversarial_reductions.py | 159 ++++++++ tests/test_adversarial_shapes.py | 194 ++++++++++ tests/test_cli.py | 4 +- tests/test_milestone6.py | 2 +- tests/test_translate.py | 8 +- 45 files changed, 1728 insertions(+), 150 deletions(-) create mode 100644 corpus/data_statistics.m create mode 100644 corpus/grid_heat.m create mode 100644 corpus/least_squares_fit.m create mode 100644 rules/builtins/sum-mean-max/cases/matrix-positions.m create mode 100644 rules/builtins/sum-mean-max/cases/matrix-positions.py create mode 100644 rules/functions/nargin/translate.py create mode 100644 rules/functions/nargout/cases/basic.m create mode 100644 rules/functions/nargout/cases/basic.py create mode 100644 rules/functions/nargout/rule.yaml create mode 100644 rules/indexing/grow-on-assign/translate.py create mode 100644 rules/syntax/command-syntax/translate.py create mode 100644 tests/test_adversarial_numerics.py create mode 100644 tests/test_adversarial_reductions.py create mode 100644 tests/test_adversarial_shapes.py diff --git a/CLAUDE.md b/CLAUDE.md index 7aebfcc..04bd095 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,16 +14,21 @@ architecture, the rule format and the milestones. ## Current state -Milestones 1-6 of docs/design.md are done. Both directions work end to end: -`.m` -> Python (dualect/lower.py, infer.py, emit.py; 30 of 35 rules mechanical) -and Python -> `.m` (dualect/pyinfer.py, lift.py, memit.py; 29 mechanical), one +Milestones 1-6 of docs/design.md are done, plus a coverage pass (section 11, +item 7). Both directions work end to end: +`.m` -> Python (dualect/lower.py, infer.py, emit.py; 58 of 61 rules mechanical) +and Python -> `.m` (dualect/pyinfer.py, lift.py, memit.py; 54 mechanical), one rule folder per construct serving both (`from_python:` in rule.yaml, `lift()` in -translate.py, status per direction). `dualect rules check` enforces that every +translate.py, status per direction; inference facts for a built-in come from +its rule's `infer_call`/`pyinfer_call`). Still guided: functions/nargout, +io/display, builtins/tic-toc. `dualect rules check` enforces that every status is earned; `dualect mcp` serves scan/get_rule/translate/verify; `llms.txt` is generated (`dualect llms-txt -o llms.txt`) and must stay current. -Adversarial probes live in tests/test_adversarial.py and tests/test_reverse.py. -Next: more rules (the guided ones, `cumsum`, `filter`, printing), cell arrays -and structs. +Verify compares printed output when a script carries `% dualect: stdout` +(translations that print add it) and random values by shape (`shape r`). +Adversarial probes live in tests/test_adversarial*.py and tests/test_reverse.py. +All six corpus scripts are tested; three translate completely both ways. +Next: cell arrays and structs, `cond`/`ind2sub`-style gaps the corpus shows. The project site is `docs/index.html` (GitHub Pages from `/docs`, TagBrush.css); keep its numbers in step with README.md and run TagCheck after editing it. diff --git a/README.md b/README.md index 821bf54..39074ff 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,8 @@ the same way. Site: https://kovirlabs.github.io/dualect/ · Design: [docs/design.md](docs/design.md) -> **Status: early (0.1.0).** 35 rules. `.m` → Python: 30 mechanical, 5 guided. -> Python → `.m`: 29 mechanical, 3 guided. Details under [Status and limits](#status-and-limits). +> **Status: early (0.1.0).** 61 rules. `.m` → Python: 58 mechanical, 3 guided. +> Python → `.m`: 54 mechanical, 1 guided. Details under [Status and limits](#status-and-limits). ## Example @@ -118,7 +118,7 @@ The `.m` side may use Octave syntax (`#` comments, `!=`, `++`, `+=`, `translate` prints one line per statement: line and column, kind, the status used, whether it was verified, and the rules it used. Under a statement it could -not translate, it prints why, for example `needs call:filter (no rule)` or +not translate, it prints why, for example `needs call:cond (no rule)` or `translator declined: max of a value whose shape is unknown or along a singleton dimension`. Then come a summary (`30 statements: 29 mechanical, 1 guided, 0 unsupported`), the per-variable comparison when verification ran, and a `verified:` line. @@ -128,7 +128,9 @@ An untranslated statement becomes a hole in the output: in Python, a `raise NotImplementedError(...)`; in `.m`, a `% TODO(dualect)` comment followed by `error(...)`. The output's first line then says `UNVERIFIED` and why. `# dualect: assumed ...` marks an assumption the engine could not prove (for -example a real `sqrt` argument). +example a real `sqrt` argument). A translation that prints carries +`# dualect: stdout`, so verification also compares the printed text exactly; +`# dualect: shape r` compares random values by shape only. | Exit code | `translate` | `verify` | |---|---|---| @@ -201,26 +203,40 @@ Desktop, ...) looks like: ## Status and limits -From `uv run dualect rules list`: 35 rules with 49 case pairs. - -- `.m` → Python: 30 mechanical; guided: `functions/multiple-returns`, - `functions/nargin`, `indexing/grow-on-assign`, `io/display`, - `syntax/command-syntax`. -- Python → `.m`: 29 mechanical; guided: `functions/nargin`, - `indexing/grow-on-assign`, `io/display`; 3 rules cover `.m`-only constructs. - -The [`corpus/`](corpus) scripts, `.m` → Python: - -| Script | Statements | Translated | Verified | +From `uv run dualect rules list`: 61 rules with 88 case pairs. + +- `.m` → Python: 58 mechanical; guided: `functions/nargout` (a body that + depends on how many outputs were requested), `io/display` (a missing `;`: + the display format depends on the value) and `builtins/tic-toc` (timing). +- Python → `.m`: 54 mechanical; guided: `builtins/tic-toc`; 6 rules cover + `.m`-only constructs. + +Built-ins with rules include printing (`printf`, `fprintf`, `sprintf`, `disp`, +`num2str`), `filter` (as `scipy.signal.lfilter`), reductions and statistics +(`sum mean max min prod cumsum cumprod diff any all std var median`), ordering +(`sort` with its index output, `unique`, `flip`), shape (`reshape repmat cat +horzcat vertcat meshgrid`), linear algebra (`norm dot cross kron inv det trace +rank`, `\` for square and tall systems), `interp1`, `polyfit`, `polyval`, +`trapz`, `rand`/`randn` (compared by shape only: no two runs share values) and +the element-wise math functions; `llms.txt` lists them all. +[NumPy for MATLAB users](https://numpy.org/doc/stable/user/numpy-for-matlab-users.html) +served as the checklist. Forms a rule cannot translate exactly are declined +by name (for example `%d` of a fraction, `unique` with several outputs, +`interp1` with `'spline'`). + +The [`corpus/`](corpus) scripts: + +| Script | `.m` → Python | Verified | Back to `.m` | |---|---|---|---| -| `ode_rk4.m` | 23 | 23 | yes | -| `beam_deflection.m` | 30 | 29 (`fprintf` is guided) | no | -| `signal_filter.m` | 33 | 29 (`filter` has no rule; two `max` calls depend on it) | no | - -The Python that dualect writes for `ode_rk4.m` translates back to `.m` and verifies. - -Not supported yet: cell arrays, structs, plotting, random numbers, file I/O and -most built-ins beyond the rules listed in `llms.txt`. Out of scope for now: +| `ode_rk4.m` | 23/23 | yes | 21/21, verified | +| `beam_deflection.m` | 30/30 | yes | 27/27, verified | +| `signal_filter.m` | 33/33 | yes | 29/29, verified | +| `least_squares_fit.m` | 26/27 (`cond` has no rule) | no | holes carried over | +| `data_statistics.m` | 27/28 (`round` of an expression is declined) | no | holes carried over | +| `grid_heat.m` | 20/26 (`trapz` along a dimension, `ind2sub`, shapes lost after a slice) | no | holes carried over | + +Not supported yet: cell arrays, structs, plotting, file I/O and built-ins +beyond the rules listed in `llms.txt`. Out of scope for now: `classdef`, GUIs, Simulink, MEX and toolboxes. Verification shows the two programs agree when run as written, not on every possible input. diff --git a/corpus/data_statistics.m b/corpus/data_statistics.m new file mode 100644 index 0000000..ce0c992 --- /dev/null +++ b/corpus/data_statistics.m @@ -0,0 +1,35 @@ +% Summary statistics of a data matrix: one column per sensor, one row per +% sample (deterministic data, so both sides see the same numbers). +n = 12; +k = (1:n)'; +D = [20 + 2*sin(k), 15 + 0.5*k, 30 - cos(3*k).^2, mod(7*k, 5)]; + +col_mean = mean(D); +col_std = std(D); % N-1 normalisation +col_var = var(D, 1); % N normalisation +col_median = median(D); +[col_max, row_of_max] = max(D); +[col_min, row_of_min] = min(D); +spread = col_max - col_min; + +% Standardise each column (implicit expansion), then find outliers. +Z = (D - mean(D)) ./ std(D); +outlier = abs(Z) > 1.5; +n_outliers = sum(outlier(:)); +any_outlier = any(outlier); +all_positive = all(D > 0); + +% Running totals and ranks of the second sensor. +running = cumsum(D(:, 2)); +[sorted2, order2] = sort(D(:, 2), 'descend'); +top3 = order2(1:3); + +% Rounded values and how many distinct levels the last sensor takes. +levels = unique(D(:, 4)); +n_levels = numel(levels); +D_round = round(D * 10) / 10; + +for j = 1:size(D, 2) + fprintf('sensor %d: mean %8.3f std %7.3f median %8.3f\n', ... + j, col_mean(j), col_std(j), col_median(j)); +end diff --git a/corpus/grid_heat.m b/corpus/grid_heat.m new file mode 100644 index 0000000..b56f7a5 --- /dev/null +++ b/corpus/grid_heat.m @@ -0,0 +1,33 @@ +% Steady temperature on a unit square: a hot top edge, cold elsewhere, +% solved by Jacobi iteration on a grid, then integrated with trapz. +nx = 21; +ny = 11; +x = linspace(0, 1, nx); +y = linspace(0, 1, ny); +[X, Y] = meshgrid(x, y); % ny-by-nx: rows follow y, columns follow x + +T = zeros(ny, nx); +T(end, :) = 100; % the top edge (y = 1) is hot + +for iter = 1:400 + T_old = T; + T(2:end-1, 2:end-1) = 0.25 * (T_old(1:end-2, 2:end-1) + T_old(3:end, 2:end-1) ... + + T_old(2:end-1, 1:end-2) + T_old(2:end-1, 3:end)); +end +change = max(max(abs(T - T_old))); + +% Mean temperature over the square, by the trapezoidal rule in both directions. +inner = trapz(x, T, 2); % along x, for each row +mean_T = trapz(y, inner); + +% The centre line, its gradient, and the hottest interior point. +centre = T(:, (nx + 1) / 2); +dT = diff(centre) / (y(2) - y(1)); +interior = T(2:end-1, 2:end-1); +[t_max, idx] = max(interior(:)); +[row, col] = ind2sub(size(interior), idx); + +% A smooth reference field on the same grid, and its distance from T. +F = 100 * sinh(pi * Y) .* sin(pi * X) / sinh(pi); +gap = norm(T - F, 'fro') / sqrt(numel(T)); +profile = reshape(T(:, 1:2:end), 1, []); diff --git a/corpus/least_squares_fit.m b/corpus/least_squares_fit.m new file mode 100644 index 0000000..892f7f5 --- /dev/null +++ b/corpus/least_squares_fit.m @@ -0,0 +1,32 @@ +% Fit a quadratic to noisy measurements, three ways: polyfit, the normal +% equations, and a QR-free backslash solve; compare and summarise. +t = linspace(0, 2, 21); +noise = 0.05 * sin(37 * t) .* cos(11 * t); % deterministic "noise" +y = 1.5 - 0.8 * t + 0.6 * t.^2 + noise; + +% 1) polyfit / polyval +p = polyfit(t, y, 2); +y_fit = polyval(p, t); + +% 2) the same model by least squares on a design matrix +A = [ones(numel(t), 1), t', (t.^2)']; +c = A \ y'; +c_normal = (A' * A) \ (A' * y'); + +% Residuals and goodness of fit +r = y - y_fit; +ss_res = sum(r.^2); +ss_tot = sum((y - mean(y)).^2); +r_squared = 1 - ss_res / ss_tot; +rms_err = sqrt(mean(r.^2)); +coef_diff = max(abs(fliplr(p) - c')); +cond_A = cond(A); + +% Prediction at a few new points, and where the fitted curve is lowest +t_new = [2.5 3.0]; +y_new = polyval(p, t_new); +[y_low, k_low] = min(y_fit); +t_low = t(k_low); + +fprintf('fit: y = %.4f + %.4f t + %.4f t^2\n', p(3), p(2), p(1)); +fprintf('R^2 = %.6f, rms = %.3e\n', r_squared, rms_err); diff --git a/docs/design.md b/docs/design.md index b5b4022..684ba60 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,6 @@ # dualect — design -Status: 2026-11-13. This document is the plan; section 11 tracks what is built. +Status: 2026-11-14. This document is the plan; section 11 tracks what is built. ## 1. Problem @@ -266,7 +266,21 @@ join of the argument facts at its call sites in the file. (the source leaves the variable as a `1x0` array). The normalizer turns `2.^x` into `2 .^x`: the grammar read it as the number `2.` and a matrix power. Horizontal concatenation of columns and matrices is - `np.column_stack`. + `np.column_stack`. Squares overflow too (an int64 holding 3037000500 has a + square beyond 2**63), so every exponent of 2 or more on an integer array, + or on an element read out of one (`np.int64`), is a float (`x**2.0`), and + an integer matrix power works in floats (`A.astype(float)`). +- **Built-ins teach the analysis themselves.** A rule's `translate.py` may + define `infer_call(node, args, nargout)` and `infer_outputs(...)` (what a + built-in returns, as `Info`), and `pyinfer_call(tag, node, args, keywords, + receiver)` for the Python direction; `dualect/infer.py` and + `dualect/pyinfer.py` ask the rule covering a call before their own tables. + So a new built-in is still one folder, facts included. A call made only for + its effect (`fprintf(...)`) may need several statements (a loop that + recycles a format): its rule's `translate_call_statement` provides them. + A store the scanner tagged `assign:grow` goes to indexing/grow-on-assign's + `translate_store`, and `a, b = (...)` from Python to the claiming + rule's `lift_multi`. - **Output.** ruff formats the file (its default style, so the result does not depend on the caller's configuration). The first line states the verdict: `verified against the .m source`, or `UNVERIFIED: ` (holes, no @@ -473,6 +487,23 @@ good seed for `builtins/*` rules (link, don't copy). directory, failing every later script; the runner now changes directory before clearing the workspace. +7. **Coverage** (done): 61 rules, 88 case pairs. `.m` -> Python 58 + mechanical, 3 guided (`functions/nargout`, split out of + multiple-returns; `io/display`, now only a missing `;`; `builtins/tic-toc`); + Python -> `.m` 54 mechanical, 1 guided, 6 `.m`-only. New: `io/printf` + (formats as f-strings, recycling carried out statically or as a loop), + `builtins/filter` (`scipy.signal.lfilter`, SciPy added as a dependency), + `types/double`, 22 built-in rules chosen from NumPy's "NumPy for MATLAB + users" page, and per-rule inference hooks (section 5.4). Promoted to + mechanical: `functions/multiple-returns`, `functions/nargin` (both ways), + `indexing/grow-on-assign` (both ways) and `syntax/command-syntax` + (display-only commands dropped with a comment, `clear a b` is `del`). + Verification compares printed output on request and random values by + shape (section 12.1). All six corpus scripts run in the tests; + `beam_deflection`, `signal_filter` and `ode_rk4` translate completely and + verify both ways; `least_squares_fit` (26/27), `data_statistics` (27/28) + and `grid_heat` (20/26) report their holes by name. + ## 12. Decisions Settled by the owner on 2026-11-12 (these were the open questions of the first draft): diff --git a/docs/index.html b/docs/index.html index 3a3a82b..f6e3039 100644 --- a/docs/index.html +++ b/docs/index.html @@ -257,7 +257,7 @@

From Python to .m

Reading the report

-

For each statement, translate prints its line and column, its kind, the status used, whether it was verified, and the rules it used. Below a statement that was not translated, it prints why (for example needs call:filter (no rule)). The summary line counts statements by status, and the verified: line gives the verdict.

+

For each statement, translate prints its line and column, its kind, the status used, whether it was verified, and the rules it used. Below a statement that was not translated, it prints why (for example needs call:cond (no rule)). The summary line counts statements by status, and the verified: line gives the verdict.

@@ -316,11 +316,11 @@

Current coverage

dualect is at version 0.1.0 and early. These numbers come from dualect rules list and the test suite.

Rules
-
35, with 49 case pairs between them.
+
61, with 88 case pairs between them.
.m to Python
-
30 mechanical, 5 guided.
+
58 mechanical, 3 guided.
Python to .m
-
29 mechanical, 3 guided; 3 rules cover constructs that exist only in .m code.
+
54 mechanical, 1 guided; 6 rules cover constructs that exist only in .m code.

Rules not yet mechanical

@@ -330,17 +330,15 @@

Rules not yet mechanical

- - - - - + + +
Exit codes of dualect translate
Rule.m to PythonPython to .mWhat is missing
functions/multiple-returnsguidedmechanicalBodies that depend on nargout need to collapse into one tuple return.
functions/narginguidedguidedDefault-argument patterns need facts about arguments that the analysis does not derive.
indexing/grow-on-assignguidedguidedGrowing an array past its end needs rewrites that span several statements.
io/displayguidedguidedprintf-style formats and displaying values without a semicolon.
syntax/command-syntaxguidednot applicableIts case needs strsplit, which has no rule.
builtins/tic-tocguidedguidedTiming has no value to compare, and dropping it silently is a judgement, not a translation.
functions/nargoutguidednot applicableA body that skips work when fewer outputs are requested has no single Python form.
io/displayguidednot applicableA missing semicolon displays values in a format that depends on the value.
-

The other 30 rules are mechanical in every direction they apply to. They cover comments and line continuation, array literals, character strings, one-based and logical indexing, end in an index, colon ranges, A(:), arithmetic, division and linear solves, matrix and element-wise products and powers, transposes, comparisons, logical NOT and short-circuit logic, augmented assignment, for, while, if and switch, function definitions, constants, element-wise math, zeros/ones/eye, linspace, size/numel/length, sum/mean/max/min, find and isempty. The full list is in llms.txt.

+

The other 58 rules are mechanical in every direction they apply to. Besides the core language (literals, strings, indexing with end, ranges and masks, growing arrays, operators, control flow, functions with several outputs and nargin defaults, command syntax), they cover printing (printf, fprintf, sprintf, disp, num2str), filter, reductions and statistics (sum, mean, max, min, prod, cumsum, cumprod, diff, any, all, std, var, median), sort, unique, flip, reshape, repmat, concatenation, meshgrid, rand, linear algebra (norm, dot, cross, kron, inv, det, trace, rank), interp1, polyfit, polyval, trapz and element-wise math. The full list is in llms.txt.

Example scripts

-

The repository's corpus/ holds three realistic scripts that combine many constructs, translated from .m to Python in the test suite.

+

The repository's corpus/ holds six realistic scripts that combine many constructs, translated from .m to Python in the test suite.

@@ -348,14 +346,17 @@

Example scripts

- - + + + + +
Results for the example scripts, .m to Python
ode_rk4.m23230Yes
beam_deflection.m30291: fprintf is guidedNo
signal_filter.m33294: filter has no rule, and two max calls depend on its resultNo
beam_deflection.m30300Yes
signal_filter.m33330Yes
least_squares_fit.m27261: cond has no ruleNo
data_statistics.m28271: round of an expression is declinedNo
grid_heat.m26206: trapz along a dimension, ind2sub, and shapes lost after slicingNo
-

In the other direction, the Python that dualect writes for ode_rk4.m translates back to .m completely and verifies against that Python.

+

In the other direction, the Python that dualect writes for the three complete scripts translates back to .m completely and verifies against that Python.

Not supported yet

-

Any construct without a rule is reported as unsupported. Today that includes cell arrays, structs, plotting, random numbers, file input and output, and most built-in functions beyond the list above, including filter. Classes (classdef), GUIs, Simulink, MEX files and toolboxes are out of scope for now.

+

Any construct without a rule is reported as unsupported. Today that includes cell arrays, structs, plotting, file input and output, and built-in functions beyond the list above. Classes (classdef), GUIs, Simulink, MEX files and toolboxes are out of scope for now.