Problem Types

AbstractStateSpaceProblem <: AbstractDEProblem

Abstract supertype for all discrete-time state-space problems in DifferenceEquations.jl.

Every concrete subtype supplies an initial state u0, an integer-step tspan, parameters p, and model-specific fields required by the solver. The public problem interface is consumed by solve, init, SciMLBase.remake, and StateSpaceSolution.

Interface

Callers may treat any subtype as an AbstractDEProblem and pass it to the standard SciML problem and solver functions. The time span must have an integer distance because the discrete trajectory contains one state for every integer step. Additional problem subtypes must preserve the callback and field semantics described by their concrete constructors.

The internal solver hooks used to implement additional problem types are documented on the developer API page. They are package-extension interfaces, not a requirement for ordinary users.

Examples

julia> using DifferenceEquations

julia> prob = LinearStateSpaceProblem([1.0;;], nothing, [0.0], (0, 2));

julia> prob isa AbstractStateSpaceProblem
true

Subtypes include LinearStateSpaceProblem, QuadraticStateSpaceProblem, PrunedQuadraticStateSpaceProblem, and StateSpaceProblem.

LinearStateSpaceProblem(A, B, u0, tspan[, p]; kwargs...)

Define a linear time-invariant state-space model:

\[u_{n+1} = A \, u_n + B \, w_{n+1}\]

with optional observation equation $z_n = C \, u_n + v_n$.

Arguments

• A: Transition matrix (n×n).
• B: Noise input matrix (n×k), or nothing for deterministic dynamics.
• u0: Initial state vector, or a Distribution for random initial conditions.
• tspan: Time span as (t0, t_end) with integer distance (e.g., (0, T)).
• p: Parameters (default: NullParameters()).

Keyword Arguments

