gea-program 0.20.0__tar.gz → 0.22.0__tar.gz

{gea_program-0.20.0 → gea_program-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.20.0
+Version: 0.22.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 (347 checks)
+gea accept                     # the product gate (353 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,6 +648,53 @@ 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 interval against the mapped tops
+
+Where does the injection sit in the geology? The operator declares the
+disposal interval - top and base, true vertical depth, and the reference
+elevation the depths are measured from with what it is (kelly bushing, ground,
+derrick floor) and where it came from: `gea workspace --action set-well --well
+<id> --top-interval-ft 9850 --base-interval-ft 10400 --depth-ref TVD
+--ref-elev-ft 2962 --ref-elev-datum KB --ref-elev-source "completion report"`
+(`--elev-3dep` fetches the ground elevation from the USGS 3DEP point service
+instead, stored with its raster and named as the ground). A contours layer is
+told what it maps (`add-layer ... --formation-name Wolfcamp --role
+top|isopach|base`). `--action interval --well <id>` then converts the interval
+to subsea with the arithmetic printed and sets it beside each formation-top
+bracket at the well: ABOVE the mapped top, BELOW it, or NOT RESOLVED where
+the bracket overlaps the interval; a formation with a top and an isopach gets
+a base bracket by arithmetic the report shows, and the declared depth tier
+(shallow or deep by the base the SRA names) is CONSISTENT with the map,
+INCONSISTENT, or NOT RESOLVED. The SRA packet's section 2c carries it and
+section 2d sets the catalogue's events against the mapped faults - the
+nearest trace to each epicentre, the counts within 1, 2 and 5 km, proximity
+never called attribution. `gea help interval`.
+
+### Mapped structure
+
+The first geological statement the program makes about a well. A structure
+layer - a shapefile of mapped faults and folds, a public map (USGS, a state
+survey, BEG/TexNet) or the operator's own - is read as the specification
+lays the format out (`gea/shapefile.py`, no dependency: the .shp by its .shx
+index, the .dbf attributes, the .prj coordinate system; geographic NAD83 or
+WGS84 taken as is, the Texas State Plane NAD83 zones unprojected, anything
+else refused by name) and kept in the workspace with every part hashed:
+`gea workspace --action add-layer --name ... --layer structure.zip
+--citation ...` (`--member <name>` names one shapefile in a zip holding
+several; `gea structure --layer <zip> --list` lists them). Each layer is
+kept by kind and read for what it is: faults and folds (`--action structure
+--well <id>` prints the nearest mapped fault and the nearest fold by
+distance along the ellipsoid and bearing, and what else the map holds within
+the radius), formation-top contours (which two the position lies between,
+read and not interpolated, or on one), basin and play polygons (which one
+the position is inside), picked wells (the nearest picks with their values).
+A position outside the layer's extent is OUTSIDE LAYER EXTENT, which is not
+"no faults". Proven on the USGS PP 1708 Appalachian structure layer and the
+EIA Permian Basin set. On the well page, in the SRA packet's
+section 2b for every well inside the area, and from `gea structure --layer
+<file> --lat --lon` for any position. A distance to a mapped trace is a fact
+of the map at the map's scale, not a hazard judgement. `gea help structure`.
+
 ### WITSML 2.x over ETP
 
 The newer rigs and stores do not poll: Energistics ETP v1.2 is a WebSocket

{gea_program-0.20.0 → gea_program-0.22.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 (347 checks)
+gea accept                     # the product gate (353 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,6 +609,53 @@ 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 interval against the mapped tops
+
+Where does the injection sit in the geology? The operator declares the
+disposal interval - top and base, true vertical depth, and the reference
+elevation the depths are measured from with what it is (kelly bushing, ground,
+derrick floor) and where it came from: `gea workspace --action set-well --well
+<id> --top-interval-ft 9850 --base-interval-ft 10400 --depth-ref TVD
+--ref-elev-ft 2962 --ref-elev-datum KB --ref-elev-source "completion report"`
+(`--elev-3dep` fetches the ground elevation from the USGS 3DEP point service
+instead, stored with its raster and named as the ground). A contours layer is
+told what it maps (`add-layer ... --formation-name Wolfcamp --role
+top|isopach|base`). `--action interval --well <id>` then converts the interval
+to subsea with the arithmetic printed and sets it beside each formation-top
+bracket at the well: ABOVE the mapped top, BELOW it, or NOT RESOLVED where
+the bracket overlaps the interval; a formation with a top and an isopach gets
+a base bracket by arithmetic the report shows, and the declared depth tier
+(shallow or deep by the base the SRA names) is CONSISTENT with the map,
+INCONSISTENT, or NOT RESOLVED. The SRA packet's section 2c carries it and
+section 2d sets the catalogue's events against the mapped faults - the
+nearest trace to each epicentre, the counts within 1, 2 and 5 km, proximity
+never called attribution. `gea help interval`.
+
+### Mapped structure
+
+The first geological statement the program makes about a well. A structure
+layer - a shapefile of mapped faults and folds, a public map (USGS, a state
+survey, BEG/TexNet) or the operator's own - is read as the specification
+lays the format out (`gea/shapefile.py`, no dependency: the .shp by its .shx
+index, the .dbf attributes, the .prj coordinate system; geographic NAD83 or
+WGS84 taken as is, the Texas State Plane NAD83 zones unprojected, anything
+else refused by name) and kept in the workspace with every part hashed:
+`gea workspace --action add-layer --name ... --layer structure.zip
+--citation ...` (`--member <name>` names one shapefile in a zip holding
+several; `gea structure --layer <zip> --list` lists them). Each layer is
+kept by kind and read for what it is: faults and folds (`--action structure
+--well <id>` prints the nearest mapped fault and the nearest fold by
+distance along the ellipsoid and bearing, and what else the map holds within
+the radius), formation-top contours (which two the position lies between,
+read and not interpolated, or on one), basin and play polygons (which one
+the position is inside), picked wells (the nearest picks with their values).
+A position outside the layer's extent is OUTSIDE LAYER EXTENT, which is not
+"no faults". Proven on the USGS PP 1708 Appalachian structure layer and the
+EIA Permian Basin set. On the well page, in the SRA packet's
+section 2b for every well inside the area, and from `gea structure --layer
+<file> --lat --lon` for any position. A distance to a mapped trace is a fact
+of the map at the map's scale, not a hazard judgement. `gea help structure`.
+
 ### WITSML 2.x over ETP
 
 The newer rigs and stores do not poll: Energistics ETP v1.2 is a WebSocket

{gea_program-0.20.0 → gea_program-0.22.0}/gea/__init__.py

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

{gea_program-0.20.0 → gea_program-0.22.0}/gea/__main__.py

@@ -285,7 +285,7 @@ def main(argv=None) -> int:
                                "add-seismic", "refresh-seismic", "remove-seismic", "sar-film", "refresh-all", "add-track", "refresh-track", "remove-track",
                                "seismic-dataset", "seismic-field", "add-site", "sites", "site-report", "remove-site", "rename",
                                "set-well", "sra-define", "sra-report", "associate", "osdu-export", "quakeml-export", "well-identity", "vibration-report",
-                               "add-live-station", "live-fold", "live-run", "month-end"])
+                               "add-live-station", "live-fold", "live-run", "month-end", "add-layer", "layers", "remove-layer", "structure", "interval"])
     p_ws.add_argument("--stations", type=str, nargs="+", default=None, help="add-track: two or more array station ids of this workspace")
     p_ws.add_argument("--site", type=str, default=None, help="site-report/remove-site: the site id")
     p_ws.add_argument("--api", type=str, default=None, help="set-well: the API number")
