optixde 0.2.2__tar.gz → 0.2.4__tar.gz

{optixde-0.2.2 → optixde-0.2.4}/CHANGELOG.md

@@ -7,6 +7,35 @@ and OptiXDE uses semantic versioning for public releases.
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-08-16
+
+### Added
+
+- An additive `optixde.custom_pde` subsystem for compiling scalar,
+  constant-coefficient, two-dimensional periodic linear PDEs into steady or
+  transient generic spectral execution plans.
+- A hybrid-spectral two-dimensional elastic half-space solver in
+  `optixde.solvers.solid`, supporting a traction-free surface, absorbing
+  exterior layers, configurable source histories, and sampled wavefields.
+- Backend-independent periodic immersed-boundary Navier--Stokes utilities for
+  NumPy and CuPy, including nonzero mean flow and split constraints.
+- Exact three-halves padding dealiasing for the periodic Burgers solver.
+
+### Changed
+
+- Updated the Burgers and immersed-cylinder paper examples to call the public
+  `optixde.solvers` implementations while preserving their numerical kernels
+  and reference outputs.
+- Aligned the canonical Re=200 paper driver with the final frozen production
+  configuration (ND=24/32/40, eta=0.0025, compact mask width 1h, T=100).
+
+## [0.2.3] - 2026-08-04
+
+### Changed
+
+- Fixed the PyPI project-page logo by using an absolute HTTPS image URL.
+- Removed the benchmark-reference subsection from the main README.
+
 ## [0.2.2] - 2026-07-27
 
 ### Added
@@ -77,7 +106,9 @@ and OptiXDE uses semantic versioning for public releases.
   modules are still experimental and should be validated for each research use
   case.
 
-[Unreleased]: https://github.com/yangyLab/OptiXDE/compare/v0.2.2...main
+[Unreleased]: https://github.com/yangyLab/OptiXDE/compare/v0.2.4...main
+[0.2.4]: https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.4
+[0.2.3]: https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.3
 [0.2.2]: https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.2
 [0.2.1]: https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.1
 [0.2.0]: https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.0

{optixde-0.2.2 → optixde-0.2.4}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use OptiXDE in academic work, please cite this software and the related paper or preprint when available."
 title: "OptiXDE: optical-inspired PDE solvers"
-version: "0.2.2"
-date-released: "2026-07-27"
+version: "0.2.4"
+date-released: "2026-08-16"
 type: software
 license: MIT
 authors:
@@ -10,7 +10,7 @@ authors:
     given-names: "Yang"
     email: "yangyhhu@foxmail.com"
 repository-code: "https://github.com/yangyLab/OptiXDE"
-url: "https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.2"
+url: "https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.4"
 abstract: "OptiXDE is a lightweight Python package for optical-inspired, matrix-free spectral solvers for differential equations on uniform grids, with examples for linear PDEs, nonlinear splitting, flow, wave propagation, and GPU-oriented periodic FFT workflows."
 keywords:
   - PDE

