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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.41.0
+Version: 0.42.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -648,6 +648,20 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Operations and seismicity
+
+The Operations & Seismicity tab sets each well's drilling, completion and
+disposal windows against the earthquake catalogue around it: every event
+within the screening distance by its distance and time, whether it fell
+during an operation or in the months after, what the rig was doing when a
+drilling record covers it, the level a regulator's protocol would reach
+(British Columbia, Alberta, Oklahoma, Ohio, Texas, each with its
+document), and the exact test of whether the rate near the well is higher
+while it works than in the rest of the record. The Mahoning Valley, Ohio -
+the 2011 Youngstown sequence against the Northstar 1 injection year, the
+2014 Poland Township events against a stimulation - ships as a worked
+example from the public record. `gea seismicity`, `gea help opseis`.
+
 ### The declarations sheet
 
 Everything the operator declares about a pad comes in from one spreadsheet:

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

@@ -609,6 +609,20 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Operations and seismicity
+
+The Operations & Seismicity tab sets each well's drilling, completion and
+disposal windows against the earthquake catalogue around it: every event
+within the screening distance by its distance and time, whether it fell
+during an operation or in the months after, what the rig was doing when a
+drilling record covers it, the level a regulator's protocol would reach
+(British Columbia, Alberta, Oklahoma, Ohio, Texas, each with its
+document), and the exact test of whether the rate near the well is higher
+while it works than in the rest of the record. The Mahoning Valley, Ohio -
+the 2011 Youngstown sequence against the Northstar 1 injection year, the
+2014 Poland Township events against a stimulation - ships as a worked
+example from the public record. `gea seismicity`, `gea help opseis`.
+
 ### The declarations sheet
 
 Everything the operator declares about a pad comes in from one spreadsheet:

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

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

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

@@ -539,6 +539,33 @@ def main(argv=None) -> int:
     p_pn.add_argument("--actor", type=str, default="cli")
     p_pn.add_argument("--json", action="store_true")
 
+    p_os = sub.add_parser("seismicity", help="operations and seismicity: each well's drilling, completion and disposal windows against the earthquake catalogue around it - the events during and after each, the levels a regulator's protocol would reach, and the rate during operations against the rest of the record; the Mahoning Valley worked example")
+    p_os.add_argument("--workspace", type=str, default=None)
+    p_os.add_argument("--scene", type=str, default=None, choices=("workspace", "mahoning"), help="your wells (the default with --workspace) or the public worked example")
+    p_os.add_argument("--protocol", type=str, default=None, help="a protocol id (--protocols lists them)")
+    p_os.add_argument("--radius-km", type=float, default=None, help="the association radius (default 5 km)")
+    p_os.add_argument("--screen-km", type=float, default=None, help="the screening distance (default 20 km)")
+    p_os.add_argument("--post-days", type=float, default=None, help="the association window after an operation ends (default 90 days)")
+    p_os.add_argument("--mc", type=float, default=None, help="the completeness magnitude counted in the rate (default the catalogue's minimum)")
+    p_os.add_argument("--set", action="store_true", help="keep --protocol, --radius-km, --screen-km, --post-days and --mc as this workspace's settings")
+    p_os.add_argument("--protocols", action="store_true", help="list the protocols and their levels")
+    p_os.add_argument("--query", action="store_true", help="print the ComCat query for the workspace's wells (run it where the catalogue service is reachable)")
+    p_os.add_argument("--attach", type=str, default=None, help="a catalogue export to attach (with --start --end --min-magnitude --lat --lon --catalog-radius-km --source)")
+    p_os.add_argument("--start", type=str, default=None)
+    p_os.add_argument("--end", type=str, default=None)
+    p_os.add_argument("--min-magnitude", type=float, default=None)
+    p_os.add_argument("--lat", type=float, default=None)
+    p_os.add_argument("--lon", type=float, default=None)
+    p_os.add_argument("--catalog-radius-km", type=float, default=None)
+    p_os.add_argument("--source", type=str, default="")
+    p_os.add_argument("--declare-op", action="store_true", help="declare an operation window (with --well --kind --start [--end] --source)")
+    p_os.add_argument("--well", type=str, default=None)
+    p_os.add_argument("--kind", type=str, default=None, choices=("drilling", "completion", "disposal", "injection", "other"))
+    p_os.add_argument("--remove-op", type=str, default=None)
+    p_os.add_argument("--remove-catalog", type=str, default=None)
+    p_os.add_argument("--actor", type=str, default="cli")
+    p_os.add_argument("--json", action="store_true")
+
     p_sm = sub.add_parser("simulation", help="the simulation in words: the scenes (Volve 15/9-F-4 with its logs and interpretation, Volve F-5 and F-10 on the survey clock, every drilling-recorder well), and what the record says at a depth (the Simulation tab replays it)")
     p_sm.add_argument("--workspace", type=str, default=None)
     p_sm.add_argument("--scene", type=str, default=None, help="e.g. volve-f4, or well:Well-30636033")
@@ -2144,6 +2171,61 @@ def main(argv=None) -> int:
             raise SystemExit(f"penetrator: {e.args[0] if e.args else e}")
         print(_json.dumps(p, default=str) if a.json else _PN.text(p))
         return 0
