|
| 1 | +```@meta |
| 2 | +CollapsedDocStrings = true |
| 3 | +``` |
| 4 | + |
| 5 | +# OrdinaryDiffEqAMF |
| 6 | + |
| 7 | +**Approximate Matrix Factorization (AMF)** is a wrapper around Rosenbrock-W methods that replaces the dense `W = I - γJ` solve at each stage with a product of simpler factors: |
| 8 | + |
| 9 | +``` |
| 10 | +W ≈ -∏ᵢ (I - γJᵢ) / γ |
| 11 | +``` |
| 12 | + |
| 13 | +where the `Jᵢ` are individually-structured pieces of the Jacobian (e.g. upper and lower triangular parts, directional operators in dimensional splittings, mode blocks in spectral discretizations). Each factor can be solved independently with a cheap structured solver, so the overall per-step work drops from "one dense solve" to "a handful of structured solves". |
| 14 | + |
| 15 | +## Key Properties |
| 16 | + |
| 17 | +AMF methods provide: |
| 18 | + |
| 19 | + - **Structured linear solves** — each factor is handled by its own `SciMLOperator`-aware solver, so you never materialize a dense `W`. |
| 20 | + - **Any Rosenbrock-W base method** — `AMF` is an algorithm wrapper, not a fixed integrator; plug in `Rosenbrock23`, `ROS34PW1a`, `Rodas4`, etc. |
| 21 | + - **Works with the existing SciML split/operator infrastructure** — you describe the Jacobian split as `SciMLOperators` and pass them through `build_amf_function`. |
| 22 | + - **Preserves the Rosenbrock-W order** under the usual AMF consistency assumptions. |
| 23 | + |
| 24 | +## When to Use AMF |
| 25 | + |
| 26 | +AMF is recommended when: |
| 27 | + |
| 28 | + - Your Jacobian has **exploitable structure** that a dense LU solve would throw away — e.g. ADI-style dimensional splits, upper+lower triangular decompositions, block-diagonal plus a low-rank coupling, FFT/diagonalizable pieces. |
| 29 | + - You're using a **Rosenbrock-W method** and the `W` solve is the dominant per-step cost. |
| 30 | + - You can write the structured factors as `SciMLOperators`. |
| 31 | + |
| 32 | +If your Jacobian is genuinely dense and unstructured, plain Rosenbrock with a standard `LinearSolve` algorithm will be simpler and faster — AMF only helps when the product-of-factors approximation is significantly cheaper than the true `W` solve. |
| 33 | + |
| 34 | +## How It Works |
| 35 | + |
| 36 | +`AMF(AlgType)` wraps a Rosenbrock-W algorithm type. When you call `solve(prob, AMF(ROS34PW1a))`, the wrapper: |
| 37 | + |
| 38 | + 1. Instantiates the inner algorithm with `linsolve = SciMLOpFactorization()`, a `LinearSolve` backend that respects `SciMLOperator` products and solves them factor-by-factor rather than concretizing them. |
| 39 | + 2. Delegates the rest of the integration to the inner Rosenbrock-W method unchanged. |
| 40 | + |
| 41 | +To use it, the `ODEFunction` must carry a `jac_prototype` (the true Jacobian, as a `SciMLOperator`) *and* a `W_prototype` (the AMF approximation of `-(I - γJ)/γ`, built from the factors). `build_amf_function` assembles both for you. |
| 42 | + |
| 43 | +## Usage: 2D reaction-diffusion with ADI-style splitting |
| 44 | + |
| 45 | +The canonical AMF use case is a PDE whose discrete Laplacian separates along each spatial dimension — the split reduces the dense Rosenbrock-W `W` solve to a pair of Kronecker-structured solves that can be done much faster. This example is a 2D reaction-diffusion problem, |
| 46 | + |
| 47 | +``` |
| 48 | +uₜ = A uₓₓ + B u_yy + g(u, t), g(u, t) = u²(1 − u) + eᵗ, |
| 49 | +``` |
| 50 | + |
| 51 | +on the unit square with homogeneous Dirichlet boundary conditions. After second-order finite differencing on an `N × N` grid, the Jacobian of the linear (diffusion) part splits as |
| 52 | + |
| 53 | +``` |
| 54 | +J = A (Lx ⊗ I) + B (I ⊗ Lx) = Jx + Jy |
| 55 | +``` |
| 56 | + |
| 57 | +where `Lx` is the tridiagonal 1D Laplacian. AMF approximates the stage operator as |
| 58 | + |
| 59 | +``` |
| 60 | +W ≈ −(I − γ Jx)(I − γ Jy) / γ, |
| 61 | +``` |
| 62 | + |
| 63 | +so each stage does two independent block-diagonal tridiagonal solves instead of one dense solve — the standard ADI preconditioner, applied automatically by `AMF(...)` whenever you hand it the split. |
| 64 | + |
| 65 | +Install the package alongside a Rosenbrock-W subpackage: |
| 66 | + |
| 67 | +```julia |
| 68 | +using Pkg |
| 69 | +Pkg.add(["OrdinaryDiffEqAMF", "OrdinaryDiffEqRosenbrock"]) |
| 70 | +``` |
| 71 | + |
| 72 | +Set up the problem: |
| 73 | + |
| 74 | +```julia |
| 75 | +using OrdinaryDiffEqAMF |
| 76 | +using OrdinaryDiffEqRosenbrock |
| 77 | +using SciMLOperators |
| 78 | +using LinearAlgebra |
| 79 | + |
| 80 | +function setup_fd2d_problem(; A = 0.1, B = 0.1, N = 40, final_t = 1.0) |
| 81 | + h = 1 / (N + 1) |
| 82 | + |
| 83 | + # 1D Laplacian with Dirichlet zero BCs, as a SciMLOperator. |
| 84 | + D = (1 / h^2) * Tridiagonal(ones(N - 1), -2 * ones(N), ones(N - 1)) |
| 85 | + D_op = MatrixOperator(D) |
| 86 | + |
| 87 | + # 2D Jacobian pieces: diffusion in x and in y, via Kronecker products. |
| 88 | + Jx_op = A * Base.kron(D_op, IdentityOperator(N)) |
| 89 | + Jy_op = B * Base.kron(IdentityOperator(N), D_op) |
| 90 | + J_op = cache_operator(Jx_op + Jy_op, zeros(N^2)) |
| 91 | + |
| 92 | + # Nonlinear reaction term. |
| 93 | + g!(du, u, p, t) = (@. du += u^2 * (1 - u) + exp(t); return nothing) |
| 94 | + |
| 95 | + # Full RHS: linear diffusion + nonlinear reaction. |
| 96 | + function f!(du, u, p, t) |
| 97 | + mul!(du, J_op, u) |
| 98 | + g!(du, u, p, t) |
| 99 | + return nothing |
| 100 | + end |
| 101 | + |
| 102 | + # Initial condition: a bump that vanishes on the boundary. |
| 103 | + u0 = [16 * (h * i) * (h * j) * (1 - h * i) * (1 - h * j) for i in 1:N for j in 1:N] |
| 104 | + |
| 105 | + # Hand the split to build_amf_function so Rosenbrock-W sees the |
| 106 | + # structured W_prototype instead of a dense one. |
| 107 | + amf_func = build_amf_function(f!; jac = J_op, split = (Jx_op, Jy_op)) |
| 108 | + return ODEProblem(amf_func, u0, (0.0, final_t)) |
| 109 | +end |
| 110 | + |
| 111 | +prob = setup_fd2d_problem() |
| 112 | +sol = solve(prob, AMF(ROS34PW1a); abstol = 1e-8, reltol = 1e-8) |
| 113 | +``` |
| 114 | + |
| 115 | +For this 1600-unknown problem the AMF stage solve is substantially faster than the dense equivalent, and the speedup grows with `N` because the dense `W` solve is `O(N⁶)` while the two Kronecker-structured AMF solves are `O(N³)` total. A regression test inside the package (`lib/OrdinaryDiffEqAMF/test/test_fd2d.jl`) measures the speedup on the same problem against a baseline `solve(..., ROS34PW1a())` without AMF. |
| 116 | + |
| 117 | +### Supplying AMF factors directly |
| 118 | + |
| 119 | +Sometimes you want to control the factors yourself — for instance to pre-factorize each 1D operator with something cheaper than a generic structured solver, or to bake in an FFT plan. Pass the custom factors as `amf_factors`: |
| 120 | + |
| 121 | +```julia |
| 122 | +using SciMLOperators: ScalarOperator |
| 123 | + |
| 124 | +gamma_op = ScalarOperator( |
| 125 | + 1.0; |
| 126 | + update_func = (old, u, p, t; gamma = 1.0) -> gamma, |
| 127 | + accepted_kwargs = Val((:gamma,)), |
| 128 | +) |
| 129 | + |
| 130 | +# Each factor is (I − γ Jᵢ), pre-assembled as a Kronecker-structured operator. |
| 131 | +custom_factors = ( |
| 132 | + Base.kron(IdentityOperator(N) - gamma_op * A * D_op, IdentityOperator(N)), |
| 133 | + Base.kron(IdentityOperator(N), IdentityOperator(N) - gamma_op * B * D_op), |
| 134 | +) |
| 135 | + |
| 136 | +amf_func = build_amf_function( |
| 137 | + f!; |
| 138 | + jac = J_op, |
| 139 | + split = (Jx_op, Jy_op), |
| 140 | + amf_factors = custom_factors, |
| 141 | +) |
| 142 | + |
| 143 | +sol = solve(ODEProblem(amf_func, u0, (0.0, 1.0)), AMF(ROS34PW1a); reltol = 1e-8) |
| 144 | +``` |
| 145 | + |
| 146 | +`split` and `amf_factors` must contain the same number of operators: the split is used to propagate Jacobian updates, and the factors determine the actual `W_prototype` that the linear solver sees. |
| 147 | + |
| 148 | +### Forwarding keyword arguments |
| 149 | + |
| 150 | +Any extra kwargs passed to `AMF(alg; kwargs...)` are forwarded to the inner algorithm constructor: |
| 151 | + |
| 152 | +```julia |
| 153 | +sol = solve(prob, AMF(ROS34PW1a; autodiff = AutoFiniteDiff())) |
| 154 | +``` |
| 155 | + |
| 156 | +## Full list of exports |
| 157 | + |
| 158 | +```@docs |
| 159 | +OrdinaryDiffEqAMF.AMF |
| 160 | +OrdinaryDiffEqAMF.AMFOperator |
| 161 | +OrdinaryDiffEqAMF.build_amf_function |
| 162 | +``` |
0 commit comments