Sand Silt Clay module

class quick_pp.lithology.sand_silt_clay.SandSiltClay(dry_sand_point: tuple[float, float] | None = None, dry_silt_point: tuple[float, float] | None = None, dry_clay_point: tuple[float, float] | None = None, fluid_point: tuple[float, float] | None = None, wet_clay_point: tuple[float, float] | None = None, silt_line_angle: float | None = None, **kwargs)

Bases: object

A ternary lithology model for sand-silt-clay sequences.

This model is a modification of Kuttan’s litho-porosity model. It uses a neutron-density crossplot to estimate the volumetric fractions of sand, silt, and clay. Unlike the original binary model, this implementation considers reservoir sections as a combination of sand, silt, and clay.

estimate_lithology(nphi, rhob)

Estimate sand silt clay lithology volumetrics.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand, silt, and clay,

and a tuple with the calculated min/max trend lines for NPHI and RHOB.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, tuple]

lithology_fraction_kuttan_modified(nphi, rhob)

Estimate lithology volumetrics based on modified Kuttan’s litho-porosity model.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand, silt, and clay.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

lithology_chart(proj_len, rock_len, res_ratio)

Estimate lithology fraction based on Kuttan’s modified chart.

Parameters:

• proj_len (float) – The length of the projected point from the dry sand point along the rock line.

• rock_len (float) – The total length of the rock line (sand to clay).

• res_ratio (float) – The ratio of the reservoir section length (sand to silt) to the total rock line length.

Returns:

A tuple containing the volumes of sand, silt, and clay.

Return type:

tuple[float, float, float]

SandSiltClay.estimate_lithology(nphi, rhob)

Estimate sand silt clay lithology volumetrics.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand, silt, and clay,

and a tuple with the calculated min/max trend lines for NPHI and RHOB.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray, tuple]

SandSiltClay.lithology_fraction_kuttan_modified(nphi, rhob)

Estimate lithology volumetrics based on modified Kuttan’s litho-porosity model.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand, silt, and clay.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

SandSiltClay.lithology_chart(proj_len, rock_len, res_ratio)

Estimate lithology fraction based on Kuttan’s modified chart.

Parameters:

• proj_len (float) – The length of the projected point from the dry sand point along the rock line.

• rock_len (float) – The total length of the rock line (sand to clay).

• res_ratio (float) – The ratio of the reservoir section length (sand to silt) to the total rock line length.

Returns:

A tuple containing the volumes of sand, silt, and clay.

Return type:

tuple[float, float, float]

Sand Shale module

class quick_pp.lithology.sand_shale.SandShale(dry_sand_point: tuple[float, float] | None = None, dry_clay_point: tuple[float, float] | None = None, fluid_point: tuple[float, float] | None = None, wet_clay_point: tuple[float, float] | None = None, silt_line_angle: float | None = None, **kwargs)

Bases: object

A binary lithology model for sand-shale sequences.

This model uses a neutron-density crossplot to estimate the volumetric fractions of sand and shale. It dynamically defines endpoints if not explicitly provided, making it adaptable to different datasets.

dry_sand_point

Initializes the SandShale model with specified or default endpoints.

Parameters:

• dry_sand_point (tuple, optional) – (NPHI, RHOB) for dry sand. Defaults to config values.

• dry_clay_point (tuple, optional) – (NPHI, RHOB) for dry clay. Defaults to config values.

• fluid_point (tuple, optional) – (NPHI, RHOB) for the formation fluid. Defaults to config values.

• wet_clay_point (tuple, optional) – (NPHI, RHOB) for wet clay, used for dynamic endpoint calculation. Defaults to config values.

estimate_lithology(nphi, rhob)

Estimate lithology volumetrics based on neutron density cross plot.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand and clay,

and a tuple with the calculated min/max trend lines for NPHI and RHOB.

Return type:

tuple[np.ndarray, np.ndarray, tuple]

lithology_fraction(nphi, rhob)

Estimate sand and shale based on neutron density cross plot.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand and clay.

