Gas¶

Gas mix value object for diveplan.

Represents an immutable O2/He/N2 breathing gas mixture. Provides partial pressure calculations, operating limits, and best-mix selection.

class diveplan.core.gas.Gas(fo2, fhe=0.0)[source]¶

Bases: object

Immutable O2/He/N2 breathing gas mixture.

Fractions are stored as floats (0.0-1.0). fn2 is derived: fn2 = 1.0 - fo2 - fhe. The three fractions always sum to 1.0 within a tolerance of 1e-6.

Use the named constructors (air, nitrox, trimix, …) rather than the raw constructor wherever possible.

Parameters:

fo2 (float) – Oxygen fraction, e.g. 0.21.
fhe (float) – Helium fraction. Defaults to 0.0 (no helium).

Raises:

ValueError – If any fraction is negative, or the fractions do not sum to 1.0 within 1e-6.

Example

>>> Gas(0.32)
Gas(fo2=0.32, fhe=0.00, fn2=0.68)
>>> Gas(0.21, fhe=0.35)
Gas(fo2=0.21, fhe=0.35, fn2=0.44)

property fo2: float¶: Oxygen fraction (0.0-1.0).

property fhe: float¶: Helium fraction (0.0-1.0).

property fn2: float¶: Nitrogen fraction (0.0-1.0), derived as 1 - fo2 - fhe.

property name: str¶: Human-readable name for this gas, e.g. “Air”, “EAN32”, “TX21/35”.

classmethod air()[source]¶

Return standard air (21 % O2, 79 % N2).

Return type:: Gas
Returns:: A Gas representing atmospheric air.

classmethod oxygen()[source]¶

Return 100 % oxygen.

Return type:: Gas
Returns:: A Gas with fo2=1.0.

classmethod nitrox(fo2)[source]¶

Return a nitrox (O2/N2) mix with the given O2 fraction.

Parameters:: fo2 (float) – Oxygen fraction, e.g. 0.32 for EAN32.
Return type:: Gas
Returns:: A Gas with no helium and nitrogen making up the remainder.
Raises:: ValueError – If fo2 <= 0 or fo2 > 1.

classmethod ean(fo2)[source]¶

Alias for nitrox().

Parameters:: fo2 (float) – Oxygen fraction, e.g. 0.32 for EAN32.
Return type:: Gas
Returns:: A Gas with no helium.

classmethod trimix(fo2, fhe)[source]¶

Return a trimix (O2/He/N2) gas.

Parameters:

fo2 (float) – Oxygen fraction.
fhe (float) – Helium fraction.

Return type:

Gas

Returns:

A Gas where nitrogen fills the remainder.

Raises:

ValueError – If fo2 <= 0, fhe <= 0, or fractions are otherwise invalid.

classmethod from_name(name)[source]¶

Parse a gas mix from a human-readable name string.

Supported formats (case-insensitive):

"air"
"oxygen"
"nx32", "ean32", "nitrox 32" — O2 % as integer
"tx21/35", "trimix 21/35" — O2%/He%

Parameters:: name (str) – Human-readable gas name.
Return type:: Gas
Returns:: The corresponding Gas instance.
Raises:: ValueError – If the name cannot be parsed.

Example

>>> Gas.from_name("ean32")
Gas(fo2=0.32, fhe=0.00, fn2=0.68)
>>> Gas.from_name("tx21/35")
Gas(fo2=0.21, fhe=0.35, fn2=0.44)

ppo2(pressure)[source]¶

Return the partial pressure of O2 at the given ambient pressure.

Parameters:: pressure (Pressure) – Ambient pressure.
Return type:: Pressure
Returns:: Partial pressure of oxygen.

pphe(pressure)[source]¶

Return the partial pressure of He at the given ambient pressure.

Parameters:: pressure (Pressure) – Ambient pressure.
Return type:: Pressure
Returns:: Partial pressure of helium.

ppn2(pressure)[source]¶

Return the partial pressure of N2 at the given ambient pressure.

Parameters:: pressure (Pressure) – Ambient pressure.
Return type:: Pressure
Returns:: Partial pressure of nitrogen.

mod(*, ppo2_bar)[source]¶

Return the maximum operating depth (MOD) for a given ppO2 limit.

Parameters:: ppo2_bar (float) – ppO2 ceiling in bar, e.g. 1.4.
Return type:: Pressure
Returns:: The MOD as a Pressure.
Raises:: ValueError – If ppo2_bar <= 0.

Example

>>> from diveplan.core.pressure import Pressure
>>> Gas.nitrox(0.32).mod(ppo2_bar=1.4).bar
4.375

end(pressure)[source]¶

Return the equivalent narcotic depth (END) at the given pressure.

Helium is assumed non-narcotic; the narcotic fraction is fo2 + fn2.

Parameters:: pressure (Pressure) – Ambient pressure at depth.
Return type:: Pressure
Returns:: The END as a Pressure.

is_breathable(pressure)[source]¶

Whether this gas is breathable at the given ambient pressure.

Breathable means the ppO2 sits within the configured [min_ppo2_bar, deco_ppo2_bar] window (from DiveConfig.current()). The deco limit is used because this is the gas-switching question — switches happen during the ascent, where the deco ppO2 applies; compare against mod(ppo2_bar=...) for an explicit working limit.

Parameters:: pressure (Pressure) – Ambient pressure at depth.
Return type:: bool

best_mix(depth, *, trimix=False, hypoxic=False)[source]¶

Return the optimal gas mix for the given depth.

Maximises fo2 within the ppO2 and END/ppN2 constraints taken from diveplan.core.config.DiveConfig.current().

hypoxic=True implies trimix=True.

Parameters:

depth (float | Pressure) – Target depth as metres (float) or a Pressure.
trimix (bool) – Allow helium in the mix.
hypoxic (bool) – Allow fo2 below min_ppo2_bar at surface (implies trimix=True).

Return type:

Gas

Returns:

The best Gas for the given depth and constraints.

Raises:

ValueError – If the constraints cannot be satisfied (e.g. best_mix(120, trimix=False)).

Example

>>> Gas.air().best_mix(30)
Gas(fo2=0.32, fhe=0.00, fn2=0.68)