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

{gea_program-0.13.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.13.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 (327 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]")
@@ -602,6 +602,23 @@ 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.13.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 (327 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]")
@@ -563,6 +563,23 @@ 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.13.0 → gea_program-0.14.0}/gea/__init__.py

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

{gea_program-0.13.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", "well-identity"])
+                               "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,18 @@ 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)")
@@ -1503,6 +1524,35 @@ 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":
@@ -1790,6 +1840,22 @@ 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:

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

@@ -5208,6 +5208,117 @@ def section_bg_ppdm(tmp: str) -> None:
        "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:
@@ -5270,6 +5381,7 @@ def main() -> int:
         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.13.0 → gea_program-0.14.0}/gea/client_reports.py

@@ -1703,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/vibration.md

@@ -0,0 +1,11 @@
+# Machine vibration
+
+> The pump's record read the way an operations engineer expects: which ISO 20816-3 zone the machine is in, and - when it is not A or B - what the bearings are doing, by envelope analysis against the bearing's own defect frequencies.
+
+**The command**: `gea workspace --path C:\site --action vibration-report --well <id> --record pump.csv --channel acc --vib-unit g --rpm 1780 --group 2 --support rigid --bearing 9,7.94,39.04` writes `reports/wells/<id>/vibration_report.{md,html,json}` and copies the record beside the well under `machine/` with its hash. The record is a delimited export whose first column is a timestamp or elapsed seconds (the historian reader) or a miniSEED/SAC record (the seismic reader; counts as recorded, so give the unit and `--sensitivity` units-per-count). The unit (`--vib-unit` in the workspace, `--unit` in `gea vibration`) is g, m/s2, mm/s or in/s. `--demod-band lo hi` declares the demodulation band instead of letting kurtosis choose it. `gea vibration --action assess --record ...` does the same without a workspace; `gea vibration` runs the self-test on a labelled pump record.
+
+**What it writes**: the broadband r.m.s. vibration velocity in mm/s over 10 Hz to 1000 Hz (2 Hz to 1000 Hz below 600 r/min), the quantity ISO 20816-1 defines - from an acceleration channel by integration in the frequency domain inside the band, from a velocity channel by band-limiting; the ISO 20816-3 zone for the declared machine group (Group 1 above 300 kW; Group 2 from 15 kW to 300 kW) and support class (rigid when the machine-foundation system's lowest natural frequency is at least 1.25 times the main excitation frequency, otherwise flexible), with the boundaries printed (Group 1 rigid 2.3 / 4.5 / 7.1; Group 1 flexible 3.5 / 7.1 / 11.0; Group 2 rigid 1.4 / 2.8 / 4.5; Group 2 flexible 2.3 / 4.5 / 7.1 mm/s for A/B, B/C, C/D) and the margin to the next; the demodulation band (chosen as the candidate band with the highest kurtosis, because a bearing fault's impacts are impulsive and kurtosis is their measure, or declared); the envelope spectrum of the analytic signal in that band; the bearing's defect frequencies from its geometry and the shaft speed - BPFO, BPFI, BSF, FTF - each MATCHED (a peak at the fundamental within 2% or one resolution bin, at least four times the spectrum's median, harmonics at the same tolerance, and for the inner race the sidebands at the shaft speed) or NOT MATCHED.
+
+**The number to check**: the zone, the r.m.s. value it was set by, and `FAULT FREQUENCY PRESENT` or `NO FAULT FREQUENCY MATCHED` with the matched frequency named. `PARTIAL BAND` on the zone means the record's rate cannot carry 1000 Hz and the value was taken to the record's own Nyquist frequency.
+
+**What this page will not call a measurement**: a machine group or a support class - the record does not say what the machine is standing on, and both are declared. A zone from a record that cannot carry the band, which is marked PARTIAL BAND and not promoted; or from a record shorter than a second. A fault size - a matched frequency says the bearing rings at it, not how far the fault has gone. A defect frequency without the bearing's geometry - without it the envelope spectrum's peaks are listed and nothing is matched. A match on harmonics alone - the harmonics of one defect frequency fall near multiples of another, so the fundamental is required. An mm/s value from a record in counts without a declared sensitivity.

