Petroleum Conversions¶

API Gravity¶

The API MPMS Chapter 11 formula:

\[SG = \frac{141.5}{°API + 131.5}\]

api_to_sg ¶

api_to_sg(
    api: Union[float, "UnitFloat", "ProbUnitFloat"],
) -> Union["UnitFloat", "ProbUnitFloat"]

Convert API gravity to specific gravity relative to water at 60°F.

Parameters:

Name	Type	Description	Default
`api`	`float, UnitFloat, or ProbUnitFloat`	API gravity value. When a :class:`~quantia._scalar.UnitFloat` is passed, the `.value` attribute is extracted. When a :class:`~quantia.prob._scalar.ProbUnitFloat` is passed, the conversion is applied sample-wise and a new `ProbUnitFloat` is returned.	required

Returns:

Type	Description
`float or ProbUnitFloat`	Specific gravity (dimensionless). Returns the same type as the input when input is `ProbUnitFloat`.

Raises:

Type	Description
`ValueError`	If `api <= -131.5` (produces zero or negative specific gravity).

See Also

sg_to_api : Inverse conversion.

Examples:

>>> from quantia.petroleum_conversions import api_to_sg
>>> api_to_sg(10.0)    # water by definition
UnitFloat(1.0, '1')
>>> api_to_sg(35.0)    # medium crude
UnitFloat(0.8498, '1')
>>> api_to_sg(60.0)    # light condensate
UnitFloat(0.7389, '1')

Uncertain API gravity:

>>> with qu.config(seed=42, n_samples=2000):
...     api = qu.ProbUnitFloat.normal(35.0, 3.0, '1')
>>> sg = api_to_sg(api)   # ProbUnitFloat
>>> sg.mean().value
0.849...

sg_to_api ¶

sg_to_api(
    sg: Union[float, "UnitFloat", "ProbUnitFloat"],
) -> Union["UnitFloat", "ProbUnitFloat"]

Convert specific gravity to API gravity.

Parameters:

Name	Type	Description	Default
`sg`	`float, UnitFloat, or ProbUnitFloat`	Specific gravity relative to water at 60°F. Must be > 0.	required

Returns:

Type	Description
`float or ProbUnitFloat`	API gravity in degrees.

Raises:

Type	Description
`ValueError`	If `sg <= 0`.