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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.21.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 (350 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,28 @@ 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

{gea_program-0.21.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 (350 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,28 @@ 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

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

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

{gea_program-0.21.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-layer", "layers", "remove-layer", "structure"])
+                               "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")
@@ -362,6 +362,15 @@ def main(argv=None) -> int:
     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")
@@ -395,6 +404,10 @@ 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)
@@ -939,6 +952,16 @@ 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
@@ -1953,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":
@@ -2021,7 +2059,7 @@ def main(argv=None) -> int:
             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)
+                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 ''))
@@ -2050,6 +2088,14 @@ def main(argv=None) -> int:
                     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)

{gea_program-0.21.0 → gea_program-0.22.0}/gea/acceptance_tests.py

@@ -6336,6 +6336,265 @@ def section_bo_structure(tmp: str) -> None:
        "all four; `gea structure --list` and `--member`"
        + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
 
+def section_bp_interval(tmp: str) -> None:
+    """Section BP - the declared interval against the mapped tops: subsea conversion through a stated reference, the
+    interval ABOVE / BELOW / NOT RESOLVED against each formation-top bracket, a base from a top and an isopach by the
+    arithmetic shown, the depth tier against the mapped base; the catalogue events against the mapped faults; the
+    3DEP ground elevation client against a stand-in service; the workspace, the SRA packet's sections, the API, the
+    page, the CLI, the help."""
+    import http.cookiejar
+    import http.server
+    import math as _math
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    import zipfile
+    from . import shapefile as SF
+    from . import interval as IV
+    from . import elevation as EL
+    from . import helplib as H
+    from .telemetry import TelemetryRecorder, TelemetryConfig
+    from .downhole_engine import DownholeEngine, SimulatorConfig
+    from .workspace import Workspace, WorkspaceError
+    from .service import Service, Users
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bp"); d.mkdir()
+
+    # -- BP1: the module on its own ----------------------------------------------------------------------------------
+    ss = IV.subsea_ft(9850.0, 2962.0)
+    c_above = IV.compare(-2050.0, -2650.0, (-8000.0, -7500.0))
+    c_below = IV.compare(-8100.0, -8700.0, (-8000.0, -7500.0))
+    c_nr = IV.compare(-7400.0, -7900.0, (-8000.0, -7500.0))
+    c_swapped = IV.compare(-2650.0, -2050.0, (-8000.0, -7500.0))          # top and base given the wrong way round
+    bb = IV.base_bracket((-8000.0, -7500.0), (1800.0, 2000.0))
+    t_deep_ok = IV.tier_check("deep", -10050.0, -10650.0, bb)
+    t_deep_bad = IV.tier_check("deep", -2050.0, -2650.0, bb)
+    t_shallow_ok = IV.tier_check("shallow", -2050.0, -2650.0, bb)
+    t_nr = IV.tier_check("shallow", -9500.0, -10100.0, bb)
+    t_none = IV.tier_check(None, -2050.0, -2650.0, bb)
+    br_on = IV.bracket_of({"status": "OK", "on": -7600.0, "between": None})
+    br_none = IV.bracket_of({"status": "OUTSIDE LAYER EXTENT"})
+    named = IV.formation_named("base of the Wolfcamp", ["Delaware", "Wolfcamp", "Bone Spring"])
+    named_none = IV.formation_named("base of the Ellenburger", ["Wolfcamp"])
+    well_md = {"id": "w", "surface": {"lat": 1.0, "lon": 1.0, "elevation": {"ft": 2950.0, "datum": "KB", "source": "report"}},
+               "disposal": {"top_interval_ft": 5000.0, "base_interval_ft": 5600.0, "depth_reference": "MD"}}
+    st_md = IV.statement(well_md, {"status": "OK", "layers": []}, [], None)
+    st_undeclared = IV.statement({"id": "w"}, {"status": "OK", "layers": []}, [], None)
+    well_gl = {"id": "w", "surface": {"lat": 1.0, "lon": 1.0, "elevation": {"ft": 2950.0, "datum": "GL", "source": "USGS 3DEP"}},
+               "disposal": {"top_interval_ft": 5000.0, "base_interval_ft": 5600.0, "depth_reference": "TVD"}}
+    st_gl = IV.statement(well_gl, {"status": "OK", "layers": [{"layer_id": "t", "layer": "t", "layer_kind": "contours", "status": "OK", "between": [-8000.0, -7500.0]}]},
+                         [{"id": "t", "kind": "contours", "formation": "Wolfcamp", "role": "top"}], None)
+    c1 = {
+        "subsea": ss == -6888.0,
+        "relations": c_above["relation"] == "ABOVE" and c_below["relation"] == "BELOW" and c_nr["relation"] == "NOT RESOLVED" and c_swapped["relation"] == "ABOVE"
+                     and "cannot place the top" in c_nr["detail"],
+        "base_arithmetic": bb == (-10000.0, -9300.0),
+        "tier": t_deep_ok["status"] == "CONSISTENT" and t_deep_bad["status"] == "INCONSISTENT" and t_shallow_ok["status"] == "CONSISTENT"
+                and t_nr["status"] == "NOT RESOLVED" and t_none["status"] == "NOT DECLARED",
+        "brackets_and_names": br_on == (-7600.0, -7600.0) and br_none is None and named == "Wolfcamp" and named_none is None,
+        "md_refused": st_md["status"] == "NOT RESOLVED" and "measured depth" in st_md["lines"][0] and "set-well --depth-ref TVD" in st_md["lines"][0],
+        "undeclared_named": st_undeclared["status"] == "NOT DECLARED" and "--top-interval-ft" in st_undeclared["lines"][0] and "--ref-elev-ft" in st_undeclared["lines"][0]
+                            and "--depth-ref" in st_undeclared["lines"][0],
+        "gl_note": st_gl["status"] == "OK" and st_gl["tops"][0]["relation"] == "ABOVE" and any("kelly bushing" in n and "not stated" in n for n in st_gl["notes"]),
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       "BP1 the interval module: subsea = reference - depth; ABOVE, BELOW and NOT RESOLVED against a top bracket (the top and base taken either way round); "
+       "a base from a top bracket and a thickness bracket by the arithmetic shown; the tier CONSISTENT, INCONSISTENT, NOT RESOLVED or NOT DECLARED against "
+       "the base; a measured-depth interval refused naming the remedy; an undeclared interval named by what is missing; a ground-elevation reference "
+       "carries the note that the kelly bushing is not stated"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    # -- BP2: the workspace, the SRA packet, the API, the page, the CLI, the help -----------------------------------
+    lat1, lon1 = 31.42, -103.50
+    kmlat = 1.0 / 111.195
+    kmlon = 1.0 / (111.195 * _math.cos(_math.radians(lat1)))
+
+    def ns_contours(name, attr, values, spacing_km=4.0):
+        ctr = [([[(lon1 + (i - (len(values) - 1) / 2) * spacing_km * kmlon, lat1 - 0.3), (lon1 + (i - (len(values) - 1) / 2) * spacing_km * kmlon, lat1 + 0.3)]],
+                {attr: float(v)}) for i, v in enumerate(values)]
+        SF.write(str(d / name), "PolyLine", ctr, [(attr, "F", 10, 1)], SF.NAD83_GEOGCS)
+        with zipfile.ZipFile(str(d / (name + ".zip")), "w") as z:
+            for ext in (".shp", ".shx", ".dbf", ".prj"):
+                z.write(str(d / (name + ext)), name + ext)
+        return str(d / (name + ".zip"))
+    z_top = ns_contours("WC_Top", "ElevTop_ft", [-8500, -8000, -7500, -7000])        # the position between -8,000 and -7,500
+    z_iso = ns_contours("WC_Isopach", "Thick_ft", [1600, 1800, 2000, 2200])          # between 1,800 and 2,000: base between -10,000 and -9,300
+    z_del = ns_contours("DEL_Top", "ElevTop_ft", [-2400, -2000, -1600, -1200])       # between -2,000 and -1,600
+    faults = [([[(lon1 - 0.3, lat1 + 3 * kmlat), (lon1 + 0.3, lat1 + 3 * kmlat)]], {"LONG_DESC": "fault", "NAME": "North Trace"}),
+              ([[(lon1 + 8 * kmlon, lat1 - 0.3), (lon1 + 8 * kmlon, lat1 + 0.3)]], {"LONG_DESC": "dotted fault", "NAME": "East Trace"})]
+    SF.write(str(d / "Faults_Test"), "PolyLine", faults, [("LONG_DESC", "C", 30, 0), ("NAME", "C", 30, 0)], SF.NAD83_GEOGCS)
+    with zipfile.ZipFile(str(d / "Faults_Test.zip"), "w") as z:
+        for ext in (".shp", ".shx", ".dbf", ".prj"):
+            z.write(str(d / ("Faults_Test" + ext)), "Faults_Test" + ext)
+    hist = str(d / "hist.csv")
+    TelemetryRecorder(engine=DownholeEngine(SimulatorConfig()), config=TelemetryConfig(duration_hours=1.0, seed=5)).run().export_csv(hist)
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad 3", actor="tester")
+    w = ws.add_well_file(hist, display="SWD 1", actor="tester")
+    lay_t = ws.add_layer(z_top, "WC top", actor="tester", formation="Wolfcamp", role="top", citation="the gate's own layer")
+    lay_i = ws.add_layer(z_iso, "WC isopach", actor="tester", formation="Wolfcamp", role="isopach")
+    ws.add_layer(z_del, "Delaware top", actor="tester", formation="Delaware")          # a formation named, the role defaulting to top
+    ws.add_layer(str(d / "Faults_Test.zip"), "Faults", actor="tester")
+    role_err = None
+    try:
+        ws.add_layer(str(d / "Faults_Test.zip"), "Faults as top", actor="tester", formation="X", role="top")
+    except WorkspaceError as e:
+        role_err = str(e)
+    before = ws.well_interval(w["id"], actor="tester")
+    elev_err = None
+    try:
+        ws.set_well(w["id"], surface={"lat": lat1, "lon": lon1, "datum": "NAD83", "elevation": {"ft": 2950.0, "datum": "KB"}}, actor="tester")
+    except WorkspaceError as e:
+        elev_err = str(e)
+    ws.set_well(w["id"], surface={"lat": lat1, "lon": lon1, "datum": "NAD83", "elevation": {"ft": 2950.0, "datum": "KB", "source": "completion report"}}, actor="tester")
+    order_err = None
+    try:
+        ws.set_well(w["id"], disposal={"top_interval_ft": 5600.0, "base_interval_ft": 5000.0}, actor="tester")
+    except WorkspaceError as e:
+        order_err = str(e)
+    ws.set_well(w["id"], disposal={"top_interval_ft": 5000.0, "base_interval_ft": 5600.0, "depth_reference": "TVD", "depth_tier": "shallow",
+                                   "formation_basis": "completed above the base of the Wolfcamp", "channel_pressure": "P_surf_psi", "channel_rate": "Q_bpm",
+                                   "rate_unit": "bbl/min", "bhp_method": "probe", "channel_bhp": "P_bh_psi"}, actor="tester")
+    site = ws.add_site("Pad 3 site", wells=[w["id"]], actor="tester")
+    ws.sra_define(site["id"], actor="tester", name="Pad 3 SRA", lat=lat1, lon=lon1, radius_km=9.08, plan_date="2026-01-15")
+    st1 = ws.well_interval(w["id"], actor="tester")
+    rel1 = {t["layer_id"]: t["relation"] for t in st1["tops"]}
+    ws.set_well(w["id"], disposal={"top_interval_ft": 13000.0, "base_interval_ft": 13600.0, "depth_tier": "deep"}, actor="tester")
+    st2 = ws.well_interval(w["id"], actor="tester")
+    ws.set_well(w["id"], disposal={"top_interval_ft": 10300.0, "base_interval_ft": 10900.0, "depth_tier": "deep"}, actor="tester")   # -7,350 to -7,950: across the top, above the base
+    st3 = ws.well_interval(w["id"], actor="tester")
+    ws.set_well(w["id"], disposal={"top_interval_ft": 12400.0, "base_interval_ft": 13000.0, "depth_tier": "deep"}, actor="tester")   # -9,450 to -10,050: across the base bracket
+    st3b = ws.well_interval(w["id"], actor="tester")
+    ws.set_well(w["id"], disposal={"top_interval_ft": 5000.0, "base_interval_ft": 5600.0, "depth_tier": "shallow"}, actor="tester")
+    # the catalogue: three events, two beside a trace
+    cat = str(d / "cat.csv")
+    with open(cat, "w", encoding="utf-8") as f:
+        f.write("EventID,Origin Date,Origin Time,Local Magnitude,Latitude (WGS84),Longitude (WGS84),Depth of Hypocenter (Km.  Rel to MSL)\n")
+        f.write(f"e1,2026-03-01,00:00:00,3.6,{lat1 + 2.5 * kmlat:.6f},{lon1:.6f},6.0\n")
+        f.write(f"e2,2026-03-02,00:00:00,2.0,{lat1:.6f},{lon1 + 7.5 * kmlon:.6f},5.0\n")
+        f.write(f"e3,2026-03-03,00:00:00,2.2,{lat1 - 0.05:.6f},{lon1 - 0.05:.6f},7.0\n")
+    pk = ws.write_sra_packet(site["id"], catalog_csv=cat, actor="tester")
+    sra_md = open(pk["paths"]["markdown"], encoding="utf-8").read()
+    audit = [a["action"] for a in ws.audit_log()]
+    users = Users(str(Path(wsp, "users.json"))); users.add("op", "operator-pass-1", "operator")
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base_url = svc.url.rstrip("/")
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+
+    def call(method, path, body=None):
+        req = urllib.request.Request(base_url + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        req.add_header("Content-Type", "application/json"); req.add_header("X-GEA-Action", "1")
+        try:
+            with opener.open(req, timeout=120) as rr_:
+                return rr_.status, json.loads(rr_.read())
+        except urllib.error.HTTPError as e:
+            return e.code, json.loads(e.read())
+    try:
+        call("POST", "/api/login", {"name": "op", "password": "operator-pass-1"})
+        st_g, got = call("GET", f"/api/wells/{w['id']}/interval")
+        st_d, dec = call("POST", f"/api/wells/{w['id']}/declare", {"disposal": {"top_interval_ft": 13000.0, "base_interval_ft": 13600.0, "depth_tier": "deep"}})
+        st_bad = call("POST", f"/api/wells/{w['id']}/declare", {"disposal": {"depth_reference": "feet"}})[0]
+        st_p, wrote = call("POST", f"/api/wells/{w['id']}/interval", {})
+        st_l, lst = call("GET", "/api/layers")
+    finally:
+        svc.stop()
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "interval.md").read_text(encoding="utf-8")
+    r_cli = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "interval", "--well", w["id"]], capture_output=True, text=True)
+    r_set = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "set-well", "--well", w["id"], "--top-interval-ft", "5000", "--base-interval-ft", "5600",
+                     "--depth-ref", "TVD", "--depth-tier", "shallow", "--ref-elev-ft", "2950", "--ref-elev-datum", "KB", "--ref-elev-source", "completion report"], capture_output=True, text=True)
+    r_add = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "add-layer", "--name", "WC top again", "--layer", z_top, "--formation-name", "Wolfcamp", "--role", "top"],
+                    capture_output=True, text=True)
+    sec2c = sra_md.split("The declared interval against the mapped tops")[1].split("## 2d")[0] if "The declared interval against the mapped tops" in sra_md else ""
+    sec2d = sra_md.split("Catalogue events against the mapped faults")[1].split("## 3")[0] if "Catalogue events against the mapped faults" in sra_md else ""
+    c2 = {
+        "layers_declared": lay_t["formation"] == "Wolfcamp" and lay_t["role"] == "top" and lay_i["role"] == "isopach" and role_err and "contours layer" in role_err
+                           and next(L_["role"] for L_ in ws.layers() if L_["id"] == "Delaware-top") == "top",
+        "declarations_refused": before["status"] == "NOT DECLARED" and elev_err and "source" in elev_err and order_err and "deeper than its top" in order_err,
+        "shallow_statement": st1["status"] == "OK" and st1["declared"]["top_subsea_ft"] == -2050.0 and st1["declared"]["base_subsea_ft"] == -2650.0
+                             and rel1 == {lay_t["id"]: "ABOVE", lay_i["id"]: "THICKNESS", "Delaware-top": "BELOW"}
+                             and st1["formations"][0]["base"] == [-10000.0, -9300.0] and st1["tier"]["status"] == "CONSISTENT" and st1["tier"]["formation"] == "Wolfcamp"
+                             and os.path.isfile(Path(wsp, "reports", "wells", w["id"], "interval.json")),
+        "deep_and_unresolved": st2["tier"]["status"] == "CONSISTENT" and st2["formations"][0]["interval_vs_base"]["relation"] == "BELOW"
+                               and st3["tier"]["status"] == "INCONSISTENT" and {t["layer_id"]: t["relation"] for t in st3["tops"]}[lay_t["id"]] == "NOT RESOLVED"
+                               and st3b["tier"]["status"] == "NOT RESOLVED" and st3b["formations"][0]["interval_vs_base"]["relation"] == "NOT RESOLVED",
+        "sra_sections": "## 2c" in sra_md and "| SWD-1 | OK |" in sec2c and "ABOVE WC top (-8,000/-7,500)" in sec2c and "CONSISTENT" in sec2c
+                        and "## 2d" in sra_md and "| Faults | e1 |" in sec2d and "North Trace | 0.50 |" in sec2d and "East Trace | 0.50 |" in sec2d
+                        and "2 within 1 km, 2 within 2 km, 2 within 5 km" in sec2d and "proximity to a mapped trace is not an attribution" in sec2d,
+        "audited": "well.interval" in audit and audit.count("well.interval") >= 3,
+        "api": st_g == 200 and got["status"] == "OK" and st_d == 200 and dec["disposal"]["depth_tier"] == "deep" and st_bad == 400 and st_p == 200
+               and wrote["tier"]["status"] == "CONSISTENT" and st_l == 200 and any(L_.get("role") == "isopach" for L_ in lst["layers"]),
+        "page": "intervalCardHtml" in page_src and "/api/wells/' + id + '/interval'" in page_src and "/api/elevation" in page_src and "lyRole" in page_src
+                and "kelly bushing is deeper by the KB height" in page_src,
+        "cli": r_cli.returncode == 0 and "BELOW the mapped Wolfcamp top" in r_cli.stdout and "Depth tier against the map (base of the Wolfcamp): CONSISTENT" in r_cli.stdout
+               and r_set.returncode == 0 and "'depth_reference': 'TVD'" in r_set.stdout and r_add.returncode == 0,
+        "help": any(t["topic"] == "interval" for t in H.topics()) and not H.check("interval") and "never a value between them" in help_md.split("will not call a measurement")[1],
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "BP2 the workspace: a contours layer declared with its formation and role (a role on a faults layer refused); the interval and its reference declared "
+       "(an elevation without its source refused, a base above its top refused), NOT DECLARED before; the shallow interval ABOVE the Wolfcamp top and "
+       "BELOW the Delaware top, the Wolfcamp base from top and isopach, the tier CONSISTENT; a deep interval CONSISTENT; an interval across the top NOT "
+       "RESOLVED against it and INCONSISTENT with a deep declaration; an interval across the base bracket NOT RESOLVED; the SRA packet's 2c and 2d; audited; the API declares, answers and writes; the page card with the 3DEP button; the CLI; the help"
+       + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+    # -- BP3: the 3DEP client against a stand-in service, and set-well --elev-3dep through it ----------------------
+    seen = []
+
+    class _EPQS(http.server.BaseHTTPRequestHandler):
+        def log_message(self, *a):       # quiet
+            pass
+
+        def do_GET(self):
+            import urllib.parse as up
+            q = up.parse_qs(up.urlsplit(self.path).query)
+            seen.append(q)
+            y = float(q.get("y", ["0"])[0]); x = float(q.get("x", ["0"])[0])
+            if y > 80:
+                body = json.dumps({"location": {"x": x, "y": y}, "value": "-1000000", "rasterSource": "", "resolution": 0})
+            elif y < -80:
+                body = b"<html>not json</html>"
+            else:
+                body = json.dumps({"location": {"x": x, "y": y, "spatialReference": {"wkid": 4326}}, "locationId": 0, "value": "2951.37",
+                                   "rasterSource": "https://prd-tnm.s3.amazonaws.com/USGS_13_n32w104.tif", "resolution": 10})
+            data = body.encode() if isinstance(body, str) else body
+            self.send_response(200); self.send_header("Content-Type", "application/json"); self.send_header("Content-Length", str(len(data))); self.end_headers()
+            self.wfile.write(data)
+    srv = http.server.ThreadingHTTPServer(("127.0.0.1", 0), _EPQS)
+    th = threading.Thread(target=srv.serve_forever, daemon=True); th.start()
+    url = f"http://127.0.0.1:{srv.server_address[1]}/v1/json"
+    try:
+        r_ok = EL.epqs(lat1, lon1, url=url)
+        r_nodata = EL.epqs(85.0, lon1, url=url)
+        r_notjson = EL.epqs(-85.0, lon1, url=url)
+        r_unreach = EL.epqs(lat1, lon1, url="http://127.0.0.1:9/v1/json", timeout=3)
+        ref = EL.as_reference(r_ok)
+        r_cli_el = _sp.run([sys.executable, "-m", "gea", "elevation", "--lat", str(lat1), "--lon", str(lon1), "--url", url], capture_output=True, text=True)
+        r_set3 = _sp.run([sys.executable, "-m", "gea", "workspace", "--path", wsp, "--action", "set-well", "--well", w["id"], "--elev-3dep", "--epqs-url", url], capture_output=True, text=True)
+        w3 = ws.well(w["id"])
+        st4 = ws.well_interval(w["id"], actor="tester")
+    finally:
+        srv.shutdown(); srv.server_close()
+    c3 = {
+        "answer": r_ok["status"] == "OK" and r_ok["elev_ft"] == 2951.37 and r_ok["resolution_m"] == 10.0 and "USGS_13_n32w104" in r_ok["raster"]
+                  and r_ok["source"].startswith("USGS 3DEP EPQS, ") and "10 m raster" in r_ok["source"] and "NAVD88" in r_ok["vertical_datum"],
+        "query_as_specified": seen and seen[0].get("wkid") == ["4326"] and seen[0].get("units") == ["Feet"] and abs(float(seen[0]["x"][0]) - lon1) < 1e-6 and abs(float(seen[0]["y"][0]) - lat1) < 1e-6,
+        "failures_named": r_nodata["status"] == "NO DATA" and r_notjson["status"] == "NOT JSON" and r_unreach["status"] == "UNREACHABLE" and EL.as_reference(r_nodata) is None,
+        "reference": ref == {"ft": 2951.37, "datum": "GL", "source": r_ok["source"], "vertical_datum": "NAVD88", "raster": r_ok["raster"], "queried_utc": r_ok["queried_utc"]},
+        "cli": r_cli_el.returncode == 0 and "2,951.37 ft" in r_cli_el.stdout and "source: USGS 3DEP EPQS" in r_cli_el.stdout,
+        "set_well": r_set3.returncode == 0 and "3DEP ground elevation 2,951.37 ft" in r_set3.stdout and w3["surface"]["elevation"]["datum"] == "GL"
+                    and w3["surface"]["elevation"]["ft"] == 2951.37 and "USGS 3DEP EPQS" in w3["surface"]["elevation"]["source"],
+        "gl_note_in_statement": st4["status"] == "OK" and st4["declared"]["ref_datum"] == "GL" and any("kelly bushing" in n for n in st4["notes"])
+                                and st4["declared"]["top_subsea_ft"] == round(2951.37 - 5000.0, 1),
+    }
+    failed3 = [k for k, v in c3.items() if not v]
+    ok(not failed3,
+       "BP3 the 3DEP point service: the query as the service specifies it (x, y, wkid 4326, feet), the answer with its raster, resolution and query "
+       "time as the source, the ground and NAVD88 named; no data, not JSON and unreachable each named; the answer as a reference elevation (datum GL); "
+       "`gea elevation` and `set-well --elev-3dep` through the stand-in service; the statement then carries the kelly-bushing note"
+       + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
+
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -6406,6 +6665,7 @@ def main() -> int:
         section_bm_month_end(tmp)
         section_bn_soak(tmp)
         section_bo_structure(tmp)
+        section_bp_interval(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.21.0 → gea_program-0.22.0}/gea/client_reports.py

@@ -1664,6 +1664,39 @@ def sra_packet_report(pk: dict, evaluated_at: Optional[datetime] = None, program
             'outside a layer\'s extent is said to be outside it. A distance to a mapped trace is a fact of the map at that map\'s scale, not a hazard '
             'judgement; the layer\'s own metadata and the site\'s citation say where the map came from.'],
             [Table(['Well', 'Layer', 'Kind', 'Status', 'What the layer says'], srows, 'Mapped structure')]))
