Quantar 0.1.0__py3-none-any.whl

lang_systems/operators.py

@@ -0,0 +1,367 @@
+"""Generic operator registry and ``@operator`` decorator.
+
+Completely independent of quantum code -- it can be used for anything.
+
+Operator kinds are named by **how the operator is written**, which is usually
+what you care about:
+
+    kind          operands   example
+    ----------    --------   -------------------------
+    nullary       0          ``pi``
+    unary_pre     1          ``-x``, ``~x``
+    unary_post    1          ``x!``, ``x†``
+    binary        2          ``a <-> b``
+    ternary       3          ``a ? b : c``
+    callable      any        ``f(a, b, c)``
+    matrix        0          a gate factory returning an ``np.ndarray``
+
+``kind`` is optional and defaults to ``"callable"``. Common synonyms are
+accepted (``"unary"``/``"prefix"`` -> ``unary_pre``, ``"infix"`` -> ``binary``,
+...), so existing code keeps working. As a shortcut you can write
+``@operator.binary("CNOT")`` instead of ``@operator(kind="binary", name="CNOT")``.
+"""
+
+from functools import wraps
+from importlib import import_module
+from types import ModuleType
+from typing import Any, Callable, Literal
+
+
+OperatorKind = Literal[
+    "nullary",
+    "unary_pre",
+    "unary_post",
+    "binary",
+    "ternary",
+    "callable",
+    "matrix",
+]
+
+#: Every accepted kind, in a convenient order for docs/validation.
+OPERATOR_KINDS: tuple[str, ...] = (
+    "nullary",
+    "unary_pre",
+    "unary_post",
+    "binary",
+    "ternary",
+    "callable",
+    "matrix",
+    "gate"
+)
+
+#: Friendly synonyms, so the old names and obvious variations still work.
+_KIND_ALIASES: dict[str, str] = {
+    "constant": "nullary",
+    "value": "nullary",
+    "zero": "nullary",
+    "unary": "unary_pre",
+    "prefix": "unary_pre",
+    "pre": "unary_pre",
+    "postfix": "unary_post",
+    "post": "unary_post",
+    "infix": "binary",
+    "nary": "callable",
+    "any": "callable",
+    "func": "callable",
+    "gate": "matrix",
+    "gate_matrix": "matrix",
+}
+
+
+#: Operators that the language knows syntactically even before their runtime
+#: implementation is imported.  Keeping these names here means ``parse()`` does
+#: not have to import the quantum simulator just to recognise ``a <-> b``.
+BUILTIN_OPERATOR_KINDS: dict[str, str] = {
+    "<->": "binary",
+    "<-i->": "binary",
+    "<-s->": "binary",
+}
+
+
+def normalize_kind(kind: str) -> str:
+    """Return the canonical kind name for `kind` (or raise ``ValueError``)."""
+    if not isinstance(kind, str):
+        raise ValueError(f"Operator kind must be a string, got {type(kind).__name__}.")
+    key = _KIND_ALIASES.get(kind.strip().lower(), kind.strip().lower())
+    if key not in OPERATOR_KINDS:
+        raise ValueError(
+            f"Unknown operator kind {kind!r}. Choose one of: {', '.join(OPERATOR_KINDS)}."
+        )
+    return key
+
+
+# Global operator registry
+_global_operators: dict[str, Callable] = {}
+_operator_metadata: dict[str, dict[str, Any]] = {}
+
+
+def _mark(obj, name: str, kind: str, requires_instance: bool) -> None:
+    obj._operator_name = name
+    obj._is_operator = True
+    obj._requires_instance = requires_instance
+    obj._kind = kind
+
+
+def _register(name: str, kind: str, func: Callable) -> Callable:
+    if not isinstance(name, str) or not name:
+        raise ValueError("Operator name must be a non-empty string")
+    kind = normalize_kind(kind)
+
+    # Handle staticmethod/classmethod
+    if isinstance(func, (staticmethod, classmethod)):
+        func = func.__func__
+
+    # For matrix kind, call once now to validate and cache the matrix.
+    if kind == "matrix":
+        import numpy as np
+
+        try:
+            matrix = func()
+        except TypeError as error:
+            if "missing 1 required positional argument: 'self'" in str(error):
+                # Instance method: defer the call until an instance is supplied.
+                def instance_wrapper(instance):
+                    return func(instance)
+
+                _mark(instance_wrapper, name, kind, True)
+                _global_operators[name] = instance_wrapper
+                _operator_metadata[name] = {"kind": kind, "requires_instance": True}
+                _mark(func, name, kind, True)
+                return func
+            raise
+
+        if not isinstance(matrix, np.ndarray):
+            raise ValueError(f"Operator function '{name}' must return a numpy array")
+
+        _mark(func, name, kind, False)
+        func._operator_matrix = matrix  # type: ignore[attr-defined]
+        _global_operators[name] = func
+        _operator_metadata[name] = {"kind": kind, "requires_instance": False}
+        return func
+
+    # unary_pre / unary_post / binary / ternary / nullary / callable
+    code = getattr(func, "__code__", None)
+    requires_instance = bool(code and "self" in code.co_varnames)
+    _mark(func, name, kind, requires_instance)
+    _global_operators[name] = func
+    _operator_metadata[name] = {"kind": kind, "requires_instance": requires_instance}
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    _mark(wrapper, name, kind, requires_instance)
+    return wrapper
+
+
+class operator:
+    """Register a callable under an arbitrary name.
+
+    The name can be any string: capital letters, symbols, unicode, etc. Works as
+    a function, method, or class decorator (or with any Python callable).
+
+    Examples::
+
+        @operator(kind="matrix", name="h")
+        def h_MAT(): ...
+
+        @operator.binary("<->")
+        def swap(control, target): ...
+
+        @operator.unary_post("†")
+        def adjoint(qubit): ...
+
+    ``kind`` may be omitted (default ``"callable"``).
+    """
+
+    def __init__(self, name: str, kind: OperatorKind = "callable"):
+        self.name = name
+        self.kind = kind
+
+    def __call__(self, func: Callable) -> Callable:
+        return _register(self.name, self.kind, func) #type: ignore
+
+    # ─── Convenience constructors ───
+
+    @classmethod
+    def nullary(cls, name: str) -> "operator":
+        return cls(name, "nullary")
+
+    @classmethod
+    def unary_pre(cls, name: str) -> "operator":
+        return cls(name, "unary_pre")
+
+    @classmethod
+    def unary_post(cls, name: str) -> "operator":
+        return cls(name, "unary_post")
+
+    @classmethod
+    def binary(cls, name: str) -> "operator":
+        return cls(name, "binary")
+
+    @classmethod
+    def ternary(cls, name: str) -> "operator":
+        return cls(name, "ternary")
+
+    @classmethod
+    def callable(cls, name: str) -> "operator": 
+        return cls(name, "callable")
+
+    @classmethod
+    def matrix(cls, name: str) -> "operator":
+        return cls(name, "matrix")
+
+
+# ─── Public API ───
+
+def get_global_operator(name: str):
+    """Retrieve a registered operator by name.
+
+    Returns ``(operator, kind)``; ``kind`` is one of :data:`OPERATOR_KINDS`, or
+    ``None`` when the name is not registered.
+    """
+    op = _global_operators.get(name)
+    if op is None:
+        return None, None
+    return op, getattr(op, "_kind", "callable")
+
+
+def get_operator(name: str):
+    """Alias for get_global_operator (backwards compatibility)."""
+    return get_global_operator(name)
+
+
+def get_operator_kind(name: str) -> str | None:
+    """Get the canonical kind of a registered operator."""
+    meta = _operator_metadata.get(name)
+    return meta.get("kind") if meta else None
+
+
+def get_known_operator_kind(name: str) -> str | None:
+    """Get the kind of a registered or built-in operator."""
+    kind = get_operator_kind(name)
+    if kind is not None:
+        return kind
+    return BUILTIN_OPERATOR_KINDS.get(name)
+
+
+def is_known_operator(name: str) -> bool:
+    """Return whether `name` is a registered or built-in operator."""
+    return name in _global_operators or name in BUILTIN_OPERATOR_KINDS
+
+
+def get_operator_requires_instance(name: str) -> bool:
+    """Check if an operator requires an instance (is a method)."""
+    meta = _operator_metadata.get(name)
+    return meta.get("requires_instance", False) if meta else False
+
+
+def get_global_operator_matrix(name: str):
+    """Retrieve a registered matrix operator by name."""
+    op, kind = get_global_operator(name)
+    if kind == "matrix" and callable(op):
+        try:
+            return op()
+        except TypeError:
+            # Instance method: can't call without an instance.
+            return op
+    return None
+
+
+def get_operator_matrix(name: str):
+    """Alias for get_global_operator_matrix (backwards compatibility)."""
+    return get_global_operator_matrix(name)
+
+
+def list_operators(kind: str | None = None) -> list[str]:
+    """List registered operator names, optionally filtered to one `kind`."""
+    if kind is None:
+        return list(_global_operators.keys())
+    wanted = normalize_kind(kind)
+    return [name for name in _global_operators if _operator_metadata.get(name, {}).get("kind") == wanted]
+
+def list_known_operators() -> dict[str, str]:
+    """Return every registered and built-in operator mapped to its kind."""
+    names = set(list_operators()) | set(BUILTIN_OPERATOR_KINDS)
+    return {
+        name: get_known_operator_kind(name) or "callable"
+        for name in names
+    }
+
+
+def load_operators(*modules: str | ModuleType) -> tuple[ModuleType, ...]:
+    """Import operator modules so their registrations take effect.
+
+    Strings are imported with :func:`importlib.import_module`; module objects
+    are accepted as-is. Call this before :func:`lang_systems.parse` when the
+    source uses operators defined by another package::
+
+        from lang_systems import parse
+        from lang_systems.operators import load_operators
+
+        load_operators("my_package.quantar_ops")
+        tree = parse("a >< b\\n")
+
+    Returns the loaded modules in the order given.
+    """
+    loaded = []
+    for module in modules:
+        if isinstance(module, str):
+            loaded.append(import_module(module))
+        elif isinstance(module, ModuleType):
+            loaded.append(module)
+        else:
+            raise TypeError(
+                "load_operators() expects module names or module objects, "
+                f"got {type(module).__name__}"
+            )
+    return tuple(loaded)
+
+
+def clear_operators():
+    """Clear all registered operators (useful for testing)."""
+    _global_operators.clear()
+    _operator_metadata.clear()
+
+
+def apply_operator(name: str, *args, **kwargs) -> Any:
+    """Execute a registered operator by name with the given arguments.
+
+    Raises:
+        ValueError: If the operator is unknown or needs an instance.
+    """
+    op, kind = get_operator(name)
+    if op is None:
+        raise ValueError(f"Unknown operator: '{name}'")
+
+    meta = _operator_metadata.get(name, {})
+    if meta.get("kind") == "matrix" and callable(op):
+        try:
+            return op()
+        except TypeError as error:
+            if "missing 1 required positional argument: 'self'" in str(error):
+                raise ValueError(f"Operator '{name}' is a method and requires an instance") from error
+            raise
+
+    return op(*args, **kwargs)
+
+
+__all__ = [
+    "operator",
+    "OperatorKind",
+    "OPERATOR_KINDS",
+    "normalize_kind",
+    "BUILTIN_OPERATOR_KINDS",
+    "get_operator",
+    "get_global_operator",
+    "get_global_operator_matrix",
+    "get_operator_kind",
+    "get_known_operator_kind",
+    "is_known_operator",
+    "get_operator_requires_instance",
+    "get_operator_matrix",
+    "list_operators",
+    "clear_operators",
+    "apply_operator",
+    "list_known_operators",
+]

