API Reference

Summary

Primary Phase Models

`THM`(qi, Di, bi, bf, telf, bterm, tterm, ...)	Transient Hyperbolic Model
`MH`(qi, Di, bi, Dterm, validate_params)	Modified Hyperbolic Model
`PLE`(qi, Di, Dinf, n, validate_params)	Power-Law Exponential Model
`SE`(qi, tau, n, validate_params)	Stretched Exponential
`Duong`(qi, a, m, validate_params)	Duong Model

Associated Phase Models

Secondary Phase Models

PLYield(c, m0, m, t0[, min, max])

Power-Law Associated Phase Model.

Water Phase Models

PLYield(c, m0, m, t0[, min, max])

Power-Law Associated Phase Model.

Model Functions

All Models

`rate`(t)	Defines the model rate function:
`cum`(t, **kwargs)	Defines the model cumulative volume function:
`interval_vol`(t[, t0])	Defines the model interval volume function:
`monthly_vol`(t, **kwargs)	Defines the model fixed monthly interval volume function.
`monthly_vol_equiv`(t[, t0])	Defines the model equivalent monthly interval volume function:
`D`(t)	Defines the model D-parameter function:
`beta`(t)	Defines the model beta-parameter function.
`b`(t)	Defines the model b-parameter function:
`get_param_desc`(name)	Get a single parameter description.
`get_param_descs`()	Get the parameter descriptions.
`from_params`(params)	Construct a model from a sequence of parameters.

Primary Phase Models

`add_secondary`(secondary)	Attach a secondary phase model to this primary phase model.
`add_water`(water)	Attach a water phase model to this primary phase model.

Associated Phase Models

Secondary Phase Models

`gor`(t)	Defines the model GOR function.
`cgr`(t)	Defines the model CGR function.

Water Phase Models

`wor`(t)	Defines the model WOR function.
`wgr`(t)	Defines the model WGR function.

Transient Hyperbolic Specific

`transient_rate`(t, **kwargs)	Compute the rate function using full definition.
`transient_cum`(t, **kwargs)	Compute the cumulative volume function using full definition.
`transient_D`(t)	Compute the D-parameter function using full definition.
`transient_beta`(t)	Compute the beta-parameter function using full definition.
`transient_b`(t)	Compute the b-parameter function using full definition.

Utility Functions

`bourdet`(y, x[, L, xlog, ylog])	Bourdet Derivative Smoothing
`get_time`([start, end, n])	Get a time array to evaluate with.
`get_time_monthly_vol`([start, end])	Get a time array to evaluate with.

Utility Constants

`DAYS_PER_MONTH`	365.25 / 12 = 30.4375
`DAYS_PER_YEAR`	365.25

Detailed Reference

Base Classes

These classes define the basic functions that are exposed by all decline curve models.

class petbox.dca.DeclineCurve(*args: float)[source]

Base class for decline curve models. Each model must implement the defined abstract methods.

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

