gea-program 0.48.0__tar.gz → 0.50.0__tar.gz

{gea_program-0.48.0 → gea_program-0.50.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.48.0
+Version: 0.50.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -648,6 +648,37 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Plan vs actual and the survey tools
+
+Each well against its directional plan: at every survey station, how far
+it is from the plan - high or low, right or left, in the plan's own frame -
+against the survey's own uncertainty in that direction; the bit projected
+below the last survey; the one arc back to the plan, with its dogleg
+severity and toolface. Each well's survey program names the tool that
+surveyed each run, weighed by the ISCWSA MWD Rev 5.11 model (checked
+against all 144 rows of the ISCWSA's own Rev 5 example) or one of 21 OWSG
+tool-code models on its weighting functions - MWD and EMS with the standard,
+high- or low-resolution geomagnetic model or in-field referencing. Wells not
+yet drilled are checked for collision along their plans, a well being
+drilled along its survey and then its plan, and the Collision tab draws the
+travelling cylinder. The **Plan vs actual** tab, `gea plan`, `gea help plan`.
+
+### Well collision checks
+
+Every well scanned against every other: at each point of one well, the
+closest point of the other, and the ISCWSA separation factor - the distance
+between them less the holes and a surface margin, over k times the
+uncertainty of that distance. Each well's position uncertainty comes from
+the ISCWSA MWD Rev 4 error model (27 error sources, propagated as the model
+says, the errors two wells share taken out of the distance between them),
+checked against all 112 rows of the ISCWSA's own example; the Earth's field
+at each well comes from the World Magnetic Model 2025. Each pair is levelled
+as the ISCWSA's separation rule does - reported below 4.0, the approach
+limit below 1.5, revise the plan below 1.25, below 1.0 only by the
+operator's dispensation - with a company standard's k and margin kept with
+its source. The Volve template's three wells are the worked example. The
+**Collision** tab, `gea collision`, `gea help collision`.
+
 ### One record, tied together
 
 The invoice check, rig time, the daily summary, the alerts, the signed

{gea_program-0.48.0 → gea_program-0.50.0}/README.md

@@ -609,6 +609,37 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Plan vs actual and the survey tools
+
+Each well against its directional plan: at every survey station, how far
+it is from the plan - high or low, right or left, in the plan's own frame -
+against the survey's own uncertainty in that direction; the bit projected
+below the last survey; the one arc back to the plan, with its dogleg
+severity and toolface. Each well's survey program names the tool that
+surveyed each run, weighed by the ISCWSA MWD Rev 5.11 model (checked
+against all 144 rows of the ISCWSA's own Rev 5 example) or one of 21 OWSG
+tool-code models on its weighting functions - MWD and EMS with the standard,
+high- or low-resolution geomagnetic model or in-field referencing. Wells not
+yet drilled are checked for collision along their plans, a well being
+drilled along its survey and then its plan, and the Collision tab draws the
+travelling cylinder. The **Plan vs actual** tab, `gea plan`, `gea help plan`.
+
+### Well collision checks
+
+Every well scanned against every other: at each point of one well, the
+closest point of the other, and the ISCWSA separation factor - the distance
+between them less the holes and a surface margin, over k times the
+uncertainty of that distance. Each well's position uncertainty comes from
+the ISCWSA MWD Rev 4 error model (27 error sources, propagated as the model
+says, the errors two wells share taken out of the distance between them),
+checked against all 112 rows of the ISCWSA's own example; the Earth's field
+at each well comes from the World Magnetic Model 2025. Each pair is levelled
+as the ISCWSA's separation rule does - reported below 4.0, the approach
+limit below 1.5, revise the plan below 1.25, below 1.0 only by the
+operator's dispensation - with a company standard's k and margin kept with
+its source. The Volve template's three wells are the worked example. The
+**Collision** tab, `gea collision`, `gea help collision`.
+
 ### One record, tied together
 
 The invoice check, rig time, the daily summary, the alerts, the signed

{gea_program-0.48.0 → gea_program-0.50.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.48.0"
+__version__ = "0.50.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.48.0 → gea_program-0.50.0}/gea/__main__.py

@@ -590,6 +590,38 @@ def main(argv=None) -> int:
     p_dz.add_argument("--actor", type=str, default="cli")
     p_dz.add_argument("--json", action="store_true")
 
+    p_co = sub.add_parser("collision", help="every well scanned against every other: the closest approach and the ISCWSA separation factor, each well's position uncertainty by the ISCWSA MWD model and the field by WMM2025")
+    p_co.add_argument("--workspace", type=str, default=None)
+    p_co.add_argument("--scene", type=str, default=None, help="workspace (your wells) or volve (the worked example)")
+    p_co.add_argument("--write", action="store_true", help="write the client report")
+    p_co.add_argument("--k", type=str, default=None, help="declare the rule's scaling factor")
+    p_co.add_argument("--surface-margin", type=str, default=None, help="declare the surface margin, m")
+    p_co.add_argument("--sigma-pa", type=str, default=None, help="declare the project-ahead uncertainty, m")
+    p_co.add_argument("--source", type=str, default="", help="where the rule's values came from")
+    p_co.add_argument("--well", type=str, default=None)
+    p_co.add_argument("--hole", type=str, default=None, help="with --well: the hole size in inches ('' removes it)")
+    p_co.add_argument("--field", type=str, default=None, help="the magnetic field at LAT,LON[,YYYY-MM-DD] by WMM2025, and nothing else")
+    p_co.add_argument("--actor", type=str, default="cli")
+    p_co.add_argument("--json", action="store_true")
+
+    p_pl = sub.add_parser("plan", help="a well against its plan: the distance high/low and right/left at each survey, the bit projected, the arc back to the plan; the survey program's tool models")
+    p_pl.add_argument("--workspace", type=str, default=None)
+    p_pl.add_argument("--well", type=str, default=None)
+    p_pl.add_argument("--attach", type=str, default=None, help="attach FILE as the well's plan (CSV, Excel or WITSML)")
+    p_pl.add_argument("--azimuth-reference", type=str, default=None, help="with --attach: true, grid or magnetic")
+    p_pl.add_argument("--md-unit", type=str, default="ft", help="with --attach: ft or m")
+    p_pl.add_argument("--grid", type=str, default=None, help="with a grid azimuth reference: the grid (e.g. UTM14N)")
+    p_pl.add_argument("--declination", type=str, default=None, help="with a magnetic azimuth reference: the declination used")
+    p_pl.add_argument("--remove", action="store_true", help="take the well's plan off it")
+    p_pl.add_argument("--program", type=str, default=None, help="the survey program: 'MWD+SRGM' or '0-1500:MWD+SRGM, 1500-:MWD+IFR1' (metres)")
+    p_pl.add_argument("--bit-offset", type=str, default=None, help="survey sensor to bit, m")
+    p_pl.add_argument("--lookahead", type=str, default=None, help="how far ahead the arc back rejoins the plan, m")
+    p_pl.add_argument("--source", type=str, default="", help="where the plan or the program came from")
+    p_pl.add_argument("--models", action="store_true", help="list the tool models")
+    p_pl.add_argument("--write", action="store_true", help="write the well's report")
+    p_pl.add_argument("--actor", type=str, default="cli")
+    p_pl.add_argument("--json", action="store_true")
+
     p_rt = sub.add_parser("rig-time", help="what the rig did each second of the drilling record - drilling, connections, trips, the slips - and the time lost against the pad's own best")
     p_rt.add_argument("--workspace", type=str, required=True)
     p_rt.add_argument("--well", type=str, default=None, help="with --write: one well's report (without it, the pad's)")
@@ -2372,6 +2404,85 @@ def main(argv=None) -> int:
         print(f"  {os.path.join(ws.reports_dir, e['path'])}")
         print(f"  key fingerprint {e['fingerprint']}")
         return 0
+    elif a.cmd == "collision":
+        import json as _json
+        from . import collision as _CO
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            if a.field:
+                from . import geomag as _GM
+                parts = [x.strip() for x in a.field.split(",")]
+                f_ = _GM.field(float(parts[0]), float(parts[1]), 0.0, parts[2] if len(parts) > 2 else None)
+                print(f"{f_['model']} at {float(parts[0]):.4f}, {float(parts[1]):.4f} for {f_['decimal_year']:.2f}: declination {f_['declination_deg']:+.3f} deg, "
+                      f"dip {f_['dip_deg']:.3f} deg, total {f_['total_nT']:,.1f} nT" + (f" ({f_['note']})" if f_['note'] else ""))
+                return 0
+            ws = Workspace(a.workspace) if a.workspace else None
+            if ws is not None and (a.k is not None or a.surface_margin is not None or a.sigma_pa is not None or a.hole is not None):
+                if a.hole is not None and not a.well:
+                    raise ValueError("--hole needs --well")
+                s_ = _CO.set_settings(ws, a.actor, a.k, a.surface_margin, a.sigma_pa, (a.well, a.hole) if a.hole is not None else None, a.source)
+                print(f"rule: k {s_['k']:g}, surface margin {s_['surface_margin_m']:g} m, project-ahead {s_['sigma_pa_m']:g} m; holes: "
+                      + (", ".join(f"{k} {v:g} in" for k, v in s_['holes_in'].items()) or "8.5 in by default"))
+                return 0
+            scene = a.scene or ("workspace" if ws is not None else "volve")
+            if a.write:
+                if ws is None:
+                    raise ValueError("--write needs --workspace")
+                r_ = _CO.write_report(ws, __version__, a.actor, scene)
+                print(f"wrote {r_['report_id']}: {r_['paths']['html']}")
+                if r_['paths'].get('pdf'):
+                    print(f"  printable: {r_['paths']['pdf']}")
+                return 0
+            r = _CO.page(ws, scene)
+        except (KeyError, ValueError, OSError, WorkspaceError) as e:
+            raise SystemExit(f"collision: {e.args[0] if e.args else e}")
+        print(_json.dumps({k: v for k, v in r.items()}, default=str) if a.json else _CO.text(r))
+        return 0
+    elif a.cmd == "plan":
+        import json as _json
+        from . import wellplan as _PL
+        from . import wellpos as _WP
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            if a.models:
+                for m_ in _WP.model_list():
+                    print(f"{m_['name']:<18} {m_['id']:<14} {m_['terms']:>2} terms  {m_['family']:<10} {m_['long_name']}" + ("  (default)" if m_['default'] else ""))
+                return 0
+            if not a.workspace:
+                raise ValueError("--workspace is needed")
+            ws = Workspace(a.workspace)
+            if (a.attach or a.remove or a.program or a.bit_offset is not None or a.lookahead is not None or a.write) and not a.well:
+                raise ValueError("--well is needed")
+            if a.attach:
+                with open(a.attach, "rb") as f_:
+                    r_ = _PL.attach(ws, a.well, os.path.basename(a.attach), f_.read(), a.actor, a.azimuth_reference or "", a.md_unit, a.grid,
+                                    float(a.declination) if a.declination else None, a.source)
+                print(f"plan attached to {a.well}: {r_['stations']} stations, {r_['md_range_m'][0]:,.1f} to {r_['md_range_m'][1]:,.1f} m MD ({r_['azimuth_reference']} north)")
+                return 0
+            if a.remove:
+                _PL.remove(ws, a.well, a.actor)
+                print(f"plan removed from {a.well}")
+                return 0
+            if a.program or a.bit_offset is not None or a.lookahead is not None:
+                s_ = _PL.set_well(ws, a.actor, a.well, _PL.parse_program(a.program) if a.program else None, a.bit_offset, a.lookahead, a.source)
+                print(f"{a.well}: " + ", ".join(f"{p_['model']} to {p_['to_md_m']:,.0f} m" if p_['to_md_m'] is not None else f"{p_['model']} to TD" for p_ in s_['program'])
+                      + f"; the bit {s_['bit_offset_m']:g} m below the survey sensor; back to the plan {s_['lookahead_m']:g} m ahead")
+                return 0
+            if a.write:
+                r_ = _PL.write_report(ws, __version__, a.well, a.actor)
+                print(f"wrote {r_['report_id']}: {r_['paths']['html']}")
+                if r_['paths'].get('pdf'):
+                    print(f"  printable: {r_['paths']['pdf']}")
+                return 0
+            r = _PL.page(ws, a.well)
+        except (KeyError, ValueError, OSError, WorkspaceError) as e:
+            raise SystemExit(f"plan: {e.args[0] if e.args else e}")
+        print(_json.dumps(r, default=str) if a.json else _PL.text(r))
+        return 0
     elif a.cmd == "rig-time":
         import json as _json
         from . import rig_state as _RS