Documentation
/ User's manual in Python
: 
| XI.3. Minimisation techniques | ||
|---|---|---|
 | Chapter XI. The Calibration module |  |
Warning
This method is entirely reliant on the Relauncher architecture so the only available
constructor is the runner constructor (discussed in the section Section XI.2.3.1).
This means there is no constructor based on TCode or function (respectively described in Section XI.2.3.2 and Section XI.2.3.3).
This is because the method uses the Nlopt-algorithm library, introduced in Chapter IX or the Vizir package for multi-criteria and
many-objective algorithms.
Even though the theory behind this method is not revolutionary, these methods are of interest and are, historically and
conceptually, among the simplest methods one can use. Because of the way the framework is organised, it can be used
with all Relauncher assessors and can call any algorithm from NLopt
or Vizir.
Apart from what is presented in Section XI.3.2, the TMinimisation class
does not provide any additional options or methods beyond those available in the default TCalibration
object (see Section XI.2).
The usage of the TMinimisation class can be summarised in a few key steps:
Prepare the data and the model:
Specify the experimental dataserver, the parameters to calibrate, and the model;
Construct the
TMinimisationobject with the appropriate distance function (see Section XI.3.1).
Set the algorithm properties:
Define optimisation algorithm and prepare its properties (see Section XI.3.2).
Perform the estimate and analyse the results:
Run the estimate process;
Extract the results and visualise them with the standard plotting tools (see Section XI.3.3).
As stated above, the only available constructor is the one whose prototype includes an instance of a TRun-inheriting object. This approach provides a simple way to change the evaluator (e.g., from a C++ function to a Python function or an external code) and to use either a sequential approach (for a code) or a threaded one (to distribute locally the estimates).
In this case, the constructor should look like this:
# Constructor with a runner
TMinimisation(tds, runner, ns=1, option="")
This method takes up to four arguments, two of which are optional:
tds: a
TDataServerobject containing one attribute for each parameter to be calibrated. This is theTDataServerobject calledtdsPar, defined in Section XI.2.1.runner: a
TRun-inheriting instance that contains all the model information and whose type determines how the estimates are distributed: it can either be aTSequentialRuninstance orTThreadedRunfor distributed computations.ns (optional): the number of samples to be produced. This parameter is not used in this context.
option (optional): the options that can be applied to the method. Options common to all calibration classes (those defined in the
TCalibrationclass) are discussed in Section XI.2.3.4.
A crucial step in this constructor is the creation of the instance that inherits from TRun.
As mentioned earlier, its type determines how the estimates are distributed. To construct such an object, one needs
to provide an evaluator (the available evaluators are described in detail in Section VIII.3).
The final step is to construct the TDistanceLikelihoodFunction, a mandatory step that must
always follow the constructor, using the setDistance method (following the prototype presented
in Section XI.2.2.1). Advanced users also have the option to define a custom distance
by following the prototype:
setDistance(distFunc, tdsRef, input, reference, weight="")
Once the TMinimisation instance is created along with its associated
TDistanceLikelihoodFunction, the optimisation properties must be defined to specify which
algorithm will be used. This is done by calling the setOptimProperties, whose prototype is:
# Prototype for NLopt or Vizir
setOptimProperties(solv, option="")
The option field is reserved for future use and is currently non-functional. It is advisable to prepare the solver
before integrating it into the TCalibration object, as modifying it afterwards may be
difficult (as shown in the example below). For example, it may be preferable to set the population size, number of
iterations, and number of steps using the setSize method on the TVizirGenetic
object before to provide it to the TMinimisation (via setOptimProperties),
which will then automatically create the appropriate optimisation master based on the solver type:
- TNlopt
the optimisation master used for any
TNloptSolverinstance. An example can be found in Section XIV.12.1;- TVizir2
the optimisation master used for any
TVizirSolverShareinstance. Even though the optimisation will remain mono-criterion, this might be useful for certain complex problems, as discussed in Section XIV.12.2.
It is also possible to access the optimisation master by calling the getOptimMaster method.
This method returns a pointer to the newly created TOptimShare instance. This might be useful
to set some properties (for instance the tolerance).
# Set the calibration object
cal = Calibration.TMinimisation(tdsPar,runner,1)
cal.setDistance("relativeLS",tdsRef,"rw:l","Qexp")
# Set Vizir optimisation properties
solv = Reoptimizer.TVizirGenetic()
solv.setSize(24,15000,100)
cal.setOptimProperties(solv)
optimMaster = cal.getOptimMaster()
optimMaster.setTolerance(1e-6)
# Set Nlopt optimisation properties
solv = Reoptimizer.TNloptSubplexe()
cal.setOptimProperties(solv)
optimMaster = cal.getOptimMaster()
optimMaster.setTolerance(1e-6)
Finally, once the computation is complete (using the standard estimateParameters method), the
calibrated values of the parameters are directly stored in the parameter TDataServer.
It is also recommended to check the residuals (using the standard drawResiduals method,
introduced in Section XI.2.3.7), as they may provide useful information on the quality of the calibration.
No additional options or visualization methods are specific to the TMinimisation implementation;
these functions behave exactly as described in their respective sections.
Two examples are also provided in the use-case section (see Section XIV.12.1 and Section XIV.12.2).
| |  | |
| XI.2. Calibration classes, distance and likelihood functions, observations and model |  | XI.4. Analytical linear Bayesian estimation |