Return type:

tuple[np.ndarray, np.ndarray]

SandShale.estimate_lithology(nphi, rhob)

Estimate lithology volumetrics based on neutron density cross plot.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand and clay,

and a tuple with the calculated min/max trend lines for NPHI and RHOB.

Return type:

tuple[np.ndarray, np.ndarray, tuple]

SandShale.lithology_fraction(nphi, rhob)

Estimate sand and shale based on neutron density cross plot.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of sand and clay.

Return type:

tuple[np.ndarray, np.ndarray]

Carbonate module

class quick_pp.lithology.carbonate.Carbonate(dry_calc_point: tuple[float, float] | None = None, dry_dolo_point: tuple[float, float] | None = None, dry_clay_point: tuple[float, float] | None = None, fluid_point: tuple[float, float] | None = None, **kwargs)

Bases: object

A model for estimating carbonate lithology from well logs.

This class implements methods for determining the volumetric fractions of calcite, dolomite, and clay using either neutron-density or density-PEF crossplots. It supports both single-mineral (limestone or dolostone) and dual-mineral (limestone-dolomite) carbonate models.

estimate_lithology(nphi, rhob, pef=None, vsh_gr=None, model: str = 'single', method: str = 'neu_den', carbonate_type: str = 'limestone')

Estimate carbonate and clay lithology volumetrics.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

• pef (np.ndarray or float, optional) – Photoelectric Factor log [barns/electron]. Required for ‘den_pef’ method. Defaults to None.

• vsh_gr (np.ndarray or float, optional) – Volume of shale from gamma ray log [v/v]. Defaults to None.

• model (str, optional) – The lithology model, either ‘single’ (one carbonate type + clay) or ‘double’ (calcite + dolomite + clay). Defaults to ‘single’.

• method (str, optional) – The crossplot method for the ‘double’ model, either ‘neu_den’ or ‘den_pef’. Defaults to ‘neu_den’.

• carbonate_type (str, optional) – The dominant carbonate type for the ‘single’ model, either ‘limestone’ or ‘dolostone’. Defaults to ‘limestone’.

Returns:

A tuple containing the volumes of clay, calcite, and dolomite.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

lithology_fraction_neu_den(nphi, rhob, model: str = 'single', carbonate_type: str = 'limestone')

Estimate clay and carbonate (either limestone or dolostone) based on neutron density cross plot.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

• model (str, optional) – The lithology model, either ‘single’ or ‘double’. Defaults to ‘single’.

• carbonate_type (str, optional) – The dominant carbonate type for the ‘single’ model. Defaults to ‘limestone’.

Returns:

A tuple containing the volumes of the two lithology components.

For ‘single’ model: (vclay, vcarbonate). For ‘double’ model: (vdolomite, vcalcite).

Return type:

tuple[np.ndarray, np.ndarray]

lithology_fraction_pef(pef, rhob)

Estimate limestone and dolostone based on pef density cross plot. Expecting the inputs are clay corrected.

Parameters:

• pef (np.ndarray or float) – Photoelectric Factor log [barns/electron].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of calcite and dolomite.

Return type:

tuple[np.ndarray, np.ndarray]

clay_correction(vcld, nphi, rhob, pef)

Apply clay correction to the input logs.

Parameters:

• vcld (np.ndarray or float) – Volume of clay [v/v].

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

• pef (np.ndarray or float) – Photoelectric Factor log [barns/electron].

Returns:

Clay-corrected NPHI, RHOB, and PEF logs.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

Carbonate.estimate_lithology(nphi, rhob, pef=None, vsh_gr=None, model: str = 'single', method: str = 'neu_den', carbonate_type: str = 'limestone')

Estimate carbonate and clay lithology volumetrics.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

• pef (np.ndarray or float, optional) – Photoelectric Factor log [barns/electron]. Required for ‘den_pef’ method. Defaults to None.

• vsh_gr (np.ndarray or float, optional) – Volume of shale from gamma ray log [v/v]. Defaults to None.

