gea-program 0.40.0__tar.gz → 0.42.0__tar.gz

{gea_program-0.40.0 → gea_program-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.40.0
+Version: 0.42.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,43 @@ 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`.
 
+### Operations and seismicity
+
+The Operations & Seismicity tab sets each well's drilling, completion and
+disposal windows against the earthquake catalogue around it: every event
+within the screening distance by its distance and time, whether it fell
+during an operation or in the months after, what the rig was doing when a
+drilling record covers it, the level a regulator's protocol would reach
+(British Columbia, Alberta, Oklahoma, Ohio, Texas, each with its
+document), and the exact test of whether the rate near the well is higher
+while it works than in the rest of the record. The Mahoning Valley, Ohio -
+the 2011 Youngstown sequence against the Northstar 1 injection year, the
+2014 Poland Township events against a stimulation - ships as a worked
+example from the public record. `gea seismicity`, `gea help opseis`.
+
+### The declarations sheet
+
+Everything the operator declares about a pad comes in from one spreadsheet:
+each well's API number, position and reference elevation, its directional
+survey, the day rates, one-off costs and AFE, the fleet, the drill-string
+runs and their components, and the ESP penetrator and drive. Every row is
+checked against the workspace and planned NEW, CHANGE or SAME before
+anything is written; one error and nothing is. The sheet the program writes
+for a workspace is already filled with what is declared, so a site fills in
+the blanks. On the Setup tab, or `gea declare --template`, `gea declare
+--file`, `gea help declare`.
+
+### Completion - the ESP wellhead penetrator
+
+The Completion tab keeps each ESP well's penetrator installation record -
+the installer and their certification, the motor, the gauge distance, the
+insulation readings, the void test - and checks the well's ESP drive, motor
+nameplate and wellhead against the penetrator's ratings as its maker's
+document prints them, one line each: voltage, current, frequency, phases,
+hazardous area, gas group, temperature class, ambient range and altitude.
+It carries the permanent magnet motor safety note with its sources.
+`gea penetrator`, `gea help penetrator`.
+
 ### Drill string
 
 The Drill String tab holds each run's string from the bit up - drawn as a
@@ -657,7 +694,7 @@ its declared service interval. The downhole motor tracker charts the
 differential against the maker's limits, the stalls, the motor's and the
 bit's speed and a torque estimate, and judges the motor's stability from
 the slow oscillations of the torque and the differential, block by block.
-The tool catalogue carries 41 downhole motors with the maker's figures.
+The tool catalogue carries 43 downhole motors with the maker's figures.
 `gea drillstring`, `gea tools --action motors`, `gea help drillstring`.
 
 ### Simulation
@@ -785,7 +822,7 @@ library**: every class of downhole tool in use across the industry - bits
 and hole openers, motors and rotary steerable systems, MWD and LWD, the drill
 string and its subs, casing and cementing equipment, completion and
 artificial lift, wireline and cased-hole tools, fishing and milling, test
-tools - ninety-six classes in nine categories. Point at a tool, or Tab to
+tools - ninety-seven classes in nine categories. Point at a tool, or Tab to
 it, for a one-line description; click, tap or press Enter for its tutorial:
 what it is, where it runs, how it works, what it shows in the data, what to
 watch, and what this program does with it, with the published figures

{gea_program-0.40.0 → gea_program-0.42.0}/README.md

@@ -609,6 +609,43 @@ 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`.
 
+### Operations and seismicity
+
+The Operations & Seismicity tab sets each well's drilling, completion and
+disposal windows against the earthquake catalogue around it: every event
+within the screening distance by its distance and time, whether it fell
+during an operation or in the months after, what the rig was doing when a
+drilling record covers it, the level a regulator's protocol would reach
+(British Columbia, Alberta, Oklahoma, Ohio, Texas, each with its
+document), and the exact test of whether the rate near the well is higher
+while it works than in the rest of the record. The Mahoning Valley, Ohio -
+the 2011 Youngstown sequence against the Northstar 1 injection year, the
+2014 Poland Township events against a stimulation - ships as a worked
+example from the public record. `gea seismicity`, `gea help opseis`.
+
+### The declarations sheet
+
+Everything the operator declares about a pad comes in from one spreadsheet:
+each well's API number, position and reference elevation, its directional
+survey, the day rates, one-off costs and AFE, the fleet, the drill-string
+runs and their components, and the ESP penetrator and drive. Every row is
+checked against the workspace and planned NEW, CHANGE or SAME before
+anything is written; one error and nothing is. The sheet the program writes
+for a workspace is already filled with what is declared, so a site fills in
+the blanks. On the Setup tab, or `gea declare --template`, `gea declare
+--file`, `gea help declare`.
+
+### Completion - the ESP wellhead penetrator
+
+The Completion tab keeps each ESP well's penetrator installation record -
+the installer and their certification, the motor, the gauge distance, the
+insulation readings, the void test - and checks the well's ESP drive, motor
+nameplate and wellhead against the penetrator's ratings as its maker's
+document prints them, one line each: voltage, current, frequency, phases,
+hazardous area, gas group, temperature class, ambient range and altitude.
+It carries the permanent magnet motor safety note with its sources.
+`gea penetrator`, `gea help penetrator`.
+
 ### Drill string
 
 The Drill String tab holds each run's string from the bit up - drawn as a
@@ -618,7 +655,7 @@ its declared service interval. The downhole motor tracker charts the
 differential against the maker's limits, the stalls, the motor's and the
 bit's speed and a torque estimate, and judges the motor's stability from
 the slow oscillations of the torque and the differential, block by block.
-The tool catalogue carries 41 downhole motors with the maker's figures.
+The tool catalogue carries 43 downhole motors with the maker's figures.
 `gea drillstring`, `gea tools --action motors`, `gea help drillstring`.
 
 ### Simulation
@@ -746,7 +783,7 @@ library**: every class of downhole tool in use across the industry - bits
 and hole openers, motors and rotary steerable systems, MWD and LWD, the drill
 string and its subs, casing and cementing equipment, completion and
 artificial lift, wireline and cased-hole tools, fishing and milling, test
-tools - ninety-six classes in nine categories. Point at a tool, or Tab to
+tools - ninety-seven classes in nine categories. Point at a tool, or Tab to
 it, for a one-line description; click, tap or press Enter for its tutorial:
 what it is, where it runs, how it works, what it shows in the data, what to
 watch, and what this program does with it, with the published figures

{gea_program-0.40.0 → gea_program-0.42.0}/gea/__init__.py

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

{gea_program-0.40.0 → gea_program-0.42.0}/gea/__main__.py

@@ -524,6 +524,48 @@ def main(argv=None) -> int:
     p_ds.add_argument("--actor", type=str, default="cli")
     p_ds.add_argument("--json", action="store_true")
 
+    p_dc = sub.add_parser("declare", help="the declarations sheet: wells' identity, position and elevation, surveys, rates, items and AFEs, fleet tools, drill-string runs, ESP penetrators and drives - one CSV, checked against the workspace before anything is written")
+    p_dc.add_argument("--workspace", type=str, required=True)
+    p_dc.add_argument("--file", type=str, default=None, help="the sheet (CSV); every row is planned NEW, CHANGE or SAME and nothing is written without --apply")
+    p_dc.add_argument("--apply", action="store_true", help="write the NEW and CHANGE rows (only when the sheet has no error)")
+    p_dc.add_argument("--template", type=str, default=None, help="write the sheet for this workspace, filled with what is already declared, to this path")
+    p_dc.add_argument("--actor", type=str, default="cli")
+    p_dc.add_argument("--json", action="store_true")
+
+    p_pn = sub.add_parser("penetrator", help="the ESP wellhead penetrator: the penetrators the program knows with their ratings, the permanent magnet motor safety note, and each well's installation record and drive checked against the ratings")
+    p_pn.add_argument("--workspace", type=str, default=None)
+    p_pn.add_argument("--well", type=str, default=None)
+    p_pn.add_argument("--remove", type=str, default=None, choices=("install", "drive"), help="remove the well's installation record or its drive")
+    p_pn.add_argument("--actor", type=str, default="cli")
+    p_pn.add_argument("--json", action="store_true")
+
+    p_os = sub.add_parser("seismicity", help="operations and seismicity: each well's drilling, completion and disposal windows against the earthquake catalogue around it - the events during and after each, the levels a regulator's protocol would reach, and the rate during operations against the rest of the record; the Mahoning Valley worked example")
+    p_os.add_argument("--workspace", type=str, default=None)
+    p_os.add_argument("--scene", type=str, default=None, choices=("workspace", "mahoning"), help="your wells (the default with --workspace) or the public worked example")
+    p_os.add_argument("--protocol", type=str, default=None, help="a protocol id (--protocols lists them)")
+    p_os.add_argument("--radius-km", type=float, default=None, help="the association radius (default 5 km)")
+    p_os.add_argument("--screen-km", type=float, default=None, help="the screening distance (default 20 km)")
+    p_os.add_argument("--post-days", type=float, default=None, help="the association window after an operation ends (default 90 days)")
+    p_os.add_argument("--mc", type=float, default=None, help="the completeness magnitude counted in the rate (default the catalogue's minimum)")
+    p_os.add_argument("--set", action="store_true", help="keep --protocol, --radius-km, --screen-km, --post-days and --mc as this workspace's settings")
+    p_os.add_argument("--protocols", action="store_true", help="list the protocols and their levels")
+    p_os.add_argument("--query", action="store_true", help="print the ComCat query for the workspace's wells (run it where the catalogue service is reachable)")
+    p_os.add_argument("--attach", type=str, default=None, help="a catalogue export to attach (with --start --end --min-magnitude --lat --lon --catalog-radius-km --source)")
+    p_os.add_argument("--start", type=str, default=None)
+    p_os.add_argument("--end", type=str, default=None)
+    p_os.add_argument("--min-magnitude", type=float, default=None)
+    p_os.add_argument("--lat", type=float, default=None)
+    p_os.add_argument("--lon", type=float, default=None)
+    p_os.add_argument("--catalog-radius-km", type=float, default=None)
+    p_os.add_argument("--source", type=str, default="")
+    p_os.add_argument("--declare-op", action="store_true", help="declare an operation window (with --well --kind --start [--end] --source)")
+    p_os.add_argument("--well", type=str, default=None)
+    p_os.add_argument("--kind", type=str, default=None, choices=("drilling", "completion", "disposal", "injection", "other"))
+    p_os.add_argument("--remove-op", type=str, default=None)
+    p_os.add_argument("--remove-catalog", type=str, default=None)
+    p_os.add_argument("--actor", type=str, default="cli")
+    p_os.add_argument("--json", action="store_true")
+
     p_sm = sub.add_parser("simulation", help="the simulation in words: the scenes (Volve 15/9-F-4 with its logs and interpretation, Volve F-5 and F-10 on the survey clock, every drilling-recorder well), and what the record says at a depth (the Simulation tab replays it)")
     p_sm.add_argument("--workspace", type=str, default=None)
     p_sm.add_argument("--scene", type=str, default=None, help="e.g. volve-f4, or well:Well-30636033")
@@ -2074,6 +2116,116 @@ def main(argv=None) -> int:
             raise SystemExit(f"drillstring: {e.args[0] if e.args else e}")
         print(_json.dumps(p, default=str) if a.json else _DS.text(p))
         return 0
+    elif a.cmd == "declare":
+        import json as _json
+        from . import declarations as _DC
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"declare: {e}")
+        if a.template:
+            with open(a.template, "w", encoding="utf-8", newline="") as f:
+                f.write(_DC.template(ws))
+            print(f"wrote {a.template}: fill in the blanks, then gea declare --workspace {a.workspace} --file {a.template}")
+            return 0
+        if not a.file:
+            raise SystemExit("declare: give --file <sheet.csv> (or --template <out.csv> to start one)")
+        try:
+            with open(a.file, encoding="utf-8-sig") as f:
+                text_ = f.read()
+        except OSError as e:
+            raise SystemExit(f"declare: {e}")
+        p = _DC.apply(ws, text_, a.actor, os.path.dirname(os.path.abspath(a.file)), write=a.apply)
+        print(_json.dumps(p, default=str) if a.json else _DC.text(p))
+        return 1 if p["errors"] else 0
+    elif a.cmd == "penetrator":
+        import json as _json
+        from . import penetrator as _PN
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        ws = None
+        if a.workspace:
+            try:
+                ws = Workspace(a.workspace)
+            except WorkspaceError as e:
+                raise SystemExit(f"penetrator: {e}")
+        try:
+            if a.remove:
+                if ws is None or not a.well:
+                    raise SystemExit("penetrator: --remove needs --workspace and --well")
+                _PN.remove(ws, a.actor, a.well, a.remove)
+                print(f"removed the {a.remove} record of {a.well}")
+                return 0
+            if a.well:
+                if ws is None:
+                    raise SystemExit("penetrator: --well needs --workspace")
+                c = _PN.check(ws, a.well)
+                print(_json.dumps(c, default=str) if a.json else _PN.text_check(c))
+                return 0
+            p = _PN.page(ws)
+        except (ValueError, KeyError, OSError) as e:
+            raise SystemExit(f"penetrator: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _PN.text(p))
+        return 0
+    elif a.cmd == "seismicity":
+        import json as _json
+        from . import op_seismicity as _OS
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if a.protocols:
+            for p_ in _OS.protocols()["protocols"]:
+                print(f"{p_['id']}: {p_['name']} - within {p_['radius_km'] if p_['radius_km'] is not None else 'the permit distance'} km of {p_['radius_from']}; covers {', '.join(p_['applies_to'])}")
+                for lv in p_["levels"]:
+                    print(f"    M {lv['m']:g}{' (' + lv['condition'] + ')' if lv.get('condition') else ''}: {lv['action']}")
+                print(f"    {p_['document']} - {p_['url']}{' (a secondary summary)' if p_['source_kind'] == 'secondary' else ''}")
+            return 0
+        ws = None
+        if a.workspace:
+            try:
+                ws = Workspace(a.workspace)
+            except WorkspaceError as e:
+                raise SystemExit(f"seismicity: {e}")
+        try:
+            if a.attach:
+                if ws is None:
+                    raise SystemExit("seismicity: --attach needs --workspace")
+                with open(a.attach, "rb") as f:
+                    r = _OS.attach_catalog(ws, a.actor, os.path.basename(a.attach), f.read(), a.start, a.end, a.min_magnitude, a.lat, a.lon, a.catalog_radius_km, a.source)
+                print(f"attached {r['file']}: {r['n_events']} event(s), {r['start']} to {r['end']}, M >= {r['min_magnitude']:g}")
+                return 0
+            if a.declare_op:
+                if ws is None or not a.well or not a.kind:
+                    raise SystemExit("seismicity: --declare-op needs --workspace, --well and --kind")
+                r = _OS.save_operation(ws, a.actor, a.well, a.kind, a.start, a.end, a.source)
+                print(f"declared {r['id']}: {r['kind']} on {r['well_id']}, {r['start']} to {r['end'] or 'open'}")
+                return 0
+            if a.remove_op:
+                _OS.remove_operation(ws, a.actor, a.remove_op); print(f"removed {a.remove_op}"); return 0
+            if a.remove_catalog:
+                _OS.remove_catalog(ws, a.actor, a.remove_catalog); print(f"removed {a.remove_catalog}"); return 0
+            over = {k: v for k, v in (("protocol", a.protocol), ("radius_km", a.radius_km), ("screen_km", a.screen_km), ("post_days", a.post_days), ("mc", a.mc)) if v is not None}
+            if a.set:
+                if ws is None:
+                    raise SystemExit("seismicity: --set needs --workspace")
+                s_ = _OS.set_settings(ws, a.actor, over.get("protocol"), over.get("radius_km"), over.get("screen_km"), over.get("post_days"), over.get("mc"))
+                print("settings: " + ", ".join(f"{k} {v}" for k, v in s_.items()))
+                return 0
+            if over.get("protocol"):
+                _OS.protocol(over["protocol"])
+            r = _OS.page(ws, a.scene or ("workspace" if ws is not None else "mahoning"), over or None)
+        except (ValueError, KeyError, OSError) as e:
+            raise SystemExit(f"seismicity: {e.args[0] if e.args else e}")
+        if a.query:
+            q = r.get("query")
+            print(q["url"] if q else "no well of the workspace has a surface position yet: declare one first")
+            return 0
+        print(_json.dumps(r, default=str) if a.json else _OS.text(r))
+        return 0
     elif a.cmd == "simulation":
         import json as _json
         from . import simulation as _SIM