PDE Solver Framework

unitarylab.library.equation provides equation solvers based on Schrödingerization: a discretized non-unitary evolution is embedded in a higher-dimensional Schrödinger-type evolution, then solved using a classical matrix exponential, a Trotter circuit, or a block-encoding circuit.

This page covers the public low-level interfaces and 20 configuration-driven algorithms in examples. For a first run, use the default classical configuration to validate equation parameters and outputs before switching to a Trotter or block method.

Workflow

setup.json / dict / JSON string
        │
        ▼
parse_equation()
        │
        ├── Equation and equation parameters
        ├── BoundaryCondition
        ├── InitialCondition
        ├── DiscreteFormat
        ├── Preprocessing
        └── SolutionMethod
        │
        ▼
Finite differences and Schrödingerization
        │
        ├── classical: matrix-exponential reference implementation
        ├── trotter: construct and execute a Trotter circuit
        └── block: construct and execute a block-encoding circuit
        │
        ▼
Result dictionary + solution plot + circuit diagram + logs

The framework is organized into four layers:

equation/
├── differential_operator/   # Classical, Trotter, and block-encoded difference operators
├── equation_parser/          # Equation, boundary, initial, discretization, and solver parsing
├── schrodingerization/       # Classical and Trotter Schrödingerization
└── examples/                 # 20 configuration-driven equation algorithms

Public interfaces

The following nine names are exported directly from unitarylab.library.equation:

from unitarylab.library.equation import (
    CDiff,
    TDiff,
    ClassicalOperator,
    TrotterOperator,
    parse_equation,
    Equation,
    schro_trotter,
    initial_schro_fp,
    schro_classical,
)

Most users should start with an algorithm class in examples. Call the low-level interfaces directly when assembling a discretized operator or Schrödingerization workflow.

Quick start: one-dimensional heat equation

HeatEquationAlgorithm reads setup.json from its own example directory by default. The default selects the classical method and does not require a quantum simulation backend:

from unitarylab.library.equation.examples import HeatEquationAlgorithm
 
solver = HeatEquationAlgorithm()
result = solver.run(params=None, algo_dir="results/pde-heat")
 
print(result["status"])
print(result["message"])
print(result["grid"])
print(result["x"][:5])
print(result["u"][:5])
print(result["plot"])
print(result["circuit"])

The result typically contains:

run() writes result files. Depending on the execution path, algo_dir can contain algorithm.log, algorithm_error.log, solution SVGs, and circuit diagrams. If omitted, the default directory is:

<current working directory>/results/equation/equation_heat

Pass algo_dir explicitly when output location must be fixed.

Configuration structure

params may be None, a parsed dictionary, or an equivalent JSON string. If it is None, the algorithm reads setup.json from its example directory.

{
  "request_id": "optional request identifier",
  "params": [
    {
      "equation": {},
      "boundary_condition": [],
      "initial_condition": [],
      "discrete_format": [],
      "preprocessing": []
    },
    {
      "type": "solutionMethod_classical",
      "par_fix": [],
      "par_func": []
    }
  ]
}

• params[0] describes the equation and selects boundary conditions, initial conditions, discretization, and preprocessing through type fields.
• params[1] selects the solution method, for example solutionMethod_classical, solutionMethod_trotter, or solutionMethod_block.
• par_fix stores scalar parameters such as L, T, nx, na, R, p, order, and dt.
• par_func stores function expressions such as initial values and source terms.
• parse_equation() assembles the configuration into an Equation and attaches boundary, initial, discrete, preprocessing, and solver.

The selected method must be declared by both the algorithm and its setup.json. An undeclared method name causes a configuration or execution error.

Solution methods

Not every example supports Trotter or block methods. A method can be selected only if it appears in that example’s method_list.

Built-in algorithms

“Backend parameters supported” means run() accepts backend="torch", device="cpu", and dtype=np.complex128. Eleven examples support these three parameters; the other nine accept only params and algo_dir. Do not pass backend parameters to every algorithm, or unsupported signatures raise TypeError.

Algorithm classes can also be imported from their specific submodules:

from unitarylab.library.equation.examples.equation_heat import HeatEquationAlgorithm
from unitarylab.library.equation.examples.equation_maxwell import MaxwellEquationAlgorithm

Return-value differences

All 20 example result dictionaries contain status, message, grid, plot, and circuit. Physical-value fields depend on the problem:

Read fields according to the selected algorithm; do not assume every result contains result["u"].

Scale and recommendations

• For examples using nx, it is the number of qubits in the spatial register; the spatial grid size is approximately $2^{nx}$.
• na is the number of qubits in the Schrödingerization auxiliary register; the auxiliary discretization size is approximately $2^{na}$.
• Increasing nx and na can substantially increase matrix, state, and circuit resources; they do not represent ordinary linearly sized grid-point counts.
• First validate the equation, boundary, initial condition, and output directory with the example’s default classical configuration.
• Before switching to Trotter or block, check the algorithm table and start with smaller nx and na values.
• For quantum methods, pass backend, device, and dtype only when accepted by the algorithm’s signature.
• Set a separate algo_dir for long-running or batched jobs to avoid output files overwriting one another.

Related pages

• Linear System Solvers
• QSP, QSVT, and Block Encoding
• Execution Backends and Parameters