@@ -299,7 +299,7 @@ def main(argv=None) -> int:
     p_ws.add_argument("--channel-bhp", type=str, default=None, help="set-well: the downhole gauge channel (probe method)")
     p_ws.add_argument("--top-interval-ft", type=float, default=None, help="set-well: top of the disposal interval, ft (calculated method)")
     p_ws.add_argument("--gradient-psi-ft", type=float, default=None, help="set-well: fluid gradient, psi/ft (calculated method)")
-    p_ws.add_argument("--radius-km", type=float, default=None, help="sra-define: the area's radius in km (Gardendale: 9.08)")
+    p_ws.add_argument("--radius-km", type=float, default=None, help="sra-define: the area's radius in km (Gardendale: 9.08); structure: how far around the well to look (default 50)")
     p_ws.add_argument("--plan-date", type=str, default=None, help="sra-define: the plan date, YYYY-MM-DD")
     p_ws.add_argument("--threshold-m", type=float, default=3.5, help="sra-define: the magnitude the plan is written against (3.5)")
     p_ws.add_argument("--goal-months", type=int, default=18, help="sra-define: months without a threshold event that meet the goal (18)")
@@ -359,6 +359,18 @@ def main(argv=None) -> int:
     p_ws.add_argument("--seedlink-config", type=str, default=None, help="add-live-station: the SeedLink config JSON (gea seedlink --write-example-config)")
     p_ws.add_argument("--include-open", action="store_true", help="live-fold: fold the current day's files too (they are still being written)")
     p_ws.add_argument("--seconds", type=float, default=None, help="live-run: how long to run (default: until Ctrl+C)")