+        irows = []
+        for wid, iv in (pk.get('interval') or {}).items():
+            d = iv.get('declared') or {}
+            decl = (f"{d['top_ft']:,.0f}-{d['base_ft']:,.0f} ft {d['depth_reference']} below {d['ref_datum']} {d['ref_elev_ft']:,.0f} ft = "
+                    f"{d['top_subsea_ft']:,.0f} to {d['base_subsea_ft']:,.0f} ft subsea") if d else '-'
+            tops = '; '.join(f"{t['relation']} {t['layer']}" + (f" ({t['bracket'][0]:,.0f}/{t['bracket'][1]:,.0f})" if t.get('bracket') else '') for t in iv.get('tops', [])) or '-'
+            tier = iv.get('tier') or {}
+            irows.append([wid, iv.get('status', '-'), decl, tops[:260], (f"{tier.get('status')}: {tier.get('detail', '')}"[:220] if tier else '-')])
+        if irows:
+            secs.append(Section('2c', 'The declared interval against the mapped tops', [
+                'For each well inside the area, the declared disposal interval - top and base in true vertical depth below the reference elevation the '
+                'operator stated - converted to subsea elevation and set beside each formation-top bracket the layers give at the well: ABOVE the mapped top, '
+                'BELOW it, or NOT RESOLVED where the bracket overlaps the interval. Where a formation has a top layer and an isopach layer, its base is the '
+                'arithmetic shown, and the declared depth tier (shallow or deep by the base the plan names) is CONSISTENT with the map, INCONSISTENT, or '
+                'NOT RESOLVED. A contour map is read, not interpolated; the completion report is the record of the interval.'],
+                [Table(['Well', 'Status', 'Declared interval', 'Against the mapped tops', 'Depth tier against the map'], irows, 'Interval against the tops')]))
+        ef = pk.get('events_faults') or []
+        if ef:
+            paras = ['The catalogue events inside the area, each against the mapped fault traces of every structure layer: the nearest trace to the epicentre by '
+                     'distance and bearing, and the counts within 1, 2 and 5 km of any trace. An epicentre against a surface trace at the map\'s scale: the '
+                     'hypocentral depth is not used, and proximity to a mapped trace is not an attribution of the event to it.']
+            erows = []
+            for lay in ef:
+                for ln in lay.get('lines', [])[:2]:
+                    paras.append(f"{lay.get('layer_display') or lay.get('layer')}: {ln}")
+                for e in lay.get('events', []):
+                    f_ = e.get('fault') or {}
+                    erows.append([lay.get('layer_display') or lay.get('layer'), e.get('event_id'), (e.get('time') or '')[:16].replace('T', ' '),
+                                  (f"{e['magnitude']:.1f}" if e.get('magnitude') is not None else '-'), e.get('status', '-'),
+                                  f_.get('name') or f_.get('type') or '-', (f"{f_['distance_km']:.2f}" if f_.get('distance_km') is not None else '-'),
+                                  (f"{f_['bearing_deg']:.0f}" if f_.get('bearing_deg') is not None else '-')])
+            secs.append(Section('2d', 'Catalogue events against the mapped faults', paras,
+                                [Table(['Layer', 'Event', 'Time (UTC)', 'M', 'Status', 'Nearest mapped fault', 'Distance (km)', 'Bearing'], erows[:200], 'Events against the faults')]))
     n = 3
     inside_wells = [w for w in pk['wells'] if w['inside'] and w.get('months')]
     for w in inside_wells:

gea_program-0.22.0/gea/elevation.py

@@ -0,0 +1,60 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""elevation - the ground elevation of a position from the USGS 3D Elevation Program (3DEP).
+
+The Elevation Point Query Service (EPQS) answers one position with the ground elevation from the best 3DEP
+raster it holds, the raster it came from and that raster's resolution: a public, documented, no-key service at
+https://epqs.nationalmap.gov/v1/json?x=<lon>&y=<lat>&wkid=4326&units=Feet . The elevation is orthometric
+(NAVD88 in the conterminous United States) - sea level for the purposes of a subsea depth - and it is the
+GROUND, not the kelly bushing: a depth measured from the KB is deeper by the KB height, which the completion
+report states and this service does not. The program stores what the service answered, with its raster and
+the time of the query, as the reference elevation's source; nothing is fetched unless asked.
+"""
+from __future__ import annotations
+
+import json
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from typing import Optional
+
+EPQS_URL = 'https://epqs.nationalmap.gov/v1/json'
+NO_DATA = -1000000.0
+
+
+def epqs(lat: float, lon: float, url: str = EPQS_URL, timeout: float = 20.0, units: str = 'Feet') -> dict:
+    """One query to the EPQS: the ground elevation at (lat, lon), the raster, its resolution, the query time."""
+    q = urllib.parse.urlencode({'x': f'{float(lon):.6f}', 'y': f'{float(lat):.6f}', 'wkid': '4326', 'units': units, 'includeDate': 'false'})
+    full = url + ('&' if '?' in url else '?') + q
+    req = urllib.request.Request(full, headers={'Accept': 'application/json', 'User-Agent': 'gea-program'})
+    t0 = datetime.now(timezone.utc)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            raw = r.read()
+    except Exception as e:                                                   # noqa: BLE001 - every failure is reported the same way
+        return {'status': 'UNREACHABLE', 'detail': f'{type(e).__name__}: {e}', 'url': full, 'queried_utc': t0.isoformat()}
+    try:
+        d = json.loads(raw.decode('utf-8'))
+    except Exception:                                                        # noqa: BLE001
+        return {'status': 'NOT JSON', 'detail': raw[:120].decode('utf-8', 'replace'), 'url': full, 'queried_utc': t0.isoformat()}
+    v = d.get('value')
+    try:
+        val = float(v)
+    except (TypeError, ValueError):
+        return {'status': 'NO VALUE', 'detail': f'the service answered without an elevation: {str(d)[:200]}', 'url': full, 'queried_utc': t0.isoformat()}
+    if val <= NO_DATA + 1 or val < -1500 or val > 30000:
+        return {'status': 'NO DATA', 'detail': f'the service holds no elevation at this position (value {val:g})', 'url': full, 'queried_utc': t0.isoformat()}
+    res = d.get('resolution')
+    out = {'status': 'OK', 'elev_ft': round(val, 2) if units == 'Feet' else round(val * 3.280839895, 2), 'units_answered': units,
+           'raster': d.get('rasterSource') or d.get('raster') or '', 'resolution_m': (float(res) if isinstance(res, (int, float, str)) and str(res).replace('.', '', 1).isdigit() else None),
+           'vertical_datum': 'NAVD88 (orthometric; the ground, not the kelly bushing)', 'url': full, 'queried_utc': t0.isoformat()}
+    out['source'] = f"USGS 3DEP EPQS, {out['queried_utc'][:10]}" + (f", {out['resolution_m']:g} m raster" if out['resolution_m'] else '') + (f" ({out['raster']})" if out['raster'] else '')
+    return out
+
+
+def as_reference(res: dict) -> Optional[dict]:
+    """The EPQS answer as a well's reference elevation record (datum GL, the source stated), or None."""
+    if res.get('status') != 'OK':
+        return None
+    return {'ft': res['elev_ft'], 'datum': 'GL', 'source': res['source'], 'vertical_datum': 'NAVD88', 'raster': res.get('raster', ''), 'queried_utc': res['queried_utc']}

