This repository contains the supplementary code for the research paper published in the Journal of Hydrology and Hydromechanics. The code implements parametric correlations for analyzing capillary pressure-saturation relationships in centrifuge drainage experiments on porous media.
This study focuses on modeling the first drainage process in centrifuge experiments using four different parametric correlations. The code provides tools for parameter estimation, uncertainty quantification, and correlation comparison for capillary pressure data obtained from centrifuge experiments on sandstone cores.
The repository includes implementations of four parametric correlations for capillary pressure-saturation relationships:
- Brooks & Corey (BC) - Brooks, R. H., & Corey, A. T. (1964)
- Chen Second Model (CHEN2) - Modified version of Chen, Z., Liu, H., & Yao, J. (1992)
- Unimodal van Genuchten (VG) - van Genuchten, M. Th. (1980)
- Bimodal van Genuchten (VG2) - Extended van Genuchten for bimodal pore distributions, as proposed by Durner, W. (1994).
All correlations are optimized with Numba JIT compilation for computational efficiency.
├── centrifuge001/ # Core modeling package
│ ├── correlations.py # Parametric correlations implementation
│ ├── objective_fnc.py # Objective functions for parameter estimation
│ └── propagation.py # Uncertainty propagation functions
├── pictures/ # Folder containing example result images
├── tests/ # Test files for the core modeling package
├── Example_UGB_core.ipynb # Main analysis notebook with Upper Gray Berea core example
├── License # MIT License file
├── pcap.yml # Conda environment file with dependencies
└── README.md # This file
- Parametric Correlation Library: Four well-established capillary pressure correlations with both local and averaged saturation calculations
- Bayesian Parameter Estimation: Uses MCMC sampling (emcee) for robust parameter estimation with uncertainty quantification
- Uncertainty Propagation: Analytical error propagation for experimental measurements
- Centrifuge Data Processing: Specialized functions for processing centrifuge experimental data
- Performance Optimization: Numba JIT compilation for computational efficiency
This code can be installed using either Conda (recommended) or manually.
The code is designed for a Linux Jupyter environment but is fully compatible with macOS. Windows users should use the Windows Subsystem for Linux (WSL) for full compatibility. Running the code natively on Windows will result in a parallelization error because Windows relies on the spawn method rather than fork.
- Clone this repository:
git clone https://github.com/felipeeler/CENTRIFUGE
cd CENTRIFUGE- Create the conda environment:
conda env create -f pcap.yml
conda activate pcap- Register the jupyter kernel for the new environment:
python -m ipykernel install --user --name=pcap --display-name "Python (Pcap)"If you prefer manual installation, the main dependencies are:
- Python 3.14
- emcee (MCMC Sampler)
- h5py (HDF5 File Handling)
- jupyter (Notebook)
- lmfit (Non-linear Optimization)
- matplotlib (Plotting)
- numba (JIT Compilation)
- pandas (Data Manipulation)
- pytest (Code Testing)
- seaborn (Statistical Data Visualization)
- shapely (Fréchet Distance)
- tqdm (Progress Bars)
Run the pytest command:
pytestOpen and run the Jupyter notebook:
jupyter notebook Example_UGB_core.ipynbThe notebook demonstrates the complete workflow:
- Data loading and preprocessing
- Correlation selection and setup
- Parameter estimation using MCMC
- Results visualization and analysis
- Uncertainty quantification
from centrifuge001.correlations import VG_DR
import numpy as np
import matplotlib.pyplot as plt
# Example: Using the van Genuchten correlation for capillary pressure curves
# Generate a synthetic capillary pressure range for demonstration
Pc = np.linspace(0.0, 10.0, 100)
# Define the centrifuge geometry parameter
b = 0.8
# Initialize the van Genuchten correlation with sample parameters
model = VG_DR(alpha=2.5, n=2.0, m=0.5, Pd=0.0, swi=0.1)
# Calculate local water saturation (Sw) using the correlation
sw = model.calc(Pc)
# Calculate average water saturation (Swav) over the sample geometry
swav = model.calc_av(sw, b, Pc)
# Plot local and average saturation curves
fig = plt.figure(figsize=(6, 5))
plt.plot(sw, Pc, label="Local Saturation (Sw)")
plt.plot(swav, Pc, label="Average Saturation (Swav)")
plt.xlabel("Water Saturation (Sw)")
plt.ylabel("Capillary Pressure (Pc, bar)")
plt.title("van Genuchten Correlation Example")
plt.legend()
plt.show()The example notebook uses experimental data from an Upper Gray Berea sandstone core with the following properties:
- Sample diameter: 3.74 cm
- Sample length: 4.94 cm
- Centrifuge RPM range: 0-10,000 RPM
- Volume readings and saturation calculation included
The code implements:
- MCMC Sampling: Ensemble sampling for Bayesian parameter estimation
- Maximum Likelihood Estimation: Traditional optimization approaches
- Error Propagation: Analytical uncertainty quantification
- Model Averaging: Numerical integration for averaged saturation calculations
If you use this code in your research, please cite the corresponding paper:
The paper is currently in early access and citation will be provided upon publication.To access the early view of the paper, please visit the Journal of Hydrology and Hydromechanics website.
See pcap.yml for the complete list of dependencies and versions used in this study.
MIT License
Copyright (c) 2026 Felipe Eler
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
For questions about the code or methodology, please contact the corresponding author of the paper.
This repository represents supplementary material for the Journal of Hydrology and Hydromechanics publication. This research was carried out in association with the ongoing R&D projects registered as ANP nº 23020-1, “Caracterização Experimental, Modelagem e Otimização de Processos de Injeção de Água Alternada Com Gás – WAG-EX Fase II" (UFRJ/Shell Brasil/ANP), sponsored by Shell Brasil Petróleo Ltda under the ANP R&D levy as “Compromisso de Investimentos com Pesquisa e Desenvolvimento”.