{gea_program-0.13.0 → gea_program-0.14.0}/gea/helplib.py

@@ -42,6 +42,7 @@ INDEX: List[tuple] = [
     ('osdu', 'The OSDU-shaped export', 'the site as the manifest an operator\'s data platform loads'),
     ('quakeml', 'The QuakeML catalogue export', 'the site\'s own events in the format the regulator\'s catalogue tools read'),
     ('ppdm', 'The well as master data names it', 'the US Well Number taken apart and the PPDM "What is a Well" components the site can name'),
+    ('vibration', 'Machine vibration', 'the pump\'s record through the ISO 20816-3 zones and bearing envelope analysis'),
     ('doctor', 'Which code is running', 'gea doctor and the serve start-up gate'),
     ('audit-update', 'Audit / Update', 'the whole audit log with filters, the program against PyPI, every report against its source'),
     ('upkeep', 'Upkeep', 'housekeeping, sessions, the TLS proxy, the load test'),

{gea_program-0.13.0 → gea_program-0.14.0}/gea/seismic.py

@@ -80,6 +80,14 @@ def _btime_to_epoch(year: int, doy: int, hour: int, minute: int, sec: int, frac0
     return d.timestamp() + frac0001 / 10000.0
 
 
+def _epoch_to_btime_usec(t: float) -> Tuple[int, int, int, int, int, int, int]:
+    """The header's 0.1 ms field and the microseconds left over for blockette 1001 (0 to 99)."""
+    d = _dt.datetime.fromtimestamp(t, tz=_dt.timezone.utc)
+    us = int(round(d.microsecond))
+    frac = us // 100
+    return d.year, d.timetuple().tm_yday, d.hour, d.minute, d.second, frac, us - frac * 100
+
+
 def _epoch_to_btime(t: float) -> Tuple[int, int, int, int, int, int]:
     d = _EPOCH + _dt.timedelta(seconds=float(t))
     frac = int(round((d.microsecond / 1e6) * 10000.0))
@@ -597,15 +605,19 @@ def write_mseed(traces: Sequence[Trace], path: str, encoding: str = 'STEIM1', re
                     body = np.asarray(data[i:i + n], dtype='>f8').tobytes().ljust(payload_room, b'\x00')
                 if n == 0:
                     raise ValueError("no sample fits in a record")
-                year, doy, hh, mm, ss, frac = _epoch_to_btime(t0)
+                # the header's time has 0.1 ms resolution; above 5 kHz that is coarser than a sample, and a record whose start
+                # is rounded to it reads back as a gap or an overlap against the one before. Blockette 1001 carries the
+                # microseconds the header cannot, so the record's start is written exactly and the reader joins the records.
+                year, doy, hh, mm, ss, frac, usec = _epoch_to_btime_usec(t0)
                 hdr = (f"{seq % 1000000:06d}".encode() + b'D' + b' '
                        + tr.station[:5].ljust(5).encode() + tr.location[:2].ljust(2).encode() + tr.channel[:3].ljust(3).encode() + tr.network[:2].ljust(2).encode()
                        + struct.pack('>HHBBBBH', year, doy, hh, mm, ss, 0, frac)
                        + struct.pack('>Hhh', n, fac, mult)
-                       + struct.pack('BBBB', 0, 0, 0, 1)
+                       + struct.pack('BBBB', 0, 0, 0, 2)
                        + struct.pack('>iHH', 0, 64, 48))
-                b1000 = struct.pack('>HHBBBB', 1000, 0, enc_code, 1, rl_log, 0)
-                rec = (hdr + b1000).ljust(64, b'\x00') + body
+                b1000 = struct.pack('>HHBBBB', 1000, 56, enc_code, 1, rl_log, 0)
+                b1001 = struct.pack('>HHBbBB', 1001, 0, 0, usec, 0, 0)
+                rec = (hdr + b1000 + b1001).ljust(64, b'\x00') + body
                 assert len(rec) == reclen
                 f.write(rec)
                 prev = int(data[i + n - 1]) if encoding in ('STEIM1', 'STEIM2') else None