welleng

welleng is a collection of tools for Wells/Drilling Engineers, with a focus on well trajectory design and analysis.

Features

Survey listings — generate and interpolate well trajectories using minimum curvature or maximum curvature methods
Well bore uncertainty — ISCWSA MWD Rev4/Rev5 error models within 0.001% accuracy of ISCWSA test data; OWSG models also available
Clearance & Separation Factors — standard ISCWSA method (within 0.5% of ISCWSA test data) and mesh-based method using the Flexible Collision Library
Well path creation — the connector module builds trajectories between start/end locations automatically
Vertical section, TVD interpolation, project-ahead — common survey planning tools
Torque and drag — simple torque/drag model with architecture module
Visualization — interactive 3D via vedo/VTK or browser-based via plotly (requires easy install)
Data exchange — import/export Landmark .wbp files; read EDM datasets
World Magnetic Model — auto-calculates magnetic field data when not supplied

Available error models:

import welleng as we
we.error.get_error_models()

Support welleng

welleng is fuelled by copious amounts of coffee, so if you wish to supercharge development please donate generously:

Cloud API

A hosted API for 3D well path planning is available at welleng.org. Solve CLC (curve-line-curve) paths via simple REST calls — no local install, no GPU required.

Batch solving (up to 100K pairs)
GPU-accelerated
Free tier available

See the interactive docs to try it out.

Documentation

[Documentation] is available, though the library evolves quickly so the examples directory is often the best reference.

Tech

welleng uses a number of open source projects:

trimesh — loading and using triangular meshes
Flexible Collision Library — fast collision detection
numpy — scientific computing
scipy — mathematics, science, and engineering
vedo — 3D visualization based on VTK
[magnetic-field-calculator] — BGS magnetic field calculator API

Installation

The default install includes core dependencies (numpy, scipy, pandas, etc.) and covers survey generation, error models, and trajectory design. The easy extras add 3D visualization (vedo/VTK), magnetic field lookup, network analysis, and mesh import. The all extras add mesh-based collision detection, which requires compiled dependencies.

You'll receive an ImportError with a suggested install tag if a required optional dependency is missing.

Default install (core functionality, no visualization)

pip install welleng

Easy install (recommended — adds 3D visualization, magnetic field calculator, trimesh, networkx)

pip install welleng[easy]

Full install (adds mesh collision detection — requires compiled dependencies)

First install the compiled dependencies. On Ubuntu:

sudo apt-get update
sudo apt-get install libeigen3-dev libccd-dev octomap-tools

On macOS, use brew. On Windows, follow the FCL install instructions. Then:

pip install welleng[all]

Developer install

The project uses uv for dependency management:

git clone https://github.com/jonnymaserati/welleng.git
cd welleng
uv sync --all-extras

Or with plain pip:

pip install -e .[all]

Windows

On Windows, pip install welleng should work for the default and easy installs. For the full install with mesh collision detection, follow the FCL install instructions to set up the compiled dependencies first.

Colaboratory

For Google Colab, install dependencies with:

!apt-get install -y libeigen3-dev libccd-dev octomap-tools
!pip install welleng[easy] plotly

The VTK-based 3D viewer doesn't work in Colab, but plotly does. Here's a quick example:

import welleng as we
import plotly.graph_objects as go

# create a survey
s = we.survey.Survey(
    md=[0., 500., 2000., 5000.],
    inc=[0., 0., 30., 90],
    azi=[0., 0., 30., 90.]
)

# interpolate every 30 m
s_interp = s.interpolate_survey(step=30)

fig = go.Figure()
fig.add_trace(go.Scatter3d(
    x=s_interp.e, y=s_interp.n, z=s_interp.tvd,
    mode='lines', name='interpolated'
))
fig.add_trace(go.Scatter3d(
    x=s.e, y=s.n, z=s.tvd,
    mode='markers', marker=dict(color='red'), name='survey stations'
))
fig.update_scenes(zaxis_autorange="reversed")
fig.show()

Quick Start

Build a pair of well trajectories, compute error ellipses and clearance, and visualize (requires pip install welleng[all] for mesh clearance and visualization):

import welleng as we

# construct well paths
connector_reference = we.survey.from_connections(
    we.connector.Connector(
        pos1=[0., 0., 0.], inc1=0., azi1=0.,
        pos2=[-100., 0., 2000.], inc2=90, azi2=60,
    ),
    step=50
)
connector_offset = we.survey.from_connections(
    we.connector.Connector(
        pos1=[0., 0., 0.], inc1=0., azi1=225.,
        pos2=[-280., -600., 2000.], inc2=90., azi2=270.,
    ),
    step=50
)

# create surveys with error models
survey_reference = we.survey.Survey(
    md=connector_reference.md,
    inc=connector_reference.inc_deg,
    azi=connector_reference.azi_grid_deg,
    header=we.survey.SurveyHeader(name="reference", azi_reference="grid"),
    error_model='ISCWSA MWD Rev4'
)
survey_offset = we.survey.Survey(
    md=connector_offset.md,
    inc=connector_offset.inc_deg,
    azi=connector_offset.azi_grid_deg,
    start_nev=[100., 200., 0.],
    header=we.survey.SurveyHeader(name="offset", azi_reference="grid"),
    error_model='ISCWSA MWD Rev4'
)

# build well meshes
mesh_reference = we.mesh.WellMesh(survey_reference)
mesh_offset = we.mesh.WellMesh(survey_offset)

# calculate clearance
clearance_ISCWSA = we.clearance.IscwsaClearance(survey_reference, survey_offset)
clearance_mesh = we.clearance.MeshClearance(survey_reference, survey_offset, sigma=2.445)

# print minimum SF
print(f"Min SF (ISCWSA): {min(clearance_ISCWSA.sf):.2f}")
print(f"Min SF (mesh):   {min(clearance_mesh.sf):.2f}")

# visualize
lines = we.visual.get_lines(clearance_mesh)
plot = we.visual.Plotter()
plot.add(mesh_reference, c='red')
plot.add(mesh_offset, c='blue')
plot.add(lines)
plot.show()
plot.close()

This results in a quick, interactive visualization of the well meshes. What's interesting about these results is that the ISCWSA method does not explicitly detect a collision in this scenario whereas the mesh method does.

For more examples, including how to build a well trajectory by joining up a series of sections created with the welleng.connector module (see pic below), check out the examples and follow the [jonnymaserati] blog.

Well trajectory generated by [build_a_well_from_sections.py]

It's possible to generate data for visualizing well trajectories with welleng, as can be seen with the rendered scenes below. ISCWSA Standard Set of Well Paths

The ISCWSA standard set of well paths for evaluating clearance scenarios have been rendered in blender above. See the examples for the code used to generate a volve scene, extracting the data from the volve EDM.xml file.

License

Apache 2.0

Please note the terms of the license. Although this software endeavors to be accurate, it should not be used as is for real wells. If you want a production version or wish to develop this software for a particular application, then please get in touch with jonnycorcutt, but the intent of this library is to assist development.

[build_a_well_from_sections.py]: <https://github.com/jonnymaserati/welleng/tree/main/examples/build_a_well_fr

Welleng

Install / Use

README