Development

.gitignore

@@ -139,4 +139,12 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
+# VS Code settings
 .vscode/
+
+# Well log data (low resource policy)
+*.las
+*.csv
+*.txt
+*.dat
+*.dlis

CHANGELOG.txt

@@ -1,6 +1,6 @@
 Change Log
 ==========
 
-0.1.0 (29/01/2022)
+0.2.0 (25/02/2026)
 ------------------
-- First Release
+- Major Update 

README.md

@@ -43,6 +43,8 @@ and them verify the installation using the following command in Python:
 ```
 >>> import stoneforge
 ```
+
+
 
 ## Dataset
 

docs/DOCS.md

@@ -1,6 +1,7 @@
 # How to use docs
 
 Verify if you have installed the dev dependencies. The script 'make.bat' (windows) or 'Makefile' (linux) have automatons to build the documentation.
+Verify also if you are in this directory before the commands execution.
 
 **Windows**
 ```

docs/index.rst

@@ -23,7 +23,8 @@ and develop routines in Python to solve geological and geophysical problems. Mai
    usage/installation
    usage/quickstart
 
-   modules/petrophysics
+   modules/petrophysics/index
+   modules/reservoir/index
    modules/rockphysics
    modules/pseudowells
    modules/machinelearning/index

docs/modules/petrophysics/index.rst

@@ -0,0 +1,60 @@
+=========================
+Petrophysics
+=========================
+
+**About:** This section contains documentation for the Petrophysics module. We indicate the reference (Pt-Br) of :footcite:t:`freire2020youtube` for the methods used in this module.
+
+This module implements a comprehensive suite of petrophysical models for porosity, shale volume, water saturation, and permeability, following well-established formulations from the geoscience and reservoir engineering literature (e.g., Archie, Simandoux, Indonesia, Larionov, Clavier, Timur, Coates, Tixier).
+
+Beyond numerical implementation, the library adopts a multi-layered scientific validation strategy designed to ensure correctness, numerical robustness, and physical consistency across scalar and log-scale data. The testing framework is structured into four complementary levels:
+
+1. Analytical (Equation-Based) Validation
+
+Each petrophysical model is validated against its analytical formulation using deterministic unit tests. For fixed, physically meaningful inputs, the numerical output is compared directly to the closed-form equation, ensuring exact correspondence with the theoretical model. This guarantees that the implementation faithfully reproduces the published equations and assumptions.
+
+2. Vectorization and Numerical Behavior
+
+Because petrophysical data are inherently log-based and vectorized, all models are tested using NumPy arrays to verify correct broadcasting, array-wise computation, and performance on realistic datasets. These tests explicitly check:
+
+- Vectorized execution (arrays in → arrays out)
+
+- Correct propagation of NaN values
+
+- Numerical stability across valid physical ranges
+
+- Enforcement of physical bounds (e.g., 0 ≤ 𝜙, 𝑉𝑠ℎ, 𝑆𝑤 ≤ 1; 𝑘 ≥ 0)
+
+This level ensures the models behave reliably when applied to full well logs rather than isolated scalar values.
+
+3. Physical Invariants and Limiting Behavior (Property-Based Testing)
+
+Advanced property-based testing is employed to validate physical laws and monotonic trends, independent of any specific numerical example. Using randomized but physically constrained inputs, the models are verified against invariant properties such as:
+
+- Increasing resistivity leads to decreasing water saturation
+
+- Increasing porosity leads to increasing permeability
+
+- Increasing shale volume increases shale-corrected water saturation
+
+- Limiting cases (e.g., 𝑉𝑠ℎ→0, 𝑅𝑡→∞, 𝑆𝑤→1) converge to physically meaningful results
+
+This approach provides strong guarantees that the models remain physically consistent even outside hand-picked test cases and is particularly effective at identifying subtle numerical or logical errors.
+
+4. Cross-Model Consistency
+
+Where applicable, cross-model relationships are validated (e.g., shaly-sand models converging to Archie behavior in clean formations). This ensures internal coherence across the petrophysical workflow and reinforces interpretational reliability.
+
+.
+
+.. toctree::
+   :maxdepth: 1
+
+   shale_volume
+   porosity
+   water_saturation
+   permeability
+
+References
+----------------
+
+.. footbibliography::

docs/modules/petrophysics/permeability.rst

@@ -0,0 +1,32 @@
+=========================
+Permeability
+=========================
+
+The library incorporates several classical empirical permeability (k) estimators derived from porosity, water saturation, and resistivity measurements. These models reflect historically validated correlations between rock storage capacity, fluid distribution, and flow properties, providing practical permeability proxies in the absence of core data. While empirical in nature, these methods remain widely used for quick-look evaluations and comparative reservoir analysis.
+
+Porosity–saturation–based formulations represent the primary class of estimators:
+
+- Timur Model – A foundational empirical relationship linking permeability to porosity (φ) and irreducible water saturation (Sw). The model captures the intuitive dependence of permeability on pore volume and fluid occupancy, typically predicting higher permeability for well-connected pore systems exhibiting low water saturation.
+
+- Coates Model – A refinement of the Timur-type approach, incorporating similar dependencies but calibrated to better reflect movable fluid fractions and pore geometry effects. The formulation is frequently applied in conjunction with NMR-derived parameters, although it can be used with conventional porosity and saturation logs.
+
+Resistivity-integrated estimators extend permeability prediction by exploiting electrical responses:
+
+- Coates–Dumanoir Model – Combines deep formation resistivity (Rt or ResD) with porosity to estimate permeability. This model implicitly links pore structure and fluid distribution to electrical behavior, offering an alternative pathway when saturation estimates are uncertain or unavailable. Proper calibration is essential, as unit consistency and formation-specific constants strongly influence results.
+
+- Tixier Model – Utilizes the contrast between deep and shallow resistivity measurements to infer permeability through invasion-profile behavior. The method is based on the premise that permeability governs mud filtrate invasion dynamics; therefore, resistivity differentials can serve as indirect indicators of pore connectivity and transmissibility.
+
+These empirical methods do not replace laboratory-derived permeability but provide operationally useful approximations, particularly during early-stage interpretation, interval ranking, or uncertainty screening. Their reliability depends on lithology, pore type, fluid system, and calibration against representative core or test data.
+
+Permeability
+----------------
+
+.. automodule:: stoneforge.petrophysics.permeability
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+References
+----------------
+
+.. footbibliography::

docs/modules/petrophysics/porosity.rst

@@ -0,0 +1,36 @@
+=========================
+Porosity
+=========================
+
+The library provides a set of conventional porosity estimation techniques derived from density, neutron, and sonic well logs, as well as hybrid formulations designed to mitigate lithology and shale effects. These methods reflect standard petrophysical models and enable users to compute both total and effective porosity under varying geological and logging conditions.
+
+- Density-based porosity calculations rely on the bulk density response of the formation. The Density Porosity model estimates total porosity from the contrast between the measured bulk density (RHOB) and assumed matrix (ρ_ma) and fluid (ρ_f) densities. This formulation is grounded in the volumetric mixing law and is particularly effective in clean formations where matrix properties are reasonably constrained.
+
+- Neutron-derived porosity exploits the sensitivity of neutron tools to hydrogen concentration. The Neutron Porosity estimator corrects the raw neutron response for shale effects by incorporating shale volume (Vsh) and an apparent shale porosity term. This correction is essential because bound water in clays can significantly inflate neutron readings, leading to overestimated porosity if untreated.
+
+- Sonic-based porosity is computed using the Wyllie Time-Average Equation, which models acoustic transit time (Δt) as a linear combination of matrix and fluid contributions. Sonic porosity is often useful in consolidated formations but may require caution in poorly compacted or complex lithologies where the time-average assumption breaks down.
+
+To improve robustness and reduce tool-specific biases, the library includes combined estimators:
+
+- Neutron–Density Porosity – Computes effective porosity from the joint response of density and neutron logs. Depending on configuration, the estimator uses either the arithmetic mean or a root-mean-square formulation, helping stabilize results where individual logs are affected by lithology or fluid variations.
+
+- Gaymard–Poupon Method – A crossplot-inspired correction that integrates neutron and density porosities to better resolve shale-free porosity. This method is widely applied in shaly sand interpretations to compensate for systematic tool deviations.
+
+Effective porosity calculations are also explicitly supported:
+
+- Effective Porosity – Derives shale-corrected porosity from total porosity and shale volume, accounting for the non-reservoir pore space associated with clays. This adjustment is critical for volumetric evaluations and saturation models.
+
+For workflow simplification, the library exposes a façade function that unifies all porosity models under a single interface. This design allows users to select estimation methods based on available logs, formation characteristics, and interpretation strategy while maintaining methodological consistency across analyses.
+
+Porosity
+----------------
+
+.. automodule:: stoneforge.petrophysics.porosity
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+References
+----------------
+
+.. footbibliography::

docs/modules/petrophysics/shale_volume.rst

@@ -0,0 +1,38 @@
+=========================
+Shale Volume
+=========================
+
+The library implements a set of established shale volume (Vshale) estimation techniques widely used in petrophysical interpretation. These methods derive shale content from different logging measurements and reflect distinct theoretical assumptions about rock response, mineralogy, and compaction effects. Collectively, they provide flexible alternatives suitable for a variety of geological settings and data availability scenarios.
+
+Gamma ray–based approaches constitute the primary group of models. The Gamma Ray Index (IGR) serves as the fundamental normalization step, scaling the measured gamma ray log between clean (GRmin) and shale (GRmax) reference values. From this index, several transformation models are provided:
+
+- Linear Model – Assumes a direct proportional relationship between gamma ray response and shale fraction. It is simple, robust, and commonly used as a baseline estimator.
+
+- Larionov Model (Young Rocks) – Introduces a nonlinear correction to account for the typical gamma ray behavior of Tertiary or weakly compacted formations, where the linear assumption tends to overestimate shale volume.
+
+- Larionov Model (Old Rocks) – Adapts the nonlinear response for older, more compacted lithologies, reflecting reduced gamma ray sensitivity with increasing diagenesis.
+
+- Clavier Model – Applies an empirical nonlinear transformation designed to moderate shale volume estimates, particularly in formations exhibiting intermediate gamma ray responses.
+
+- Stieber Model – Incorporates a correction that limits shale volume inflation at higher gamma ray index values, often producing more conservative estimates in laminated or dispersed shale systems.
+
+Beyond gamma ray methods, the library includes multi-log and specialized estimators:
+
+- Neutron–Density Method (Neutron–Density Crossplot) – Computes shale volume using neutron porosity (NPHI) and bulk density (RHOB) measurements via a three-point mixing model. This approach is particularly useful where gamma ray logs are unreliable or where lithology effects must be explicitly handled.
+
+- NMR-Based Method – Estimates shale volume from the relationship between total and effective porosity derived from nuclear magnetic resonance (NMR) data, leveraging differences in fluid and bound water responses.
+
+By offering multiple formulations, the library enables users to select methods consistent with formation age, mineralogical complexity, logging conditions, and calibration strategy. This multi-model design supports comparative analysis and uncertainty assessment in shale volume interpretation workflows.
+
+Shale Volume
+----------------
+
+.. automodule:: stoneforge.petrophysics.shale_volume
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+References
+----------------
+
+.. footbibliography::

docs/modules/petrophysics/water_saturation.rst

@@ -0,0 +1,32 @@
+=========================
+Water Saturation
+=========================
+
+The library implements a suite of widely adopted water saturation (Sw) models derived from resistivity and porosity measurements. These formulations cover both clean and shaly reservoir scenarios, reflecting distinct assumptions about conductive pathways, clay effects, and rock electrical behavior. The available methods enable consistent saturation evaluation across a broad range of lithological and petrophysical conditions.
+
+- The Archie Equation constitutes the fundamental clean-formation model. It relates water saturation to true formation resistivity (Rt), porosity (φ), and water resistivity (Rw), governed by the tortuosity factor (a), cementation exponent (m), and saturation exponent (n). Archie’s model assumes that the rock matrix is non-conductive and that electrical conduction occurs exclusively through the formation water. As such, it is most reliable in clean, clay-free reservoirs where surface conductivity is negligible.
+
+For shaly formations, the library provides models that explicitly incorporate clay conductivity effects:
+
+- Simandoux Model – Extends Archie’s formulation by accounting for the parallel conductive contribution of shale. The model integrates shale volume (Vsh) and shale resistivity (Rsh), making it suitable for dispersed clay systems and laminated shaly sands. It remains one of the most commonly applied shaly-sand saturation equations.
+
+- Indonesia (Poupon–Leveaux) Model – Introduces a nonlinear coupling between matrix and shale conductivity terms. This formulation often produces more stable results in formations with moderate-to-high shale content and is particularly valued where Simandoux may overestimate Sw.
+
+- Fertl Model – A simplified shaly-formation model designed to reduce sensitivity to shale resistivity uncertainties. Instead of requiring explicit Rsh input, the method uses an empirical correction term controlled by the alpha parameter (α). This approach is operationally convenient when shale resistivity is poorly constrained or unavailable.
+
+All shale-corrected models require effective porosity rather than total porosity, reflecting the need to isolate the interconnected pore space contributing to fluid flow and electrical conduction.
+
+To streamline interpretation workflows, the library exposes a façade function that unifies all saturation models under a single interface. This design allows users to select the appropriate equation based on reservoir type, shale content, and data quality while preserving parameter consistency.
+
+Water Saturation
+----------------
+
+.. automodule:: stoneforge.petrophysics.water_saturation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+References
+----------------
+
+.. footbibliography::

docs/modules/reservoir/index.rst

@@ -0,0 +1,15 @@
+=========================
+Reservoir
+=========================
+
+**About:** This section contains documentation for the Reservoir analysis module.
+
+.. toctree::
+   :maxdepth: 1
+
+   net_pay
+
+References
+----------------
+
+.. footbibliography::

docs/modules/reservoir/net_pay.rst

@@ -0,0 +1,18 @@
+=========================
+Net Pay
+=========================
+
+This section is about some methods to stimate some reservoir properties, such as net pay, based on well log data.
+
+Basic Calculations
+------------------
+
+.. automodule:: stoneforge.petrophysics.net_pay
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+References
+----------------
+
+.. footbibliography::