Skip to main content

declinecast

declinecast forecasts how much oil a young horizontal well will have produced by month 36 (or 60) from its first 6 to 24 months of production, and gives each forecast a range that holds up: on wells it never saw, its 80% range (P90 to P10) contains the outcome close to 80% of the time. It does this with amortized Bayesian inference: a neural network trained on 500,000 simulated wells returns, for any well in a fraction of a second, a posterior over the parameters of the industry's own decline model (modified hyperbolic Arps), with the noise and downtime of real monthly records inferred per well. The posterior's calibration is checked on simulated wells, where the truth is known (simulation-based calibration and coverage), and the forecasts are scored on real Colorado wells against what analysts already use. The data layer (the panel build from 9.4 million raw regulator rows, the quality checks and the Tableau tables) is DuckDB SQL, tested against an independent pandas version.

The package ships a derived extract of 8,344 DJ Basin horizontal Niobrara and Codell wells from the Colorado Energy & Carbon Management Commission (ECMC) and a pretrained model.

The business question: an acquisitions team, a royalty buyer or a reserve-based lender looks at a well that has produced for a year. How much oil will it have produced in three years, what are the low and high cases, and can those cases be trusted?

Results on the locked test (1,463 wells first produced 2020-2022)

The test wells were set aside on 7 November 2026, before any scoring, and scored once. Forecasts are of cumulative oil from first production to month 36. Ranges in brackets are 95% bootstrap intervals that resample whole operators (20 to 22 operators), because wells of one operator are not independent.

Question Answer
Do the ranges hold up? Yes. The 80% range contains the actual 36-month oil for 88% of wells seen for 6 months, 81% at 12 months, 77% at 18 and 78% at 24; the 90% range for 96%, 92%, 88% and 89%. The 18- and 24-month figures are 2 to 3 points under nominal, and their intervals ([74%, 82%] and [74%, 83%]) contain 80%.
Better than least-squares Arps, the analyst's default? Yes, mainly on the ranges. A per-well least-squares fit's 80% range contains the outcome for only 48% to 57% of wells. The network's weighted interval score (WIS, a proper score for ranges; lower is better) is lower at every history, and its median is more accurate at 6 months (−0.020 [−0.027, −0.007] dex) and ties from 12 months on.
Better than the simplest empirical method? Only with two years of history. Multiplying a well's oil to date by how similar wells went is a strong benchmark. The two tie on WIS at 6, 12 and 18 months; the network is better at 24 months (−0.0015 [−0.0033, −0.0000]). The multiplier's median is more accurate at 12 months (6.0% against 6.8% median error), and its ranges are better calibrated at 18 to 24 months.
Is it faster than per-well MCMC, without losing accuracy? Yes, modestly. Per-well MCMC on the same model and the same wells (the published Bayesian approach) ties the network at 12 and 18 months and is 0.2% more accurate at 24, while the network's ranges are better calibrated there (78% against 75%). The network needs 0.16 s per forecast against 0.40 s for MCMC vectorized over wells and 1.41 s one well at a time, so its 1.85-hour training pays back after about 5,300 to 28,200 forecasts. See FINDINGS section 12.
How accurate is the middle forecast? The median error is 13% at 6 months, 6.8% at 12, 3.2% at 18 and 1.4% at 24 (part of the 36 months is already produced, so the error shrinks fast).
Is the forecast biased? It was, at short histories: +22% at 6 months on test wells before a correction fit on development wells, and +6% after it. From 12 months on it is under 2% either way. The correction is applied by default and both versions are reported.
Which wells should not be trusted? Wells flagged as unlike the training wells (lateral, rates, or a posterior pushing on its limits): 174 of 1,463. At 12 months their 80% range covers 68%, against 83% for the rest.
Is the uncertainty right on simulated wells? Mostly. 173 of 180 coverage checks match their nominal level. Five of six parameters pass simulation-based calibration; the noise memory fails, and so do the derived cumulatives, which the network overestimates by about 2% (5% at 6 months). The 17 October pre-registration said they would pass; that claim is reported as falsified.
Does the regulator's revision of filings matter? Not in this cohort. Given the record as first filed instead of as finally revised, the network's WIS changes by at most 0.0001 and its 80% coverage by at most 0.8 points; first-filed oil differs from the final figure in 0.5% of test well-months.

The full write-up is in docs/BUSINESS_CASE.md, the measurements, negative results and verification log in docs/FINDINGS.md, and the model card in docs/MODEL_CARD.md.

Coverage of the 36-month forecast ranges on the locked test wells

What it is not

Not a reserves estimate (no economics, price deck, or SEC or PRMS process), not validated outside the DJ Basin or for gas or water, and it does not model refracs or interference from offset wells. The input is a monthly oil series, producing days and a lateral length, so a loader for another basin is new data, not a new method, but it has not been done here.

Install

pip install torch --index-url https://download.pytorch.org/whl/cpu   # CPU PyTorch first
pip install declinecast            # library and command line
pip install "declinecast[plot]"    # adds the figures

Python 3.10 to 3.13. The dependencies are PyTorch, sbi, zuko, NumPy, SciPy, pandas and DuckDB; no GPU, database server or internet access is needed at run time. Installing CPU PyTorch first avoids pip pulling the CUDA build, which the package never uses.

Workflow

declinecast datasets                                   # the bundled extract and its source
declinecast quality                                    # its data-quality table (DuckDB SQL)
declinecast predict --api 050010984800 --history 12 --out one_well.csv   # one bundled well
declinecast predict --csv my_wells.csv --out forecasts.csv               # your own wells
declinecast validate --out results/validation          # calibration on simulated wells (~10 min)
declinecast score --split development --out results/dev --max-wells 2000 # real wells (~25 min)
declinecast tableau --score results/dev --validation results/validation --out results/tableau

