Emulators

struct Emulator{FT<:AbstractFloat, VV<:(AbstractVector)}

Structure used to represent a general emulator, independently of the algorithm used.

Fields

• machine_learning_tool::CalibrateEmulateSample.Emulators.MachineLearningTool: Machine learning tool, defined as a struct of type MachineLearningTool.

• io_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT} where FT<:AbstractFloat: original training data

• encoded_io_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT} where FT<:AbstractFloat: encoded training data

• encoder_schedule::AbstractVector: Store of the pipeline to encode (/decode) the data

optimize_hyperparameters!(
    emulator::CalibrateEmulateSample.Emulators.Emulator{FT<:AbstractFloat},
    args...;
    kwargs...
) -> Any

Optimizes the hyperparameters in the machine learning tool. Note that some machine learning packages train hyperparameters on construction so this call is not necessary

Emulator(
    machine_learning_tool::CalibrateEmulateSample.Emulators.MachineLearningTool,
    input_output_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT<:AbstractFloat};
    encoder_schedule,
    encoder_kwargs,
    obs_noise_cov,
    mlt_kwargs...
) -> CalibrateEmulateSample.Emulators.Emulator{FT, Vector{Any}} where FT<:AbstractFloat

Construct an Emulator from a machine-learning tool and paired training data, fitting the encoder schedule and building the underlying model in encoded space.

Arguments

• machine_learning_tool: the MachineLearningTool to train (e.g. GaussianProcess, ScalarRandomFeatureInterface).
• input_output_pairs: training data as a PairedDataContainer.
• encoder_schedule (keyword, default nothing): encoding/decoding pipeline passed to create_encoder_schedule. nothing builds a default schedule using decorrelate_sample_cov for both input and output, or (decorrelate_sample_cov(), decorrelate_structure_mat()) when :obs_noise_cov is present in encoder_kwargs. Pass [] to disable encoding.
• encoder_kwargs (keyword, default NamedTuple()): forwarded to initialize_and_encode_with_schedule!.
• Additional keywords are forwarded to the machine-learning tool initialiser.

predict(
    gp::CalibrateEmulateSample.Emulators.GaussianProcess{CalibrateEmulateSample.Emulators.GPJL},
    new_inputs::AbstractArray{FT<:AbstractFloat, 2};
    add_obs_noise_cov,
    mlt_kwargs...
) -> Tuple{Any, Any}

