Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ authors:
email: "imranfadhil@gmail.com"
repository-code: "https://github.com/imranfadhil/quick_pp"
url: "https://quick-pp.readthedocs.io"
version: 0.3.3
date-released: "2026-10-31"
version: 0.3.4
date-released: "2026-11-03"
license: MIT
keywords:
- petrophysics
Expand Down Expand Up @@ -44,4 +44,4 @@ preferred-citation:
orcid: "https://orcid.org/0000-0001-9392-8083"
year: 2026
url: "https://github.com/imranfadhil/quick_pp"
version: 0.3.3
version: 0.3.4
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,6 @@ If you use `quick_pp` in your academic research, coursework, publications, or te
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/imranfadhil/quick_pp}},
version = {0.3.3}
version = {0.3.4}
}
```
10 changes: 10 additions & 0 deletions docs/community/changelog.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## 0.3.4 (2026-11-03)
- Added **Multi-Well Probabilistic Volumetric Assessment & Subsurface Risk Analysis** (`quick_pp/app/backend/services/workspace.py`, `MultiWellVolumetrics.svelte`, `VolumetricsCanvas.svelte`, `WorkflowStepper.svelte`) implementing Monte Carlo Latin Hypercube Sampling (LHS, $N \ge 10{,}000$) for STOIIP and GIIP across project wells and reservoir zones, supporting dual $S_w$-based and SHF-based (saturation-height function) modes, flexible parametric distributions (Normal, Log-Normal, Triangular, Uniform) for Area, Gross Thickness, NTG, $\phi_e$, $S_w$, $B_o/B_g$, and Recovery Factor, interactive parameter bounding, cumulative exceedance (CDF), probability density (PDF), and Tornado sensitivity ranking charts for P90 (1P/Proven), P50 (2P/Probable), P10 (3P/Possible), Mean, and Standard Deviation, and automated injection into Section 8 of FDP and Reservoir Summary reports.
- Added **Petrophysical Handover Package Import & Bi-Directional Exchange** (`quick_pp/handover.py`, `quick_pp/app/backend/services/database.py`, `HandoverImporter.svelte`, `BulkImporterModal.svelte`, `TopContextBar.svelte`, `tests/test_handover.py`) enabling end-to-end ingestion and project re-hydration from structured handover `.zip` archives (Techlog, Geolog, quick_pp), including pre-import archive inspection (`inspect_handover_archive`), manifest validation, well inventory reconciliation, and comprehensive database reconstruction of well headers, deviation surveys, continuous log curves (LAS 2.0/3.0), formation tops, fluid contacts, perforation intervals, core RCA sample point-sets (`RAW_DEPTH`, `SHIFT_M`, `CPORE`, `CPERM`), MDT/FPT formation pressure tests, and SCAL capillary pressure / relative permeability tables.
- Added **Field-Wide Fluid Contact Delineation & Contact Optimization** (`quick_pp/saturation.py`, `quick_pp/database/objects.py`, `quick_pp/app/backend/services/workspace.py`, `MultiWellShf.svelte`, `tests/test_fluid_contacts_and_limits.py`) with `extract_fluid_contacts_and_limits` to automatically identify and classify petrophysical fluid limits and contacts across project wells and zones: Gas limits (GUT, GDT, GOC, GWC), Oil limits (OUT, ODT, OWC), and Water limits (WUT, FWL) with explicit exclusion of non-physical WDT, robust Water-Up-To (WUT) assignment using net reservoir sand cutoffs (`phit_cutoff`, `vsh_cutoff`, `min_sand_thickness`), per-zone Free Water Level (`FWL`) and fluid contact persistence in `WellFluidContact` tables with automatic TVDSS-to-MD interpolation, and integrated contact table generation in Section 6 of the FDP report pipeline.
- Added **Multi-Well Parameters & Fits Management Workbench** (`quick_pp/app/backend/services/ancillary.py`, `quick_pp/app/backend/services/workspace.py`, `ParametersManagementPanel.svelte`, `SavedParamsIndicator.svelte`, `moduleParams.svelte.ts`, `projectParams.svelte.ts`, `tests/test_params_and_contacts_reset.py`) providing a unified interactive manager to inspect, modify, zone-override, and reset model parameters and regression fits across Lithology/Porosity, Rock Typing, SHF, Permeability transforms, and Swirr, complete with real-time dirty state tracking and zone-level parameter isolation.
- Added **Petrophysical Single-Source-of-Truth (SSOT) Reference & AI Assistant Grounding** (`docs/workflows/index.md`, `single_well.md`, `multi_well.md`, `quick_pp/app/backend/services/ssot_reference.py`, `quick_pp/app/backend/services/chat.py`, `WorkflowGuideSheet.svelte`) establishing authoritative petrophysical equations, curve contracts, parameter bounds, and diagnostic guidelines across sequential steps (1–7) and standalone modules, backed by `SSOTReferenceRegistry` and MCP server tool `get_workflow_technical_reference` for context-grounded AI assistant responses, paired with the interactive in-app `WorkflowGuideSheet` reference panel.
- Enhanced **Lithology Inversion & Multi-Mineral Optimization** (`quick_pp/lithology.py`, `quick_pp/plotter/report_plots.py`, `LogTrackCanvas.svelte`, `CrossplotCanvas.svelte`) to cater to essential secondary and accessory minerals (Siderite, Pyrite, Anhydrite, Coal) alongside quartz, clay, calcite, and dolomite, refined silt line angle geometric constraints in Sand-Silt-Clay (SSC) inversion models, refactored Thomas-Stieber thin-bed analysis, enforced non-reservoir rock flag filtering in rock typing and permeability modules, and added Spectral Gamma Ray (SGR) track components (K, U, Th).
- Refined **SCAL Water Saturation Normalization, Swirr & Permeability Transforms** (`quick_pp/saturation.py`, `quick_pp/scal.py`, `MultiWellSwirr.svelte`, `InspectorPerm.svelte`) correcting $S_w$ normalization bounds in SCAL relative permeability models, improving multi-well irreducible water saturation (`SWIRR`) fitting and continuous curve propagation across zones, and enforcing rigorous outlier filtering on core data points.
- Enhanced **Automated FDP & Single-Well Report Generation** (`quick_pp/plotter/report_plots.py`, `quick_pp/app/backend/services/report.py`, `InspectorReport.svelte`) with upgraded headless high-DPI Matplotlib figure rendering, composite CPI well logs with strictly monotonic depth indexing, auto-zoomed target reservoir depth windows, core calibration overlays (`CPORE`, `CPERM`), and zonal contact boundary lines.

## 0.3.3 (2026)
- Added **Formation Pressure Testing (FPT) Fluid Gradient & Contact Analysis** (`quick_pp/fluid_type.py`, `quick_pp/app/backend/services/fpt.py`, `MultiWellFpt.svelte`, `tests/test_fluid_type_fpt.py`) supporting multi-well pressure-depth regression (OLS, Huber, RANSAC), automatic mobility (`TIGHT`) and supercharge residual quality flagging, unsupervised fluid phase clustering, in-situ fluid density conversion (`gradient_to_density`, `density_to_gradient`), Monte Carlo P10/P50/P90 fluid contact intersections (`GOC`, `OWC`/`FWL`, `GWC`), excess pressure profiling, per-zone analysis, and one-click TVDSS-to-MD contact writing into well fluid contact tables.
- Added **Multi-Well Irreducible Water Saturation (`Swirr`) Module** (`quick_pp/saturation.py`, `MultiWellSwirr.svelte`, `InspectorPerm.svelte`) with multi-well `Swirr` correlation fitting (`fit_swirr_correlation`) and continuous curve prediction using **RQI (`swirr_rqi`)**, **Semi-log Permeability (`swirr_semilog_k`)**, and **Timur (`swirr_timur`)** models, plus direct `SWIRR` integration in Single-Well Timur, Coates, and Tixier permeability calculations.
Expand Down
2 changes: 1 addition & 1 deletion docs/workflows/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ The tables below define the 1-to-1 correspondence between the SvelteKit workbenc
| **Step 2** | `qaqc` | `MultiWellQaqc.svelte` | [`#mw-step-2-qaqc`](multi_well.md#mw-step-2-qaqc) | Key-well designation & stratigraphic quantile normalization |
| **Step 3** | `rock-typing` | `MultiWellRockTyping.svelte` | [`#mw-step-3-rock-typing`](multi_well.md#mw-step-3-rock-typing) | Core Hydraulic Flow Units (FZI), Winland $r_{35}$ & Lucia RFN |
| **Step 4** | `perm-transform` | `MultiWellPermTransform.svelte` | [`#mw-step-4-perm-transform`](multi_well.md#mw-step-4-perm-transform) | Rock-type partitioned poro-perm regression ($k = a \cdot e^{b\phi}$) |
| **Step 5** | `shf` | `MultiWellShf.svelte` | [`#mw-step-5-shf`](multi_well.md#mw-step-5-shf) | Saturation-Height Modeling (Leverett $J$ / Skelt-Harrison) & log reconciliation |
| **Step 5** | `shf` | `MultiWellShf.svelte` | [`#mw-step-5-shf`](multi_well.md#mw-step-5-shf) | Saturation-Height Modeling (Leverett $J$ / Skelt-Harrison), fluid contacts & log reconciliation |
| **Step 6** | `volumetrics` | `MultiWellVolumetrics.svelte` | [`#mw-step-6-volumetrics`](multi_well.md#mw-step-6-volumetrics) | Probabilistic Monte Carlo LHS STOIIP/GIIP (P90/P50/P10) & Tornado |
| **Step 7** | `report` | `InspectorReport.svelte` | [`#mw-step-7-report`](multi_well.md#mw-step-7-report) | Field Development Plan (FDP) comprehensive report generation |
| **Standalone** | `swirr-corr` | `MultiWellSwirr.svelte` | [`#mw-standalone-scal-relperm`](multi_well.md#mw-standalone-scal-relperm) | **SCAL & Rel-Perm**: Field Swirr fit, Brooks-Corey, LET & SWOF decks |
Expand Down
7 changes: 7 additions & 0 deletions docs/workflows/multi_well.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,13 @@ flowchart TD

$$\min_{z_{\text{FWL}}, \mathbf{\theta}_{\text{SHF}}} \sum_{w=1}^{N_w} \sum_{i=1}^{M_w} \left( S_{w,\text{SHF}}(z_{w,i}; z_{\text{FWL}}, \mathbf{\theta}) - S_{w,\text{log},i} \right)^2$$

* **Fluid Contact & Transition Limits Delineation (`extract_fluid_contacts_and_limits`):**
Automatically establishes petrophysical fluid boundaries across all wells and zones:
* **Gas Limits & Contacts:** GUT (Gas Up To), GDT (Gas Down To), GOC (Gas-Oil Contact), GWC (Gas-Water Contact)
* **Oil Limits & Contacts:** OUT (Oil Up To), ODT (Oil Down To), OWC (Oil-Water Contact)
* **Water Limits & Contacts:** WUT (Water Up To), FWL (Free Water Level) — *Note: WDT (Water Down To) is explicitly excluded as it carries no petrophysical utility.*
* **Net Sand & Pay Conditioning:** Declared contacts require contiguous reservoir sand samples ($V_{\text{sh}} \le V_{\text{sh,cutoff}}$, $\phi_e \ge \phi_{\text{cutoff}}$, $h_{\text{sand}} \ge 1.0\,\text{m}$) and saturation discrimination ($S_w \le S_{w,\text{pay}}$ for hydrocarbon, $S_w \ge S_{w,\text{water}}$ for water).

* **Input Data:** `TVDSS`, `PERM_FIELD`, `PHIE`, $z_{\text{FWL}}$, In-situ fluid densities ($\rho_w, \rho_{\text{hc}}$).
* **Output Data:** `SW_SHF`, Reconciliation crossplots, Residual error statistics ($\text{RMSE}, R^2$).

Expand Down
10 changes: 8 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "quick-pp"
version = "0.3.3"
version = "0.3.4"
description = "Comprehensive Python package and web platform for deterministic and probabilistic petrophysical evaluation, SCAL & relative permeability modeling, multi-well FWL optimization, stratigraphic normalization, and geomodel log upscaling."
readme = { file = "README.md", content-type = "text/markdown" }
license = "MIT"
Expand Down Expand Up @@ -187,7 +187,13 @@ quick_pp = [
"app/frontend/.svelte-kit",
"app/frontend/.svelte-kit/**/*",
"app/backend/static/reports",
"app/backend/static/reports/**/*"
"app/backend/static/reports/**/*",
"**/*.db",
"**/*.db*",
"**/*.sqlite",
"**/*.sqlite3",
"**/.env",
"**/.env.*"
]

# Development tools configuration
Expand Down
8 changes: 7 additions & 1 deletion quick_pp/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@

__author__ = """Imran Fadhil"""
__email__ = "imranfadhil@gmail.com"
__version__ = "0.3.3" # Need to be updated manually when releasing a new version/ change in pyproject.toml
__version__ = "0.3.4" # Need to be updated manually when releasing a new version/ change in pyproject.toml

# Expose core petrophysical submodules and key public functions at top-level package namespace
from quick_pp import ( # noqa: E402
Expand All @@ -71,6 +71,8 @@
from quick_pp.handover import ( # noqa: E402
build_handover_archive_bytes,
collect_well_handover_dict,
import_handover_archive,
inspect_handover_archive,
)
from quick_pp.qaqc import ( # noqa: E402
apply_environmental_corrections,
Expand All @@ -87,6 +89,7 @@
ContactOptimizer,
analyze_transition_zone,
estimate_mdt_fwl,
extract_fluid_contacts_and_limits,
fit_swirr_correlation,
optimize_fwl,
plot_fwl_reconciliation,
Expand Down Expand Up @@ -182,6 +185,7 @@
"enforce_physical_constraints",
"estimate_cbw_from_qv",
"estimate_mdt_fwl",
"extract_fluid_contacts_and_limits",
"expand_blocked_logs",
"fit_relperm",
"fit_swirr_correlation",
Expand All @@ -192,6 +196,8 @@
"handover",
"harm_upscale",
"humidity_to_total_porosity",
"import_handover_archive",
"inspect_handover_archive",
"klinkenberg_permeability_correction",
"let_relperm",
"logger",
Expand Down
8 changes: 8 additions & 0 deletions quick_pp/app/backend/mcp_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -1673,7 +1673,15 @@ def tool_get_workflow_technical_reference(
"primary_match": matches[0],
"reference_content": matches[0]["content"],
"source": f"docs/workflows/{'multi_well.md' if 'multi' in matches[0]['scope'] else 'single_well.md'}",
"found": True,
}
return {
"tool": "get_workflow_technical_reference",
"query": query,
"matches_count": 0,
"reference_content": f"No workflow technical reference found matching query '{query}'.",
"found": False,
}

if step:
content = get_step_reference(effective_scope, step)
Expand Down
93 changes: 91 additions & 2 deletions quick_pp/app/backend/services/ancillary.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
import numpy as np
import pandas as pd
from fastapi import APIRouter, Body, File, Form, HTTPException, Query, UploadFile
from sqlalchemy import select
from sqlalchemy import or_, select

from quick_pp.app.backend.schemas.well_metadata import (
AncillaryColumnMapping,
Expand Down Expand Up @@ -188,6 +188,10 @@
"depth_m",
"depth_ft",
],
"ZONE": ["zone", "formation", "reservoir", "unit", "compartment"],
"FAULT_BLOCK": ["fault_block", "faultblock", "block", "compartment_block"],
"SOURCE": ["source", "method", "determination_method", "lineage", "basis"],
"REMARKS": ["remarks", "remark", "comment", "comments", "description"],
},
"perforations": {
"WELL_NAME": ["well", "well_name", "wellname", "uwi", "wellbore", "well_id"],
Expand Down Expand Up @@ -1330,6 +1334,79 @@ def delete_fluid_contact_project(
) from e


@router.delete(
"/fluid_contacts",
summary="Delete fluid contacts across project or for a well (optionally auto-generated only)",
tags=["Fluid Contacts"],
)
@router.delete(
"/wells/{well_name}/fluid_contacts",
include_in_schema=False,
)
def delete_fluid_contacts_project(
project_id: int,
well_name: Optional[str] = None,
auto_only: bool = True,
zone: Optional[str] = None,
):
"""Delete fluid contacts. If `auto_only=True` (default), only auto-generated/optimized contacts are deleted."""
try:
deleted_count = 0
wells_affected = set()
with get_db() as session:
proj = db_objects.Project.load(session, project_id=project_id)
if well_name:
wells = [proj.get_well(well_name)]
else:
wells = [proj.get_well(wn) for wn in proj.get_well_names()]

for well in wells:
query = session.query(db_objects.ORMFluidContact).filter_by(well_id=well.well_id)
if zone:
query = query.filter(db_objects.ORMFluidContact.zone == str(zone).strip())

if auto_only:
auto_conditions = [
db_objects.ORMFluidContact.source.ilike("%Log Evaluation%"),
db_objects.ORMFluidContact.source.ilike("%Calculated%"),
db_objects.ORMFluidContact.source.ilike("%Optimizer%"),
db_objects.ORMFluidContact.source.ilike("%FPT%"),
db_objects.ORMFluidContact.source.ilike("%Auto%"),
db_objects.ORMFluidContact.name.in_(["GUT", "GDT", "OUT", "ODT", "WUT"]),
db_objects.ORMFluidContact.remarks.ilike("%Proved Gas%"),
db_objects.ORMFluidContact.remarks.ilike("%Proved Oil%"),
db_objects.ORMFluidContact.remarks.ilike("%Proved Water%"),
db_objects.ORMFluidContact.remarks.ilike("%bracketed%"),
db_objects.ORMFluidContact.remarks.ilike("%Optimized Free Water Level%"),
db_objects.ORMFluidContact.remarks.ilike("%Formation Pressure Test%"),
]
query = query.filter(or_(*auto_conditions))

count = query.delete(synchronize_session="fetch")
if count > 0:
deleted_count += count
wells_affected.add(well.name)
try:
session.expire(well._orm_well, ["fluid_contacts"])
except Exception:
pass

session.flush()

for w_name in wells_affected:
invalidate_well_cache(project_id=project_id, well_name=str(w_name))

return {
"deleted_count": deleted_count,
"wells_affected": list(wells_affected),
"auto_only": auto_only,
}
except Exception as e:
raise HTTPException(
status_code=500, detail=f"Failed to delete fluid contacts: {e}"
) from e


@router.get(
"/pressure_tests",
summary="List pressure tests for a project (optional well_name)",
Expand Down Expand Up @@ -2564,12 +2641,24 @@ def _opt_str(row: Dict[str, Any], col: Optional[str]) -> Optional[str]:
elif dtype == "contacts":
c_col, _ = col_map.get("CONTACT_TYPE", ("contact_type", None))
d_col, d_unit = col_map.get("DEPTH", ("depth", None))
z_col, _ = col_map.get("ZONE", ("zone", None))
fb_col, _ = col_map.get("FAULT_BLOCK", ("fault_block", None))
src_col, _ = col_map.get("SOURCE", ("source", None))
rem_col, _ = col_map.get("REMARKS", ("remarks", None))
contacts_payload = []
for r in w_rows:
c_type = str(r.get(c_col, "")).strip().upper()
d_v = _convert_ancillary_numeric(r.get(d_col), d_unit, "DEPTH")
if c_type and d_v is not None:
contacts_payload.append({"name": c_type, "depth": d_v})
contacts_payload.append({
"name": str(r.get("name") or c_type).strip(),
"contact_type": c_type,
"depth": d_v,
"zone": str(r.get(z_col, "")).strip() or None if z_col in r else None,
"fault_block": str(r.get(fb_col, "")).strip() or None if fb_col in r else None,
"source": str(r.get(src_col, "")).strip() or None if src_col in r else None,
"remarks": str(r.get(rem_col, "")).strip() or None if rem_col in r else None,
})
if contacts_payload:
well.add_fluid_contacts(contacts_payload, replace=True)
summary_by_well[wn] = len(contacts_payload)
Expand Down
Loading
Loading