# 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

The general appearance of the program window, especially its left section, is described in detail
in the **Input preparation** link. Here the main focus is on the other part
that is to a certain point individual for each of the supported methods. The initial
of the GUI window when preparing inputs for the **Preliminary Analysis** is shown in
Figure 1, as the user starts from scratch and needs to
**Define Input Variables**.

### Define Input Variables

In the beginning, only two controls are available for the user:

**# of Monte-Carlo samples**: Entry field setting the number of samples for Monte Carlo simulation, size of input distributions. It must be an integer value between 1,000 and 1,000,000.**Add input variable**: Creating a new variable (parameter) of the input domain. Each added variable appears at the bottom of the list of already existing variables.

The Monte Carlo sampling is used for model propagation and visualizations. The default value of 100,000 is based on the best-practice trade-off between the speed of the solver and postprocessor, file sizes, and model precision.

Adding an input variable enhances the input domain space with one dimension. There has to be at least one for the model to be created. Figure 2 describes the situation with multiple input variables already created (see this link for more info about the borehole problem). One of the displayed variables is about to be edited. The input variable can be set using the following controls:

**Variable name**: Label of the input parameter, which is being used throughout the whole process up to the postprocessing. The variable name cannot contain empty spaces, these are automatically replaced with underscores.**Distribution**: Selection box where the user sets the shape of the probabilistic function for the input variable. According to the distribution type selected, additional entries with shape parameters appear. A detailed description of featured probability distribution types can be found in the section**Input distribution types**.**Confirm**: Any changes need to be confirmed with this button to take effect.**"X"**: Each input variable can be deleted when clicking this icon.**"="**: Allows input variable dragging to change the ordering of inputs in the projects.**"+ Advanced Options:****Activation Type"**: Allows change between*Active*(by default) and*Inactive*.*Active*means that the intrinsic uncertainty of the variable will be propagated and*Inactive*means that only the nominal value will be used (variable won’t be studied).

Adding one or more input variables activates the *Prepare distributions* button. This one invokes the
preparation of randomly distributed samples according to the settings. If there are invalid
entries in the input variable definition, the user is informed and not allowed to continue to the next
step until everything is by the book. Then, the button itself turns into *Tweak distribution options*,
sending the user to this next step. Also, the **Tweak Distribution Options** item is activated
in the fishbone navigation bar on the left.

### Tweak Distribution Options

At this point, the user adjusts the boundaries of the input domain and the so-called nominal sample. Boundaries are recommended to be adjusted, especially for distribution shapes where the user defines parameters like mean value and standard deviation. In these cases, the edges of the domain depend on the randomization of samples within the input variable. Thus, modification is usually required to set the exact range for such inputs. For certain types of distribution shapes as uniform or discrete, edges of the domain are exactly given by the distribution shape definition and cannot be changed after.

The nominal point is a sample acting as a baseline for the created surrogate model and analysis.
In the model, the results of all data samples are compared with the result value of the nominal
sample. This process allows handling the effects of input parameters and their interactions
separately as increments to the nominal value. It must be within the range of each input variable
and not be equal to its boundaries. Although not strictly necessary, it is recommended
to place the nominal sample into the statistical centre of the domain. Then, the process of the
surrogate model creation is most efficient and precise. The nominal sample's default position is
suggested as the mean of the probability distribution of each input variable. When changing its position,
(shown in Figure 3) it is advised to not shift it by more than 10% of the range
of each input. As in the case of input variable distribution definition, all changes must be saved
using the *Confirm* button.

For the sampling of variables leading to periodic or symmetrical functions
(typically, but not exclusively, angles of any kind), extra
caution is required. It is highly recommended not to set their
nominal value exactly to the centre of symmetry of the
corresponding input distribution**!** A typical example can be the
angular position of a crankshaft, wave phase, etc.

Clicking the *Generate data* button at the bottom right invokes the saving
of `.txt`

files with randomly distributed samples according to the settings and input domain info.
Then, the button itself turns into a **View Data Histogram**,
sending the user to this next step. Also, the **View Data Histogram** item is activated
in the fishbone navigation bar on the left. For fundamental changes in any input distribution,
the user can return to the previous step with the *Return to Input Variables* button.

### View Data Histogram

In this section, all created input variables can be reviewed to check their probability distribution shapes. Users can see the histograms of randomized samples as these are about to be used. It is recommended to provide such type of check before an actual preliminary analysis run to prevent solver crashes and eliminate misinterpretation of results.

To the left of the actual histogram plot, there are controls of the figure to be shown. The box
labelled *Variables* contains the list of input parameters available in the domain. Each item can be
selected by mouse clicking, showing the corresponding distribution shape. The appearance of the
plot can be changed using the settings in the *Plot options* section:

**Plot title**: Displayed above the plot, input variable name by default.**X label**: Label of the X axis, input variable name by default.**Y label**: Label of the Y axis. The default text contains the number of samples used for the histogram and the number of bins these are split in.**Title size**: Size of the title font.**Label size**: Size of the font for both axis labels.**Show legend**: Switch turning on/off the legend of the plot.**Legend size**: Size of the legend font.**Range**: Double-sided slider allowing to show a slice of the input distribution in detail. Dragging one of the slider's points limits the depicted range one can move with the section along the X-axis by dragging the green bar of the slider (both edge points are highlighted).**Adjust axes**: Toggle if the X-axis range of the plot should be only the range adjusted with the slider above (on) or the full range of the input distribution (off).**Normalize plot**: Turn on/off normalization of the histogram. Y-axis values change accordingly, Y-axis' default label changes from*N*to*Density*.**Log. vertical axis**: Turns on/off logarithmic scaling of the Y-axis.**Bin count**: Set the number of bins for the histogram. The recommended value is below 200. Needs to be confirmed with the*Apply*button.

There are two more buttons under the plot. *Return to Distribution Options* brings users back
to the previous step of **Tweak Distribution Options** where they can fix boundaries or the
the nominal sample position. The other button will *Close Preprocessor* since all the input files
required are ready for the next step, which is **Core Solver Setup**.

Additional vertical lines that can be seen in the plot show the boundaries of the input variable distribution (input domain edges) and the position of the nominal sample. Also, clicking into the plot invokes the cross with a label showing the exact value of the selected point in the histogram.