Method cards

A numerical method declares its math (equations, order of accuracy, assumptions, references) on the code that implements it, with methodcard:

from methodcard import NumericalMethod


class Leapfrog(Scheme):
    """Half a kick, a drift and half a kick: the velocity Verlet scheme."""

    equations = {
        "half_kick": r"v^{n+1/2} = v^n + \tfrac{1}{2} a(x^n)\,\Delta t",
        "drift": r"x^{n+1} = x^n + v^{n+1/2}\,\Delta t",
        "kick": r"v^{n+1} = v^{n+1/2} + \tfrac{1}{2} a(x^{n+1})\,\Delta t",
    }
    order = {"x": 2, "v": 2}
    components = (Kick, Drift)

or, on a function, @method(equations=..., order=...). With methodcard: true in defineDocs, the site shows them in three places:

the Numerics page lists every card of the package, by module;
with methodcard: { pages: true } each module has its own page, such as Time steps, and the sidebar a Numerics group;
each method’s API page, such as Leapfrog, has a “Numerics” section;
an MDX page shows one card with <MethodCard name="..." />:

import MethodCard from '@max-models/starlight-theme/components/MethodCard.astro';

<MethodCard name="example_pkg.schemes.Leapfrog" />

`Leapfrog`

classsource

Half a kick, a drift and half a kick: the velocity Verlet scheme.

half kick: $v^{n+1/2} = v^n + \tfrac{1}{2} a(x^n)\,\Delta t$
drift: $x^{n+1} = x^n + v^{n+1/2}\,\Delta t$
kick: $v^{n+1} = v^{n+1/2} + \tfrac{1}{2} a(x^{n+1})\,\Delta t$
energy: $\left|H(x^n, v^n) - H(x^0, v^0)\right| = \mathcal{O}(\Delta t^2) \quad \text{for all } n$

Order

x: 2, v: 2

Assumes

the acceleration depends on the position only

References

Hairer, Lubich and Wanner, Geometric Numerical Integration (2006), section I.1.4

Built from

The equations go through the site’s KaTeX, with its math.macros; “Built from” links to the cards of the parts, the name to the API entry and “source” to the line that declares it.

`midpoint_integral`

functionsource

The integral of f on [start, stop] by the composite midpoint rule.

rule: $\int_a^b f(x)\,dx \approx h \sum_{i=0}^{n-1} f\left(\frac{x_i + x_{i+1}}{2}\right)$
error: $\left|E\right| \le \frac{(b - a) h^2}{24} \max_{[a, b]} |f''|$

Order

Assumes

f twice continuously differentiable on [a, b]

References

Süli and Mayers, An Introduction to Numerical Analysis (2003), section 7.2

The cards are read from the source with griffe (methodcard export example_pkg), like the API reference, so building the docs imports nothing. The package’s tests check the same cards: TestMethodCards = method_suite("example_pkg") compares each SymPy rule with the implementation, the observed with the declared order, and the cards of the docs with those of the code.