fracpta

GeoType catalogues of fractured-reservoir pressure transients.

A GeoType is a recurring fluid-flow behaviour of a fractured reservoir, read off the shape of its pressure-transient response. fracpta builds catalogues of them: it generates or ingests transients, turns them into comparable shapes, clusters them into a catalogue whose prototypes are real member curves, assigns new curves with a coverage guarantee, and attributes each behaviour to the fracture-network properties that control it. The shape machinery underneath (derivative preprocessing, banded DTW, PAM k-medoids, conformal assignment) is pygeotypes; this package keeps the domain.

It is the engine of the Pulso product and lived inside it as an internal package until 0.01.000. A product declares no package of its own, so the engine is published here and the product pins it.

Install

pip install fracpta                 # core: numpy + pygeotypes; analytic ensembles, studies, the live entry
pip install "fracpta[dfn]"          # GeoDFN network generation, fracture descriptors, meshing
pip install "fracpta[learn]"        # the clustering ladder, representations, attribution (scikit-learn, tslearn, ...)
pip install "fracpta[field]"        # welltestpy field campaigns and the 4TU real-data readers
pip install "fracpta[sim]"          # open-DARTS discrete-fracture simulation (heavy, offline)
pip install "fracpta[deep]"         # the learned tier (torch, ONNX export)

Every heavy engine is imported inside the function that needs it: import fracpta stays light, and the analytic generators and the live classifier run anywhere the core installs, Pyodide included.

Quickstart

from fracpta.io.schema import EnsembleSpec
from fracpta.study import run_study

spec = EnsembleSpec(case_id="demo", kind="warren_root", n_curves=120,
                    omega_range=(0.01, 0.5), lam_range=(1e-8, 1e-4), noise_sd=0.01,
                    k_min=2, k_max=6, alpha=0.1)
result = run_study(spec, seed=42)

trace = result["trace"]            # the full-ensemble study artifact (see docs/contracts.md)
trace["k"]                          # catalogue size chosen by the silhouette sweep
result["metrics"]["silhouette_train"], result["metrics"]["coverage"]
result["report"].flagged            # CONTRACT 1 flags on the generated curves

Classify a new curve against that catalogue, the way a browser does it:

from fracpta.live import classify_curve_json, generate_curve_json

curve = generate_curve_json(omega=0.05, lam=1e-6, noise_sd=0.02, seed=9)
verdict = classify_curve_json(trace, curve["t"], curve["p"], alpha=0.1)
verdict["point_prediction"], verdict["prediction_set"], verdict["out_of_catalogue"]

Bring your own transients (time and pressure arrays plus optional physical descriptors per curve):

from fracpta.stages.feature_extraction import arrays_from_curves
from fracpta.study import study_trace, train_infer_evaluate

arrays = arrays_from_curves("mine", t_list, p_list, features, feature_names,
                            n_points=spec.n_points, derivative_order=1, L=spec.L, norm=spec.norm)
result = train_infer_evaluate(arrays, spec, seed=42)
trace, schema = study_trace("mine", arrays, spec, result, seed=42)

A run is a pure function of (spec, seed): the same inputs produce an identical trace, byte for byte.

What is in the package

The theory behind each method, equation by equation and with its sources, is in docs/.

Data the readers expect

Two datasets are not shipped (size and licence) and are read from a vault directory named by FRACPTA_VAULT (the former name FLOWDNA_VAULT is still accepted): real-curves/ holds the 4TU fractured-reservoir corpus, field/ the welltestpy campaigns (Zenodo 4139374). available() on each reader says whether the data is reachable, so a caller can skip those studies instead of failing.

Determinism and provenance

Every random draw goes through one seeded generator (fracpta.core.rng.make_rng); no stage reads a clock into an artifact. A trace records the catalogue, the conformal calibration, the attribution, the full committed ensemble and the diagnostics of the run; the consuming product adds its own manifest with the package version it used.

Versioning

VERSION is the source of truth (X.XX.XXX); pyproject.toml carries the PEP 440 form; every release is tagged vX.XX.XXX and published to PyPI by publish-pypi.yml through trusted publishing. History in CHANGELOG.md.

Licence

MIT. Third-party engines keep their own licences: GeoDFN (MIT), open-DARTS (Apache-2.0), tslearn (BSD-2), hdbscan (BSD-3), umap-learn (BSD-3), pycatch22 (GPL-3, optional, imported only when installed).