gea-program 0.4.0__tar.gz → 0.6.0__tar.gz

{gea_program-0.4.0 → gea_program-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.4.0
+Version: 0.6.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
@@ -92,6 +92,25 @@ reaches a client document. Nothing unmeasured is ever reported as met.
 - **Survey track** (`earth_model.py`, `strata_join.py`, `inverse_engine.py`,
   `blind_harness.py`, `rock_inventory.py`, `forward_model.py`, ...): strata
   property estimation over a public co-located library, blind-scored on every run.
+- **The second leg - seismic** (`seismic.py`, `seismic_detect.py`): raw seismic
+  records in (miniSEED with Steim1/Steim2, SAC, or fetched from any FDSN
+  archive - TexNet, EarthScope), Welch spectra, spectrograms and the persistent
+  lines above the local floor out, and the detectability test: one station's
+  record against a list of known rigs with positions and working windows,
+  verdict per rig, the detection radius bracketed between the farthest rig
+  heard and the nearest not heard. The instrument response (`seismic_response.py`):
+  the station's StationXML read into its stages, evaluated as evalresp does,
+  removed with a water level - counts to m/s, m or m/s^2. The decoder is proven
+  against libmseed on a corpus of real-station files; the response against
+  evalresp on a real IRIS channel. The array step (`seismic_array.py`):
+  beamforming over a slowness grid with the array response function's width
+  beside every bearing, the crossing of bearings from several arrays with its
+  ellipse, location from lags with the velocity named as an input, and the
+  array's detectability test - did it point at each known rig. On a site the
+  leg lives on the dashboard: a Seismic page where a station or an array is
+  added by upload with its rigs list and station file, refreshed as a job,
+  and read - spectrum, lines, verdicts, bearing - with its Seismic Station
+  Report under Reports. See *The second leg*.
 
 ## Quick start
 
@@ -103,8 +122,8 @@ 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 (237 checks)
-gea help drift                 # the help library, by the job (14 pages; the same text is on every dashboard page)
+gea accept                     # the product gate (258 checks)
+gea help drift                 # the help library, by the job (15 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]")
 gea workspace --path C:\site --action init --name "Pad 3"     # a site folder
@@ -112,6 +131,7 @@ gea serve --workspace C:\site                                 # the dashboard as
 gea doctor --workspace C:\site                                # which code runs, can it serve, with every fix
 gea files --workspace C:\site --action list --root historian  # the import roots, detection by content, import, export, packs
 gea transient --file historian.csv --params params.json --out pta   # shut-ins and build-up analysis with a band
+gea seismic --action detect --file tx.mseed --station-lat 31.9 --station-lon -102.1 --sources rigs.csv   # the second leg: is a known rig in this record?
 gea swaps / gea certificates / gea notify / gea housekeeping / gea loadtest   # instruments, notification rules, site upkeep
 ```
 
@@ -231,10 +251,10 @@ text: JSON, JSON lines, CSV, Markdown, HTML.
 
 ### The help library
 
-`gea help` lists fourteen pages indexed by the job a reader arrives with -
+`gea help` lists fifteen pages indexed by the job a reader arrives with -
 start, bring data in, quality rules, drift, well tests, alarms and the month,
-the site, instruments, shut-ins and build-ups, patches, files, notifications,
-which code is running, upkeep. Each page carries four lines and stops: the
+the site, instruments, shut-ins and build-ups, seismic (the second leg),
+patches, files, notifications, which code is running, upkeep. Each page carries four lines and stops: the
 command, what it writes, the one number to check, and what the page will not
 call a measurement. The pages ship inside the package (`gea/help/`), and the
 same text is what `/api/help` serves and what the dashboard shows under every
@@ -286,6 +306,94 @@ chose it; an analyst can move the region (`gea transient --mtr 2:40`) and the
 result follows. It is the first look every shut-in should get automatically,
 not a replacement for a full interpretation, and it says so.
 
+### The second leg
+
+The second leg of the program is seismic: the client's site records ground
+motion that conventional processing treats as noise, and in that noise are
+the machinery lines of every rig working within range - mud pumps and their
+harmonics, rotary tables, engines. The leg starts with ingest and one measured
+number, not with a map. `gea seismic` reads the two formats the archives and
+most field recorders write (miniSEED with Steim1/Steim2 and integer/float
+encodings, decided by content; SAC), fetches records from any FDSN web service
+(`--base texnet` for the Texas network TX, `--base iris` for EarthScope), and
+produces the standard spectral products: the Welch PSD, a spectrogram, and
+the lines that persist above a running-median floor in the band where rig
+machinery sits (1-50 Hz by default). The decoder is proven in the acceptance
+suite against records written by libmseed, the format's reference
+implementation (`gea/reference/`), and `tools/seismic_reader_check.py` runs it
+against libmseed on about ninety real-station files of every encoding and
+byte order (the obspy test corpus, fetched with pip, never redistributed):
+every time-series file sample-exact.
+
+Physical units come from the station's own response file. `gea seismic
+--action remove-response --stationxml station.xml` reads the FDSN StationXML
+the archives serve beside the data (`fetch --with-response` fetches it),
+builds the response from its stages - the poles and zeros of the sensor, the
+gain of each stage, the FIR and IIR coefficients of the digitizer with their
+delay corrections - the way evalresp builds it, and removes it in the
+frequency domain with a water level and a pre-filter, giving velocity,
+displacement or acceleration in SI units. The acceptance suite holds the
+evaluation to evalresp's numbers on a real IRIS channel (IU.ANMO.10.BHZ,
+`gea/reference/`) to one part in a hundred thousand. A station file whose
+stages disagree with their own declared sensitivity, a polynomial stage, a
+channel the file does not cover: refused with the reason, never patched, and
+the record stays in counts, labelled.
+
+One station detects; an array gives a direction. `gea seismic --action beam`
+takes three or more sensors' records with their positions and returns the
+back-azimuth and slowness the band's energy crossed the array with, by
+frequency-domain beamforming over a slowness grid (the conventional Bartlett
+beam, or Capon), refined around its maximum - and, beside the bearing, the
+array response function's half-power width, which is the resolution the
+geometry allows at that band, and whether the geometry has aliasing lobes
+there, so a lone peak is not mistaken for a source. `--action array-detect`
+is the array's form of the detectability test: for each rig on the
+ground-truth list, in the windows it worked alone, did the array point at it
+within its own tolerance (POINTED, NOT_POINTED, INCOHERENT). `--action
+locate` crosses the bearings of two or more arrays, weighted by their
+uncertainties, and returns the point with its 1-sigma ellipse, the crossing
+angle and the residual of each bearing; a location from station-pair lags is
+there too, with the medium velocity it needs named as the input it is. On
+the labelled synthetic scene (`--action array-selftest`) a 1.2 km,
+nine-sensor array points at rigs from 6 to 45 km within 0.3 degrees against
+a 7-degree tolerance, and three arrays' bearings cross within a kilometre of
+the rig. What none of it claims: a position from one array, a bearing to a
+source nearer than five apertures, a direction finer than the array response
+function, or a velocity that was not measured.
+
+On a site the leg is a page. Seismic, beside Wells: a station (one record)
+or an array (one record per sensor and a sensors CSV) is added by upload with
+its position, its rigs list and, when there is one, its StationXML, and lives
+under `seismic/<station>/` in the workspace with its files copied in verbatim
+and hashed. Refresh - a button, or `gea workspace --action refresh-seismic`,
+and like every other action a job with its log - reads the record, removes
+the response when the station file is there, writes the spectrum, the
+persistent lines, the detectability verdicts and, for an array, the beam and
+the array verdicts under `reports/seismic/<station>/`, and the Seismic
+Station Report beside them; the station page draws the spectrum and shows
+the tables with the limits printed under each. The home page counts the
+stations and the listed rigs heard. The sample report is in
+`docs/report_samples/`.
+
+The first number is the detectability test (`--action detect`): one station's
+continuous record, the station's position, and a CSV of known rigs - position
+and working window from a public permit register or the operator's own
+schedule. For every rig that worked alone for enough windows the test
+compares the band power in its windows with the quiet baseline (the windows
+when no listed rig was working) and says DETECTED or NOT_DETECTED, with the
+excess in dB and the lines that belong to those windows and not to the quiet
+ones; a rig that never worked alone is AMBIGUOUS, and a record with no quiet
+hour gets NO_QUIET_BASELINE and no verdict at all. The result is the radius
+bracketed between the farthest rig heard and the nearest not heard - the
+station's measured reach for rigs like those on the list. Everything the leg
+can later claim sits inside that radius. What the test will not call a
+measurement is printed with it: a well's position or track (one station
+detects, it does not locate - locating is the array step that comes after
+this number exists), a radius beyond the farthest listed rig, anything about
+a rig not on the list, and any quantity in physical units until a station's
+response has been applied and named. `--action selftest` runs the test on a
+synthetic scene and labels its output SIMULATION_SELF_TEST.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: keep the service on the loopback
@@ -309,10 +417,15 @@ workspace folder it never deletes.
 
 ```
 python tools/build_installer.py                       # dist/gea-program-<version>-win64/ and .zip (needs internet here, none there)
-python tools/build_installer.py --extras live,plotting,xls,desktop   # add the PyQt6 desktop window (~100 MB)
+python tools/build_installer.py --extras live,plotting,xls   # a smaller kit without the PyQt6 desktop window
 python tools/build_installer.py --platform linux      # a venv-based kit for a Linux site server
 ```
 
+The kit carries every optional dependency by default - the live ports
+(asyncua, paho-mqtt, pymodbus, pyserial), matplotlib, xlrd and the PyQt6
+desktop window - so `gea sbom` from an installed kit lists all of them as
+installed; and `report-samples/`, one rendered example of every report.
+
 At the site: unzip, `install.cmd`, `start-dashboard.cmd`; the browser opens
 `http://127.0.0.1:8765/`. `verify.cmd` runs the acceptance gate from the
 installed kit (the client's own evidence), `register-service.cmd` starts the
@@ -328,6 +441,8 @@ attaches the zips to the GitHub release of that tag.
 gea/            the package: engines, record layer, reports, monitor, dashboard, cli, shell, acceptance suite,
                 workspace, jobs, service, patches and web/app.html (the served dashboard)
 gea/catalog/    52 public archive entries, each with a provenance file
+gea/reference/  miniSEED records written by libmseed and an IRIS StationXML with evalresp's numbers, with provenance: the independent references
+docs/report_samples/  one rendered example of every client report, from this build (tools/render_report_samples.py; SAMPLES.md names each command)
 docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports), examples/ (port configs),
                 SESSION_LOG.md (the working record, session by session),
                 commercial/ (pilot proposal, bench readiness, commercial use), HISTORY.md (the ship-by-ship record)
@@ -348,10 +463,22 @@ density anchors and Vp ranges with their citations (Telford, Geldart and
 Sheriff; Schon). Every catalogue entry under `gea/catalog/` has a provenance
 file naming its public source.
 
-Two statements the product carries on its own model cards: the gauge aging
-envelope's lower bound is an engineering model with no field validation on
-record, and five of the fourteen back-tested strata quantities are NOT
-ACCEPTABLE at the 95 % target. Both are printed, never claimed otherwise.
+The gauge aging rate the drift evaluation uses is the instrument's published
+drift specification, read from a cited datasheet (`gea/gauge_specs.py`), with
+nothing added for temperature or pressure - above the rating the rate is
+flagged, not changed. The program carries no aging model of its own, no
+engineering constant that is not a datasheet number, and no claim about a
+gauge beyond what its datasheet says; `tools/standalone_check.py` fails the
+build on the names, phrases and numbers of the model that once stood there.
+The seismic leg is textbook signal processing - Welch's PSD estimate, a
+running-median floor, band power, great-circle distance - and the decoder is
+checked against libmseed; the synthetic scene behind its self-test states its
+own assumptions (body-wave spreading, a Q) and is labelled as a scene, not a
+ground. Two statements the product carries on its own model cards: the datasheet
+rate has no field validation on record against a gauge with a known history
+(`gea bench` is the instrument for it), and five of the fourteen back-tested
+strata quantities are NOT ACCEPTABLE at the 95 % target. Both are printed,
+never claimed otherwise.
 
 ## Shipping
 
@@ -361,7 +488,9 @@ not exist anywhere, every version in `SHIP_LOG.md` must have its tag, `python -m
 accept` must be green, `SHIP_MESSAGE.txt` must start with the tag; then commit, tag,
 push, and the remote tag must be seen before SHIPPED is printed. `CHANGELOG.md` must carry a
 section headed by the tag, and `tools/standalone_check.py` must report no findings. `-DryRun` runs every
-check and changes nothing; `-NoPush` stops after the local tag.
+check and changes nothing; `-NoPush` stops after the local tag. Before the gate, after the bump:
+`python tools/render_report_samples.py` re-renders `docs/report_samples/` from the new build
+(section AM fails on a stale build number).
 
 ## Publishing to PyPI
 

{gea_program-0.4.0 → gea_program-0.6.0}/README.md

@@ -53,6 +53,25 @@ reaches a client document. Nothing unmeasured is ever reported as met.
 - **Survey track** (`earth_model.py`, `strata_join.py`, `inverse_engine.py`,
   `blind_harness.py`, `rock_inventory.py`, `forward_model.py`, ...): strata
   property estimation over a public co-located library, blind-scored on every run.
+- **The second leg - seismic** (`seismic.py`, `seismic_detect.py`): raw seismic
+  records in (miniSEED with Steim1/Steim2, SAC, or fetched from any FDSN
+  archive - TexNet, EarthScope), Welch spectra, spectrograms and the persistent
+  lines above the local floor out, and the detectability test: one station's
+  record against a list of known rigs with positions and working windows,
+  verdict per rig, the detection radius bracketed between the farthest rig
+  heard and the nearest not heard. The instrument response (`seismic_response.py`):
+  the station's StationXML read into its stages, evaluated as evalresp does,
+  removed with a water level - counts to m/s, m or m/s^2. The decoder is proven
+  against libmseed on a corpus of real-station files; the response against
+  evalresp on a real IRIS channel. The array step (`seismic_array.py`):
+  beamforming over a slowness grid with the array response function's width
+  beside every bearing, the crossing of bearings from several arrays with its
+  ellipse, location from lags with the velocity named as an input, and the
+  array's detectability test - did it point at each known rig. On a site the
+  leg lives on the dashboard: a Seismic page where a station or an array is
+  added by upload with its rigs list and station file, refreshed as a job,
+  and read - spectrum, lines, verdicts, bearing - with its Seismic Station
+  Report under Reports. See *The second leg*.
 
 ## Quick start
 
@@ -64,8 +83,8 @@ 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 (237 checks)
-gea help drift                 # the help library, by the job (14 pages; the same text is on every dashboard page)
+gea accept                     # the product gate (258 checks)
+gea help drift                 # the help library, by the job (15 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]")
 gea workspace --path C:\site --action init --name "Pad 3"     # a site folder
@@ -73,6 +92,7 @@ gea serve --workspace C:\site                                 # the dashboard as
 gea doctor --workspace C:\site                                # which code runs, can it serve, with every fix
 gea files --workspace C:\site --action list --root historian  # the import roots, detection by content, import, export, packs
 gea transient --file historian.csv --params params.json --out pta   # shut-ins and build-up analysis with a band
+gea seismic --action detect --file tx.mseed --station-lat 31.9 --station-lon -102.1 --sources rigs.csv   # the second leg: is a known rig in this record?
 gea swaps / gea certificates / gea notify / gea housekeeping / gea loadtest   # instruments, notification rules, site upkeep
 ```
 
@@ -192,10 +212,10 @@ text: JSON, JSON lines, CSV, Markdown, HTML.
 
 ### The help library
 
-`gea help` lists fourteen pages indexed by the job a reader arrives with -
+`gea help` lists fifteen pages indexed by the job a reader arrives with -
 start, bring data in, quality rules, drift, well tests, alarms and the month,
-the site, instruments, shut-ins and build-ups, patches, files, notifications,
-which code is running, upkeep. Each page carries four lines and stops: the
+the site, instruments, shut-ins and build-ups, seismic (the second leg),
+patches, files, notifications, which code is running, upkeep. Each page carries four lines and stops: the
 command, what it writes, the one number to check, and what the page will not
 call a measurement. The pages ship inside the package (`gea/help/`), and the
 same text is what `/api/help` serves and what the dashboard shows under every
@@ -247,6 +267,94 @@ chose it; an analyst can move the region (`gea transient --mtr 2:40`) and the
 result follows. It is the first look every shut-in should get automatically,
 not a replacement for a full interpretation, and it says so.
 
+### The second leg
+
+The second leg of the program is seismic: the client's site records ground
+motion that conventional processing treats as noise, and in that noise are
+the machinery lines of every rig working within range - mud pumps and their
+harmonics, rotary tables, engines. The leg starts with ingest and one measured
+number, not with a map. `gea seismic` reads the two formats the archives and
+most field recorders write (miniSEED with Steim1/Steim2 and integer/float
+encodings, decided by content; SAC), fetches records from any FDSN web service
+(`--base texnet` for the Texas network TX, `--base iris` for EarthScope), and
+produces the standard spectral products: the Welch PSD, a spectrogram, and
+the lines that persist above a running-median floor in the band where rig
+machinery sits (1-50 Hz by default). The decoder is proven in the acceptance
+suite against records written by libmseed, the format's reference
+implementation (`gea/reference/`), and `tools/seismic_reader_check.py` runs it
+against libmseed on about ninety real-station files of every encoding and
+byte order (the obspy test corpus, fetched with pip, never redistributed):
+every time-series file sample-exact.
+
+Physical units come from the station's own response file. `gea seismic
+--action remove-response --stationxml station.xml` reads the FDSN StationXML
+the archives serve beside the data (`fetch --with-response` fetches it),
+builds the response from its stages - the poles and zeros of the sensor, the
+gain of each stage, the FIR and IIR coefficients of the digitizer with their
+delay corrections - the way evalresp builds it, and removes it in the
+frequency domain with a water level and a pre-filter, giving velocity,
+displacement or acceleration in SI units. The acceptance suite holds the
+evaluation to evalresp's numbers on a real IRIS channel (IU.ANMO.10.BHZ,
+`gea/reference/`) to one part in a hundred thousand. A station file whose
+stages disagree with their own declared sensitivity, a polynomial stage, a
+channel the file does not cover: refused with the reason, never patched, and
+the record stays in counts, labelled.
+
+One station detects; an array gives a direction. `gea seismic --action beam`
+takes three or more sensors' records with their positions and returns the
+back-azimuth and slowness the band's energy crossed the array with, by
+frequency-domain beamforming over a slowness grid (the conventional Bartlett
+beam, or Capon), refined around its maximum - and, beside the bearing, the
+array response function's half-power width, which is the resolution the
+geometry allows at that band, and whether the geometry has aliasing lobes
+there, so a lone peak is not mistaken for a source. `--action array-detect`
+is the array's form of the detectability test: for each rig on the
+ground-truth list, in the windows it worked alone, did the array point at it
+within its own tolerance (POINTED, NOT_POINTED, INCOHERENT). `--action
+locate` crosses the bearings of two or more arrays, weighted by their
+uncertainties, and returns the point with its 1-sigma ellipse, the crossing
+angle and the residual of each bearing; a location from station-pair lags is
+there too, with the medium velocity it needs named as the input it is. On
+the labelled synthetic scene (`--action array-selftest`) a 1.2 km,
+nine-sensor array points at rigs from 6 to 45 km within 0.3 degrees against
+a 7-degree tolerance, and three arrays' bearings cross within a kilometre of
+the rig. What none of it claims: a position from one array, a bearing to a
+source nearer than five apertures, a direction finer than the array response
+function, or a velocity that was not measured.
+
+On a site the leg is a page. Seismic, beside Wells: a station (one record)
+or an array (one record per sensor and a sensors CSV) is added by upload with
+its position, its rigs list and, when there is one, its StationXML, and lives
+under `seismic/<station>/` in the workspace with its files copied in verbatim
+and hashed. Refresh - a button, or `gea workspace --action refresh-seismic`,
+and like every other action a job with its log - reads the record, removes
+the response when the station file is there, writes the spectrum, the
+persistent lines, the detectability verdicts and, for an array, the beam and
+the array verdicts under `reports/seismic/<station>/`, and the Seismic
+Station Report beside them; the station page draws the spectrum and shows
+the tables with the limits printed under each. The home page counts the
+stations and the listed rigs heard. The sample report is in
+`docs/report_samples/`.
+
+The first number is the detectability test (`--action detect`): one station's
+continuous record, the station's position, and a CSV of known rigs - position
+and working window from a public permit register or the operator's own
+schedule. For every rig that worked alone for enough windows the test
+compares the band power in its windows with the quiet baseline (the windows
+when no listed rig was working) and says DETECTED or NOT_DETECTED, with the
+excess in dB and the lines that belong to those windows and not to the quiet
+ones; a rig that never worked alone is AMBIGUOUS, and a record with no quiet
+hour gets NO_QUIET_BASELINE and no verdict at all. The result is the radius
+bracketed between the farthest rig heard and the nearest not heard - the
+station's measured reach for rigs like those on the list. Everything the leg
+can later claim sits inside that radius. What the test will not call a
+measurement is printed with it: a well's position or track (one station
+detects, it does not locate - locating is the array step that comes after
+this number exists), a radius beyond the farthest listed rig, anything about
+a rig not on the list, and any quantity in physical units until a station's
+response has been applied and named. `--action selftest` runs the test on a
+synthetic scene and labels its output SIMULATION_SELF_TEST.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: keep the service on the loopback
@@ -270,10 +378,15 @@ workspace folder it never deletes.
 
 ```
 python tools/build_installer.py                       # dist/gea-program-<version>-win64/ and .zip (needs internet here, none there)
-python tools/build_installer.py --extras live,plotting,xls,desktop   # add the PyQt6 desktop window (~100 MB)
+python tools/build_installer.py --extras live,plotting,xls   # a smaller kit without the PyQt6 desktop window
 python tools/build_installer.py --platform linux      # a venv-based kit for a Linux site server
 ```
 
+The kit carries every optional dependency by default - the live ports
+(asyncua, paho-mqtt, pymodbus, pyserial), matplotlib, xlrd and the PyQt6
+desktop window - so `gea sbom` from an installed kit lists all of them as
+installed; and `report-samples/`, one rendered example of every report.
+
 At the site: unzip, `install.cmd`, `start-dashboard.cmd`; the browser opens
 `http://127.0.0.1:8765/`. `verify.cmd` runs the acceptance gate from the
 installed kit (the client's own evidence), `register-service.cmd` starts the
@@ -289,6 +402,8 @@ attaches the zips to the GitHub release of that tag.
 gea/            the package: engines, record layer, reports, monitor, dashboard, cli, shell, acceptance suite,
                 workspace, jobs, service, patches and web/app.html (the served dashboard)
 gea/catalog/    52 public archive entries, each with a provenance file
+gea/reference/  miniSEED records written by libmseed and an IRIS StationXML with evalresp's numbers, with provenance: the independent references
+docs/report_samples/  one rendered example of every client report, from this build (tools/render_report_samples.py; SAMPLES.md names each command)
 docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports), examples/ (port configs),
                 SESSION_LOG.md (the working record, session by session),
                 commercial/ (pilot proposal, bench readiness, commercial use), HISTORY.md (the ship-by-ship record)
@@ -309,10 +424,22 @@ density anchors and Vp ranges with their citations (Telford, Geldart and
 Sheriff; Schon). Every catalogue entry under `gea/catalog/` has a provenance
 file naming its public source.
 
-Two statements the product carries on its own model cards: the gauge aging
-envelope's lower bound is an engineering model with no field validation on
-record, and five of the fourteen back-tested strata quantities are NOT
-ACCEPTABLE at the 95 % target. Both are printed, never claimed otherwise.
+The gauge aging rate the drift evaluation uses is the instrument's published
+drift specification, read from a cited datasheet (`gea/gauge_specs.py`), with
+nothing added for temperature or pressure - above the rating the rate is
+flagged, not changed. The program carries no aging model of its own, no
+engineering constant that is not a datasheet number, and no claim about a
+gauge beyond what its datasheet says; `tools/standalone_check.py` fails the
+build on the names, phrases and numbers of the model that once stood there.
+The seismic leg is textbook signal processing - Welch's PSD estimate, a
+running-median floor, band power, great-circle distance - and the decoder is
+checked against libmseed; the synthetic scene behind its self-test states its
+own assumptions (body-wave spreading, a Q) and is labelled as a scene, not a
+ground. Two statements the product carries on its own model cards: the datasheet
+rate has no field validation on record against a gauge with a known history
+(`gea bench` is the instrument for it), and five of the fourteen back-tested
+strata quantities are NOT ACCEPTABLE at the 95 % target. Both are printed,
+never claimed otherwise.
 
 ## Shipping
 
@@ -322,7 +449,9 @@ not exist anywhere, every version in `SHIP_LOG.md` must have its tag, `python -m
 accept` must be green, `SHIP_MESSAGE.txt` must start with the tag; then commit, tag,
 push, and the remote tag must be seen before SHIPPED is printed. `CHANGELOG.md` must carry a
 section headed by the tag, and `tools/standalone_check.py` must report no findings. `-DryRun` runs every
-check and changes nothing; `-NoPush` stops after the local tag.
+check and changes nothing; `-NoPush` stops after the local tag. Before the gate, after the bump:
+`python tools/render_report_samples.py` re-renders `docs/report_samples/` from the new build
+(section AM fails on a stale build number).
 
 ## Publishing to PyPI
 

gea_program-0.6.0/gea/BENCH_TEST_PROTOCOL.md

@@ -0,0 +1,91 @@
+# Bench-Test Protocol - Does this gauge drift within its datasheet?
+
+The program judges a measured drift trend against one number: the
+instrument's published drift specification (percent of full scale per year,
+from its datasheet). That number is a specification, not a measurement of
+the gauge in your hand. This protocol is the measurement: one gauge, one
+held setpoint, one reference standard, enough weeks, and a verdict written
+down - the bench record the drift report cites as `NONE ON RECORD` until it
+exists.
+
+---
+
+## 1. What is being tested
+
+For a gauge of serial number S with datasheet drift specification D (%FS/yr):
+
+```
+measured drift rate (|slope| of the gauge's reading against the reference, at a held setpoint)
+compared with D, with the slope's own standard error
+```
+
+The outcome is one of four words (section 5). A gauge that drifts faster
+than its datasheet is a finding, not an error.
+
+## 2. Apparatus
+
+- The gauge under test, with its serial number and its calibration
+  certificate id (both go on the record; `gea certificates` files the
+  certificate).
+- A temperature-controlled bath or pressure vessel holding a setpoint inside
+  the gauge's rating (the rating check applies on the bench too).
+- A reference pressure standard of a class better than the specification
+  under test (deadweight tester or transfer standard), logged at the same
+  cadence, or at least checked weekly and logged.
+- Logging at one reading per day or better into the program's historian CSV
+  format (a timestamp or `time_s` column and one pressure column per
+  instrument).
+
+## 3. Duration - the program's own rule applies
+
+The reconciler refuses trend verdicts below its minimum span
+(`ReconcilerConfig.min_trend_span_years`, the 18-day rule), and the bench
+analysis reads that floor from the same configuration: a shorter record is
+`INSUFFICIENT_SPAN`, no verdict. The protocol asks for **at least 90 days**
+at setpoint; 180 days or more when the specification is tight (a 0.01 %FS/yr
+gauge at 30,000 psi full scale drifts 3 psi in a year - 0.75 psi in 90
+days - so the reference and the logging must resolve tenths of a psi).
+
+## 4. Procedure
+
+1. File the certificate (`gea certificates --action add ...`) and record the
+   serial number.
+2. Install the gauge and the reference at the setpoint; log continuously.
+3. Weekly: verify the setpoint against the reference; do not adjust the gauge
+   under test. Log every intervention.
+4. Export the gauge's series and the reference's series as historian CSVs.
+5. Run:
+
+       gea bench --gauge-csv gauge.csv --reference-csv reference.csv --spec geoq177_30k --serial SN --certificate CERT --out bench_register.jsonl
+
+   The reference series is subtracted first (the setpoint's own wander is
+   not the gauge's drift). `--spec` names the datasheet preset or a JSON
+   datasheet of your own.
+6. Keep the record: the JSON line appended to the register carries the fit,
+   the band, the datasheet source, the serial, the certificate and the verdict.
+
+## 5. Analysis and verdict vocabulary
+
+- The slope of the (gauge - reference) series is fitted by least squares;
+  its standard error comes from the residuals.
+- A band of k sigma (default 2) is placed around the measured rate.
+- `WITHIN_DATASHEET` - the whole band is at or below the specification.
+- `EXCEEDS_DATASHEET` - the whole band is above the specification: this
+  gauge, at these conditions, drifts faster than its datasheet says. A
+  first-class outcome.
+- `INSUFFICIENT_SPAN` - shorter than the 18-day floor; no verdict.
+- `INSUFFICIENT_SNR` - the band straddles the specification; a longer span
+  or a quieter setpoint is needed; no verdict.
+
+`gea bench --selftest` runs the arithmetic on synthetic series and labels
+its output `SIMULATION_SELF_TEST`; it proves nothing about a physical gauge.
+
+## 6. What the record changes
+
+Nothing in the program's arithmetic changes with a bench result; the
+datasheet rate stays the rate the reports use. What changes is the model
+card's `field validation` line, which can cite the register once a gauge
+with a known history has been run, and the reader's confidence in a
+`DRIFT_CONSISTENT` label on that instrument. An `EXCEEDS_DATASHEET` record
+is the reason to recalibrate, replace or re-rate that gauge, and to file
+the result with its certificate.

{gea_program-0.4.0 → gea_program-0.6.0}/gea/__init__.py

@@ -1,17 +1,15 @@
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
-"""gea — the GEA Downhole HPHT Quartz-Gauge Simulator.
+"""gea - GEA-Program: the downhole gauge monitoring program.
 
-The gea-program's first packaged industry-application module: a
-deep-well (TD ~20,300 ft) six-gauge quartz P/T string with GEA-stabilized
-drift, transient events, live animation (matplotlib / optional PyQt6), and
-CSV export.
-
-The program aging model composes a fixed drift-suppression factor from three
-locked engineering constants (K_MEX = 25/12, PHI_RES = 0.84, F_TRZ = 0.1); the
-user-facing settings are the two instrument trims (k_structural_trim,
-phi_coupling_trim), never the constants. See README.md.
+A described well (gradients or a real profile, a toolstring of cited
+instruments), the data that comes back from it (files or live ports), and
+the report family that judges the two against each other: data quality,
+gauge drift against each instrument's datasheet aging rate, well tests,
+alarms, shut-ins and build-ups, instruments and certificates, the monthly
+service note. Every number on a report names the rule or the datasheet it
+came from; the program adds no physics of its own.
 
 Quick use (headless):
     from gea import DownholeEngine, SimulatorConfig
@@ -19,18 +17,10 @@ Quick use (headless):
     for _ in range(100): e.step()
     print(e.summary()); e.export_csv("run.csv")
 
-Demos (need a display):
-    python -m gea.matplotlib_demo
-    python -m gea.qt6_downhole_app   (pip install PyQt6)
+The dashboard: gea workspace --path C:\\site --action init --name "Pad 3"; gea serve --workspace C:\\site
 """
 
-from .quartz_hpht_extension import (
-    calculate_quartz_transducer_hpht_program,
-    canonical_suppression,
-    conventional_drift,
-    drift_comparison,
-    PROGRAM_MODEL_AVAILABLE,
-)
+from .gauge_aging import aging_rate, rate_psi_yr, accuracy_psi
 from .downhole_engine import (
     Sensor,
     SimulatorConfig,
@@ -49,15 +39,11 @@ from .telemetry import (
     TelemetryConfig,
     TelemetryRecorder,
 )
-from .case_study import (
-    CaseStudyConfig,
-    case_study,
-    depth_sweep,
-    write_markdown,
-)
 from .gauge_specs import (
     GaugeSpec,
     GAUGE_SPECS,
+    DEFAULT_SPEC,
+    get_spec,
     load_gauge_spec_json,
 )
 from .deviation import (
@@ -70,7 +56,7 @@ from .tool_library import (
     TOOL_LIBRARY,
     ToolString,
     drift_model_for,
-    piezoresistive_drift,
+    user_gauge_tool,
     rating_check,
 )
 from .ports import (
@@ -109,6 +95,13 @@ from .well_assembler import (
 from .gamma import (
     find_gr_channels, shale_volume, formation_flags, gamma_report, gamma_entries,
 )
+from .seismic import (
+    Trace as SeismicTrace, read_mseed, write_mseed, read_sac, write_sac, read_any as read_seismic, fdsn_fetch, fdsn_stations,
+    welch_psd, spectrogram, persistent_lines, band_power,
+)
+from .seismic_detect import Source as SeismicSource, detectability_test, load_sources_csv, haversine_km, DRILLING_BAND_HZ
+from .seismic_response import read_stationxml, remove_response, transfer as response_transfer, fdsn_stationxml
+from .seismic_array import Sensor as SeismicSensor, load_sensors_csv, beam as array_beam, array_detectability, intersect_backazimuths, locate_from_lags
 from .bench import (
     bench_analysis, bench_selftest,
 )
@@ -129,19 +122,17 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"
 __all__ = [
-    "calculate_quartz_transducer_hpht_program", "canonical_suppression",
-    "conventional_drift", "drift_comparison",
-    "PROGRAM_MODEL_AVAILABLE", "Sensor", "SimulatorConfig", "DownholeEngine",
+    "aging_rate", "rate_psi_yr", "accuracy_psi",
+    "Sensor", "SimulatorConfig", "DownholeEngine",
     "WellProfile", "load_well_profile_csv", "make_sensor_string",
     "ServiceLifeConfig", "ServiceLifeSimulator",
     "TelemetryConfig", "TelemetryRecorder",
-    "CaseStudyConfig", "case_study", "depth_sweep", "write_markdown",
-    "GaugeSpec", "GAUGE_SPECS", "load_gauge_spec_json",
+    "GaugeSpec", "GAUGE_SPECS", "DEFAULT_SPEC", "get_spec", "load_gauge_spec_json",
     "DeviationSurvey", "load_deviation_csv", "run_batch",
     "ToolSpec", "TOOL_LIBRARY", "ToolString", "drift_model_for",
-    "piezoresistive_drift", "rating_check",
+    "user_gauge_tool", "rating_check",
     "LiveStream", "StreamChannel", "PortSpec", "PORT_REGISTRY",
     "ingest", "read_historian_csv", "read_las", "register_port",
     "Reconciler", "ReconcilerConfig", "auto_station_map",