gea_program-0.22.0/gea/help/interval.md

@@ -0,0 +1,11 @@
+# The interval against the mapped tops
+
+> The second geological statement this program makes about a well, and the first question a reviewer of a disposal well in a seismic response area asks: where does the injection interval sit against the mapped geology? The operator declares the interval and the elevation it is measured from; the formation-top layers the site brought give a bracket at the well; the program puts the two side by side and says ABOVE, BELOW, or NOT RESOLVED - and whether the declared depth tier agrees with the mapped base of the formation the plan names.
+
+**The command**: `gea workspace --path C:\site --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 W-2"` declares the interval in true vertical depth below the kelly bushing at the elevation the completion report states. `--elev-3dep` instead fetches the GROUND elevation at the declared surface position from the USGS 3D Elevation Program point service (`gea elevation --lat --lon` does the same for any position) and stores it as the reference with datum GL and the service's raster as the source. Layers are told what they map: `--action add-layer --name "EIA Wolfcamp top" --layer Wolfcamp_Elevation_Isopachs.zip --member Wolfcamp_Formation_Elevation_201712 --formation-name Wolfcamp --role top`, and the isopach the same way with `--role isopach`. Then `--action interval --well <id>` writes the statement; the well page's "Interval against the mapped tops" card and the SRA packet's section 2c carry it, and section 2d sets the catalogue's events against the mapped faults.
+
+**What it writes**: the declared interval converted to subsea elevation - reference elevation minus depth, so 9,850 ft below a KB at 2,962 ft is -6,888 ft subsea - and, for each contours layer with a bracket at the well, whether the interval is ABOVE the mapped top (its base shallower than the shallowest the top can be), BELOW it (its top deeper than the deepest the top can be), or NOT RESOLVED (the bracket overlaps the interval). For a formation with a top layer and an isopach layer, the base bracket by the arithmetic shown - top minus thickness, both as brackets - and the declared depth tier against it: CONSISTENT, INCONSISTENT, or NOT RESOLVED. For the catalogue events inside the SRA, the nearest mapped fault trace to each epicentre with its distance and bearing, and the counts within 1, 2 and 5 km. Written to `reports/wells/<id>/interval.json` and audited as `well.interval`.
+
+**The number to check**: the subsea top and base of the interval, and the status beside each top - and the tier line: `CONSISTENT`, `INCONSISTENT`, or `NOT RESOLVED` against the mapped base. `NOT DECLARED` names what is missing.
+
+**What this page will not call a measurement**: a depth between two contours - a bracket is two contours, never a value between them, and an interval the bracket overlaps is NOT RESOLVED, not placed. A kelly-bushing depth from a ground elevation - 3DEP answers the ground; the KB is higher by a height only the completion report states, and the page says so whenever the reference is GL. A measured depth - this program converts true vertical depth only; a deviated well's MD needs its survey first. The tier being right - the statement is whether the declaration and the map agree; the completion report is the record. An event's cause - an epicentre near a mapped trace at the map's scale is a distance, not an attribution, and the hypocentral depth is not used.