gea-program 0.86.0__tar.gz → 0.88.0__tar.gz

{gea_program-0.86.0 → gea_program-0.88.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.86.0
+Version: 0.88.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
@@ -847,7 +847,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.86.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.88.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -1000,6 +1000,59 @@ in plan, in section and, at its depths, in the 3D tab. Every figure a
 SIMULATION, said on every line. The **Fluid front** tab, `gea front`,
 `gea help front`.
 
+### Calibration
+
+The plume and the front, run many times over the numbers nobody knows
+exactly and ranked against what is measured. Each uncertain number - the
+permeability, the thickness, the porosity, the compressibility - gets a
+range, declared with its source or a default spread named as one; each
+fault layer is open in half the runs and sealing in the other half. Every
+run is scored against the pressures in the ledger (a gauge in an
+observation well, an injector's or a producer's own bottomhole pressure,
+each compared in its shape through time) and the producers' measured TDS;
+the runs the measurements do not contradict are kept, and when none comes
+close the page says NO RUN FITS and to look outside the ranges. Every
+forecast the other pages give as one number - the area of review, each
+fault's rise and the share of kept runs that take it past the friction
+line, the front's radius, each producer's share and arrival - is given as
+a range: what the declarations alone allow beside what the measurements
+leave. And what to measure next, ranked: a falloff test, a gauge at a
+neighbour, a water analysis, each with how much it would narrow the area
+of review and the front. Run by a person, kept with the hash of its inputs,
+marked stale when they change. Every figure a SIMULATION. The
+**Calibration** tab, `gea calibrate`, `gea help calibration`.
+
+### Drilling roadmap
+
+What the fastest stands on the pad were drilled with, stretch by stretch.
+Every well's drilling record is cut into stands of 100 ft; each stand goes
+into the stretch of hole it was drilled in - 1,000 ft of true vertical
+depth down to the heel, 1,000 ft along the hole beyond it, named for the
+mapped formation where the workspace has the tops and the well its
+elevation. In each stretch the fastest quarter of the stands is found, and
+the window is what those stands ran: the weight on bit, the rotary speed,
+the flow, the differential pressure, beside the well that was fastest
+there and what every other well ran through the same rock. Then the
+roadmap checks itself: each well is set against the roadmap made from the
+others, the half of its stands nearer the window against the farther half,
+stretch by stretch - so the page says whether running nearer the window
+went with drilling faster, or did not, before anyone drills the next well
+from it. The **Roadmap** tab, `gea roadmap`, `gea help roadmap`.
+
+### Drilling alerts
+
+Three old driller's rules, written down so each is applied to every stand
+of every well the same way, and replayed over the whole of each record:
+the off-bottom pressure falling at a steady flow, connection after
+connection (a washout - or a pump, the mud or a nozzle; the trip finds
+which); the differential pressure spiking with the bit stopped (a motor
+stall); the pick-up and slack-off weight leaving their own trend (the hole
+getting tight). The page shows every reading, what each rule would have
+said and when, and what the rig did next - whether a trip out of the hole
+followed. The thresholds are settings, each changed with its source. On a
+record still being written an event raises an alert once. The **Drilling
+alerts** tab, `gea dysfunction`, `gea help dysfunction`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1664,7 +1717,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.86.0.exe` (for 0.86.0): the
+Every release also carries `GEA-Program-Setup-0.88.0.exe` (for 0.88.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1683,7 +1736,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.86.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.86.0 → gea_program-0.88.0}/README.md

@@ -808,7 +808,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.86.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.88.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -961,6 +961,59 @@ in plan, in section and, at its depths, in the 3D tab. Every figure a
 SIMULATION, said on every line. The **Fluid front** tab, `gea front`,
 `gea help front`.
 
+### Calibration
+
+The plume and the front, run many times over the numbers nobody knows
+exactly and ranked against what is measured. Each uncertain number - the
+permeability, the thickness, the porosity, the compressibility - gets a
+range, declared with its source or a default spread named as one; each
+fault layer is open in half the runs and sealing in the other half. Every
+run is scored against the pressures in the ledger (a gauge in an
+observation well, an injector's or a producer's own bottomhole pressure,
+each compared in its shape through time) and the producers' measured TDS;
+the runs the measurements do not contradict are kept, and when none comes
+close the page says NO RUN FITS and to look outside the ranges. Every
+forecast the other pages give as one number - the area of review, each
+fault's rise and the share of kept runs that take it past the friction
+line, the front's radius, each producer's share and arrival - is given as
+a range: what the declarations alone allow beside what the measurements
+leave. And what to measure next, ranked: a falloff test, a gauge at a
+neighbour, a water analysis, each with how much it would narrow the area
+of review and the front. Run by a person, kept with the hash of its inputs,
+marked stale when they change. Every figure a SIMULATION. The
+**Calibration** tab, `gea calibrate`, `gea help calibration`.
+
+### Drilling roadmap
+
+What the fastest stands on the pad were drilled with, stretch by stretch.
+Every well's drilling record is cut into stands of 100 ft; each stand goes
+into the stretch of hole it was drilled in - 1,000 ft of true vertical
+depth down to the heel, 1,000 ft along the hole beyond it, named for the
+mapped formation where the workspace has the tops and the well its
+elevation. In each stretch the fastest quarter of the stands is found, and
+the window is what those stands ran: the weight on bit, the rotary speed,
+the flow, the differential pressure, beside the well that was fastest
+there and what every other well ran through the same rock. Then the
+roadmap checks itself: each well is set against the roadmap made from the
+others, the half of its stands nearer the window against the farther half,
+stretch by stretch - so the page says whether running nearer the window
+went with drilling faster, or did not, before anyone drills the next well
+from it. The **Roadmap** tab, `gea roadmap`, `gea help roadmap`.
+
+### Drilling alerts
+
+Three old driller's rules, written down so each is applied to every stand
+of every well the same way, and replayed over the whole of each record:
+the off-bottom pressure falling at a steady flow, connection after
+connection (a washout - or a pump, the mud or a nozzle; the trip finds
+which); the differential pressure spiking with the bit stopped (a motor
+stall); the pick-up and slack-off weight leaving their own trend (the hole
+getting tight). The page shows every reading, what each rule would have
+said and when, and what the rig did next - whether a trip out of the hole
+followed. The thresholds are settings, each changed with its source. On a
+record still being written an event raises an alert once. The **Drilling
+alerts** tab, `gea dysfunction`, `gea help dysfunction`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1625,7 +1678,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.86.0.exe` (for 0.86.0): the
+Every release also carries `GEA-Program-Setup-0.88.0.exe` (for 0.88.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1644,7 +1697,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.86.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.86.0 → gea_program-0.88.0}/gea/__init__.py

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

{gea_program-0.86.0 → gea_program-0.88.0}/gea/__main__.py

@@ -565,7 +565,7 @@ def main(argv=None) -> int:
     p_fl.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs on labelled scenes")
     p_fl.add_argument("--well", type=str, default=None, help="the well a declaration, a report or a removal is for")
     p_fl.add_argument("--declare", action="store_true", help="declare the well's role, formation or density (with --source)")
-    p_fl.add_argument("--role", type=str, default=None, choices=("injection", "production"))
+    p_fl.add_argument("--role", type=str, default=None, choices=("injection", "production", "observation"), help="--declare: injection, production, or observation (a gauge or a water analysis, no flow)")
     p_fl.add_argument("--formation", type=str, default=None, help="--declare: the formation the well is completed in; alone with --porosity etc.: the formation to declare")
     p_fl.add_argument("--density-sg", type=float, default=None, help="--declare: the injected water's specific gravity")
     p_fl.add_argument("--density-ppg", type=float, default=None, help="--declare: the injected water's density in lb/gal")
@@ -611,6 +611,41 @@ def main(argv=None) -> int:
     p_ff.add_argument("--write", action="store_true", help="write reports/front/front.json and .md")
     p_ff.add_argument("--actor", type=str, default="cli")
     p_ff.add_argument("--json", action="store_true")
+    p_cb = sub.add_parser("calibrate", help="the calibration (SIMULATION): the plume and the front run many times over the uncertain numbers - permeability, thickness, porosity, compressibility, each fault open or sealing - ranked against the measured pressures and the producers' water; the ranges that leaves, and which measurement would narrow them most")
+    p_cb.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (a formation whose true numbers are not the declared ones, found from its measurements)")
+    p_cb.add_argument("--run", action="store_true", help="run the ensemble now and keep the result")
+    p_cb.add_argument("--formation", type=str, default=None, help="--run: one formation; --range: the formation the range is for")
+    p_cb.add_argument("--runs", type=int, default=None, help="settings: the runs, 8 to 200 (default 48)")
+    p_cb.add_argument("--sigma-psi", type=float, default=None, help="settings: the pressure measurements' error, psi (default 25)")
+    p_cb.add_argument("--sigma-share", type=float, default=None, help="settings: the error of a share of injected water read from a TDS (default 0.05)")
+    p_cb.add_argument("--well-radius-ft", type=float, default=None, help="settings: the wellbore radius for a flowing well's own draw (default 0.354)")
+    p_cb.add_argument("--sample-sealing", type=str, default=None, choices=("yes", "no"), help="settings: whether each fault layer is open in half the runs and sealing in the other half (default yes)")
+    p_cb.add_argument("--range", dest="range_param", type=str, default=None, choices=("k_md", "thickness_ft", "porosity", "c_t_per_psi"), help="declare an uncertain number's range for --formation: --low, --high, --source (or --clear)")
+    p_cb.add_argument("--low", type=float, default=None)
+    p_cb.add_argument("--high", type=float, default=None)
+    p_cb.add_argument("--clear", action="store_true", help="--range: back to the default spread")
+    p_cb.add_argument("--source", type=str, default="", help="where a declared range comes from")
+    p_cb.add_argument("--write", action="store_true", help="write reports/calibration/calibration.json and .md from the kept result")
+    p_cb.add_argument("--actor", type=str, default="cli")
+    p_cb.add_argument("--json", action="store_true")
+    p_rm = sub.add_parser("roadmap", help="the drilling roadmap: for every stretch of hole, the weight on bit, rotary speed, flow and differential pressure the fastest quarter of the stands on the pad's wells were drilled with, which well was fastest there, and each well checked against the roadmap made from the others")
+    p_rm.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (three labelled wells through rock with a known best weight and speed)")
+    p_rm.add_argument("--well", type=str, default=None, help="the well the next stand is given for (default: the well whose record ends last)")
+    p_rm.add_argument("--write", action="store_true", help="write reports/roadmap/roadmap.json, .md and .csv")
+    p_rm.add_argument("--actor", type=str, default="cli")
+    p_rm.add_argument("--json", action="store_true")
+    p_dy = sub.add_parser("dysfunction", help="drilling alerts replayed over each well's record: the off-bottom pressure falling at a steady flow (a washout), the differential pressure spiking with the bit stopped (a motor stall), the pick-up weight leaving its own trend (the hole getting tight) - what each rule would have said, when, and whether a trip followed")
+    p_dy.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (a labelled record with a washout, three stalls and a tightening hole put in, and a sound one)")
+    p_dy.add_argument("--washout-fall", type=float, default=None, help="settings: the fall in off-bottom pressure that flags a reading, as a fraction (default 0.06)")
+    p_dy.add_argument("--washout-min-psi", type=float, default=None, help="settings: and the least fall in psi (default 100)")
+    p_dy.add_argument("--stall-rise", type=float, default=None, help="settings: the rise in differential pressure over its median that is a stall, as a fraction (default 0.6)")
+    p_dy.add_argument("--stall-min-psi", type=float, default=None, help="settings: and the least rise in psi (default 300)")
+    p_dy.add_argument("--drag-sigma", type=float, default=None, help="settings: how many scatters off its trend a pick-up or slack-off weight is flagged at (default 3)")
+    p_dy.add_argument("--drag-min-klbf", type=float, default=None, help="settings: and the least distance in klbf (default 10)")
+    p_dy.add_argument("--source", type=str, default="", help="who set a changed setting and on what grounds")
+    p_dy.add_argument("--write", action="store_true", help="write reports/dysfunction/drilling_alerts.json, .md and events.csv")
+    p_dy.add_argument("--actor", type=str, default="cli")
+    p_dy.add_argument("--json", action="store_true")
     p_os = sub.add_parser("seismicity", help="operations and seismicity: each well's drilling, completion and disposal windows against the earthquake catalogue around it - the events during and after each, the levels a regulator's protocol would reach, and the rate during operations against the rest of the record; the Mahoning Valley worked example")
     p_os.add_argument("--workspace", type=str, default=None)
     p_os.add_argument("--scene", type=str, default=None, choices=("workspace", "mahoning"), help="your wells (the default with --workspace) or the public worked example")
@@ -2776,6 +2811,91 @@ def main(argv=None) -> int:
             raise SystemExit(f"front: {e.args[0] if e.args else e}")
         print(_json.dumps(p, default=str) if a.json else _FF.text(p))
         return 0
+    elif a.cmd == "calibrate":
+        import json as _json
+        from . import calibration as _CB
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            r = _CB.selftest()
+            print(_json.dumps(r, default=str) if a.json else "\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']} ({r['runs']} runs)")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"calibrate: {e}")
+        try:
+            if a.range_param:
+                if not a.formation:
+                    raise SystemExit("calibrate: --range needs --formation")
+                _CB.set_range(ws, a.actor, a.formation, a.range_param, None if a.clear else a.low, None if a.clear else a.high, a.source)
+                rg_ = _CB.page(ws)["ranges"].get(a.formation, {}).get(a.range_param)
+                print(f"{a.formation} {a.range_param}: " + (f"{rg_['low']:g} to {rg_['high']:g} ({rg_['kind']}: {rg_['source']})" if rg_ else "kept; the formation has no permeability, thickness and porosity declared yet"))
+                return 0
+            if any(v is not None for v in (a.runs, a.sigma_psi, a.sigma_share, a.well_radius_ft, a.sample_sealing)):
+                st_ = _CB.set_settings(ws, a.actor, a.runs, a.sigma_psi, a.sigma_share, (None if a.sample_sealing is None else a.sample_sealing == "yes"), a.well_radius_ft)
+                print("settings: " + ", ".join(f"{k} {v}" for k, v in st_.items() if k in ("runs", "sigma_psi", "sigma_share", "well_radius_ft", "sample_sealing")))
+                if not a.run:
+                    return 0
+            if a.run:
+                r = _CB.run(ws, a.actor, a.formation)
+                print(f"run: {r['seconds']} s; " + "; ".join(f"{f['formation']} {f['status']}" + (f" ({f['n_kept']} of {f['n_ok']} kept)" if f.get('n_kept') is not None else "") for f in r["formations"]))
+            if a.write:
+                from . import __version__ as _ver87
+                r = _CB.write_report(ws, _ver87, a.actor)
+                print(f"written: {', '.join(r['files'])} under {r['folder']}")
+            p = _CB.page(ws)
+        except (_CB.CalibrationError, WorkspaceError, ValueError, OSError) as e:
+            raise SystemExit(f"calibrate: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _CB.text(p))
+        return 0
+    elif a.cmd == "roadmap":
+        import json as _json
+        from . import roadmap as _RM
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            r = _RM.selftest()
+            print(_json.dumps(r, default=str) if a.json else "\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']}")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+            if a.write:
+                from . import __version__ as _ver88r
+                r = _RM.write_report(ws, _ver88r, a.actor)
+                print(f"written: {', '.join(r['files'])} under {r['folder']}")
+            p = _RM.page(ws, a.well)
+        except (_RM.RoadmapError, WorkspaceError, ValueError, OSError) as e:
+            raise SystemExit(f"roadmap: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _RM.text(p))
+        return 0
+    elif a.cmd == "dysfunction":
+        import json as _json
+        from . import dysfunction as _DY
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            r = _DY.selftest()
+            print(_json.dumps(r, default=str) if a.json else "\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']}")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+            kw_ = {"washout_fall": a.washout_fall, "washout_min_psi": a.washout_min_psi, "stall_rise": a.stall_rise, "stall_min_psi": a.stall_min_psi, "drag_sigma": a.drag_sigma, "drag_min_klbf": a.drag_min_klbf}
+            if any(v is not None for v in kw_.values()):
+                st_ = _DY.set_settings(ws, a.actor, a.source, **kw_)
+                print("settings: " + ", ".join(f"{k} {st_[k]:g}" for k in _DY.DEFAULTS))
+            if a.write:
+                from . import __version__ as _ver88d
+                r = _DY.write_report(ws, _ver88d, a.actor)
+                print(f"written: {', '.join(r['files'])} under {r['folder']}")
+            p = _DY.page(ws)
+        except (_DY.DysfunctionError, WorkspaceError, ValueError, OSError) as e:
+            raise SystemExit(f"dysfunction: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _DY.text(p))
+        return 0
     elif a.cmd == "seismicity":
         import json as _json
         from . import op_seismicity as _OS