Skip to main content

Borehole

This is a basic tutorial of Uptim.ai software prepared to give a first introduction to the suite, and how to run the different features. To complete this tutorial will be needed Uptim.ai software and a zip file with some complementary files needed for the specific problem to be solved. The zip file can be found inside Uptim.ai Member Area -> Downloads.

The zip file contains the whole project folder, so the user can start at any step of the given tutorial. Nevertheless, if the user wants to fulfill the tutorial from the beginning, only the Python script Borehole.py will be necessary, as all the other files will be generated during the process.

This tutorial will show you:

  • The process of software installation
  • How to run each program of the package
  • What are the main features of each program and how to use them
  • What are the results you can expect
  • How to export and store output data
  • How to deal with basic issues you can encounter during the process

Part 1: Software Installation#

  • 1.1 : Download the software package from Uptim.ai website. It is located inside Member Area -> Download -> Software

  • 1.2 : Open the Uptim.ai installer, and a window similar to Figure 1 will appear

Figure 1: Installer - Initial state
  • 1.3 : Press the button Get Computer UID, which will show the ID of your computer which will be linked to your license

  • 1.4 : Write your UID in the Uptim.ai website -> License Request. We will send you back the license files. The license consists of two different files:

    • UptimAI_Solver.lic
    • UptimAI_UI.lic
  • 1.5 : Click the Configure License button, and under the Node-locked license attach the files sent

Figure 2: Installer - Configure Licenses
  • 1.6 : Press the Install button, choose if you want the shortcuts to be created for easier access to the software, and select an empty folder where the software will be installed. NOTE: You can create the folder directly from the interface, with the +New folder button
Figure 3: Installer - Starting installation
  • 1.7 : Once the message, Installation Complete appears on the screen, installation is finished and you can now use all the features of the software
Figure 4: Installer - Installation Finished

Part 2: Main Interface#

  • 2.1 : Open Uptim.ai software. You can use the shortcuts if selected the option during the installation process, or find the executable inside the installation folder
Figure 5: Main Interface - Initial state
  • 2.2 : Create a New Project. You will have to choose an empty folder where all the project files will be located. The name of the folder will become the name of the project, in this example, we will use the name Borehole. You can create the folder directly from the interface. NOTE: Once you have created the project a .uptim file will appear inside your project folder. That file is used as a flag so the folder is recognized as a Uptim.ai project, and contains information about it.
Figure 6: Main Interface - Project created
  • 2.3 : Now, you have access to all the different features that conform to the Uptim.ai suite. In this tutorial, we will use them one by one

Part 3: Input Preprocess#

  • 3.1 : The first step of all projects is always the Input Preprocessor, which can be opened directly from the main interface. The initial state can be seen in Figure 7.
Figure 7: Input Preprocess - Initial state
  • 3.2 : In this tutorial, we will use the Uncertainty Quantification method. It is possible to modify the Input name, but for simplicity, we will maintain the default name suggested by the software. Then, we can click the create input to start generating the input files
Figure 8: Input Preprocess - Method selected
  • 3.3 : In this case, we have 8 input variables, so we will use the Add input variable, to generate 8 variable spots

  • 3.4 : Insert the following distribution to each variable. Remember to press the confirm button, to save the changes after editing each variable. In the end, you should have the same settings as in Figure 9

Open to view Input Distributions
NameTypeParameter 1Parameter 2
rw_boreholeNormal0.10.0161812
r_influenceLognormal7.711.0056
T_upperUniform63070115600
H_upperUniform9901110
T_lowerUniform63.1116
H_lowerUniform700820
L_boreholeUniform11201680
KwUniform985512045
Figure 9: Input Preprocess - Input distributions defined
  • 3.5 : Click the Prepare Distributions and the Tweak Distributions options to move forward

  • 3.6 : At this point, we can tune the domain of each variable. In this case, as variable number 1 has a normal distribution, we will crop the tails to ensure we don’t have any samples outside the domain. Set the minimum value to 0.03 and the maximum to 0.17

Figure 10: Input Preprocess - Domain defined
  • 3.7 : Finally, we can press the Generate data button, and move to visualizing the input distributions we just created. At this point, we have generated three files that store all the information provided inside an input folder in the project folder.

    • InputSet: Stores the information related to the probabilistic distributions
    • InputDomain: Stores the information related to the boundaries of the problem
    • XDis: Stores a Monte-Carlo set of samples used for the propagation of uncertainties
  • 3.8 : Once we ensure that the histograms presented for every variable are the probability distributions wanted, we can close the Input Preprocessor and move to the next tool.

Figure 11: Input Preprocess - Histogram visualization

Part 4: Set-up Core Solver#

  • 4.1 : Once the inputs have been generated is time to prepare all the settings for the solver. We can do that using the Core Solver Setup, which once opened from the Uptim.ai main interface has the following appearance
Figure 12: Set-up Core Solver - Initial State
  • 4.2 : Once opened, the first thing we need to do is create a new file. We can maintain the name of the file to the default value of UptimRes, and just click on the Create button

  • 4.3 : Then, we will see that the Core Solver Setup has three main tabs. The first one is to select the input files that will be used in this run. As in this case we only have one set of available inputs, we will just select that one

Figure 13: Set-up Core Solver - Input Files tab
  • 4.4 : The second tab, which is Cases / Outputs, details all the settings that are used for tuning the core solver to the needs of each specific problem. Also, there is information about which outputs we would like to study. In this case, we will leave all the parameters to the default value except the global residual which we will reduce to 0.01, to have a very accurate model of the problem.
