gea-program 0.1.0__py3-none-any.whl

gea/project.py

@@ -0,0 +1,213 @@
+# 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/.
+"""project - Part 7 of the subsurface surveying tool: THE CLIENT SHELL
+(v1.84.0) - project files and the client report.
+
+A SurveyProject is what a client engagement touches: a JSON project file
+(name, created stamp, tool versions, render paths, notes) plus
+`generate_report()` - the deliverable that assembles EVERYTHING the tool
+can currently prove into one markdown document:
+
+  - Earth Model census and the structural-ladder audit
+  - K2 gravity validation (with its circularity caveat, verbatim)
+  - the inverse engine's current read and both predictions' status
+    (including the REFUTED one - the scoring record IS the product)
+  - the standing blind accuracy table, weak tails included
+  - the correlation findings (time frame + the refusal census)
+  - the honest renders, regenerated fresh if matplotlib is present
+
+Every number in the report is computed AT GENERATION TIME from the same
+modules the gate verifies - a report cannot say anything the gate cannot
+prove, and each section names its machinery. The CLI exposes this as
+`python -m gea report --out <dir>`.
+
+The Qt operator surface gains geology through `build_geology_tab(...)`
+(guarded, optional): the site map and cross-section rendered into the
+operator app - the surface stops drawing only gauges.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import statistics
+import time
+from typing import Dict, Optional
+
+
+def create_project(path: str, name: str, notes: str = '') -> Dict:
+    """Create/overwrite a survey project file (JSON, human-readable)."""
+    from . import __version__ as sim_version
+    proj = {'name': name, 'notes': notes,
+            'created_utc': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()),
+            'simulator_version': sim_version,
+            'renders': {}, 'report': None}
+    with open(path, 'w', encoding='utf-8') as f:
+        json.dump(proj, f, indent=2)
+    return proj
+
+
+def load_project(path: str) -> Dict:
+    with open(path, encoding='utf-8') as f:
+        return json.load(f)
+
+
+def generate_report(out_dir: str, project_path: Optional[str] = None,
+                    name: str = 'GEA Subsurface Survey Report') -> Dict:
+    """The client deliverable. Returns {'report_path', 'renders', 'sections'};
+    every figure is regenerated, every number recomputed, at call time."""
+    from . import __version__ as sim_version
+    from .earth_model import EarthModel
+    from .forward_model import ktb_gravity_test
+    from .inverse_engine import invert_gravity_column
+    from .blind_harness import accuracy_report
+    from .correlation import time_frame, depth_frame_pairs
+
+    os.makedirs(out_dir, exist_ok=True)
+    em = EarthModel()
+    cen = em.census()
+    k2 = ktb_gravity_test()
+    inv = invert_gravity_column(prior_family='continental_crystalline')
+    acc = accuracy_report()
+    tf = time_frame(em)
+    df = depth_frame_pairs(em)
+
+    renders = {}
+    try:
+        from .survey_view import render_site_map, render_ktb_inversion
+        m = os.path.join(out_dir, 'site_map.png')
+        x = os.path.join(out_dir, 'inversion_cross_section.png')
+        render_site_map(m)
+        render_ktb_inversion(x)
+        renders = {'site_map': m, 'cross_section': x}
+    except ImportError:
+        renders = {'note': 'matplotlib absent - figures skipped, disclosed'}
+
+    ins = [e for e in inv['estimates']
+           if e.posteriors['vp']['status'] == 'OK'
+           and not e.posteriors['vp']['extrapolation']]
+    v2 = [e.posteriors['vp']['estimate'] for e in ins]
+    nf = k2['null_filtered']
+
+    lines = []
+    w = lines.append
+    w('# %s' % name)
+    w('')
+    w('*Generated %s UTC by gea v%s (ENRGYONE / '
+      'GEA-Program). Every number below is recomputed at generation '
+      'time by the same gate-verified modules; each section names its '
+      'machinery.*' % (time.strftime('%Y-%m-%d %H:%M', time.gmtime()),
+                       sim_version))
+    w('')
+    w('## 1. The registered library (`earth_model`)')
+    w('')
+    w('%d sites registered from archive-declared coordinates only, spanning '
+      '%.1f degrees of latitude and %.0f km of great circle; %d entries '
+      'unregistered with reasons on file; %d multi-entry sites reunited by '
+      'coordinates alone.'
+      % (cen['sites'], cen['latitude_span_deg'],
+         cen['great_circle_span_km'], cen['unregistered_entries'],
+         cen['multi_entry_sites']))
+    w('')
+    w('## 3. Gravity kernel validation (`forward_model`)')
+    w('')
+    w('Standard-constant gravity kernel vs the KTB borehole gravimeter: correlation '
+      '%.4f over %d intervals, mean residual %.4f mGal. Caveat, verbatim: '
+      '%s' % (nf['correlation'], nf['n'], nf['mean_residual_mgal'],
+              k2['circularity_caveat']))
+    w('')
+    w('## 4. The scoring record (`inverse_engine`)')
+    w('')
+    w('- Prediction v1 (transferred 504B prior): **REFUTED** at +10%% '
+      '(measured 6,228 m/s vs predicted 5,675±109) - diagnosis was the '
+      'assumption disclosed on every estimate in advance.')
+    w('- Prediction V2 (continental_crystalline family prior): Vp '
+      '%.0f-%.0f m/s (mean %.0f) over %d in-support intervals - '
+      '**PINNED_AWAITING_DEEP_SONIC**, unsettled by design.'
+      % (min(v2), max(v2), statistics.mean(v2), len(ins)))
+    w('')
+    w('## 5. Standing blind accuracy (`blind_harness`)')
+    w('')
+    w('| given → target | well | n | MAE %% | coverage |')
+    w('|---|---|---|---|---|')
+    for row in acc['ok']:
+        w('| %s → %s | %s | %d | %.2f | %.2f |'
+          % (row['given'], row['target'], row['well'], row['n'],
+             row['mae_pct'], row['coverage']))
+    w('')
+    w('Median 1σ coverage %.2f (honest target ~0.68). %d thin pairs '
+      'refused. %s' % (acc['median_coverage'], acc['n_refused'],
+                       acc['doctrine']))
+    w('')
+    w('## 6. Correlation (`correlation`)')
+    w('')
+    w('Time frame: %d age-bearing sites; master chronology %s overlaps %d '
+      'others. Depth frame: %s'
+      % (tf['n_sites'], tf['master_chronology']['site'],
+         tf['master_chronology']['overlaps_others'], df['finding']))
+    w('')
+    if 'site_map' in renders:
+        w('## 7. Figures')
+        w('')
+        w('![site map](site_map.png)')
+        w('')
+        w('![inversion cross-section](inversion_cross_section.png)')
+        w('')
+    w('---')
+    w('*What this report will not do: quote unmeasured accuracy, fill '
+      'missing data with templates, or present transferred models as site '
+      'truth. Refusals above are deliberate outputs of the same doctrine '
+      'that produced the numbers.*')
+
+    report_path = os.path.join(out_dir, 'survey_report.md')
+    with open(report_path, 'w', encoding='utf-8', newline='') as f:
+        f.write('\n'.join(lines) + '\n')
+
+    if project_path:
+        proj = load_project(project_path)
+        proj['renders'] = renders
+        proj['report'] = report_path
+        with open(project_path, 'w', encoding='utf-8') as f:
+            json.dump(proj, f, indent=2)
+
+    return {'report_path': report_path, 'renders': renders,
+            'sections': 7 if 'site_map' in renders else 6}
+
+
+def build_geology_tab(parent=None):
+    """The operator surface stops drawing only gauges: a Qt widget holding
+    the regenerated site map and cross-section. Optional by construction -
+    raises a clear ImportError naming PyQt6/matplotlib if absent; nothing
+    load-bearing depends on it."""
+    try:
+        from PyQt6.QtWidgets import (QWidget, QVBoxLayout, QLabel,
+                                     QScrollArea)
+        from PyQt6.QtGui import QPixmap
+    except ImportError as e:
+        raise ImportError(
+            'build_geology_tab needs the optional gui extra '
+            '(pip install "gea-program[gui]")') from e
+    import tempfile
+    from .survey_view import render_site_map, render_ktb_inversion
+    td = tempfile.mkdtemp(prefix='geology_')
+    m = os.path.join(td, 'map.png')
+    x = os.path.join(td, 'xsec.png')
+    render_site_map(m)
+    render_ktb_inversion(x)
+    tab = QWidget(parent)
+    lay = QVBoxLayout(tab)
+    scroll = QScrollArea(tab)
+    inner = QWidget()
+    ilay = QVBoxLayout(inner)
+    for path, title in ((m, 'Earth Model - registered sites'),
+                        (x, 'Inverse engine - KTB read (V2 unsettled)')):
+        cap = QLabel(title)
+        img = QLabel()
+        img.setPixmap(QPixmap(path))
+        ilay.addWidget(cap)
+        ilay.addWidget(img)
+    scroll.setWidget(inner)
+    scroll.setWidgetResizable(True)
+    lay.addWidget(scroll)
+    return tab

gea/qt6_downhole_app.py

@@ -0,0 +1,144 @@
+# 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/.
+"""qt6_downhole_app — PyQt6 GUI for the GEA Downhole Simulator (optional).
+
+Template-faithful port (22Aug2026 thread): control panel + embedded matplotlib
+canvas, QTimer-driven stepping at 120 ms, CSV export button. Knob ruling
+applied: the spinboxes are the ENGINEERING TRIMS (k_structural_trim /
+phi_coupling_trim, range 0.50-1.50, default 1.00) — the canonical K_MEX = 25/12
+and Phi_res = 0.84 are locked inside the physics layer and shown read-only.
+
+PyQt6 is an OPTIONAL dependency: `pip install PyQt6 matplotlib`.
+Run:  python -m gea.qt6_downhole_app
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .downhole_engine import SimulatorConfig, DownholeEngine
+from .quartz_hpht_extension import canonical_suppression
+
+try:
+    from PyQt6.QtCore import QTimer
+    from PyQt6.QtWidgets import (QApplication, QDoubleSpinBox, QFormLayout,
+                                 QGroupBox, QHBoxLayout, QLabel, QMainWindow,
+                                 QPushButton, QVBoxLayout, QWidget)
+    from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg
+    from matplotlib.figure import Figure
+    QT_AVAILABLE = True
+except ImportError:
+    QT_AVAILABLE = False
+
+
+if QT_AVAILABLE:
+
+    class MplCanvas(FigureCanvasQTAgg):
+        def __init__(self):
+            self.fig = Figure(figsize=(9, 7), facecolor="#0b1220")
+            self.ax_p = self.fig.add_subplot(211, facecolor="#101a2e")
+            self.ax_t = self.fig.add_subplot(212, facecolor="#101a2e")
+            super().__init__(self.fig)
+
+    class MainWindow(QMainWindow):
+        def __init__(self):
+            super().__init__()
+            self.setWindowTitle("GEA Deep-Well Quartz Simulator (PyQt6) - gea-program")
+            self.resize(1480, 920)
+            self.cfg = SimulatorConfig()
+            self.engine = DownholeEngine(self.cfg)
+            self._build_ui()
+            self.timer = QTimer(self)
+            self.timer.timeout.connect(self._on_timer)
+            self.timer.setInterval(120)
+            self.statusBar().showMessage("Ready")
+
+        def _build_ui(self):
+            central = QWidget()
+            self.setCentralWidget(central)
+            main_layout = QHBoxLayout(central)
+
+            control = QWidget()
+            control.setFixedWidth(360)
+            clayout = QVBoxLayout(control)
+
+            gbox = QGroupBox("Canonical GEA primitives (LOCKED)")
+            form0 = QFormLayout(gbox)
+            form0.addRow("K_MEX", QLabel("25/12 = 2.0833  (PAPER_1522)"))
+            form0.addRow("Phi_res", QLabel("0.84  (PAPER_2134)"))
+            form0.addRow("rho ratio", QLabel("F_TRZ = 0.1  (PAPER_1160)"))
+            form0.addRow("suppression", QLabel(f"{canonical_suppression():.4f} at unity trims"))
+            clayout.addWidget(gbox)
+
+            tbox = QGroupBox("Engineering trims (instrument tuning)")
+            form = QFormLayout(tbox)
+            self.spin_k = QDoubleSpinBox()
+            self.spin_k.setRange(0.50, 1.50)
+            self.spin_k.setSingleStep(0.01)
+            self.spin_k.setValue(1.00)
+            self.spin_phi = QDoubleSpinBox()
+            self.spin_phi.setRange(0.50, 1.50)
+            self.spin_phi.setSingleStep(0.01)
+            self.spin_phi.setValue(1.00)
+            form.addRow("k_structural_trim", self.spin_k)
+            form.addRow("phi_coupling_trim", self.spin_phi)
+            self.spin_k.valueChanged.connect(self._on_trims)
+            self.spin_phi.valueChanged.connect(self._on_trims)
+            clayout.addWidget(tbox)
+
+            self.btn_start = QPushButton("Start")
+            self.btn_stop = QPushButton("Stop")
+            self.btn_export = QPushButton("Export CSV")
+            self.btn_start.clicked.connect(self.timer.start)
+            self.btn_stop.clicked.connect(self.timer.stop)
+            self.btn_export.clicked.connect(self._on_export)
+            for b in (self.btn_start, self.btn_stop, self.btn_export):
+                clayout.addWidget(b)
+            clayout.addStretch(1)
+
+            self.canvas = MplCanvas()
+            main_layout.addWidget(control)
+            main_layout.addWidget(self.canvas, stretch=1)
+
+        def _on_trims(self):
+            self.engine.set_global_trims(self.spin_k.value(), self.spin_phi.value())
+
+        def _on_export(self):
+            p = self.engine.export_csv()
+            self.statusBar().showMessage(f"Exported: {p.resolve()}")
+
+        def _on_timer(self):
+            e = self.engine
+            e.step()
+            for ax, hist, label in ((self.canvas.ax_p, e.history_P, "Pressure (psi)"),
+                                    (self.canvas.ax_t, e.history_T, "Temperature (\N{DEGREE SIGN}F)")):
+                ax.clear()
+                ax.set_facecolor("#101a2e")
+                ax.grid(True, alpha=0.3)
+                ax.set_ylabel(label, color="#e0f2fe")
+                ax.tick_params(colors="#e0f2fe")
+                for i, s in enumerate(e.sensors):
+                    ax.plot(e.history_t, [row[i] for row in hist], lw=1.4,
+                            label=f"{s.name} ({s.depth_ft:.0f} ft)")
+                ax.legend(fontsize=7, loc="upper right")
+            s = e.summary()
+            self.statusBar().showMessage(
+                f"t={s['time_s']}s  avg drift={s['avg_drift_pct']}% FS/yr  "
+                f"suppression={s['canonical_suppression_at_unity_trims']} (unity trims)")
+            self.canvas.draw_idle()
+
+
+def main():
+    if not QT_AVAILABLE:
+        print("PyQt6/matplotlib not available. Install with: pip install PyQt6 matplotlib")
+        return 1
+    app = QApplication(sys.argv)
+    win = MainWindow()
+    win.show()
+    win.timer.start()
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gea/quartz_hpht_extension.py

