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 Rev 5.11 error model (validated 35/35 sources against all three ISCWSA example workbooks), legacy Rev4 for back-compat, and OWSG gyro tool stacks (north-seeking stationary, mixed continuous, gyro-MWD) driven by the new ISCWSA JSON schema and an Excel-formula interpreter
- 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()
Error model update (welleng 0.10.0). The MWD Rev 5 model has been brought into compliance with the ISCWSA Rev 5.11 example workbooks. The
"ISCWSA MWD Rev5"string remains a selectable alias with aDeprecationWarningpointing at the new"ISCWSA MWD Rev5.11"name, but produces the corrected Rev 5.11 covariance (slightly different numerical output to welleng ≤ 0.9.x)."ISCWSA MWD Rev4"is unchanged for users who need to reproduce older results. Seewelleng/errors/iscwsa_validate.pyfor the validation harness used to audit against each ISCWSA example workbook.
Gyro support + JSON-driven tool models (welleng 0.11.0). ISCWSA is moving its error-model standard from the legacy Excel workbooks to a machine-readable JSON schema at
iscwsa/error-models. welleng 0.11 ships ahead of that transition: a vendored copy of the schema (pinned to upstream SHAc7af784atwelleng/errors/iscwsa_schema/), a ~95-line Excel-formula interpreter atwelleng/errors/interpreter.py, and the full OWSG Set A library (~100 tool models, including the gyro stacks) generated as ISCWSA JSON atwelleng/errors/iscwsa_json/owsg_a/. Use them viaSurvey(error_model='GYRO-NS' | 'GYRO-NS-CT' | 'GYRO-MWD' | 'MWD+SRGM' | ...). Seeexamples/gyro_survey_example.pyfor a side-by-side MWD/gyro position-uncertainty comparison.The legacy hand-coded MWD path is untouched — the canonical strings (
'ISCWSA MWD Rev4','ISCWSA MWD Rev5','ISCWSA MWD Rev5.11') still route through the production engine, so existing users see no behaviour change unless they opt in to a JSON-driven tool name.
Parallel-paths conformance harness. Every term that exists in both the legacy hand-coded dispatcher and the new JSON+interpreter path is diff-tested at machine precision in CI (
tests/test_iscwsa_json_conformance.py). The harness also catalogues schema gaps it surfaces — terms that don't evaluate against the current draft schema (cross-station references likeMDPrev/AzPrev/IncPrev, per-tool calibration constants likeNoiseReductionFactor). Runpython -m welleng.errors.conformance --summaryfor the agreement matrix. Findings are filed upstream as schema-feedback on the ISCWSA Discussions board.
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
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.
Metadata
Release files for welleng 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| welleng-0.12.0.tar.gz | 158.5 kB | With provenance | Details for welleng-0.12.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| welleng-0.12.0-py3-none-any.whl | Python 3 | none | any | Details for welleng-0.12.0-py3-none-any.whl |
Total release size: 390.0 kB
Release files / welleng-0.12.0.tar.gz
| Download URL | welleng-0.12.0.tar.gz |
|---|---|
| Size | 158.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f32913da3ceabd72e6b4a2bff1b81ff7d53d09409ece94e07f8370c77589621f
|
|
BLAKE2b-256 checksum How to use checksums |
cb22df40245c800850996be9adfcb7db01e6b9091dd5b0a3a9421578905fb125
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.
Transparency logRelease files / welleng-0.12.0-py3-none-any.whl
| Download URL | welleng-0.12.0-py3-none-any.whl |
|---|---|
| Size | 231.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fabd6cc687e90efe3238e1093685f315b5c3f4fe52936aee6cb5cd0a435fec77
|
|
BLAKE2b-256 checksum How to use checksums |
00ad71755a49da9edbd2ba3aa7590b26aedc9708ded9cc8923f69c67dade1c62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.
Transparency logSecurity for welleng 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for welleng-0.12.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.