Explicit and implicit Runge-Kutta numerical ODE solvers (ode45, ode23, ode113, ode15s, ode23s) and event handling. More...

Files
file	options.hpp
file	solvers.hpp

Functions
Value	nk::ode::odeset (const Value args, std::size_t nargs, std::pmr::memory_resource mr=nullptr)
	Build / extend an ODE options struct (odeset(...)).
Value	nk::ode::odeget (const Value &opts, const Value &name, const Value &default_v, std::pmr::memory_resource *mr=nullptr)
	Read a single field from an ODE options struct (val = odeget(opts, 'Name'[, default])).
std::tuple< Value, Value >	nk::ode::ode45 (FnHandle rhs, const Value &tspan, const Value &y0, const Value &opts, std::pmr::memory_resource *mr=nullptr)
	Explicit Dormand-Prince 5(4) RK solver ([t, y] = ode45(f, tspan, y0[, opts])).
std::tuple< Value, Value >	nk::ode::ode23 (FnHandle rhs, const Value &tspan, const Value &y0, const Value &opts, std::pmr::memory_resource *mr=nullptr)
	Explicit Bogacki-Shampine 3(2) RK solver ([t, y] = ode23(f, tspan, y0[, opts])).

Detailed Description

Explicit and implicit Runge-Kutta numerical ODE solvers (ode45, ode23, ode113, ode15s, ode23s) and event handling.

Function Documentation

◆ ode23()

std::tuple< Value, Value > nk::ode::ode23	(	FnHandle	rhs,
		const Value &	tspan,
		const Value &	y0,
		const Value &	opts,
		std::pmr::memory_resource *	mr = nullptr )

Explicit Bogacki-Shampine 3(2) RK solver ([t, y] = ode23(f, tspan, y0[, opts])).

Solves the IVP dy/dt = f(t, y), y(t0) = y0 from t0 = tspan(1) to tf = tspan(end). Uses the 4-stage embedded pair of Bogacki & Shampine (1989) with the FSAL property, controlling local error with the 2nd-order embedded estimate. Step-size control follows the standard adaptive formula (Hairer-Nørsett-Wanner I, §II.4, Eq. 4.13) with safety = 0.9 and 3rd-order exponent.

MATLAB ode23 default Refine = 1 (no interpolation between accepted steps), unlike ode45 which defaults to 4. Override via odeset. Dense output (used for Refine > 1 or explicit tspan with ≥ 3 points) is the cubic Hermite interpolant between (y_n, k1) and (y_{n+1}, k4), which is 3rd-order accurate — matching MATLAB (Shampine-Reichelt 1997).

Parameters

rhs	RHS callback (Engine-free nk::FnHandle): args={t,y} → outs[0]=dy/dt.
tspan	Time vector (length ≥ 2, strictly monotonic).
y0	Initial state (column or row vector; flattened).
opts	Options struct from odeset (or Value::Empty).
mr	Memory resource.

Returns: {t, y} — t is an m × 1 column of accepted/sampled times; y is an m × d matrix with each row a state.

◆ ode45()

std::tuple< Value, Value > nk::ode::ode45	(	FnHandle	rhs,
		const Value &	tspan,
		const Value &	y0,
		const Value &	opts,
		std::pmr::memory_resource *	mr = nullptr )

Explicit Dormand-Prince 5(4) RK solver ([t, y] = ode45(f, tspan, y0[, opts])).

Solves the IVP dy/dt = f(t, y), y(t0) = y0 from t0 = tspan(1) to tf = tspan(end). The step size is chosen adaptively to keep the local truncation error below max(RelTol · max(|y_old|, |y_new|), AbsTol) per component.

Time output:

tspan = [t0, tf] → return every accepted step;
tspan = [t0, ..., tf] (≥ 3 unique points) → return values only at tspan, computed by shortening the integration step to land exactly on each target.

The RHS is an Engine-free nk::FnHandle callback: it receives args = {t, y} and writes dy/dt into outs[0]. C++ embedders pass a stack lambda directly (no Engine needed); the MATLAB-facing adapter wraps the script function-handle via Engine::callFunctionHandle into an FnHandle.

Parameters

rhs	RHS callback: args={t (scalar), y (d×1)} → outs[0]=dy/dt (d×1).
tspan	Time vector (length ≥ 2, strictly monotonic).
y0	Initial state (column or row vector; flattened).
opts	Options struct from odeset (or Value::Empty).
mr	Memory resource.

Returns: {t, y} — t is an m × 1 column of accepted/sampled times; y is an m × d matrix with each row a state.

◆ odeget()

Value nk::ode::odeget	(	const Value &	opts,
		const Value &	name,
		const Value &	default_v,
		std::pmr::memory_resource *	mr = nullptr )

Read a single field from an ODE options struct (val = odeget(opts, 'Name'[, default])).

Returns the value of Name from opts, or default (or []) if unset. Case-insensitive name lookup.

◆ odeset()

Value nk::ode::odeset	(	const Value *	args,
		std::size_t	nargs,
		std::pmr::memory_resource *	mr = nullptr )

Build / extend an ODE options struct (odeset(...)).

MATLAB signatures supported:

opts = odeset() — return defaults.
opts = odeset('Name', Value, ...) — name-value pairs.
opts = odeset(old, 'Name', Value, ...) — extend an existing struct.
opts = odeset(old, new) — merge two structs (new wins).

Recognised names (case-insensitive, MATLAB convention): RelTol, AbsTol, NormControl, MaxStep, InitialStep, NonNegative, Refine, Stats, OutputFcn, OutputSel, Mass, MStateDependence, MvPattern, MassSingular, InitialSlope, Vectorized, Events, BDF, MaxOrder, Jacobian, JPattern.

Unknown names throw m:odeset:badName. Unset names default to [].