algo2code 0.2.1__tar.gz → 0.2.2__tar.gz

{algo2code-0.2.1 → algo2code-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: algo2code
-Version: 0.2.1
+Version: 0.2.2
 Summary: Transpile LaTeX algorithm boxes (algpseudocode) to executable Taichi/NumPy/C code
 Project-URL: Repository, https://github.com/CEmM2/MechDSL
 Author: Shmuel Osovski
@@ -17,7 +17,14 @@ Description-Content-Type: text/markdown
 
 # algo2code
 
-Transpile LaTeX algorithm boxes (`algpseudocode`) to executable code targeting Taichi, NumPy, or C/PETSc.
+Transpile LaTeX algorithm boxes (`algpseudocode`) to executable code targeting Taichi or NumPy (C/PETSc planned).
+
+```python
+from algo2code import transpile
+
+transpile(source, backend="taichi")  # Taichi kernels + Python driver
+transpile(source, backend="numpy")   # plain function that imports only NumPy
+```
 
 Parses `\begin{algorithmic}...\end{algorithmic}` environments with type-directed code generation.
 Zero runtime dependencies — standard library only.

{algo2code-0.2.1 → algo2code-0.2.2}/README.md

@@ -1,6 +1,13 @@
 # algo2code
 
-Transpile LaTeX algorithm boxes (`algpseudocode`) to executable code targeting Taichi, NumPy, or C/PETSc.
+Transpile LaTeX algorithm boxes (`algpseudocode`) to executable code targeting Taichi or NumPy (C/PETSc planned).
+
+```python
+from algo2code import transpile
+
+transpile(source, backend="taichi")  # Taichi kernels + Python driver
+transpile(source, backend="numpy")   # plain function that imports only NumPy
+```
 
 Parses `\begin{algorithmic}...\end{algorithmic}` environments with type-directed code generation.
 Zero runtime dependencies — standard library only.

{algo2code-0.2.1 → algo2code-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "algo2code"
-version = "0.2.1"
+version = "0.2.2"
 description = "Transpile LaTeX algorithm boxes (algpseudocode) to executable Taichi/NumPy/C code"
 readme = "README.md"
 license = "MIT"

{algo2code-0.2.1 → algo2code-0.2.2}/src/algo2code/__init__.py

@@ -1,6 +1,6 @@
 """algo2code — Transpile LaTeX algorithm boxes (algpseudocode) to executable code.
 
-Targets: Taichi (MVP), NumPy, C/PETSc.
+Targets: Taichi, NumPy (C/PETSc planned).
 
 Usage:
     from algo2code import transpile
@@ -8,10 +8,11 @@ Usage:
     taichi_code = transpile(latex_source, backend='taichi')
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 from .algo_parser import parse_algorithm
 from .ast_nodes import Algorithm, VarType
+from .backends.numpy_codegen import generate_numpy
 from .backends.taichi_codegen import (
     RUNTIME_INLINE,
     RUNTIME_TI_RUNTIME,
@@ -33,9 +34,11 @@ def transpile(source: str, backend: str = "taichi", runtime: str = "inline") ->
         LaTeX source containing \\begin{algorithmic} ... \\end{algorithmic}
         with optional % directive comments.
     backend : str
-        Target backend. Currently only 'taichi' is supported.
+        Target backend: ``"taichi"`` (default) or ``"numpy"``. The NumPy
+        backend emits a plain function that imports only ``numpy``, so the
+        result runs without Taichi installed.
     runtime : str
-        Import mode for the Taichi backend.  ``"inline"`` (default) emits
+        Import mode for the Taichi backend (ignored by ``"numpy"``).  ``"inline"`` (default) emits
         private ``@ti.kernel`` definitions inline.  ``"ti_runtime"`` emits
         ``from ti_runtime import vector_ops as _v`` and calls the shared
         primitives for dot/norm/copy.  algo2code itself never imports
@@ -51,8 +54,9 @@ def transpile(source: str, backend: str = "taichi", runtime: str = "inline") ->
 
     if backend == "taichi":
         return generate_taichi(algo, runtime=runtime)
-    else:
-        raise ValueError(f"Unknown backend: {backend!r}. Supported: 'taichi'")
+    if backend == "numpy":
+        return generate_numpy(algo)
+    raise ValueError(f"Unknown backend: {backend!r}. Supported: 'taichi', 'numpy'")
 
 
 __all__ = [
@@ -63,6 +67,7 @@ __all__ = [
     "Algorithm",
     "UnsupportedConstructError",
     "VarType",
+    "generate_numpy",
     "generate_taichi",
     "get_pcg_algorithm_latex",
     "infer_types",

algo2code-0.2.2/src/algo2code/backends/numpy_codegen.py

@@ -0,0 +1,154 @@
+"""
+NumPy code generator.
+
+Takes the same typed Algorithm AST as the Taichi backend and emits a plain
+Python function that depends on NumPy only. The generated module never
+imports Taichi, so algorithms transpiled with this backend run on a lean
+install (no ``[verify]`` extra).
+
+The lowering mirrors :class:`~algo2code.backends.taichi_codegen.TaichiEmitter`
+statement for statement, so the two backends agree on semantics:
+
+  - Scalar arithmetic and control flow are emitted exactly as in the Taichi
+    driver (plain Python on floats), so a scalar-only algorithm produces the
+    same function body under both backends and yields bit-identical results.
+  - Vector/matrix variables are ``numpy.ndarray`` buffers. Local working
+    vectors are allocated once with ``np.zeros(n)`` and every vector operation
+    writes *in place* (``out[...] = ...``), matching the Taichi field model:
+    a vector argument updated by the algorithm is updated for the caller too.
+  - Callables keep the in-place seam contract of the Taichi backend:
+    ``M_inv(r, z)`` writes into ``z``, and a matrix-free operator declared
+    ``% type A callable`` is applied as ``A(out, p)``.
+  - ``dot`` lowers to ``float(np.dot(a, b))``, ``norm`` to
+    ``float(np.linalg.norm(a))``, a stored-matrix product to ``A @ x``.
+"""
+
+from __future__ import annotations
+
+from ..ast_nodes import Algorithm, Assign, BinOp, Expr, FuncCall, UnaryOp, Var, VarType
+from ..errors import UnsupportedConstructError
+from .taichi_codegen import (
+    RUNTIME_INLINE,
+    TaichiEmitter,
+    _collect_arg_names,
+    _collect_vector_vars,
+    _var_name,
+)
+
+
+class NumpyEmitter(TaichiEmitter):
+    """Emit a NumPy-only Python function from a typed Algorithm AST."""
+
+    BACKEND_DOC = "Backend: NumPy (CPU)"
+
+    def __init__(self, algo: Algorithm):
+        super().__init__(algo, runtime=RUNTIME_INLINE)
+
+    def emit(self) -> str:
+        """Generate the complete NumPy source."""
+        self._arg_names = _collect_arg_names(self.algo)
+        self._vector_vars = _collect_vector_vars(self.algo)
+        self._pre_scan_temps(self.algo.body)
+
+        parts = ["import numpy as np\n", "# ── Solver driver " + "─" * 57, self._emit_driver()]
+        return "\n\n".join(parts) + "\n"
+
+    # ── Allocation ───────────────────────────────────────────────────────
+
+    def _vector_field_alloc(self, vec_arg: str | None) -> str:
+        return "np.zeros(n)"
+
+    # ── Expressions ──────────────────────────────────────────────────────
+
+    def _emit_assign(self, stmt: Assign) -> None:
+        target = _var_name(stmt.target)
+        target_type = self.algo.type_annotations.get(stmt.target.display, stmt.target.inferred_type)
+        if (
+            target_type == VarType.VECTOR
+            and isinstance(stmt.value, Var)
+            and stmt.value.inferred_type == VarType.VECTOR
+        ):
+            self._write(f"{target}[...] = {_var_name(stmt.value)}")
+            return
+        super()._emit_assign(stmt)
+
+    def _emit_unary(self, expr: UnaryOp) -> str:
+        if expr.op == "norm" and expr.operand.inferred_type != VarType.SCALAR:
+            return f"float(np.linalg.norm({self._emit_expr_str(expr.operand)}))"
+        return super()._emit_unary(expr)
+
+    def _emit_dot(self, expr: BinOp) -> str:
+        left = expr.left
+        if isinstance(left, UnaryOp) and left.op == "transpose":
+            left = left.operand
+        return f"float(np.dot({self._emit_expr_str(left)}, {self._emit_expr_str(expr.right)}))"
+
+    def _emit_func_call_name(self, expr: FuncCall) -> str:
+        if isinstance(expr.func, Var) and _var_name(expr.func) == "sqrt":
+            return "np.sqrt"
+        return super()._emit_func_call_name(expr)
+
+    # ── Vector lowering (in-place writes into ndarray buffers) ───────────
+
+    def _lower_vector_expr(self, expr: Expr, dest: str | None) -> str:
+        if isinstance(expr, Var):
+            name = _var_name(expr)
+            if dest is not None and dest != name:
+                self._write(f"{dest}[...] = {name}")
+                return dest
+            return name
+
+        if isinstance(expr, FuncCall):
+            out = dest if dest is not None else self._get_temp()
+            func = self._emit_func_call_name(expr)
+            args = ", ".join(self._emit_expr_str(a) for a in expr.args)
+            self._write(f"{func}({args}, {out})")
+            return out
+
+        if isinstance(expr, UnaryOp) and expr.op == "neg":
+            vec = self._lower_to_field(expr.operand)
+            out = dest if dest is not None else self._get_temp()
+            self._write(f"{out}[...] = -{vec}")
+            return out
+
+        if isinstance(expr, BinOp):
+            if expr.op == "matvec":
+                out = dest if dest is not None else self._get_temp()
+                vec = self._lower_to_field(expr.right)
+                if expr.left.inferred_type == VarType.CALLABLE:
+                    self._write(f"{self._emit_expr_str(expr.left)}({out}, {vec})")
+                    return out
+                self._write(f"{out}[...] = {self._emit_expr_str(expr.left)} @ {vec}")
+                return out
+
+            if expr.op in ("scale", "*"):
+                scalar, vec_expr = self._split_scale(expr)
+                if scalar is not None and vec_expr is not None:
+                    vec = self._lower_to_field(vec_expr)
+                    out = dest if dest is not None else self._get_temp()
+                    self._write(f"{out}[...] = {scalar} * {vec}")
+                    return out
+
+            if expr.op in ("+", "-"):
+                left = self._lower_to_field(expr.left)
+                coeff, right = self._lower_addend(expr.right)
+                beta = self._negate(coeff) if expr.op == "-" else coeff
+                out = dest if dest is not None else self._get_temp()
+                self._write(f"{out}[...] = {left} + {beta} * {right}")
+                return out
+
+        raise UnsupportedConstructError(
+            f"cannot lower vector expression to NumPy ops: {expr!r}. "
+            f"Supported vector forms are copy, callable application, matvec, "
+            f"scalar*vector, and vector +/- vector."
+        )
+
+
+def generate_numpy(algo: Algorithm) -> str:
+    """Generate NumPy source code from a typed Algorithm AST.
+
+    The emitted module imports only ``numpy`` and defines one function named
+    after the algorithm, with the same signature and return values as the
+    Taichi backend's driver.
+    """
+    return NumpyEmitter(algo).emit()

{algo2code-0.2.1 → algo2code-0.2.2}/src/algo2code/backends/taichi_codegen.py

@@ -18,9 +18,9 @@ Import modes (``runtime`` parameter of :func:`generate_taichi`):
     each generated file — backward-compatible, no runtime dependency.
   - ``"ti_runtime"``: emit ``from ti_runtime import vector_ops as _v`` and call
     the shared primitives for ``dot``/``norm``/``copy``/``vec_add``; only
-    ``_matvec`` remains inlined (the matrix-free operator seam is P2-2's
-    concern).  algo2code itself never imports ``ti_runtime`` — it only *emits*
-    the import line.
+    ``_matvec`` remains inlined (the matrix-free operator is injected through
+    the seam by the consumer).  algo2code itself never imports ``ti_runtime`` —
+    it only *emits* the import line.
 
 Compatibility note (``"ti_runtime"`` mode):
   ``ti_runtime.vector_ops.dot`` uses ``x[I].dot(y[I])`` which requires
@@ -29,7 +29,7 @@ Compatibility note (``"ti_runtime"`` mode):
   the consumer passes scalar fields.  Callers that use vector fields (e.g.
   mechdsl FEM drivers) are unaffected.  This is a known field-model mismatch;
   resolving it (either by changing the emitted field model to ``ti.Vector.field``
-  or by adding scalar variants to ti_runtime) is out of scope for P2-1.
+  or by adding scalar variants to ti_runtime) is out of scope for this backend.
 """
 
 from __future__ import annotations
@@ -177,7 +177,7 @@ class KernelCollector:
         In ``"ti_runtime"`` mode the shared primitives (dot/norm/copy/vec_add)
         are called via the ``_v`` alias imported from ``ti_runtime.vector_ops``.
         Only ``_matvec`` has no ti_runtime equivalent and remains inlined
-        (the matrix-free operator seam is P2-2's concern).
+        (the matrix-free operator is injected through the seam by the consumer).
         """
         lines = []
         if runtime == RUNTIME_TI_RUNTIME:
@@ -266,6 +266,9 @@ class TaichiEmitter:
         docstring for the full description of each mode.
     """
 
+    #: Backend line written into the generated driver's docstring.
+    BACKEND_DOC = "Backend: Taichi (GPU)"
+
     def __init__(self, algo: Algorithm, runtime: str = RUNTIME_INLINE):
         self.algo = algo
         self.runtime = runtime
@@ -341,7 +344,7 @@ class TaichiEmitter:
 
         self._write('"""')
         self._write("Auto-generated from LaTeX algorithmic environment.")
-        self._write("Backend: Taichi (GPU)")
+        self._write(self.BACKEND_DOC)
         self._write('"""')
 
         vec_arg = self._first_vector_arg()
@@ -394,8 +397,8 @@ class TaichiEmitter:
         locals matching the *vector argument's* component layout (``<arg>.n``):
         the ``ti_runtime`` ``dot``/``norm2`` primitives use ``x[I].dot(y[I])``,
         which requires vector fields. This is what lets the matrix-free seam
-        (P2-2) run end-to-end against ``ti_runtime`` (resolving the field-model
-        mismatch P2-1 documented). With no vector argument the component count
+        run end-to-end against ``ti_runtime`` (resolving the field-model
+        mismatch documented above). With no vector argument the component count
         is unknown, so fall back to the scalar layout.
         """
         if self.runtime == RUNTIME_TI_RUNTIME and vec_arg is not None:
@@ -847,7 +850,8 @@ def generate_taichi(algo: Algorithm, runtime: str = RUNTIME_INLINE) -> str:
         ``"ti_runtime"``
             Emit ``from ti_runtime import vector_ops as _v`` and call the
             shared primitives for dot/norm/copy/vec_add.  Only ``_matvec``
-            remains inlined (the matrix-free operator seam is P2-2's concern).
+            remains inlined (the matrix-free operator is injected through the
+            seam by the consumer).
             algo2code itself never imports ti_runtime — it only emits the
             import line.
 

{algo2code-0.2.1 → algo2code-0.2.2}/src/algo2code/expr_parser.py

@@ -225,8 +225,7 @@ class ExprParser:
 
         Division at the term level shares precedence with multiplication
         (left-associative) so ``a + b / c`` parses as ``a + (b / c)``
-        rather than dropping the divisor. post_recovery_plan Phase 5
-        parser fix.
+        rather than dropping the divisor.
         """
         left = self.parse_signed_factor()
         while True:

{algo2code-0.2.1 → algo2code-0.2.2}/src/algo2code/library/__init__.py

@@ -6,14 +6,25 @@ small helper that returns it (and, where the parser supports it, the parsed
 here instead of re-typing or re-inventing the algorithm text — this is the
 canonical hand-off seam between ``algo2code`` and any consumer that wants a
 reference implementation of a textbook iterative solver.
+
+The verbatim ``.tex`` sources live in ``algo2code/library/algorithms/`` and
+ship as package data; :func:`algorithm_source` reads any of them by name.
 """
 
 from algo2code.library.pcg import (
     PCG_ALGORITHM_LATEX,
     get_pcg_algorithm_latex,
 )
+from algo2code.library.sources import (
+    ALGORITHM_SOURCES,
+    algorithm_source,
+    algorithm_source_path,
+)
 
 __all__ = [
+    "ALGORITHM_SOURCES",
     "PCG_ALGORITHM_LATEX",
+    "algorithm_source",
+    "algorithm_source_path",
     "get_pcg_algorithm_latex",
 ]

algo2code-0.2.2/src/algo2code/library/algorithms/jacobi.tex

@@ -0,0 +1,51 @@
+% Point-Jacobi preconditioner apply.
+%
+% Computes the Jacobi (diagonal) preconditioned vector:
+%
+%     z_I = r_I / max(d_I, eps)
+%
+% where ``d`` is the diagonal of the system matrix (point-Jacobi: M = diag(d)),
+% ``r`` is the residual vector, ``z`` is the output (M^{-1} r), and ``eps`` is a
+% small positive guard against near-zero diagonal entries. All operands are
+% degree-of-freedom vectors (one value per node or per component).
+%
+% Grammar note:
+% -------------
+% algo2code currently lowers vector/vector division (`z = r / d`) to the Python
+% expression `z = (r / d)`, which is not runnable for `ti.Vector.field` operands
+% (Taichi raises TypeError: unsupported operand type(s) for /: MatrixField /
+% MatrixField).  The grammar supports scalar operations and vector +/-/scale/
+% callable-matvec, but has no `vec_ediv` (elementwise divide) primitive.
+%
+% The clean fix is a new `vec_ediv(z, r, d, eps)` primitive in ti_runtime
+% vector_ops.  The generated body below is therefore
+% realised as a thin `@ti.data_oriented` adapter
+% (`mechdsl.solver.jacobi_preconditioner.GeneratedJacobiPreconditioner`) whose
+% `_apply` kernel calls `ti_runtime.vector_ops.ediv(z, r, d, eps)` — a
+% generated body in the sense that the algorithm is expressed in LaTeX and
+% realised via a structured adapter, not hand-coded heuristics.
+%
+% When algo2code gains a `vec_ediv` primitive (or scalar-field elementwise ops),
+% this box can be re-transpiled to a fully auto-generated driver with no adapter
+% shim.
+%
+% Inputs
+% ------
+%   r   : residual vector (numerator)
+%   d   : diagonal vector (denominator)
+%   eps : small positive guard (scalar)  -- assumed positive (SPD diagonal guard)
+%
+% Output
+% ------
+%   z   : preconditioned vector = M^{-1} r
+
+% algorithm jacobi_apply
+% backend taichi
+% args r:vector, d:vector, eps:scalar
+
+% type z vector
+
+\begin{algorithmic}
+\State $z_I = r_I \, / \, \max(d_I,\, \varepsilon)$   \Comment{elementwise; for all DOF indices $I$}
+\Return $z$
+\end{algorithmic}

algo2code-0.2.2/src/algo2code/library/algorithms/newmark.tex

@@ -0,0 +1,99 @@
+% Newmark-beta implicit time integration — single step.
+%
+% The canonical Newmark-beta step authored for the **all-Taichi on-device
+% time-integration seam path** (the temporal analogue of the matrix-free PCG in
+% ``pcg.tex``): the per-step acceleration solve ``solve_a`` is a *callable*
+% (matrix-free), so this box transpiles via
+% ``algo2code.transpile(..., runtime='ti_runtime')`` into a body that advances a
+% dynamic state ``(u, v, a)`` one step over ``ti.Vector.field`` DOF vectors
+% **without NumPy in the hot path** — every update is a ``ti_runtime.vector_ops``
+% AXPBY/copy call and the only non-primitive call is the injected ``solve_a``.
+%
+% Scheme (Hughes 2000, Box 9.1; Newmark 1959)
+% -------------------------------------------
+% For the semidiscrete equation of motion ``M a + C v + K u = F`` the Newmark
+% family advances ``(u_n, v_n, a_n) -> (u_{n+1}, v_{n+1}, a_{n+1})`` via the
+% predictor/corrector split:
+%
+%   predictors (known from step n):
+%       u_pred = u_n + dt*v_n + dt^2*(1/2 - beta)*a_n
+%       v_pred = v_n + dt*(1 - gamma)*a_n
+%
+%   acceleration solve (the only system solve — folded into the callable):
+%       a_{n+1} = solve_a(u_pred, v_pred)
+%       i.e. solve  (M + gamma*dt*C + beta*dt^2*K) a_{n+1}
+%                       = F_{n+1} - C*v_pred - K*u_pred
+%
+%   correctors:
+%       u_{n+1} = u_pred + beta*dt^2 * a_{n+1}
+%       v_{n+1} = v_pred + gamma*dt  * a_{n+1}
+%
+% gamma = 1/2 gives second-order accuracy; beta = 1/4 (with gamma = 1/2) is the
+% average-acceleration / trapezoidal rule — unconditionally stable, no numerical
+% damping. HHT-alpha is a one-parameter generalisation (alpha-weighted residual);
+% it reuses the same predictor/corrector skeleton and is intentionally NOT
+% authored here — Newmark-beta is the deliverable, HHT is optional/next.
+%
+% Seam contract (mirrors ti_runtime.seams.TimeIntegrationContext)
+% ---------------------------------------------------------------
+%   solve_a(u_pred, v_pred, a_out)   — acceleration solve: a_out = a_{n+1}
+%                                      (out LAST; the in-place callable convention,
+%                                       same shape as the PCG operator A(out, x)).
+% The callable owns the mass / damping / stiffness / external-force data; the box
+% is mass-/material-agnostic, exactly like ``pcg.tex`` is operator-agnostic.
+%
+% Grammar note
+% ------------
+% This box transpiles **directly** through algo2code in ``runtime='ti_runtime'``
+% mode with no grammar gap: the predictor/corrector updates are all
+% ``scalar*vector`` and ``vector +/- vector`` (fused ``_v.vec_add`` AXPBY calls),
+% the scalar coefficients ``c0..c3`` are plain scalar arithmetic, and the
+% acceleration solve is an in-place ``callable`` (``solve_a``) — the matrix-free
+% seam form (11-ALGO2CODE §8.3). No NumPy, no dense ``_matvec``. (Verified: the
+% emitted ``newmark_step`` body contains only ``_v.vec_add`` / ``_v.copy`` /
+% ``solve_a(...)``.)
+%
+% The two predictor scalar coefficients are precomputed into named scalars
+% (``c0``, ``c1``) and the corrector coefficients into (``c2``, ``c3``) so each
+% vector update fuses to a single AXPBY; ``dt`` itself is the predictor velocity
+% coefficient (``u + dt*v``).
+%
+% Inputs
+% ------
+%   u       : displacement vector at step n (carries the state; updated in place)
+%   v       : velocity     vector at step n (updated in place)
+%   a       : acceleration vector at step n (updated in place)
+%   solve_a : acceleration solve (callable, in-place ``solve_a(u_pred, v_pred, a_out)``)
+%   dt      : time step (scalar)
+%   beta    : Newmark beta  (scalar; 1/4 = average acceleration)
+%   gamma   : Newmark gamma (scalar; 1/2 = second order, no algorithmic damping)
+%
+% Output
+% ------
+%   u, v, a  — the advanced state (u_{n+1}, v_{n+1}, a_{n+1})
+
+% algorithm newmark_step
+% backend taichi
+% args u:vector, v:vector, a:vector, solve_a:callable, dt:scalar, beta:scalar, gamma:scalar
+
+% type u_pred vector
+% type v_pred vector
+% type a_new vector
+% type c_0 scalar
+% type c_1 scalar
+% type c_2 scalar
+% type c_3 scalar
+
+\begin{algorithmic}
+\State $c_0 = dt \cdot dt \cdot (0.5 - \beta)$                              % scalar
+\State $c_1 = dt \cdot (1 - \gamma)$                                        % scalar
+\State $c_2 = \beta \cdot dt \cdot dt$                                      % scalar
+\State $c_3 = \gamma \cdot dt$                                              % scalar
+\State $u_{\text{pred}} = u + dt \cdot v + c_0 \cdot a$                     % vector
+\State $v_{\text{pred}} = v + c_1 \cdot a$                                  % vector
+\State $a_{\text{new}} = \text{solve\_a}(u_{\text{pred}}, v_{\text{pred}})$ % vector
+\State $u = u_{\text{pred}} + c_2 \cdot a_{\text{new}}$                     % vector
+\State $v = v_{\text{pred}} + c_3 \cdot a_{\text{new}}$                     % vector
+\State $a = a_{\text{new}}$                                                 % vector
+\Return $u, v, a$
+\end{algorithmic}

algo2code-0.2.2/src/algo2code/library/algorithms/pcg.tex

@@ -0,0 +1,103 @@
+% Matrix-free Preconditioned Conjugate Gradient (PCG).
+%
+% The canonical PCG algorithm authored for the **all-Taichi on-device seam path**:
+% the operator ``A`` and the preconditioner ``M_inv`` are both
+% *callables* (matrix-free), so this box transpiles via
+% ``algo2code.transpile(..., runtime='ti_runtime')`` into a body that solves
+% ``A x = b`` over ``ti.Vector.field`` DOF vectors without ever forming or storing
+% a matrix and without NumPy in the hot path.
+%
+% Provenance
+% ----------
+% Identical in algorithm to the canonical PCG LaTeX
+% (``algo2code.library.pcg.PCG_ALGORITHM_LATEX`` / the hand twin
+% ``mechdsl.solver.import_adapter.Algo2CodePCGSolver``) and to the matrix-free
+% ``_CALLABLE_PCG_LATEX`` proven runnable in runtime mode.  The *only* surface change vs
+% the canonical box is the operator type:
+%
+%   canonical:  ``% args A:matrix,    ... apply_M_inv:callable, ...``
+%   here:       ``% args A:callable,  ... M_inv:callable,       ...``
+%
+% A matrix ``A`` lowers to a dense scalar-indexed ``_matvec`` (incompatible with
+% the ``ti.Vector.field`` layout the seam uses); a callable ``A`` lowers to the
+% in-place ``A(out, p)`` operator call — the ``ti_runtime`` ``apply_A(out, x)``
+% seam contract.  The runtime-mode guard requires exactly this: a callable
+% operator + a vector argument.
+%
+% Seam contract (mirrors ti_runtime.seams.LinearSolveContext)
+% -----------------------------------------------------------
+%   A(out, x)        — operator:        out = A @ x       (out FIRST)
+%   M_inv(r, z)      — preconditioner:  z   = M^{-1} r    (out LAST)
+%
+% This box productionizes the spike's hand-written ``pcg`` body
+% (``packages/mechdsl-core/tests/spike/svk_hex8_taichi.py``): the generated body
+% maps line-for-line to that hand-written PCG, but is *derived from LaTeX* rather
+% than hand-coded.
+%
+% Inputs
+% ------
+%   A       : matrix-free operator (callable, in-place ``A(out, x)``)
+%   b       : right-hand side vector
+%   x       : solution vector (carries the initial guess; solved in place)
+%   M_inv   : preconditioner apply (callable, in-place ``M_inv(r, z)``)
+%   tol     : relative convergence tolerance (scalar)
+%   maxiter : maximum iteration count (scalar)
+%
+% Output
+% ------
+%   x, iterations, residual_norm, converged
+%
+%   ``converged`` is a hard non-convergence flag: literal ``1`` on the two
+%   success returns (the ``r_0 = 0`` early-out and the in-loop tolerance hit),
+%   literal ``0`` on maxiter exhaustion and on the ``|pq| < 1e-300`` breakdown
+%   (which ``break``s out of the loop and falls through to the maxiter return).
+%   A caller that sees ``converged == 0`` must NOT consume ``x`` -- the inner
+%   solve failed and ``x`` is garbage (see seam_solve.make_seam_solver, which
+%   raises rather than letting a Newton step advance on it).
+
+% algorithm pcg
+% backend taichi
+% args A:callable, b:vector, x:vector, M_inv:callable, tol:scalar, maxiter:scalar
+
+% type r vector
+% type z vector
+% type p vector
+% type q vector
+% type rho scalar
+% type rho_new scalar
+% type alpha scalar
+% type beta scalar
+% type pq scalar
+% type r0_norm scalar
+% type r_norm scalar
+
+\begin{algorithmic}
+\State $r = b - A \cdot x$                                          % vector
+\State $r_0 = \lVert r \rVert_2$                                    % scalar
+\If{$r_0 = 0$}
+    \Return $x, 0, 0, 1$
+\EndIf
+\State $z = M^{-1}(r)$                                              % vector
+\State $p = z$                                                      % vector
+\State $\rho = r^\top z$                                            % scalar
+\For{$k = 1, 2, \ldots, \text{maxiter}$}
+    \State $q = A \cdot p$                                          % vector
+    \State $pq = p^\top q$                                          % scalar
+    \If{$|pq| < 10^{-300}$}
+        \State \textbf{break}
+    \EndIf
+    \State $\alpha = \frac{\rho}{pq}$                               % scalar
+    \State $x = x + \alpha \, p$                                    % vector
+    \State $r = r - \alpha \, q$                                    % vector
+    \State $r_n = \lVert r \rVert_2$                                % scalar
+    \If{$r_n < \text{tol} \cdot r_0$}
+        \Return $x, k, r_n, 1$
+    \EndIf
+    \State $z = M^{-1}(r)$                                          % vector
+    \State $\rho_{\text{new}} = r^\top z$                           % scalar
+    \State $\beta = \frac{\rho_{\text{new}}}{\rho}$                 % scalar
+    \State $p = z + \beta \, p$                                     % vector
+    \State $\rho = \rho_{\text{new}}$                               % scalar
+\EndFor
+\Return $x, \text{maxiter}, \lVert r \rVert_2, 0$
+\end{algorithmic}