@@ -0,0 +1,152 @@
+# 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/.
+"""quartz_hpht_extension - the gauge aging models.
+
+Two aging models evaluated at station pressure and temperature: the conventional
+datasheet model (baseline drift scaled by thermal and pressure factors with the
+template knees and exponents) and the program aging model, which multiplies the
+conventional model by a fixed suppression composition of three engineering
+constants (K_MEX = 25/12, PHI_RES = 0.84, F_TRZ = 0.1; ratio 0.9686). The
+suppression composition is an engineering model with no field validation on
+record; the model card says so, and the drift evaluation uses the band between
+the two models, never the program model alone. `k_structural_trim` and
+`phi_coupling_trim` (default 1.0) are instrument-tuning gains. Industry anchors
+carry inline source comments.
+"""
+
+from __future__ import annotations
+
+# Engineering constants of the program aging model (template lineage, 22 Aug 2026).
+# They are settings, not measurements; the model card labels this model as
+# having no field validation on record.
+_K_MEX = 25.0 / 12.0        # structural factor (engineering constant)
+_PHI_RES = 0.84             # resonance factor (engineering constant)
+_F_TRZ = 0.1                # vacuum-stability factor (engineering constant)
+_U_I = 2.75e-7              # coupling constant (engineering constant)
+PROGRAM_MODEL_AVAILABLE = True
+
+
+def canonical_suppression(k_structural_trim: float = 1.0,
+                          phi_coupling_trim: float = 1.0) -> float:
+    """The GEA drift-suppression composition, canonical primitives locked.
+
+    Template lineage (22Aug2026 thread): suppression = vacuum * structural *
+    resonance. The three dressings' coefficients are the template's engineering
+    fit (DERIVED_HYBRID); the primitive INPUTS are canonical and immutable.
+    Trims are external instrument gains, applied multiplicatively and
+    disclosed as such.
+    """
+    vacuum_stab = 0.58 + 0.32 * (1.0 - _F_TRZ)          # rho_SCm/rho_UA = F_TRZ (canonical)
+    structural = 0.52 + 0.38 * _K_MEX                   # K_MEX = 25/12 (canonical)
+    resonance = 0.68 + 0.27 * _PHI_RES                  # Phi_res = 0.84 (canonical)
+    return vacuum_stab * structural * resonance * float(k_structural_trim) * float(phi_coupling_trim)
+
+
+def calculate_quartz_transducer_hpht_program(depth_m: float,
+                                          temp_c: float,
+                                          pressure_psi: float,
+                                          k_structural_trim: float = 1.0,
+                                          phi_coupling_trim: float = 1.0,
+                                          spec=None) -> dict:
+    """Physics-informed quartz HPHT drift model (GEA-stabilized).
+
+    Returns the template's rich dictionary shape, current-API values.
+    Anchors (inline, per charter): 0.215 %FS/yr typical good-quartz baseline
+    (industry spec class); 150 C thermal knee / 15,000 psi pressure knee with
+    exponents 1.15 / 0.9 (template engineering fit); clip band 0.035-0.48 %FS/yr
+    (physical plausibility bounds, template).
+
+    `spec` (v1.5.0): an optional GaugeSpec (gauge_specs) replacing the
+    template anchors with a cited datasheet's baseline/knees/exponents. The
+    clip band scales proportionally with the baseline so a datasheet bound
+    ~20x below the template baseline is not floored by template-scaled clips.
+    With spec=None every number is bit-identical to v1.0-1.4.
+    """
+    base_drift = 0.215          # anchor: %FS/yr typical good-quartz baseline (industry)
+    knee_C, knee_psi = 150.0, 15000.0   # anchors: industry knees (template; ChampionX confirms >=150 C focus)
+    exp_T, exp_P = 1.15, 0.9            # template engineering fit
+    if spec is not None:
+        base_drift = float(spec.baseline_drift_pct_fs_yr)
+        knee_C = float(spec.thermal_knee_C)
+        knee_psi = float(spec.pressure_knee_psi)
+        exp_T = float(spec.thermal_exponent)
+        exp_P = float(spec.pressure_exponent)
+
+    thermal_stress = max(0.0, (temp_c - knee_C) / 80.0) ** exp_T
+    pressure_stress = max(0.0, (pressure_psi - knee_psi) / 5000.0) ** exp_P
+
+    suppression = canonical_suppression(k_structural_trim, phi_coupling_trim)
+
+    drift = base_drift * (1.0 + 0.55 * thermal_stress + 0.35 * pressure_stress) / suppression
+    clip_scale = base_drift / 0.215     # clip band scales with the baseline (template-exact at 0.215)
+    drift = min(max(drift, 0.035 * clip_scale), 0.48 * clip_scale)
+
+    expected_temp_c = 15.0 + (depth_m / 1000.0) * 29.5   # anchor: ~29.5 C/km geothermal gradient
+    hydrostatic_psi = depth_m * 3.28084 * 0.465          # anchor: 0.465 psi/ft gradient
+
+    return {
+        "value": {
+            "drift_pct": round(drift, 4),
+            "stability_factor": round(base_drift / drift, 3),
+            "suppression": round(suppression, 4),
+            "rho_SCm_over_rho_UA": _F_TRZ,
+            "U_i": _U_I,
+            "K_MEX_canonical": _K_MEX,
+            "Phi_res_canonical": _PHI_RES,
+            "k_structural_trim": float(k_structural_trim),
+            "phi_coupling_trim": float(phi_coupling_trim),
+            "expected_temp_c": round(expected_temp_c, 1),
+            "hydrostatic_psi": round(hydrostatic_psi, 0),
+            "live": PROGRAM_MODEL_AVAILABLE,
+            "gauge_spec": spec.name if spec is not None else "template_generic (default)",
+        },
+        "classification": "DERIVED_HYBRID (PAPER_2149): industry baseline x canonical-GEA suppression",
+        "notes": "gea-program port of the 22Aug2026 QCALCGEOM template; knob ruling applied",
+    }
+
+
+def conventional_drift(temp_c: float, pressure_psi: float, spec=None) -> float:
+    """Conventional-gauge drift: SAME baseline and stress dressing as the GEA
+    leg (from the template anchors or the given GaugeSpec), NO GEA suppression
+    (suppression = 1). The comparison-mode reference leg.
+    """
+    base_drift = 0.215   # anchor: same industry baseline as the program-model leg
+    knee_C, knee_psi, exp_T, exp_P = 150.0, 15000.0, 1.15, 0.9
+    if spec is not None:
+        base_drift = float(spec.baseline_drift_pct_fs_yr)
+        knee_C = float(spec.thermal_knee_C)
+        knee_psi = float(spec.pressure_knee_psi)
+        exp_T = float(spec.thermal_exponent)
+        exp_P = float(spec.pressure_exponent)
+    thermal_stress = max(0.0, (temp_c - knee_C) / 80.0) ** exp_T
+    pressure_stress = max(0.0, (pressure_psi - knee_psi) / 5000.0) ** exp_P
+    drift = base_drift * (1.0 + 0.55 * thermal_stress + 0.35 * pressure_stress)
+    clip_scale = base_drift / 0.215
+    return min(max(drift, 0.035 * clip_scale), 0.48 * clip_scale)
+
+
+def drift_comparison(depth_m: float, temp_c: float, pressure_psi: float,
+                     k_structural_trim: float = 1.0,
+                     phi_coupling_trim: float = 1.0,
+                     spec=None) -> dict:
+    """Twin-gauge comparison at matched T/P: GEA-stabilized vs conventional.
+
+    The module's substantive testable claim (PAPER_2256 sec 5): away from the
+    clip band, the conventional/GEA drift ratio EQUALS the suppression
+    composition — 1.0324 at unity trims. This function is the simulation side
+    of the quartz bench test (PAPER_2250 LABORATORY tier).
+    """
+    uq = calculate_quartz_transducer_hpht_program(
+        depth_m, temp_c, pressure_psi, k_structural_trim, phi_coupling_trim, spec=spec)
+    conv = conventional_drift(temp_c, pressure_psi, spec=spec)
+    uqd = uq["value"]["drift_pct"]
+    sup = uq["value"]["suppression"]
+    return {
+        "drift_pct": uqd,
+        "conventional_drift_pct": round(conv, 4),
+        "measured_ratio": round(conv / uqd, 4) if uqd > 0 else None,
+        "predicted_ratio_suppression": sup,
+        "clip_active": bool(conv >= 0.48 or uqd <= 0.035),
+        "note": "measured_ratio == suppression exactly when neither leg clips",
+    }