lang_systems/pegen_gram_gen.py

@@ -0,0 +1,159 @@
+"""Generate ``src/lang_systems/quantar_parser.py``.
+
+Quantar is a *superset* of Python: this builds its parser from the vendored
+CPython grammar (``Grammar/python.gram``) plus the small operator overlay in
+``src/lang_systems/quantar.gram``.
+
+pegen 0.3.0 is the last PyPI release and predates several things we need, so a
+few fixes are applied before generating (each one is marked below). Run directly
+with::
+
+    python -m lang_systems.pegen_gram_gen
+
+or let the build do it (see ``hatch_build.py``).
+"""
+
+import sys
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+ROOT = PACKAGE_ROOT.parent.parent
+BASE_GRAMMAR = ROOT / "Grammar" / "python.gram"
+OVERLAY_GRAMMAR = PACKAGE_ROOT / "quantar.gram"
+MERGED_GRAMMAR = ROOT / "Grammar" / "quantar_merged.gram"
+OUTPUT_PARSER = PACKAGE_ROOT / "quantar_parser.py"
+
+# Pseudo-tokens the overlay grammar references; implemented at runtime in
+# lang_systems/quantar.py (registered here so pegen's checker accepts them).
+EXTRA_TOKENS = {"QUANTUM_OP", "QUANTUM_NAME"}
+
+# CPython grammar rules whose names collide (case-insensitively) with pegen's
+# base token methods (e.g. rule `string` vs the STRING token method). pegen
+# 0.3.0 case-folds and generates `self.string()` -> infinite recursion, so the
+# rules are renamed.
+COLLIDING_RULES = {
+    "name",
+    "number",
+    "string",
+    "fstring_start",
+    "fstring_middle",
+    "fstring_end",
+    "op",
+    "type_comment",
+    "soft_keyword",
+}
+
+# Splice that gives custom operators their precedence (between `comparison`
+# and `bitwise_or`); see the header of lang_systems/quantar.gram. The comparison
+# left operand and every comparison RHS become `quantum_expr`.
+COMPARISON_OLD = "comparison[expr_ty]:\n    | a=bitwise_or b=compare_op_bitwise_or_pair+"
+COMPARISON_NEW = "comparison[expr_ty]:\n    | a=quantum_expr b=compare_op_bitwise_or_pair+"
+COMPARISON_BASE_OLD = "\n    | bitwise_or\n\ncompare_op_bitwise_or_pair["
+COMPARISON_BASE_NEW = "\n    | quantum_expr\n\ncompare_op_bitwise_or_pair["
+COMPARE_PAIRS_START = "compare_op_bitwise_or_pair[CmpopExprPair*]:"
+COMPARE_PAIRS_END = "# Bitwise operators"
+
+
+def _allow_comparison_rhs_operators(base: str) -> str:
+    """Use `quantum_expr` on both sides of comparisons, not just the left."""
+    start = base.find(COMPARE_PAIRS_START)
+    end = base.find(COMPARE_PAIRS_END, start)
+    if start == -1 or end == -1:
+        raise RuntimeError(
+            "Could not find the comparison operator rules to splice; the "
+            "vendored Grammar/python.gram changed."
+        )
+    block = base[start:end].replace("a=bitwise_or", "a=quantum_expr")
+    return base[:start] + block + base[end:]
+
+
+def _build_grammar_text() -> str:
+    base = BASE_GRAMMAR.read_text(encoding="utf-8")
+    for old in (COMPARISON_OLD, COMPARISON_BASE_OLD):
+        if old not in base:
+            raise RuntimeError(
+                "Could not find the `comparison` rule to splice; the vendored "
+                "Grammar/python.gram changed. Update the COMPARISON_* constants."
+            )
+    base = base.replace(COMPARISON_OLD, COMPARISON_NEW, 1)
+    base = base.replace(COMPARISON_BASE_OLD, COMPARISON_BASE_NEW, 1)
+    base = _allow_comparison_rhs_operators(base)
+    overlay = OVERLAY_GRAMMAR.read_text(encoding="utf-8")
+    merged = base + "\n" + overlay
+
+    MERGED_GRAMMAR.write_text(merged, encoding="utf-8")
+    return merged
+
+
+def build() -> None:
+    # The full CPython grammar is deep; generation recurses a lot.
+    sys.setrecursionlimit(200_000)
+
+    import token
+
+    from pegen.build import build_parser
+    from pegen.grammar import Alt, NameLeaf
+    from pegen.python_generator import (
+        PythonCallMakerVisitor,
+        PythonParserGenerator,
+    )
+
+    # pegen 0.3.0 predates t-strings (Python 3.14). Map TSTRING_* tokens to
+    # expect() instead of a (nonexistent) self.TSTRING_START() method.
+    original_name_leaf = PythonCallMakerVisitor.visit_NameLeaf
+
+    def patched_name_leaf(self, node):
+        name = node.value
+        if name in ("TSTRING_START", "TSTRING_MIDDLE", "TSTRING_END"):
+            return "_" + name.lower(), f"self.expect({name!r})"
+        return original_name_leaf(self, node)
+
+    PythonCallMakerVisitor.visit_NameLeaf = patched_name_leaf
+
+    _build_grammar_text()
+    grammar, _, _ = build_parser(str(MERGED_GRAMMAR))
+
+    # pegen 0.3.0 ignores --skip-actions (a `# TODO` in the source) and still
+    # ast.parse()s every action, so the CPython C actions must be removed. The
+    # `@trailer` meta (C `_PyPegen_parse`) and the `[return_type]` annotations
+    # would also leak into the generated Python, so drop those too.
+    grammar.metas = {"trailer": ""} #type: ignore
+    renames = {r: r + "_rule" for r in COLLIDING_RULES if r in grammar.rules}
+
+    def strip(node, seen):
+        if id(node) in seen:
+            return
+        seen.add(id(node))
+        if isinstance(node, Alt) and node.action:
+            node.action = None
+        if isinstance(node, NameLeaf):
+            if node.value in renames:
+                node.value = renames[node.value]
+            return
+        for value in vars(node).values():
+            if isinstance(value, list):
+                for item in value:
+                    strip(item, seen)
+            elif hasattr(value, "__dict__"):
+                strip(value, seen)
+
+    seen = set()
+    for rule in grammar.rules.values():
+        rule.type = None
+        strip(rule.rhs, seen)
+
+    for old, new in renames.items():
+        rule = grammar.rules.pop(old)
+        rule.name = new
+        grammar.rules[new] = rule
+
+    tokens = set(token.tok_name.values()) | EXTRA_TOKENS
+    with open(OUTPUT_PARSER, "w", encoding="utf-8") as out:
+        generator = PythonParserGenerator(grammar, out, tokens=tokens)
+        generator.generate(str(MERGED_GRAMMAR))
+
+    print(f"Generated {OUTPUT_PARSER.relative_to(ROOT)} ({len(grammar.rules)} rules)")
+
+
+if __name__ == "__main__":
+    build()

