Detailed API reference

This page is generated from Yonderdrake’s public Python objects. The concise support tables and method-selection guidance remain in API and supported scope.

Time-memory operators

Yonderdrake public interface.

Markers

yonderdrake.CaputoDerivative(u, alpha)[source]

Create a Caputo marker for FractionalTimeStepper.

Parameters:
Return type:

Any

yonderdrake.RiemannLiouvilleDerivative(u, alpha)[source]

Create a left Riemann-Liouville marker.

Parameters:
Return type:

Any

yonderdrake.ExponentialMemory(u, decay_rate)[source]

Create a one-timescale fading-memory marker.

Parameters:
Return type:

Any

yonderdrake.CaputoFabrizioOperator(u, alpha, *, normalization=1.0)[source]

Return the published Caputo-Fabrizio exponential-memory operator.

Parameters:
Return type:

Any

Representations

class yonderdrake.BirkSong(num_modes, **method_parameters)[source]

Birk-Song’s squared Cayley-transform Gauss-Jacobi spectrum.

Parameters:

  • num_modes (int)

  • method_parameters (Any)

class yonderdrake.Cayley(num_modes, *, power=None, t_final=None, min_step=None, **method_parameters)[source]

Cayley-transform diffusive spectrum with a selectable exponent.

The rate map is ((1 - x) / (1 + x)) ** power over the Gauss-Jacobi reference interval, so power sets how many decades of relaxation rate a given mode count spans. Diethelm2008 and BirkSong are the published power=2 and power=4 members of this family.

Pass t_final and min_step to size the exponent from the time range the problem needs, or power to set it directly.

Parameters:

  • num_modes (int)

  • power (float | None)

  • t_final (float | None)

  • min_step (float | None)

  • method_parameters (Any)

property power: float

Return the Cayley exponent this spectrum was built with.

class yonderdrake.Jacobi(num_modes, *, sigma, rho, **method_parameters)[source]

Two-parameter Gauss-Jacobi diffusive representation.

sigma controls the rate-map behaviour near x=1 and rho controls it near x=-1. Both parameters must be finite and positive.

Parameters:

  • num_modes (int)

  • sigma (float)

  • rho (float)

  • method_parameters (Any)

property sigma: float

Return the exponent controlling the low-rate end of the map.

property rho: float

Return the exponent controlling the high-rate end of the map.

class yonderdrake.Diethelm2008(num_modes, **method_parameters)[source]

Diethelm2008’s Gauss-Jacobi improvement of the diffusive representation.

Parameters:

  • num_modes (int)

  • method_parameters (Any)

class yonderdrake.SumOfExponentials(*, target_error, t_final, min_step)[source]

Tolerance-driven positive sum of exponentials from Jiang et al.

Parameters:
spectrum(alpha)[source]

Construct the positive spectrum on the declared time interval.

Parameters:

alpha (float)

Return type:

DiffusiveSpectrum

describe(alpha=None)[source]

Describe the requested interval or one generated spectrum.

Parameters:

alpha (float | None)

Return type:

dict[str, Any]

class yonderdrake.Diethelm2022(num_modes, *, quadrature='trapezoidal', target_error=1e-08, decay_scale=1.0, truncation_radius=None, rate_scale=1.0)[source]

Discretize Diethelm2008’s 2022 real-line representation.

quadrature selects the published Gauss-Laguerre construction or a truncated composite trapezoidal, composite Simpson, or Gauss-Legendre rule. Gauss-Laguerre requires an even num_modes because each node produces two modes. Simpson quadrature requires an odd num_modes. The truncation controls apply only to the three truncated rules.

Warning:

This representation is provided for expert use and comparison. It is more sensitive to mode count, time range, and scaling than BirkSong or Diethelm2008.

Parameters:
spectrum(alpha)[source]

Generate positive modes for the selected quadrature.

Parameters:

alpha (float)

Return type:

DiffusiveSpectrum

describe(alpha=None)[source]

