API Server

API Server

1
Disclaimer! While taking this training tutorial, it is worth remembering that the techniques and approaches presented
here should not be considered the only right way. All the techniques shown further in this course should be considered
recommendations. The main goal is to describe all the main functionalities available in tNavigator. The approaches
applied in real projects can differ from the ones shown in this course. None of the entry data used in this tutorial is
real.

2
API Server: Digital Asset
tNavigator's Digital Asset is a fully integrated solution, which creates a consolidated system of digital copies of production assets: from
seismic and geology to field operations optimization

The solution is based on the global tNavigator project ecosystem

The system offers connection with the project and data updating via API Server

Virtual flowmetry and field production optimization in real time

Model Designer Geology Designer

MBA Seismic
Geosteering

Network Designer PVT Designer

Well Designer RP Designer

3
API Server operation
API Server is designed to manage tNavigator projects using external control systems

A proprietary Python library—tNavigator_python_API—is used by API Server

API Server operates as follows:

• a Python-based application connects to tNavigator, Python application +
tNavigator_python_API
• connects to a project (the entire tNavigator ecosystem is supported),
• sends commands similar to workflow calculations to the project for execution, and
[Link]
• receives the results of the commands being executed

Model Designer / Geology Designer /

Applications of API Server: PVT Designer / RP Designer / MBA

• Creation of digital twins for production objects

Network Designer
• Automation of routine operations and local management of user projects
• Virtual flowmeter surveys
• Measurements verification Well Designer

• Production and injection optimization

4
API Server diagram

5
 Contents

• System requirements
• API Server licensing
• API Server installation
• Unique features of API Server

Use of API Server

6
System requirements for the tutorial
To complete this tutorial, 64-bit Python version 3.11.x must be installed for all users

Administrator rights are required for the installation

7
API Server licensing
tNavigator provides two types of API Server licenses:
API Server: the license allows managing API Server directly
API Client: the license connects clients to API Server from independent workstations

When connecting multiple clients to the same server, 1 API Server license + N * API Client licenses are required (where N
corresponds to the number of connected clients)

API Server

API Client

API Client

API Client
8
API Server installation
A proprietary Python library—tNavigator_python_API—is used by API Server. Libraries are a part of the tNavigator installer

During the installation process, you must select the Custom installation mode and tick the following items: Libs and tNavigator Console
(the console version of the software)

9
tNavigator_python_API library installation
After tNavigator is installed, the Python library called tNavigator_python_API will be in the software installation directory. This library
can be installed using the standard Python library installation method:
• Run the command prompt with administrator rights. Type and run the following command with the name of the .zip archive of the
library:
pip install tNavigator_python_API.zip

Troubleshooting tip:

A system reboot may be required for the settings to be applied

10
Key commands of API Server
The API Server library includes some unique functions necessary to work with a project:
• Connecting to the executable [Link] file
• Opening of the main Designer project (*.snp) and other subprojects

tNavigator API Server

connection() create_project() open_project() close_project()

.get_list_of_subprojects()

.get_subproject_by_name()

11
Types of data returned
API Server supports receiving data from projects of the tNavigator ecosystem

All key data types necessary for effective work with API Server are supported

Usage:
• To be used in code, the data must be prepared in the required format
• The <return> operator returns the result of the Python function

Data types used in tNavigator API Server

Numerical Sequential Pandas Library (DataFrame)

Integer Double/Float String List Dict

12
API Server functions and methods
.Connection() is a function designed to set a connection between the Python application and tNavigator. It returns a Connection object
Function arguments:

path_to_exe=<name> the path to tNavigator's console executable file (string)

minimum_required_version=<version's number> the minimum required version of tNavigator, Any = None
license_wait_time_limit_secs=<time> waiting time for an available license in seconds, int = None

# Code Example:
# The import of necessary libraries
import tNavigator_python_API as tnav
# Creating a Connection object to run the executable file of tNavigator. Here, tNavigator's version
should not be older than 23.3 and the waiting time for an available license is set to 5 seconds
conn = [Link](path_to_exe='d:/tNav/24.3/[Link]', minimum_required_version=(23.3),
license_wait_time_limit_secs= 5)

13
API Server functions and methods
.open_project() takes the absolute or relative path to the *.snp file of a Model Designer project, which may also contain projects of other
Designers (Network, Well, etc.). This function returns the project object required to work with the project
Function arguments:

