AbstractEstimationModel{M}

Abstract supertype for all parameter-estimation model wrappers in Clapeyron.jl.

An AbstractEstimationModel{M} wraps a concrete equation-of-state (EoS) model of type M together with the metadata needed to map a flat parameter vector Θ onto that model's fields and back.

Required interface

Every concrete subtype must implement:

• set_eos_parameters!(estimation_model, Θ): write the flat parameter vector Θ into the wrapped EoS model in-place.
• get_eos_parameters(estimation_model): extract a flat parameter vector Θ from the wrapped EoS model.
• set_model(estimation_model, new_model): return a new instance of the estimation model that wraps new_model instead of the current one.
• get_model(estimation_model): return the EoS model currently stored inside the estimation wrapper.

set_model and get_model have default implementations that assume that the model is stored in a model field.

Optional interface

• parameter_length(estimation_model): return the amount of parameters that are being manipulated.

• lower_bounds(estimation_model): return a flat vector of lower bounds for Θ, with -Inf for unconstrained parameters.

• upper_bounds(estimation_model): return a flat vector of upper bounds for Θ, with +Inf for unconstrained parameters.

• initial_guess(estimation_model): return a flat vector of starting values for the optimiser, they may be different that the current stored parameters in the EoS model.

Indexing and broadcasting

The abstract type provides fallback implementations of Base.getindex, Base.setindex!, and Base.copyto! so that an AbstractEstimationModel can be used like a vector of parameter values. Indexing by Symbol or Vector{Symbol} is supported when symbol_indices is defined.

Concrete subtypes

Clapeyron.EstimationModel is the standard concrete subtype.

Θ = get_eos_parameters(estimation_model::AbstractEstimationModel{M})
Θ = get_eos_parameters(eos_model::M, estimation_model::AbstractEstimationModel{M})

Extract a flat Vector of parameter values Θ from the EoS model stored in estimation_model.

The one-argument form operates on estimation_model's own internal model. The two-argument form first calls set_model to substitute eos_model and then extracts parameters using the same index/factor metadata, allowing inspection of a foreign EoS instance without modifying it permanently.

set_eos_parameters!(estimation_model::AbstractEstimationModel{M}, Θ)
set_eos_parameters!(eos_model::M, estimation_model::AbstractEstimationModel{M}, Θ)

Write the flat parameter vector Θ into the EoS model stored in estimation_model, updating it in-place.

The two-argument form operates on estimation_model's own internal model. The three-argument form first calls set_model to swap in eos_model and then delegates to the two-argument form, allowing a foreign EoS instance to be updated using the same index/factor metadata.

get_model(estimation_model::AbstractEstimationModel{M}) -> M

Return the EoS model currently wrapped by estimation_model.

The default implementation just accesses the model field.

set_model(estimation_model::AbstractEstimationModel{M}, new_model::M) -> AbstractEstimationModel{M}

Return a new estimation model that is identical to estimation_model except that its wrapped EoS model is replaced by new_model.

This is used internally to perform parameter extraction or injection on a different EoS instance while reusing the same index/factor metadata.

The function defaults to setting the model field to the new model.

parameter_length(estimation_model::AbstractEstimationModel{M})::Int

returns the length of the parameter vector Θ. Defaults to the length of get_eos_parameters(estimation_model)

symbol_indices(estimation_model::AbstractEstimationModel{M}, syms::Symbol) -> AbstractVector{Int}

Return the integer indices into the flat parameter vector Θ that correspond to the parameter names in syms (a Symbol or AbstractVector{Symbol}).

Implementing this function is optional; it enables named indexing via estimation_model[:param_name].

lower_bounds(model) -> Vector{Float64}

Return a flat vector of lower bounds for the parameter vector Θ used in the estimation procedure.

Elements are -Inf for parameters with no lower bound. Used to configure box-constrained optimisers.

upper_bounds(model)

Return a flat vector of upper bounds for the parameter vector Θ used in the estimation procedure.

