DOCSEARCHbyAlgolia
Submit Docs

welleng: Well Engineering Toolkit

repository·main·Indexed 41 days ago

https://github.com/jonnymaserati/welleng

A specialized toolkit for Wells and Drilling Engineers focused on well trajectory design and analysis. It features ISCWSA and OWSG tool error models, a closed-form curve-hold-curve (CLC) solver for trajectory construction, and tools for calculating kick tolerance (including NOGEPA-50). The library supports streaming Landmark EDM/COMPASS and WITSML 1.4.1.1 data, as well as 3D visualization and mesh-based collision detection.

Tokens
60.7K
Snippets
153
Records
262
Agent score
49%

What's inside welleng

  1. Overview of welleng

    main
    welleng is a collection of tools designed for Wells and Drilling Engineers. Its primary focus is on well trajectory design and analysis, providing tools related to OWSG (Ocean Drilling Advisory Group) toolgroup workbooks and public reference data (ISCWSA / OWSG).

  3. Use the welleng.interpretation package for directional-survey interpretation

    main
    The welleng.interpretation package provides tools for the complete directional-survey interpretation workflow. It enables the transformation of raw sensor data into a survey, performs Quality Control (QC), executes Multi-Station Analysis (MSA), and handles correction-uncertainty propagation.

  4. Understand the structure of welleng published papers

    main

    The papers/ directory contains published research papers and the artifacts required to reproduce their results. The directory is organized as follows:

    • published/: Contains the Markdown source files for the papers and their corresponding .zenodo.json metadata files (linked to a Zenodo DOI).
    • figures/: Contains the visual figures used in the papers.
    • data/: Contains the validation data used to generate the results presented in the papers.
    • generate_*.py: Python scripts used to regenerate the figures and data from source.

  5. Explore the welleng package structure

    main

    The welleng package is organized into several subpackages and submodules designed for well engineering tasks.

    Subpackages

    • welleng.catalog: Likely manages data catalogs or reference datasets.
    • welleng.errors: Handles error-related logic or definitions.
    • welleng.exchange: Facilitates data exchange or interoperability.
    • welleng.interpretation: Provides tools for interpreting well data.
    • welleng.kick_tolerance: Specifically handles kick tolerance calculations and logic.

    Core Submodules

    Key functional areas are exposed through submodules including:

    • Physics & Mechanics: welleng.fluid, welleng.torque_drag, welleng.architecture, welleng.mesh.
    • Well Components: welleng.connector, welleng.node, welleng.surface, welleng.target.
    • Data & Environment: welleng.geomag (geomagnetic data), welleng.survey (well surveys), welleng.osdu (Open Subsurface Data Universe integration), welleng.units (unit conversions).
    • Analysis & Logic: welleng.acceptance, welleng.clearance, welleng.combination, welleng.composition, welleng.conditioning, welleng.error.

  6. Understand the source of catalogue data

    main

    The welleng catalogue provides dimensional and weight data for casing and tubing, extracted into an SI-ready schema. The data is based on industry standards (API Spec 5CT) and is provided as factual values rather than reproduced PDF text.

    Key data files include:

    • casing.json: Casing dimensional tables (OD, nominal weight, wall thickness, ID).
    • tubing.json: Tubing dimensional tables (OD, nominal weight, wall, ID).
    • couplings.json: Coupling dimensions (regular OD W, special-clearance OD Wc, minimum coupling length NL).
    • grades: Tensile properties (max yield, min UTS, min yield) based on API Spec 5CT.

  7. Combining and Forward-Carrying Overlapping Wellbore Surveys

    main

    This paper describes the implementation of two core methodologies within the welleng tool for handling overlapping wellbore surveys (e.g., combining MWD and Gyro surveys):

    1. Combination: Uses the Best Linear Unbiased Estimator (BLUE) to fuse two overlapping surveys into a single, continuous trajectory. This method is evaluated using an analytical arc-faithful interior covariance, ensuring the result is continuous in measured depth rather than being tied to discrete survey stations.
    2. Forward-carry: A technique where an independent overlapping reference (like a gyro) is used to constrain the systematic (magnetic) errors of another tool (like an MWD). Because these systematic errors persist down-hole, the constraint reduces the uncertainty (covariance) in the deeper, reference-free sections of the wellbore.

    Additionally, the implementation supports the covariance EOU (Ellipse of Uncertainty) approach, which treats the entire well as a single block covariance with off-diagonal cross-station correlation. This allows conditioning on a single station to propagate through the correlation and tighten the uncertainty for the entire run.

  8. Compose complex wellbores with SurveyComposition

    main

    Use SurveyComposition to tie together a wellbore's ordered survey sections. This is particularly useful when a wellbore has multiple survey sections, each with its own tool or error model (e.g., due to tool changes or restarts).

    Key Features:

    • Correlated Covariance: Systematic errors stay correlated within a single tool run but restart at tool changes.
    • Independence: Global geomagnetic errors carry per share-mode, and random errors correlate per error model.
    • Validation: Structural validation ensures that same-tool sections compose to be exactly equal to a single continuous survey, following ISCWSA error-model definitions (§4.7).
    # Conceptual usage of SurveyComposition
from welleng.survey import SurveyComposition

# Compose multiple survey sections into one wellbore
wellbore = SurveyComposition(sections=[section1, section2, section3])

  9. Handling small-angle exceptions in interior covariance

    main

    The welleng implementation of interior covariance correctly handles small-angle exceptions (such as those found in ISCWSA cross-axial and misalignment terms) by re-evaluating each term at the interior inclination.

    Instead of interpolating weights between stations—which can lead to inaccuracies or singularities near vertical inclinations—the implementation uses the same interpreter used at the stations. This ensures that position-space substitutions (like the Rayleigh-folded distribution used for transverse-sensor errors near vertical) are honored throughout the entire trajectory, preventing the over-statement of uncertainty at low inclinations.

  11. Configure temperature models for kick tolerance

    main

    The engine uses three tiers of temperature modeling to calculate kick tolerance (KT). The choice of model affects how conservative the result is:

    1. Isothermal (Basic): Assumes the entire well is at the bottom-hole temperature (BHT). This is the most conservative model because it assumes the gas is at its hottest/most expanded point everywhere, resulting in the lowest KT.
    2. Geothermal Gradient (Advanced): Uses a user-supplied geothermal gradient. This is more realistic and typically returns a higher (less conservative) KT than the isothermal model.
    3. Explicit Temperature Profile: An explicit profile takes precedence over both the geothermal gradient and the isothermal assumption.

    Resolution Logic: Explicit Profile > Geothermal Gradient > Isothermal at BHT.

  12. Calculate exact wellbore anti-collision boundaries

    main

    While the ISCWSA separation rule (Sawaryn et al., SPE-187073-MS) is a common conservative approximation for wellbore anti-collision, welleng provides an implementation of the exact combined-ellipsoid boundary.

    This implementation uses a mesh-free analytic Mahalanobis clearance to determine the exact boundary. It is designed to be efficient and can be used as a narrowphase check after a fast broadphase filter has been applied.

    Research Reference: DOI 10.5281/zenodo.20976872.