Tutorial I: Borehole

In this tutorial it is explained how to create from scratch a New Project and how to use the basics of UptimAI software package on your computer. To learn advanced settings, go to Tutorial II: Xfoil.

Introduction: #

For this tutorial we are going to use as test problem the Borehole Function. It is a well known test function widely used to test methods of uncertainty propagation and surrogate modelling. It consists in a simple analytical model of water flow through the borehole. The main goal is to obtain the response in water flow rate (m3/yr) to 8 input parameters.

The equation that modelizes the borehole is the following:

The variables are described in the following table:

LabelDescriptionType of distributionParametersNominal input value
rwradius of borehole (m)NormalMean = 0.1 Variance = 0.016180.1
rradius of influence (m)LognormalMean = 7.71Variance = 1.00563698.25
Tutransmissivity of upper aquifer (m2/yr)UniformMin = 63070Max = 11560089335
Hupotentiometric head of upper aquifer (m)UniformMin = 990Max = 11101050
Tltransmissivity of lower aquifer (m2/yr)UniformMin = 63.1Max = 11689.55
Hlpotentiometric head of lower aquifer (m)UniformMin = 700Max = 820760
Llength of borehole (m)UniformMin = 1120Max = 16801400
Kwhydraulic conductivity of borehole (m/yr)UniformMin = 9850Max = 1204510985

Where to find it: #

Necessary file to perform this tutorial can be found on the Member Area section of our website

Download -> Tutorial Cases -> Borehole

Borehole.py: Python 3.x script processing input data and evaluating the output. It requires the Numpy Python library

Starting the project: #

Main window: #

The functionality of the Main UptimAI window is to guide you through the statistical process. It can create or load projects, and run all the different parts of the UptimAI software package.

Step 1: To open the main window, go to the folder with your UptimAI installation and start UptimAI.exe

Tip: In the Help button which is available under the About item of the menu bar, you can find an explanation of all the features and buttons of your actual screen. Similarly you can find description of methods and features of other UptimAI programs too!

Step 2: Create an empty folder where all the files created by this project will be saved. After, create a New project in your empty folder using the File -> New Project item from the menu bar.

Tip: A file folder_name.uptim will appear in the working directory once the project is on. This file identifies the folder as a UptimAI working directory, and all projects must have one.

Step 3: Copy the Borehole.py downloaded from the UptimAI’s Member Area inside the project folder.

Input Preprocess: #

Input Preprocess is a GUI to prepare and check the input distributions for all your input variables.

Step 4: Open the Input Preprocess. You can open it directly from the main window, or you can call it from the command window as:

cmd -> uptimai_preprocess.exe

Methods – UQ: #

UQ Method of the Input Preprocessor is where inputs distributions for the uncertainty quantification are prepared. Distribution type can be chosen from the list of presets or an arbitrary shape can be designed using the separate Distribution Creator tool.

Step 5: Select the UQ Method and write the number of input variables of your problem (in this case 8) and press Enter.

Step 6: Define your Inputs. For each variable, you have to change the name of your variable (not mandatory), select a type of distribution, and choose its characteristics. One all the variables are prepared, press the Prepare red button.

Step 7: Now, an additional table will appear with the boundaries and nominal values of the distribution. For this tutorial, we will leave the pre-defined values. To Generate the distributions, press the Generate red button.

Tip: Once you have generated your distributions, 3 different files will appear in your project folder, with all the relevant information.

  • InputSet.txt: Contains general information about each input distribution and its parameters
  • InputDomain.txt: Values of input distribution boundaries and coordinates of the nominal solution
  • XDis.txt: Matrix of input distribution values – each column for one input distribution

Methods – Histogram: #

Method of the Input Preprocessor where inputs distributions for the uncertainty quantification are visualized.

Step 8: Select the Histogram Method

Step 9: In the Load Variables button, load the InputSet.txt file

Step 10: In the Load XDis button, load the XDis.txt file

Step 11: In the Load Domain, load the InputDomain.txt file

Step 12: Go through all the different variables checking that the input distributions are correctly visualized If wanted, you can change the graphic settings and save the plot in File -> Save.

Once you have finished those steps, you can close the Input Preprocess window.

Core Solver Setup: #