Describe the configuration or one ordered spectrum.

Parameters:

alpha (float | None)

Return type:

dict[str, Any]

class yonderdrake.YuanAgrawal(num_modes, *, rate_scale=1.0)[source]

Original Yuan-Agrawal Gauss-Laguerre diffusive spectrum.

Warning:

This representation is provided for expert use and comparison. It is generally less robust per mode than BirkSong or Diethelm2008.

Parameters:
spectrum(alpha)[source]

Generate the original squared-node Gauss-Laguerre spectrum.

Parameters:

alpha (float)

Return type:

DiffusiveSpectrum

describe(alpha=None)[source]

Describe the configuration or one generated spectrum.

Parameters:

alpha (float | None)

Return type:

dict[str, Any]

class yonderdrake.SineDiffusive(num_modes)[source]

Sine diffusive representation of Khosravian-Arab and Dehghan.

Warning:

This undamped, slowly convergent representation is provided for literature comparison. Use a positive-rate representation for routine simulations.

Parameters:

num_modes (int)

spectrum(alpha)[source]

Construct the generalized Gauss-Laguerre oscillator spectrum.

Parameters:

alpha (float)

Return type:

OscillatorSpectrum

describe(alpha=None)[source]

Describe the configuration or one generated spectrum.

Parameters:

alpha (float | None)

Return type:

dict[str, Any]

class yonderdrake.FullHistory[source]

Direct time history with piecewise-linear interpolation.

Formulations and steppers

class yonderdrake.Recurrence(interpolant='quadratic')[source]

Eliminated constant-memory recurrence formulation.

Parameters:

interpolant (str)

describe()[source]

Return deterministic checkpoint metadata.

Return type:

dict[str, str]

class yonderdrake.AuxiliaryODE(scheme='backward_euler')[source]

Auxiliary-ODE formulation solving the field and its modes together.

Where Recurrence eliminates the memory modes from the field solve, this couples them into one monolithic system on V^(m+1), which is what makes the modes reachable from PETSc.

Parameters:

scheme (str)

class yonderdrake.Oscillator[source]

Exact two-field rotation for sine diffusive memory modes.

yonderdrake.FractionalTimeStepper(F, representation, t, dt, u, *, formulation=None, u0=None, bcs=None, solver_parameters=None, appctx=None)[source]

Construct a native formulation for a fractional derivative marker.

Parameters:
Return type:

Any

yonderdrake.TimeMemoryStepper(F, t, dt, u, *, representation=None, formulation=None, u0=None, bcs=None, solver_parameters=None, appctx=None, warn_initial_compatibility=True)[source]

Advance exponential memory and optional fractional time markers.

Parameters:
Return type:

Any

class yonderdrake.ExponentialMemoryCompatibilityWarning[source]

Warn that bounded-kernel evolution requires compatible initial data.

class yonderdrake.ModeCountAdvisoryWarning[source]

Warn that a representation is beyond its useful mode-count range.

class yonderdrake.StartingCorrectionAdvisoryWarning[source]

Warn that Lubich starting corrections are poorly conditioned.

Spatial operators

yonderdrake.SpectralFractionalLaplacian(u, s, *, bcs=None, sinc_truncation_target=1e-10, shift_cache='stream', shift_solver_parameters=None, mass_solver_parameters=None)[source]

Create (-Delta)^s with Dirichlet or natural Neumann boundaries.

Omitting bcs uses the discrete Neumann Laplacian. Supplying bcs selects the homogeneous-Dirichlet realization and must constrain the complete exterior boundary.

Parameters:

  • u (Any)

  • s (Any)

  • bcs (Any)

  • sinc_truncation_target (float)

  • shift_cache (str)

  • shift_solver_parameters (Any)

  • mass_solver_parameters (Any)

Return type:

Any

