Source code for solprop.backends.numpy_ref.adams_tables

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""The coefficient tables of an Adams trial (SEP 13, SEP 16, ADR-042).

Every weight an Adams trial applies depends only on the history's normalised nodes and
the orders it scores, never on the state. The interaction formulation integrates its
interpolants: :func:`defect_rows` (each scored order's corrector less predictor, and the
step's own corrector) and :func:`fused_tables`. The exponential formulation works in the
monomial basis of its moments: :func:`exponential_corrector` and
:func:`exponential_rows`, and for native's factored defects
:func:`factored_defect_rows`; :func:`compensation_tables` are a varying operator's
transported compensation, and :func:`exponential_tables` and :func:`trial_tables` gather
them as native's march forms them in C++. The reference's engines
(:mod:`~solprop.backends.numpy_ref.multistep`) read these with the plain basis; native's
parity tests read them with its own (``helpers``).
"""

import numpy as np

from solprop._helpers import PLAIN, Helpers
from solprop.stepper.multistep import integrated_weights, lagrange_coefficients

__all__ = [
    "compensation_tables",
    "defect_rows",
    "exponential_corrector",
    "exponential_rows",
    "exponential_tables",
    "factored_defect_rows",
    "fused_tables",
    "trial_tables",
]


[docs] def defect_rows( nodes: list[float], orders: list[int], *, helpers: Helpers = PLAIN ) -> tuple[np.ndarray, np.ndarray]: """Return each order's defect weights and the step's own corrector weights. Over ``(source, newest, ...)``, order ``k``'s defect is its ``k + 1``-node corrector through the new source less its ``k``-node predictor, as integrated weights of the interaction formulation. Parameters ---------- nodes : list of float The history's normalised positions, newest first. orders : list of int The orders scored, the step's own first. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- rows : numpy.ndarray The defect rows, shape ``(len(orders), 1 + max(orders))``. corrector : numpy.ndarray The step's own corrector weights, zero past its nodes. """ width = 1 + max(orders) rows = np.zeros((len(orders), width)) corrector = np.zeros(width) for index, order in enumerate(orders): stencil = nodes[:order] through = integrated_weights([1.0, *stencil], check=False, helpers=helpers) rows[index, : order + 1] = through rows[index, 1 : order + 1] -= integrated_weights( stencil, check=False, helpers=helpers ) if index == 0: corrector[: order + 1] = through return rows, corrector
[docs] def fused_tables( nodes: list[float], order: int, orders: list[int], *, helpers: Helpers = PLAIN ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """Return an interaction-formulation trial's coefficient tables, as one record. What :class:`~solprop.backends.numpy_ref.multistep.InteractionHistory`'s trial forms; native's march forms the same tables in C++, and its parity tests read them here. Parameters ---------- nodes : list of float The history's normalised positions, newest first. order : int The step's order. orders : list of int The orders scored, the step's own first. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- tuple The predictor's integrated weights over the ``order`` newest rows; the corrector's weights over ``(source, newest, ...)``, zero past its nodes; and one defect row per scored order over the same samples. """ rows, corrector = defect_rows(nodes, orders, helpers=helpers) predictor = integrated_weights(nodes[:order], check=False, helpers=helpers) return predictor, corrector, rows
[docs] def exponential_corrector( nodes: list[float], order: int, width: int, *, helpers: Helpers = PLAIN ) -> np.ndarray: """Return the step's own corrector's Lagrange coefficients, padded to `width`. Parameters ---------- nodes : list of float The history's normalised positions, newest first. order : int The step's order. width : int ``1 + max(orders)``. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- numpy.ndarray The coefficients over ``X = (source, newest, ...)``, shape ``(width, width)``, zero past its nodes. """ corrector = np.zeros((width, width)) corrector[: order + 1, : order + 1] = lagrange_coefficients( [1.0, *nodes[:order]], check=False, helpers=helpers ) return corrector
[docs] def exponential_rows( nodes: list[float], orders: list[int], width: int, *, helpers: Helpers = PLAIN ) -> np.ndarray: """Return each order's defect coefficients in the monomial basis. Over ``X = (source, newest, ...)`` in the monomial basis of the moments, order ``k``'s defect is its ``k + 1``-node corrector through the new source less its ``k``-node predictor, as for :func:`defect_rows`; the weights are the Lagrange coefficients, which the trial's moments turn into exponential weights. Parameters ---------- nodes : list of float The history's normalised positions, newest first. orders : list of int The orders scored, the step's own first. width : int ``1 + max(orders)``. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- numpy.ndarray The defect rows, shape ``(len(orders), width, width)``. """ rows = np.zeros((len(orders), width, width)) for index, order in enumerate(orders): stencil = nodes[:order] rows[index, : order + 1, : order + 1] = lagrange_coefficients( [1.0, *stencil], check=False, helpers=helpers ) rows[index, 1 : order + 1, :order] -= lagrange_coefficients( stencil, check=False, helpers=helpers ) return rows
[docs] def factored_defect_rows( nodes: list[float], orders: list[int], width: int ) -> np.ndarray: """Return each exponential defect factored: a divided difference and a polynomial. Order ``k``'s defect, its ``k + 1``-node corrector through the new sample less its ``k``-node predictor, vanishes at the predictor's nodes, so it is ``f[1, theta_0, ..., theta_{k-1}] prod_{j<k} (theta - theta_j)``: one divided difference of the samples times one polynomial, whose integral against the flow is one combination of the moments. That is ``2 (k + 1)`` products an element instead of ``(k + 1) n_k``, the monomial rows of :func:`exponential_rows`. Parameters ---------- nodes : list of float The history's normalised positions, newest first. orders : list of int The orders scored, the step's own first. width : int ``1 + max(orders)``: the samples and the moments of the trial. Returns ------- numpy.ndarray Shape ``(len(orders), 2 width)``: the divided-difference coefficients over ``(source, newest, ...)``, then the node polynomial's ascending monomial coefficients. """ rows = np.zeros((len(orders), 2 * width)) for index, order in enumerate(orders): points = [1.0, *nodes[:order]] row = rows[index] for t, node in enumerate(points): denominator = 1.0 for s, other in enumerate(points): if s != t: denominator *= node - other row[t] = 1.0 / denominator # The node polynomial one linear factor at a time, newest node first, as the # Adams basis builds its numerators (`_basis_rows`); in plain floats, since # `numpy.polynomial.polyfromroots` costs four fifths of this function. Every # node is at or below zero, so every coefficient is positive: no cancellation. coefficients = [1.0] for root in nodes[:order]: product = [0.0, *coefficients] for power, value in enumerate(coefficients): product[power] -= root * value coefficients = product row[width : width + order + 1] = coefficients return rows
[docs] def exponential_tables( nodes: list[float], order: int, orders: list[int], *, helpers: Helpers = PLAIN ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """Return an exponential trial's coefficient tables. What :class:`~solprop.backends.numpy_ref.multistep.ExponentialHistory`'s trial forms, but for the defects, which the reference applies in the monomial basis (:func:`exponential_rows`) and native in the factored form. Parameters ---------- nodes : list of float The history's normalised positions, newest first. order : int The step's order. orders : list of int The orders scored, the step's own first. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- tuple The predictor's Lagrange coefficients over the ``order`` newest rows, shape ``(order, order)``; the corrector's over ``(source, newest, ...)``, shape ``(width, width)`` with ``width = 1 + max(orders)``; and the factored defect rows of :func:`factored_defect_rows`. """ width = 1 + max(orders) corrector = exponential_corrector(nodes, order, width, helpers=helpers) predictor = lagrange_coefficients(nodes[:order], check=False, helpers=helpers) return predictor, corrector, factored_defect_rows(nodes, orders, width)
[docs] def compensation_tables( nodes: list[float], order: int, orders: list[int], *, helpers: Helpers = PLAIN ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: """Return a trial's transported-compensation tables. The weights the reference's compensation applies (SEP 16 section 4.2, ADR-042), over the carried rows ``exp((1 - theta_j) x) (D(z_j) - x / h) u_j`` of the history samples and the endpoint term ``(D(z + h) - x / h) u_pred``, each sum still to be multiplied by the step. Parameters ---------- nodes : list of float The history's normalised positions, newest first. order : int The step's order. orders : list of int The orders scored, the step's own first. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- tuple The spans ``1 - theta_j`` of the ``width - 1`` carried samples; the predictor's weights over the ``order`` newest of them; the corrector's over ``(endpoint, newest, ...)``; and each scored order's defect weights over the same, shape ``(len(orders), width)``, with ``width = 1 + max(orders)``. """ width = 1 + max(orders) spans = np.array([1.0 - node for node in nodes[: width - 1]]) # Each count's predictor and corrector once: the step's own pair is also its # defect's, so a trial forms two weights per scored order, not two more. weights = { count: ( integrated_weights(nodes[:count], check=False, helpers=helpers), integrated_weights([1.0, *nodes[:count]], check=False, helpers=helpers), ) for count in dict.fromkeys([order, *orders]) } rows = np.zeros((len(orders), width)) for index, scored in enumerate(orders): predicted, through = weights[scored] rows[index, : scored + 1] = through rows[index, 1 : scored + 1] -= predicted predictor, corrector = weights[order] return spans, predictor, corrector, rows
[docs] def trial_tables( nodes: list[float], order: int, orders: list[int], *, compensated: bool, helpers: Helpers = PLAIN, ) -> tuple[ np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray ]: """Return all of an exponential trial's coefficient tables, as native reads them. :func:`exponential_tables`' three and, compensated, :func:`compensation_tables`' four, composed over the record's basis, read once a trial instead of from a dozen small calls. The native march forms the same tables in C++ with the same operations in the same order. Parameters ---------- nodes : list of float The history's normalised positions, newest first. order : int The step's order. orders : list of int The orders scored, the step's own first. compensated : bool Whether the trial carries a varying operator's transported compensation. helpers : solprop._helpers.Helpers, optional The implementation of the Adams basis; the plain forms by default. Returns ------- tuple The predictor, the corrector and the factored defect rows; then the compensation's spans, predictor, corrector and defect rows, shapes ``(0,)`` and ``(0, 0)`` when not compensated. """ predictor, corrector, factored = exponential_tables( nodes, order, orders, helpers=helpers ) if not compensated: return predictor, corrector, factored, *_NO_COMPENSATION spans, carried, endpoint, defects = compensation_tables( nodes, order, orders, helpers=helpers ) return predictor, corrector, factored, spans, carried, endpoint, defects
_NO_COMPENSATION = (np.empty(0), np.empty(0), np.empty(0), np.empty((0, 0))) """An uncompensated trial's compensation tables: spans, weights and defect rows."""