gea-program 0.12.0__tar.gz → 0.14.0__tar.gz

{gea_program-0.12.0/gea_program.egg-info → gea_program-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.12.0
+Version: 0.14.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 (324 checks)
+gea accept                     # the product gate (330 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]")
@@ -584,6 +584,41 @@ it first - identifiers, allowed children, required children, enumerations,
 references - and the file validates against the published XSD. `gea help
 quakeml`; `gea quakeml` runs the labelled scene.
 
+### The well as master data names it
+
+`gea workspace --action well-identity --well <id>` names a well the way the
+operator's master data and a regulator's well file name it: the US Well
+Number (the API number, whose standard PPDM has held since 2010) taken apart
+- state and offshore code, county code, unique well and its range, sidetrack
+and event when given, and which component the number identifies (ten digits
+the Well Origin, twelve a Wellbore, fourteen an event) - and the components
+of PPDM's "What is a Well" the site can name: the Well and its one Origin at
+the declared position on its datum, the Wellbore only when the sidetrack
+code was given, the gauge station as a measured depth along the wellbore,
+the Wellhead Stream as the channels recorded at the wellhead, the Well Set
+as the site, every alias typed. The identity rides on every well row of the
+SRA packet (section 2a) and in the OSDU export's Well and Wellbore records.
+It will not assume a sidetrack, invent an injection interval or a
+completion, or name a county. `gea ppdm --action parse --number ...` takes a
+number apart from the command line; `gea help ppdm`.
+
+### Machine vibration
+
+The pump's record read the way an operations engineer expects. `gea
+workspace --action vibration-report --well <id> --record pump.csv --vib-unit
+g --rpm 1780 --group 2 --support rigid --bearing 9,7.94,39.04` writes the
+broadband r.m.s. vibration velocity over 10-1000 Hz (2-1000 Hz below 600
+r/min), the quantity ISO 20816-1 defines, and the ISO 20816-3 zone for the
+declared machine group and support class with the boundaries printed; then
+the envelope spectrum of the most impulsive band (chosen by kurtosis, or
+declared) against the bearing's defect frequencies - BPFO, BPFI, BSF, FTF
+from its geometry and the shaft speed - each MATCHED at its fundamental or
+NOT MATCHED, the inner race with its sidebands. A record in counts needs a
+sensitivity; a rate that cannot carry 1000 Hz is PARTIAL BAND, never
+promoted; the group and the support are declarations; a matched frequency
+is not a fault size. CSV or miniSEED/SAC; `gea vibration` runs the labelled
+pump; `gea help vibration`.
+
 ### Audit / Update
 
 The Audit / Update tab holds three things. The whole audit log

{gea_program-0.12.0 → gea_program-0.14.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 (324 checks)
+gea accept                     # the product gate (330 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]")
@@ -545,6 +545,41 @@ it first - identifiers, allowed children, required children, enumerations,
 references - and the file validates against the published XSD. `gea help
 quakeml`; `gea quakeml` runs the labelled scene.
 
+### The well as master data names it
+
+`gea workspace --action well-identity --well <id>` names a well the way the
+operator's master data and a regulator's well file name it: the US Well
+Number (the API number, whose standard PPDM has held since 2010) taken apart
+- state and offshore code, county code, unique well and its range, sidetrack
+and event when given, and which component the number identifies (ten digits
+the Well Origin, twelve a Wellbore, fourteen an event) - and the components
+of PPDM's "What is a Well" the site can name: the Well and its one Origin at
+the declared position on its datum, the Wellbore only when the sidetrack
+code was given, the gauge station as a measured depth along the wellbore,
+the Wellhead Stream as the channels recorded at the wellhead, the Well Set
+as the site, every alias typed. The identity rides on every well row of the
+SRA packet (section 2a) and in the OSDU export's Well and Wellbore records.
+It will not assume a sidetrack, invent an injection interval or a
+completion, or name a county. `gea ppdm --action parse --number ...` takes a
+number apart from the command line; `gea help ppdm`.
+
+### Machine vibration
+
+The pump's record read the way an operations engineer expects. `gea
+workspace --action vibration-report --well <id> --record pump.csv --vib-unit
+g --rpm 1780 --group 2 --support rigid --bearing 9,7.94,39.04` writes the
+broadband r.m.s. vibration velocity over 10-1000 Hz (2-1000 Hz below 600
+r/min), the quantity ISO 20816-1 defines, and the ISO 20816-3 zone for the
+declared machine group and support class with the boundaries printed; then
+the envelope spectrum of the most impulsive band (chosen by kurtosis, or
+declared) against the bearing's defect frequencies - BPFO, BPFI, BSF, FTF
+from its geometry and the shaft speed - each MATCHED at its fundamental or
+NOT MATCHED, the inner race with its sidebands. A record in counts needs a
+sensitivity; a rate that cannot carry 1000 Hz is PARTIAL BAND, never
+promoted; the group and the support are declarations; a matched frequency
+is not a fault size. CSV or miniSEED/SAC; `gea vibration` runs the labelled
+pump; `gea help vibration`.
+
 ### Audit / Update
 
 The Audit / Update tab holds three things. The whole audit log

{gea_program-0.12.0 → gea_program-0.14.0}/gea/__init__.py

@@ -122,7 +122,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.12.0"
+__version__ = "0.14.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.12.0 → gea_program-0.14.0}/gea/__main__.py

@@ -282,7 +282,7 @@ def main(argv=None) -> int:
                       choices=["init", "add-file", "add-catalog", "add-live", "remove", "list", "migrate", "refresh", "audit",
                                "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"])
+                               "set-well", "sra-define", "sra-report", "associate", "osdu-export", "quakeml-export", "well-identity", "vibration-report"])
     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")
@@ -317,6 +317,15 @@ def main(argv=None) -> int:
     p_ws.add_argument("--operator-org", type=str, default="", help="osdu-export: the operator's Organisation record id on the platform")
     p_ws.add_argument("--out", type=str, default=None, help="osdu-export: the folder to write the manifest and files into; quakeml-export: the file to write")
     p_ws.add_argument("--agency", type=str, default="", help="quakeml-export: the agencyID written in creationInfo (default: the site's name)")
+    p_ws.add_argument("--record", type=str, default=None, help="vibration-report: the machine record (CSV with a timestamp or elapsed-seconds column, or miniSEED/SAC)")
+    p_ws.add_argument("--channel", type=str, default=None, help="vibration-report: the channel to assess (default: the first)")
+    p_ws.add_argument("--vib-unit", type=str, default="g", help="vibration-report: the channel's unit - g, m/s2, mm/s, in/s, or counts with --sensitivity")
+    p_ws.add_argument("--sensitivity", type=float, default=None, help="vibration-report: units per count, when the record is in counts")
+    p_ws.add_argument("--rpm", type=float, default=None, help="vibration-report: the shaft speed, r/min (declared)")
+    p_ws.add_argument("--group", type=int, choices=[1, 2], default=None, help="vibration-report: ISO 20816-3 machine group - 1 above 300 kW, 2 from 15 to 300 kW (declared)")
+    p_ws.add_argument("--support", type=str, choices=["rigid", "flexible"], default=None, help="vibration-report: the support class (declared)")
+    p_ws.add_argument("--bearing", type=str, default=None, help="vibration-report: elements,ball_mm,pitch_mm[,contact_deg] - the bearing geometry (declared)")
+    p_ws.add_argument("--demod-band", type=float, nargs=2, default=None, help="vibration-report: the demodulation band in Hz (default: chosen by kurtosis)")
     p_ws.add_argument("--depth-km", type=float, default=6.0, help="associate: the hypocentral depth the location is made under, km (declared)")
     p_ws.add_argument("--rms-tol", type=float, default=0.15, help="associate: the RMS residual an event must fit within, s")
     p_ws.add_argument("--wells", type=str, nargs="+", default=None, help="add-site: well ids of this workspace")
@@ -400,6 +409,21 @@ def main(argv=None) -> int:
 
     p_osdu = sub.add_parser("osdu", help="the OSDU-shaped export: the self-test on a labelled site")
     p_osdu.add_argument("--action", choices=["selftest"], default="selftest")
+    p_vib = sub.add_parser("vibration", help="machine vibration: ISO 20816-3 zone and bearing envelope analysis on a record, or the self-test")
+    p_vib.add_argument("--action", choices=["selftest", "assess"], default="selftest")
+    p_vib.add_argument("--record", type=str, default=None, help="assess: the record (CSV with a time column, or miniSEED/SAC)")
+    p_vib.add_argument("--channel", type=str, default=None)
+    p_vib.add_argument("--unit", type=str, default="g", help="g, m/s2, mm/s, in/s, or counts with --sensitivity")
+    p_vib.add_argument("--sensitivity", type=float, default=None)
+    p_vib.add_argument("--rpm", type=float, default=None)
+    p_vib.add_argument("--group", type=int, choices=[1, 2], default=None)
+    p_vib.add_argument("--support", type=str, choices=["rigid", "flexible"], default=None)
+    p_vib.add_argument("--bearing", type=str, default=None, help="elements,ball_mm,pitch_mm[,contact_deg]")
+    p_vib.add_argument("--demod-band", type=float, nargs=2, default=None)
+    p_vib.add_argument("--json", action="store_true")
+    p_ppdm = sub.add_parser("ppdm", help="the well named as the US Well Number and PPDM name it: take a number apart, or run the self-test")
+    p_ppdm.add_argument("--action", choices=["selftest", "parse"], default="selftest")
+    p_ppdm.add_argument("--number", type=str, default=None, help="parse: a US Well Number (10, 12 or 14 digits, dashes optional)")
     p_qml = sub.add_parser("quakeml", help="the QuakeML 1.2 catalogue export: the self-test on the association leg's labelled scene")
     p_qml.add_argument("--action", choices=["selftest"], default="selftest")
     p_qml.add_argument("--out", type=str, default=None, help="where to leave the self-test's file (default: a temporary folder)")
@@ -1500,6 +1524,57 @@ def main(argv=None) -> int:
             return 0
         print(f"notifications: {'configured' if n.cfg else 'not configured'}" + (f" - {len(n.cfg['channels'])} channel(s), {len(n.cfg['rules'])} rule(s), quiet {n.cfg['quiet_s']} s" if n.cfg else " (gea notify --example)"))
         return 0
+    elif a.cmd == "vibration":
+        from . import vibration as _V
+        if a.action == "assess":
+            if not a.record:
+                raise SystemExit("vibration --action assess needs --record")
+            brg = None
+            if a.bearing:
+                parts = [float(x) for x in a.bearing.split(",")]
+                if len(parts) not in (3, 4):
+                    raise SystemExit("--bearing is elements,ball_mm,pitch_mm[,contact_deg]")
+                brg = {"n_elements": int(parts[0]), "d_mm": parts[1], "D_mm": parts[2], "contact_deg": parts[3] if len(parts) == 4 else 0.0}
+            try:
+                rec = _V.read_record(a.record, a.channel)
+            except ValueError as e:
+                raise SystemExit(f"vibration: {e}")
+            r = _V.assess(rec["x"], rec["fs"], a.unit, a.rpm, group=a.group, support=a.support, bearing=brg,
+                          band_hz=tuple(a.demod_band) if a.demod_band else None, label=f"{rec['name']}:{rec['channel']}", sensitivity=a.sensitivity)
+            r["gaps"] = list(r["gaps"]) + list(rec["notes"])
+            if a.json:
+                print(json.dumps({k: v for k, v in r.items()}, indent=1, default=str))
+            else:
+                print(_V.report_text(r))
+            return 0 if r["status"] == "ASSESSED" else 1
+        r = _V.selftest()
+        print(f"vibration selftest [{r['label']}]: {r['status']}")
+        for k, v in r["checks"].items():
+            print(f"  {'ok ' if v else 'BAD'} {k}")
+        print(_V.report_text(r["assessment"]))
+        return 0 if r["status"] == "OK" else 1
+    elif a.cmd == "ppdm":
+        from . import ppdm as _P
+        if a.action == "parse":
+            if not a.number:
+                raise SystemExit("ppdm --action parse needs --number")
+            r = _P.parse_well_number(a.number)
+            print(f"{r['input']}: {r['status']}" + (f" - {r['form']}; identifies the {r['identifies'].replace('_', ' ')}" if r.get('form') and r['status'] == 'VALID' else ''))
+            if r.get('state'):
+                print(f"  state {r['state']['code']} ({r['state']['name'] or 'not a state code'}), county {r['county']['code']}, unique well {r['unique_well']['code']}"
+                      f" ({r['unique_well']['range'] or '-'})" + (f"; sidetrack {r['sidetrack']['code']}: {r['sidetrack']['meaning']}" if r.get('sidetrack') else '')
+                      + (f"; event {r['event']['code']}: {r['event']['meaning']}" if r.get('event') else ''))
+            for x in r["problems"]:
+                print(f"  problem: {x}")
+            for x in r.get("notes") or []:
+                print(f"  note: {x}")
+            return 0 if r["status"] == "VALID" else 1
+        r = _P.selftest()
+        print(f"ppdm selftest [{r['label']}]: {r['status']}")
+        for k, v in r["checks"].items():
+            print(f"  {'ok ' if v else 'BAD'} {k}")
+        print(_P.report_text(r["identity"]))
+        return 0 if r["status"] == "OK" else 1
     elif a.cmd == "quakeml":
         from . import quakeml as _Q
         r = _Q.selftest(a.out)
@@ -1765,6 +1840,28 @@ def main(argv=None) -> int:
                                    countries=a.country, operator_org_id=a.operator_org, out_dir=a.out, actor=a.actor)
                 print(_osdu_text(r)); v = r["validate"]
                 print(f"  structure: {'ok' if v['ok'] else 'PROBLEMS'} ({v['records']} record(s))" + ('' if v['ok'] else '; ' + '; '.join(v['problems'][:5]))); return 0
+            elif a.action == "vibration-report":
+                from .vibration import report_text as _vib_text
+                if not a.well or not a.record:
+                    raise SystemExit("vibration-report needs --well <id> and --record <file>")
+                brg = None
+                if a.bearing:
+                    parts = [float(x) for x in a.bearing.split(",")]
+                    if len(parts) not in (3, 4):
+                        raise SystemExit("--bearing is elements,ball_mm,pitch_mm[,contact_deg]")
+                    brg = {"n_elements": int(parts[0]), "d_mm": parts[1], "D_mm": parts[2], "contact_deg": parts[3] if len(parts) == 4 else 0.0}
+                try:
+                    r = ws.vibration_report(a.well, a.record, channel=a.channel, unit=a.vib_unit, rpm=a.rpm, group=a.group, support=a.support, bearing=brg,
+                                            band_hz=a.demod_band, sensitivity=a.sensitivity, actor=a.actor)
+                except ValueError as e:
+                    raise SystemExit(f"vibration-report: {e}")
+                print(_vib_text(r)); print("  written:", r["paths"].get("md") or r["paths"]); return 0
+            elif a.action == "well-identity":
+                from .ppdm import report_text as _ppdm_text
+                if not a.well:
+                    raise SystemExit("well-identity needs --well <id>")
+                r = ws.well_identity(a.well)
+                print(_ppdm_text(r)); return 0
             elif a.action == "quakeml-export":
                 from .quakeml import report_text as _qml_text
                 if not a.site:

{gea_program-0.12.0 → gea_program-0.14.0}/gea/acceptance_tests.py

@@ -5104,6 +5104,221 @@ def section_bf_quakeml(tmp: str) -> None:
        "a station with no position gets a pick but an arrival without azimuth or distance and is named as a gap; neither is invented; the misfit "
        "region of 1 km by 2 km becomes a 1000 m horizontal uncertainty and a latitude uncertainty of one kilometre in degrees")
 
+
+def section_bg_ppdm(tmp: str) -> None:
+    """Section BG - the well named the way the operator's master data names it: the US Well Number taken
+    apart and checked, the PPDM "What is a Well" components the site can name, and the identity carried into
+    the SRA packet and the OSDU export without a sidetrack, an interval or a county name being invented."""
+    import csv as _csv
+    import subprocess as _sp
+    from datetime import datetime as _dt, timedelta as _td, timezone as _tz
+    from . import ppdm as P
+    from . import helplib as H
+    from .client_reports import forbidden_terms
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bg"); d.mkdir()
+
+    # -- the number ----------------------------------------------------------------------------------
+    r = P.selftest()
+    a = P.parse_well_number("42 329 39123 01 00")
+    b = P.parse_well_number("4232939123")
+    ok(r["status"] == "OK" and all(r["checks"].values())
+       and a["status"] == "VALID" and a["api14"] == "42-329-39123-01-00" and a["identifies"] == "event" and a["event"]["meaning"].startswith("the original")
+       and b["status"] == "VALID" and b["api10"] == "42-329-39123" and b["api12"] is None and b["identifies"] == "well_origin"
+       and len(P.STATE_CODES) == 55 and P.STATE_CODES["42"] == "Texas" and P.STATE_CODES["60"] == "Northern Gulf of Mexico" and "52" not in P.STATE_CODES
+       and P.parse_well_number("42-329-61000")["unique_well"]["range"] == "reserved" and P.parse_well_number("42-329-00500")["unique_well"]["range"] == "historical"
+       and P.parse_well_number("42-329-96000")["unique_well"]["range"] == "exempt"
+       and "booklet" in P.parse_well_number("42-329-39123")["county"]["basis"],
+       "BG1 a US Well Number in any written form is taken apart to the standard - state and offshore codes named (51 states and territories, four "
+       "offshore areas, 52-54 reserved), the county code kept as a code because the county booklet is not held, the unique well placed in the "
+       "standard's historical, current, reserved or exempt range - and ten, twelve and fourteen digits name the Well Origin, a Wellbore and an "
+       "event; a reserved or unknown state, a wrong length, a stray letter and a zero unique well are each named as a problem, never repaired")
+
+    # -- the identity, and what it will not name ---------------------------------------------------
+    ident = r["identity"]; c = ident["components"]
+    ok(c["well"]["identifier"] == "42-329-39123" and c["wellbore"]["identifier"] is None and "sidetrack code" in c["wellbore"]["detail"]
+       and c["well_origin"]["position"]["datum"] == "NAD27" and c["wellhead_stream"]["direction"] == "into the ground"
+       and c["wellbore_contact_interval"]["identifier"] is None and c["wellbore_completion"]["identifier"] is None
+       and all(k in P.COMPONENTS for k in ("well", "well_origin", "wellbore", "wellbore_segment", "wellbore_contact_interval", "wellbore_completion", "wellhead_stream", "well_set"))
+       and "one and only one" in P.COMPONENTS["wellbore_segment"] and "not an activity" in P.COMPONENTS["wellbore_completion"]
+       and sum("not given" in g for g in ident["gaps"]) == 1 and sum("not held here" in g for g in ident["gaps"]) == 1,
+       "BG2 the identity names the Well and its Origin at the declared position on its datum, the Wellhead Stream with its direction, the Well Set "
+       "as the site and every alias typed, and names as not named - with the reason - the Wellbore when the sidetrack code was not given, and the "
+       "Contact Interval and the Completion that are the permit's and the completion report's facts; the component definitions are PPDM's")
+
+    # -- through the workspace: the packet and the OSDU export carry it ----------------------------
+    t0 = _dt(2026, 3, 1, tzinfo=_tz.utc)
+    hist = d / "swd.csv"
+    with open(hist, "w", newline="") as f:
+        w = _csv.writer(f); w.writerow(["timestamp", "P_surf_psi", "Q_bpm"])
+        for i in range(2 * 144):
+            w.writerow([(t0 + _td(seconds=600 * i)).strftime("%Y-%m-%dT%H:%M:%SZ"), "1500.0", "5.0"])
+    ws = Workspace.create(str(d / "ws"), "Pad 3", actor="tester")
+    w1 = ws.add_well_file(str(hist), display="SWD 1", actor="tester", station_md_ft=9800.0)
+    run = lambda *a: _sp.run([sys.executable, "-m", "gea", "workspace", "--path", ws.path, "--actor", "tester", *a], capture_output=True, text=True)
+    r0 = run("--action", "well-identity", "--well", w1["id"])                                       # nothing declared yet
+    r1 = run("--action", "set-well", "--well", w1["id"], "--lat", "31.96", "--lon", "-102.24", "--datum", "NAD27", "--api", "42-329-39123", "--uic", "123456",
+             "--depth-tier", "deep", "--formation", "completed below the base of the Wolfcamp", "--channel-pressure", "P_surf_psi", "--channel-rate", "Q_bpm",
+             "--rate-unit", "bbl/min", "--bhp-method", "calculated")
+    r2 = run("--action", "add-site", "--name", "PPDM block", "--wells", w1["id"], "--client", "Acme Operating")
+    r3 = run("--action", "well-identity", "--well", w1["id"])
+    r4 = run("--action", "sra-define", "--site", "PPDM-block", "--name", "Test SRA", "--lat", "31.95", "--lon", "-102.25", "--datum", "WGS84",
+             "--radius-km", "9.08", "--plan-date", "2026-02-25")
+    r5 = run("--action", "sra-report", "--site", "PPDM-block")
+    out = Path(ws.path, "reports", "sites", "PPDM-block")
+    md = (out / "sra_packet.md").read_text(encoding="utf-8"); html = (out / "sra_packet.html").read_text(encoding="utf-8")
+    pkj = json.loads((out / "sra_packet.json").read_text(encoding="utf-8"))["packet"]
+    ws2 = Workspace(ws.path)
+    o1 = ws2.osdu_export("PPDM-block", partition="opendes", acl_owners=["o"], acl_viewers=["v"], legal_tags=["t"], actor="tester")
+    man1 = json.loads(Path(o1["manifest"]).read_text(encoding="utf-8"))
+    wells1 = [x for x in man1["MasterData"] if x["kind"].endswith(":master-data--Well:1.0.0")]
+    bores1 = [x for x in man1["MasterData"] if x["kind"].endswith(":master-data--Wellbore:1.0.0")]
+    ws2.set_well(w1["id"], disposal={"api_number": "42-329-39123-01"}, actor="tester")
+    o2 = ws2.osdu_export("PPDM-block", partition="opendes", acl_owners=["o"], acl_viewers=["v"], legal_tags=["t"], actor="tester")
+    man2 = json.loads(Path(o2["manifest"]).read_text(encoding="utf-8"))
+    bores2 = [x for x in man2["MasterData"] if x["kind"].endswith(":master-data--Wellbore:1.0.0")]
+    r6 = _sp.run([sys.executable, "-m", "gea", "ppdm", "--action", "parse", "--number", "42-329-39123-01"], capture_output=True, text=True)
+    r7 = _sp.run([sys.executable, "-m", "gea", "ppdm", "--action", "parse", "--number", "53-329-39123"], capture_output=True, text=True)
+    r8 = _sp.run([sys.executable, "-m", "gea", "ppdm"], capture_output=True, text=True)
+    ident_w = pkj["wells"][0]["identity"]
+    ok(r0.returncode == 0 and "no US Well Number declared" in r0.stdout and r1.returncode == 0 and r2.returncode == 0
+       and r3.returncode == 0 and "US Well Number 42-329-39123" in r3.stdout and "state 42 (Texas)" in r3.stdout and "Wellbore: not identified" in r3.stdout
+       and "Well Set: PPDM block" in r3.stdout and "Wellhead Stream: 2 channel(s)" in r3.stdout and "into the ground" in r3.stdout
+       and "9800 ft MD" in r3.stdout and "123456 [UIC permit number]" in r3.stdout
+       and r4.returncode == 0 and r5.returncode == 0 and ident_w["us_well_number"] == "42-329-39123" and ident_w["state"] == "Texas"
+       and ident_w["wellbore"] is None and ident_w["origin_datum"] == "NAD27" and not any("sidetrack" in g or "Completion" in g for g in pkj["gaps"])
+       and "Well identity" in md and "42-329-39123" in md and "not identified" in md and "US Well Number and PPDM" in html
+       and not forbidden_terms(md) and not forbidden_terms(html)
+       and len(wells1) == 1 and wells1[0]["data"]["FacilityID"] == "42-329-39123"
+       and any(al["AliasName"] == "42-329-39123" and al["AliasNameTypeID"].endswith("AliasNameType:USWellNumber:") for al in wells1[0]["data"]["NameAliases"])
+       and wells1[0]["data"]["ExtensionProperties"]["gea"]["us_well_number"]["state"]["name"] == "Texas"
+       and len(bores1) == 1 and bores1[0]["data"]["FacilityID"] == w1["id"] and "not identified" in bores1[0]["data"]["ExtensionProperties"]["gea"]["wellbore_identifier"]
+       and bores2[0]["data"]["FacilityID"] == "42-329-39123-01" and bores2[0]["data"]["ExtensionProperties"]["gea"]["wellbore_identifier"] == "42-329-39123-01"
+       and o2["validate"]["ok"]
+       and r6.returncode == 0 and "identifies the wellbore" in r6.stdout and r7.returncode == 1 and "reserved" in r7.stdout
+       and r8.returncode == 0 and "ppdm selftest" in r8.stdout
+       and any(t["topic"] == "ppdm" for t in H.topics()) and not H.check("ppdm")
+       and "sidetrack code" in (pkg / "help" / "ppdm.md").read_text(encoding="utf-8").split("will not call a measurement")[1],
+       "BG3 `--action well-identity` names a bare well as unidentified and a declared one by its US Well Number, state, origin datum, wellbore "
+       "standing, gauge depth, wellhead stream, well set and typed aliases; the SRA packet carries the identity on every well row and in its own "
+       "table (section 2a) without counting its gaps against the packet, and the packet's prose passes the vocabulary gate; the OSDU export's Well "
+       "record carries the ten-digit number as FacilityID and a typed alias with the state in the extension, and its Wellbore record keeps the "
+       "program's id and says the sidetrack code was not given until a twelve-digit number is declared, when it carries that; `gea ppdm` parses "
+       "a number from the command line with the exit code saying whether it is valid, and runs the self-test; the help page names the sidetrack "
+       "it will not assume")
+
+
+def section_bh_vibration(tmp: str) -> None:
+    """Section BH - machine vibration: the ISO 20816-3 zone of the declared machine from the broadband r.m.s.
+    velocity, and the bearing's defect frequencies found or not found in the envelope spectrum of the most
+    impulsive band; the declarations named as declarations, the band's limits named, no fault size claimed."""
+    import csv as _csv
+    import subprocess as _sp
+    import numpy as _np
+    from . import vibration as V
+    from . import seismic as S
+    from . import helplib as H
+    from .client_reports import forbidden_terms
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bh"); d.mkdir()
+
+    # -- the self-test on the labelled pump ----------------------------------------------------------
+    r = V.selftest()
+    a = r["assessment"]
+    ok(r["status"] == "OK" and all(r["checks"].values()) and r["label"] == "SIMULATION_SELF_TEST"
+       and a["zone"]["zone"] == "C" and abs(a["broadband"]["rms_mm_s"] - r["truth"]["unbalance_rms_mm_s"] * (1 + 0.09) ** 0.5) < 0.3
+       and a["envelope"]["match"]["matched"] == ["BPFO"] and len(a["envelope"]["match"]["rows"]["BPFO"]["harmonics_found"]) == 3
+       and r["inner"]["envelope"]["match"]["matched"] == ["BPFI"] and len(r["inner"]["envelope"]["match"]["rows"]["BPFI"]["sidebands"]["found"]) == 2
+       and V.ZONE_BOUNDARIES == {(1, "rigid"): (2.3, 4.5, 7.1), (1, "flexible"): (3.5, 7.1, 11.0), (2, "rigid"): (1.4, 2.8, 4.5), (2, "flexible"): (2.3, 4.5, 7.1)}
+       and V.BAND_HZ == (10.0, 1000.0) and V.BAND_LOW_SPEED_HZ == (2.0, 1000.0) and V.LOW_SPEED_RPM == 600.0
+       and abs(V.bearing_frequencies(1780, 9, 7.94, 39.04)["BPFI"] - 0.5 * 9 * (1780 / 60) * (1 + 7.94 / 39.04)) < 1e-3
+       and abs(V.bearing_frequencies(1780, 9, 7.94, 39.04)["BSF"] - (39.04 / (2 * 7.94)) * (1780 / 60) * (1 - (7.94 / 39.04) ** 2)) < 1e-3
+       and abs(V.bearing_frequencies(1780, 9, 7.94, 39.04)["FTF"] - 0.5 * (1780 / 60) * (1 - 7.94 / 39.04)) < 1e-3
+       and abs(V.bearing_frequencies(1780, 9, 7.94, 39.04, 30.0)["BPFO"] - 0.5 * 9 * (1780 / 60) * (1 - 7.94 / 39.04 * _np.cos(_np.radians(30)))) < 1e-3,
+       "BH1 the self-test on a labelled pump at 1780 r/min: the broadband r.m.s. velocity recovers the unbalance line put into the record to within "
+       "8% and places a Group 2 rigid machine in zone C as the truth says; the most impulsive band is chosen and the outer-race fault is matched at "
+       "its fundamental and two harmonics with the inner race, the ball and the cage not matched; an inner-race scene is matched at BPFI with both "
+       "sidebands at the shaft speed and the outer race not matched; the zone boundaries are ISO 20816-3's for both groups and both supports, the "
+       "band is ISO 20816-1's, and the four defect frequencies are the kinematic formulas including the contact angle")
+
+    # -- what it will not call a measurement ----------------------------------------------------------
+    sc = V.synthetic_scene(seconds=2.0)
+    slow = V.assess(sc["acc_m_s2"][::10], sc["fs"] / 10.0, "m/s2", sc["rpm"], group=2, support="rigid", bearing=sc["bearing"])
+    short = V.assess(sc["acc_m_s2"][:int(0.5 * sc["fs"])], sc["fs"], "m/s2", sc["rpm"], group=2, support="rigid", bearing=sc["bearing"])
+    nod = V.assess(sc["acc_m_s2"], sc["fs"], "m/s2", None)
+    cnt = V.assess(_np.round(sc["acc_m_s2"] / 9.80665 / 1e-4), sc["fs"], "counts", sc["rpm"], group=2, support="rigid", bearing=sc["bearing"])
+    sens = V.assess(_np.round(sc["acc_m_s2"] / 9.80665 / 1e-4), sc["fs"], "g", sc["rpm"], group=2, support="rigid", bearing=sc["bearing"], sensitivity=1e-4)
+    low = V.assess(sc["acc_m_s2"], sc["fs"], "m/s2", 450.0, group=1, support="flexible")
+    declared_band = V.assess(sc["acc_m_s2"], sc["fs"], "m/s2", sc["rpm"], group=2, support="rigid", bearing=sc["bearing"], band_hz=(2000.0, 4000.0))
+    ok(slow["broadband"]["band_partial"] and slow["broadband"]["band_hz"][1] < 1000 and slow["zone"]["zone_qualified"] == "PARTIAL BAND"
+       and any("PARTIAL BAND" in g for g in slow["gaps"])
+       and any("shorter than one second" in g for g in short["gaps"])
+       and nod["zone"] is None and nod["status"] == "PARTIAL" and any("no shaft speed" in g for g in nod["gaps"]) and any("group" in g for g in nod["gaps"])
+       and any("bearing" in g for g in nod["gaps"]) and nod["envelope"]["match"] is None and len(nod["envelope"]["peaks"]) > 0
+       and cnt["status"] == "NOT ASSESSED" and cnt["broadband"]["status"] == "NOT EVALUATED" and cnt["envelope"]["match"]["matched"] == ["BPFO"]
+       and sens["status"] == "ASSESSED" and abs(sens["broadband"]["rms_mm_s"] - a["broadband"]["rms_mm_s"]) < 0.3 and sens["declared"]["sensitivity"] == 1e-4
+       and low["broadband"]["band_hz"][0] == 2.0 and low["zone"]["boundaries_mm_s"] == {"A/B": 3.5, "B/C": 7.1, "C/D": 11.0}
+       and declared_band["envelope"]["band"]["status"] == "DECLARED" and declared_band["envelope"]["band"]["band_hz"] == [2000.0, 4000.0]
+       and declared_band["envelope"]["match"]["matched"] == ["BPFO"]
+       and "fault size" in " ".join(a["not_a_measurement"]) and "declared" in " ".join(a["not_a_measurement"]),
+       "BH2 a record whose rate cannot carry 1000 Hz is evaluated to its own Nyquist frequency and marked PARTIAL BAND, never promoted; a record "
+       "under a second is named; without a shaft speed, a group or a bearing the broadband value is stated, the zone is not, the envelope peaks "
+       "are listed and nothing is matched; a record in counts gets no mm/s and no zone but its envelope is still read, and with a declared "
+       "sensitivity it agrees with the same record in g; below 600 r/min the band starts at 2 Hz and Group 1 flexible has its own boundaries; a "
+       "declared demodulation band is used as declared; the assessment says it is not a fault size and that the machine is a declaration")
+
+    # -- through the workspace and the command line, from a CSV and from a miniSEED record ------------
+    csvp = d / "pump.csv"
+    with open(csvp, "w", newline="") as f:
+        w = _csv.writer(f); w.writerow(["elapsed_s", "acc_g", "temp_C"])
+        for i, x in enumerate(sc["acc_m_s2"]):
+            w.writerow([f"{i / sc['fs']:.6f}", f"{x / 9.80665:.6f}", "41.0"])
+    counts = _np.round(sc["acc_m_s2"] / 9.80665 / 1e-4).astype(_np.int32)
+    S.write_mseed([S.Trace("XX", "PUMP", "", "ACC", 1700000000.1234567, sc["fs"], counts, "synthetic", "INT32")], str(d / "pump.mseed"))
+    back = S.read_any(str(d / "pump.mseed"))
+    hist = d / "swd.csv"
+    with open(hist, "w", newline="") as f:
+        w = _csv.writer(f); w.writerow(["timestamp", "P_surf_psi"])
+        for h in range(24):
+            w.writerow([f"2026-03-01T{h:02d}:00:00Z", "1500"])
+    ws = Workspace.create(str(d / "ws"), "Pad 3", actor="tester")
+    w1 = ws.add_well_file(str(hist), display="SWD 1", actor="tester", station_md_ft=9800.0)
+    run = lambda *a: _sp.run([sys.executable, "-m", "gea", "workspace", "--path", ws.path, "--actor", "tester", *a], capture_output=True, text=True)
+    r1 = run("--action", "vibration-report", "--well", w1["id"], "--record", str(csvp), "--channel", "acc_g", "--vib-unit", "g", "--rpm", "1780",
+             "--group", "2", "--support", "rigid", "--bearing", "9,7.94,39.04")
+    r0 = run("--action", "vibration-report", "--well", w1["id"], "--record", str(csvp), "--channel", "nope")
+    out = Path(ws.path, "reports", "wells", w1["id"])
+    md = (out / "vibration_report.md").read_text(encoding="utf-8"); html = (out / "vibration_report.html").read_text(encoding="utf-8")
+    js = json.loads((out / "vibration_report.json").read_text(encoding="utf-8"))
+    audit = Path(ws.path, "records", "audit.jsonl").read_text(encoding="utf-8")
+    r2 = _sp.run([sys.executable, "-m", "gea", "vibration", "--action", "assess", "--record", str(d / "pump.mseed"), "--unit", "g", "--sensitivity", "1e-4",
+                  "--rpm", "1780", "--group", "2", "--support", "rigid", "--bearing", "9,7.94,39.04"], capture_output=True, text=True)
+    r3 = _sp.run([sys.executable, "-m", "gea", "vibration", "--action", "assess", "--record", str(d / "pump.mseed"), "--unit", "counts", "--rpm", "1780",
+                  "--group", "2", "--support", "rigid"], capture_output=True, text=True)
+    r4 = _sp.run([sys.executable, "-m", "gea", "vibration"], capture_output=True, text=True)
+    help_md = (pkg / "help" / "vibration.md").read_text(encoding="utf-8")
+    ok(len(back) == 1 and back[0].npts == counts.size and not back[0].gaps and abs(back[0].starttime - 1700000000.1234567) < 2e-6
+       and r1.returncode == 0 and "ISO 20816-3 zone C" in r1.stdout and "BPFO 106.3486 Hz: MATCHED" in r1.stdout and "written:" in r1.stdout
+       and r0.returncode != 0 and "no channel" in (r0.stderr + r0.stdout)
+       and Path(ws.path, "wells", w1["id"], "machine", "pump.csv").is_file()
+       and "| **Result** | ZONE C |" in md and "Bearing defect frequencies" in md and "Group 2 (15 kW to 300 kW)" in md and "fault size" in md
+       and not forbidden_terms(md) and not forbidden_terms(html)
+       and js["assessment"]["record"]["sha256"] and js["assessment"]["zone"]["zone"] == "C" and js["assessment"]["declared"]["bearing"]["n_elements"] == 9
+       and "well.vibration" in audit and '"zone": "C"' in audit
+       and r2.returncode == 0 and "from acceleration (g), 2.0 s at 20000 Hz" in r2.stdout and "zone C" in r2.stdout and "MATCHED" in r2.stdout
+       and r3.returncode == 1 and "NOT ASSESSED" in r3.stdout and "without a sensitivity" in r3.stdout
+       and r4.returncode == 0 and "vibration selftest [SIMULATION_SELF_TEST]: OK" in r4.stdout
+       and any(t["topic"] == "vibration" for t in H.topics()) and not H.check("vibration")
+       and "fault size" in help_md.split("will not call a measurement")[1] and "2.3 / 4.5 / 7.1" in help_md,
+       "BH3 a 20 kHz record round-trips through this program's own miniSEED writer as one trace with no gap (the header's 0.1 ms time field "
+       "is coarser than a sample above 5 kHz and every record read back as a gap until blockette 1001 carried the microseconds); "
+       "`--action vibration-report` copies the record beside the well, writes the report in three forms with the zone as its result, the "
+       "declarations in their own table and the defect frequencies each matched or not, audits it with the zone and the declarations, and names "
+       "a channel that is not there; `gea vibration --action assess` reads a miniSEED record in counts with a declared sensitivity and says "
+       "NOT ASSESSED without one; the self-test runs from the command line; the help page carries the boundaries and names the fault size it will not claim")
+
 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:
@@ -5165,6 +5380,8 @@ def main() -> int:
         section_bd_association(tmp)
         section_be_osdu(tmp)
         section_bf_quakeml(tmp)
+        section_bg_ppdm(tmp)
+        section_bh_vibration(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.12.0 → gea_program-0.14.0}/gea/client_reports.py

@@ -1613,6 +1613,23 @@ def sra_packet_report(pk: dict, evaluated_at: Optional[datetime] = None, program
         f"from the centre, with every position carried to WGS84 first; {m['n_undecided']} could not be placed."],
         [Table(['Well', 'Name', 'API', 'UIC', 'Membership', 'Distance (km)', 'Depth tier', 'BHP method', 'Daily record'], wrows, 'Wells'),
          Table(['Station', 'Name', 'Kind', 'Membership', 'Distance (km)'], srows, 'Seismic stations')]))
+    # the wells named the way the operator's master data names them (v0.13.0)
+    irows = []
+    for w in pk['wells']:
+        i = w.get('identity')
+        if not i:
+            continue
+        irows.append([w['id'], i.get('us_well_number') or '-', (i.get('identifies') or '-').replace('_', ' '), i.get('state') or '-',
+                      i.get('wellbore') or 'not identified', i.get('origin_datum') or '-', '; '.join(i.get('aliases') or []),
+                      '; '.join(g.split(': ', 1)[1] if ': ' in g else g for g in (i.get('gaps') or [])) or '-'])
+    if irows:
+        secs.append(Section('2a', 'The wells as the US Well Number and PPDM name them', [
+            'Each well by its US Well Number taken apart - the state, the county, the unique well - and by the components of PPDM\'s "What is a '
+            'Well" the site can name: the Well and its one Origin at the declared surface position, the Wellbore when the sidetrack code was '
+            'given, the Well Set as the site, and every alias typed. Ten digits name the Well Origin and nothing below it; a Wellbore is named '
+            'only when the regulator\'s sidetrack code was declared. The injection interval and the completion are the permit\'s and the '
+            'completion report\'s facts and are named here as not held.'],
+            [Table(['Well', 'US Well Number', 'Identifies', 'State', 'Wellbore', 'Origin datum', 'Aliases', 'Not named'], irows, 'Well identity')]))
     n = 3
     inside_wells = [w for w in pk['wells'] if w['inside'] and w.get('months')]
     for w in inside_wells:
@@ -1686,6 +1703,64 @@ def sra_packet_report(pk: dict, evaluated_at: Optional[datetime] = None, program
                     data={'packet': pk, 'report_id': report_id, 'evaluated_at_utc': now.strftime('%Y-%m-%dT%H:%M:%SZ'), '_records': [], '_catalogue_obj': None})
 
 
+def vibration_report(r: dict, evaluated_at: Optional[datetime] = None, program_version: str = '') -> Document:
+    """One machine record through ISO 20816-3 and the envelope: the broadband value and its zone for the
+    declared machine, the demodulation band, the bearing's defect frequencies each matched or not, and every
+    declaration and gap by name. Built from `vibration.assess`; nothing is recomputed here."""
+    now = evaluated_at or _utc_now()
+    label = str(r.get('label') or r.get('record', {}).get('name') or 'machine')
+    report_id = f"VIB-{label.replace('/', '-').replace(' ', '-')[:24]}-{now.strftime('%Y%m%dT%H%M%SZ')}"
+    bb = r.get('broadband') or {}; z = r.get('zone'); env = r.get('envelope') or {}; d = r.get('declared') or {}
+    rec = r.get('record') or {}
+    result = (f"ZONE {z['zone']}" + (f" ({z['zone_qualified']})" if z.get('zone_qualified') else '')) if z else r.get('status', '-')
+    paras = []
+    if bb.get('status') == 'EVALUATED':
+        paras.append(f"The broadband r.m.s. vibration velocity is {bb['rms_mm_s']} mm/s over {bb['band_hz'][0]:g} Hz to {bb['band_hz'][1]:g} Hz"
+                     + (' - a partial band: the record cannot carry the standard\'s 1000 Hz' if bb.get('band_partial') else '')
+                     + f", from {'an' if bb['from'] == 'acceleration' else 'a'} {bb['from']} channel in {bb['unit_in']}, {bb['seconds']} s at {bb['fs_hz']:g} Hz.")
+    else:
+        paras.append(f"The broadband value was not evaluated: {bb.get('detail') or 'see the gaps'}.")
+    if z:
+        paras.append(f"For a {z['group_basis'].split(':')[0]} machine on a {z['support']} support that is ISO 20816-3 zone {z['zone']}: {z['meaning']}. "
+                     f"The boundaries for this group and support are A/B {z['boundaries_mm_s']['A/B']}, B/C {z['boundaries_mm_s']['B/C']} and C/D "
+                     f"{z['boundaries_mm_s']['C/D']} mm/s" + (f"; {z['margin_to_next_mm_s']} mm/s remain to the next boundary." if z['margin_to_next_mm_s'] is not None else '.'))
+    secs = [Section('1', 'Summary', paras)]
+    secs.append(Section('2', 'What was declared', ['The group, the support class, the shaft speed and the bearing are the operator\'s declarations; the record carries none of them.'],
+                        [Table(['Declaration', 'Value'],
+                               [['Machine group', (GROUPS_TEXT.get(d.get('group')) if d.get('group') else 'not declared')],
+                                ['Support class', d.get('support') or 'not declared'], ['Shaft speed (r/min)', d.get('rpm') if d.get('rpm') is not None else 'not declared'],
+                                ['Bearing', (f"{d['bearing']['n_elements']} elements, d {d['bearing']['d_mm']} mm, D {d['bearing']['D_mm']} mm, contact {d['bearing'].get('contact_deg', 0)}°" if d.get('bearing') else 'not declared')],
+                                ['Demodulation band', (f"{d['band_hz'][0]:g}-{d['band_hz'][1]:g} Hz, declared" if d.get('band_hz') else 'chosen by kurtosis')],
+                                ['Channel unit', d.get('unit') or '-']])]))
+    n = 3
+    if env.get('band') and env['band'].get('band_hz'):
+        b = env['band']; m = env.get('match')
+        ep = [f"The envelope was taken in {b['band_hz'][0]:g}-{b['band_hz'][1]:g} Hz ({b['status'].lower()}" + (f", kurtosis {b['kurtosis']}" if b.get('kurtosis') is not None else '')
+              + f"); the envelope spectrum's resolution is {env.get('resolution_hz')} Hz."]
+        tables = []
+        if m:
+            bf = env['bearing']
+            ep.append(f"Shaft speed {bf['fr']} Hz. {m['status']}. Basis: {m['basis']}.")
+            tables.append(Table(['Defect frequency', 'Hz', 'Standing', 'Found at (Hz)', 'Sidebands at fr'],
+                                [[k, v['frequency_hz'], v['standing'], ', '.join(f"{h['found_hz']} ({h['harmonic']}x)" for h in v['harmonics_found']) or '-',
+                                  (', '.join(str(x) for x in v['sidebands']['found']) or 'none') if v.get('sidebands') else '-'] for k, v in m['rows'].items()], 'Bearing defect frequencies'))
+        elif env.get('peaks'):
+            ep.append('No bearing geometry was declared: the envelope spectrum\'s largest peaks are listed and nothing is matched.')
+            tables.append(Table(['Peak (Hz)', 'Amplitude', 'Over median'], [[p['f_hz'], _fmt(p['amplitude']), p.get('over_median')] for p in env['peaks'][:10]], 'Envelope spectrum peaks'))
+        secs.append(Section(str(n), 'The envelope spectrum', ep, tables)); n += 1
+    secs.append(Section(str(n), 'What needs attention', list(r.get('gaps') or []) or ['Nothing: every declaration was made and the record carries the band.'])); n += 1
+    secs.append(Section(str(n), 'What this report does not call a measurement', [x.rstrip('.') + '.' for x in (r.get('not_a_measurement') or [])]))
+    front = [['Report ID', report_id], ['Record', rec.get('name') or label], ['Channel', rec.get('channel') or '-'],
+             ['Generated (UTC)', now.strftime('%Y-%m-%dT%H:%M:%SZ')],
+             ['Program', f'{PROGRAM_NAME}' + (f' build {program_version}' if program_version else '')], ['Result', result]]
+    return Document(title=f'{PROGRAM_NAME} - Machine Vibration Report', report_id=report_id, front=front, sections=secs,
+                    footer='ISO 20816-1 quantity, ISO 20816-3 zones for the declared machine; the envelope against the declared bearing. Nothing here is a fault size.',
+                    data={'assessment': r, 'report_id': report_id, 'evaluated_at_utc': now.strftime('%Y-%m-%dT%H:%M:%SZ'), '_records': [], '_catalogue_obj': None})
+
+
+GROUPS_TEXT = {1: 'Group 1 (above 300 kW)', 2: 'Group 2 (15 kW to 300 kW)'}
+
+
 def forbidden_terms(text: str) -> List[str]:
     low = text.lower()
     return [t for t in FORBIDDEN_TERMS if t in low]

gea_program-0.14.0/gea/help/ppdm.md

@@ -0,0 +1,11 @@
+# The well as master data names it
+
+> The US Well Number taken apart - state, county, unique well, sidetrack, event - and the components of PPDM's "What is a Well" the site can name for each well: the Well and its one Origin, the Wellbore, the Wellhead Stream, the Well Set, and every alias typed.
+
+**The command**: `gea workspace --path C:\site --action well-identity --well <id>` prints a well's identity from its declarations (`set-well --api --uic --lat --lon --datum`) and the site it belongs to. `gea ppdm --action parse --number 42-329-39123-01` takes a number apart and names every way it is not valid. `gea ppdm` runs the self-test. The identity also rides on every well row of the SRA packet (section 2a) and in the OSDU export's Well record (the ten-digit number as a typed alias and `FacilityID`, the state and the parts in the extension; the Wellbore record's `FacilityID` is the twelve-digit number when it was given).
+
+**What it writes**: the US Well Number in the standard's form `SS-CCC-UUUUU-SS-EE` (the standard the API transferred to the PPDM Association in 2010; PPDM's 2013 US Well Number is its successor): the state or offshore code and its name, the county code, the unique well number and which of the standard's ranges it falls in (historical, current, reserved, exempt), the sidetrack code and the event sequence when given, and which component the number identifies - ten digits the Well Origin, twelve a Wellbore, fourteen an event. Then the components: the Well; the Well Origin at the declared surface position on its datum; the Wellbore, identified only when the sidetrack code was given; the gauge station as a measured depth along the wellbore; the Wellhead Stream as the channels recorded at the wellhead with the declared pressure, rate and bottomhole channels named and the direction (into the ground for a disposal well); the Well Set as the site; the aliases - the operator's name, the program's id, the US Well Number, the UIC permit - each typed.
+
+**The number to check**: `IDENTIFIED` or `UNIDENTIFIED` on the identity, `VALID` or `INVALID` on the number, and the `gap:` lines - every component the site cannot name is named as not named, with the reason.
+
+**What this page will not call a measurement**: a sidetrack code that was not given - ten digits name the Well Origin and nothing below it, and "00" is the original hole only when the regulator assigned it, so a Wellbore is not identified from a ten-digit number. A Wellbore Contact Interval (the injection interval) or a Wellbore Completion - those are the permit's and the completion report's facts, and the identity names them as not held. A county name - the standard's state and county booklet carries it, this program does not, and a county code is checked for its shape only. A state from a reserved code (52-54) or a code outside the standard.