Preliminary Analysis

Uptimai Preliminary Analysis allows obtaining very rapidly the sensitivity of the variance of results to input variables, with the maximal focus on reducing the number of required data samples. The sensitivity analysis shows the relevance of each parameter by itself, but the analysis also examines if interactions between multiple parameters are significant. That allows identifying negligible variables before a complete study of the problem is done, reducing the total cost of the model. The Preliminary Analysis method will call for outputs corresponding to specific combinations of input parameters, thus, it is intended to work in connection to engineering computational codes etc.

How to use the interface#

Figure 1 shows the initial screen of the Core Solver Setup GUI. The strip on the top of the window is common for all methods. From the left, at first, it informs the user about the setup file which is being processed. Then, there are three tabs of solver settings:

Input Files : Here the user selects the set of inputs to be used and sees the list of corresponding files
Cases/Outputs : The setup for the selected method and each solver run
General Setup : The user can define the names of model result files as well as computational resources reserved for the Uptimai Solver

The control panel on top then continues with the About button with the menu dedicated to accessing the link to this document (Help), contacting Uptimai company to get the support (Company), and showing the information about the currently installed version of the program (Version). The Close button ends the preparation of the current setup (also with the option to discard the data), and the Save setup button stores all changes in the *.json file. Also, there are ? icons on the solver setting tabs to show quick reference to the corresponding entry field or feature.

Input Files#

The left section of the screen contains the general information about the Selected input. There is its name together with the Method to be used in the Uptimai Solver (in this case the Preliminary Analysis) which was identified automatically from files of the selected input. Users can change the set of inputs (together with the method, eventually) from the list of Available items below.

When going through the list of available sets of inputs, the program shows their details in the right section of the GUI window. To choose a particular set of inputs as the currently selected one, double-clicking or confirmation with the Select this input button is required. When the reviewed input is the selected one, the aforementioned button is disabled and informs the user that This is the selected input.

Cases/Outputs#

Here the user defines solver options for all cases in the current setup. Cases are listed in the left section of the program window, as seen in Figure 2. It is possible as many cases as needed, the Uptimai Solver will process them in the order prescribed by the list. The position of each case in the list can be changed by ist mouse-dragging by its = symbol. Clicking the X icon of the item will remove the case from the list. Other cases can be added to the list via the + Add case below the list.

Cases in the list have generic names based on the project output which should be solved in the model. Clicking a list item highlights it in the list and the corresponding individual settings are shown in the right section of the window. The corresponding case number can be seen also on top of the right section of the GUI to ensure users with on which case they work. The top of the right section also contains the entry field where the Output to run is set. In other words, it is the column of the result matrix to be evaluated by the Uptimai solver.

Number of outputs

The Uptimai solver checks automatically the total number of outputs in the matrix of results by counting the number of columns. Be sure you are not calling the output number out of the existing range of columns in the matrix of results!

In the Method options below is the list of Setup entry fields, drop-down menus, or switches that are available for the Preliminary Analysis method. Each entry field Value has to comply with the prescribed Allowed range. Options to be set are:

Global residual : This number represents the relative residual, which is set for the mean value of the variance of results. The algorithm iterates until the residual is achieved for both observed values, i.e.: the mean value and the variance.
Prediction residual scheme : The selection of important increment functions is driven by the prediction residual scheme. Currently, there are two schemes implemented. The Percent scheme measures the percentual influence of the selected increment function against all increment functions. The Distance scheme takes individual input distributions into account and measures the statistical influence of the neglected increment functions, i.e. what is the statistical effect of neglected increment functions on the overall result.
The Percent scheme is more suited for problems where users want an accurate model over the whole stochastic domain. However, for large-dimensional spaces (15+), the Percent scheme is very conservative and leads to a large number of required samples. The Distance scheme is coupled with the input distribution types. Thus, it is more suitable for real-world problems.
It is suggested to use the Distance scheme by default.
Sampling scheme for prediction algorithm : Positioning the number of test samples for the prediction scheme (the scheme that selects important increment functions) affects robustness and efficiency. Currently, three schemes are implemented. The first scheme takes two positions on the boundaries of the stochastic domain, the second scheme takes only one position on the boundary of the stochastic domain and the third scheme takes three positions on the boundaries of the stochastic domain.
The first scheme was found to be the most robust vs. efficient. It works well for all the problems including problems with limited randomness, e.g. simulations with explicit FEM codes, DSMC simulations, etc. The second scheme is used when the problem is simple, with null randomness (pure deterministic solution) and one wants to limit the number of expensive computation calls. The third scheme is very robust since it is using three positions to test the influence of each increment function. This scheme should be used if a large portion of randomness is expected in the external code or measurements.
It is suggested to use the prediction scheme 1 by default.
Maximum increment order : The maximum increment order sets the maximum allowed order of increment functions in the model, higher order increments will be disqualified from the computation. One can use this option to force the Uptimai Solver code to stop at a prescribed order and make the convergence process faster. E.g. users do not need to see interactions of inputs, thus, they set the maximum increment order to 1. However, the post-process convergence check is disabled if the maximum order is reached.
It is suggested to let the code select the maximum order and therefore set the maximum increment order to 0.
If the maximum increment order is set to -1, a very fast approach is followed where only variable sensitivities of input variables are computed. This is recommended in cases where only a very reduced number of samples is possible to be called.

General Setup#

The management of project results files and computer resources reserved for the Uptimai Solver is defined in the General setup tab.

In the Pipeline section on the left can the user adjust the names of files where all results received from the solver run are stored. The Iterative store file name sets the prefix for the *.itr file that holds data values of all samples already collected from third-party software. The default basename is set as <project_name>. Store file name sets the naming convention for the final resulting file produced by the Uptimai Solver. This *.upst contains the set of statistical results suitable for analysis in the Uptimai Postprocessor. The default basename is proposed as the <project_name> followed by the <setup-file_name>, the number of the output being solved, and the number of the currently processed case. For reference, see the default name of the result file of the project shown in Figure 3, where the second output was solved as the first case according to the solver setup:

Borehole_UptimRes_O2_C1.upst

The main goal of the proposed convention is to give a hint to the user on how to match the project files with particular settings of the Uptimai Solver just from the look into the file explorer.

The Core Solver section on the right of the window is about the number of CPU cores used by the Uptimai Solver when working. The Multiprocessing switch allows more than one core to be used in the first place. In such cases, the Use cores drop-down menu is enabled where the user can specify the number of cores dedicated to the Uptimai Solver. Besides arbitrary setting the Custom number of cores to be used in a separate entry field, there are two other options in the menu. All allows the solver to use all cores present in the system, while the All-1 option leaves one additional core free for other tasks. The suggested approach is to choose All-1 by default.

The Save setup button at the bottom of the GUI window saves the current setup directly under the existing name into the project directory. The button Save setup as ... opens the file dialogue allowing the use to change the file name and the path of the setup file.