Documentation / Manuel utilisateur en C++ :

VIII.5. TMaster

VIII.5. `TMaster`
	Chapter VIII. The Relauncher module

VIII.5. `TMaster`

The object inheriting from the TMaster class has a supervisor role: it defines items to be evaluated, and treats these evaluations. Usually, it is created with a TDataServer, and a TRun (TEval implicitly) that is used for evaluations. The TMaster retrieves information both:

from TDataServer, it extracts the declaration of the input variables.
from TEval, it extracts extra parameters that will be computed for each item.

We could distinguish two cases depending of the TDataServer data:

if it contains a header and data, the TMaster will complete items data by adding information (columns). This happens most of the time when considering the pure launching aspect, meaning when using the TLauncher2 object, briefly defined below.
if it contains only a header, it will be used as items definition parameters. The TMaster will fill it with its own items (lines and columns). This case happens both for pure the launching aspect, given that a design-of-experiments will be constructed at some point, but also for optimisation issues.

Disregarding the case, TMaster interface defines an abstract method, solverLoop, that runs the evaluation loop and completes or fills the TDataServer data. This method is the one to properly start the analysis.

VIII.5.1. Dealing with attributes

Disregarding the kind of master considered (the TLauncher2, discussed briefly below or those introduced in the optimisation part, in Section IX.2 for instance), there are common methods that are discussed below in order to simplify or precise some important behaviour of your current analysis.

In simple problem, the TDataServer object and the ones deriving from TEval have input parameters that fit together. In this case, you can use the addAllInputs method from the TEval class to define the TDataServer needed header (the only argument being a pointer to the considered dataserver object). For more complex one, there might be a mismatch.

In other problem, one can distinguish between three kinds of situation:

The TEval-based object is using few input parameters, one (or more) of which is requested to be set a constant value for all the upcoming estimation. To do this properly, the parameter under consideration should be added to the assessor but not to the dataserver. The method addConstantValue from the chosen TMaster inheriting object is called with argument the pointer to the attribute and its value as second parameter. A third optionnal parameter (set by default at false) specifies whether this value should be stored in the dataserver tuple at the end. This option has been recently added as it might be better for bookkeeping to know what the underlying hypothesis was when the computations were performed. An example of how to use this is provided in Section XIV.8. This method has also been implemented to be able to cope with vectors and strings but this implies to handle complicated concept that are used internally, so we strongly recommand to contact us if you have no other choice.
The TEval-based object (or more oftently the composition of evaluators) is using many internal parameters (attribute that are created from one assessor and used by any other later on in the chain). If these parameters are uninteresting for the final purpose of the analysis, they can be removed, simply by calling the addTemporary method from the chosen TMaster inheriting object. The only argument is a pointer to the attribute under consideration. Once more, an example of how to use this is provided in Section XIV.8.
Finally, in some pure launching problem (Sobol for instance), some TDataServer-objects have extra parameters unused by the TEval. In this case, it means that the initial TDataServer is not empty and that the TMaster-object is able to keep this parameters values, and completes the data by adding columns.

VIII.5.2. TLauncher2

TLauncher2 is a new version of TLauncher and TLauncherFunction using the relauncher classes. It's a basic implementation, and it has no extra method. The constructor takes the TMaster usual arguments: a TDataServer and a TEval.

VIII.5.2.1. Dealing with failure

From time to time, there might be problem when running a code. The source of these problems might differ from one instance to another. In the Relauncher module one can consider different case:

the command is returning a failure code. A convention for a command is to return 0 if all went well which means that what should be done has been done while any other returned value can be considered as a way to inform that a problem has been met. From the Uranie point of view, there is no way to know what kind of error is meant as it is command dependent.
the system function is returning other values. The command provided by the user is passed to the system C++ function and on top of the non-zero returning value (discussed above), there are few specific cases. Among these, one can find the case where the command is not known (the user made a mistake in the TCodeEval definition) or the command is suffering from an internal problem preventing from even reaching the exit (a segmentation fault for instance). With most Linux platforms, the former returned code is 127 while the latter is 139. This interpretation is just given for illustration purpose but unfornutatly no generalisation can be done.
no output file is created. In this case, nothing can be done, all output variables will be missing and this might arise even if the code is not returning any specific failing code (see the discussion above).
One or more output variables are missing in the output file. This is special, as it can arise if the command has stopped during the writting process, but this also can be coming from an empty vector whose output formatting has not properly being taken care of. This is discussed in Section VIII.3.3.2 and illustrated in a use-case macro Section XIV.8.12 because of the way the output Key-format output file is written

All these problems will be considered as a failure from the command. As such, the input configuration will be discarded and not stored in the final dataserver object. The following paragraph discussed the way to get back all failed configurations.

Unlike in Section VIII.5.1 where all the methods are inherited from the TMaster class, the method setSaveError(TDataServer *tdserror) has been implemented in order to help handling the command failures discussed previously. Its only argument is a pointer to a dataserver object in which all failing configurations will be stored. Example of its usage is shown in two use-case macros with the classical flowrate case in Section VIII.3.3.2 and illustrated in a use-case macro Section XIV.8.9 and when an empty vector is interpreted as a missing information because of the wrong output file formatting, see Section XIV.8.12.


VIII.4. `TRun`		Chapter IX. The Reoptimizer module