Reference

Utilities

Output grid

The single shared builder of the uniform, endpoint-inclusive output time grid ([t0, t0+dt, …, tf]) that every integrator samples its results onto.

make_output_grid

make_output_grid(
    t0: float, tf: float, dt: float
) -> ndarray

Build a uniform output grid from t0 to tf (inclusive).

The grid is arange(t0, tf, dt) with tf appended when the last sample would otherwise fall short of it — so the final time is always sampled exactly, regardless of whether dt divides tf - t0.

The endpoint tolerance

tf is appended when t_arr is empty or its last sample sits below tf - 1e-12. The small absolute slack matters: when dt divides the window cleanly, the last arange sample lands on tf only up to floating-point error — typically a fraction of a ULP below it. Comparing against the bare tf would then see t_arr[-1] < tf and append a second, sub-ULP-spaced "endpoint", giving a spurious final segment of width ~1e-16. The 1e-12 slack treats any sample already within that band of tf as being the endpoint, so a cleanly-dividing window yields no duplicate tail. It is an absolute tolerance (not relative) by deliberate design: the integration windows here are O(1)–O(1e3) in time units and dt is rarely below ~1e-6, so 1e-12 is far smaller than any meaningful step yet comfortably larger than arange round-off — a relative tolerance would buy nothing and complicate the contract. (A pathological window with dt itself near 1e-12 is already rejected upstream as physically meaningless.)

This is the one chokepoint every flow family (ODE / DDE / SDE) and the engine run layer build their grid through, so it is also where the silent-footgun horizons are caught early with a domain message: a non-positive dt (which used to surface as a bare ZeroDivisionError from this helper) and a window that does not run forward in time (which used to yield a one-sample garbage trajectory).

Every bound must additionally be finite. dt and final_time were guarded only by > 0 / > t0, which +inf satisfies: an infinite dt slipped through to a two-sample [t0, tf] grid (a "trajectory" of one giant step, silently nothing like the requested sampling), and an infinite final_time reached :func:numpy.arange, which raised the unhelpful ValueError: Maximum allowed size exceeded. Both are rejected here instead, naming the offending value.

PARAMETER	DESCRIPTION
t0	Start and end of the window. TYPE: float
tf	Start and end of the window. TYPE: float
dt	Output sampling interval. Must be strictly positive. TYPE: float

RETURNS	DESCRIPTION
ndarray	The output times, with t_arr[0] == t0 and t_arr[-1] == tf.

RAISES	DESCRIPTION
InvalidParameterError	If dt is not finite and strictly positive, if t0 is not finite, or if tf is not finite and strictly after t0 (an empty / backwards / unbounded window). All subclass :class:ValueError, so except ValueError still catches them.

Examples:

>>> make_output_grid(0.0, 1.0, 0.5)
array([0. , 0.5, 1. ])

Source code in src/tsdynamics/_utils/grids.py

def make_output_grid(t0: float, tf: float, dt: float) -> np.ndarray:
    """Build a uniform output grid from ``t0`` to ``tf`` (inclusive).

    The grid is ``arange(t0, tf, dt)`` with ``tf`` appended when the last
    sample would otherwise fall short of it — so the final time is always
    sampled exactly, regardless of whether ``dt`` divides ``tf - t0``.

    The endpoint tolerance
    ----------------------
    ``tf`` is appended when ``t_arr`` is empty *or* its last sample sits below
    ``tf - 1e-12``.  The small absolute slack matters: when ``dt`` divides the
    window cleanly, the last ``arange`` sample lands on ``tf`` only up to
    floating-point error — typically a fraction of a ULP *below* it.  Comparing
    against the bare ``tf`` would then see ``t_arr[-1] < tf`` and append a second,
    sub-ULP-spaced "endpoint", giving a spurious final segment of width ~1e-16.
    The ``1e-12`` slack treats any sample already within that band of ``tf`` as
    *being* the endpoint, so a cleanly-dividing window yields no duplicate tail.
    It is an **absolute** tolerance (not relative) by deliberate design: the
    integration windows here are O(1)–O(1e3) in time units and ``dt`` is rarely
    below ~1e-6, so 1e-12 is far smaller than any meaningful step yet comfortably
    larger than ``arange`` round-off — a relative tolerance would buy nothing and
    complicate the contract.  (A pathological window with ``dt`` itself near
    1e-12 is already rejected upstream as physically meaningless.)

    This is the one chokepoint every flow family (ODE / DDE / SDE) and the
    engine run layer build their grid through, so it is also where the
    silent-footgun horizons are caught early with a domain message: a
    non-positive ``dt`` (which used to surface as a bare ``ZeroDivisionError``
    from this helper) and a window that does not run forward in time (which used
    to yield a one-sample garbage trajectory).

    Every bound must additionally be **finite**.  ``dt`` and ``final_time`` were
    guarded only by ``> 0`` / ``> t0``, which ``+inf`` satisfies: an infinite
    ``dt`` slipped through to a two-sample ``[t0, tf]`` grid (a "trajectory" of
    one giant step, silently nothing like the requested sampling), and an
    infinite ``final_time`` reached :func:`numpy.arange`, which raised the
    unhelpful ``ValueError: Maximum allowed size exceeded``.  Both are rejected
    here instead, naming the offending value.

    Parameters
    ----------
    t0, tf : float
        Start and end of the window.
    dt : float
        Output sampling interval.  Must be strictly positive.

    Returns
    -------
    ndarray
        The output times, with ``t_arr[0] == t0`` and ``t_arr[-1] == tf``.

    Raises
    ------
    tsdynamics.errors.InvalidParameterError
        If ``dt`` is not finite and strictly positive, if ``t0`` is not finite,
        or if ``tf`` is not finite and strictly after ``t0`` (an empty /
        backwards / unbounded window).  All subclass :class:`ValueError`, so
        ``except ValueError`` still catches them.

    Examples
    --------
    >>> make_output_grid(0.0, 1.0, 0.5)
    array([0. , 0.5, 1. ])
    """
    from tsdynamics.errors import invalid_value

    if not (math.isfinite(dt) and dt > 0):
        raise invalid_value("dt", dt, rule="must be finite and > 0 (the output sampling interval)")
    if not math.isfinite(t0):
        raise invalid_value("t0", t0, rule="must be finite (the start of the window)")
    if not math.isfinite(tf):
        raise invalid_value(
            "final_time",
            tf,
            rule="must be finite (the window has to have an end to sample)",
        )
    if not tf > t0:
        raise invalid_value(
            "final_time",
            tf,
            rule=f"must run forward in time (be > the start time {t0!r})",
            hint="check the sign and that final_time exceeds t0",
        )
    t_arr = np.arange(t0, tf, dt)
    if t_arr.size == 0 or t_arr[-1] < tf - 1e-12:
        t_arr = np.append(t_arr, tf)
    return t_arr