gea-program 0.27.0__tar.gz → 0.28.0__tar.gz

{gea_program-0.27.0/gea_program.egg-info → gea_program-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.27.0
+Version: 0.28.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 (366 checks)
+gea accept                     # the product gate (368 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -648,6 +648,20 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Tools and ports
+
+The Tools & ports tab (`#/tools`, `gea tools`) is the program's two
+registers in one place: the tool library - every downhole and surface tool
+with its source citation, ratings, what it measures, the telemetry interface
+it declares and its datasheet aging rate where the vendor published one -
+and the ports, the file formats read and the eleven live protocols spoken,
+each with what it speaks to, what the site must supply and what to rehearse
+against. Tools whose declared interface no port in this build speaks are
+listed by name. The rating check hangs a tool string in a well and reports
+each station's tool against the conditions there, with the basis stated:
+`gea tools --rating --station 16000:quartz_pt_geoq177_16k` exits 1 when a
+station is over a rating. `gea help tools`.
+
 ### ComCat
 
 The seismicity response plan reads a TexNet export; it reads the FDSN text

{gea_program-0.27.0 → gea_program-0.28.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 (366 checks)
+gea accept                     # the product gate (368 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -609,6 +609,20 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Tools and ports
+
+The Tools & ports tab (`#/tools`, `gea tools`) is the program's two
+registers in one place: the tool library - every downhole and surface tool
+with its source citation, ratings, what it measures, the telemetry interface
+it declares and its datasheet aging rate where the vendor published one -
+and the ports, the file formats read and the eleven live protocols spoken,
+each with what it speaks to, what the site must supply and what to rehearse
+against. Tools whose declared interface no port in this build speaks are
+listed by name. The rating check hangs a tool string in a well and reports
+each station's tool against the conditions there, with the basis stated:
+`gea tools --rating --station 16000:quartz_pt_geoq177_16k` exits 1 when a
+station is over a rating. `gea help tools`.
+
 ### ComCat
 
 The seismicity response plan reads a TexNet export; it reads the FDSN text

{gea_program-0.27.0 → gea_program-0.28.0}/gea/__init__.py

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

{gea_program-0.27.0 → gea_program-0.28.0}/gea/__main__.py

@@ -278,6 +278,13 @@ def main(argv=None) -> int:
         p_lp.add_argument("--stream-csv", type=str, default=None, help="also write a historian-style CSV the other commands ingest")
         p_lp.add_argument("--selftest", action="store_true", help="etp: the codec round-trip and a session against the simulated store on the loopback")
 
+    p_tl = sub.add_parser("tools", help="the tool library and the port registry: every tool with its citation, ratings and the interface it declares; every file format and live protocol; --rating checks a tool string")
+    p_tl.add_argument("--json", action="store_true")
+    p_tl.add_argument("--list", action="store_true", help="just the tool names")
+    p_tl.add_argument("--rating", action="store_true", help="check a tool string: --station <md_ft>:<tool> (repeatable)")
+    p_tl.add_argument("--station", type=str, action="append", default=None, help="a station as <measured depth in feet>:<tool name>")
+    p_tl.add_argument("--surface-temp-f", type=float, default=75.0); p_tl.add_argument("--temp-gradient-f-ft", type=float, default=0.018)
+    p_tl.add_argument("--surface-pressure-psi", type=float, default=14.7); p_tl.add_argument("--pressure-gradient-psi-ft", type=float, default=0.465)
     p_cc = sub.add_parser("comcat", help="USGS ComCat / any FDSN event service: --lat --lon --radius-km --start --end prints the text-format query to open; --file reads the export it returns")
     p_cc.add_argument("--lat", type=float, default=None); p_cc.add_argument("--lon", type=float, default=None); p_cc.add_argument("--radius-km", type=float, default=25.0)
     p_cc.add_argument("--start", type=str, default=None); p_cc.add_argument("--end", type=str, default=None); p_cc.add_argument("--min-mag", type=float, default=1.0)
@@ -2356,6 +2363,37 @@ def main(argv=None) -> int:
             stop.set()
             print("etp-sim: stopped")
         return 0
+    elif a.cmd == "tools":
+        import json as _json
+        from . import tool_catalog as _TC
+        if a.rating or a.station:
+            stations = []
+            for spec in (a.station or []):
+                if ":" not in spec:
+                    raise SystemExit(f"--station takes <measured depth in feet>:<tool name>, got {spec!r}")
+                md, _, nm = spec.partition(":")
+                try:
+                    stations.append((float(md), nm.strip()))
+                except ValueError:
+                    raise SystemExit(f"--station depth is not a number: {md!r}")
+            try:
+                r = _TC.check_string(stations, surface_temp_F=a.surface_temp_f, temp_gradient_F_per_ft=a.temp_gradient_f_ft,
+                                     surface_pressure_psi=a.surface_pressure_psi, pressure_gradient_psi_per_ft=a.pressure_gradient_psi_ft)
+            except ValueError as e:
+                raise SystemExit(f"tools: {e}")
+            if a.json:
+                print(_json.dumps(r, indent=1)); return 0 if not r["n_over_rating"] else 1
+            for line in r["lines"]:
+                print(line)
+            return 0 if not r["n_over_rating"] else 1
+        if a.list:
+            for t in _TC.tools():
+                print(t["name"])
+            return 0
+        if a.json:
+            print(_json.dumps(_TC.catalog(), indent=1)); return 0
+        print(_TC.text())
+        return 0
     elif a.cmd == "comcat":
         import json as _json
         from . import sra as _SR

{gea_program-0.27.0 → gea_program-0.28.0}/gea/acceptance_tests.py

@@ -7320,6 +7320,115 @@ def section_bu_comcat(tmp: str) -> None:
        + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
 
 
+def section_bv_tools(tmp: str) -> None:
+    """Section BV - the tool library and the port registry as one register: every tool with its citation, ratings,
+    declared interface and published aging rate (or the reason there is none); every file format and live protocol
+    with what the site must supply; the tools no port speaks named; the rating check; the API, the page, the CLI, the help."""
+    import http.cookiejar
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    from . import tool_catalog as TC
+    from . import helplib as H
+    from .ports import PORT_REGISTRY
+    from .tool_library import PARAMETERS_USER_SUPPLIED, TOOL_LIBRARY
+    from .telemetry import TelemetryRecorder, TelemetryConfig
+    from .downhole_engine import DownholeEngine, SimulatorConfig
+    from .workspace import Workspace
+    from .service import Service, Users
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bv"); d.mkdir()
+
+    c = TC.catalog()
+    by = {t["name"]: t for t in c["tools"]}
+    q30, piezo, g6 = by["quartz_pt_geoq177_30k"], by["piezoresistive_pt_class"], by["surface_interface_g6"]
+    rate = TC.check_string([(500.0, "quartz_pt_geoq177_30k"), (16000.0, "quartz_pt_geoq177_16k")])
+    deep = rate["stations"][1]
+    ok_all = TC.check_string([(500.0, "quartz_pt_geoq177_30k")])
+    bad_tool = empty = None
+    try:
+        TC.check_string([(100.0, "no_such_tool")])
+    except ValueError as e:
+        bad_tool = str(e)
+    try:
+        TC.check_string([])
+    except ValueError as e:
+        empty = str(e)
+    c1 = {
+        "tools": c["counts"]["tools"] == len(TOOL_LIBRARY) and c["counts"]["fully_specified"] + c["counts"]["user_supplied"] == len(TOOL_LIBRARY)
+                 and all(t["source"] for t in c["tools"]) and q30["aging_rate_pct_fs_yr"] is not None and q30["aging_note"].startswith("the datasheet")
+                 and q30["temp_rating_C"] == 177.0 and q30["pressure_rating_psi"] == 30000.0 and q30["gauge_spec"]["full_scale_psi"] == 30000.0,
+        "user_supplied_named": piezo["spec_status"] == PARAMETERS_USER_SUPPLIED and piezo["aging_rate_pct_fs_yr"] is None
+                               and "does not invent vendor numbers" in piezo["aging_note"] and g6["measures"] == [],
+        "ports": c["counts"]["file_ports"] == len(PORT_REGISTRY) and {p["name"] for p in c["ports"]["live"]} >= {"wits0", "witsml", "etp", "opcua", "mqtt", "modbus_g6", "modbus_rtu", "dnp3", "hartip", "piwebapi", "seedlink"}
+                 and all(p["needs"] and p["speaks"] and p["rehearse"] for p in c["ports"]["live"]) and any(p["status"] == "IMPLEMENTED" for p in c["ports"]["files"])
+                 and any(p["name"] == "dlis" for p in c["ports"]["files"]),
+        "interfaces": "modbus_rtu" in q30["ports"] and not piezo["ports"] and {u["tool"] for u in c["unmatched"]} == {t["name"] for t in c["tools"] if not t["ports"]}
+                      and "piezoresistive_pt_class" in {u["tool"] for u in c["unmatched"]},
+        "rating": rate["n_over_rating"] == 1 and deep["over_temp_rating"] and not deep["over_pressure_rating"] and abs(deep["station_temp_C"] - 183.9) < 0.2
+                  and "OVER its 177 C rating" in rate["lines"][2] and "declared gradients" in rate["basis"] and "no survey given" in rate["deviation"]
+                  and ok_all["n_over_rating"] == 0 and bad_tool and "not in the tool library" in bad_tool and empty and "at least one station" in empty,
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       f"BV1 the register: all {len(TOOL_LIBRARY)} tools with their citations, the quartz gauge's datasheet aging rate and ratings, the piezoresistive "
+       "class carrying no rate and saying why, the interface card measuring nothing; every file port of the registry and all eleven live protocols with "
+       "what each needs from the site and what to rehearse against; the tools no port in this build speaks named; the rating check flagging a 177 C gauge "
+       "at 16,000 ft and clearing a shallow one, an unknown tool and an empty string refused"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    hist = str(d / "hist.csv")
+    TelemetryRecorder(engine=DownholeEngine(SimulatorConfig()), config=TelemetryConfig(duration_hours=0.5, seed=3)).run().export_csv(hist)
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad 3", actor="tester")
+    ws.add_well_file(hist, display="SWD 1", actor="tester")
+    users = Users(str(Path(wsp, "users.json"))); users.add("v", "viewer-pass-1", "viewer")
+    svc = Service(wsp, port=0, scheduler=False).start()
+    base_url = svc.url.rstrip("/")
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+
+    def call(method, path, body=None):
+        req = urllib.request.Request(base_url + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        req.add_header("Content-Type", "application/json"); req.add_header("X-GEA-Action", "1")
+        try:
+            with opener.open(req, timeout=120) as rr_:
+                return rr_.status, json.loads(rr_.read())
+        except urllib.error.HTTPError as e:
+            return e.code, json.loads(e.read())
+    try:
+        st_anon = call("GET", "/api/tools")[0]
+        call("POST", "/api/login", {"name": "v", "password": "viewer-pass-1"})
+        st_g, got = call("GET", "/api/tools")
+        st_r, rr = call("POST", "/api/tools/rating", {"stations": [{"md_ft": 500, "tool": "quartz_pt_geoq177_30k"}, {"md_ft": 16000, "tool": "quartz_pt_geoq177_16k"}]})
+        st_bad = call("POST", "/api/tools/rating", {"stations": [{"md_ft": 100, "tool": "nope"}]})[0]
+        st_bad2 = call("POST", "/api/tools/rating", {"stations": [{"tool": "quartz_pt_geoq177_30k"}]})[0]
+    finally:
+        svc.stop()
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "tools.md").read_text(encoding="utf-8")
+    r_txt = _sp.run([sys.executable, "-m", "gea", "tools"], capture_output=True, text=True)
+    r_list = _sp.run([sys.executable, "-m", "gea", "tools", "--list"], capture_output=True, text=True)
+    r_json = _sp.run([sys.executable, "-m", "gea", "tools", "--json"], capture_output=True, text=True)
+    r_rate = _sp.run([sys.executable, "-m", "gea", "tools", "--rating", "--station", "500:quartz_pt_geoq177_30k", "--station", "16000:quartz_pt_geoq177_16k"], capture_output=True, text=True)
+    r_badst = _sp.run([sys.executable, "-m", "gea", "tools", "--rating", "--station", "500"], capture_output=True, text=True)
+    c2 = {
+        "api": st_anon == 401 and st_g == 200 and got["counts"]["tools"] == len(TOOL_LIBRARY) and st_r == 200 and rr["n_over_rating"] == 1
+               and rr["stations"][1]["over_temp_rating"] and st_bad == 400 and st_bad2 == 400,
+        "page": "VIEWS.tools" in page_src and "'#/tools', 'Tools & ports'" in page_src and "/api/tools/rating" in page_src
+                and "Tools no live port in this build speaks" in page_src and "Rating check" in page_src,
+        "cli": r_txt.returncode == 0 and "file ports:" in r_txt.stdout and "live ports:" in r_txt.stdout and "does not invent vendor numbers" in r_txt.stdout
+               and r_list.returncode == 0 and r_list.stdout.split() == sorted(TOOL_LIBRARY) and r_json.returncode == 0 and json.loads(r_json.stdout)["counts"]["live_ports"] == 11
+               and r_rate.returncode == 1 and "OVER its 177 C rating" in r_rate.stdout and r_badst.returncode != 0 and "<measured depth in feet>:<tool name>" in (r_badst.stderr + r_badst.stdout),
+        "help": any(t["topic"] == "tools" for t in H.topics()) and not H.check("tools") and H.VIEW_TOPIC.get("tools") == "tools"
+                and "not a promise the tool survives" in help_md.split("will not call a measurement")[1],
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "BV2 the Tools & ports tab: the API refuses an anonymous caller and answers a viewer, runs the rating check and refuses an unknown tool and a "
+       "station with no depth; the page carries the tab, the unmatched-tools table and the rating-check form; `gea tools`, `--list`, `--json` and "
+       "`--rating --station` (exit 1 when a station is over a rating, and a malformed station named); the help page and its view mapping"
+       + (f" [failed: {', '.join(failed2)}]" if failed2 else ""))
+
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -7396,6 +7505,7 @@ def main() -> int:
         section_bs_catalog(tmp)
         section_bt_slip(tmp)
         section_bu_comcat(tmp)
+        section_bv_tools(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

gea_program-0.28.0/gea/help/tools.md

@@ -0,0 +1,11 @@
+# Tools and ports
+
+> What this program knows how to measure with, and what it knows how to speak. The tool library is the downhole and surface tools - each with the citation its numbers came from, the conditions it is rated for, and the telemetry interface it declares; the port registry is the file formats and live protocols that bring a tool's readings in. The page draws the line between them: a tool declares an interface, a port speaks one, and a tool whose interface no port in this build speaks is named rather than hidden.
+
+**The command**: the page is Tools & ports on the dashboard; `gea tools` prints the same register at the command line (`--json` for the machine record, `--rating --station <ft>:<tool> ...` for the rating check). A tool whose vendor published no numbers is listed as PARAMETERS_USER_SUPPLIED: `gea config` takes your own datasheet (`load_gauge_spec_json`) and the tool is then simulated and aged from it. The live protocols each name what the site must supply before they run and what to rehearse against - `gea wits0-sim`, `gea etp-sim`, `gea seedlink-sim`, or the stand-in slave, outstation, device and historian the field ports ship with.
+
+**What it writes**: nothing to the workspace - this page is a register, not a record. It states, per tool: the class, what it measures, the temperature and pressure ratings, the published aging rate in %FS/yr where the datasheet gives one (and the reason there is none where it does not), the interface it declares, the ports that can carry it, and its source. Per port: the transport, the status (IMPLEMENTED, or DECLARED_SITE_DETAILS_REQUIRED with what is missing), and what it speaks to. The rating check returns, per station, the temperature and pressure at that depth, the tool's ratings and whether the station is within them, with the basis of the conditions printed beside the answer.
+
+**The number to check**: the aging rate against your own datasheet before you trust a drift report built on it, and the rating check's per-station temperature against the tool's rating - the check that catches a 177 °C gauge hung in a 233 °C zone before the well does.
+
+**What this page will not call a measurement**: a vendor number nobody published - a tool with no datasheet rate carries none and raises rather than inventing one, and the page says PARAMETERS_USER_SUPPLIED. A rating as a prediction - a station within its ratings is arithmetic on the vendor's number and the declared conditions, not a promise the tool survives. The conditions themselves - without a well profile they are the gradients declared on the page, and the answer prints which basis it used. A port as a connection - a port listed here speaks a protocol; whether the site's own device answers is what the Patch panel shows.

{gea_program-0.27.0 → gea_program-0.28.0}/gea/helplib.py

@@ -42,6 +42,7 @@ INDEX: List[tuple] = [
     ('catalog', 'The catalogue', 'every shipped public dataset, what in this program reads it or that nothing does; the measured friction envelope; the core check; any log through the survey'),
     ('dlis', 'The DLIS log', 'a well log as it is delivered (API RP66 V1), read as the standard lays it out: the frames, the channels, what was skipped; into the strata survey'),
     ('historian', 'The historian pull', 'an operator\'s gauge history out of the PI System through PI Web API, read-only, every value with its archive time and flags'),
+    ('tools', 'Tools and ports', 'the downhole and surface tools this program knows, each with its citation and ratings, the formats and protocols that bring their readings in, and the rating check on a tool string'),
     ('field-ports', 'The field ports', 'Modbus RTU on the serial line, DNP3 from the pad RTU, HART-IP from the transmitter itself - read-only, polled, with the stand-ins to rehearse against'),
     ('slip', 'Slip tendency on the mapped faults', 'the declared stress state resolved on each mapped fault around a well: the slip tendency, the pressure to slip, the World Stress Map as the SHmax source, the published Hennings values beside'),
     ('interval', 'The interval against the mapped tops', 'the declared disposal interval, subsea, beside each formation-top bracket; the depth tier against the mapped base; the catalogue events against the mapped faults'),
@@ -66,7 +67,7 @@ REQUIRED_LINES = ('**The command**', '**What it writes**', '**The number to chec
 VIEW_TOPIC: Dict[str, str] = {
     'home': 'start', 'wells': 'data-in', 'well': 'drift', 'live': 'patches', 'patch': 'patches', 'files': 'files', 'alarms': 'alarms',
     'approvals': 'well-tests', 'config': 'site', 'reports': 'drift', 'verify': 'start', 'survey': 'data-in', 'jobs': 'site',
-    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'audit': 'audit-update',
+    'admin': 'site', 'prefs': 'site', 'search': 'start', 'welcome': 'start', 'seismic': 'seismic', 'seismic_station': 'seismic', 'track': 'seismic', 'sar': 'seismic', 'sites': 'sites', 'audit': 'audit-update', 'tools': 'tools',
 }
 
 

{gea_program-0.27.0 → gea_program-0.28.0}/gea/service.py

@@ -1637,6 +1637,9 @@ def make_handler(app: App):
                         raise ApiError(404, str(e))
                 if path == '/api/stress':
                     return self._json(200, {'stress': app.ws.stress(), 'stress_map': app.ws.stress_map()})
+                if path == '/api/tools':
+                    from . import tool_catalog as _TC
+                    return self._json(200, _TC.catalog())
                 if path == '/api/stress/wsm':
                     try:
                         lat, lon = float(qs['lat'][0]), float(qs['lon'][0]); rad = float(qs.get('radius_km', ['100'])[0])
@@ -1839,6 +1842,22 @@ def make_handler(app: App):
                                                                 depth_ft=(float(b['depth_ft']) if b.get('depth_ft') is not None else None), actor=user['name']))
                     except WorkspaceError as e:
                         raise ApiError(404, str(e))
+                if path == '/api/tools/rating':
+                    from . import tool_catalog as _TC
+                    b = body or {}
+                    try:
+                        stations = [(float(x['md_ft']), str(x['tool'])) for x in (b.get('stations') or [])]
+                    except (KeyError, TypeError, ValueError):
+                        raise ApiError(400, 'each station needs md_ft and tool')
+                    try:                                        # the conditions are the declared gradients, and the answer says so
+                        return self._json(200, _TC.check_string(stations, profile=None, deviation=None,
+                                                                surface_temp_F=float(b.get('surface_temp_F', 75.0)),
+                                                                temp_gradient_F_per_ft=float(b.get('temp_gradient_F_per_ft', 0.018)),
+                                                                surface_pressure_psi=float(b.get('surface_pressure_psi', 14.7)),
+                                                                pressure_gradient_psi_per_ft=float(b.get('pressure_gradient_psi_per_ft', 0.465)),
+                                                                name=str(b.get('name', 'toolstring'))))
+                    except (ValueError, KeyError) as e:
+                        raise ApiError(400, str(e))
                 if path == '/api/stress':
                     App.require(user, 'operator')
                     try:

gea_program-0.28.0/gea/tool_catalog.py

@@ -0,0 +1,190 @@
+# 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/.
+"""tool_catalog - what this program knows how to measure with, and what it knows how to speak.
+
+Two registers have lived in the code since the beginning and had no page: the tool library (the downhole and
+surface tools, each with a mandatory source citation, its ratings and the telemetry interface it declares) and
+the port registry (the formats and protocols that bring a tool's readings in). This module puts them side by
+side as one record, and draws the line between them: a tool declares an interface, a port speaks one, and the
+page says which tool each port can carry and which tool has no port in this build.
+
+Every entry is a declaration with a citation; nothing here is a measurement. A tool whose vendor published no
+numbers is PARAMETERS_USER_SUPPLIED and says so - its aging rate raises rather than inventing one. A port that
+needs the site's own details (a register map, an endpoint, a point list) is DECLARED_SITE_DETAILS_REQUIRED and
+names what it needs. The rating check is the one piece of arithmetic: a tool string hung in a well, each
+station's tool against the temperature and pressure at that station, from the well's own profile when there is
+one and from declared gradients when there is not.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+from .ports import PORT_REGISTRY
+from .tool_library import (FULLY_SPECIFIED, PARAMETERS_USER_SUPPLIED, TOOL_LIBRARY, ToolString, drift_model_for,
+                           rating_check)
+
+# the live protocol ports: the module that speaks each, and what the site must supply before it runs
+LIVE_PORTS: Dict[str, dict] = {
+    'wits0': {'module': 'gea.wits0', 'transport': 'WITS Level 0 over TCP connect, TCP listen or serial',
+              'needs': 'the sender (host and port, or the serial device) and the item map (four-digit code -> tag)',
+              'rehearse': 'gea wits0-sim', 'speaks': 'the mud logger or EDR on the drill floor'},
+    'witsml': {'module': 'gea.witsml', 'transport': 'WITSML 1.4.1.1 SOAP (read-only STORE interface)',
+               'needs': "the store's url, the well/wellbore/log uids and the environment variable names holding the credentials",
+               'rehearse': 'the in-package test store', 'speaks': 'a rig or operator WITSML 1.4 store'},
+    'etp': {'module': 'gea.etp', 'transport': 'WITSML 2.x over Energistics ETP v1.2 (WebSocket, Avro)',
+            'needs': 'the ETP endpoint and the channel URIs the store publishes',
+            'rehearse': 'gea etp-sim', 'speaks': 'a newer rig or store that pushes rather than answers polls'},
+    'opcua': {'module': 'gea.opcua_port', 'transport': 'OPC UA client (read and subscribe)',
+              'needs': "the server endpoint, the security policy and the node ids", 'rehearse': 'a recording, replayed offline',
+              'speaks': 'a pad PLC or SCADA server'},
+    'mqtt': {'module': 'gea.mqtt_port', 'transport': 'MQTT 3.1.1 / 5.0 subscriber, including Sparkplug B',
+             'needs': 'the broker, the topics and the tag map (topic/metric -> tag)', 'rehearse': 'a recording, replayed offline',
+             'speaks': 'an edge gateway publishing to a broker'},
+    'modbus_g6': {'module': 'gea.modbus', 'transport': 'Modbus TCP (read-only; pymodbus)',
+                  'needs': "the host and the site's register map with its citation", 'rehearse': 'an in-process loopback server',
+                  'speaks': 'a G6-class surface interface card on Ethernet'},
+    'modbus_rtu': {'module': 'gea.modbus_rtu', 'transport': 'Modbus RTU on RS-485 (pyserial) or RTU over TCP',
+                   'needs': "the serial device or converter, the unit id and the site's register map with its citation",
+                   'rehearse': 'the stand-in slave (transport: sim)', 'speaks': 'the RS-485 drop most surface-readout panels are'},
+    'dnp3': {'module': 'gea.dnp3', 'transport': 'DNP3 (IEEE 1815) master, read-only, over TCP',
+             'needs': "the master and outstation addresses and the RTU's point list with its source",
+             'rehearse': 'the stand-in outstation (transport: sim)', 'speaks': 'a pad RTU or pipeline SCADA'},
+    'hartip': {'module': 'gea.hartip', 'transport': 'HART-IP (TCP 5094), read-only: commands 0, 3 and 9',
+               'needs': "the gateway address and the variable map (pv, sv, tv, qv, loop_mA, dv:<code>) with the instrument's datasheet",
+               'rehearse': 'the stand-in device (transport: sim)', 'speaks': 'the transmitter itself through a HART-IP gateway'},
+    'piwebapi': {'module': 'gea.piwebapi', 'transport': 'AVEVA (OSIsoft) PI Web API over HTTPS, GET only',
+                 'needs': "the base url, the tag list with its source and the environment variable names holding the credentials",
+                 'rehearse': 'the stand-in server (base_url: sim)', 'speaks': "the operator's own PI Data Archive"},
+    'seedlink': {'module': 'gea.seedlink', 'transport': 'SeedLink 3 / 4.0 (TCP 18000), read-only',
+                 'needs': 'the server, the network and station codes and the channel selectors', 'rehearse': 'gea seedlink-sim',
+                 'speaks': 'a seismic data centre or a digitiser at the pad'},
+}
+# which live port a tool's declared telemetry interface can be carried by, by the words the declaration uses
+_INTERFACE_PORTS: Tuple[Tuple[str, Tuple[str, ...]], ...] = (
+    ('modbus rs485', ('modbus_rtu', 'modbus_g6')),
+    ('modbus', ('modbus_g6', 'modbus_rtu')),
+    ('4-20ma', ()),
+    ('thermocouple input card', ()),
+    ('fiber-optic interrogator', ()),
+    ('vibrating-wire', ()),
+    ('psk downhole telemetry', ('modbus_rtu', 'modbus_g6')),
+)
+
+
+def tools() -> List[dict]:
+    """Every tool in the library as the page shows it: what it is, what it measures, what it is rated for, what it
+    speaks, whether its numbers are published or the site's, its citation, and its published aging rate if it has one."""
+    out = []
+    for name, t in sorted(TOOL_LIBRARY.items()):
+        row = {'name': name, 'tool_class': t.tool_class, 'measures': list(t.measures), 'telemetry_interface': t.telemetry_interface,
+               'spec_status': t.spec_status, 'temp_rating_C': t.temp_rating_C, 'pressure_rating_psi': t.pressure_rating_psi,
+               'source': t.source, 'notes': t.notes, 'params': dict(t.params), 'aging_rate_pct_fs_yr': None, 'aging_note': '',
+               'ports': ports_for_interface(t.telemetry_interface)}
+        if t.gauge_spec is not None:
+            row['gauge_spec'] = {'full_scale_psi': t.gauge_spec.full_scale_psi, 'accuracy_pct_fs': t.gauge_spec.accuracy_pct_fs,
+                                 'max_temp_C': t.gauge_spec.max_temp_C, 'source': t.gauge_spec.source}
+        try:
+            row['aging_rate_pct_fs_yr'] = round(drift_model_for(t)(25.0, 1000.0), 6)
+            row['aging_note'] = "the datasheet's published drift rate"
+        except ValueError as e:
+            row['aging_note'] = str(e)
+        out.append(row)
+    return out
+
+
+def ports_for_interface(interface: str) -> List[str]:
+    """The live ports that can carry a declared telemetry interface, by the words the declaration uses."""
+    s = (interface or '').lower()
+    hits: List[str] = []
+    for word, names in _INTERFACE_PORTS:
+        if word in s:
+            for n in names:
+                if n not in hits:
+                    hits.append(n)
+    return hits
+
+
+def ports() -> dict:
+    """The two kinds of port: the file formats this program reads, and the live protocols it speaks."""
+    files = []
+    for name, spec in sorted(PORT_REGISTRY.items()):
+        files.append({'name': name, 'transport': spec.transport, 'status': spec.status, 'detail': spec.detail,
+                      'live': name in LIVE_PORTS})
+    live = []
+    for name, d in sorted(LIVE_PORTS.items()):
+        live.append({'name': name, **d, 'in_registry': name in PORT_REGISTRY,
+                     'registry_status': (PORT_REGISTRY[name].status if name in PORT_REGISTRY else '')})
+    return {'files': files, 'live': live}
+
+
+def unmatched() -> List[dict]:
+    """The tools whose declared interface no live port in this build speaks - named, not hidden."""
+    return [{'tool': t['name'], 'telemetry_interface': t['telemetry_interface']} for t in tools() if not t['ports']]
+
+
+def catalog() -> dict:
+    ts, ps = tools(), ports()
+    return {'tools': ts, 'ports': ps, 'unmatched': unmatched(),
+            'counts': {'tools': len(ts), 'fully_specified': sum(1 for t in ts if t['spec_status'] == FULLY_SPECIFIED),
+                       'user_supplied': sum(1 for t in ts if t['spec_status'] == PARAMETERS_USER_SUPPLIED),
+                       'file_ports': len(ps['files']), 'live_ports': len(ps['live'])},
+            'statement': ('Every tool and every port here is a declaration with its source, not a measurement. A tool whose vendor '
+                          'published no numbers carries none and says so; a port that needs the site\'s own details names them.')}
+
+
+def check_string(stations: List[Tuple[float, str]], profile=None, deviation=None, surface_temp_F: float = 75.0,
+                 temp_gradient_F_per_ft: float = 0.018, surface_pressure_psi: float = 14.7,
+                 pressure_gradient_psi_per_ft: float = 0.465, name: str = 'toolstring') -> dict:
+    """A tool string against a well: each station's tool at that station's conditions. Unknown tool names are
+    named, not guessed; the conditions' basis is stated with the answer."""
+    bad = [n for _, n in stations if n not in TOOL_LIBRARY]
+    if bad:
+        raise ValueError(f"not in the tool library: {', '.join(sorted(set(bad)))} (gea tools --list)")
+    if not stations:
+        raise ValueError('a tool string needs at least one station: (measured depth in feet, tool name)')
+    ts = ToolString(stations=[(float(md), n) for md, n in stations], name=name)
+    rows = rating_check(ts, profile=profile, deviation=deviation, surface_temp_F=surface_temp_F,
+                        temp_gradient_F_per_ft=temp_gradient_F_per_ft, surface_pressure_psi=surface_pressure_psi,
+                        pressure_gradient_psi_per_ft=pressure_gradient_psi_per_ft)
+    over = [r for r in rows if not r['ok']]
+    basis = ('the well profile' if profile is not None else
+             f'declared gradients: {surface_temp_F:g} F + {temp_gradient_F_per_ft:g} F/ft, {surface_pressure_psi:g} psi + {pressure_gradient_psi_per_ft:g} psi/ft')
+    return {'name': name, 'stations': rows, 'n_over_rating': len(over), 'basis': basis,
+            'deviation': 'measured depth converted to true vertical depth by the survey' if deviation is not None else 'measured depth taken as true vertical depth (no survey given)',
+            'lines': [f"{len(rows)} station(s) checked against {basis}; {len(over)} over a rating."] +
+                     [f"{r['tool']} at {r['md_ft']:,.0f} ft: {r['station_temp_C']:.1f} C, {r['station_pressure_psi']:,.0f} psi"
+                      + (f" - OVER its {r['temp_rating_C']:g} C rating" if r['over_temp_rating'] else '')
+                      + (f" - OVER its {r['pressure_rating_psi']:,.0f} psi rating" if r['over_pressure_rating'] else '')
+                      + ('' if not r['ok'] else ' - within its ratings') for r in rows] +
+                     ['A rating is the vendor\'s, and the conditions are the well\'s or the declaration\'s; this check is arithmetic on both, not a prediction of failure.']}
+
+
+def text() -> str:
+    c = catalog()
+    out = [f"tools: {c['counts']['tools']} ({c['counts']['fully_specified']} with published numbers, {c['counts']['user_supplied']} parameters user-supplied)"]
+    for t in c['tools']:
+        out.append(f"  {t['name']:<30s} {t['tool_class']:<24s} {t['spec_status']}")
+        out.append(f"      measures {', '.join(t['measures']) or '(none - it is an interface)'}; speaks {t['telemetry_interface']}")
+        if t['temp_rating_C'] or t['pressure_rating_psi']:
+            out.append(f"      rated {t['temp_rating_C'] or '?'} C, {t['pressure_rating_psi'] or '?'} psi")
+        out.append(f"      aging: {('%.4f %%FS/yr - ' % t['aging_rate_pct_fs_yr']) + t['aging_note'] if t['aging_rate_pct_fs_yr'] is not None else t['aging_note']}")
+        out.append(f"      ports: {', '.join(t['ports']) or 'none in this build'}")
+        out.append(f"      source: {t['source'][:160]}")
+    out.append('')
+    out.append(f"file ports: {c['counts']['file_ports']}")
+    for p in c['ports']['files']:
+        out.append(f"  {p['name']:<16s} {p['status']:<32s} {p['transport']}")
+    out.append('')
+    out.append(f"live ports: {c['counts']['live_ports']}")
+    for p in c['ports']['live']:
+        out.append(f"  {p['name']:<12s} {p['transport']}")
+        out.append(f"      speaks to {p['speaks']}; needs {p['needs']}; rehearse with {p['rehearse']}")
+    if c['unmatched']:
+        out.append('')
+        out.append('tools whose declared interface no live port in this build speaks:')
+        for u in c['unmatched']:
+            out.append(f"  {u['tool']}: {u['telemetry_interface']}")
+    out.append('')
+    out.append(c['statement'])
+    return '\n'.join(out)

{gea_program-0.27.0 → gea_program-0.28.0}/gea/web/app.html

@@ -264,6 +264,61 @@ VIEWS.well = async (id) => {
   catch (e) { $('#chart').innerHTML = `<p class="muted">${esc(e.message)}</p>`; }
 };
 
+VIEWS.tools = async () => {
+  const c = await get('/api/tools');
+  let h = `<h2>Tools and ports</h2>` + help('tools');
+  h += `<p class="small muted">${esc(c.statement)}</p>`;
+  h += `<div class="tiles">` + tile('Tools in the library', `${c.counts.tools}`, 'neutral', '#/tools', `${c.counts.fully_specified} with published numbers`)
+     + tile('Parameters user-supplied', `${c.counts.user_supplied}`, c.counts.user_supplied ? 'warn' : 'good', '#/tools', 'no vendor numbers on the fetched pages')
+     + tile('File formats read', `${c.counts.file_ports}`, 'neutral', '#/tools')
+     + tile('Live protocols spoken', `${c.counts.live_ports}`, 'neutral', '#/live') + `</div>`;
+
+  h += `<div class="card"><h3>The tool library <span class="small muted">every entry carries its source; a tool whose vendor published no numbers carries none</span></h3>`;
+  h += `<table><thead><tr><th>Tool</th><th>Class</th><th>Measures</th><th>Rated</th><th>Aging (%FS/yr)</th><th>Speaks</th><th>Ports</th><th>Numbers</th></tr></thead><tbody>`;
+  for (const t of c.tools) {
+    h += `<tr><td><b>${esc(t.name)}</b>${t.notes ? `<div class="small muted">${esc(t.notes)}</div>` : ''}</td><td class="small">${esc(t.tool_class)}</td><td class="small">${esc((t.measures || []).join(', ') || '— (an interface)')}</td>`
+       + `<td class="small">${t.temp_rating_C != null ? fmt(t.temp_rating_C, 0) + ' °C' : '—'}${t.pressure_rating_psi != null ? ' / ' + fmt(t.pressure_rating_psi, 0) + ' psi' : ''}</td>`
+       + `<td>${t.aging_rate_pct_fs_yr != null ? fmt(t.aging_rate_pct_fs_yr, 4) : `<span class="small muted" title="${esc(t.aging_note)}">none on record</span>`}</td>`
+       + `<td class="small">${esc(t.telemetry_interface)}</td><td class="small">${(t.ports || []).map(p => `<a href="#/live">${esc(p)}</a>`).join(', ') || '<span class="muted">none in this build</span>'}</td>`
+       + `<td>${statusPill(t.spec_status === 'FULLY_SPECIFIED' ? 'good' : 'warn', t.spec_status === 'FULLY_SPECIFIED' ? 'published' : 'user-supplied')}</td></tr>`;
+    h += `<tr><td colspan="8" class="small muted">source: ${esc(t.source)}</td></tr>`;
+  }
+  h += `</tbody></table></div>`;
+
+  if (c.unmatched && c.unmatched.length) {
+    h += `<div class="card"><h3>Tools no live port in this build speaks</h3><table><thead><tr><th>Tool</th><th>It declares</th></tr></thead><tbody>${c.unmatched.map(u => `<tr><td>${esc(u.tool)}</td><td class="small">${esc(u.telemetry_interface)}</td></tr>`).join('')}</tbody></table><p class="small muted">Named rather than hidden: a reading from one of these comes in as a file, or through a port the site adds.</p></div>`;
+  }
+
+  h += `<div class="card"><h3>Live protocols <span class="small muted">what each speaks to, what the site must supply, and what to rehearse against</span></h3>`;
+  h += `<table><thead><tr><th>Port</th><th>Transport</th><th>Speaks to</th><th>Needs from the site</th><th>Rehearse with</th></tr></thead><tbody>`;
+  for (const p of c.ports.live) h += `<tr><td><a href="#/live">${esc(p.name)}</a></td><td class="small">${esc(p.transport)}</td><td class="small">${esc(p.speaks)}</td><td class="small">${esc(p.needs)}</td><td class="small mono">${esc(p.rehearse)}</td></tr>`;
+  h += `</tbody></table></div>`;
+
+  h += `<div class="card"><h3>File formats <span class="small muted">what a file can be brought in as</span></h3>`;
+  h += `<table><thead><tr><th>Port</th><th>Transport</th><th>Status</th><th>Detail</th></tr></thead><tbody>`;
+  for (const p of c.ports.files) h += `<tr><td>${esc(p.name)}</td><td class="small">${esc(p.transport)}</td><td>${statusPill(p.status === 'IMPLEMENTED' ? 'good' : 'warn', p.status)}</td><td class="small">${esc(p.detail)}</td></tr>`;
+  h += `</tbody></table></div>`;
+
+  const names = c.tools.filter(t => (t.measures || []).length).map(t => t.name);
+  h += `<div class="card"><h3>Rating check <span class="small muted">a tool string hung in a well: each station's tool against the conditions there</span></h3>
+    <p class="small muted">The conditions come from the gradients declared here, and the answer says so. A rating is the vendor's; this check is arithmetic on both, not a prediction of failure.</p>
+    <div class="row"><label>Surface temperature °F<input id="rcT" type="number" step="0.1" value="75" style="width:7em"></label><label>Gradient °F/ft<input id="rcTG" type="number" step="0.001" value="0.018" style="width:7em"></label><label>Surface pressure psi<input id="rcP" type="number" step="0.1" value="14.7" style="width:7em"></label><label>Gradient psi/ft<input id="rcPG" type="number" step="0.001" value="0.465" style="width:7em"></label></div>
+    <div class="row" id="rcRows"></div>
+    <div class="row"><button class="secondary" id="rcAdd" type="button">Add a station</button><button id="rcRun" type="button">Check the string</button></div>
+    <div id="rcOut"></div></div>`;
+  $('#main').innerHTML = h;
+  const mk = (md) => { const d = document.createElement('div'); d.className = 'row'; d.style.margin = '0';
+    d.innerHTML = `<label>Measured depth ft<input type="number" class="rcMd" value="${md}" style="width:8em"></label><label>Tool<select class="rcTool">${names.map(n => `<option value="${esc(n)}">${esc(n)}</option>`).join('')}</select></label><button class="secondary rcDel" type="button">Remove</button>`;
+    d.querySelector('.rcDel').onclick = () => d.remove(); $('#rcRows').appendChild(d); };
+  mk(500); mk(9000);
+  $('#rcAdd').onclick = () => mk(12000);
+  $('#rcRun').onclick = async () => {
+    const stations = [...document.querySelectorAll('#rcRows .row')].map(r => ({md_ft: parseFloat(r.querySelector('.rcMd').value), tool: r.querySelector('.rcTool').value})).filter(x => !isNaN(x.md_ft));
+    try { const r = await post('/api/tools/rating', {stations, surface_temp_F: parseFloat($('#rcT').value), temp_gradient_F_per_ft: parseFloat($('#rcTG').value), surface_pressure_psi: parseFloat($('#rcP').value), pressure_gradient_psi_per_ft: parseFloat($('#rcPG').value)});
+      let o = `<p class="small"><b>${r.n_over_rating ? r.n_over_rating + ' station(s) over a rating' : 'every station within its ratings'}</b> — ${esc(r.basis)}; ${esc(r.deviation)}.</p>`;
+      o += `<table><thead><tr><th>Depth (ft)</th><th>Tool</th><th>Temperature (°C)</th><th>Pressure (psi)</th><th>Rated</th><th>Verdict</th></tr></thead><tbody>${r.stations.map(x => `<tr><td>${fmt(x.md_ft, 0)}</td><td>${esc(x.tool)}</td><td>${fmt(x.station_temp_C, 1)}</td><td>${fmt(x.station_pressure_psi, 0)}</td><td class="small">${x.temp_rating_C != null ? fmt(x.temp_rating_C, 0) + ' °C' : '—'}${x.pressure_rating_psi != null ? ' / ' + fmt(x.pressure_rating_psi, 0) + ' psi' : ''}</td><td>${statusPill(x.ok ? 'good' : 'serious', x.ok ? 'within ratings' : (x.over_temp_rating ? 'OVER TEMPERATURE' : 'OVER PRESSURE'))}</td></tr>`).join('')}</tbody></table>`;
+      $('#rcOut').innerHTML = o; } catch (e) { toast(e.message, 'err'); } };
+};
 VIEWS.sites = async () => {
   const {sites} = await get('/api/sites');
   let h = `<h2>Sites</h2><p class="muted small">A site is the engagement: the wells, the seismic stations and the tracks that belong to one client's ground, held together so there is one thing to refresh and one thing to hand over. The Site Report pulls every leg of it into one document and names anything that has not been run since the thing it was made from changed.</p>`;
@@ -1099,7 +1154,7 @@ function authScreen(first) {
 }
 
 // ---------- routing ---------------------------------------------------------------------
-const NAV = [['#/', 'Home'], ['#/sites', 'Sites'], ['#/wells', 'Wells'], ['#/seismic', 'Seismic'], ['#/sar', 'SAR panel'], ['#/live', 'Patch panel'], ['#/files', 'Files'], ['#/alarms', 'Alarms'], ['#/approvals', 'Approvals'], ['#/config', 'Configuration'], ['#/reports', 'Reports'], ['#/verify', 'Verification'], ['#/survey', 'Survey'], ['#/jobs', 'Jobs'], ['#/audit', 'Audit / Update'], ['#/admin', 'Administration'], ['#/help', 'Help']];
+const NAV = [['#/', 'Home'], ['#/sites', 'Sites'], ['#/wells', 'Wells'], ['#/seismic', 'Seismic'], ['#/sar', 'SAR panel'], ['#/live', 'Patch panel'], ['#/files', 'Files'], ['#/alarms', 'Alarms'], ['#/approvals', 'Approvals'], ['#/config', 'Configuration'], ['#/reports', 'Reports'], ['#/verify', 'Verification'], ['#/survey', 'Survey'], ['#/tools', 'Tools & ports'], ['#/jobs', 'Jobs'], ['#/audit', 'Audit / Update'], ['#/admin', 'Administration'], ['#/help', 'Help']];
 const BADGE = {'#/alarms': b => [b.alarms_unacked, ''], '#/approvals': b => [b.approvals_pending, 'w'], '#/jobs': b => [b.jobs_failed_24h, ''], '#/live': b => [b.patches_down, '']};
 function renderNav() { const cur = (location.hash || '#/').split('?')[0]; $('#nav').innerHTML = NAV.map(([h, l]) => { const f = BADGE[h]; const [n, k] = f ? f(BADGES) : [0, '']; return `<a href="${h}" ${(h === '#/' ? cur === '#/' || cur === '' : cur.startsWith(h)) ? 'aria-current="page"' : ''}>${l}${n ? `<span class="b ${k}" title="${n} needing attention">${n}</span>` : ''}</a>`; }).join(''); }
 async function refreshBadges() { if (!me) return; try { BADGES = await get('/api/badges'); renderNav(); const t = BADGES.alarms_unacked ? `(${BADGES.alarms_unacked}) ` : ''; document.title = `${t}GEA-Program · ${workspaceName}`; } catch (e) {} }