predict --csv reads one row per well and month: well_id, month (YYYY-MM), oil_bbl, days (producing days) and lateral_ft. Its output has the quantiles of cumulative oil to each horizon (q0.1 is P90, the low case; q0.5 is P50; q0.9 is P10), the oil produced to date, and the share of posterior draws inside the prior's support (below 0.8, the well is unlike the training wells).

--api takes the 12-digit API numbers of bundled wells. List them with declinecast sql --query "SELECT api, first_operator, vintage FROM wells LIMIT 5".

The locked test is scored with declinecast score --split test --unlock-test; without --unlock-test the command refuses. --as-reported gives every method the production as first filed, with the outcome kept final.

Rebuilding the extract from the raw files (opt-in; fetch requests the 14 published files one at a time and never crawls):

declinecast fetch --dest data/raw
declinecast panel --raw data/raw --out data/panel      # about 45 s, DuckDB SQL
declinecast quality --raw data/raw                     # the full raw-file report
declinecast train --out results/model                  # about 2 h on two CPU cores

For questions of your own, declinecast sql runs a read-only DuckDB query over the tables wells and months; files and the network are out of reach.

Python:

import declinecast as dc

panel = dc.load_panel()                                 # checksum verified
model = dc.load_model()                                 # the bundled model, checksums verified
wells = panel.wells[panel.wells.vintage == 2021].head(5)
arrays = dc.well_arrays(panel, wells=wells)
table = dc.predict_table(model, arrays, panel, history=12, horizons=(36,))
table[["well_id", "q0.1", "q0.5", "q0.9"]]              # P90, P50, P10 barrels to month 36

scripts/reproduce.sh reruns every result in the docs, in order.

How it works

Step What happens Why
Panel DuckDB SQL builds one row per well and month from 13 yearly files, keeping one version of each re-exported record and summing commingled formations the 2025 file re-exports 240,000 earlier records; summing every row double-counts them
Cohort horizontal Niobrara and Codell wells first producing 2014 or later, at least 12 producing months, lateral at least 3,000 ft: 8,344 wells the files start in 2013, so earlier first months are unknown
Split development wells first produced 2014-2019, locked test wells 2020 and later a forecast is used on wells newer than the ones it was built on
Simulator ramp to a peak in months 0 to 5, modified Arps decline with a 5% per year terminal decline, AR(1) log-rate noise with heavy tails, and downtime each piece is measured on development wells (FINDINGS section 2)
Prior initial rate given the lateral (it explains 22.5% of peak-rate variance), the rest uniform over ranges wider than the development fits the lateral is known before a well produces
Network the embedding network and neural spline flow of Steinle et al. (arXiv:2607.12971), written from the paper's text, trained on 500,000 simulated wells one training run serves every well afterwards
Validation SBC with a Bonferroni KS test, coverage at fixed histories, a known-answer test, a prior predictive check the posterior must be right where the truth is known before it is trusted where it is not
Forecast observed oil to date plus the posterior predictive future, with the noise carried forward and future uptime drawn from development wells the same bookkeeping for every method, so the comparison is between decline models
Recalibration the predicted oil scaled per history so its median error on development wells is zero the network ran +14% high at 6 months on development wells
Scoring WIS, coverage and median error on log barrels, with bootstrap intervals over operators and over pads wells of one operator or pad are not independent
MCMC baseline the same model fit well by well with an ensemble MCMC sampler (declinecast.mcmc, scripts/mcmc_baseline.py), scored on the same test wells separates the cost of the inference from the quality of the model

Safety and reproducibility

No pickles: the model is a state_dict read with torch.load(weights_only=True), rebuilt from the settings in its manifest, with every file's SHA-256 checked and unknown files refused. The bundled extract's checksum is checked on every load. SQL runs in an in-memory DuckDB with external access off. Results are seeded, and every output folder refuses to be overwritten without --overwrite. See SECURITY.md.

Data and citation

Production and well data courtesy of the Colorado Energy & Carbon Management Commission. The bundled extract is derived, and is not an official ECMC product (DATA_LICENSE.md). The method is from N. Steinle et al., "A new model for the continuum spectra of AM CVn binaries and multi-messenger inference with normalizing flows", arXiv:2607.12971; cite the package with CITATION.cff.

MIT License.

Metadata

Release files for declinecast 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for declinecast 0.1.0
File Size Uploaded Provenance Actions
declinecast-0.1.0.tar.gz 13.8 MB With provenance Details for declinecast-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for declinecast 0.1.0
File Interpreter ABI Platform Actions
declinecast-0.1.0-py3-none-any.whl Python 3 none any Details for declinecast-0.1.0-py3-none-any.whl

Total release size: 27.0 MB

Release files / declinecast-0.1.0.tar.gz

Download URL declinecast-0.1.0.tar.gz
Size 13.8 MB
Tags Source
SHA-256 checksum
How to use checksums
3feaee8a76ed771ad0278c8cc488c4d8edafaf3cdee2a6db706525834cc9499e
BLAKE2b-256 checksum
How to use checksums
cd7bbca862c6df7e4dd28fe1b97278a788e5ea0f4933abaa017707e783dbc761
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / declinecast-0.1.0-py3-none-any.whl

Download URL declinecast-0.1.0-py3-none-any.whl
Size 13.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
ee58bd35d894ae3446cd0c8e75a3bbe84395ddb80fa814db00004fedaf3533dd
BLAKE2b-256 checksum
How to use checksums
5c5b4780dfa8886b0d4cd78165815fedcd495874f8f994e33131fec2fbbb387f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for declinecast 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for declinecast-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page