Crate multishoot

Expand description

Multiple shooting for boundary-value problems, in double-, quad- and octo-double precision.

A boundary-value problem asks for the solution of differential equations that meets conditions at two or more places. Multiple shooting splits the interval at nodes, integrates the equations across each piece from the values held at its start, and asks Newton’s method to make every piece end where the next one begins. The unknowns are the values at the nodes, the data of series that start the solution at singular endpoints, and global parameters such as an eigenvalue; the residual is the list of mismatches; it is zero exactly when the pieces join into one solution.

The crate is the engine of that method, generic over the equations, built on multidouble’s arithmetic:

the equations enter through one trait: the Taylor coefficients of their right-hand side at a point, and the series that start the solution at the endpoints;
between the nodes the solution is carried by Taylor series, with steps planned so that each truncation term stays below a tolerance;
the fields may depend on a periodic variable, represented on collocation points, with exact derivatives in it;
the Jacobian is exact, by forward-mode dual numbers over the same code that forms the residual, and so is its product with a vector, from one pass per block;
Newton’s method runs in double-double, quad-double or octo-double (multidouble’s Precision), as the conditioning requires, and the residual can be expanded as a Taylor series in a parameter of the equations.

Status: under construction (0.1.0, not published).

Modules:

equations: the Equations trait, the state and the Taylor work arrays;
taylor: Taylor steps, paths and the step planner;
shooting: the layout (Shooting): nodes, segments, the unknown vector and the residual’s blocks;
residual: the residual F(z) in any precision;
jacobian: its exact Jacobian by forward-mode duals;
jvp: the Jacobian-vector product J v by one forward-mode pass per block, without the Jacobian;
newton: the Newton step and the damped Newton loop;
fast: the f64 Jacobian from f64-tangent lanes, dense or in staircase storage, and the mixed-precision Newton;
jet: the residual’s Taylor series in a parameter of the equations;
mode: the mode matrix, the linearization for perturbations growing at a complex rate, and its determinant;
prec: helpers for states held as part arrays in any of multidouble’s precisions (Precision: double-double Double, quad-double Quad, octo-double Octo);
periodic: collocation grids in the periodic variable and their derivative matrices;
projected: one field’s rows of a block replaced by a projection onto its low harmonics;
lane: the lane types the engine is generic over;
control (feature mutate): deliberate errors, the controls of the accuracy checks.

Re-exports§

pub use equations::Equations;
pub use equations::State;
pub use equations::Work;
pub use fast::MixedLu;
pub use fast::Storage;
pub use mode::ModeMatrix;
pub use mode::Rate;
pub use newton::NewtonOpts;
pub use newton::NewtonReport;
pub use projected::ProjectedRows;
pub use shooting::ExtraRow;
pub use shooting::Shooting;
pub use taylor::Plan;
pub use multidouble;

Modules§

equations: The problem’s side of the engine: the Equations trait, the state at a point and the work arrays of one Taylor step.
fast: The fast path of Newton’s method: the Jacobian in f64 from lanes with f64 tangents, several columns per evaluation, stored dense or factored in staircase storage, and the mixed-precision Newton step built on it.
jacobian: The exact Jacobian dF/dz by forward-mode duals (Wengert, Commun. ACM 7, 463 (1964)), in any precision: one evaluation of a block per column, with a unit tangent on one of its inputs or on a global, through the same code that forms the residual.
jet: The residual’s Taylor series in a parameter: the residual on a jet state z(h) = sum_k z_k h^k, in the lanes P::J<N> (multidouble’s Jet, QJet, OJet), with the equations’ parameter entered as the jet variable.
jvp: The Jacobian-vector product J v without the Jacobian: one forward-mode pass per block (Wengert, Commun. ACM 7, 463 (1964)), with the block’s inputs and the globals carrying v’s entries as their tangents, in any precision.
lane: The lane types the engine is generic over: multidouble’s dual::Lane (values, tangents, jets) with its field::MatLane (the product with a constant matrix such as d/dtheta), on the compile-time backend Native.
mode: The mode matrix: the linearization of the shooting system about a background, for perturbations that grow as exp(lambda t) in a variable t of the equations, and its determinant, whose zeros in lambda are the growth rates of the background’s modes.
newton: Newton’s method on F(z) = 0 in any precision: the step dz = -J^-1 F with the exact Jacobian and a dense LU, and a damped loop.
periodic: The periodic direction: collocation grids in theta, the spectral derivative d/dtheta on them, and sines and cosines in double-double, and in octo-double for constants that must be exact in every precision.
prec: Helpers for states held as PARTS arrays of f64 (part q of unknown i at z[q][i]), in any of multidouble’s precisions (precision::Precision: Double, Quad, Octo), which the residual, the Jacobian and Newton’s method are written over.
projected: Projected rows: one field’s rows of one block replaced by a projected condition, a constraint of the layout.
residual: The residual F(z) in any of multidouble’s precisions (Precision): every block’s state from its inputs, minus its target node, then the extra rows. F is zero exactly when the pieces join into one solution that meets the extra conditions.
shooting: The layout of a multiple-shooting problem: the nodes, the segments of Taylor steps between them, the unknown vector and the residual’s blocks.
taylor: Taylor stepping in x: one step from the coefficients of Equations::taylor_coeffs summed by Horner’s rule, a path of steps through given points, and the planner that chooses those points so that each step’s last terms stay below a tolerance.

Structs§

DD
Double: Double-double: DD, DV, Du, Jet<N>, DDLu; its dot product is the plain sum of double-double products
Fl: 8 B values of the lane type T as B lane vectors: value j is lane j % 8 of vector j / 8.
Octo: Octo-double: OD, OV, Ou, OJet<N>, ODLu, OdAcc
Quad: Quad-double: QD, QV, Qu, QJet<N>, QDLu, QdAcc

Traits§

Precision: One multi-double precision on the backend S: its types, and the operations whose names differ between precisions. Every method delegates to the precision’s own method and returns its result bit for bit.

Functions§

cs: Cauchy product coefficient sum_{j=0..k} x[j] y[k-j]
cs_range: sum_{j=lo..=hi} x[j] y[k-j]
cs_w: sum_{j=lo..=hi} (w(j) x[j]) y[k-j] with exact f64 weights w(j) (small integers, as in the coefficients of a derivative)
horner: Horner evaluation sum_k s[k] h^k

Type Aliases§

Native: The backend the build’s target features select at compile time (the cargo feature portable forces the plain array).