Predict means and covariances in decorrelated output space using Gaussian process models. The use of stored FType and YType to control this method is deprecated, the return covariance is now determined by the predict( kwarg add_obs_noise_cov

predict(
    srfi::CalibrateEmulateSample.Emulators.ScalarRandomFeatureInterface,
    new_inputs::AbstractMatrix;
    multithread,
    add_obs_noise_cov,
    mlt_kwargs...
) -> Tuple{Any, Any}

Prediction of emulator mean at new inputs (passed in as columns in a matrix), and a prediction of the total covariance at new inputs equal to (emulator covariance + noise covariance).

predict(
    vrfi::CalibrateEmulateSample.Emulators.VectorRandomFeatureInterface,
    new_inputs::AbstractMatrix;
    add_obs_noise_cov,
    mlt_kwargs...
) -> Tuple{Any, Any}

Prediction of data observation (not latent function) at new inputs (passed in as columns in a matrix). That is, we add the observational noise into predictions.

predict(
    emulator::CalibrateEmulateSample.Emulators.Emulator{FT<:AbstractFloat},
    new_inputs::AbstractMatrix;
    encode,
    add_obs_noise_cov,
    transform_to_real,
    mlt_kwargs...
) -> Tuple{Any, Any}

Return emulator predictions (mean and covariance) at new_inputs, where each input is a column of the matrix.

Arguments

• emulator: trained Emulator to query.
• new_inputs: [input_dim × N] matrix of query points.
• encode (keyword, default nothing): controls which encoding stages are applied. Let Eᵢ/Eₒ be input/output encoders and G the model in encoded space:
  • nothing → Dₒ∘G∘Eᵢ(x) — standard user-facing call.
  • "in" → Dₒ∘G(z) — inputs already encoded as z = Eᵢx.
  • "out" → G∘Eᵢ(x) — outputs returned in encoded space.
  • "in_and_out" → G(z) — inputs encoded, outputs in encoded space (used internally by sample).
• add_obs_noise_cov (keyword, default false): when true, adds the stored observational noise covariance to the returned uncertainty (used internally by sample).
• Additional keywords are forwarded to the machine-learning tool predict method.

Returns (mean, cov) where for N inputs:

• 1-D output: mean is [1 × N], cov is [1 × N] variances.
• p-D output: mean is [p × N], cov is a length-N iterator of [p × p] covariance matrices.

predict(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper,
    new_inputs::AbstractMatrix;
    encode,
    add_obs_noise_cov,
    transform_to_real
) -> Tuple{Any, Any}

Return predictions (mean and covariance) from the ForwardMapWrapper at new_inputs, where each input is a column. The forward map runs in the physical (decoded) space and is encoded/decoded as requested.

Arguments

• fmw: ForwardMapWrapper to query.
• new_inputs: [input_dim × N] matrix of query points.
• encode (keyword, default nothing): controls encoding stages applied to inputs/outputs. Let Di/Eo be input decoder/output encoder and G the forward map in decoded space:
  • nothing → G(x) — standard user-facing call.
  • "in" → G∘Di(z) — inputs are encoded as z = Ei(x).
  • "out" → Eo∘G(x) — outputs returned in encoded space.
  • "in_and_out" → Eo∘G∘Di(z) — used internally by sample.
• add_obs_noise_cov (keyword, default false): when true, adds observational noise covariance to the returned uncertainty (used internally by sample).

Returns (mean, cov) with the same shape conventions as predict.

encode_data(
    encoder_schedule::AbstractVector,
    data::Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix, AbstractVector},
    in_or_out::AbstractString
) -> Any

Encode the new data (a DataContainer, or matrix where data are columns, or vector viewed as one column) representing inputs ("in") or outputs ("out"), with the stored and initialized encoder schedule. Always internally calls CES.Utilities.encode_with_schedule

decode_data(
    encoder_schedule::AbstractVector,
    data::Union{EnsembleKalmanProcesses.DataContainers.DataContainer, AbstractMatrix, AbstractVector},
    in_or_out::AbstractString
) -> Any

Decode the new data (a DataContainer, or matrix where data are columns, or vector viewed as one column) representing inputs ("in") or outputs ("out"), with the stored and initialized encoder schedule. Always internally calls CES.Utilities.decode_with_schedule

encode_structure_matrix(
    encoder_schedule::AbstractVector,
    structure_mat,
    in_or_out::AbstractString
) -> Any

Encode a new structure matrix in the input space ("in") or output space ("out"). with the stored and initialized encoder schedule. Always internally calls CES.Utilities.encode_with_schedule. If the structure matrix is a LinearMap, then the encoded structure matrix remains a LinearMap

decode_structure_matrix(
    encoder_schedule::AbstractVector,
    structure_mat,
    in_or_out::AbstractString
) -> Any

Decode a new structure matrix in the input space ("in") or output space ("out"). with the stored and initialized encoder schedule. Always internally calls CES.Utilities.decode_with_schedule. If the structure matrix is a LinearMap, then the decoded structure matrix remains a LinearMap

Wrapper that stores an explicit forward map f in place of a trained Emulator. When predict is called this object evaluates E_out ∘ f ∘ c(x), where c is the constraint transformation from the prior and E_out is the output encoder.

struct ForwardMapWrapper{FT<:Real, VV<:(AbstractVector), PD<:EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution, NI<:CalibrateEmulateSample.Utilities.NoiseInjector}

Fields

• forward_map::Function: function that represents the forward map

• prior::EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution: a parameter distribution, containing transformations to constrain the forward map inputs

• io_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer: data used to construct encoder-decoder

• encoded_io_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer: encoded data

• encoder_schedule::AbstractVector: Store of the pipeline to encode (/decode) the data