yonderdrake.RieszFractionalLaplacian(u, s, *, extension='zero', quadrature_degree=6, quadrature_rule='boundary', assembly='matfree', compression_tolerance=1e-06, admissibility=1.0, leaf_size=16, bcs=None, mass_solver_parameters=None)[source]

Create the zero-exterior operator on affine triangles or tetrahedra.

Parameters:

  • u (Any)

  • s (Any)

  • extension (str)

  • quadrature_degree (int)

  • quadrature_rule (str)

  • assembly (str)

  • compression_tolerance (float)

  • admissibility (float)

  • leaf_size (int)

  • bcs (Any)

  • mass_solver_parameters (Any)

Return type:

Any

yonderdrake.PeriodicFractionalLaplacian(u, s)[source]

Create the Fourier multiplier (-Delta_periodic)^s.

Parameters:
Return type:

Any

Caputo-Wismer applications

Application-level building blocks.

class yonderdrake.applications.CaputoWismerMaterial(*, indicator, density, wave_speed, damping, alpha)[source]

One piecewise acoustic material in a Caputo-Wismer model.

Parameters:
class yonderdrake.applications.SensorArray(space, locations, *, width)[source]

Gaussian volume sensors with a matching discrete adjoint.

Parameters:

  • space (Any)

  • locations (Any)

  • width (float)

classmethod ring(space, num_sensors, radius, *, width, center=(0.0, 0.0))[source]

Construct a two-dimensional circular sensor array.

Parameters:
Return type:

SensorArray

classmethod sphere(space, num_sensors, radius, *, width, center=(0.0, 0.0, 0.0))[source]

Construct a three-dimensional spherical sensor array.

Parameters:
Return type:

SensorArray

sample(field)[source]

Return the spatially averaged value recorded by every sensor.

Parameters:

field (Any)

Return type:

ndarray

adjoint_field(values, *, out=None)[source]

Map sensor values back to their normalized spatial kernels.

Parameters:
Return type:

Any

adjoint_covector(values, *, out=None)[source]

Apply the exact coefficient-space transpose of sample.

Parameters:
Return type:

Any

class yonderdrake.applications.CaputoWismerStepper(u, t, dt, *, materials, representation=None, num_modes=32, volume_source=None, boundary_source=None, boundaries=(), initial_velocity=0.0, bcs=None, stiffness_theta=1.0, solver_parameters=None, appctx=None)[source]

Advance a heterogeneous Caputo-Wismer wave equation.

Parameters:

  • u (Any)

  • t (Any)

  • dt (Any)

  • materials (Sequence[CaputoWismerMaterial])

  • representation (Any)

  • num_modes (int)

  • volume_source (Any)

  • boundary_source (Any)

  • boundaries (Sequence[CaputoWismerImpedanceBoundary])

  • initial_velocity (Any)

  • bcs (Any)

  • stiffness_theta (float)

  • solver_parameters (Any)

  • appctx (Any)

advance()[source]

Advance one step and commit the two physical wave histories.

Return type:

None

reset(u0, *, initial_velocity=0.0, t0=None)[source]

Reset the wave field, velocity, and fractional memory.

Parameters:
Return type:

None

class yonderdrake.applications.CaputoWismerSource(*, profile, signal, region='volume', boundary_id=None)[source]

A separable spatial profile and time signal.

Parameters:

  • profile (Any)

  • signal (Any)

  • region (Literal['volume', 'boundary'])

  • boundary_id (Any)

classmethod volume(profile, signal)[source]

Create a volume forcing profile * signal(t).

Parameters:
Return type:

CaputoWismerSource

classmethod boundary(profile, signal, *, boundary_id=None)[source]

Create incoming data for a natural or absorbing boundary.

Parameters:

  • profile (Any)

  • signal (Any)

  • boundary_id (Any)

Return type:

CaputoWismerSource

class yonderdrake.applications.CaputoWismerArraySource(*, array, signals)[source]

Independent time signals injected through a sensor-array transpose.

Parameters:
class yonderdrake.applications.CaputoWismerImpedanceBoundary(*, coefficient, boundary_id=None)[source]