path=<name> the path to the *.snp file of a Model Designer project (string)
save_on_close=<True/False> the Boolean argument determines whether the project should be saved after code
execution. The default value is False, i.e., do not save

# Code Example:
# Connect to the project without saving it when exiting:
with conn.open_project(path='E:/Projects/API/tnav_api/api_calc.snp', save_on_close=False) as
snp_project:
wd_proj_list = snp_project.get_list_of_subprojects(type='wd')
print(wd_proj_list)
# Connect to the project and save it when exiting:
with conn.open_project(path='E:/Projects/API/tnav_api/api_calc.snp', save_on_close=True) as
snp_project:
wd_proj_list = snp_project.get_list_of_subprojects(type='wd')
print(wd_proj_list)

14
API Server functions and methods
ProjectType is a class for defining the type of the subproject to which the connection is set
The following project types are available:
• 'MD' for connection to a Model Designer project
• 'GD' for connection to a Geology Designer project
• 'ND' for connection to a Network Designer project
• 'WD' for connection to a Well Designer project
• 'RP' for connection to an RP Designer project
• 'PVT' for connection to a PVT Designer project
# Code Example:
with conn.open_project(path='E:/Projects/api_calc.snp', save_on_close=True) as snp_project:
wd_proj_list = snp_project.get_list_of_subprojects(type='wd')
print(wd_proj_list)

.close_project() is a function (without arguments) which closes a project

# Code Example:
project.close_project()

15
API Server functions and methods
.get_list_of_subprojects() is a function that returns a list of project objects (nested subprojects) of the specified type
• Function arguments:
type=<project type> the type of the ProjectType projects (see slide 14) to which you are connecting
# Code Example:
with conn.open_project(path='E:/Projects/API/tnav_api/api_calc.snp', save_on_close=False) as
snp_project:
wd_proj_list = snp_project.get_list_of_subprojects(type='wd')
print(wd_proj_list)

get_subproject_by_name() is a function that returns a project object (nested project) by its name and type
• Function arguments:
type=<project type> the type of the ProjectType projects (see slide 14) to which you are connecting
name=<project name> the name of the project to which you are connecting
# Code Example:
well_designer_project = snp_project.get_subproject_by_name(name=“Well_1”, type='wd')

16
API Server functions and methods
run_py_code() is a function that passes and executes Python code in a tNavigator project and returns the result of the return statement (if
it is present in the code)
• Function arguments:

code=<code> the Python code that will be passed to the tNavigator project and executed

file=<file> the path to the external *.py file where functions can be saved. If two files arguments
are used along with the code argument, the code from the passed string is attached to
the code from the file

files=<list of files> the path to the list of files with functions that can be called in the code argument

save=<True/False> a logical flag that determines whether the project is saved after code execution. The
default value is False, i.e., do not save
# An example of calling the Python function whose source code is in the specified files
nd_proj.run_py_code(files=['[Link]','[Link]'],code='my_func1(10,20,4)')

17
Python code generation for API Server
Commands for API Server can be generated automatically using
the standard functionality of tNavigator workflows
API Server commands generation
The key advantages include generation of commands in the
form of graphical diagrams, combination of several commands, tNavigator project
use of internal loops and logical expressions, and debugging in
the graphical interface Workflow

Workflows support any operations with objects within a

Operations with objects
project: creating and editing objects, as well as obtaining their
parameters
Python custom code

External Python
application

18
Python code generation via a workflow
tNavigator modules support workflows written in Python
All calculations within a workflow can be converted to Python code using the Show Code option

Show/Hide Code

19
 Contents

• Project management using API Server

• Data acquisition
• Use of variables and loops

Examples of API Server

Methods and Functions

20
Project management using API Server
This project management example contains code in which # Code Example:
the following steps are performed sequentially:
1 import tNavigator_python_API as tnav
1. Importing libraries
2. Connecting to the project 2 conn = [Link](path_to_exe='[Link]')
snp_project = conn.open_project(path= 'api_calc.snp')
3. License request well_designer_project =
4. Project management snp_project.get_subproject_by_name(name= 'Well1',
type= 'wd')