• noise_injector::CalibrateEmulateSample.Utilities.NoiseInjector: For lossy encodings, this determines how to inject noise into the null-space upon decoding

Constructors

Prefer the forward_map_wrapper factory function for construction — it builds and initialises the encoder schedule automatically from training data.

ForwardMapWrapper(
    forward_map,
    prior,
    io_pairs,
    encoded_io_pairs,
    encoder_schedule,
    noise_injector
)

defined at /home/runner/work/CalibrateEmulateSample.jl/CalibrateEmulateSample.jl/src/Emulator.jl:136.

forward_map_wrapper(
    forward_map::Function,
    prior::EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution,
    input_output_pairs::EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT<:Real};
    encoder_schedule,
    encoder_kwargs,
    noise_injector_threshold,
    noise_injector_scaling
) -> CalibrateEmulateSample.Emulators.ForwardMapWrapper{FT, Vector{Any}, EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution{PDType, CType, ST}} where {FT<:Real, PDType<:EnsembleKalmanProcesses.ParameterDistributions.ParameterDistributionType, CType<:EnsembleKalmanProcesses.ParameterDistributions.ConstraintType, ST<:AbstractString}

Construct a ForwardMapWrapper from an explicit forward map, a prior, and paired training data. Behaves similarly to the Emulator constructor but additionally requires prior so that inputs can be constrained and null-space noise can be injected when the encoder is lossy.

Arguments

• forward_map: function F(x) mapping physical (constrained) parameters to model outputs.
• prior: ParameterDistribution describing the prior on physical parameters.
• input_output_pairs: training data as a PairedDataContainer.
• encoder_schedule (keyword, default nothing): encoding pipeline; see Emulator constructor for details.
• encoder_kwargs (keyword, default NamedTuple()): forwarded to initialize_and_encode_with_schedule!.
• noise_injector_threshold (keyword, default 0.001): if the variance lost by the encoder exceeds this threshold, noise consistent with the prior is injected into the null-space when decoding encoded MCMC samples.
• noise_injector_scaling (keyword, default 1.0): multiplicative scale applied to injected noise; values below 1.0 can improve robustness for non-Gaussian problems.

get_machine_learning_tool(
    emulator::CalibrateEmulateSample.Emulators.Emulator
) -> CalibrateEmulateSample.Emulators.MachineLearningTool

Return the MachineLearningTool (e.g. GaussianProcess, ScalarRandomFeatureInterface) stored in emulator.

get_io_pairs(
    emulator::CalibrateEmulateSample.Emulators.Emulator
) -> EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT} where FT<:AbstractFloat

Return the original (unencoded) training PairedDataContainer stored in emulator.

get_io_pairs(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper
) -> EnsembleKalmanProcesses.DataContainers.PairedDataContainer

Return the original (unencoded) training PairedDataContainer stored in fmw.

get_encoded_io_pairs(
    emulator::CalibrateEmulateSample.Emulators.Emulator
) -> EnsembleKalmanProcesses.DataContainers.PairedDataContainer{FT} where FT<:AbstractFloat

Return the encoded training PairedDataContainer stored in emulator.

get_encoded_io_pairs(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper
) -> EnsembleKalmanProcesses.DataContainers.PairedDataContainer

Return the encoded training PairedDataContainer stored in fmw.

get_encoder_schedule(
    mcmc::CalibrateEmulateSample.MarkovChainMonteCarlo.MCMCWrapper
) -> AbstractVector

gets the stored encoder_schedule from an MCMCWrapper

get_encoder_schedule(
    emulator::CalibrateEmulateSample.Emulators.Emulator
) -> AbstractVector

Return the initialised encoder schedule stored in emulator.

get_encoder_schedule(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper
) -> AbstractVector

Return the initialised encoder schedule stored in fmw.

get_forward_map(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper
) -> Function

Return the forward-map function stored in fmw.

get_prior(
    fmw::CalibrateEmulateSample.Emulators.ForwardMapWrapper
) -> EnsembleKalmanProcesses.ParameterDistributions.ParameterDistribution

Return the ParameterDistribution prior stored in fmw.