• model (str, optional) – The lithology model, either ‘single’ (one carbonate type + clay) or ‘double’ (calcite + dolomite + clay). Defaults to ‘single’.

• method (str, optional) – The crossplot method for the ‘double’ model, either ‘neu_den’ or ‘den_pef’. Defaults to ‘neu_den’.

• carbonate_type (str, optional) – The dominant carbonate type for the ‘single’ model, either ‘limestone’ or ‘dolostone’. Defaults to ‘limestone’.

Returns:

A tuple containing the volumes of clay, calcite, and dolomite.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

Carbonate.lithology_fraction_neu_den(nphi, rhob, model: str = 'single', carbonate_type: str = 'limestone')

Estimate clay and carbonate (either limestone or dolostone) based on neutron density cross plot.

Parameters:

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

• model (str, optional) – The lithology model, either ‘single’ or ‘double’. Defaults to ‘single’.

• carbonate_type (str, optional) – The dominant carbonate type for the ‘single’ model. Defaults to ‘limestone’.

Returns:

A tuple containing the volumes of the two lithology components.

For ‘single’ model: (vclay, vcarbonate). For ‘double’ model: (vdolomite, vcalcite).

Return type:

tuple[np.ndarray, np.ndarray]

Carbonate.lithology_fraction_pef(pef, rhob)

Estimate limestone and dolostone based on pef density cross plot. Expecting the inputs are clay corrected.

Parameters:

• pef (np.ndarray or float) – Photoelectric Factor log [barns/electron].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

Returns:

A tuple containing the volumes of calcite and dolomite.

Return type:

tuple[np.ndarray, np.ndarray]

Carbonate.clay_correction(vcld, nphi, rhob, pef)

Apply clay correction to the input logs.

Parameters:

• vcld (np.ndarray or float) – Volume of clay [v/v].

• nphi (np.ndarray or float) – Neutron Porosity log [v/v].

• rhob (np.ndarray or float) – Bulk Density log [g/cc].

• pef (np.ndarray or float) – Photoelectric Factor log [barns/electron].

Returns:

Clay-corrected NPHI, RHOB, and PEF logs.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

Multi Mineral module

class quick_pp.lithology.multi_mineral.MultiMineral(minerals: List[str] | None = None, fluid_properties: Dict | None = None, porosity_method: str = 'density', porosity_endpoints: Dict | None = None)

Bases: object

Optimization-based multi-mineral model for lithology estimation with fluid volumes.

_volume_constraint(volumes: ndarray) → float

Ensure that the sum of all mineral and fluid volumes equals 1.

_calculate_porosity(nphi: float, rhob: float, dtc: float | None = None) → float

Calculate an initial porosity estimate based on the selected method.

Parameters:

• nphi (float) – Neutron porosity value.

• rhob (float) – Bulk density value.

• dtc (float, optional) – Sonic transit time value. Defaults to None.

Returns:

The initial porosity estimate.

Return type:

float

_calculate_matrix_density(mineral_volumes: ndarray) → float

Calculate the average matrix density from mineral volumes.

Parameters:

mineral_volumes (np.ndarray) – An array of mineral volumes.

Returns:

The calculated matrix density.

Return type:

float

_calculate_fluid_density(fluid_volumes: ndarray) → float

Calculate the average fluid density from fluid volumes.

Parameters:

fluid_volumes (np.ndarray) – An array of fluid volumes.

Returns:

The calculated average fluid density.

Return type:

float

_calculate_log_response(volumes: ndarray, log_type: str) → float

Calculate the reconstructed log response for a given log type.

Parameters:

• volumes (np.ndarray) – An array of combined mineral and fluid volumes.

• log_type (str) – The type of log to reconstruct (e.g., ‘NPHI’, ‘RHOB’).

Returns:

The reconstructed log value.

Return type:

float

_calculate_average_error(volumes: ndarray, log_values: Dict[str, float]) → float

Calculate the average absolute error between measured and reconstructed logs.

Parameters:

