gea-program 0.30.0__tar.gz → 0.33.0__tar.gz

{gea_program-0.30.0/gea_program.egg-info → gea_program-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.30.0
+Version: 0.33.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
@@ -125,7 +125,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (376 checks)
+gea accept                     # the product gate (386 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -648,10 +648,62 @@ 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`.
 
+### The charts
+
+A well's page carries the Charts card: up to four channels stacked on one
+horizontal axis, a cursor that reads them all at the same moment, cut from
+every sample of the well's file. Drag across a stretch to zoom into it, the
+wheel zooms where you point, double-click or Reset shows everything; the
+keyboard does the same (arrows, + and -, Page Up and Page Down, Home). A
+month-wide view keeps a one-second spike - each bucket is the minimum, the
+maximum and the mean of its samples - and a stretch with no samples is drawn
+empty, never bridged. On a drilling recorder's export the axis switches
+between time and depth (the drilling samples by bit depth, kept off hole a
+later sidetrack abandoned), the depth events are marked where they
+happened, and each section of the recording is a button. The Wells page
+carries the drilling progress of every drilling-recorder well: hole depth
+against days, one colour per well. The refresh writes a chart cache per well
+from the read it already makes; `gea help charts`.
+
+### The setup checklist
+
+The Setup tab (`#/setup`, `gea checklist --workspace C:\site`) says what a
+workspace still needs before its reports can be handed over, read from the
+workspace as it stands: an administrator, the wells, a site record naming
+the client, a backup folder off the machine, a current backup, the daily
+schedule, current reports, and for each well its surface location and
+datum, its reference elevation with its source, and its US Well Number.
+Each item carries its own form or button - declare the position, take the
+ground level from USGS 3DEP to check, create the site, back up now - and,
+where every value is already known, the command to paste. The tab's badge
+counts the required items still to do and the Home page names the next
+one. A drilling record's depth events are confirmed by a person against
+the daily drilling reports, with a note; the confirmation stops counting
+if the record changes. `gea checklist` exits 0 when everything required is
+done. `gea help setup`.
+
 ### Tools and ports
 
-The Tools & ports tab (`#/tools`, `gea tools`) is the program's two
-registers in one place: the tool library - every downhole and surface tool
+The Tools & ports tab (`#/tools`, `gea tools`) opens on the **downhole tool
+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
+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
+quoted from the pages they cite and the pages themselves. The tutorials
+carry no numbers of their own; a figure on a tool's card is the cited page's
+words, most often one maker's product, never a limit for the class. Your
+**fleet** - the tools you actually run - goes in beside the classes, each
+with its maker, model, serial and the datasheet that rates it
+(`gea tools --action fleet-add --workspace C:\site --class pdm_motor
+--maker ... --model ... --datasheet ...`, or from the tutorial), kept in the
+workspace and audited. `gea tools --action classes`, `--action tutorial
+--class drilling_jar`.
+
+Below it are the program's two registers: the gauge library - every gauge
 with its source citation, ratings, what it measures, the telemetry interface
 it declares and its datasheet aging rate where the vendor published one -
 and the ports, the file formats read and the eleven live protocols spoken,
@@ -730,8 +782,14 @@ on bottom and rotating, the rate of penetration on bottom, the connections,
 the peaks; for the well, total depth and when the bit was first on bottom
 there, the recorder's TVD at it; per channel what was missing and how
 often; and the **MD-TVD table**, hole depth against the recorder's
-interpolated TVD, labelled an interpolation and not a survey. A recorder
-that resets its hole depth at a restart is named, not corrected. `gea edr
+interpolated TVD, labelled an interpolation and not a survey. Before any
+footage is counted the hole depth is read for what it can be trusted for:
+a depth carried over from the last well, a depth set back and counted up
+again by running pipe, a sidetrack, an overstated or understated depth
+corrected - each named as a depth event in the record and on the well
+page, and handled so that total depth is the final borehole's and the
+footage adds up. The recorder's gamma is written as a LAS log by bit
+depth. `gea edr
 --file C:\site\_incoming\30636033.csv`; `gea workspace --action add-file`
 then `refresh` for the record beside the well's other reports. `gea help
 edr`.

{gea_program-0.30.0 → gea_program-0.33.0}/README.md

@@ -86,7 +86,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (376 checks)
+gea accept                     # the product gate (386 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -609,10 +609,62 @@ 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`.
 
+### The charts
+
+A well's page carries the Charts card: up to four channels stacked on one
+horizontal axis, a cursor that reads them all at the same moment, cut from
+every sample of the well's file. Drag across a stretch to zoom into it, the
+wheel zooms where you point, double-click or Reset shows everything; the
+keyboard does the same (arrows, + and -, Page Up and Page Down, Home). A
+month-wide view keeps a one-second spike - each bucket is the minimum, the
+maximum and the mean of its samples - and a stretch with no samples is drawn
+empty, never bridged. On a drilling recorder's export the axis switches
+between time and depth (the drilling samples by bit depth, kept off hole a
+later sidetrack abandoned), the depth events are marked where they
+happened, and each section of the recording is a button. The Wells page
+carries the drilling progress of every drilling-recorder well: hole depth
+against days, one colour per well. The refresh writes a chart cache per well
+from the read it already makes; `gea help charts`.
+
+### The setup checklist
+
+The Setup tab (`#/setup`, `gea checklist --workspace C:\site`) says what a
+workspace still needs before its reports can be handed over, read from the
+workspace as it stands: an administrator, the wells, a site record naming
+the client, a backup folder off the machine, a current backup, the daily
+schedule, current reports, and for each well its surface location and
+datum, its reference elevation with its source, and its US Well Number.
+Each item carries its own form or button - declare the position, take the
+ground level from USGS 3DEP to check, create the site, back up now - and,
+where every value is already known, the command to paste. The tab's badge
+counts the required items still to do and the Home page names the next
+one. A drilling record's depth events are confirmed by a person against
+the daily drilling reports, with a note; the confirmation stops counting
+if the record changes. `gea checklist` exits 0 when everything required is
+done. `gea help setup`.
+
 ### Tools and ports
 
-The Tools & ports tab (`#/tools`, `gea tools`) is the program's two
-registers in one place: the tool library - every downhole and surface tool
+The Tools & ports tab (`#/tools`, `gea tools`) opens on the **downhole tool
+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
+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
+quoted from the pages they cite and the pages themselves. The tutorials
+carry no numbers of their own; a figure on a tool's card is the cited page's
+words, most often one maker's product, never a limit for the class. Your
+**fleet** - the tools you actually run - goes in beside the classes, each
+with its maker, model, serial and the datasheet that rates it
+(`gea tools --action fleet-add --workspace C:\site --class pdm_motor
+--maker ... --model ... --datasheet ...`, or from the tutorial), kept in the
+workspace and audited. `gea tools --action classes`, `--action tutorial
+--class drilling_jar`.
+
+Below it are the program's two registers: the gauge library - every gauge
 with its source citation, ratings, what it measures, the telemetry interface
 it declares and its datasheet aging rate where the vendor published one -
 and the ports, the file formats read and the eleven live protocols spoken,
@@ -691,8 +743,14 @@ on bottom and rotating, the rate of penetration on bottom, the connections,
 the peaks; for the well, total depth and when the bit was first on bottom
 there, the recorder's TVD at it; per channel what was missing and how
 often; and the **MD-TVD table**, hole depth against the recorder's
-interpolated TVD, labelled an interpolation and not a survey. A recorder
-that resets its hole depth at a restart is named, not corrected. `gea edr
+interpolated TVD, labelled an interpolation and not a survey. Before any
+footage is counted the hole depth is read for what it can be trusted for:
+a depth carried over from the last well, a depth set back and counted up
+again by running pipe, a sidetrack, an overstated or understated depth
+corrected - each named as a depth event in the record and on the well
+page, and handled so that total depth is the final borehole's and the
+footage adds up. The recorder's gamma is written as a LAS log by bit
+depth. `gea edr
 --file C:\site\_incoming\30636033.csv`; `gea workspace --action add-file`
 then `refresh` for the record beside the well's other reports. `gea help
 edr`.

{gea_program-0.30.0 → gea_program-0.33.0}/gea/__init__.py

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

{gea_program-0.30.0 → gea_program-0.33.0}/gea/__main__.py

@@ -285,6 +285,17 @@ def main(argv=None) -> int:
     p_tl.add_argument("--station", type=str, action="append", default=None, help="a station as DEPTH_FT:TOOL, e.g. 9850:quartz_pt_geoq177_16k")
     p_tl.add_argument("--surface-temp-f", type=float, default=75.0); p_tl.add_argument("--temp-gradient-f-ft", type=float, default=0.018)
     p_tl.add_argument("--surface-pressure-psi", type=float, default=14.7); p_tl.add_argument("--pressure-gradient-psi-ft", type=float, default=0.465)
+    p_tl.add_argument("--action", choices=["classes", "tutorial", "fleet", "fleet-add", "fleet-remove"], default=None,
+                      help="the downhole tool classes in use across the industry: classes (--category, --find), tutorial --class ID, and the workspace's own fleet (fleet, fleet-add, fleet-remove)")
+    p_tl.add_argument("--category", type=str, default=None, help="classes: one category (bits, drive, measure, bha, casing, completion, logging, fishing, testing)")
+    p_tl.add_argument("--find", type=str, default="", help="classes: words to look for in the name and description")
+    p_tl.add_argument("--class", dest="class_id", type=str, default=None, help="tutorial / fleet-add: the tool class id, e.g. pdm_motor")
+    p_tl.add_argument("--workspace", type=str, default=None, help="fleet actions: the workspace folder")
+    p_tl.add_argument("--maker", type=str, default=""); p_tl.add_argument("--model", type=str, default="")
+    p_tl.add_argument("--datasheet", type=str, default="", help="fleet-add: the datasheet that rates the tool - title and revision, or its URL (required)")
+    p_tl.add_argument("--serial", type=str, default=""); p_tl.add_argument("--od-in", type=float, default=None); p_tl.add_argument("--note", type=str, default="")
+    p_tl.add_argument("--id", type=str, default=None, help="fleet-remove: the fleet tool id (gea tools --action fleet lists them)")
+    p_tl.add_argument("--actor", type=str, default="cli")
     p_cc = sub.add_parser("comcat", help="USGS ComCat / any FDSN event service: --lat --lon --radius-km --start --end prints the text-format query to open; --file reads the export it returns")
     p_cc.add_argument("--lat", type=float, default=None); p_cc.add_argument("--lon", type=float, default=None); p_cc.add_argument("--radius-km", type=float, default=25.0)
     p_cc.add_argument("--start", type=str, default=None); p_cc.add_argument("--end", type=str, default=None); p_cc.add_argument("--min-mag", type=float, default=1.0)
@@ -457,6 +468,13 @@ def main(argv=None) -> int:
     p_ws.add_argument("--sat", action="store_true", help="refresh: also run the SAT protocol")
     p_ws.add_argument("--outage", action="append", default=None, help="refresh: outage window start/end (ISO), repeatable")
 
+    p_ck = sub.add_parser("checklist", help="the setup checklist: what this workspace still needs before its reports can be handed over - read from the workspace as it stands")
+    p_ck.add_argument("--workspace", type=str, default=None, help="the workspace folder, e.g. C:\\site")
+    p_ck.add_argument("--json", action="store_true")
+    p_ck.add_argument("--confirm", type=str, default=None, help="record a person's check of a confirmation item, e.g. events:Well-30636033")
+    p_ck.add_argument("--note", type=str, default="", help="--confirm: what it was checked against (required)")
+    p_ck.add_argument("--actor", type=str, default="cli")
+
     p_sv = sub.add_parser("serve", help="serve the dashboard over a workspace: the page, the reports and the JSON API (standard library HTTP)")
     p_sv.add_argument("--workspace", type=str, required=True, help="the workspace folder (gea workspace --action init)")
     p_sv.add_argument("--host", type=str, default="127.0.0.1", help="bind address; 0.0.0.0 exposes it on the site network (put TLS in front)")
@@ -1879,6 +1897,31 @@ def main(argv=None) -> int:
     elif a.cmd == "update":
         from .doctor import update as _update
         return _update(check_only=a.check, extras=a.extras, as_json=a.json)
+    elif a.cmd == "checklist":
+        import json as _json
+        from . import setup_checklist as _SC
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            raise SystemExit("checklist needs --workspace, e.g. --workspace C:\\site")
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"checklist: {e}")
+        if a.confirm:
+            try:
+                rec = _SC.confirm(ws, a.confirm, a.actor, a.note)
+            except ValueError as e:
+                raise SystemExit(f"checklist: {e}")
+            print(f"confirmed {a.confirm} by {rec['by']} at {rec['utc']}: {rec['note']}")
+            return 0
+        r = _SC.checklist(ws)
+        if a.json:
+            print(_json.dumps(r, indent=1))
+        else:
+            print(_SC.text(r))
+        return 0 if r["ready"] else 2
     elif a.cmd == "serve":
         from .service import Service
         from .workspace import WorkspaceError
@@ -2067,16 +2110,19 @@ def main(argv=None) -> int:
                     print(f"3DEP ground elevation {r['elev_ft']:,.2f} ft ({r['source']})")
                 elif a.ref_elev_ft is not None or a.ref_elev_datum or a.ref_elev_source:
                     surface["elevation"] = {"ft": a.ref_elev_ft, "datum": a.ref_elev_datum, "source": a.ref_elev_source}
-                disposal = {k: v for k, v in {"api_number": a.api, "uic_number": a.uic, "depth_tier": a.depth_tier, "formation_basis": a.formation,
+                identity = {"api_number": a.api} if a.api else {}
+                disposal = {k: v for k, v in {"uic_number": a.uic, "depth_tier": a.depth_tier, "formation_basis": a.formation,
                                               "channel_pressure": a.channel_pressure, "channel_rate": a.channel_rate, "rate_unit": a.rate_unit,
                                               "bhp_method": a.bhp_method, "channel_bhp": a.channel_bhp, "top_interval_ft": a.top_interval_ft,
                                               "base_interval_ft": a.base_interval_ft, "depth_reference": a.depth_ref,
                                               "gradient_psi_ft": a.gradient_psi_ft}.items() if v is not None}
-                if not surface and not disposal:
+                if a.api and (disposal or (ws.well(a.well).get("disposal") or {})):
+                    disposal["api_number"] = a.api          # a disposal well keeps its number in the block the SRA packet reads too
+                if not surface and not disposal and not identity:
                     raise SystemExit("set-well: nothing to declare (give --lat/--lon, --ref-elev-ft, or any of --api --uic --depth-tier --top-interval-ft ...)")
                 surface = surface or None
-                w = ws.set_well(a.well, surface=surface, disposal=disposal or None, actor=a.actor)
-                print(f"well {a.well}: surface {w.get('surface')}; disposal {w.get('disposal')}"); return 0
+                w = ws.set_well(a.well, surface=surface, disposal=disposal or None, identity=identity or None, actor=a.actor)
+                print(f"well {a.well}: surface {w.get('surface')}; identity {w.get('identity')}; disposal {w.get('disposal')}"); return 0
             elif a.action == "sra-define":
                 if not a.site or not a.name or a.lat is None or a.lon is None or a.radius_km is None or not a.plan_date:
                     raise SystemExit("sra-define needs --site, --name, --lat, --lon, --radius-km and --plan-date")
@@ -2374,6 +2420,71 @@ def main(argv=None) -> int:
     elif a.cmd == "tools":
         import json as _json
         from . import tool_catalog as _TC
+        if a.action:
+            from . import tool_taxonomy as _TX
+            from .cli import _safe_stdout
+            _safe_stdout()                                  # the cited figures carry fractions and degree signs
+            if a.action == "classes":
+                cs = _TX.classes(a.category, a.find)
+                if a.category and a.category not in _TX.CATEGORY_NAMES:
+                    raise SystemExit(f"tools: no category {a.category!r}; one of {', '.join(_TX.CATEGORY_NAMES)}")
+                if a.json:
+                    print(_json.dumps(cs, indent=1)); return 0
+                sm = _TX.summary()
+                print(f"{len(cs)} of {sm['classes']} tool classes; {sm['sources']} pages checked (fetched {sm['sources_fetched']}); {sm['figures']} published figures, each quoted from its page")
+                last = None
+                for t in cs:
+                    if t["category"] != last:
+                        print(f"\n{t['category_name']}"); last = t["category"]
+                    print(f"  {t['id']:<24s} {t['name']}")
+                    print(f"      {t['one_line']}")
+                print("\n`gea tools --action tutorial --class ID` opens one.")
+                return 0
+            if a.action == "tutorial":
+                if not a.class_id:
+                    raise SystemExit("tools: tutorial needs --class, e.g. --class pdm_motor (gea tools --action classes lists them)")
+                try:
+                    if a.json:
+                        print(_json.dumps(_TX.tool_class(a.class_id), indent=1)); return 0
+                    print(_TX.tutorial_text(a.class_id))
+                except KeyError as e:
+                    raise SystemExit(f"tools: {e.args[0]}")
+                return 0
+            if not a.workspace:
+                raise SystemExit(f"tools: --action {a.action} needs --workspace, e.g. --workspace C:\\site")
+            from .workspace import Workspace, WorkspaceError
+            try:
+                ws = Workspace(a.workspace)
+            except WorkspaceError as e:
+                raise SystemExit(f"tools: {e}")
+            if a.action == "fleet":
+                fl = _TX.fleet_list(ws.path)
+                if a.json:
+                    print(_json.dumps(fl, indent=1)); return 0
+                if not fl:
+                    print("the fleet is empty: gea tools --action fleet-add --workspace ... --class pdm_motor --maker ... --model ... --datasheet ...")
+                for t in fl:
+                    print(f"{t['id']:<32s} {t['class_name']}  -  {t['maker']} {t['model']}" + (f" s/n {t['serial']}" if t['serial'] else '') + (f", {t['od_in']:g} in OD" if t['od_in'] else ''))
+                    print(f"      datasheet: {t['datasheet']}")
+                return 0
+            if a.action == "fleet-add":
+                try:
+                    rec = _TX.fleet_add(ws.path, a.class_id or "", a.maker, a.model, a.datasheet, serial=a.serial, od_in=a.od_in, note=a.note, actor=a.actor)
+                except ValueError as e:
+                    raise SystemExit(f"tools: {e}")
+                ws.audit(a.actor, 'fleet.add', {'id': rec['id'], 'class': rec['class_id'], 'datasheet': rec['datasheet']})
+                print(f"added {rec['id']}: {rec['maker']} {rec['model']} ({rec['class_name']}); datasheet {rec['datasheet']}")
+                return 0
+            if a.action == "fleet-remove":
+                if not a.id:
+                    raise SystemExit("tools: fleet-remove needs --id (gea tools --action fleet lists them)")
+                try:
+                    rec = _TX.fleet_remove(ws.path, a.id)
+                except ValueError as e:
+                    raise SystemExit(f"tools: {e}")
+                ws.audit(a.actor, 'fleet.remove', {'id': rec['id'], 'class': rec['class_id']})
+                print(f"removed {rec['id']}")
+                return 0
         if a.rating or a.station:
             stations = []
             for spec in (a.station or []):