+    elif a.cmd == "seismicity":
+        import json as _json
+        from . import op_seismicity as _OS
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if a.protocols:
+            for p_ in _OS.protocols()["protocols"]:
+                print(f"{p_['id']}: {p_['name']} - within {p_['radius_km'] if p_['radius_km'] is not None else 'the permit distance'} km of {p_['radius_from']}; covers {', '.join(p_['applies_to'])}")
+                for lv in p_["levels"]:
+                    print(f"    M {lv['m']:g}{' (' + lv['condition'] + ')' if lv.get('condition') else ''}: {lv['action']}")
+                print(f"    {p_['document']} - {p_['url']}{' (a secondary summary)' if p_['source_kind'] == 'secondary' else ''}")
+            return 0
+        ws = None
+        if a.workspace:
+            try:
+                ws = Workspace(a.workspace)
+            except WorkspaceError as e:
+                raise SystemExit(f"seismicity: {e}")
+        try:
+            if a.attach:
+                if ws is None:
+                    raise SystemExit("seismicity: --attach needs --workspace")
+                with open(a.attach, "rb") as f:
+                    r = _OS.attach_catalog(ws, a.actor, os.path.basename(a.attach), f.read(), a.start, a.end, a.min_magnitude, a.lat, a.lon, a.catalog_radius_km, a.source)
+                print(f"attached {r['file']}: {r['n_events']} event(s), {r['start']} to {r['end']}, M >= {r['min_magnitude']:g}")
+                return 0
+            if a.declare_op:
+                if ws is None or not a.well or not a.kind:
+                    raise SystemExit("seismicity: --declare-op needs --workspace, --well and --kind")
+                r = _OS.save_operation(ws, a.actor, a.well, a.kind, a.start, a.end, a.source)
+                print(f"declared {r['id']}: {r['kind']} on {r['well_id']}, {r['start']} to {r['end'] or 'open'}")
+                return 0
+            if a.remove_op:
+                _OS.remove_operation(ws, a.actor, a.remove_op); print(f"removed {a.remove_op}"); return 0
+            if a.remove_catalog:
+                _OS.remove_catalog(ws, a.actor, a.remove_catalog); print(f"removed {a.remove_catalog}"); return 0
+            over = {k: v for k, v in (("protocol", a.protocol), ("radius_km", a.radius_km), ("screen_km", a.screen_km), ("post_days", a.post_days), ("mc", a.mc)) if v is not None}
+            if a.set:
+                if ws is None:
+                    raise SystemExit("seismicity: --set needs --workspace")
+                s_ = _OS.set_settings(ws, a.actor, over.get("protocol"), over.get("radius_km"), over.get("screen_km"), over.get("post_days"), over.get("mc"))
+                print("settings: " + ", ".join(f"{k} {v}" for k, v in s_.items()))
+                return 0
+            if over.get("protocol"):
+                _OS.protocol(over["protocol"])
+            r = _OS.page(ws, a.scene or ("workspace" if ws is not None else "mahoning"), over or None)
+        except (ValueError, KeyError, OSError) as e:
+            raise SystemExit(f"seismicity: {e.args[0] if e.args else e}")
+        if a.query:
+            q = r.get("query")
+            print(q["url"] if q else "no well of the workspace has a surface position yet: declare one first")
+            return 0
+        print(_json.dumps(r, default=str) if a.json else _OS.text(r))
+        return 0
     elif a.cmd == "simulation":
         import json as _json
         from . import simulation as _SIM

{gea_program-0.41.0 → gea_program-0.42.0}/gea/acceptance_tests.py

@@ -7310,7 +7310,7 @@ def section_bu_comcat(tmp: str) -> None:
         "url": url == "https://earthquake.usgs.gov/fdsnws/event/1/query?format=text&starttime=2011-03-01&endtime=2012-03-01&latitude=41.1000&longitude=-80.6800&maxradiuskm=25&minmagnitude=1.5&orderby=time-asc",
         "cli": r_file.returncode == 0 and "largest: M 4.0 ml 2011-12-31T20:05:01Z at 41.1215, -80.6843" in r_file.stdout and "1.68 km" in r_file.stdout
                and r_url.returncode == 0 and "maxradiuskm=30&minmagnitude=2.5" in r_url.stdout and r_bad.returncode == 1 and "not an FDSN text export" in r_bad.stdout,
-        "help_and_fixtures": "gea comcat" in help_md and (fx / "README.md").read_text(encoding="utf-8").count("earthquake.usgs.gov/fdsnws/event/1/query") == 2,
+        "help_and_fixtures": "gea comcat" in help_md and (fx / "README.md").read_text(encoding="utf-8").count("earthquake.usgs.gov/fdsnws/event/1/query") == 3,
     }
     failed1 = [k for k, v in c1.items() if not v]
     ok(not failed1,
@@ -9703,6 +9703,213 @@ def section_cj_declarations(tmp: str) -> None:
        + (f" [failed: {', '.join(failed3)}]" if failed3 else ""))
 
 