• C: Observation matrix (m×n). If nothing, no observations are computed.
• observables_noise: Observation noise covariance matrix (AbstractMatrix, e.g. Diagonal(d) or Symmetric(H * H')).
• observables: Observed data as Vector{Vector{T}} for likelihood computation.
• noise: Fixed noise sequence as Vector{Vector{T}}. If nothing, noise is drawn randomly.
• u0_prior_mean: Prior mean for Kalman filtering.
• u0_prior_var: Prior covariance matrix for Kalman filtering.
• syms: State variable names (e.g., (:x, :y)) for symbolic indexing.
• obs_syms: Observation variable names for symbolic indexing.

Notes

• Providing u0_prior_mean, u0_prior_var, observables, and observables_noise (with noise = nothing) triggers automatic selection of KalmanFilter.
• The observables timing convention: observations correspond to $z_1, z_2, \ldots$ (starting from the second state), so pass T observations for a tspan of (0, T).

See also: StateSpaceProblem, QuadraticStateSpaceProblem, DirectIteration, KalmanFilter.

Fields

• f: Internal SciMLBase.ODEFunction bridge used for SciML interfaces and symbolic indexing; it does not define the state transition.
• A: State transition matrix.
• B: Noise input matrix or nothing for deterministic dynamics.
• C: Observation matrix or nothing when observations are disabled.
• u0: Initial state or initial-state distribution.
• tspan: Integer-step time span.
• p: User parameters.
• observables_noise, observables, noise: Observation and simulation data.
• u0_prior_mean, u0_prior_var: Optional Gaussian prior for KalmanFilter.
• syms, obs_syms: Optional state and observation names for symbolic indexing.
• kwargs: Additional constructor keyword arguments retained for remaking.

Returns

• LinearStateSpaceProblem: A SciML-compatible linear discrete-time problem.

Throws

• ArgumentError: If tspan does not have an integer distance.

Examples

julia> using DifferenceEquations

julia> prob = LinearStateSpaceProblem([1.0;;], nothing, [1.0], (0, 2));

julia> length(solve(prob).u)
3

QuadraticStateSpaceProblem(A_0, A_1, A_2, B, u0, tspan[, p]; kwargs...)

Define a second-order (quadratic) state-space model:

\[u_{n+1} = A_0 + A_1 \, u_n + u_n^\top A_2 \, u_n + B \, w_{n+1}\]

with optional observation equation $z_n = C_0 + C_1 \, u_n + u_n^\top C_2 \, u_n + v_n$.

Arguments

• A_0: Constant drift vector (length n).
• A_1: Linear transition matrix (n×n).
• A_2: Quadratic transition tensor (n×n×n). Entry A_2[i,:,:] gives the matrix for the i-th element of the quadratic term.
• B: Noise input matrix (n×k), or nothing.
• u0: Initial state vector.
• tspan: Time span as (t0, t_end) with integer distance.
• p: Parameters passed through the SciML problem interface (default: NullParameters()).

Keyword Arguments

• C_0: Constant observation term, or nothing when observations are disabled.
• C_1: Linear observation matrix, or nothing when observations are disabled.
• C_2: Quadratic observation tensor, or nothing when observations are disabled.
• observables_noise: Observation covariance matrix, or nothing.
• observables: Observed data used for likelihood calculations, or nothing.
• noise: Fixed process-noise sequence, or nothing for generated noise.
• syms: State variable names for symbolic indexing, or nothing.
• obs_syms: Observation variable names for symbolic indexing, or nothing.
• kwargs...: Additional constructor keywords retained in the problem.

References

• Andreasen, Fernandez-Villaverde, and Rubio-Ramirez (2017), "The Pruned State-Space System for Non-Linear DSGE Models: Theory and Empirical Applications."

See also: PrunedQuadraticStateSpaceProblem, LinearStateSpaceProblem.

Fields

• A_0, A_1, A_2: Constant, linear, and quadratic transition coefficients.
• f: Internal SciMLBase.ODEFunction bridge used for SciML interfaces and symbolic indexing.
• B: Noise input matrix or nothing.
• C_0, C_1, C_2: Optional observation coefficients.
• u0: Initial state.
• tspan: Integer-step time span.
• p: User parameters.
• observables_noise, observables, noise: Observation and simulation data.
• syms, obs_syms: Optional state and observation names for symbolic indexing.
• kwargs: Additional constructor keyword arguments retained for remaking.

Returns

• QuadraticStateSpaceProblem: A quadratic discrete-time state-space problem.

Throws

• ArgumentError: If tspan does not have an integer distance.

Examples

julia> using DifferenceEquations

julia> prob = QuadraticStateSpaceProblem([0.0], [1.0;;], zeros(1, 1, 1), nothing, [1.0], (0, 2));

julia> length(solve(prob).u)
3

PrunedQuadraticStateSpaceProblem(A_0, A_1, A_2, B, u0, tspan[, p]; kwargs...)

Define a pruned second-order state-space model. Unlike QuadraticStateSpaceProblem, the quadratic terms operate on a separate linear-part state $u_f$ rather than the full state:

\[u_f^{n+1} = A_1 \, u_f^n + B \, w_{n+1}\]

\[u_{n+1} = A_0 + A_1 \, u_n + (u_f^n)^\top A_2 \, u_f^n + B \, w_{n+1}\]

The observation equation similarly uses $u_f$: $z_n = C_0 + C_1 \, u_n + (u_f^n)^\top C_2 \, u_f^n + v_n$.

This pruning approach prevents explosive dynamics in higher-order perturbation solutions.

Arguments

• A_0: Constant drift vector.
• A_1: Linear transition matrix used by both the full and linear-part states.
• A_2: Quadratic transition tensor applied to the linear-part state.
• B: Noise input matrix, or nothing.
• u0: Initial full state and initial linear-part state.
• tspan: Integer-step time span.
• p: Parameters passed through the SciML problem interface (default: NullParameters()).

Keyword Arguments

• C_0: Constant observation term, or nothing.
• C_1: Linear observation matrix, or nothing.
• C_2: Quadratic observation tensor, or nothing.
• observables_noise: Observation covariance matrix, or nothing.
• observables: Observed data used for likelihood calculations, or nothing.
• noise: Fixed process-noise sequence, or nothing for generated noise.
• syms: State variable names for symbolic indexing, or nothing.
• obs_syms: Observation variable names for symbolic indexing, or nothing.
• kwargs...: Additional constructor keywords retained in the problem.

References

• Andreasen, Fernandez-Villaverde, and Rubio-Ramirez (2017), "The Pruned State-Space System for Non-Linear DSGE Models: Theory and Empirical Applications."

See also: QuadraticStateSpaceProblem.

Fields

• A_0, A_1, A_2: Constant, linear, and quadratic transition coefficients.
• f: Internal SciMLBase.ODEFunction bridge used for SciML interfaces and symbolic indexing.
• B: Noise input matrix or nothing.
• C_0, C_1, C_2: Optional observation coefficients.
• u0: Initial state and the initial value of the linear component u_f.
• tspan: Integer-step time span.
• p: User parameters.
• observables_noise, observables, noise: Observation and simulation data.
• syms, obs_syms: Optional state and observation names for symbolic indexing.
• kwargs: Additional constructor keyword arguments retained for remaking.

Returns

• PrunedQuadraticStateSpaceProblem: A pruned quadratic state-space problem.

Throws

• ArgumentError: If tspan does not have an integer distance.

Examples

julia> using DifferenceEquations

julia> prob = PrunedQuadraticStateSpaceProblem([0.0], [1.0;;], zeros(1, 1, 1), nothing, [1.0], (0, 2));

julia> length(solve(prob).u)
3

StateSpaceProblem(transition, observation, u0, tspan[, p]; n_shocks, kwargs...)

Define a generic state-space model with user-provided callback functions:

\[u_{n+1} = f(u_n, w_{n+1}, p, t_n), \quad z_n = g(u_n, p, t_n)\]

Arguments

• transition: Callback f!!(x_next, x, w, p, t) -> x_next. For mutable arrays, mutate x_next in place and return it; for immutable arrays (e.g., SVector), return a new value.
• observation: Callback g!!(y, x, p, t) -> y, or nothing for no observations.
• u0: Initial state vector, or a Distribution for random initial conditions.
• tspan: Time span as (t0, t_end) with integer distance.
• p: Parameters passed to the callbacks (default: NullParameters()).

Keyword Arguments

• n_shocks::Int: Number of noise dimensions (required).
• n_obs::Int: Number of observation dimensions (default: 0).
• observables_noise: Observation noise covariance matrix (AbstractMatrix, e.g. Diagonal(d) or Symmetric(H * H')).
• observables: Observed data as Vector{Vector{T}}.
• noise: Fixed noise sequence as Vector{Vector{T}}.
• syms: State variable names for symbolic indexing.
• obs_syms: Observation variable names for symbolic indexing.

See also: LinearStateSpaceProblem, DirectIteration.

Fields

• transition: In-place or out-of-place transition callback.
• observation: In-place or out-of-place observation callback, or nothing.
• u0: Initial state or initial-state distribution.
• tspan: Integer-step time span.
• p: Parameters passed to both callbacks.
• n_shocks, n_obs: Noise and observation dimensions.
• observables_noise, observables, noise: Observation and simulation data.
• syms, obs_syms: Optional state and observation names for symbolic indexing.
• f: Internal SciMLBase.ODEFunction bridge used for SciML interfaces and symbolic indexing.
• kwargs: Additional constructor keyword arguments retained for remaking.

Returns

• StateSpaceProblem: A SciML-compatible callback-based state-space problem.

Throws

• ArgumentError: If tspan does not have an integer distance.

Examples

julia> using DifferenceEquations

julia> transition = (x_next, x, w, p, t) -> copyto!(x_next, x);

julia> prob = StateSpaceProblem(transition, nothing, [1.0], (0, 2); n_shocks = 0);

julia> solve(prob).u[end]
1-element Vector{Float64}:
 1.0