+    p_ws.add_argument("--layer", type=str, default=None, help="add-layer: the shapefile (zip, folder or .shp); remove-layer: the layer id")
+    p_ws.add_argument("--member", type=str, default=None, help="add-layer: which shapefile inside a zip or folder that holds several (gea structure --layer <zip> --list)")
+    p_ws.add_argument("--citation", type=str, default="", help="add-layer: where the map came from, in the site's words")
+    p_ws.add_argument("--formation-name", type=str, default=None, help="add-layer: the formation a contours layer maps (Wolfcamp)")
+    p_ws.add_argument("--role", type=str, choices=["top", "isopach", "base"], default=None, help="add-layer: what the contours are of that formation: its top elevation, its thickness, or its base")
+    p_ws.add_argument("--base-interval-ft", type=float, default=None, help="set-well: base of the disposal interval, ft")
+    p_ws.add_argument("--depth-ref", type=str, choices=["TVD", "MD"], default=None, help="set-well: the interval depths are true vertical (TVD) or measured (MD) depth")
+    p_ws.add_argument("--ref-elev-ft", type=float, default=None, help="set-well: the reference elevation the depths are measured from, ft above sea level")
+    p_ws.add_argument("--ref-elev-datum", type=str, choices=["KB", "GL", "DF"], default=None, help="set-well: what that elevation is: kelly bushing, ground level, derrick floor")
+    p_ws.add_argument("--ref-elev-source", type=str, default=None, help="set-well: where the elevation came from (completion report, survey plat)")
+    p_ws.add_argument("--elev-3dep", action="store_true", help="set-well: fetch the GROUND elevation at the surface position from the USGS 3DEP point service and store it as the reference (datum GL, source stated)")
+    p_ws.add_argument("--epqs-url", type=str, default=None, help="set-well --elev-3dep / gea elevation: the EPQS endpoint (default the USGS one)")
     p_ws.add_argument("--period", type=str, default="previous", help="month-end: the month, YYYY-MM, or 'previous' (the last closed month)")
     p_ws.add_argument("--no-refresh", action="store_true", help="month-end: collect the reports as they stand without refreshing first")
     p_ws.add_argument("--name", type=str, default=None, help="init: site name; add-*: display name")
@@ -392,6 +404,18 @@ def main(argv=None) -> int:
     p_hk.add_argument("--actor", type=str, default="housekeeping")
     p_hk.add_argument("--json", action="store_true")
 
+    p_el = sub.add_parser("elevation", help="the ground elevation of a position from the USGS 3DEP point service: --lat --lon (the ground, NAVD88; not the kelly bushing)")
+    p_el.add_argument("--lat", type=float, required=True); p_el.add_argument("--lon", type=float, required=True)
+    p_el.add_argument("--url", type=str, default=None, help="the EPQS endpoint (default the USGS one)")
+    p_el.add_argument("--json", action="store_true")
+    p_st = sub.add_parser("structure", help="the nearest mapped fault and fold to a position, from a shapefile: --layer <zip|folder|.shp> --lat --lon; --info describes the layer")
+    p_st.add_argument("--layer", type=str, required=True)
+    p_st.add_argument("--lat", type=float, default=None); p_st.add_argument("--lon", type=float, default=None)
+    p_st.add_argument("--radius-km", type=float, default=50.0)
+    p_st.add_argument("--member", type=str, default=None, help="which shapefile inside a zip or folder that holds several")
+    p_st.add_argument("--list", action="store_true", help="list the shapefiles a zip or folder holds and exit")
+    p_st.add_argument("--info", action="store_true", help="describe the layer (coordinate system, extent, types, metadata) and exit")
+    p_st.add_argument("--json", action="store_true")
     p_sk = sub.add_parser("soak", help="the patches through link outages for hours, measured: N WITS0 patches, an ETP patch and a SeedLink station through relays that are cut on a schedule; the Soak Report")
     p_sk.add_argument("--hours", type=float, default=None, help="how long (72 for the go-live soak); or --seconds")
     p_sk.add_argument("--seconds", type=float, default=None)