interval_vol(t: float | ndarray[tuple[Any, ...], dtype[float64]], t0: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None, **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model interval volume function:

\[N(t) = \int_{t_{i-1}}^{t_i} q \, dt\]

for each element of t.

Parameters:

t (Union[float, numpy.NDFloat]) – An array of interval end times at which to evaluate the function.
t0 (Optional[Union[float, numpy.NDFloat]]) – A start time of the first interval. If not given, the first element of t is used.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

interval volume

Return type:

numpy.NDFloat

monthly_vol(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model fixed monthly interval volume function. If t < 1 month, the interval begin at zero:

\[N(t) = \int_{t-{1 \, month}}^{t} q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of interval end times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

monthly equivalent volume

Return type:

numpy.NDFloat

monthly_vol_equiv(t: float | ndarray[tuple[Any, ...], dtype[float64]], t0: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None, **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model equivalent monthly interval volume function:

\[N(t) = \frac{\frac{365.25}{12}}{t-(t-1 \, month)} \int_{t-{1 \, month}}^{t} q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of interval end times at which to evaluate the function.
t0 (Optional[Union[float, numpy.NDFloat]]) – A start time of the first interval. If not given, assumed to be zero.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

monthly equivalent volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

classmethod get_param_desc(name: str) → ParamDesc[source]

Get a single parameter description.

Parameters:: name (str) – The parameter name.
Returns:: parameter description – A parameter description.
Return type:: ParamDesc

abstract classmethod get_param_descs() → List[ParamDesc][source]

Get the parameter descriptions.

Returns:: parameter description – A list of parameter descriptions.
Return type:: List[ParamDesc]

classmethod from_params(params: Sequence[float]) → _Self[source]

Construct a model from a sequence of parameters.

Returns:: decline curve – The constructed decline curve model class.
Return type:: DeclineCurve

class petbox.dca.PrimaryPhase(*args: float)[source]

Extends DeclineCurve for a primary phase forecast. Adds the capability to link a secondary (associated) phase model.

add_secondary(secondary: SecondaryPhase) → None[source]

Attach a secondary phase model to this primary phase model.

Parameters:: secondary (SecondaryPhase) – A model that inherits the SecondaryPhase class.

add_water(water: WaterPhase) → None[source]

Attach a water phase model to this primary phase model.

Parameters:: water (WaterPhase) – A model that inherits the WaterPhase class.

class petbox.dca.SecondaryPhase(*args: float)[source]

Extends DeclineCurve for a secondary (associated) phase forecast. Adds the capability to link a primary phase model. Defines the gor() and cgr() functions. Each model must implement the defined abstract method.

gor(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model GOR function. Implementation is idential to CGR function.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: GOR – The gas-oil ratio function in units of Mscf / Bbl.
Return type:: numpy.NDFloat

cgr(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model CGR function. Implementation is identical to GOR function.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: CGR – The condensate-gas ratio in units of Bbl / Mscf.
Return type:: numpy.NDFloat

class petbox.dca.WaterPhase(*args: float)[source]

Extends DeclineCurve for a water (associated) phase forecast. Adds the capability to link a primary phase model. Defines the wor() function. Each model must implement the defined abstract method.

wor(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model WOR function.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: WOR – The water-oil ratio function in units of Bbl / Bbl.
Return type:: numpy.NDFloat

wgr(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Defines the model WGR function.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: WOR – The water-gas ratio function in units of Bbl / Mscf.
Return type:: numpy.NDFloat

Primary Phase Models

Implementations of primary phase decline curve models

class petbox.dca.THM(qi: float, Di: float, bi: float, bf: float, telf: float, bterm: float = 0.0, tterm: float = 0.0, validate_params: ~typing.Iterable[bool] = <factory>)[source]

Transient Hyperbolic Model

Fulford, D. S., and Blasingame, T. A. 2013. Evaluation of Time-Rate Performance of Shale Wells using the Transient Hyperbolic Relation. Presented at SPE Unconventional Resources Conference – Canada in Calgary, Alberta, Canda, 5–7 November. SPE-167242-MS. https://doi.org/10.2118/167242-MS.

Analytic Approximation

Fulford, D.S. 2018. A Model-Based Diagnostic Workflow for Time-Rate Performance of Unconventional Wells. Presented at Unconventional Resources Conference in Houston, Texas, USA, 23–25 July. URTeC-2903036. https://doi.org/10.15530/urtec-2018-2903036.

Parameters:

qi (float) – The initial production rate in units of volume / day.
Di (float) –
The initial decline rate in secant effective decline aka annual effective percent decline, i.e.

\[D_i = 1 - \frac{q(t=1 \, year)}{qi}\]

\[D_i = 1 - (1 + 365.25 \, D_{nom} \, b) ^ \frac{-1}{b}\]

where Dnom is defined as \(\frac{d}{dt}\textrm{ln} \, q\) and has units of 1 / day.
bi (float) – The initial hyperbolic parameter, defined as \(\frac{d}{dt}\frac{1}{D}\). This parameter is dimensionless. Advised to always be set to 2.0 to represent transient linear flow. See literature for more details.
bf (float) – The final hyperbolic parameter after transition. Represents the boundary-dominated or boundary-influenced flow regime.
telf (float) – The time to end of linear flow in units of day, or more specifically the time at which b(t) < bi. Visual end of half slope occurs ~2.5x after telf.
bterm (Optional[float] = None) –
The terminal value of the hyperbolic parameter. Has two interpretations:

If tterm > 0 then the terminal regime is a hyperbolic regime with b = bterm and the parameter is given as the hyperbolic parameter.

If tterm = 0 then the terminal regime is an exponential regime with Dterm = bterm and the parameter is given as secant effective decline.
tterm (Optional[float] = None) – The time to start of the terminal regime in years. Setting tterm = 0.0 creates an exponential terminal regime, while setting tterm > 0.0 creates a hyperbolic terminal regime.

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

transient_rate(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the rate function using full definition. Numerically integrates transient_D().

\[q(t) = e^{-\int_0^t D(t) \, dt}\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of time values to evaluate.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Return type:

numpy.NDFloat

transient_cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the cumulative volume function using full definition. Numerically integrates transient_rate().

\[N(t) = \int_0^t q(t) \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of time values to evaluate.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Return type:

numpy.NDFloat

transient_D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the D-parameter function using full definition.

\[D(t) = \frac{1}{\frac{1}{Di} + b_i t + \frac{bi - bf}{c} (\textrm{Ei}[-e^{-c \, (t -t_{elf}) + e^(\gamma)}] - \textrm{Ei}[-e^{c \, t_{elf} + e^(\gamma)}])}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of time values to evaluate.
Return type:: numpy.NDFloat

transient_beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the beta-parameter function using full definition.

\[\beta(t) = \frac{t}{\frac{1}{Di} + b_i t + \frac{bi - bf}{c} (\textrm{Ei}[-e^{-c \, (t -t_{elf}) + e^(\gamma)}] - \textrm{Ei}[-e^{c \, t_{elf} + e^(\gamma)}])}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of time values to evaluate.
Return type:: numpy.NDFloat

transient_b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the b-parameter function using full definition.

\[b(t) = b_i - (b_i - b_f) e^{-\textrm{exp}[{-c * (t - t_{elf}) + e^{\gamma}}]}\]

where:

\[\begin{split}c & = \frac{e^{\gamma}}{1.5 \, t_{elf}} \\ \gamma & = 0.57721566... \; \textrm{(Euler-Mascheroni constant)}\end{split}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of time values to evaluate.
Return type:: numpy.NDFloat

class petbox.dca.MH(qi: float, Di: float, bi: float, Dterm: float = 0.0, validate_params: ~typing.Iterable[bool] = <factory>)[source]

Modified Hyperbolic Model

Robertson, S. 1988. Generalized Hyperbolic Equation. Available from SPE, Richardson, Texas, USA. SPE-18731-MS.

Parameters:

qi (float) – The initial production rate in units of volume / day.
Di (float) –
The initial decline rate in secant effective decline aka annual effective percent decline, i.e.

\[D_i = 1 - \frac{q(t=1 \, year)}{qi}\]

\[D_i = 1 - (1 + 365.25 \, D_{nom} \, b) ^ \frac{-1}{b}\]

where Dnom is defined as \(\frac{d}{dt}\textrm{ln} \, q\) and has units of 1 / day.
bi (float) – The (initial) hyperbolic parameter, defined as \(\frac{d}{dt}\frac{1}{D}\). This parameter is dimensionless.
Dterm (float) – The terminal secant effective decline rate aka annual effective percent decline.

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

classmethod get_param_desc(name: str) → ParamDesc

Get a single parameter description.

Parameters:: name (str) – The parameter name.
Returns:: parameter description – A parameter description.
Return type:: ParamDesc

classmethod get_param_descs() → List[ParamDesc][source]

Get the parameter descriptions.

Returns:: parameter description – A list of parameter descriptions.
Return type:: List[ParamDesc]

classmethod from_params(params: Sequence[float]) → _Self

Construct a model from a sequence of parameters.

Returns:: decline curve – The constructed decline curve model class.
Return type:: DeclineCurve

class petbox.dca.PLE(qi: float, Di: float, Dinf: float, n: float, validate_params: ~typing.Iterable[bool] = <factory>)[source]

Power-Law Exponential Model

Ilk, D., Perego, A. D., Rushing, J. A., and Blasingame, T. A. 2008. Exponential vs. Hyperbolic Decline in Tight Gas Sands – Understanding the Origin and Implications for Reserve Estimates Using Arps Decline Curves. Presented at SPE Annual Technical Conference and Exhibition in Denver, Colorado, USA, 21–24 September. SPE-116731-MS. https://doi.org/10.2118/116731-MS.

Ilk, D., Rushing, J. A., and Blasingame, T. A. 2009. Decline Curve Analysis for HP/HT Gas Wells: Theory and Applications. Presented at SPE Annual Technical Conference and Exhibition in New Orleands, Louisiana, USA, 4–7 October. SPE-125031-MS. https://doi.org/10.2118/125031-MS.

Parameters:

qi (float) – The initial production rate in units of volume / day.
Di (float) – The initial decline rate in nominal decline rate defined as d[ln q] / dt and has units of 1 / day.
Dterm (float) – The terminal decline rate in nominal decline rate, has units of 1 / day.
n (float) – The n exponent.

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

classmethod get_param_desc(name: str) → ParamDesc

Get a single parameter description.

Parameters:: name (str) – The parameter name.
Returns:: parameter description – A parameter description.
Return type:: ParamDesc

classmethod get_param_descs() → List[ParamDesc][source]

Get the parameter descriptions.

Returns:: parameter description – A list of parameter descriptions.
Return type:: List[ParamDesc]

classmethod from_params(params: Sequence[float]) → _Self

Construct a model from a sequence of parameters.

Returns:: decline curve – The constructed decline curve model class.
Return type:: DeclineCurve

class petbox.dca.SE(qi: float, tau: float, n: float, validate_params: ~typing.Iterable[bool] = <factory>)[source]

Stretched Exponential

Valkó, P. P. Assigning Value to Stimulation in the Barnett Shale: A Simultaneous Analysis of 7000 Plus Production Histories and Well Completion Records. 2009. Presented at SPE Hydraulic Fracturing Technology Conference in College Station, Texas, USA, 19–21 January. SPE-119369-MS. https://doi.org/10.2118/119369-MS.

Parameters:

qi (float) – The initial production rate in units of volume / day.
tau (float) –
The tau parameter in units of day ** n. Equivalent to:

\[\tau = D^n\]
n (float) – The n exponent.

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

classmethod get_param_desc(name: str) → ParamDesc

Get a single parameter description.

Parameters:: name (str) – The parameter name.
Returns:: parameter description – A parameter description.
Return type:: ParamDesc

classmethod get_param_descs() → List[ParamDesc][source]

Get the parameter descriptions.

Returns:: parameter description – A list of parameter descriptions.
Return type:: List[ParamDesc]

classmethod from_params(params: Sequence[float]) → _Self

Construct a model from a sequence of parameters.

Returns:: decline curve – The constructed decline curve model class.
Return type:: DeclineCurve

class petbox.dca.Duong(qi: float, a: float, m: float, validate_params: ~typing.Iterable[bool] = <factory>)[source]

Duong Model

Duong, A. N. 2001. Rate-Decline Analysis for Fracture-Dominated Shale Reservoirs. SPE Res Eval & Eng 14 (3): 377–387. SPE-137748-PA. https://doi.org/10.2118/137748-PA.

Parameters:

qi (float) – The initial production rate in units of volume / day defined at ``t=1 day``.
a (float) – The a parameter. Roughly speaking, controls slope of the :func:q(t) function.
m (float) – The m parameter. Roughly speaking, controls curvature of the:func:q(t) function.

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

classmethod get_param_desc(name: str) → ParamDesc

Get a single parameter description.

Parameters:: name (str) – The parameter name.
Returns:: parameter description – A parameter description.
Return type:: ParamDesc

classmethod get_param_descs() → List[ParamDesc][source]

Get the parameter descriptions.

Returns:: parameter description – A list of parameter descriptions.
Return type:: List[ParamDesc]

classmethod from_params(params: Sequence[float]) → _Self

Construct a model from a sequence of parameters.

Returns:: decline curve – The constructed decline curve model class.
Return type:: DeclineCurve

Associated Phase Models

Implementations of associated (secondary and water) phase GOR/CGR/WOR/WGR models

class petbox.dca.PLYield(c: float, m0: float, m: float, t0: float, min: float | None = None, max: float | None = None)[source]

Power-Law Associated Phase Model.

Fulford, D.S. 2018. A Model-Based Diagnostic Workflow for Time-Rate Performance of Unconventional Wells. Presented at Unconventional Resources Conference in Houston, Texas, USA, 23–25 July. URTeC-2903036. https://doi.org/10.15530/urtec-2018-2903036.

Has the general form of

\[GOR = c \, t^m\]

and allows independent early-time and late-time slopes m0 and m respectively.

Parameters:

c (float) – The value of GOR/CGR/WOR/CGR that acts as the anchor or pivot at t=t0. Units should be correctly specified for the respective yield function. Assumed volumes units per phase must be Bbl for oil and water and Mscf for gas in order to resolve any inconsistencies in unit magnitude.
m0 (float) – Early-time power-law slope.
m (float) – Late-time power-law slope.
t0 (float) – The time of the anchor or pivot value c.
min (Optional[float] = None) – The minimum allowed value. Would be used e.g. to limit minimum CGR.
max (Optional[float] = None) – The maximum allowed value. Would be used e.g. to limit maximum GOR.

gor(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model GOR function. Implementation is idential to CGR function.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: GOR – The gas-oil ratio function in units of Mscf / Bbl.
Return type:: numpy.NDFloat

cgr(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model CGR function. Implementation is identical to GOR function.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: CGR – The condensate-gas ratio in units of Bbl / Mscf.
Return type:: numpy.NDFloat

rate(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model rate function:

\[q(t) = f(t)\]

where \(f(t)\) is defined by each model.

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: rate
Return type:: numpy.NDFloat

cum(t: float | ndarray[tuple[Any, ...], dtype[float64]], **kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model cumulative volume function:

\[N(t) = \int_0^t q \, dt\]

Parameters:

t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
**kwargs – Additional keyword arguments (currently unused, reserved for future use).

Returns:

cumulative volume

Return type:

numpy.NDFloat

D(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model D-parameter function:

\[D(t) \equiv \frac{d}{dt}\textrm{ln} \, q \equiv \frac{1}{q}\frac{dq}{dt}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: D-parameter
Return type:: numpy.NDFloat

beta(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model beta-parameter function.

\[\beta(t) \equiv \frac{d \, \textrm{ln} \, q}{d \, \textrm{ln} \, t} \equiv \frac{t}{q}\frac{dq}{dt} \equiv t \, D(t)\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: beta-parameter
Return type:: numpy.NDFloat

b(t: float | ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]]

Defines the model b-parameter function:

\[b(t) \equiv \frac{d}{dt}\frac{1}{D}\]

Parameters:: t (Union[float, numpy.NDFloat]) – An array of times at which to evaluate the function.
Returns:: b-parameter
Return type:: numpy.NDFloat

classmethod get_param_desc(name: str) → ParamDesc

Get a single parameter description.

Parameters:: name (str) – The parameter name.
Returns:: parameter description – A parameter description.
Return type:: ParamDesc

classmethod get_param_descs() → List[ParamDesc][source]

Get the parameter descriptions.

Returns:: parameter description – A list of parameter descriptions.
Return type:: List[ParamDesc]

classmethod from_params(params: Sequence[float]) → _Self

Construct a model from a sequence of parameters.

Returns:: decline curve – The constructed decline curve model class.
Return type:: DeclineCurve

Utility Functions

petbox.dca.bourdet(y: ndarray[tuple[Any, ...], dtype[float64]], x: ndarray[tuple[Any, ...], dtype[float64]], L: float = 0.0, xlog: bool = True, ylog: bool = False) → ndarray[tuple[Any, ...], dtype[float64]][source]

Bourdet Derivative Smoothing

Compute the smoothed derivative using the Bourdet three-point algorithm (Eq. 8 of SPE-12777):

\[\left(\frac{dp}{dX}\right)_i = \frac{\frac{\Delta p_1}{\Delta X_1} \Delta X_2 + \frac{\Delta p_2}{\Delta X_2} \Delta X_1} {\Delta X_1 + \Delta X_2}\]

where points 1 and 2 are the first neighbors outside the smoothing window of distance L from point i on the log10(x) axis.

At interior points, the left neighbor is the last point j < i such that log10(x[i]) - log10(x[j]) > L, and the right neighbor is the first point j > i such that log10(x[j]) - log10(x[i]) > L. At left-edge points (where no left neighbor beyond L exists), a forward difference to the right neighbor is used. At right-edge points, a backward difference to the left neighbor is used.

Bourdet, D., Ayoub, J. A., and Pirard, Y. M. 1989. Use of Pressure Derivative in Well-Test Interpretation. SPE Form Eval 4 (2): 293-302. SPE-12777-PA. https://doi.org/10.2118/12777-PA.

Parameters:

y (numpy.NDFloat) – An array of y values to compute the derivative for.
x (numpy.NDFloat) – An array of x values.
L (float = 0.0) –
Smoothing factor in units of log10 cycles (i.e., decades). A value of zero returns the point-by-point first-order difference derivative.

Note

The original paper (SPE-12777) defines L in natural-log units. To convert: L_log10 = L_paper / ln(10). For example, the paper’s L=0.1 corresponds to L=0.0434 in this function.
xlog (bool = True) – Calculate the derivative with respect to the log of x, i.e. dy / d[ln x].
ylog (bool = False) – Calculate the derivative with respect to the log of y, i.e. d[ln y] / dx.

Returns:

der – The calculated derivative.

Return type:

numpy.NDFloat

petbox.dca.get_time(start: float = 1.0, end: float = 100000.0, n: int = 101) → ndarray[tuple[Any, ...], dtype[float64]][source]

Get a time array to evaluate with.

Parameters:

start (float) – The first time value of the array.
end (float) – The last time value of the array.
n (int) – The number of element in the array.

Returns:

time – An evenly-logspaced time series.

Return type:

numpy.NDFloat

petbox.dca.get_time_monthly_vol(start: float = 1, end: int = 10000) → ndarray[tuple[Any, ...], dtype[float64]][source]

Get a time array to evaluate with.

Parameters:

start (float) – The first time value of the array.
end (float) – The last time value of the array.

Returns:

time – An evenly-monthly-spaced time series

Return type:

numpy.NDFloat

Other Classes

class petbox.dca.AssociatedPhase(*args: float)[source]: Extends DeclineCurve for an associated phase forecast. Each model must implement the defined abstract _yieldfn() method.

class petbox.dca.BothAssociatedPhase(*args: float)[source]: Extends DeclineCurve for a general yield model used for both secondary phase and water phase.

class petbox.dca.base.ParamDesc(name: str, description: str, lower_bound: float | None, upper_bound: float | None, naive_gen: Callable[[numpy.random._generator.Generator, int], numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]], exclude_lower_bound: bool = False, exclude_upper_bound: bool = False)[source]