Getting Started#

Python Tool Pro requires a connection to be established from the preferred client-side Python IDE to the Python Tool Pro server in Petrel. Petrel domain objects are accessed from the external Python IDE and the scripts are executed outside of Petrel. The results of the Python scripts can then be streamed back to Petrel.

Establishing a connection between Python and Petrel#

Python Tool Pro is using Cegal Hub to establish a connection to Petrel. The Hub client (Petrel connector application) needs to establish a connection to the Hub server. Once this connection is established, the Python Tool Pro client can connect to the active Petrel instance through the Hub server.


It is recommended that the Hub Connection is configured to be established automatically on Petrel start-up. This can be done centrally for all users. If this is set up correctly you can skip step 1 and go straight to step 2. To configure the Hub connection manually, follow step 1.

Step 1 - Establishing Hub Connection#

Open a Petrel instance with the Python Tool Pro plug-in installed. Open Hub from Marina to establish the connection to the Hub server. It is possible to connect to a local Hub Server or a remote Hub Server.

Local Hub Server#

In the Hub Server Connection pane select the option Use local Hub Server and click on Connect.


Figure 1. Hub local server#

The Hub Petrel plug-in will check if there is a running Hub server on the local machine and connect to it. If no Hub Server is running the Hub Petrel plug-in will start up a new Hub Server and connect to it.

Remote Hub Server#

To use a remote Hub connection, change to the option ‘Use remote Hub Server’. Type in the URL address of the Hub Server. This can be hosted in Cegal Innovation Space, in your company’s centralized Python environment, a virtual machine, or container. If the remote Python environment is managed internally, it is usually your IT department or digitalization team that will have to start and configure the Hub server. The Server Port is most commonly 443 and Use TLS is required. For more detail on the Hub configuration please consult the Hub documentation.


Figure 2. Hub remote#

Now you can connect to the remote Hub Server by clicking ‘Connect’.


Figure 3. Hub server connected#

If the Hub Server status shows Running: False, please contact your Hub admin for the remote Hub Server address.


Figure 4. Hub server status: failed#

Step 2 - Establish a PetrelConnection with Python Tool Pro#

From your preferred Python IDE use the following code:

from cegalprizm.pythontool import PetrelConnection
ptp = PetrelConnection()

This default connection option works for local connections and remote connections where the Python Tool Pro Python client and the Hub Server are running in the same environment. For remote connections with the Hub Server running on a separate machine (separate from the Python environment) or if you have multiple Petrel instances connected to the Hub Server a Petrel context and or the Hub ConnectionParameters have to be defined.

from cegalprizm.pythontool import PetrelConnection
from cegalprizm.hub import Hub, ConnectionParameters
cp= ConnectionParameters(host='hostname',port=portnumber,use_tls=True,use_auth=True)
# Setting the ConnectionParameters is optional and is only needed when the Hub Server is running on a separate machine.
# After the petrelctx is defined it can be used to establish the PetrelConnection
ptp = PetrelConnection(petrel_ctx=petrel_ctx)

Now that your PetrelConnection is assigned to the Python variable named ‘ptp’ (it is possible to use any string for this), you can use it to access the classes and methods form the Python Tool Pro API.

Access the help documentation#

You can use this documentation to find out what methods and properties are available. A quick overview of methods and properties can be displayed with help(PetrelConnection)


Generally, the API tries to be consistent: the method indices returns the i-, j- and k-indices of a position, and operates identically for cegalprizm.pythontool.Grid, cegalprizm.pythontool.SeismicCube, cegalprizm.pythontool.SeismicLine and cegalprizm.pythontool.Surface. There are two main sections to the API, as well as other methods available for particular objects:

  • the Gridding API: The methods indices() and position() convert from and to world-coordinates from indices, and XYZ positions respectively

  • the Chunking API: The methods column(), layer() and all() are available on most objects and return a cegalprizm.pythontool.Chunk. A Chunk allows you to operate on the values in a consistent way.

Iterate over Petrel’s collections of objects#


In  [4]: for obj in petrel.wells:

Out [4]: Well(petrel_name="B1")
         Well(petrel_name="34/10-A 12")

Well logs

In  [5]: for obj in petrel.well_logs:

Out [5]: WellLog(petrel_name="AvgPORO")


In  [6]: for obj in petrel.surfaces:

Out [6]: Surface(petrel_name="Top Etive (Depth 1)")
         Surface(petrel_name="Top Ness [Final]")
         Surface(petrel_name="Top Etive")
         Surface(petrel_name="Base Cretaceous")
         Surface(petrel_name="Top Tarbert (Depth 1)")
         Surface(petrel_name="Base Cretaceous (Depth 1)")
         Surface(petrel_name="AOI Model")

Seismic cubes

In  [7]: for obj in petrel.seismic_cubes:

Out [7]: Seismic(petrel_name="ST8511r92 [General depth conversion]")
         Seismic(petrel_name="ST8511r92 [StructSmooth] 1 [Realized] 1")


In  [8]: for obj in petrel.grids:

Out [8]: Grid(petrel_name="Gullfaks Final (DC)")
         Grid(petrel_name="Gullfaks (Make Horizon)"