@@ -928,6 +952,55 @@ def main(argv=None) -> int:
             for x in r['records_removed'][:20]:
                 print(f"  record  {x['well_id']}/{x['file']}  {x['age_days']} d")
         return 0
+    elif a.cmd == "elevation":
+        from .elevation import EPQS_URL, epqs
+        r = epqs(a.lat, a.lon, url=a.url or EPQS_URL)
+        if a.json:
+            print(json.dumps(r, indent=1)); return 0 if r["status"] == "OK" else 1
+        if r["status"] != "OK":
+            print(f"elevation: {r['status']} - {r.get('detail', '')}", file=sys.stderr); return 1
+        print(f"ground elevation at {a.lat}, {a.lon}: {r['elev_ft']:,.2f} ft ({r['vertical_datum']})")
+        print(f"  source: {r['source']}")
+        return 0
+    elif a.cmd == "structure":
+        import json as _json
+        from . import shapefile as _SF
+        from . import structure as _ST
+        if a.list:
+            ms = _SF.members(a.layer)
+            print("\n".join(ms) if ms else f"no shapefile in {a.layer}")
+            return 0 if ms else 1
+        try:
+            L = _SF.read(a.layer, member=a.member)
+        except (ValueError, OSError) as e:
+            raise SystemExit(f"structure: {e}")
+        ta, na = _ST.guess_attrs(L)
+        kind = _ST.layer_kind(L)
+        if a.info or a.lat is None or a.lon is None:
+            md = L.source.get("metadata", {})
+            info = {"name": L.name, "kind": kind, "shape_type": L.shape_type, "crs": {k: v for k, v in L.crs.items() if k != "wkt"}, "bbox": list(L.bbox), "n_features": L.n,
+                    "fields": L.fields, "type_attr": ta, "name_attr": na, "value_attr": _ST.guess_value_attr(L) if kind == "contours" else None,
+                    "type_counts": dict(list(L.counts(ta).items())[:20]) if ta else {}, "metadata": md}
+            if a.json:
+                print(_json.dumps(info, indent=1))
+            else:
+                print(f"{L.name} ({kind}): {L.n} {L.shape_type} features; {L.crs['kind']} {L.crs.get('datum') or ''}; extent lon {L.bbox[0]:.3f}..{L.bbox[2]:.3f} lat {L.bbox[1]:.3f}..{L.bbox[3]:.3f}")
+                print(f"  fields: {', '.join(f['name'] + ' (' + f['type'] + ')' for f in L.fields)}; type attribute {ta!r}, name attribute {na!r}")
+                for k, v in list(info["type_counts"].items())[:12]:
+                    print(f"  {v:7d}  {k}")
+                if md.get("titles"):
+                    print(f"  source: {'; '.join(md['titles'][:2])}" + (f" ({md['pubdates'][0]})" if md.get("pubdates") else ""))
+            if a.lat is None or a.lon is None:
+                return 0
+        r = _ST.describe(L, a.lat, a.lon, a.radius_km, ta, na)
+        if a.json:
+            print(_json.dumps(r, indent=1, default=str))
+        else:
+            for line in _ST.lines(r):
+                print(line)
+            for h in r.get("within", [])[:10]:
+                print(f"  {h['distance_km']:8.2f} km  {h['bearing_deg']:5.0f} deg  {h['kind']:5s}  {h['type']}  {h['name']}")
+        return 0 if r["status"] == "OK" else 1
     elif a.cmd == "soak":
         import json as _json
         from .soak import run as _soak
@@ -1903,13 +1976,28 @@ def main(argv=None) -> int:
             elif a.action == "set-well":
                 if not a.well:
                     raise SystemExit("set-well needs --well <id>")