Core Solver Setup is a GUI to define the settings for the Core Solver and the Postprocess.

Step 13: Open the Core Solver Setup. You can open it directly from the main window, or you can call it from the command window as:

cmd -> uptimai_css.exe

Step 14: In case the correct InputSet.txt hasn’t been found, load it by clicking the Browse button

Step 15: In the Output section, create a new Output

Step 16: Select the UQ method, and write a 1 in Output to run, as in the borehole case there is only 1 output. Once selected the method, new characteristics will appear regarding numerical characteristics of the solver. For the first run, you can leave the default setup.

Tip: In the Details buttons, you can see more information about all the different characteristics of the setup, giving you advice on the choice for future and more complex problems.

Step 17: In the Coupling section, write the command to run your simulation platform. In this case the command to run will have the following format:

python3 C:\…\borehole.py

Step 18: To finish the setup, press the Generate Button.

Tip: Once you have generated your setup, 2 files have been created in your project folder, with all the relevant information.

  • UptimRes.json: Contains all the information about the setup for the solver.
  • <Project_name>.bat: Batch script, that parallelizes the simulations if requested and call the simulation software (Python script in this case).

Once you have finished those steps, you can close the Core Solver Setup window

Core Solver: #

The Core Solver, is the UptimAI’s UQ algorithm itself. It will be continuouly calling the simulation platform (in this case Python) with different outputs. It does not have any GUI, but the information of what it is doing at any time is printed in the terminal.

Step 19: Run the Core Solver directly from the main window, or you can call it from the command window as:

cmd -> uptimai_solver.exe <Path_to_the_project_folder>

When it finishes the terminal should look similar to the following:

Also, when it is finished 4 different files are generated with all the information from the case, in the project folder:

  • Project_Name_O1_C1.json: Contains all the general information for the postprocess.
  • Project_Name_interp_O1_C1.json: Contains information about the model, to interpolate new samples.
  • Project_Name_it.json: Contains the data from all the simulations performed.
  • Progress_iterative_store_file_O1_C1.json: Contains information about the progress of the core solver.

Result Postprocess: #

Result postprocess is a GUI that allows to evaluate Uncertainty Quantification results obtained in the core solver. In this basic tutorial, only the most basic features of the Postprocess are explained. Information about other features is explained in the Advanced Tutorial.

Step 20: Open the Result Postprocess. You can open it directly from the main window, or you can call it from the command window as:

cmd -> uptimai_postprocess.exe <Project_path>

UQ: #

Sensitivity Analysis: #

The Sensitivity Analysis quantifies the response of mean and variance of results to change in certain variables and their increment functions. It is very useful at early stages of the postprocess to check which variables are more important, and which can be neglected as they don’t have any influence in the results.

Step 21: Load the results file:

File -> Load -> Project_Name_O1_C1.json

Step 22: Enter to the Sensitivity Analysis feature. UQ -> Sensitivity Analysis -> Variable

Step 23: Select the variables that you want to compare in the graphic (for this tutorial, it is recommended for visual purposes to select all), and press Apply.

Increment Function: #

The Increment Function feature allows to visualizes the response of the output to changes in an input variable or combination of input variables. It allows a fast analysis of which are the range of input variables that minimize or maximize the output.

Step 24: Enter to the Increment Function . UQ -> Increment Function -> Increment

Step 25: Press any increment function to see how is the impact that has in the output.

Histogram: #

Visualize separate contribution of each increment function to the final probability density function

Step 26: Enter to the Increment Function . UQ -> Increment Function -> Increment

Step 27: Check the boxes from the increment functions that you want to see in the histogram. If all checked, the result is the statistical distribution of the output.

Iterative File: #

I the iterative file, you can check, edit and save all the combination of inputs that have been required and its outputs.

Step 28: Clean the memory of the program and load the iterative file

File -> Clean

File -> Load -> Project_Name_it.json

Step 29: Open the Iterative File -> Sample Data to see all the sample points that has been computed to generate the Surrogate Model.

Tip: You can export this table to a .xls format with File -> Save

Congratulations! You have finished the Tutorial I: Borehole. Now, you should understand the basics of the software. If you want to learn more advanced settings, please check the Tutorial II: Xfoil