Unscented Kalman Inversion

Unscented{FT<:AbstractFloat, IT<:Int} <: Process

An unscented Kalman Inversion process.

Fields

• u_mean::Any: an interable of arrays of size N_parameters containing the mean of the parameters (in each uki iteration a new array of mean is added), note - this is not the same as the ensemble mean of the sigma ensemble as it is taken prior to prediction

• uu_cov::Any: an iterable of arrays of size (N_parameters x N_parameters) containing the covariance of the parameters (in each uki iteration a new array of cov is added), note - this is not the same as the ensemble cov of the sigma ensemble as it is taken prior to prediction

• obs_pred::Any: an iterable of arrays of size N_y containing the predicted observation (in each uki iteration a new array of predicted observation is added)

• c_weights::AbstractVecOrMat{FT} where FT<:AbstractFloat: weights in UKI

• mean_weights::AbstractVector{FT} where FT<:AbstractFloat

• cov_weights::AbstractVector{FT} where FT<:AbstractFloat

• N_ens::Int64: number of particles 2N+1 or N+2

• Σ_ω::AbstractMatrix{FT} where FT<:AbstractFloat: covariance of the artificial evolution error

• Σ_ν_scale::AbstractFloat: covariance of the artificial observation error

• α_reg::AbstractFloat: regularization parameter

• r::AbstractVector{FT} where FT<:AbstractFloat: regularization vector

• update_freq::Int64: update frequency

• impose_prior::Bool: using augmented system (Tikhonov regularization with Kalman inversion in Chada et al 2020 and Huang et al (2022)) to regularize the inverse problem, which also imposes prior for posterior estimation.

• prior_mean::Any: prior mean - defaults to initial mean

• prior_cov::Any: prior covariance - defaults to initial covariance

• iter::Int64: current iteration number

Constructors

Unscented(
    u0_mean::AbstractVector{FT},
    uu0_cov::AbstractMatrix{FT};
    α_reg::FT = 1.0,
    update_freq::IT = 0,
    modified_unscented_transform::Bool = true,
    impose_prior::Bool = false,
    prior_mean::Any,
    prior_cov::Any,
    sigma_points::String = symmetric
) where {FT <: AbstractFloat, IT <: Int}

Construct an Unscented Inversion Process.

Inputs:

• u0_mean: Mean at initialization.
• uu0_cov: Covariance at initialization.
• α_reg: Hyperparameter controlling regularization toward the prior mean (0 < α_reg ≤ 1),

default should be 1, without regulariazion.

• update_freq: Set to 0 when the inverse problem is not identifiable,

namely the inverse problem has multiple solutions, the covariance matrix will represent only the sensitivity of the parameters, instead of posterior covariance information; set to 1 (or anything > 0) when the inverse problem is identifiable, and the covariance matrix will converge to a good approximation of the posterior covariance with an uninformative prior.

• modified_unscented_transform: Modification of the UKI quadrature given in Huang et al (2021).
• impose_prior: using augmented system (Tikhonov regularization with Kalman inversion in Chada et al 2020 and Huang et al (2022)) to regularize the inverse problem, which also imposes prior for posterior estimation. If impose_prior == true, prior mean and prior cov must be provided. This is recommended to use, especially when the number of observations is smaller than the number of parameters (ill-posed inverse problems). When this is used, other regularizations are turned off automatically.
• prior_mean: Prior mean used for regularization.
• prior_cov: Prior cov used for regularization.
• sigma_points: String of sigma point type, it can be symmetric with 2N_par+1 ensemble members or simplex with N_par+2 ensemble members.

Unscented(
    u_mean,
    uu_cov,
    obs_pred,
    c_weights,
    mean_weights,
    cov_weights,
    N_ens,
    Σ_ω,
    Σ_ν_scale,
    α_reg,
    r,
    update_freq,
    impose_prior,
    prior_mean,
    prior_cov,
    iter
)

defined at /home/runner/work/EnsembleKalmanProcesses.jl/EnsembleKalmanProcesses.jl/src/UnscentedKalmanInversion.jl:57.

Unscented(
    u0_mean,
    uu0_cov;
    α_reg,
    update_freq,
    modified_unscented_transform,
    impose_prior,
    prior_mean,
    prior_cov,
    sigma_points
)

defined at /home/runner/work/EnsembleKalmanProcesses.jl/EnsembleKalmanProcesses.jl/src/UnscentedKalmanInversion.jl:91.

Unscented(prior; kwargs...)

defined at /home/runner/work/EnsembleKalmanProcesses.jl/EnsembleKalmanProcesses.jl/src/UnscentedKalmanInversion.jl:210.

construct_sigma_ensemble(
    process::Unscented,
    x_mean::Array{FT},
    x_cov::AbstractMatrix{FT},
) where {FT <: AbstractFloat, IT <: Int}

Construct the sigma ensemble based on the mean x_mean and covariance x_cov.

construct_mean(
    uki::EnsembleKalmanProcess{FT, IT, Unscented},
    x::AbstractVecOrMat{FT};
    mean_weights = uki.process.mean_weights,
) where {FT <: AbstractFloat, IT <: Int}

constructs mean x_mean from an ensemble x.

construct_cov(
    uki::EnsembleKalmanProcess{FT, IT, Unscented},
    x::AbstractVecOrMat{FT},
    x_mean::Union{FT, AbstractVector{FT}, Nothing} = nothing;
    cov_weights = uki.process.cov_weights,
) where {FT <: AbstractFloat, IT <: Int}

Constructs covariance xx_cov from ensemble x and mean x_mean.

construct_cov(
    uki::EnsembleKalmanProcess{FT, IT, Unscented},
    x::AbstractMatrix{FT},
    x_mean::AbstractVector{FT},
    obs_mean::AbstractMatrix{FT},
    y_mean::AbstractVector{FT};
    cov_weights = uki.process.cov_weights,
) where {FT <: AbstractFloat, IT <: Int, P <: Process}

Constructs covariance xy_cov from ensemble x and mean x_mean, ensemble obs_mean and mean y_mean.

update_ensemble_prediction!(process::Unscented, Δt::FT) where {FT <: AbstractFloat}

UKI prediction step : generate sigma points.

update_ensemble_analysis!(
    uki::EnsembleKalmanProcess{FT<:Real, IT<:Int64, TU<:TransformUnscented},
    u_p_full::AbstractMatrix,
    g_full::AbstractMatrix,
    u_idx::Vector{Int64},
    g_idx::Vector{Int64}
)

UKI analysis step : g is the predicted observations Ny x N_ens matrix

update_ensemble_analysis!(
    uki::EnsembleKalmanProcess{FT, IT, Unscented},
    u_p::AbstractMatrix{FT},
    g::AbstractMatrix{FT},
) where {FT <: AbstractFloat, IT <: Int}

UKI analysis step : g is the predicted observations Ny x N_ens matrix

construct_initial_ensemble(
    prior::EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution,
    process::Union{TransformUnscented, Unscented};
    constrained
) -> Any

Constructs the initial ensemble for the Unscented or TransformUnscented process. Returned with parameters as columns in unconstrained space by default (constrain by settingconstrained=true`)

NOTE: This function is created just to see what the initial sigma_ensemble will be without constructing the EKP object. Do not pass the initial ensemble into the EnsembleKalmanProcess object.