welleng is a collection of tools for Wells/Drilling Engineers, with a focus on well trajectory design and analysis.
- 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
connectormodule 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
easyinstall) - 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()welleng is fuelled by copious amounts of coffee, so if you wish to supercharge development please donate generously:
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 is available, though the library evolves quickly so the examples directory is often the best reference.
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
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.
pip install welleng
pip install welleng[easy]
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]
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]
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.
For Google Colab, install dependencies with:
!apt-get install -y libeigen3-dev libccd-dev octomap-tools
!pip install welleng[easy] plotlyThe 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()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.
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.