Developer API

AbstractBasis

Supertype for symbolic feature bases accepted by data-driven algorithms. A basis maps measured states, parameters, time, and optional controls to feature values.

Interface

Subtypes must provide the following interface:

• ModelingToolkitBase.equations(b), unknowns(b), parameters(b), get_observed(b), and get_iv(b) expose the symbolic system.
• states, controls, is_implicit, and is_controlled describe the feature inputs.
• get_f or dynamics returns the callable feature evaluator.
• An explicit basis is callable as b(u, p, t) and, when controlled, as b(u, p, t, c). An implicit basis is callable as b(du, u, p, t) and, when controlled, as b(du, u, p, t, c).

The default accessors use fields named eqs, unknowns, ps, observed, iv, ctrls, implicit, f, name, and systems. A subtype with different storage must provide equivalent methods explicitly. Solver-specific requirements, such as jacobian for Koopman algorithms, should be documented by that solver.

Example

Basis is the standard implementation:

using DataDrivenDiffEq, Symbolics

@variables x
b = Basis([2x], [x])
b([3.0], [], 0.0) # [6.0]

AbstractDataDrivenAlgorithm

Supertype for algorithms that solve data-driven problems.

Interface

An algorithm package must define CommonSolve.solve! for InternalDataDrivenProblem{A} and return a DataDrivenSolution. The implementation must accept the preprocessed data and options in that internal problem, and must not require callers to construct the internal representation.

The default get_fit_targets evaluates the basis and returns the problem's implicit data. An algorithm may specialize it when its regression targets differ from the problem's implicit data. The algorithm's callable form and keyword arguments are solver-specific and must be documented by the concrete algorithm.

Example

struct MyAlgorithm <: DataDrivenDiffEq.AbstractDataDrivenAlgorithm end

DataDrivenDiffEq.get_fit_targets(::MyAlgorithm, problem, basis) =
    (basis(problem), DataDrivenDiffEq.get_implicit_data(problem))

AbstractDataDrivenResult

Supertype for algorithm-specific result objects stored by DataDrivenSolution.

Interface

Result types must implement the applicable StatsAPI.StatisticalModel accessors: coef, rss, dof, nobs, loglikelihood, nullloglikelihood, and r2. Solver packages should also provide a success predicate and a return code so that failed fits can be excluded from model selection. The result fields and the meaning of each statistic must be documented by the concrete result type.

AbstractDataDrivenProblem{N, C, K}

Supertype for data containers consumed by data-driven algorithms.

Interface

N is the numeric element type, C records whether controls are present, and K is DDProbType(1), DDProbType(2), or DDProbType(3) for direct, discrete, or continuous data. Problem subtypes must implement:

• get_implicit_data: the target matrix used by the default algorithm.
• get_oop_args: (X, p, t, U) aligned with that target matrix.
• remake_problem: a same-kind problem with selected data replaced by keyword arguments.
• is_valid: validation of finite values and compatible sample lengths.

They must also expose state, control, parameter, time, and observed data through the corresponding ModelingToolkit accessors or equivalent package methods. For a discrete problem, inputs and targets must be offset by one sample; for direct and continuous problems they must have the same sample count.

Example

DataDrivenProblem is the reference implementation:

X = [1.0 2.0 3.0]
problem = DirectDataDrivenProblem(X, 2 .* X)
get_implicit_data(problem) == 2 .* X

ABSTRACT_DIRECT_PROB{N, C}

Developer dispatch alias for direct AbstractDataDrivenProblem subtypes.

ABSTRACT_DISCRETE_PROB{N, C}

Developer dispatch alias for discrete AbstractDataDrivenProblem subtypes.

ABSTRACT_CONT_PROB{N, C}

Developer dispatch alias for continuous AbstractDataDrivenProblem subtypes.

InternalDataDrivenProblem

Preprocessed problem passed to data-driven algorithm implementations.

This type is developer API for solver packages. Application code should construct a DataDrivenProblem and call solve instead.

Fields

• alg: selected AbstractDataDrivenAlgorithm.
• testdata: held-out data used to select a result.
• traindata: batches used to fit the result.
• transform: fitted data-normalization transform.
• control_idx: basis-to-control dependency indicators.
• implicit_idx: basis-to-implicit-variable dependency indicators.
• parameter_idx: basis entries that contain only parameters.
• state_idx: basis-to-state dependency indicators.
• options: shared DataDrivenCommonOptions.
• basis: feature AbstractBasis.
• problem: source AbstractDataDrivenProblem.
• kwargs: algorithm-specific keyword arguments.

get_fit_targets(alg, problem, basis) -> (inputs, targets)

Construct the matrices fitted by a data-driven algorithm.

The default evaluates basis(problem) and uses get_implicit_data as the target. Algorithms whose target convention differs, such as Koopman algorithms, should specialize this function.

Arguments

• alg::AbstractDataDrivenAlgorithm: algorithm selecting the target convention.
• problem::AbstractDataDrivenProblem: source data.
• basis::AbstractBasis: feature basis evaluated on the source data.

Returns

• (inputs, targets): matrices passed to the algorithm implementation.

is_implicit(basis) -> Bool

Return whether basis contains implicit variables.

is_controlled(basis) -> Bool

Return whether basis contains control variables.

get_f(basis)

Return the generated callable used to evaluate basis.

Solver implementations should normally call the basis directly. This accessor is for implementations that need to reuse the generated function with specialized argument handling.

get_implicit_data(problem)

Return the target matrix fitted by the default data-driven algorithm interface.

Direct problems return Y, discrete problems return the next-step states, and continuous problems return DX.

get_oop_args(problem) -> (X, p, t, U)

Return the arguments used for out-of-place basis evaluation on problem.

Discrete problems omit the final sample so that inputs align with next-step targets.

remake_problem(problem; kwargs...) -> AbstractDataDrivenProblem

Construct a problem of the same causal kind with selected data replaced.

Keywords

• X, t, DX, Y, U, p: replacement state, time, derivative, target, control, and parameter data. Each defaults to the corresponding data in problem.

Returns

• AbstractDataDrivenProblem: a problem with the requested replacements.

assert_lhs(problem) -> (causality, timestep)

Return the equation causality and timestep used when constructing a recovered basis.

The causality is :direct, :discrete, or :continuous. The timestep is inferred for discrete time-series data and is otherwise 0.0.

apply_transform(transform, data) -> transformed_data

Apply a fitted data-normalization transform and return a transformed copy of data.

This is developer API for DataDrivenDiffEq solver packages. The supported transforms are StatsBase.ZScoreTransform and StatsBase.UnitRangeTransform, which are the transforms produced by DataNormalization.

Arguments

• transform: fitted normalization transform.
• data::AbstractArray: numeric data arranged consistently with the fitted transform.

Returns

• transformed_data: a transformed copy of data.

apply_transform!(transform, data) -> data

Apply a fitted data-normalization transform to data in place.

This is the mutating form of apply_transform and is developer API for DataDrivenDiffEq solver packages.

__construct_basis(coefficients, basis, problem, options) -> Basis

Construct a recovered Basis from an algorithm's coefficient matrix.

This is developer API for DataDrivenDiffEq solver packages. It applies coefficient rounding and sparsification from options, creates symbolic parameters when requested, and preserves the problem's direct, discrete, or continuous causality.

Arguments

• coefficients: fitted coefficient matrix, mutated during postprocessing.
• basis::AbstractBasis: feature basis used during fitting.
• problem::AbstractDataDrivenProblem: problem that determines output causality.
• options::DataDrivenCommonOptions: shared postprocessing options.

Returns

• Basis: recovered symbolic model.