Elements are +Inf for parameters with no upper bound. Used to configure box-constrained optimisers.

initial_guess(model)

Return a flat vector of initial parameter values for the optimiser. The default implementation just returns get_eos_parameters(model).

AbstractEstimationLoss

Abstract supertype for all loss/data containers used in parameter estimation.

A concrete subtype must implement at least objective_function

Clapeyron.EstimationData is the standard concrete subtype.

objective_function(loss::AbstractEstimationLoss, model) -> Number

Evaluate the scalar objective (loss) for model given the experimental data stored in loss.

EstimationData{𝔽, L, N, M} <: EstimationUtils.AbstractEstimationLoss

Data structure for parameter estimation.

Fields:

• method: function that computes model predictions
• loss: loss function comparing prediction and data
• inputs_name: names of input variables
• outputs_name: names of output variables (from columns prefixed out_)
• inputs: vector of input tuples (each of length N)
• outputs: vector of output tuples (each of length M)
• inputs_ismissingvalues: vector of tuples of length N indicating if the corresponding input at the same index is a missing value.
• outputs_ismissingvalues:vector of tuples of length M indicating if the corresponding output at the same index is a missing value.
• inputs_error: vector of error tuples for inputs (NaN where no error)
• outputs_error: vector of error tuples for outputs (NaN where no error)
• inputs_errortype: error type per input variable (one of ERRORTYPES or :none)
• outputs_errortype: error type per output variable
• output_weights: tuple of weights at each evaluation of the method function: sum(w[j]*loss(method[i][j],output[i][j]) for j in 1:M). By default is 1.0
• data_weights: vector of weights applied to each data point. by default is 1.0
• normalize: if set to true, the result of the objective function will be divided by the amount of valid (non-missing) data points.

EstimationProblem(est_model::AbstractEstimationModel,data;concrete = false)

Core structure used for parameter optimization. It joins estimation models and estimation data to perform parameter optimization. It can be created from a EstimationUtils.AbstractEstimationModel and a list of EstimationUtils.AbstractEstimationLoss. If concrete is set to true, then the list of data will be converted into a tuple before storing it. If concrete is set to false, then the list of data will be stored as an abstract vector, allowing adding data with different losses and methods afer the problem is constructed.

est,obj,x0,lb,ub = Estimation(model::EoSModel,toestimate::Dict,filepaths;ignorefield = Vector{String},objective_form = mse(pred,exp) = ((pred-exp)/exp)^2)
est,obj,x0,lb,ub = Estimation(est_model::EstimationModel,to_estimate::Union{Vector{EstimationData},NTuple{N,EstimationData}) where N
est,obj,x0,lb,ub = Estimation(est_model::EstimationModel,to_estimate::EstimationData)

Input parameters:

• model: The initial model containing the species we wish to parameterise
• toestimate: The dictionary of parameters being fitted, or already instantiated EstimationData objects.
• filepaths or filepaths_weights: The location of the data files used to fit. Can also contain the weights of each dataset
• ignorefield: Specify which EoSModel fields to ignore in the main model
• objective_form: Specify the functional form of the objective function in the form objective_form(pred,exp)

Output:

• est: an EstimationProblem object which contains the following fields:
  • model: The model whose parameters will be varied
  • initial_model: The initial model before parameterisation
  • toestimate: EstimateModel struct, which contains information on how to transform between an specified model and a vector of parameters
  • data: a collection of EstimationData objects. each one contributing to the objective function obj
• obj: The objective function which is used to fit the parameters. It can be also be created via Clapeyron.EstimationUtils.objective_function(est)
• x0: Initial guesses for the parameters. They can also be accessed via Clapeyron.EstimationUtils.initial_guess(est)
• ub: Upper bounds for the parameters. They can also be accessed via Clapeyron.EstimationUtils.upper_bounds(est)
• lb: Lower bounds for the parameters. They can also be accessed via Clapeyron.EstimationUtils.upper_bounds(est)

Description

Produces the estimator and other useful objects used within parameter estimation