-                surface = {"lat": a.lat, "lon": a.lon, "datum": a.datum} if (a.lat is not None or a.lon is not None) else None
+                surface = {"lat": a.lat, "lon": a.lon, "datum": a.datum} if (a.lat is not None or a.lon is not None) else {}
+                if a.elev_3dep:
+                    from .elevation import EPQS_URL, as_reference, epqs
+                    w0 = ws.well(a.well)
+                    pos = {"lat": a.lat, "lon": a.lon} if a.lat is not None else (w0.get("surface") or {})
+                    if pos.get("lat") is None:
+                        raise SystemExit("--elev-3dep needs the surface position (give --lat --lon --datum, or declare it first)")
+                    r = epqs(float(pos["lat"]), float(pos["lon"]), url=a.epqs_url or EPQS_URL)
+                    if r["status"] != "OK":
+                        raise SystemExit(f"3DEP: {r['status']} - {r.get('detail', '')} ({r['url']})")
+                    surface["elevation"] = as_reference(r)
+                    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,
                                               "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:
-                    raise SystemExit("set-well: nothing to declare (give --lat/--lon, or any of --api --uic --depth-tier --channel-pressure ...)")
+                    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
             elif a.action == "sra-define":
@@ -1968,6 +2056,46 @@ def main(argv=None) -> int:
                     raise SystemExit("well-identity needs --well <id>")
                 r = ws.well_identity(a.well)
                 print(_ppdm_text(r)); return 0
+            elif a.action == "add-layer":
+                if not a.layer or not a.name:
+                    raise SystemExit("add-layer needs --name <display> and --layer <shapefile zip | folder | .shp>")
+                L = ws.add_layer(a.layer, a.name, actor=a.actor, citation=a.citation, member=a.member, formation=a.formation_name, role=a.role)
+                tc = ", ".join(f"{k} {v}" for k, v in list(L["type_counts"].items())[:6])
+                print(f"layer {L['id']} ({L['kind']}): {L['n_features']} {L['shape_type']} features, {L['crs']['kind']} {L['crs'].get('datum') or ''}, extent lon {L['bbox'][0]:.3f}..{L['bbox'][2]:.3f} lat {L['bbox'][1]:.3f}..{L['bbox'][3]:.3f}"
+                      + (f"; contour value {L['value_attr']}" if L.get('value_attr') else ''))
+                print(f"  types: {tc}" + (" ..." if len(L["type_counts"]) > 6 else ""))
+                md = L.get("metadata") or {}
+                if md.get("titles"):
+                    print(f"  source: {'; '.join(md['titles'][:2])}" + (f" ({md['pubdates'][0]})" if md.get("pubdates") else ""))
+                return 0
+            elif a.action == "layers":
+                for L in ws.layers():
+                    print(f"{L['id']:28s} {L.get('kind', 'structure'):10s} {L['n_features']:7d} {L['shape_type']:9s} {L['crs']['kind']} {L['crs'].get('datum') or '':6s} {L['display']}")
+                if not ws.layers():
+                    print("no structure layer - add one with --action add-layer --name ... --layer <shapefile zip>")
+                return 0
+            elif a.action == "remove-layer":
+                if not a.layer:
+                    raise SystemExit("remove-layer needs --layer <id>")
+                ws.remove_layer(a.layer, actor=a.actor); print(f"removed layer {a.layer} (folder kept, renamed)"); return 0
+            elif a.action == "structure":
+                if not a.well:
+                    raise SystemExit("structure needs --well <id>")
+                r = ws.well_structure(a.well, a.radius_km if a.radius_km is not None else 50.0, actor=a.actor)
+                print(f"structure {a.well}: {r['status']}" + (f" - {r['note']}" if r.get("note") else ""))
+                for L in r["layers"]:
+                    print(f"  [{L.get('layer_display') or L['layer']}]")
+                    for line in L["lines"]:
+                        print("    " + line)
+                return 0 if r["status"] == "OK" else 1
+            elif a.action == "interval":
+                if not a.well:
+                    raise SystemExit("interval needs --well <id>")
+                r = ws.well_interval(a.well, a.radius_km if a.radius_km is not None else 50.0, actor=a.actor)
+                print(f"interval {a.well}: {r['status']}")
+                for line in r["lines"]:
+                    print("  " + line)
+                return 0 if r["status"] == "OK" else 1
             elif a.action == "month-end":
                 from .month_end import report_text as _me_text
                 r = ws.month_end(a.period, actor=a.actor, refresh=not a.no_refresh, catalog_csv=a.catalog)