fitter

Abstraction for the calibration kernel.

This module contain the main class Fitter which is the code of Tunax for the calibration of the closure parts. The classes FittableParameter and FittableParametersSet are used to make a link between the optimization part and the closures structures. These class can be obtained by the prefix tunax.fitter. or directly by tunax..

class FittableParameter(do_fit, val=0.0)

Calibration configuration for one parameter.

An instance of this class must be created for every parameter of the closure that will be calibrated and for every not default values during calibration.

Parameters:

• do_fit (bool) – cf. attribute.

• val (float, default=0.) – cf. attribute.

do_fit

The parameter will be calibrated.

Type:

bool

val

If do_fit : the initial value for calibration (at the first step of the calibration) ; if do_fit is false : the constant value to take for this parameter if it’s not the default one in the closure.

Type:

float, default=0.

class FittableParametersSet(coef_fit_dict, closure_name)

Complete closure calibration parameters.

This class is the set of all the configurations on the closure parameters for the calibration. It makes the link between the array on which the optimizer works and the closure parameters class.

Parameters:

• coef_fit_dict (Dict[str, FittableParameter]) – cf. attribute.

• closure_name (str) – Name of the chosen closure, must be a key of CLOSURES_REGISTRY, see its documentation for the available closures.

Return type:

FittableParametersSet

coef_fit_dico

The set of all the configurations of all the parameters that will be calibrated and the one constants but not with the default value of the closure.

Type:

Dict[str, FittableParameter]

closure

The abstraction that represent the used closure.

Type:

Closure

property n_calib: int

Number of variables that are calibrated.

Returns:

nc – Number of variables that are calibrated.

Return type:

int

fit_to_closure(x)

Transforms an fitted array in a set of closure parameters.

This method copy the fixed non-default values of coef_fit_dict and copy the calibrated values from x. Which is simply the parameters values in the order that is indicated by coef_fit_dict.

Parameters:

x (Float[Array, 'nc']) – The array on which the optimize works to find the best values. It is the array of the parameters that are calibrated.

Returns:

clo_params – The instance of the closure parameters class (child class of ClosureParametersAbstract) with the modifications of the calibration step.

Return type:

ClosureParametersAbstract

gen_init_val()

Produce the fitted array for the first calibration step.

This method simply copy the initial values of the calibrated coefficients in an array x which will be used as the first calibration step for the optimizer.

Returns:

x – The initial vector for the optimizer at the first step of calibration.

Return type:

Float[Array, ‘nc’]

class Fitter(coef_fit_params, database, dt, loss, nloop=100, nit_loss=-1, learning_rate=0.001, verbatim=True, output_path='./')

Reprensentation of a complete calibration configuration.

A fitter is a link between the calibrated parameters configuration coef_fit_params, a database of observations to fit the model on, a loss function loss and some optimizer parameters. An instance can be call (with no parameters) to run the calibration. The __init__ method build a set of models corresponding to the given time-step dt , the given closure closure_name and the different initial states and physical cases extracted from the database.

Parameters:

• coef_fit_params (FittableParametersSet) – cf. attribute.

• database (Database) – cf. attribute.

• dt (float) – The time-step used for defininf the forward model that will be calibrated \([\text s]\).

• loss (Callable[[List[Trajectory], Database], float]) – cf. attribute.

• nloop (int, default=100) – cf. attribute.

• nit_loss (int, default = -1) – cf. attribute.

• learning_rate (float, default=0.001) – cf. attribute.

• verbatim (bool, default = True) – cf. attribute.

• output_path (Optional[str], default = '.') – cf. attribute.

Return type:

Fitter

coef_fit_params

Parametrization of the closure parameters that must be calibrated and the one which are fixed with non-default values.

Type:

FittableParametersSet

database

Database of observation used for calibration, the optimizer will make the model fit to them.

Type:

Database

model_list

List of model instances that represent the physical case and the initial condition for every observation in the database. At each calibration step, they will be call to compute the loss function.

Type:

List[SingleColumnModel]

loss

Abstraction that the user create to describe its own loss function which will be minimized by the fitter. The function should represent how much the model with its closure fits to the database

Parameters:

• trajectories (List[Trajectory]) – List of trajectories computed by the model and corresponding to each observation of the database case in the same order.

• database (Database) – cf.parameter

Returns:

loss – The quantity that will be minimized by the fitter. The user must compute a quantity that compares the trajectories done by the forward model (with the current values for the parameters of the closure at the current calibration step), and the trajectories from the database.

Return type:

float, positive

Type:

Callable[[List[Trajectory], Database], float]

nloop

Maximum number of calibration loops.

Type:

int

nit_loss

Number of iterations of every computation of the loss function in the output for diagnostic. Set to -1 to never compute it. Useless if output_path is None.

Type:

int, default = -1

learning_rate

Learning rate of the optimizer algorithm : how much it is fast at each step.

Type:

float, default=0.001

verbatim

Print in the terminal the evolution of the calibration.

Type:

bool, default = True

output_path

If None, don’t write the evolution on numpy files ; else must finishes by .npz : in this file the compressed numpy output will be written.

Type:

Optional[str], default = ‘.’

Note

• During the calibration the gradient of the loss function is computed at every iterations, but not the loss function itself. The set of nit_loss increase the cost of the iteration if the value of the cost funtion is computed too often.

• The output is written at every step so its readable by another python kernel during the calibration. To access to this data, one have to read the .npz file with the numpy.load() function (with allow_pickle set one True), and then access to the evolutions of the calibrated vector (the closures paramters that are calibrated) with ['x'], to their gradients with ['grads'] these are 2 dimensional arrays, the first dimension being the calibration iterations and the second one the parameters list. If nit_loss is not equal to -1, one can access to the evolution of the loss function with ['loss_it'] which records the indexes of the iterations where the loss function is computed and ['loss_values'] the corresponding values of the loss function.

loss_wrapped(x)

Wrapping of loss that takes only an array in argument.

This method runs every model for each observations with the set of closure parameters corresponding to x, then it computes and returns the the value of the loss function.

Parameters:

x (Float[Array, 'nc']) – An array that represent the values of the parameters of the closure that are in calibration.

Returns:

loss – Value of the loss function for the x values of the closure parameters.

Return type:

float, positive

__call__()

Execute the callibration.

First the optimizer is selected and parametrized with optax and the gradient function of the loss is computed. Then in the calibration loop, the gradient is evaluated on the currents values of the closure parameters, the eventual output are computed and the optax optimizer is updated. The optmizer used is optax.adam().

Returns:

closure_params – The instance of the closure parameters changed with the final value of the calibrated parameters.

Return type:

ClosureParametersAbstract