welltraj

Full well trajectory design and analysis library for oil & gas directional drilling.

Features

• Minimum curvature method — industry-standard survey computation (MD/INC/AZI → TVD/N/E/VS)
• Survey interpolation — interpolate at any MD, TVD, or VS; forward/backward extrapolation
• Trajectory design — build complete trajectories from KOP, build rate, and target (TVD + VS)
• Segment builder — fluent API: .vertical().build().hold().drop().turn()
• Multi-objective Pareto optimization — minimize MD, tortuosity, and collision risk simultaneously; knee-point selection
• Survey vs plan comparison — left/right, above/below, ahead/behind, centre-to-centre distance
• Anti-collision — separation factor scanning, ISCWSA MWD uncertainty ellipses
• Constraint validation — max DLS, max inclination, max MD, target tolerance
• I/O — parse CSV, JSON, LAS 2.0, WITSML-style tab files; export CSV, JSON, Markdown reports
• Visualization — 2D/3D Plotly.js charts (plan view, vertical section, DLS profile, Pareto front) and Three.js 3D renderer
• ES6 modules — tree-shakeable ESM + CJS + UMD builds

---

Installation

npm install welltraj

Optional visualization peer dependencies:

npm install plotly.js-dist   # for PlotlyRenderer
npm install three             # for ThreeRenderer

---

Quick Start

import { Survey } from 'welltraj';

const survey = new Survey({ name: 'DEMO-01', vsAzimuth: 45 });
survey.setStations([
  { md:    0, inc:  0, azi: 45 },
  { md:  500, inc:  0, azi: 45 },
  { md: 1200, inc: 30, azi: 45 },
  { md: 2000, inc: 60, azi: 47 },
  { md: 3000, inc: 90, azi: 47 },
]);

// Computed coordinates
console.log(survey.get(-1));      // last station
console.log(survey.atMD(1600));   // interpolated at MD 1600
console.log(survey.stats());      // summary statistics
console.log(survey.toCSV());      // export

---

API Reference

Core

new Survey(options?)

Option	Type	Default	Description
name	string	'Unnamed Well'	Well name
vsAzimuth	number	0	Vertical section reference azimuth (°)
origin	{tvd, north, east}	{0,0,0}	Starting coordinates

Methods:

Method	Returns	Description
setStations(stations)	Survey	Replace all stations (chainable)
addStation(md, inc, azi)	Survey	Append one station
get(i)	SurveyResult	Get result at index (negative = from end)
getAll()	SurveyResult[]	All computed results
atMD(md)	SurveyResult	Interpolate at measured depth
atTVD(tvd)	SurveyResult	Find point at TVD
atVS(vs)	SurveyResult	Find point at vertical section
stats()	Object	Trajectory statistics
toCSV(options?)	string	Export as CSV
toJSON()	Object	Export as JSON
Survey.fromCSV(text, options?)	Survey	Parse CSV
Survey.fromJSON(data, options?)	Survey	Parse JSON

SurveyResult fields: md, inc, azi, tvd, north, east, vs, dls, dl, closure, closureAzi

---

Design

SegmentBuilder

import { SegmentBuilder } from 'welltraj';

const survey = new SegmentBuilder({ azimuth: 45, mdStep: 10 })
  .vertical(500)          // drill straight to 500m MD
  .build(90, 3)           // build to 90° at 3°/30m
  .hold(1500)             // 1500m horizontal section
  .toSurvey({ name: 'My Well' });

Methods: .vertical(length) · .build(targetInc, buildRate) · .drop(targetInc, dropRate) · .hold(length) · .turn(targetAzi, turnRate) · .station(md, inc, azi) · .toSurvey(options?) · .getStations()

TrajectoryDesigner

import { TrajectoryDesigner } from 'welltraj';

const survey = new TrajectoryDesigner({
  kop: 500, azimuth: 45, buildRate: 3,
  target: { tvd: 3200, vs: 1800 }
}).design();

Optimizer

import { Optimizer } from 'welltraj';

const { front, knee, all } = new Optimizer({
  baseOptions: { azimuth: 45, target: { tvd: 3200, vs: 1800 } },
  buildRates:  [2, 3, 4, 5],
  kopValues:   [300, 500, 700, 1000]
}).run();

console.log(`Knee point: KOP=${knee.params.kop}, buildRate=${knee.params.buildRate}`);

---

Analysis

Survey vs Plan Comparison

import { compareSurveys, landingAccuracy } from 'welltraj';

const cmp = compareSurveys(actualSurvey, planSurvey);
// cmp[i].leftRight, .aboveBelow, .aheadBehind, .ctc

const accuracy = landingAccuracy(actualSurvey, { tvd: 3200, north: 1200, east: 1200 });

Anti-Collision

import { scanAntiCollision, minSeparationFactor } from 'welltraj';

const records = scanAntiCollision(designSurvey, offsetWells);
const { sf } = minSeparationFactor(designSurvey, offsetWells);
console.log(`Min SF: ${sf.toFixed(3)}`);   // >= 1.5 is safe

Constraints

import { validate, passes } from 'welltraj';

const violations = validate(survey, {
  maxDLS: 5,        // °/30m
  maxInc: 92,       // °
  maxMD:  6000,
  targetTVD: 3200,
  targetTolerance: 20
});

---

I/O

import { parse, surveyTable, statsSummary } from 'welltraj';

// Auto-detect format
const survey = parse(csvOrJsonString, { name: 'My Well', vsAzimuth: 45 });

// Reports
console.log(surveyTable(survey));
console.log(statsSummary(survey));

---

Visualization

import Plotly from 'plotly.js-dist';
import { PlotlyRenderer } from 'welltraj';

const r = new PlotlyRenderer(Plotly);
r.plot3D('container-id', [survey]);
r.plotVerticalSection('vs-div', [actualSurvey, planSurvey]);
r.plotDLS('dls-div', [survey], { maxDLS: 5 });

---

Low-level functions

All core computations are also exported as standalone functions:

import { dogleg, doglegSeverity, ratioFactor, segment, compute } from 'welltraj';

const dl  = dogleg(0, 45, 30, 47);          // degrees
const dls = doglegSeverity(0, 45, 30, 47, 300); // °/30m
const seg = segment({ md: 0, inc: 0, azi: 0 }, { md: 300, inc: 30, azi: 45 });
// seg: { dTVD, dNorth, dEast, dls, dl }

---

Examples

node examples/01-basic-survey.js
node examples/02-trajectory-design.js
node examples/03-anti-collision.js
node examples/04-pareto-optimization.js

---

Tests

npm test

---

Build

npm run build   # produces dist/welltraj.esm.js, .cjs.js, .umd.js

---

License

MIT © Ismail Harkat "# welltraj"