3 well_designer_project.run_py_code(code="request_license
_feature (feature='FEAT_WELL_DESIGNER')")

4 vfp_param = well_designer_project.run_py_code(code=
"""vfp = get_vfp_table_by_name (name='VFP 1')
fr = vfp.get_friction ()
hc = vfp.get_hydrostatic ()
a = [fr, hc]
return a""")

print(vfp_param)
well_designer_project.close_project()

21
Data acquisition
The task is to export the matching coefficients of pressure
# Code Example:
losses along the borehole due to hydrostatic effects and # workflow command execution
vfp_param = well_designer_project.run_py_code(code=
friction """vfp = get_vfp_table_by_name (name='VFP 1')
fr = vfp.get_friction ()
Solution: the run_py_code method will pass Python code to
hc = vfp.get_hydrostatic ()
the tNavigator project so that: a = [fr, hc]
return a""")
1. The VFP correlation object is written to the <vfp>
# Printing data from the vfp_param variable to the log
variable using the get_vfp_table_by_name (name='VFP print(vfp_param)

1') method
2. The value of the friction coefficient is written to the
variable <fr> using the vfp.get_friction() method # The results of code execution:
3. The value of the hydrostatic coefficient is written to the
E:\Projects\API\tnav_api\.venv\Scripts\[Link]
variable <hc> using the vfp.get_hydrostatic() method E:\Projects\API\tnav_api\API_.py
4. The list [fr, hc] is written to the variable <a> [0.86, 1.0]
Process finished with exit code 0
5. The function returns the object written to the variable
<a> using the <return> operator

22
Use of variables and loops
Variables are passed to a string command using standard Python
# Code Example:
functionality: vfp_list = ['VFP_1', 'VFP_2', 'VFP_3']

• Formatted string literals (f-strings):

for i in vfp_list:
vfp_name = "VFP 1" vfp_name = i
vfp_param = well_designer_project.run_py_code(
vfp_param = well_designer_project.run_py_code(code= code=f"""
f"""vfp = get_vfp_table_by_name (name=' {vfp_name} ')""") vfp = get_vfp_table_by_name (name='{vfp_name} ')
fr = vfp.get_friction ()
he = vfp.get_hydrostatic ()
• String formatting method (format()): a = [fr, he]
return a
vfp_name = "VFP 1" """)
vfp_param = well_designer_project.run_py_code(code=
print(vfp_param)
"""vfp = get_vfp_table_by_name
(name='{}')""".format(vfp_name))

23
 Contents

• Geology Designer
• Model Designer
• Network Designer
• Well Designer

Examples of Connecting
Designer Projects

24
Geology Designer. Collecting information on a set of projects
API Server allows collecting any information on a set of tNavigator projects
An example of a problem to be solved: getting a single *.xlsx file which would contain the positions of the markers (the depths where
layers intersect with wells) for all projects from a specified folder
Input data: a folder with geological tNavigator projects with additional subfolders
Additional Python libraries used:
• os (for work with files)
• pandas (for collecting marker data in tables)
• openpyxl (to save the data to an .xlsx file)
Result: a file in .xlsx format containing the positions of the markers for all given projects in the form of a table. The data for each project
is shown on a separate page

25
Model Designer. Production data update and model calculation
API Server allows to import any data to Model Designer and then
calculate a model on its basis

An example of a problem to be solved: production data and

production strategy should be updated. The dynamic model
should be calculated

Input data: a Model Designer project with a created dynamic

model variant along with an updated production data file

Result: the Model Designer project is updated and the dynamic

model is calculated

26
Well Designer. Pressure profile calculation
API Server allows to run any calculation in the Well Designer
module

An example of a problem to be solved: calculating a pressure profile

and obtaining well design data

Input data: a Well Designer project

Additional Python libraries used:

• pandas (collecting marker data in a table)

Result: the necessary data is calculated for the wellbore pressure

profile and the VFP matching parameters and well design data are
exported to the log

27
Network Designer. Setting the operation mode & network calculation
An example of a problem to be solved: import of the current pressure data, i.e., the terminal pressure and the well operation pressure;
hydraulic calculation and production optimization

Input data: a Network Designer project, production data

Result: Calculation of the surface network performance parameters; export of the output data to external files

28
Would you like to Do you have any
learn more? questions?
Training tutorials and test models Contact technical support
are available on
[Link] tNavigator@[Link]

29