Release Notes Version 2#
What’s new in 2.3#
Python Tool Pro 2.3.2 (July 2023)#
New functionality#
Accessing Petrel templates#
Python Tool Pro now supports the retrieval of Petrel templates, allowing you to assign them to a Python variable as a Template object.
To demonstrate this feature, consider the following code examples:
temp1=[i for i in ptp.templates][0]
temp1
Output: Template(petrel_name=”Pres_VES”)
log1=[i for i in my_well.logs][0]
log1.get_template()
Output: Template(petrel_name=”Pres_VES”)
For discrete template objects it is possible to retrieve the discrete codes of the template. This returns a dictionary with the codes and strings.
temp2.discrete_codes
While it’s not possible to directly set a template for an object, you can leverage Petrel workflows to achieve this. By creating a Petrel workflow with the “Set template” work-step, you can pass the template object from Python Tool Pro when executing the workflow.
Check out the example workflow screenshot below:
To execute the workflow with a new template, you can use the following code:
workflow_variable=workflow.input["InputA"]
workflow.run({workflow_variable:new_temp})
Furthermore, an ‘template’ argument has been added to the clone method, allowing you to create a clone of an object with a different template. This functionality only works when the ‘copy_values’ argument is set to False, which is the default value. See the code example below:
log1.clone('newlog2',template=temp1)
Support for checkshots#
A newly supported domain object are checkshots. You can now retrieve the checkshot object and easily read its values into a Pandas DataFrame. Please note that while you can retrieve and analyze checkshot data, editing checkshots is currently not supported.
Creation of well objects#
It is now possible to create new well objects using Python Tool Pro. This is an experimental method and needs to be explicitly enabled when establishing the PetrelConnection.
from cegalprizm.pythontool import PetrelConnection
ptp=PetrelConnection(allow_experimental=True)
To support the creation of well objects it is now also possible to retrieve well folder objects. The well folder object is passed as an argument to define the location of the new well.
well_folder=[i for i in ptp.well_folders][0]
well_folder
Output: WellFolder(petrel_name=”Wells”)
To create a new well using following code snippets.
ptp.create_well('new_well',well_folder)
The new well is created without location information or well survey. This can be added using the new methods on the well object described below.
It is now also possible to create a side track from a well object. To create a side track use the method .create_lateral().
new_lateral=my_well.create_lateral('b4 lateral')
new_lateral
Output: Well(petrel_name=”b4 lateral”)
Added support for more completion types#
The API for completion objects has been expanded to provide enhanced support for more completion types. This update includes support for squeezes and plugbacks, in addition to the existing functionality for perforations and casings.
Previously, only the start date was available from the perforation. However, with the new support for squeezes, the end date is now also accessible. This allows for more comprehensive analysis and management of completion operations. The support of Plugbacks allow the calculation of the perforation thickness and logic surrounding squeezes and perforations.
Furthermore, we have introduced the ability to add casings to your completion objects and set the equipment used in the casing.
Retrieving a list of available casing equipments#
A new feature has been added that enables the user to retrieve a list of available casing equipments from a completion set object. This enhancement allows users to easily access the available options when adding a casing to the completion set. It is possible to retrieve a Template object from the class PetrelConnection or directly from a supported domain object.
Addition of methods and properties to well object#
The well object has been enhanced with several new properties and methods.
One addition is the ability to retrieve and set the well datum of a well object.
Example usage:
well.well_datum
Output: (‘KB’, 0.0, ‘Kelly bushing’)
well.well_datum = ("KB", 25, "Kelly Bushing")
well.well_datum
Output: (‘KB’, 25.0, ‘Kelly bushing’)
A further addition is the ability to retrieve and set the well coordinates of a well object.
well.wellhead_coordinates
Output: (456645.06, 6781579.73)
well.wellhead_coordinates = (456723, 6781714)
well.wellhead_coordinates
Output: (456723.0, 6781714.0)
Furthermore, a new functionality has been introduced that allows the creation of a new well survey on a well object. To achieve this, simply provide the name of the new survey and the survey type. This is an experimental method and needs to be explicitly enabled when establishing the PetrelConnection. The supported survey types include:
‘X Y Z survey’
‘X Y TVD survey’
‘DX DY TVD survey’
‘MD inclination azimuth survey’
On a regular well object use “.create_well_survey()”. On a side track well use “.create_lateral_well_survey()”.
new_survey=my_well.create_well_survey('new_survey','MD inclination azimuth survey')
new_surv
new_survey2=new_lateral.create_lateral_well_survey('new_lateral_survey','X Y Z survey',my_well.surveys[0],1740)
new_survey2
The “create_well_survey” method will fail on lateral well objects and the “create_lateral_well_survey” method will fail on non-lateral well objects. A new property has been introduced allowing you to check if the well object is lateral or not.
my_well.is_lateral
Addition of methods and properties to well survey object#
The well survey object has been enhanced with several new properties and methods.
It is now possible to retrieve and set the algorithm for the trajectory calculation. This is supported for well surveys of type “X Y Z”, “X Y TVD” and “DX DY TVD”.
For surveys of type “MD inclination azimuth” and “DX DY TVD” it is possible to retrieve the azimuth reference. Setting the azimuth reference is currently not supported.
It is also possible to retrieve and set the tie_in_md for lateral well surveys.
For all types of well survey it is possible to check if the trajectory calculation is valid.
Changed functionality#
Improved well filter in marker collections#
Significant improvements have been made to the filtering capabilities of the marker collection object. With the latest enhancements to the as_dataframe() method, you now have more options to refine and extract valuable information from your marker collection.
New Filter Options:
Well objects
Stratigraphy objects
Marker attributes
Further it is possible to exclude the Petrel index from the DataFrame.
Example:
Get a dataframe with information about all attributes for all Markers in the MarkerCollection
mc = petrelconnection.markercollections["Input/Path/To/MarkerCollection"] df = mc.as_dataframe()Example:
Get a dataframe with only basic information about all attributes for all Markers in the MarkerCollection. Use the marker_attributes_filter and pass a empty list.
mc = petrelconnection.markercollections["Input/Path/To/MarkerCollection"] df = mc.as_dataframe(marker_attributes_filter=[])Example:
Get a dataframe with information about specific wells. Supply a list of well objects to the wells_filter argument.
my_well = petrelconnection.wells["Input/Path/To/Well"] my_well2 = petrelconnection.wells["Input/Path/To/Well2"] mc = petrelconnection.markercollections["Input/Path/To/MarkerCollection"] df = mc.as_dataframe(wells_filter=[my_well,my_well2])Example:
Get a dataframe with only basic information for a specific well and two stratigraphies while skipping the Petrel index
my_well = petrelconnection.wells["Input/Path/To/Well"] mc = petrelconnection.markercollections["Input/Path/To/MarkerCollection"] strat1 = mc.stratigraphies["First Stratigraphy"] strat2 = mc.stratigraphies["Second Stratigraphy"] df = mc.as_dataframe(include_petrel_index=False, wells_filter=[my_well], marker_stratigraphies_filter=[strat1, strat2], marker_attributes_filter=[])Example:
Get a dataframe with basic information and the selected attributes for all Markers connected to a borehole that exists in the project
mc = petrelconnection.markercollections["Input/Path/To/MarkerCollection"] attributes = [] attributes.append(mc.attributes["Interpreter"]) attributes.append(mc.attributes["Observation number"]) df = mc.as_dataframe(include_unconnected_markers=False, marker_attributes_filter=attributes)
Dealing with duplicate attributes in a marker collection#
For attributes in marker collections with the same name a numeration is added. In previous version the numeration started with (2) at the first duplicate attribute. In Python Tool Pro this changed to start with (1) at the first attribute to be more consistent with othe domain objects suporrted in Python Tool Pro.
Bug fixes#
Performance improvements on marker_collection.as_dataframe()#
On a large dataset of well markers creating a Pandas DataFrame was very slow. This was improved by not iterating over the Petrel index when retrieving the entire marker collection as a dataframe. Time savings of 85 % are possible.
Unexpected error exception for invalid well log data#
In previous versions an UnexpectedErrorException: Exception of type ‘alglib+alglibexception’ was thrown when working with invalid well log data. The error message was improved to clarify that the well log data is not valid. e.g.: “No valid log data found for well:’Copy of Well A 1’ and log:’DEPT’”
No history added to new marker attributes#
When creating a new attribute in a well marker collection this history of the object now reflects that this was done using Cegal Python Tool Pro.
Wrong Y from the .ijks_to_positions()#
When using the method .ijks_to_positions() on a 3D model grid an incorrect J position was returned. This is fixed in Python Tool Pro 2.3 .
WellSurvey.as_dataframe() returned incomplete calculated trajectory#
In previous version the method ‘as_dataframe()’ returned some additional columns from the calculated trajectory, but did not return all rows. In Python Tool Pro 2.3 ‘get_calculated_trajectory’ was introduced as an additional flag. By default this flag is set to False and the ‘as_dataframe()’ method returns only the editable columns of the well survey type and the recorded values as rows. When setting the flag ‘get_calculated_trajectory’ to true the ‘as_dataframe()’ method returns all rows of the calculated trajectory and all available columns for that well survey type.
Indexing was not possible on surface retrieved from parent folder#
Python Tool Pro allows users to retrieve a list of surfaces located in the same folder as the current Surface object. Previously, when attempting to retrieve Surface objects from this folder, it was not possible to obtain the Petrel index. However, this issue has been addressed and is now resolved.
Removed the ‘clone’ method from objects that do not support it#
Previously, all objects in the Python Tool Pro API contained a ‘clone’ method, even if it was not supported by certain objects. This led to a Python exception when the method was invoked on these objects. In order to prevent this issue, the ‘clone’ method has now been removed from the following objects: Well, 3D model grid, Surface, Marker collection, Observed data set and Workflow.”
Deprecations#
Deprecation of the copy_values Argument in the clone Method for GlobalWellLog Objects#
The ‘copy_values’ argument in the ‘clone’ method of a global well log object has been deprecated and will be removed in Python Tool Pro 3.0
gwl.clone('newgwl',copy_values=True)
DeprecationWarning: The copy_values argument is not implemented for GlobalWellLog objects and will be removed in Python Tool Pro version 3.0.
Deprecation of the ‘well’ and ‘marker_stratigraphy’ argument#
On well marker collection objects the ‘as_dataframe’ method has the optional arguments ‘well’ and ‘marker_stratigraphy’. These arguments are now deprecated. Use the new arguments ‘wells_filter’ and ‘marker_stratigraphies_filter’ to ensure backward compatibility going forward.
DeprecationWarning: The ‘marker_stratigraphy’ argument is deprecated and will be removed in Python Tool Pro version 3.0. Use ‘marker_stratigraphies_filter’ instead.
DeprecationWarning: The ‘well’ argument is deprecated and will be removed in Python Tool Pro version 3.0. Use ‘wells_filter’ instead.
What’s new in 2.2#
Python Tool Pro 2.2.4 (May 2023)#
Python Tool Pro 2.2.4 is patch version change picking up a new version of Cegal Hub with a fix around the use of self signed certificates.
Python Tool Pro 2.2.3 (December 2022)#
Python Tool Pro 2.2.3 is minor version change with added functionalities and backward compatible API changes.
New functionality#
Support for well marker collections#
You can retrieve well tops from Petrel in form of well marker collections. Marker collections can be loaded into a Pandas DataFrame in Python. Well top attributes can be updated by retrieving the marker attribute object. A well marker point can be added.
Retrieve zone and segment information from 3D grid models#
It is now possible to retrieve zone and segment information of a 3D grid model. The IJ pairs of segments and the top and base k of zones are returned and can be matched to the IJK values of a (grid property) chunk dataframe to retrieve, update or create new values for specific zones and/or segments.
from cegalprizm.pythontool import PetrelConnection
ptp=PetrelConnection()
my_grid=[i for i in ptp.grids][0]
seg_ls=[i for i in my_grid.segments]
print(seg_ls)
my_segment=seg_ls[0]
print(my_segment.petrel_name)
print(my_segment.cells)
zone_ls=[i for i in my_grid.zones]
print(zone_ls)
my_zone=zone_ls[0]
print(my_zone.petrel_name)
print(my_zone.top_k)
print(my_zone.base_k)
Information about coordinate system#
The PetrelConnection has a new property ‘crs_wkt’ that returns the well-known-text of the project coordinate system.
from cegalprizm.pythontool import PetrelConnection
ptp=PetrelConnection()
ptp.crs_wkt
The same property is available for many of the supported Petrel objects.
Retrieve the affine transform of gridded objects#
It is now possible to retrieve the affine transform of gridded Petrel objects. Together with the well-know-text of the coordinate system (using the property crs_wkt) it is possible to create georeferenced output.
var.crs_wkt
var.affine_transform
Support for completions#
Completions are supported in Python Tool Pro 2.2 as experimental method. Users have to explicitly enable these methods when establishing the connection to Petrel.
import blueback
from blueback.pythontool.grpc.petrelconnection import PetrelConnection
ptp = PetrelConnection(allow_experimental=True)
It is then possible to retrieve a completion set from a well object. Python Tool Pro will always retunr the active completion set of the well object. Currently only casings and perforations are supported.
completions = well.completions_set
completions.as_dataframe()
Completions set can be loaded into a Pandas DataFrame for QC. Casing and casing parts can be updated by changing the bottom MD value. Perforations can be updated by changing the top and bottom MD, the start date and the skin factor. New perforation objects can be added to the completion set.
Changed functionality#
Add unit symbol to PointSet dataframe#
When using the method .as_dataframe() on a PointSet object it is now possible to include the unit symbol of the attributes. The unit symbol is added in square brackets to the DataFrame column name. When writing values back to Petrel a flag indicating that the dataframe contains units can be set to strip the unit symbol from the DataFrame coloum name.
Retrieve history returns string for objects without a Petrel history#
Petrel objects without a history table now return a string stating the fact that no history table is available. This applies to: * Global well logs * Discrete global well logs * Grid segments * Grid zones * Petrel workflows
Bug fixes#
Unit conversion symbol#
The values of Petrel objects with customized Petrel templates having unit symbols different to the default Petrel unit symbol where converted to the default Petrel unit for the that template. This lead to the values in Python beiing different than the values shown in Petrel. In Python Tool Pro 2.2 all values retrieved on the Python side are now the same as seen in Petrel.
Null values for discrete integers#
Null values of discrete integers were returned as np.maxint. This is fixed in Python Tool Pro 2.2 and pd.NA is returned. pd.NA needs to be used when setting values back in Petrel.
Known issues#
It is not possible to retrieve the statistics of a well marker attribute or of casings and perforation objects. The method .retrieve_stats() returns an empty dictionary.
Python Tool Pro 2.2.1 and Python Tool Pro 2.2.2#
These are unpublished versions. The available version of Python Tool Pro went from 2.1.3 to 2.2.3.
What’s new in 2.1#
Python Tool Pro 2.1.3 (Ocotober 2022)#
Python Tool Pro 2.1.3 is a patch release. It includes a new version of the Cegal Hub plug-in avoiding a dll conflict with Petrel 2022. Further it inludes a bug fix on the as_dataframe() method unit conversion. Python Tool Pro converts units of customized templates to Petrel default template units. Values stored as type ‘double’ in Petrel with a template unit different to the Petrel project default template unit were not converted correctly. Values in a template unit the same as the Petrel project default template unit were not affected. The conversion to the Petrel project default template unit is corrected.
Python Tool Pro 2.1.2 (September 2022)#
Python Tool Pro 2.1.2 is a patch release introducing support for Petrel 2022.
Python Tool Pro 2.1.1 (June 2022)#
Python Tool Pro 2.1.1 is a patch release with performance improvements for reading and writing values from and to well logs.
Python Tool Pro 2.1.0 (May 2022)#
Python Tool Pro 2.1.0 is minor version change with added functionalities and backward compatible API changes. Moving to Python Tool Pro 2.1.0 from Python Tool Pro 1.x includes a major version change where Python Tool Pro is now placed within Prizm. Prizm is a modular data science solution for the entire energy sector. Python Tool Pro is now enabled to run in a remote (to Petrel) Python environment and, together with Hub, allows for programmatic access to Petrel. Version 2 of Python Tool Pro also includes changes to the namespace and the API. Some of these changes are not backward compatible with existing Python Tool Pro code.
Change of namespace#
To be consistent across the various Prizm modules and ensure a good user experience the Python namespace of Python Tool Pro has been changed from ‘blueback’ to ‘cegalprizm’. Python code written for Python Tool Pro v1.x will have to be adapted from
import blueback
from blueback.pythontool.grpc.petrelconnection import PetrelConnection
ptp = PetrelConnection()
to import from cegalprizm
import cegalprizm
from cegalprizm.pythontool import PetrelConnection
ptp = PetrelConnection()
Once the PetrelConnection is established, all other methods can be used from ‘ptp’ in the same way as the previous version. For any existing code using Python Tool Pro V1.x, which imports other classes than PetrelConnection, will also have to be adapted from the old ‘blueback’ namespace to cegalprizm. E.g.
from blueback.pythontool.welllog import WellLog
must be changed to
from cegalprizm.pythontool.welllog import WellLog
Hub implementation#
Python Tool Pro uses Hub to enable a connection between a Petrel project on a user’s workstation and any Python environment locally next to Petrel or remotely on a separate machine. In most scenarios, the user will establish a connection from the Hub Petrel plug-in to a Hub server. For more details, please check the Python Tool Pro ‘Getting Started’ section or the Hub documentation.
Backward incompatible API changes#
PetrelConnection moved to top-level#
The class PetrelConnection has been moved to the top-level of the Python API. Instead of using
import blueback
from blueback.pythontool.grpc.petrelconnection import PetrelConnection
users need to import the class from the top-level
import cegalprizm
from cegalprizm.pythontool import PetrelConnection
Removed borehole from API#
In previous versions the Python property ‘borehole’ was used as an alias for ‘well’. In Python Tool Pro only the property ‘well’ is available.
Removed get_rawvalues() from API#
In Python Tool Pro v1.x the method as_array() was introduced as an replacement for get_rawvalues(). In Python Tool Pro v2, get_rawvalues() has been removed, meaning that all Python scripts using the method get_rawvalues() need to be changed to as_array() to work with Python Tool Pro v2.
Removed discrete_properties and properties from API#
The properties ‘discrete_properties’ and ‘properties’ were removed from the PetrelConnection class in Python Tool Pro v2. Users should use ‘discrete_grid_properties’ and ‘grid_properties’ respectively, instead.
Changed .parent_surface to .surface#
To be consistent with other supported domain objects, the property parent_surface was renamed to surface. To get the surface object from a surface attribute object, users now need to use
surface_attribute.surface
Changed .parent_grid to .grid#
To be consistent with other supported domain objects, the property parent_grid was renamed to grid. To get the grid object from a continuous or discrete grid property object, users now need to use
grid_property.grid
discrete_grid_property.grid
Changed .parent_polylineset to .polylineset#
To be consistent with other supported domain objects, the property parent_polylineset was renamed to polylineset. To get the polylineset object from a polyline object, users now need to use
polyline.polylineset
Removed perforations from API#
The perforations() method has been removed from the well objects.
New functionality#
Create well logs from global well logs#
It is now possible to create a well log for a well from a global well log. This ensures that the new well log has an already existing template assigned to it.
Reconnect seismic cubes#
Seismic cubes with a broken link can be now reconnected. A seismic file path of the bulk file has to be passed as a string. This functionality only works for external seismic files and not for Petrel internal seismic.
Import workflows#
It is now possible to import Petrel workflows from a different Petrel project. The path of the Petrel project and the names of the Petrel workflow(s) are required.
Retrieve objects by GUID#
It is now possible to retrieve objects by passing a list of GUID (same as the .droid property). The method get_petrel_project_units() returns a dictionary with the Petrel project units.
- Example:
{‘Seismic time’: ‘ms’, ‘Z unit’: ‘m’, ‘Volume unit’: ‘m3’, ‘Area unit’: ‘m2’, ‘Seismic velocity’: ‘m/s’, ‘XY unit’: ‘m’}
Retrieve template information#
For all the domain objects with a template, it is now possible to retrieve the Petrel template of the object by using the Python property .template. Objects without a template will return an empty string.
Example:
welllog.template
Retrieve grid properties from grid#
It is now possible to retrieve the grid properties of a grid from the grid object. Use the grid.properties to get a readonly iterable collection of the grid properties for the grid. This will return the continuous and discrete grid properties together.
Changed functionality#
Updated method .retrieve_stats()#
In Python Too Pro v2, retrieve_stats() returns more information and now includes the min, max and delta for geographic extend and the values of the object.