{optixde-0.2.2 → optixde-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optixde
-Version: 0.2.2
+Version: 0.2.4
 Summary: OptiXDE: optical-inspired PDE solver
 Author-email: Yang Yang <yangyhhu@foxmail.com>
 License-Expression: MIT
@@ -33,13 +33,13 @@ Requires-Dist: twine>=5; extra == "dev"
 Dynamic: license-file
 
 <p align="center">
-  <img src="optixde_logo_horizontal.svg" alt="OptiXDE logo" width="620">
+  <img src="./optixde_logo_horizontal.svg" alt="OptiXDE logo" width="620">
 </p>
 
 # OptiXDE
 
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
-[![Release](https://img.shields.io/badge/release-v0.2.2-blueviolet.svg)](https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.2)
+[![Release](https://img.shields.io/badge/release-v0.2.4-blueviolet.svg)](https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.4)
 [![Tests](https://img.shields.io/badge/tests-unittest-green.svg)](#development)
 [![GPU](https://img.shields.io/badge/GPU-PyTorch%20periodic%20FFT-purple.svg)](docs/colab_torch_gpu.md)
 
@@ -59,8 +59,11 @@ The core convention is consistent across the package:
 
 - **Matrix-free solvers** for Poisson, Helmholtz, diffusion, and wave equations.
 - **Operator splitting** utilities for nonlinear PDEs such as Allen--Cahn.
+- **Custom linear PDE compilation** from symbolic equations to periodic
+  spectral operators, without changing the existing specialized solvers.
 - **Nonlinear examples** for Allen--Cahn and 1D periodic viscous Burgers.
 - **Periodic incompressible flow** via 2D vorticity-streamfunction Navier--Stokes.
+- **Periodic immersed-cylinder flow** with a Brinkman mask and inflow-restoring fringe.
 - **Schrödinger/paraxial propagation** for optical-style complex wave fields.
 - **FFT/DCT/DST transforms** for periodic, Dirichlet, and Neumann boundary
   conditions.
@@ -233,6 +236,10 @@ Current PyTorch scope:
   vorticity-streamfunction Navier--Stokes, and Schrödinger FFT paths.
 - Supported: CPU tensors and CUDA tensors, depending on your PyTorch install.
 - Not yet supported: Torch DCT/DST paths for Dirichlet and Neumann solvers.
+- Periodic Brinkman/fringe Navier--Stokes supports NumPy and CuPy arrays; the
+  compatibility `cylinder_re200_*` names refer to the same general solver.
+- The final Re=200 paper driver defaults to CuPy/CUDA and provides
+  `--backend numpy` for CPU smoke and regression runs.
 
 For Colab GPU validation, see `docs/colab_torch_gpu.md`.
 
@@ -321,6 +328,39 @@ python examples/base/navier_stokes_cylinder_brinkman.py --nx 96 --ny 48 --steps
 python examples/base/schrodinger_gaussian_packet.py --n 128 --T 1.0
 ```
 
+Compile a scalar constant-coefficient periodic PDE:
+
+```python
+from optixde.custom_pde import Equation, Field, compile_pde, dt, laplacian, solve_pde
+
+u = Field("u")
+problem = compile_pde(
+    Equation(dt(u), 0.05 * laplacian(u)),
+    shape=u0.shape,
+    domain=(Lx, Ly),
+)
+times, states = solve_pde(problem, u0, dt=0.01, t_end=1.0)
+```
+
+The first compiler version supports one scalar field, constant coefficients,
+two-dimensional periodic domains, steady equations, and first-order transient
+equations with derivatives up to fourth order. Existing PDE-specific solver
+APIs remain unchanged.
+
+The paper Burgers driver uses the public solver with fourth-order nonlinear
+stages and exact three-halves padding:
+
+```python
+u_next = burgers1d_step(
+    u,
+    nu,
+    L,
+    dt,
+    nonlinear_order=4,
+    dealias="three_halves",
+)
+```
+
 Run the unified reference-validation table:
 
 ```bash
@@ -343,6 +383,8 @@ Primary public imports:
 
 - `from optixde.solvers import poisson2d_solve, diffusion2d_solve, wave2d_solve`
 - `from optixde.solvers import burgers1d_solve, navier_stokes2d_vorticity_solve`
+- `from optixde.solvers import navier_stokes2d_brinkman_fringe_step`
+- `from optixde.solvers import cylinder_re200_step` (compatibility alias)
 - `from optixde.solvers import schrodinger2d_solve, allen_cahn2d_solve`
 
 PDE-specific modules are also kept as stable compatibility namespaces:
@@ -355,6 +397,7 @@ PDE-specific modules are also kept as stable compatibility namespaces:
 - `optixde.solvers.allen_cahn`
 - `optixde.solvers.burgers`
 - `optixde.solvers.navier_stokes`
+- `optixde.solvers.cylinder_re200`
 - `optixde.solvers.schrodinger`
 - `optixde.fft_backend`
 - `optixde.geometry`
@@ -399,27 +442,12 @@ from `CITATION.cff`.
   author  = {Yang, Yang},
   year    = {2026},
   url     = {https://github.com/yangyLab/OptiXDE},
-  version = {0.2.2},
+  version = {0.2.4},
 }
 ```
 
 Release notes are tracked in `CHANGELOG.md`.
 
-### Benchmark References
-
-Several examples reuse published benchmark problem definitions for independent
-OptiXDE implementations and comparisons:
-
-- M. Raissi, P. Perdikaris, and G. E. Karniadakis, “Physics-informed neural
-  networks: A deep learning framework for solving forward and inverse problems
-  involving nonlinear partial differential equations,” *Journal of
-  Computational Physics*, 378, 686–707 (2019),
-  [doi:10.1016/j.jcp.2018.10.045](https://doi.org/10.1016/j.jcp.2018.10.045).
-- L. Lu, X. Meng, Z. Mao, and G. E. Karniadakis, “DeepXDE: A deep learning
-  library for solving differential equations,” *SIAM Review*, 63(1), 208–228
-  (2021),
-  [doi:10.1137/19M1274067](https://doi.org/10.1137/19M1274067).
-
 ## Copyright, License, and Disclaimer
 
 Copyright (c) 2025-2026 Yang Yang

{optixde-0.2.2 → optixde-0.2.4}/README.md

@@ -1,11 +1,11 @@
 <p align="center">
-  <img src="optixde_logo_horizontal.svg" alt="OptiXDE logo" width="620">
+  <img src="./optixde_logo_horizontal.svg" alt="OptiXDE logo" width="620">
 </p>
 
 # OptiXDE
 
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
-[![Release](https://img.shields.io/badge/release-v0.2.2-blueviolet.svg)](https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.2)
+[![Release](https://img.shields.io/badge/release-v0.2.4-blueviolet.svg)](https://github.com/yangyLab/OptiXDE/releases/tag/v0.2.4)
 [![Tests](https://img.shields.io/badge/tests-unittest-green.svg)](#development)
 [![GPU](https://img.shields.io/badge/GPU-PyTorch%20periodic%20FFT-purple.svg)](docs/colab_torch_gpu.md)
 
@@ -25,8 +25,11 @@ The core convention is consistent across the package:
 
 - **Matrix-free solvers** for Poisson, Helmholtz, diffusion, and wave equations.
 - **Operator splitting** utilities for nonlinear PDEs such as Allen--Cahn.
+- **Custom linear PDE compilation** from symbolic equations to periodic
+  spectral operators, without changing the existing specialized solvers.
 - **Nonlinear examples** for Allen--Cahn and 1D periodic viscous Burgers.
 - **Periodic incompressible flow** via 2D vorticity-streamfunction Navier--Stokes.
+- **Periodic immersed-cylinder flow** with a Brinkman mask and inflow-restoring fringe.
 - **Schrödinger/paraxial propagation** for optical-style complex wave fields.
 - **FFT/DCT/DST transforms** for periodic, Dirichlet, and Neumann boundary
   conditions.
@@ -199,6 +202,10 @@ Current PyTorch scope:
   vorticity-streamfunction Navier--Stokes, and Schrödinger FFT paths.
 - Supported: CPU tensors and CUDA tensors, depending on your PyTorch install.
 - Not yet supported: Torch DCT/DST paths for Dirichlet and Neumann solvers.
+- Periodic Brinkman/fringe Navier--Stokes supports NumPy and CuPy arrays; the
+  compatibility `cylinder_re200_*` names refer to the same general solver.
+- The final Re=200 paper driver defaults to CuPy/CUDA and provides
+  `--backend numpy` for CPU smoke and regression runs.
 
 For Colab GPU validation, see `docs/colab_torch_gpu.md`.
 
@@ -287,6 +294,39 @@ python examples/base/navier_stokes_cylinder_brinkman.py --nx 96 --ny 48 --steps
 python examples/base/schrodinger_gaussian_packet.py --n 128 --T 1.0
 ```
 
+Compile a scalar constant-coefficient periodic PDE:
+
+```python
+from optixde.custom_pde import Equation, Field, compile_pde, dt, laplacian, solve_pde
+
+u = Field("u")
+problem = compile_pde(
+    Equation(dt(u), 0.05 * laplacian(u)),
+    shape=u0.shape,
+    domain=(Lx, Ly),
+)
+times, states = solve_pde(problem, u0, dt=0.01, t_end=1.0)
+```
+
+The first compiler version supports one scalar field, constant coefficients,
+two-dimensional periodic domains, steady equations, and first-order transient
+equations with derivatives up to fourth order. Existing PDE-specific solver
+APIs remain unchanged.
+
+The paper Burgers driver uses the public solver with fourth-order nonlinear
+stages and exact three-halves padding:
+
+```python
+u_next = burgers1d_step(
+    u,
+    nu,
+    L,
+    dt,
+    nonlinear_order=4,
+    dealias="three_halves",
+)
+```
+
 Run the unified reference-validation table:
 
 ```bash
@@ -309,6 +349,8 @@ Primary public imports:
 
 - `from optixde.solvers import poisson2d_solve, diffusion2d_solve, wave2d_solve`
 - `from optixde.solvers import burgers1d_solve, navier_stokes2d_vorticity_solve`
+- `from optixde.solvers import navier_stokes2d_brinkman_fringe_step`
+- `from optixde.solvers import cylinder_re200_step` (compatibility alias)
 - `from optixde.solvers import schrodinger2d_solve, allen_cahn2d_solve`
 
 PDE-specific modules are also kept as stable compatibility namespaces:
@@ -321,6 +363,7 @@ PDE-specific modules are also kept as stable compatibility namespaces:
 - `optixde.solvers.allen_cahn`
 - `optixde.solvers.burgers`
 - `optixde.solvers.navier_stokes`
+- `optixde.solvers.cylinder_re200`
 - `optixde.solvers.schrodinger`
 - `optixde.fft_backend`
 - `optixde.geometry`
@@ -365,27 +408,12 @@ from `CITATION.cff`.
   author  = {Yang, Yang},
   year    = {2026},
   url     = {https://github.com/yangyLab/OptiXDE},
-  version = {0.2.2},
+  version = {0.2.4},
 }
 ```
 
 Release notes are tracked in `CHANGELOG.md`.
 
-### Benchmark References
-
-Several examples reuse published benchmark problem definitions for independent
-OptiXDE implementations and comparisons:
-
-- M. Raissi, P. Perdikaris, and G. E. Karniadakis, “Physics-informed neural
-  networks: A deep learning framework for solving forward and inverse problems
-  involving nonlinear partial differential equations,” *Journal of
-  Computational Physics*, 378, 686–707 (2019),
-  [doi:10.1016/j.jcp.2018.10.045](https://doi.org/10.1016/j.jcp.2018.10.045).
-- L. Lu, X. Meng, Z. Mao, and G. E. Karniadakis, “DeepXDE: A deep learning
-  library for solving differential equations,” *SIAM Review*, 63(1), 208–228
-  (2021),
-  [doi:10.1137/19M1274067](https://doi.org/10.1137/19M1274067).
-
 ## Copyright, License, and Disclaimer
 
 Copyright (c) 2025-2026 Yang Yang

optixde-0.2.4/optixde/custom_pde/__init__.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2025-2026 Yang Yang <yangyhhu@foxmail.com>
+# SPDX-License-Identifier: MIT
+
+"""Compile scalar constant-coefficient periodic PDEs to spectral solvers."""
+
+from .compiler import CompiledLinearPDE, analyze_equation, compile_pde
+from .errors import PDECompileError, PDEError, PDESolveError, UnsupportedPDEError
+from .ir import IR_VERSION, LinearPDEIR, LinearTerm, SourceTerm
+from .solver import solve_pde, solve_steady, solve_transient
+from .symbolic import (
+    Add,
+    Constant,
+    Derivative,
+    Equation,
+    Expr,
+    Field,
+    Mul,
+    Source,
+    TimeDerivative,
+    biharmonic,
+    derivative,
+    dt,
+    dx,
+    dxx,
+    dy,
+    dyy,
+    laplacian,
+)
+
+__all__ = [
+    "Expr",
+    "Constant",
+    "Field",
+    "Source",
+    "Add",
+    "Mul",
+    "Derivative",
+    "TimeDerivative",
+    "Equation",
+    "derivative",
+    "dx",
+    "dy",
+    "dxx",
+    "dyy",
+    "laplacian",
+    "biharmonic",
+    "dt",
+    "IR_VERSION",
+    "LinearTerm",
+    "SourceTerm",
+    "LinearPDEIR",
+    "CompiledLinearPDE",
+    "analyze_equation",
+    "compile_pde",
+    "solve_steady",
+    "solve_transient",
+    "solve_pde",
+    "PDEError",
+    "PDECompileError",
+    "UnsupportedPDEError",
+    "PDESolveError",
+]

optixde-0.2.4/optixde/custom_pde/compiler.py

@@ -0,0 +1,309 @@
+# SPDX-FileCopyrightText: 2025-2026 Yang Yang <yangyhhu@foxmail.com>
+# SPDX-License-Identifier: MIT
+
+"""Compiler from the custom PDE expression tree to a periodic spectral plan."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from optixde.fft_backend import NumpyBackend
+
+from .errors import PDECompileError, UnsupportedPDEError
+from .ir import IR_VERSION, LinearPDEIR, LinearTerm, SourceTerm
+from .symbolic import (
+    Add,
+    Constant,
+    Derivative,
+    Equation,
+    Field,
+    Mul,
+    Source,
+    TimeDerivative,
+)
+
+
+@dataclass
+class _AnalysisState:
+    fields: set
+    time_coefficient: complex
+    linear_terms: list
+    source_terms: list
+
+
+@dataclass(frozen=True)
+class CompiledLinearPDE:
+    """Grid/backend-bound execution plan produced from :class:`LinearPDEIR`."""
+
+    ir: LinearPDEIR
+    shape: tuple
+    domain: tuple
+    backend: object
+    grids: object
+    spatial_symbol: object
+    evolution_symbol: object
+    zero_mode_policy: str
+    singular_tolerance: float
+    real_output: bool
+    specialized_hint: object
+
+    @property
+    def problem_type(self):
+        return self.ir.problem_type
+
+    @property
+    def report(self):
+        return {
+            "ir_version": self.ir.version,
+            "field": self.ir.field_name,
+            "problem_type": self.ir.problem_type,
+            "boundary": self.ir.boundary,
+            "shape": self.shape,
+            "domain": self.domain,
+            "max_spatial_order": self.ir.max_spatial_order,
+            "linear_term_count": len(self.ir.linear_terms),
+            "source_names": tuple(
+                term.name for term in self.ir.source_terms if term.name is not None
+            ),
+            "specialized_hint": self.specialized_hint,
+            "backend": self.backend.name,
+            "device": str(self.backend.device),
+        }
+
+
+def _constant_value(expression):
+    if isinstance(expression, Constant):
+        return expression.value
+    if isinstance(expression, Mul):
+        left = _constant_value(expression.left)
+        right = _constant_value(expression.right)
+        if left is not None and right is not None:
+            return left * right
+    return None
+
+
+def _collect(expression, state, *, scale=1.0, derivative_orders=(0, 0)):
+    if isinstance(expression, Add):
+        for term in expression.terms:
+            _collect(term, state, scale=scale, derivative_orders=derivative_orders)
+        return
+
+    if isinstance(expression, Mul):
+        left_constant = _constant_value(expression.left)
+        right_constant = _constant_value(expression.right)
+        if left_constant is not None:
+            _collect(
+                expression.right,
+                state,
+                scale=scale * left_constant,
+                derivative_orders=derivative_orders,
+            )
+            return
+        if right_constant is not None:
+            _collect(
+                expression.left,
+                state,
+                scale=scale * right_constant,
+                derivative_orders=derivative_orders,
+            )
+            return
+        raise UnsupportedPDEError(
+            "Products between non-constant expressions are nonlinear or "
+            "variable-coefficient terms and are not supported in linear PDE v1."
+        )
+
+    if isinstance(expression, Derivative):
+        combined = tuple(
+            int(old) + int(new)
+            for old, new in zip(derivative_orders, expression.orders)
+        )
+        _collect(expression.expression, state, scale=scale, derivative_orders=combined)
+        return
+
+    if isinstance(expression, TimeDerivative):
+        if derivative_orders != (0, 0) or not isinstance(expression.expression, Field):
+            raise UnsupportedPDEError(
+                "Only a first time derivative of the unknown field is supported."
+            )
+        state.fields.add(expression.expression.name)
+        state.time_coefficient += scale
+        return
+
+    if isinstance(expression, Field):
+        state.fields.add(expression.name)
+        state.linear_terms.append(LinearTerm(scale, derivative_orders))
+        return
+
+    if isinstance(expression, Source):
+        if derivative_orders != (0, 0):
+            raise UnsupportedPDEError(
+                "Spatial derivatives of prescribed sources are not supported in v1."
+            )
+        state.source_terms.append(SourceTerm(scale, expression.name))
+        return
+
+    if isinstance(expression, Constant):
+        if derivative_orders != (0, 0):
+            return
+        state.source_terms.append(SourceTerm(scale * expression.value, None))
+        return
+
+    raise PDECompileError(f"Unknown expression node: {type(expression).__name__}.")
+
+
+def analyze_equation(equation):
+    """Normalize ``lhs = rhs`` into a backend-independent linear PDE IR."""
+    if not isinstance(equation, Equation):
+        raise TypeError("compile_pde expects an Equation object.")
+    state = _AnalysisState(set(), 0.0, [], [])
+    _collect(equation.lhs, state)
+    _collect(equation.rhs, state, scale=-1.0)
+
+    if len(state.fields) != 1:
+        raise UnsupportedPDEError(
+            "Linear PDE v1 requires exactly one scalar unknown field; "
+            f"found {sorted(state.fields)!r}."
+        )
+    if not state.linear_terms and state.time_coefficient == 0:
+        raise PDECompileError("The equation contains no spatial or reaction operator.")
+    max_order = max(
+        (sum(term.derivative_orders) for term in state.linear_terms), default=0
+    )
+    if max_order > 4:
+        raise UnsupportedPDEError("Linear PDE v1 supports spatial derivatives up to order four.")
+
+    transient = state.time_coefficient != 0
+    return LinearPDEIR(
+        version=IR_VERSION,
+        field_name=next(iter(state.fields)),
+        problem_type="transient" if transient else "steady",
+        time_coefficient=state.time_coefficient,
+        linear_terms=tuple(state.linear_terms),
+        source_terms=tuple(state.source_terms),
+    )
+
+
+def _combine_terms(terms):
+    combined = {}
+    for term in terms:
+        combined[term.derivative_orders] = (
+            combined.get(term.derivative_orders, 0.0) + term.coefficient
+        )
+    return {orders: value for orders, value in combined.items() if value != 0}
+
+
+def _specialized_hint(ir):
+    terms = _combine_terms(ir.linear_terms)
+    isotropic_second = (
+        (2, 0) in terms
+        and (0, 2) in terms
+        and terms[(2, 0)] == terms[(0, 2)]
+    )
+    spatial_second = set(terms).issubset({(0, 0), (2, 0), (0, 2)})
+    if ir.problem_type == "steady" and spatial_second and isotropic_second:
+        if set(terms) == {(2, 0), (0, 2)}:
+            return "poisson2d_solve"
+        if set(terms) == {(0, 0), (2, 0), (0, 2)}:
+            return "helmholtz2d_solve"
+    if (
+        ir.problem_type == "transient"
+        and set(terms) == {(2, 0), (0, 2)}
+        and isotropic_second
+    ):
+        return "diffusion2d_solve"
+    if (
+        ir.problem_type == "steady"
+        and set(terms) == {(4, 0), (2, 2), (0, 4)}
+        and terms[(4, 0)] == terms[(0, 4)]
+        and terms[(2, 2)] == 2.0 * terms[(4, 0)]
+    ):
+        return "generic_biharmonic"
+    return None
+
+
+def _build_symbol(ir, grids):
+    symbol = 0j * grids.K2
+    for term in ir.linear_terms:
+        order_x, order_y = term.derivative_orders
+        contribution = term.coefficient
+        if order_x:
+            contribution = contribution * (1j * grids.KX) ** order_x
+        if order_y:
+            contribution = contribution * (1j * grids.KY) ** order_y
+        symbol = symbol + contribution
+    return symbol
+
+
+def _make_isolated_backend(backend_name, backend_kwargs):
+    """Create a compiler-owned backend without touching legacy shared caches."""
+    name = str(backend_name or "numpy").lower()
+    if name in {"numpy", "np"}:
+        if backend_kwargs:
+            unexpected = ", ".join(sorted(backend_kwargs))
+            raise TypeError(f"NumPy backend does not accept: {unexpected}.")
+        return NumpyBackend()
+    if name in {"torch", "pytorch"}:
+        from optixde.fft_backend import TorchBackend
+
+        return TorchBackend(**backend_kwargs)
+    if name in {"cupy", "cp", "cufft"}:
+        from optixde.fft_backend import CuPyBackend
+
+        return CuPyBackend(**backend_kwargs)
+    raise ValueError(f"Unknown backend: {backend_name!r}.")
+
+
+def compile_pde(
+    equation,
+    *,
+    shape,
+    domain,
+    boundary="periodic",
+    backend=None,
+    backend_name="numpy",
+    zero_mode_policy="project",
+    singular_tolerance=1.0e-12,
+    real_output=True,
+    **backend_kwargs,
+):
+    """Compile a scalar constant-coefficient periodic PDE into a spectral plan."""
+    if str(boundary).lower() != "periodic":
+        raise UnsupportedPDEError("Linear PDE v1 supports periodic boundaries only.")
+    shape = tuple(int(value) for value in shape)
+    domain = tuple(float(value) for value in domain)
+    if len(shape) != 2 or any(value < 2 for value in shape):
+        raise ValueError("shape must be a two-dimensional (Ny, Nx) tuple.")
+    if len(domain) != 2 or any(value <= 0.0 for value in domain):
+        raise ValueError("domain must contain positive lengths (Lx, Ly).")
+    if zero_mode_policy not in {"project", "check", "raise"}:
+        raise ValueError("zero_mode_policy must be 'project', 'check', or 'raise'.")
+    if singular_tolerance <= 0.0:
+        raise ValueError("singular_tolerance must be positive.")
+
+    ir = analyze_equation(equation)
+    selected_backend = backend or _make_isolated_backend(backend_name, backend_kwargs)
+    ny, nx = shape
+    lx, ly = domain
+    grids = selected_backend.make_freq_grids(nx, ny, lx, ly)
+    spatial_symbol = _build_symbol(ir, grids)
+    evolution_symbol = (
+        -spatial_symbol / ir.time_coefficient
+        if ir.problem_type == "transient"
+        else None
+    )
+    return CompiledLinearPDE(
+        ir=ir,
+        shape=shape,
+        domain=domain,
+        backend=selected_backend,
+        grids=grids,
+        spatial_symbol=spatial_symbol,
+        evolution_symbol=evolution_symbol,
+        zero_mode_policy=zero_mode_policy,
+        singular_tolerance=float(singular_tolerance),
+        real_output=bool(real_output),
+        specialized_hint=_specialized_hint(ir),
+    )
+
+
+__all__ = ["CompiledLinearPDE", "analyze_equation", "compile_pde"]