lang_systems/quantar.gram

@@ -0,0 +1,27 @@
+# Quantar custom-operator extension.
+#
+# `hatch_build.py` (via lang_systems.pegen_gram_gen) splices this onto the vendored
+# CPython grammar (Grammar/python.gram) and generates lang_systems/quantar_parser.py.
+# Everything below is the *only* quantum-specific grammar; the whole rest of
+# Python is inherited, so quantar is a strict superset of Python.
+#
+# Operators are matched against the `quantar.operators` registry at runtime, in
+# two forms (see lang_systems/quantar.py):
+#
+#   symbolic    a  <->  b        matched by QUANTUM_OP   (lang_systems/quantar_tokens.py)
+#   identifier  a  CNOT  b       matched by QUANTUM_NAME (any registered NAME)
+#
+# Precedence: custom operators bind *between* `comparison` and `bitwise_or`,
+# on both sides of a comparison. lang_systems.pegen_gram_gen rewires
+# `comparison: a=quantum_expr ...`; to move the level, change that splice and
+# the rule living here. The resulting order, loosest to tightest, is:
+#
+#   or > and > not > comparisons > quantum_operator > | ^ & << >> > + - > * / ...
+
+quantum_expr[expr_ty]:
+    | a=quantum_expr quantum_operator b=bitwise_or
+    | bitwise_or
+
+quantum_operator[expr_ty]:
+    | QUANTUM_OP
+    | QUANTUM_NAME

