API and supported scope

Signatures and hard limitations. The mathematics behind each entry is in Mathematics and methods. Guidance on which method to choose is in use the defaults.

The Detailed API reference gives the complete callable signatures and public methods generated from the installed package.

Notation: \(\alpha\) is a fractional time order and \(s\) a fractional spatial order. both lie in \((0,1)\) and are immutable.

Fractional time derivatives

CaputoDerivative(u, alpha)
RiemannLiouvilleDerivative(u, alpha)

BirkSong(num_modes, *, rate_scale=1.0)
Diethelm(num_modes, *, rate_scale=1.0)
Diethelm2022(
    num_modes, *, quadrature="trapezoidal", target_error=1e-8,
    decay_scale=1.0, truncation_radius=None, rate_scale=1.0,
)
YuanAgrawal(num_modes, *, rate_scale=1.0)
FullHistory(interpolant="linear")

Recurrence(interpolant="linear")
AuxiliaryODE(scheme="backward_euler", coupling="monolithic")

FractionalTimeStepper(
    F, representation, t, dt, u, *,
    formulation=None, u0=None, bcs=None,
    solver_parameters=None, appctx=None,
)

Topic	Support
Markers	Caputo and left Riemann-Liouville. The latter adds the exact initial trace. Markers must wrap u directly, not a transformed expression.
Full history	Direct variable-step linear history with one stored field per accepted step.
Diffusive representations	Positive-rate Birk-Song, Diethelm, Diethelm-2022 truncated, or Yuan-Agrawal spectra. Equal mode counts do not imply equal accuracy.
Recurrence	One or more markers on scalar or fixed-size vector continuous Lagrange fields, with linear interpolation.
Auxiliary ODE	One marker on a scalar continuous Lagrange field. The monolithic \(V^{m+1}\) solve uses backward Euler or trapezoidal stepping.
Time	Positive variable dt. The residual is evaluated at t + dt. advance() updates u and history, not the caller-owned t.
State	History, statistics, reset, collective checkpointing, and Jacobian invalidation.

Warning

Diethelm2022 and YuanAgrawal are literature-comparison options rather than general-purpose defaults. They are substantially more sensitive to mode count, time range, and scaling than BirkSong and Diethelm. Diethelm2022 accepts "trapezoidal", "simpson", or "gauss-legendre" quadrature, and its target_error selects a truncation radius from a simplified envelope estimate. See Diffusive representations of time memory.

Caputo-Wismer waves and sensors

from yonderdrake.applications import (
    CaputoWismerForwardOperator,
    CaputoWismerInverseProblem,
    CaputoWismerMaterial,
    CaputoWismerReconstruction,
    CaputoWismerStepper,
    SensorArray,
    record_sensor_data,
    reconstruct_initial_pressure,
    ring_sensor_locations,
    sphere_sensor_locations,
)

Topic	Support
Wave field	Scalar continuous Lagrange spaces on 2D or 3D Firedrake meshes. Wave demos use CG2 by default.
Materials	Any fixed UFL indicator, with its own wave speed, damping, and Caputo order.
Sensors	SensorArray accepts user-supplied 2D or 3D locations. SensorArray.ring(...) is uniformly spaced in angle. SensorArray.sphere(...) uses an approximately uniform golden-angle arrangement.
Imaging	reconstruct_initial_pressure(...) iterates the Kaltenbacher method to convergence by default. Select method="adjoint" for a one-pass backprojection.
Attenuation	"dissipative" is the default reconstruction model. Select "none" to test a lossless model.
Sensor adjoint	SensorArray.adjoint_field(values) is the spatial L2 adjoint of Gaussian sampling. adjoint_covector(values) is its exact coefficient-space transpose.
Wave update	stiffness_theta=1 is the robust implicit default. The imaging helpers use the sharper centred update (0) and therefore require a CFL-safe dt.
Boundary	Optional first-order absorbing term on the exterior boundary. Sensors are independent of the mesh boundary.
Parallelism	Forward stepping and iterative reconstruction support distributed meshes. Parallel reconstruction uses PETSc TAO.

CaputoWismerStepper uses BirkSong(num_modes) by default. See Caputo-Wismer imaging for the disk, ball, and BrainWeb vessel examples.