Figure 14: Set-up Core Solver - Cases/Outputs tab
  • 4.5 : Finally, in the third tab, there is information regarding naming and other solver aspects. In this case, we don’t need to modify anything, and we can directly save the setup. When we do that, a UptimRes.json file will be generated in the project folder containing all the information that we saved. That file will be used by the solver itself.
Figure 15: Set-up Core Solver - General Setup tab

Part 5: Run Solver (Automation)#

  • 5.1 : After the input distributions have been generated and all the settings have been saved, it is time to run the solver. For Uncertainty Quantification problems, there must be a third-party software that can convert a set of inputs to a set of outputs, so then we can adaptively create the model. In this tutorial, this role is played by a Python script called Borehole.py that you can download from the Member Area, so the first step of this process would be to download it and paste the script into the project folder.

  • 5.2 : Now it is time to open the Run Solver (Automation) from the Uptim.ai main interface

Figure 16: Run Solver (Automation) - Initial state
  • 5.3 : We will create a new automation file, by selecting the Create New button, choosing any name, and storing it in the project folder
Figure 17: Run Solver (Automation) - File created
  • 5.4 : Then we will press the plus button, and select the Python feature

  • 5.5 : Finally, under the Location / CMD box, we will select the Borehole.py script that previously we have pasted into the project folder

Figure 18: Run Solver (Automation) - Python selected
  • 5.6 : Clicking the Save & Run button will store all the information in a .automation file, and move to the following screen when the log of the run is shown

  • 5.7 : Now, it is the moment to click Run and wait until the solver finishes. The solver will automatically call the Python script for the samples needed, and build the model. An Everything Finalized message will appear at the end of the log when the solver is finished.

Figure 19: Run Solver (Automation) - Solver finalized

Part 6: Result Postprocess#

  • 6.1 : Congratulations you just ran your first Uptim.ai project! Now is the time to see the results. To do that we will open the Postprocessor from the main interface
Figure 20: Result Postprocess - Initial state
  • 6.2 : First of all, we will start opening the Iterative file. For doing that we will click on the Borehole.itr file in the project files section. The iterative files store all the samples that have been computed, so they can be reused in future projects.
Figure 21: Result Postprocess - Iterative file table view

It has two ways of visualizing the data, or within a table which can be exported or as a scatter plot that allows to start visualizing the trends of how the outputs are distributed for each input.

Figure 22: Result Postprocess - Iterative file scatter plot
  • 6.3 : Now we will open the model itself, opening the Borehole_UptimRes_O1_C1.json

  • 6.4 : In the top section, we have all the features available, we will start with the Sensitivity analysis, which shows which variables are more important. In this case, we can easily see that variables r_influence, T_upper and T_lower are irrelevant and can be neglected from the study. Also, if we switch the sensitivity analysis to increment we can see not only the importance of variables, but if they are important by themselves or by interacting with other variables. In this case, the interactions don’t have a huge impact on the results.

Figure 23: Result Postprocess - Sensitivity Analysis
  • 6.5 : In the Increment Function, we can see the independent effect of each increment, to understand how they are affecting the output and in which zones we want to be to optimize the solution.
Figure 24: Result Postprocess - Increment Function
  • 6.6 : In the Function plot, its depicted the AI surrogate model so the user can extract the exact expected output for any possible combination of inputs. We can use both the visualization mode and the Text mode
Figure 25: Result Postprocess - Increment Function
  • 6.7 : With the partial full histogram, we can see the probability distribution of the output, to be able to see what are the expected zone of results given all the uncertainty from the inputs.
Figure 26: Result Postprocess - Partial/Full Histogram
  • 6.8 : With the influencer, we can go a step further and discover how every variable or increment is actually affecting the output distribution, to understand how we can tune our problem to reduce the variability of the results in a desired way
Figure 27: Result Postprocess - Influencer
  • 6.9 : Finally, with the Regions of minimum/maximum, the software is doing a statistical optimization analysis. The Input option shows in which zones you should be from your original input distribution, no matter the uncertainties of the other variables have a statistical improvement on the output (to go to the maximum or the minimum)
Figure 28: Result Postprocess - Regions of Minimum/Maximum - Inputs

The result option allows us to see which would be the expected result if the presented new input distributions were considered.

Figure 29: Result Postprocess - Regions of Minimum/Maximum - Results

Finally, in the Optimum option, the software is showing what is the absolute maximum and the absolute minimum found with a Monte Carlo approach, and where is located.

Part 7: AI Surrogate Model#

  • 7.1 : The last feature of this tutorial is the AI surrogate model, which allows for easy access to the model and to receive the output for any set of samples given. We can access, as all the other features, from the main interface.
Figure 30: AI Surrogate Model - Initial state
  • 7.2 : First, we will need to select the interpolant file (the model), that we have previously created from the solver (Selecting the Borehole_UptimRes_O1_C1.upsi file)

  • 7.3 : Then we will need to select a Input File, that has to be in a .csv format with as many rows as samples wanted and as many columns as inputs have the problem. For this example, we can use the XDis file situated, in the inputs folder inside your project.

  • 7.4 : Finally, we can change the Result file name if needed, and press the run button. A file will be generated in the project folder with the output given from the model from all the samples that were fed.

Figure 31: AI Surrogate Model - Computation finished