Run residuals at wells

A residual at a well is how far a formation top lies from the place where the wellbore crosses a surface: the top’s measured depth minus the measured depth of the crossing, in metres. Ophiolite computes residuals on your computer from exact versions in your project. The run writes residuals.json into a new folder and publishes nothing; you decide afterwards whether to publish it.

You need, in one project:

• a saved well set: your own list of wellbores, each with the trajectory version that places it and the frame that says where it starts and how it is oriented;
• the tops of those wellbores, one tops version linked to each wellbore, with depths in metres measured from the same depth datum as its trajectory;
• a grid surface of the formation you compare with, such as a depth horizon;
• a residual tool in the project’s catalogue. Residual at wells (residual-at-wells) ships with the SDK; the next section adds it, and Write and run a tool says more about how a tool is added and enabled.

Add Residual at wells to your project

The tool’s folder is part of the installed SDK. Register that folder in your project, then have a project administrator enable its version for everyone, in Settings → Tools in the Workspace or from the command line:

ophiolite procedures register "$(python -c 'from ophiolite import residuals; print(residuals.REFERENCE)')"
ophiolite procedures enable residual-at-wells --version 1

Until a version is enabled, a run is refused with “Not run: Residual at wells has no enabled version in this project. A project administrator enables one in Settings → Tools or with ophiolite tools enable.” A newer SDK may ship a newer version; register it the same way and enable the version it reports.

Save a well selection

In the Workspace, open your project’s data and choose Well sets. Pick wellbores from the tree of wells, or draw an area on the Map and add the wellbores of the wells inside it. Where a wellbore has more than one trajectory version, choose one. For each chosen trajectory, state where it starts and how it is oriented: the map coordinate system, the wellhead east and north, the depth reference and its height above the datum, which north the survey directions use, and the angle to the map grid. Then save the set.

If you do not know a trajectory’s frame yet, leave all of its inputs blank (Leave the frame blank clears them): the page says “This will be saved without a frame.” and, once saved, lists those wellbores under “Saved without a frame.” The wellbore stays in the set but cannot be placed: a run that reaches it is refused at that member, whether or not it has a top. Open the set again, fill in the frame and save; the next version is placed.

A well set stays private to you. Saving it again after a change adds its next version, and a run always names one exact version. From Python, client.well_sets.from_list builds the set from wellbores and client.well_sets.save saves it; from_list still needs a frame for every trajectory you choose.

Run residuals

Name the tool, the exact well set version, the exact surface version and the formation as your tops name it. Each version is @ASSET:REVISION; a result’s page shows both under Technical details. Replace SET, SURFACE and each REVISION below with yours.

ophiolite residuals run residual-at-wells --selection @SET:REVISION \
  --surface @SURFACE:REVISION --formation DCC --output dcc-residuals

Before anything is computed, Ophiolite binds your inputs and refuses with one sentence when something does not fit, for example:

• “No selected wellbore has a top named “DCC”.”
• “No selected wellbore has a trajectory, so there is nothing to intersect.”
• “Two tops sets are linked to SAP-10; keep one link.”
• “Member 3: its tops are measured from NAP but its trajectory from KB; a residual needs one depth datum.”
• “Member 2: The wellbore’s trajectory was saved without a frame (map system, wellhead, depth reference, datum and north), so it cannot be placed; save the well set again with its frame.”

When the inputs fit, the tool runs on your computer and writes the new folder:

Ran Residual at wells, version 1, on this computer: made Residual result (JSON) (dcc-residuals/residuals.json). Nothing was published.

The folder holds residuals.json, run.json (the version, the settings and every input it read) and log.txt. --output must name a folder that does not exist yet.

• --display-unit ft shows depths in feet; the result keeps its values in metres either way.
• --version N runs one version of the tool; by default the newest you may run.
• The first time you run a version you did not add, Ophiolite asks first. --yes answers that question where nobody can, such as in a script.
• --json prints the documented JSON result instead of the sentence.

Read the rows

The result has one row per top of the formation on each selected wellbore. A row has a residual, or a reason it was not computed. Rows not computed are part of the result, not errors:

The row says	What it means
Not computed: this wellbore has no top of the chosen formation.	The wellbore’s tops do not name the formation.
Not computed: this wellbore has no trajectory in the selection.	The well set saved this wellbore without a trajectory.
Not computed: the path ends above the surface.	The trajectory stops before it reaches the surface.
Not computed: the path starts below the surface.	The trajectory begins under the surface.
Not computed: the surface has no data where the path would cross it.	The grid has no value there.
Not computed: a crossing is possible between a m and b m but could not be proven.	The path and the surface come too close to decide.
Not computed: the path comes within 0.01 m of the surface from a m to b m, and no crossing is proven.	The path grazes the surface.
Not computed: the path runs within 0.01 m of the surface from a m to b m, and no crossing is proven.	The path runs along the surface.
Not computed: the path crosses the surface more than 64 times between a m and b m.	Too many crossings to pick one.

Where a top has a crossing, the residual uses the crossing nearest the top.

For example, the Groningen residual wellbores (source: NLOG.NL) compare the top of the Carboniferous (DCC) with the base of the Upper Rotliegend Group from the DGM-deep model. Seven wellbores give five residuals between −1.28 m and 2.80 m, one row “Not computed: this wellbore has no top of the chosen formation.” and one row “Not computed: this wellbore has no trajectory in the selection.”

Publish and accept the result

A residual result is published from its run, as any tool run is:

ophiolite procedures publish dcc-residuals --name "Residuals DCC"

The project checks the run again before it keeps anything, and the result is private to you. To declare what your project accepts for a residual result, read whether each version is accepted, and deliver only what was accepted, see Accept results with outcomes.