• volumes (np.ndarray) – An array of combined mineral and fluid volumes.

• log_values (dict) – A dictionary of measured log values.

Returns:

The average absolute error.

Return type:

float

_error_function(volumes: ndarray, log_values: Dict[str, float]) → float

Calculate the sum of squared errors for the optimization.

Parameters:

• volumes (np.ndarray) – An array of combined mineral and fluid volumes.

• log_values (dict) – A dictionary of measured log values.

Returns:

The total squared error.

Return type:

float

_optimize_volumes(log_values: Dict[str, float]) → Tuple[ndarray, ndarray, bool]

Perform the optimization to find the best-fit mineral and fluid volumes.

Parameters:

log_values (dict) – A dictionary of measured log values for a single depth point.

Returns:

A tuple containing the optimized mineral volumes, fluid volumes, and a success flag.

Return type:

tuple

estimate_lithology(gr: ndarray, nphi: ndarray, rhob: ndarray, pef: ndarray | None = None, dtc: ndarray | None = None, auto_scale: bool = True) → DataFrame

Estimate mineral and fluid volumes for a set of log data points.

This function iterates through each depth point, performing an optimization to determine the volumetric fractions of minerals and fluids that best match the measured log responses.

Parameters:

• gr (np.ndarray) – Gamma Ray log [GAPI].

• nphi (np.ndarray) – Neutron Porosity log [v/v].

• rhob (np.ndarray) – Bulk Density log [g/cc].

• pef (np.ndarray, optional) – Photoelectric Factor log [barns/electron]. Defaults to None.

• dtc (np.ndarray, optional) – Compressional slowness log [us/ft]. Defaults to None.

• auto_scale (bool, optional) – If True, automatically calculates scaling factors. Defaults to True.

Returns:

A DataFrame containing the estimated mineral and fluid volumes,

constructed porosity, error metrics, and reconstructed logs for each depth point.

Return type:

pd.DataFrame

MultiMineral.estimate_lithology(gr: ndarray, nphi: ndarray, rhob: ndarray, pef: ndarray | None = None, dtc: ndarray | None = None, auto_scale: bool = True) → DataFrame

Estimate mineral and fluid volumes for a set of log data points.

This function iterates through each depth point, performing an optimization to determine the volumetric fractions of minerals and fluids that best match the measured log responses.

Parameters:

• gr (np.ndarray) – Gamma Ray log [GAPI].

• nphi (np.ndarray) – Neutron Porosity log [v/v].

• rhob (np.ndarray) – Bulk Density log [g/cc].

• pef (np.ndarray, optional) – Photoelectric Factor log [barns/electron]. Defaults to None.

• dtc (np.ndarray, optional) – Compressional slowness log [us/ft]. Defaults to None.

• auto_scale (bool, optional) – If True, automatically calculates scaling factors. Defaults to True.

Returns:

A DataFrame containing the estimated mineral and fluid volumes,

constructed porosity, error metrics, and reconstructed logs for each depth point.

Return type:

pd.DataFrame

General Lithology functions

quick_pp.lithology.shale_volume_larinov_tertiary(igr)

Computes shale volume from gamma ray using Larinov’s method for tertiary rocks.

Parameters:

igr (float) – Interval gamma ray [API].

Returns:

vshale – Shale volume [fraction].

Return type:

float

quick_pp.lithology.shale_volume_larinov_older(igr)

Computes shale volume from gamma ray using Larinov’s method for older rocks.

Parameters:

igr (float) – Interval gamma ray [API].

Returns:

vshale – Shale volume [fraction].

Return type:

float

quick_pp.lithology.shale_volume_steiber(igr)

Computes shale volume from gamma ray using Steiber’s method.

Parameters:

igr (float) – Interval gamma ray [API].

Returns:

vshale – Shale volume [fraction].

Return type:

float

quick_pp.lithology.gr_index(gr)

Computes gamma ray index from gamma ray.

Parameters:

gr (float) – Gamma ray [API].

Returns:

gr_index – Gamma ray index [API].

Return type:

float