Exponential memory

ExponentialMemory(u, decay_rate)
CaputoFabrizioOperator(u, alpha, *, normalization=1.0)

TimeMemoryStepper(
    F, t, dt, u, *,
    representation=None, formulation=None, u0=None, bcs=None,
    solver_parameters=None, appctx=None,
    warn_initial_compatibility=True,
)

Topic	Support
Operator	Single bounded-kernel memory state. Not a fractional derivative. See Exponential (fading) memory.
Stepper	TimeMemoryStepper only. FractionalTimeStepper raises ValueError, and FullHistory cannot be combined with it.
Mixing	The recurrence formulation may combine exponential and fractional markers. representation supplies the spectrum for the fractional terms. AuxiliaryODE accepts one marker.
Initial data	The mode starts at zero, so construction emits ExponentialMemoryCompatibilityWarning. Suppress with warn_initial_compatibility=False.
Caputo-Fabrizio	normalization is \(B(\alpha)\). The operator is built as a rescaled ExponentialMemory, so it carries no quadrature error of its own.

Spectral fractional Laplacian

SpectralFractionalLaplacian(
    u, s, *, bcs, sinc_truncation_target=1e-10,
    shift_cache="stream", shift_solver_parameters=None,
    mass_solver_parameters=None,
)

Topic	Support
Realization	Discrete \((-\Delta_D)^s\), \(0<s<1\).
Boundary	Complete homogeneous exterior Dirichlet conditions only.
Quadrature	sinc_truncation_target controls the sinc model, not FE operator error.
Cache	stream keeps two shifted solvers. all caches every shift.
Solvers	Shift and adjoint mass solves have separate PETSc dictionaries. Defaults use LU for small reference problems.
Diagnostics	Nodes, model estimate, setups, assemblies, solves, and reuse.

Riesz/restricted fractional Laplacian

RieszFractionalLaplacian(
    u, s, *, extension="zero", quadrature_degree=6,
    quadrature_rule="edge", assembly="matfree",
    compression_tolerance=1e-6, admissibility=1.0,
    leaf_size=16, bcs=None, mass_solver_parameters=None,
)

Topic	Support
Scope	Scalar CG1 or CG2, affine 2D triangles, \(0<s<1\), zero exterior extension.
Boundary	Complete homogeneous bcs are required for \(s\geq1/2\).
Topology	Periodic and overlapping cell geometries are unsupported.
Quadrature	Default edge degree 6 is singularity-fitted. ordinary uses Duffy tensor Gauss.
matfree	Uncompressed MPI backend with \(O(N^2)\) work and replicated sources.
dense	Uncompressed serial reference weak matrix.
hmatrix	Serial or distributed hierarchy: uncompressed near field plus ACA-compressed admissible blocks.
H-matrix controls	ACA tolerance, admissibility, and leaf size.
Mass solve	Configurable, with CG/Jacobi as the default.
Diagnostics	Storage, timings, solves, blocks, ranks, and compression.

Treat compression and quadrature as separate errors.

Periodic Fourier fractional Laplacian

PeriodicFractionalLaplacian(u, s)

Topic	Support
Realization	Fourier-series multiplier $
Scope	Scalar degree-one nodal fields on fully periodic uniform 1D intervals, 2D quadrilateral rectangles, or 3D hexahedral boxes.
Validation	Uniform spacing, tensor cells, complete periodicity, and a one-to-one global-DOF/grid map are checked collectively during construction.
Boundary	No boundary conditions. Every coordinate direction must be periodic.
MPI	Supported in 1D, 2D, and 3D.
Mesh size	Use at least three Firedrake cells in every periodic direction. Two-cell periodic coordinate localization is ambiguous.
Diagnostics	Grid shape, lengths, spacing, backend, ranks, and applications.

Checkpoints

stepper.save_checkpoint(checkpoint, name="state")
stepper.load_checkpoint(checkpoint, name="state")

These methods use an open Firedrake CheckpointFile collectively. Each name is unique within a file. checkpoint_state() and restore_checkpoint() are available for applications that manage an in-memory state dictionary instead of a Firedrake checkpoint file. Invalid state is rejected without changing the stepper. See Checkpoint and restart.