A first-order outgoing-wave condition on a marked boundary.

Parameters:

  • coefficient (Any)

  • boundary_id (Any)

class yonderdrake.applications.CaputoWismerPML(*, damping, outer_boundary=True, interior_bounds=None, reflection=None, polynomial_order=None)[source]

Directional damping fields for a time-domain acoustic PML.

Parameters:
classmethod box(mesh, interior_bounds, *, reference_speed, reflection=1e-06, polynomial_order=3, outer_bounds=None, outer_boundary=True)[source]

Construct polynomial PML profiles around an interior box.

Parameters:

  • mesh (Any)

  • interior_bounds (Any)

  • reference_speed (float)

  • reflection (float)

  • polynomial_order (int)

  • outer_bounds (Any)

  • outer_boundary (bool)

Return type:

CaputoWismerPML

yonderdrake.applications.ring_sensor_locations(num_sensors, radius, *, center=(0.0, 0.0))[source]

Return uniformly spaced sensor centres on a two-dimensional ring.

Parameters:
Return type:

ndarray

yonderdrake.applications.sphere_sensor_locations(num_sensors, radius, *, center=(0.0, 0.0, 0.0))[source]

Return approximately uniform sensor centres on a three-dimensional sphere.

Parameters:
Return type:

ndarray

class yonderdrake.applications.CaputoWismerModel(space, *, materials, dt, num_steps, sensors=None, sources=(), boundaries=(), pml=None, attenuation='dissipative', attenuation_filter_length=None, attenuation_filter_order=2, num_modes=32, representation=None, stiffness_theta=None, solver_parameters=None)[source]

A conservative acoustic model and its exact discrete adjoint.

Parameters:
propagate(initial_pressure, *, record_history=False)[source]

Advance an initial pressure and configured time-dependent sources.

Parameters:

  • initial_pressure (Any)

  • record_history (bool)

Return type:

CaputoWismerPropagation

adjoint_covector(sensor_values)[source]

Apply the exact transpose of the initial-pressure observation map.

Parameters:

sensor_values (Any)

Return type:

Any

adjoint(sensor_values)[source]

Return the spatial L2 representative of the discrete adjoint.

Parameters:

sensor_values (Any)

Return type:

Any

class yonderdrake.applications.CaputoWismerInverseProblem(model, sensor_data, *, regularization=1e-06)[source]

Regularized initial-pressure reconstruction for one acoustic model.

Parameters:
objective_gradient(candidate)[source]

Return the Tikhonov objective and coefficient-space gradient.

Parameters:

candidate (Any)

Return type:

tuple[float, Any]

solve(*, initial_guess=None, max_iterations=100, tolerance=1e-05, positivity=True, warm_start=True)[source]

Minimize the regularized sensor-data misfit.

Parameters:

  • initial_guess (Any)

  • max_iterations (int)

  • tolerance (float)

  • positivity (bool)

  • warm_start (bool)

Return type:

CaputoWismerReconstruction

class yonderdrake.applications.CaputoWismerReconstruction(pressure, converged, iterations, objective, objective_history, message, function_evaluations, forward_seconds, adjoint_seconds, elapsed_seconds)[source]

Result and diagnostics from an iterative reconstruction.

Parameters:
yonderdrake.applications.reconstruct_initial_pressure(model, sensor_data, *, method='kaltenbacher', regularization=1e-06, initial_guess=None, max_iterations=100, tolerance=1e-05, positivity=True, warm_start=True, compensate_attenuation=True, filter_length=None, filter_order=2)[source]

Reconstruct initial pressure with the selected method.

Parameters:
Return type:

Any

yonderdrake.applications.time_reverse_sensor_data(model, sensor_data, *, compensate_attenuation=True, filter_length=None, filter_order=2, positivity=False)[source]

Backpropagate sensor traces through a lossless or compensated model.

Parameters:
Return type:

Any