+def section_ck_operations_seismicity(tmp: str) -> None:
+    """Section CK - operations and seismicity: the Mahoning Valley worked example from the public record (the 2011
+    Youngstown sequence against Northstar 1's injection year, the 2014 Poland Township events against the Poland-CLL2
+    stimulation, the ComCat catalogue 1990-2026), the protocols each event reaches by the catalogue's magnitude, the
+    exact conditional rate test against its hand value; a labelled synthetic pad; a workspace with a drilling record,
+    an attached catalogue and declared operations; the sheet, the API, the CLI, the tab and the help page."""
+    import http.cookiejar
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    import base64 as _b64
+    from math import comb
+    from . import declarations as DC
+    from . import drill_string as DS
+    from . import helplib as H
+    from . import op_seismicity as OS
+    from .workspace import Workspace
+    from .service import Service, Users
+    pkg = Path(__file__).parent
+    d = Path(tmp, "ck"); d.mkdir()
+
+    # -- CK1 the worked example ------------------------------------------------------------------------------------
+    ex = OS.page(None, "mahoning")
+    W = {w["id"]: w for w in ex["wells"]}
+    ns, pl = W["northstar-1"], W["poland-cll2"]
+    ev_ns = {e["event_id"]: e for e in ns["events"]}
+    ev_pl = {e["event_id"]: e for e in pl["events"]}
+    share = 457.0 / (457.0 + 12982.0)
+    by_prot = {}
+    for pid in ("ohio-odnr-2014", "oklahoma-occ-2016", "alberta-aer-so2-2015", "texas-rrc-2022", "bc-ksmma-2021"):
+        r_ = OS.page(None, "mahoning", {"protocol": pid})
+        by_prot[pid] = sorted((e["event_id"], e["protocol"]["highest"]["m"]) for w in r_["wells"] for e in w["protocol_events"])
+    c1 = {
+        "catalogue": ex["n_events"] == 21 and ex["catalog"]["start"] == "1990-01-01" and ex["catalog"]["min_magnitude"] == 1.0 and (pkg / "fixtures" / "comcat_mahoning_1990-2026.txt").is_file()
+                     and "comcat_mahoning_1990-2026.txt" in (pkg / "fixtures" / "README.md").read_text(encoding="utf-8"),
+        "northstar": ns["rate"]["n_operations"] == 8 and ns["rate"]["n_background"] == 0 and ns["rate"]["days_operations"] == 457.0 and ns["rate"]["status"] == "HIGHER DURING OPERATIONS"
+                     and abs(ns["rate"]["p_value"] - share ** 8) / share ** 8 < 1e-4 and ns["rate"]["ratio"] is None and ns["rate"]["background_upper_95_per_year"] == round(3 / 12982.0 * 365.25, 4)
+                     and ev_ns["ld60029101"]["relation"] == "AFTER" and ev_ns["ld60029101"]["days_after_end"] == 0.8 and ev_ns["ld60029101"]["distance_km"] < 1.0
+                     and ev_ns["ld60004308"]["relation"] == "DURING" and not ev_ns["ld60004308"]["within_radius"] and ev_ns["ld60014118"]["relation"] == "AFTER",
+        "poland": pl["rate"]["n_operations"] == 5 and pl["rate"]["n_background"] == 1 and sum(e["relation"] == "DURING" for e in pl["associated"]) == 4
+                  and ev_pl["ld60034503"]["relation"] == "AFTER" and ev_pl["ld60047703"]["relation"] == "OUTSIDE" and pl["rate"]["p_value"] < 1e-9
+                  and abs(pl["rate"]["p_value"] / sum(comb(6, k) * (96 / 13439) ** k * (1 - 96 / 13439) ** (6 - k) for k in (5, 6)) - 1) < 1e-4,
+        "coverage": ns["coverage"]["inside"] and pl["coverage"]["inside"],
+        "protocols": by_prot["ohio-odnr-2014"] == sorted((x, 1.0) for x in ("ld60034308", "ld60034403", "ld60034408", "ld60065316", "ld60034503"))
+                     and by_prot["oklahoma-occ-2016"] == [] and by_prot["alberta-aer-so2-2015"] == sorted((x, 2.0) for x in ("ld60034308", "ld60034408", "ld60065316"))
+                     and by_prot["texas-rrc-2022"] == [("ld60029101", 3.5)] and len(by_prot["bc-ksmma-2021"]) == 5,
+        "record_magnitude": any("2.44" in n and "3.0" in n for n in ex["notes"]) and max(e["magnitude"] for e in pl["associated"]) == 2.44,
+        "sources": all(p["url"].startswith("https://") and p["document"] for p in ex["protocols"]) and len(ex["protocols"]) == 5
+                   and [p["source_kind"] for p in ex["protocols"] if p["id"] == "ohio-odnr-2014"] == ["secondary"] and "Atkinson" in ex["sources"]["screen"]
+                   and "Kim" in ns["operations"][0]["source"] and "Skoumal" in pl["operations"][0]["source"],
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       "CK1 the worked example from the public record: ComCat 1990-2026 within 30 km of the Mahoning Valley, 21 events; Northstar 1's eight "
+       "events within 5 km in its injection year and the 90 days after against none in the rest, the probability equal to the share of time to "
+       "the eighth power, the M 4.0 0.8 days after shut-in; Poland-CLL2's four during its stimulation, one the next day, one in 2016 outside; "
+       "Ohio's 1.0 reached by all five, Oklahoma's 2.5 by none at the catalogue's ML 2.44 (the regulator's M 3.0 named), Alberta's 2.0 by "
+       "three, Texas's 3.5 by the M 4.0 after disposal; every protocol with its document, Ohio's marked secondary"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    # -- CK2 the arithmetic -----------------------------------------------------------------------------------------
+    syn = OS.analyse(OS.synthetic_scene())
+    sp = {w["id"]: w for w in syn["wells"]}["pad-1"]
+    ev = {e["event_id"]: e for e in sp["events"]}
+    quiet = OS.synthetic_scene()
+    quiet["events"] = [e for e in quiet["events"] if e["event_id"].startswith("bg")]
+    qr = {w["id"]: w for w in OS.analyse(quiet)["wells"]}["pad-1"]["rate"]
+    one = OS.synthetic_scene()
+    one["events"] = [e for e in one["events"] if e["event_id"].startswith("bg")] + [e for e in one["events"] if e["event_id"] == "op0"]
+    onr = {w["id"]: w for w in OS.analyse(one)["wells"]}["pad-1"]["rate"]
+    two = OS.synthetic_scene()
+    two["wells"].append({"id": "pad-2", "display": "SYNTHETIC pad 2", "lat": 32.005, "lon": -102.0, "operations": [{"kind": "completion", "start": "2024-05-03", "end": "2024-05-06", "source": "s"}]})
+    tw = {w["id"]: w for w in OS.analyse(two)["wells"]}
+    c2 = {
+        "binomial": abs(OS.binom_tail(3, 10, 0.2) - sum(comb(10, k) * 0.2 ** k * 0.8 ** (10 - k) for k in range(3, 11))) < 1e-12 and OS.binom_tail(0, 5, 0.3) == 1.0
+                    and OS.binom_tail(6, 5, 0.3) == 0.0 and OS.binom_tail(2, 4, 0.0) == 0.0,
+        "synthetic": sp["rate"]["n_operations"] == 12 and sp["rate"]["status"] == "HIGHER DURING OPERATIONS" and "far" not in ev and ev["op5"]["protocol"]["highest"]["m"] == 3.0
+                     and ev["op4"]["protocol"]["highest"]["m"] == 2.0 and [c["m"] for c in ev["op4"]["protocol"]["conditional"]] == [2.2]
+                     and sp["cluster"] and len(sp["cluster"][0]["events"]) >= 5 and all(e["relation"] == "DURING" and e["operation"]["kind"] == "completion" for e in sp["associated"]),
+        "unplaced": {w["id"]: w for w in syn["wells"]}["unplaced"]["placed"] is False and "surface position" in {w["id"]: w for w in syn["wells"]}["unplaced"]["notes"][0],
+        "not_distinguished": qr["n_operations"] == 0 and qr["status"] == "NOT DISTINGUISHED" and onr["status"] == "NOT DISTINGUISHED" and onr["n_operations"] == 1,
+        "also": any(x["well"] == "SYNTHETIC pad 2" for e in tw["pad-1"]["events"] for x in e["also"]) and any(x["well"] == "SYNTHETIC pad 1" for e in tw["pad-2"]["events"] for x in e["also"]),
+        "radius": {w["id"]: w for w in OS.analyse({**OS.synthetic_scene(), "settings": {**OS.DEFAULTS, "radius_km": 1.0}})["wells"]}["pad-1"]["rate"]["n_operations"] == 6,
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "CK2 the arithmetic: the binomial tail against the sum by hand; over a labelled synthetic pad twelve events in its completion found "
+       "higher than a twenty-year background, an event 30 km away left out, British Columbia's levels with the after-restart ones only "
+       "conditional, its five-in-72-hours cluster found; a background alone, and one event in the window, NOT DISTINGUISHED; an event near "
+       "two wells' operations named on both; a 1 km radius counting six; a well without a position named"
+       + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+    # -- CK3 a workspace -------------------------------------------------------------------------------------------
+    synr = DS.synthetic_motor_record(str(d))
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad CK", actor="tester")
+    we = ws.add_well_file(synr["path"], display="SYNTHETIC EDR well", actor="tester")
+    wf = ws.add_well_file(str(pkg / "sample_well_profile.csv"), display="SYNTHETIC frac well", actor="tester")
+    ws.set_well(we["id"], surface={"lat": 32.0, "lon": -102.0, "datum": "NAD83"}, actor="tester")
+    lines = ["#EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName",
+             "tx1|2026-08-01T05:00:00|32.005|-102.004|4|tx|tx|tx|tx1|ml|1.9|tx|syn",
+             "tx2|2026-08-04T05:00:00|32.012|-102.012|4|tx|tx|tx|tx2|ml|2.6|tx|syn",
+             "tx3|2026-08-05T05:00:00|32.013|-102.011|4|tx|tx|tx|tx3|ml|3.1|tx|syn",
+             "tx4|2020-02-01T05:00:00|32.10|-102.10|4|tx|tx|tx|tx4|ml|2.0|tx|syn"]
+    (d / "cat.txt").write_text("\n".join(lines) + "\n", encoding="utf-8")
+    (d / "notcat.txt").write_text("hello\nworld\n", encoding="utf-8")
+    bad = {}
+    for k, fn in (("kind", lambda: OS.save_operation(ws, "t", wf["id"], "fracking", "2026-08-03", None, "s")),
+                  ("order", lambda: OS.save_operation(ws, "t", wf["id"], "completion", "2026-08-03", "2026-08-01", "s")),
+                  ("source", lambda: OS.save_operation(ws, "t", wf["id"], "completion", "2026-08-03", None, "")),
+                  ("start", lambda: OS.save_operation(ws, "t", wf["id"], "completion", "", None, "s")),
+                  ("notcat", lambda: OS.attach_catalog(ws, "t", "notcat.txt", (d / "notcat.txt").read_bytes(), "2016-01-01", "2026-10-18", 1, 32, -102, 40, "s")),
+                  ("circle", lambda: OS.attach_catalog(ws, "t", "cat.txt", (d / "cat.txt").read_bytes(), "2016-01-01", "2026-10-18", 1, None, -102, 40, "s")),
+                  ("window", lambda: OS.attach_catalog(ws, "t", "cat.txt", (d / "cat.txt").read_bytes(), "2026-10-18", "2016-01-01", 1, 32, -102, 40, "s")),
+                  ("settings", lambda: OS.set_settings(ws, "t", radius_km=30, screen_km=10)),
+                  ("protocol", lambda: OS.set_settings(ws, "t", protocol_id="nope"))):
+        try:
+            fn(); bad[k] = False
+        except (ValueError, KeyError):
+            bad[k] = True
+    sheet = ("[wells],well,lat,lon,datum\n,SYNTHETIC frac well,32.01,-102.01,NAD83\n"
+             "[operations],well,kind,start,end,source\n,SYNTHETIC frac well,completion,2026-08-03,2026-08-08T12:00,stage log\n"
+             "[catalogs],file,start,end,min_magnitude,lat,lon,radius_km,source\n,cat.txt,2016-01-01,2026-10-18,1.0,32.0,-102.0,40,SYNTHETIC catalogue\n")
+    p1 = DC.apply(ws, sheet, "importer", str(d), write=True)
+    p2 = DC.plan(ws, sheet, str(d))
+    tp = DC.plan(ws, DC.template(ws), str(d))
+    OS.set_settings(ws, "tester", protocol_id="bc-ksmma-2021", post_days=30)
+    pg = OS.page(ws)
+    WW = {w["id"]: w for w in pg["wells"]}
+    ee = {e["event_id"]: e for e in WW[we["id"]]["events"]}
+    ef = {e["event_id"]: e for e in WW[wf["id"]]["events"]}
+    c3 = {
+        "refused": all(bad.values()),
+        "sheet": p1["applied"] and p1["counts"] == {"NEW": 3, "CHANGE": 0, "SAME": 0} and p2["counts"] == {"NEW": 0, "CHANGE": 0, "SAME": 3}
+                 and not tp["errors"] and tp["counts"]["NEW"] == 0 and tp["counts"]["CHANGE"] == 0 and len(OS.operations(ws)) == 1 and OS.catalogs(ws)[0]["n_events"] == 4,
+        "rig": ee["tx1"]["relation"] == "DURING" and ee["tx1"]["operation"]["kind"] == "drilling" and ee["tx1"]["rig"]["state"] == "drilling"
+               and abs(ee["tx1"]["rig"]["bottom_ft"] - 8300.0) < 1.0 and WW[we["id"]]["operations"][0]["source"].startswith("the drilling record"),
+        "frac": ef["tx3"]["relation"] == "DURING" and ef["tx3"]["protocol"]["highest"]["m"] == 3.0 and ef["tx1"]["relation"] == "OUTSIDE"
+                and any(x["kind"] == "drilling" for x in ef["tx1"]["also"]) and pg["settings"]["post_days"] == 30,
+        "query": pg["query"]["url"].startswith("https://earthquake.usgs.gov/fdsnws/event/1/query?format=text") and pg["query"]["start"] == "1990-01-01",
+        "audit": all(a in [x["action"] for x in ws.audit_log(500)] for a in ("seismicity.operation.declare", "seismicity.catalog.attach", "seismicity.settings")),
+    }
+    Users(str(Path(wsp, "users.json"))).add("v", "viewer-pass-1", "viewer"); Users(str(Path(wsp, "users.json"))).add("op", "op-pass-123", "operator")
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base_url = svc.url.rstrip("/")
+
+    def opener(name, pw_):
+        o = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+        rq = urllib.request.Request(base_url + "/api/login", method="POST", data=json.dumps({"name": name, "password": pw_}).encode())
+        rq.add_header("Content-Type", "application/json"); rq.add_header("X-GEA-Action", "1"); o.open(rq, timeout=30)
+        return o
+
+    def call(o, method, path, body=None):
+        rq = urllib.request.Request(base_url + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        if method == "POST":
+            rq.add_header("Content-Type", "application/json"); rq.add_header("X-GEA-Action", "1")
+        try:
+            with o.open(rq, 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:
+        V, O = opener("v", "viewer-pass-1"), opener("op", "op-pass-123")
+        s_w, wj = call(V, "GET", "/api/opseis")
+        s_m, mj = call(V, "GET", "/api/opseis?scene=mahoning&protocol=texas-rrc-2022&radius_km=10")
+        s_x, _ = call(V, "GET", "/api/opseis?scene=nope")
+        s_n, _ = call(V, "GET", "/api/opseis?radius_km=abc")
+        s_vo, _ = call(V, "POST", "/api/opseis/operation", {"well_id": wf["id"], "kind": "disposal", "start": "2026-09-01", "source": "s"})
+        s_oo, oo = call(O, "POST", "/api/opseis/operation", {"well_id": wf["id"], "kind": "disposal", "start": "2026-09-01", "source": "s"})
+        s_ob, _ = call(O, "POST", "/api/opseis/operation", {"well_id": "nope", "kind": "disposal", "start": "2026-09-01", "source": "s"})
+        s_or, _ = call(O, "POST", "/api/opseis/operation/remove", {"op_id": oo.get("id", "")})
+        s_or2, _ = call(O, "POST", "/api/opseis/operation/remove", {"op_id": oo.get("id", "")})
+        s_oc, _ = call(O, "POST", "/api/opseis/catalog", {"filename": "cat2.txt", "content_b64": _b64.b64encode((d / "cat.txt").read_bytes()).decode(), "start": "2016-01-01",
+                                                         "end": "2026-10-18", "min_magnitude": 1, "lat": 32, "lon": -102, "radius_km": 40, "source": "s"})
+        s_ocb, _ = call(O, "POST", "/api/opseis/catalog", {"filename": "x.txt", "content_b64": "!!", "start": "2016-01-01"})
+        s_rc, _ = call(O, "POST", "/api/opseis/catalog/remove", {"file": "cat2.txt"})
+        s_st, _ = call(O, "POST", "/api/opseis/settings", {"radius_km": 4})
+        s_ac, _ = call(O, "POST", "/api/opseis/nope", {})
+    finally:
+        svc.stop()
+    cli_p = _sp.run([sys.executable, "-m", "gea", "seismicity", "--protocols"], capture_output=True, text=True, cwd=str(pkg.parent))
+    cli_m = _sp.run([sys.executable, "-m", "gea", "seismicity", "--scene", "mahoning"], capture_output=True, text=True, cwd=str(pkg.parent))
+    cli_q = _sp.run([sys.executable, "-m", "gea", "seismicity", "--workspace", wsp, "--query"], capture_output=True, text=True, cwd=str(pkg.parent))
+    cli_w = _sp.run([sys.executable, "-m", "gea", "seismicity", "--workspace", wsp], capture_output=True, text=True, cwd=str(pkg.parent))
+    cli_b = _sp.run([sys.executable, "-m", "gea", "seismicity", "--workspace", wsp, "--declare-op", "--well", wf["id"], "--kind", "completion", "--start", "2026-09-09"],
+                    capture_output=True, text=True, cwd=str(pkg.parent))
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    c3.update({
+        "api": s_w == 200 and len(wj["wells"]) == 2 and wj["scene"] == "workspace" and s_m == 200 and mj["protocol"]["id"] == "texas-rrc-2022" and mj["settings"]["radius_km"] == 10
+               and s_x == 404 and s_n == 400 and s_vo == 403 and s_oo == 200 and s_ob == 404 and s_or == 200 and s_or2 == 404 and s_oc == 200 and s_ocb == 400
+               and s_rc == 200 and s_st == 200 and OS.settings(ws)["radius_km"] == 4 and s_ac == 404,
+        "cli": cli_p.returncode == 0 and "bc-ksmma-2021" in cli_p.stdout and "(after a restart)" in cli_p.stdout and cli_m.returncode == 0 and "Northstar 1" in cli_m.stdout
+               and "probability 1.8e-12" in cli_m.stdout and cli_q.returncode == 0 and cli_q.stdout.startswith("https://earthquake.usgs.gov/")
+               and cli_w.returncode == 0 and "rig: drilling at 8300 ft" in cli_w.stdout and cli_b.returncode != 0 and "source" in (cli_b.stderr + cli_b.stdout),
+        "page": all(x in page_src for x in ("VIEWS.opseis", "['#/opseis', 'Operations & seismicity']", "osChart", "/api/opseis/catalog", "/api/opseis/operation",
+                                             "What this page will not call a measurement", "km from the well", "the whole catalogue")),
+        "help": any(t[0] == "opseis" for t in H.INDEX) and not H.check("opseis") and H.VIEW_TOPIC.get("opseis") == "opseis",
+    })
+    failed3 = [k for k, v in c3.items() if not v]
+    ok(not failed3,
+       "CK3 a workspace: an unknown kind, an end before the start, no source, no start, a file that is no catalogue, a catalogue without its "
+       "circle or with its window backwards, a screen narrower than the radius and an unknown protocol refused; the sheet's operations and "
+       "catalogues written and then SAME, the template round-tripping; the drilling record's span a drilling window and the rig drilling at "
+       "8,300 ft when an event struck; a completion's M 3.1 at British Columbia's 3.0; the ComCat query drawn around the wells; the API, the "
+       "CLI, the tab and the help page"
+       + (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:
@@ -9794,6 +10001,7 @@ def main() -> int:
         section_ch_simulation(tmp)
         section_ci_drill_string(tmp)
         section_cj_declarations(tmp)
+        section_ck_operations_seismicity(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.41.0 → gea_program-0.42.0}/gea/declarations.py

@@ -53,6 +53,11 @@ TABLES: Dict[str, dict] = {
                             'service_basis', 'service_source', 'fleet_id', 'note') + MOTOR_COLS,
                    'need': ('well', 'run', 'class_id'),
                    'about': "each run's components from the bit up, in order: the class, maker, model, serial, OD, length, the motor's catalogue id (`gea tools --action motors`) or - for a motor not in the catalogue - its own figures (motor_*) with their source, the service interval with its basis and source"},
+    'operations': {'cols': ('well', 'kind', 'start', 'end', 'source', 'note'), 'need': ('well', 'kind', 'start', 'source'),
+                   'about': "operation windows for Operations & Seismicity: drilling, completion, disposal, injection or other, the start and end in UTC (blank end: still going), and the record it comes from"},
+    'catalogs': {'cols': ('file', 'start', 'end', 'min_magnitude', 'lat', 'lon', 'radius_km', 'source'),
+                 'need': ('file', 'start', 'end', 'min_magnitude', 'lat', 'lon', 'radius_km', 'source'),
+                 'about': "earthquake catalogue exports (USGS ComCat text or a TexNet CSV, a path beside this sheet) with the window, minimum magnitude and circle they were queried for"},
     'penetrators': {'cols': ('well', 'penetrator', 'installed', 'installer', 'certified', 'certificate', 'motor', 'gauge_distance_in', 'ir_a_megohm',
                              'ir_b_megohm', 'ir_c_megohm', 'ir_test_volts', 'ir_min_megohm', 'ir_min_source', 'void_test_psi', 'void_test_minutes',
                              'void_held', 'note'),
@@ -63,8 +68,8 @@ TABLES: Dict[str, dict] = {
                    'need': ('well', 'source'),
                    'about': "the ESP drive's output limits and the motor nameplate, the wellhead's hazardous-area classification (e.g. Class I, Division 1), gas group, temperature class and the site's ambient range"},
 }
-ORDER = ('wells', 'fleet', 'rates', 'items', 'afe', 'surveys', 'runs', 'components', 'penetrators', 'esp_drives')
-APPLY_ORDER = ('wells', 'fleet', 'rates', 'items', 'afe', 'surveys', 'runs', 'penetrators', 'esp_drives')
+ORDER = ('wells', 'fleet', 'rates', 'items', 'afe', 'surveys', 'runs', 'components', 'penetrators', 'esp_drives', 'operations', 'catalogs')
+APPLY_ORDER = ('wells', 'fleet', 'rates', 'items', 'afe', 'surveys', 'runs', 'penetrators', 'esp_drives', 'operations', 'catalogs')
 
 
 class SheetError(ValueError):
@@ -482,6 +487,44 @@ def plan(ws, text: str, base_dir: str = '') -> dict:
                 lambda actor, wid=wid, kw=kw: PN.save_drive(ws, actor, wid, **kw))
         guard('esp_drives', rec, b)
 
+    from . import op_seismicity as OS
+    ops_have = OS.operations(ws)
+    seen_ops = set()
+    for rec in tables.get('operations', []):
+        def b(rec=rec):
+            wid = _well_id(ws, rec['well'], wells)
+            new = OS.operation_record(ws, wid, rec.get('kind', ''), rec.get('start'), rec.get('end'), rec.get('source', ''), rec.get('note', ''))
+            key = (wid, new['kind'], new['start'])
+            if key in seen_ops:
+                raise SheetError(f"the {new['kind']} operation starting {new['start']} on {wid} is on the sheet twice")
+            seen_ops.add(key)
+            old = next((o for o in ops_have if (o['well_id'], o['kind'], o['start']) == key), None)
+            if old and (old['end'], old['source'], old['note']) == (new['end'], new['source'], new['note']):
+                add('operations', rec['_row'], wid, 'SAME', f"{new['kind']} from {new['start']} already declared")
+                return
+            add('operations', rec['_row'], wid, 'CHANGE' if old else 'NEW', f"{new['kind']} {new['start']} to {new['end'] or 'open'} ({new['source']})",
+                lambda actor, wid=wid, rec=rec, oid=(old or {}).get('id'): OS.save_operation(ws, actor, wid, rec.get('kind', ''), rec.get('start'), rec.get('end'),
+                                                                                              rec.get('source', ''), rec.get('note', ''), oid))
+        guard('operations', rec, b)
+    cats_have = {c['file']: c for c in OS.catalogs(ws)}
+    for rec in tables.get('catalogs', []):
+        def b(rec=rec):
+            p = rec['file'].strip()
+            path = p if os.path.isabs(p) else os.path.join(base_dir or '.', p)
+            if not os.path.isfile(path):
+                raise SheetError(f'no catalogue file {p!r} beside the sheet' + ('' if base_dir else ' (a sheet sent through the browser carries no files: attach catalogues on the Operations & Seismicity tab or from the command line)'))
+            with open(path, 'rb') as f:
+                content = f.read()
+            new = OS.catalog_record(os.path.basename(p), content, rec['start'], rec['end'], rec['min_magnitude'], rec['lat'], rec['lon'], rec['radius_km'], rec['source'])
+            old = cats_have.get(new['file'])
+            if old and all(old.get(k) == new[k] for k in ('sha256', 'start', 'end', 'min_magnitude', 'circle', 'source')):
+                add('catalogs', rec['_row'], None, 'SAME', f"{new['file']} already attached")
+                return
+            add('catalogs', rec['_row'], None, 'CHANGE' if old else 'NEW', f"{new['file']}: {new['n_events']} event(s), {new['start']} to {new['end']}, M >= {new['min_magnitude']:g}",
+                lambda actor, p=p, content=content, rec=rec: OS.attach_catalog(ws, actor, os.path.basename(p), content, rec['start'], rec['end'], rec['min_magnitude'],
+                                                                               rec['lat'], rec['lon'], rec['radius_km'], rec['source']))
+        guard('catalogs', rec, b)
+
     steps.sort(key=lambda s: (APPLY_ORDER.index(s['table']), s['row']))
     counts = {k: sum(1 for s in steps if s['action'] == k) for k in ('NEW', 'CHANGE', 'SAME')}
     return {'steps': steps, 'errors': sorted(errs, key=lambda e: int(re.match(r'row (\d+)', e).group(1)) if re.match(r'row (\d+)', e) else 0),
@@ -619,4 +662,11 @@ def template(ws) -> str:
         d = rec.get('drive')
         if d:
             w.writerow(['', wid] + [_g(d.get(k)) if d.get(k) is not None else '' for k in TABLES['esp_drives']['cols'][1:]])
+    from . import op_seismicity as OS
+    head('operations')
+    for o in OS.operations(ws):
+        w.writerow(['', o['well_id'], o['kind'], o['start'], o['end'] or '', o['source'], o.get('note', '')])
+    head('catalogs')
+    for c in OS.catalogs(ws):
+        w.writerow(['# ' + c['file'] + ' is attached (' + str(c['n_events']) + ' events); list it here only to replace it'])
     return buf.getvalue()

{gea_program-0.41.0 → gea_program-0.42.0}/gea/fixtures/README.md

@@ -8,6 +8,12 @@ Small, verbatim, public-domain extracts kept so the gate can prove a reader on r
 - `comcat_youngstown_2011-2012.txt` - the same service, fetched 2026-10-12:
   `https://earthquake.usgs.gov/fdsnws/event/1/query?format=text&starttime=2011-03-01&endtime=2012-03-01&latitude=41.1&longitude=-80.68&maxradiuskm=25&minmagnitude=1.5&orderby=time-asc`
   (9 events within 25 km of Youngstown, Ohio: the 2011 sequence that ended with the M 4.0 of 2011-12-31; contributor ld = Lamont-Doherty). Public domain.
+- `comcat_mahoning_1990-2026.txt` - the same service, read 2026-10-18 through the web reader as text and again as CSV, the two
+  readings compared event by event and agreeing on every id, time, position, depth and magnitude (no byte-for-byte fetch, so no hash):
+  `https://earthquake.usgs.gov/fdsnws/event/1/query?format=text&starttime=1990-01-01&endtime=2026-10-18&latitude=41.065&longitude=-80.605&maxradiuskm=30&minmagnitude=1&orderby=time-asc`
+  (21 events M >= 1.0 within 30 km of the Mahoning Valley, Ohio, 1990 to 2026: none before 2011; the 2011 Youngstown sequence; the
+  March 2014 Poland Township sequence; the April 2016 events by Bessemer, Pennsylvania; one in 2024). The Operations & Seismicity
+  worked example. Public domain.
 - `ne_110m_coastline.json` - Natural Earth 1:110m coastline (`ne_110m_coastline`), fetched 2026-10-13 from
   `https://github.com/nvkelso/natural-earth-vector` (geojson/ne_110m_coastline.geojson, md5 0b8f91e9d9c4fb607e61e121b5ac48fa):
   134 lines, 5,127 points after rounding to 0.01 degree and dropping consecutive duplicates. Public domain (Natural Earth).

gea_program-0.42.0/gea/fixtures/comcat_mahoning_1990-2026.txt

@@ -0,0 +1,22 @@
+#EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName
+ld60004308|2011-03-17T10:53:11.670|41.126|-80.6056667|3.54|ld|ld|ld|ld60004308|ml|2.1|ld|2 km WSW of Maplewood Park, Ohio
+ld60007303|2011-08-22T08:00:32.640|41.1303333|-80.7081667|5|ld|ld|ld|ld60007303|ml|1.87|ld|2 km SSW of Girard, Ohio
+ld60009603|2011-09-26T01:06:10.840|41.115|-80.6823333|5|ld|ld|ld|ld60009603|ml|2.12|ld|3 km WNW of Youngstown, Ohio
+ld60009803|2011-09-30T00:52:38.710|41.1346667|-80.6845|5|ld|ld|ld|ld60009803|ml|2.44|ld|2 km SSE of Girard, Ohio
+ld60010908|2011-10-20T22:41:10.820|41.1253333|-80.704|6.39|ld|ld|ld|ld60010908|ml|2.04|ld|3 km S of Girard, Ohio
+ld60012603|2011-11-25T06:47:28.250|41.124|-80.6771667|5|ld|ld|ld|ld60012603|ml|1.79|ld|3 km NW of Youngstown, Ohio
+ld60013703|2011-12-24T06:24:58.810|41.1225|-80.7046667|5|ld|ld|ld|ld60013703|ml|2.37|ld|3 km S of Girard, Ohio
+ld60029101|2011-12-31T20:05:01.060|41.1215|-80.6843333|5|ld|ld|ld|ld60029101|ml|4|ld|3 km NW of Youngstown, Ohio
+ld60014118|2012-01-13T22:29:35.120|41.1245|-80.6923333|5.79|ld|ld|ld|ld60014118|ml|1.74|ld|3 km SSE of Girard, Ohio
+ld60034308|2014-03-10T06:26:45.900|41.0103333|-80.5433333|2.54|ld|ld|ld|ld60034308|ml|2.44|ld|2 km SSW of Lowellville, Ohio
+ld60034403|2014-03-10T06:42:44.280|41.0088333|-80.555|5|ld|ld|ld|ld60034403|ml|1.97|ld|3 km SSW of Lowellville, Ohio
+ld60034408|2014-03-10T15:03:47.610|41.0096667|-80.53|5|ld|ld|ld|ld60034408|ml|2.16|ld|2 km S of Lowellville, Ohio
+ld60065316|2014-03-10T15:44:06.780|41.009|-80.5316667|5|ld|ld|ld|ld60065316|ml|2.42|ld|2 km S of Lowellville, Ohio
+ld60034503|2014-03-11T07:01:13.340|41.0025|-80.5336667|5.22|ld|ld|ld|ld60034503|ml|1.86|ld|3 km S of Lowellville, Ohio
+ld60078511|2014-08-31T21:34:10.940|41.196|-80.7765|2.56|ld|ld|ld|ld60078511|ml|1.98|ld|Ohio
+ld60112616|2016-04-25T04:05:25.280|41|-80.46|3|ld|ld|ld|ld60112616|ml|2.04|ld|3 km NE of Bessemer, Pennsylvania
+ld60047603|2016-04-25T08:16:55.120|40.9888333|-80.3863333|3|ld|ld|ld|ld60047603|ml|1.76|ld|1 km W of Oakland, Pennsylvania
+ld60047703|2016-04-25T09:03:02.690|41.0258333|-80.512|3|ld|ld|ld|ld60047703|ml|1.85|ld|2 km ESE of Lowellville, Ohio
+ld60112636|2016-04-25T14:54:26.660|41.0031667|-80.4505|3|ld|ld|ld|ld60112636|ml|2.12|ld|4 km NE of Bessemer, Pennsylvania
+ld60112721|2016-04-26T02:10:23.290|41.0008333|-80.4646667|3|ld|ld|ld|ld60112721|ml|1.86|ld|3 km NE of Bessemer, Pennsylvania
+us6000p7j0|2024-11-25T05:36:04.376|40.937|-80.6673|5.159|us|us|us|us6000p7j0|ml|1.8|us|5 km NNE of Columbiana, Ohio

{gea_program-0.41.0 → gea_program-0.42.0}/gea/help/declare.md

@@ -1,10 +1,10 @@
 # The declarations sheet
 
-> Everything the operator declares about a pad, in one spreadsheet: who each well is and where, its reference elevation, its directional survey, the day rates, the one-off costs and the AFE, the fleet, the drill-string runs, and the ESP penetrator and drive. Every row is checked against the workspace before anything is written, and the same sheet can be imported again and again.
+> Everything the operator declares about a pad, in one spreadsheet: who each well is and where, its reference elevation, its directional survey, the day rates, the one-off costs and the AFE, the fleet, the drill-string runs, the ESP penetrator and drive, and the operation windows and earthquake catalogues for Operations & Seismicity. Every row is checked against the workspace before anything is written, and the same sheet can be imported again and again.
 
-**The command**: on the Setup tab, **Download the sheet** gives this workspace's sheet - every table with its header and a line saying what it takes, already filled with what is declared - and **Check the sheet** reads a sheet saved as CSV and plans each row: NEW, CHANGE (it replaces what is declared) or SAME (already declared exactly so). One error and nothing is written; with no error, **Write** (the operator role) writes the NEW and CHANGE rows. From a terminal: `gea declare --workspace C:\site --template pad3.csv` writes the sheet; `gea declare --workspace C:\site --file pad3.csv` checks it; add `--apply` to write. A directional survey is named by its file beside the sheet, so surveys are imported from the terminal (or attached on the well page).
+**The command**: on the Setup tab, **Download the sheet** gives this workspace's sheet - every table with its header and a line saying what it takes, already filled with what is declared - and **Check the sheet** reads a sheet saved as CSV and plans each row: NEW, CHANGE (it replaces what is declared) or SAME (already declared exactly so). One error and nothing is written; with no error, **Write** (the operator role) writes the NEW and CHANGE rows. From a terminal: `gea declare --workspace C:\site --template pad3.csv` writes the sheet; `gea declare --workspace C:\site --file pad3.csv` checks it; add `--apply` to write. A directional survey or an earthquake catalogue is named by its file beside the sheet, so those are imported from the terminal (or attached on the well page and the Operations & Seismicity tab).
 
-**The layout**: one table after another. A table starts with a row whose first cell is its name in brackets - `[wells]`, `[fleet]`, `[rates]`, `[items]`, `[afe]`, `[surveys]`, `[runs]`, `[components]`, `[penetrators]`, `[esp_drives]` - and whose other cells name its columns in any order; its rows leave the first cell empty. A row starting with `#` is a comment. A well is named by its id or its name. A run's components are listed in `[components]` under the run's name, from the bit up; a motor names its catalogue id, or gives its own figures (`motor_rev_per_gal` ... `motor_source`). Fleet ratings are `key=value` pairs separated by `;`, lists with `/`.
+**The layout**: one table after another. A table starts with a row whose first cell is its name in brackets - `[wells]`, `[fleet]`, `[rates]`, `[items]`, `[afe]`, `[surveys]`, `[runs]`, `[components]`, `[penetrators]`, `[esp_drives]`, `[operations]`, `[catalogs]` - and whose other cells name its columns in any order; its rows leave the first cell empty. A row starting with `#` is a comment. A well is named by its id or its name. A run's components are listed in `[components]` under the run's name, from the bit up; a motor names its catalogue id, or gives its own figures (`motor_rev_per_gal` ... `motor_source`). Fleet ratings are `key=value` pairs separated by `;`, lists with `/`.
 
 **What it writes**: through the same functions the forms and commands use, so each declaration is audited the same way under the importing user, and one `declarations.import` line records the import. It adds and replaces; it never removes: a rate that overlaps one already declared, or a fleet tool already there with another datasheet, is an error to resolve where it lives first.
 

gea_program-0.42.0/gea/help/opseis.md

@@ -0,0 +1,13 @@
+# Operations and seismicity
+
+> Each well's operations - drilling, completion, disposal, injection - set against the earthquake catalogue around it: what happened near the well while it worked and in the months after, what each event would reach under a regulator's protocol, and whether the earthquake rate near the well differs while it works from the rest of the record. The Mahoning Valley, Ohio, ships as a worked example from the public record.
+
+**The command**: the Operations & Seismicity tab. Choose the scene - your wells, or the worked example - and the protocol (British Columbia's Kiskatinaw order, Alberta's Subsurface Order No. 2, Oklahoma's completion notice, Ohio's 2014 permit conditions, Texas's response plan), the association radius (5 km by default), the days after an operation that still count (90) and the completeness magnitude. Each well shows its operations as bands on a time line, every event within the screening distance (20 km) as a circle by its distance from the well and sized by magnitude, the events table with the rig's state at an event during a drilling record, the protocol level each reaches, and the rate comparison. The operator declares operation windows (or the declarations sheet's `[operations]`) and attaches catalogue exports with the window, minimum magnitude and circle they were queried for (or `[catalogs]`); the program cannot reach a catalogue service itself, so the tab gives the ComCat query to open in a browser. From a terminal: `gea seismicity --workspace C:\site`; `--scene mahoning` for the example; `--protocols`; `--query`; `--attach FILE --start --end --min-magnitude --lat --lon --catalog-radius-km --source`; `--declare-op --well W --kind completion --start --end --source`; `--set` keeps the settings.
+
+**What it writes**: `seismicity/operations.json`, `seismicity/catalogs.json` with each catalogue file kept verbatim beside it (its SHA-256 recorded), and `seismicity/settings.json` in the workspace; each declaration, attachment, removal and change of settings a line in the audit log. The protocols ship with the program (`reference/seismicity_protocols.json`), each with its document; the worked example's catalogue (`fixtures/comcat_mahoning_1990-2026.txt`) and its wells and dates (`reference/mahoning_example.json`), each with its source.
+
+**The arithmetic**: an event's distance is the great-circle distance from the well's declared surface position (converted to WGS84). It is DURING an operation inside its window, AFTER one within the association days that follow, and OUTSIDE otherwise; an event near two wells' operations is named on both, each with the other beside it. The rate comparison counts the events at or above the completeness within the radius over the catalogue's window: n inside the operation windows (with their association days) and m outside. If one constant rate held, n would be binomial in n + m with the share of time inside; the probability of n or more is the exact conditional test for two Poisson rates. HIGHER DURING OPERATIONS means that probability is under 1 % and the rate inside is the higher; otherwise NOT DISTINGUISHED. With no event outside, the background is given as its 95 % upper bound, 3 events over its time.
+
+**The number to check**: a distance against a map; for the worked example, Northstar 1's eight events within 5 km during its injection year and the 90 days after against none in the rest of 1990 to 2026; Poland-CLL2's four events during its stimulation and one the next day; the Poland events' ML 2.44 in ComCat against the M 3.0 the regulator and the published study give - a protocol is read against its own magnitude of record.
+
+**What this page will not call a measurement**: a cause - a coincidence in time and place is what the record shows; the catalogue's completeness - declared (the query's minimum magnitude by default), not measured, and a sparse network misses small events, so a quiet background is a floor; independence - the test counts every event, so an aftershock sequence weighs as many; the distance to the lateral - it is from the surface position; a protocol's verdict - the level an event reaches by the catalogue's magnitude, while the regulator's catalogue and the permit's own conditions govern.

{gea_program-0.41.0 → gea_program-0.42.0}/gea/helplib.py

@@ -49,6 +49,7 @@ INDEX: List[tuple] = [
     ('drillstring', 'Drill string', "each run's string from the bit up, every component's usage against its service interval, and the downhole motor's statistics and stability"),
     ('declare', 'The declarations sheet', 'everything the operator declares about a pad in one spreadsheet - identity, position, elevation, surveys, rates, AFE, fleet, runs, penetrators and drives - checked row by row before anything is written'),
     ('penetrator', 'Completion - the ESP penetrator', "the wellhead penetrator's ratings from its maker's documents, each well's installation record, and the ESP drive, motor and site checked against them; the permanent magnet motor safety note"),
+    ('opseis', 'Operations and seismicity', "each well's drilling, completion and disposal windows against the earthquake catalogue around it: the events during and after each, the levels a regulator's protocol would reach, the rate during operations against the rest of the record; the Mahoning Valley worked example"),
     ('economics', 'Economics', 'each well\'s days, footage and cost by the operator\'s own declared rates, against the EIA oil and gas spot prices while it was drilled, and any series the site imports'),
     ('well3d', 'The well in 3D', 'each well\'s path from its directional survey, set among the mapped formation surfaces and contours with its picks, coloured by what was measured along it, and the drill string replayed from the record; the Volve field shipped as the worked example'),
     ('charts', 'The charts', 'a well\'s channels stacked on one axis with a linked cursor, zoom and pan from every sample, time or depth for a drilling recorder, the depth events marked, and the drilling progress of every well'),
@@ -79,7 +80,7 @@ REQUIRED_LINES = ('**The command**', '**What it writes**', '**The number to chec
 VIEW_TOPIC: Dict[str, str] = {
     'home': 'start', 'wells': 'data-in', 'well': 'drift', 'live': 'patches', 'patch': 'patches', 'files': 'files', 'alarms': 'alarms',
     'approvals': 'well-tests', 'config': 'site', 'reports': 'drift', 'verify': 'start', 'survey': 'data-in', 'jobs': 'site',
-    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'setup': 'setup', 'map': 'map', '3d': 'well3d', 'simulation': 'simulation', 'drillstring': 'drillstring', 'completion': 'penetrator', 'economics': 'economics', 'control': 'control-room', 'wall': 'control-room', 'audit': 'audit-update', 'tools': 'tools', 'catalog': 'catalog',
+    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'setup': 'setup', 'map': 'map', '3d': 'well3d', 'simulation': 'simulation', 'drillstring': 'drillstring', 'completion': 'penetrator', 'opseis': 'opseis', 'economics': 'economics', 'control': 'control-room', 'wall': 'control-room', 'audit': 'audit-update', 'tools': 'tools', 'catalog': 'catalog',
 }