lang_systems/quantar.py

@@ -0,0 +1,63 @@
+"""Parse Quantar source into a parse tree.
+
+Quantar is a superset of Python, so the parser is generated from CPython's
+grammar (see lang_systems/pegen_gram_gen.py) plus a small operator overlay. This
+module adds the two custom-operator token matchers the overlay refers to and a
+convenient :func:`parse` entry point.
+
+The result is pegen's raw tree (nested lists of tokens and sub-nodes); turning
+it into an AST or executing it is intentionally a separate concern.
+"""
+
+import sys
+import token
+
+from pegen.tokenizer import Tokenizer
+
+from lang_systems.quantar_parser import GeneratedParser
+from lang_systems.quantar_tokens import tokenize_source
+from lang_systems.operators import is_known_operator
+
+# The generated parser is deep; parsing the CPython grammar needs headroom.
+_RECURSION_LIMIT = 200_000
+
+
+class QuantarParser(GeneratedParser):
+    """The generated Python parser plus Quantar's custom-operator matchers."""
+
+    def QUANTUM_OP(self):
+        """Match a symbolic operator (e.g. ``<->``) known to the language."""
+        peeked = self._tokenizer.peek()
+        if peeked.type == token.OP and is_known_operator(peeked.string):
+            return self._tokenizer.getnext()
+        return None
+
+    def QUANTUM_NAME(self):
+        """Match an identifier operator (e.g. ``CNOT``) known to the language."""
+        peeked = self._tokenizer.peek()
+        if (
+            peeked.type == token.NAME
+            and peeked.string not in self.KEYWORDS
+            and is_known_operator(peeked.string)
+        ):
+            return self._tokenizer.getnext()
+        return None
+
+
+def parse(source: str):
+    """Parse `source` and return the raw parse tree (the grammar's `file` rule).
+
+    Raises:
+        SyntaxError: If `source` is not valid Quantar.
+    """
+    sys.setrecursionlimit(max(sys.getrecursionlimit(), _RECURSION_LIMIT))
+    tokenizer = Tokenizer(tokenize_source(source))
+    parser = QuantarParser(tokenizer)
+    tree = parser.file()
+    if tree is None:
+        bad = parser._tokenizer.peek()
+        raise SyntaxError(
+            f"invalid Quantar syntax near {bad.string!r}",
+            ("<quantar>", bad.start[0], bad.start[1] + 1, bad.line),
+        )
+    return tree