Skip to main content

gas_force/
lib.rs

1//! Typed ideal-gas state and reference-condition conversions.
2//!
3//! This crate applies `PV = nRT` to validated scalar quantities. Pressure is
4//! always absolute and temperature is always stored in kelvin.
5
6#![forbid(unsafe_code)]
7#![warn(missing_docs)]
8
9use std::error::Error;
10use std::fmt;
11
12/// Molar gas constant in joules per mole-kelvin.
13pub const MOLAR_GAS_CONSTANT: f64 = 8.314_462_618_153_24;
14
15/// A finite, positive absolute pressure stored in pascals.
16#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
17pub struct Pressure(f64);
18
19impl Pressure {
20    /// Creates an absolute pressure in pascals.
21    pub fn pascals(value: f64) -> Result<Self, GasError> {
22        validate_positive_finite(value, "absolute pressure")?;
23        Ok(Self(value))
24    }
25
26    /// Creates an absolute pressure in kilopascals.
27    pub fn kilopascals(value: f64) -> Result<Self, GasError> {
28        validate_positive_finite(value, "absolute pressure")?;
29        let pascals = value * 1_000.0;
30        ensure_finite(pascals)?;
31        Ok(Self(pascals))
32    }
33
34    /// Returns absolute pressure in pascals.
35    pub const fn as_pascals(self) -> f64 {
36        self.0
37    }
38
39    /// Returns absolute pressure in kilopascals.
40    pub fn as_kilopascals(self) -> f64 {
41        self.0 / 1_000.0
42    }
43}
44
45/// A finite, positive volume stored in cubic meters.
46#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
47pub struct Volume(f64);
48
49impl Volume {
50    /// Creates a volume in cubic meters.
51    pub fn cubic_meters(value: f64) -> Result<Self, GasError> {
52        validate_positive_finite(value, "volume")?;
53        Ok(Self(value))
54    }
55
56    /// Creates a volume in liters.
57    pub fn liters(value: f64) -> Result<Self, GasError> {
58        validate_positive_finite(value, "volume")?;
59        Ok(Self(value / 1_000.0))
60    }
61
62    /// Returns volume in cubic meters.
63    pub const fn as_cubic_meters(self) -> f64 {
64        self.0
65    }
66
67    /// Returns volume in liters.
68    pub fn as_liters(self) -> f64 {
69        self.0 * 1_000.0
70    }
71}
72
73/// A finite, positive absolute temperature stored in kelvin.
74#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
75pub struct Temperature(f64);
76
77impl Temperature {
78    /// Creates an absolute temperature in kelvin.
79    pub fn kelvin(value: f64) -> Result<Self, GasError> {
80        validate_positive_finite(value, "absolute temperature")?;
81        Ok(Self(value))
82    }
83
84    /// Creates an absolute temperature from degrees Celsius.
85    pub fn celsius(value: f64) -> Result<Self, GasError> {
86        if !value.is_finite() {
87            return Err(GasError::NonFinite("temperature"));
88        }
89        let kelvin = value + 273.15;
90        validate_positive_finite(kelvin, "absolute temperature")?;
91        Ok(Self(kelvin))
92    }
93
94    /// Returns absolute temperature in kelvin.
95    pub const fn as_kelvin(self) -> f64 {
96        self.0
97    }
98
99    /// Returns temperature in degrees Celsius.
100    pub fn as_celsius(self) -> f64 {
101        self.0 - 273.15
102    }
103}
104
105/// A finite, positive amount of substance stored in moles.
106#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
107pub struct Amount(f64);
108
109impl Amount {
110    /// Creates an amount of substance in moles.
111    pub fn moles(value: f64) -> Result<Self, GasError> {
112        validate_positive_finite(value, "amount")?;
113        Ok(Self(value))
114    }
115
116    /// Returns amount of substance in moles.
117    pub const fn as_moles(self) -> f64 {
118        self.0
119    }
120}
121
122/// A finite, non-negative volumetric flow stored in cubic meters per second.
123#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
124pub struct VolumetricFlow(f64);
125
126impl VolumetricFlow {
127    /// Creates a volumetric flow in cubic meters per second.
128    pub fn cubic_meters_per_second(value: f64) -> Result<Self, GasError> {
129        validate_non_negative_finite(value, "volumetric flow")?;
130        Ok(Self(value))
131    }
132
133    /// Returns volumetric flow in cubic meters per second.
134    pub const fn as_cubic_meters_per_second(self) -> f64 {
135        self.0
136    }
137}
138
139/// Pressure and temperature defining a gas reference condition.
140#[derive(Debug, Clone, Copy, PartialEq)]
141pub struct GasCondition {
142    pressure: Pressure,
143    temperature: Temperature,
144}
145
146impl GasCondition {
147    /// Creates a reference condition from absolute pressure and temperature.
148    pub const fn new(pressure: Pressure, temperature: Temperature) -> Self {
149        Self {
150            pressure,
151            temperature,
152        }
153    }
154
155    /// Returns absolute pressure.
156    pub const fn pressure(self) -> Pressure {
157        self.pressure
158    }
159
160    /// Returns absolute temperature.
161    pub const fn temperature(self) -> Temperature {
162        self.temperature
163    }
164}
165
166/// A complete equilibrium state satisfying the ideal gas equation.
167#[derive(Debug, Clone, Copy, PartialEq)]
168pub struct IdealGasState {
169    pressure: Pressure,
170    volume: Volume,
171    temperature: Temperature,
172    amount: Amount,
173}
174
175impl IdealGasState {
176    /// Derives amount from pressure, volume, and temperature.
177    pub fn from_pressure_volume_temperature(
178        pressure: Pressure,
179        volume: Volume,
180        temperature: Temperature,
181    ) -> Result<Self, GasError> {
182        let amount = Amount(checked(
183            pressure.0 * volume.0 / (MOLAR_GAS_CONSTANT * temperature.0),
184        )?);
185        Ok(Self {
186            pressure,
187            volume,
188            temperature,
189            amount,
190        })
191    }
192
193    /// Derives pressure from amount, volume, and temperature.
194    pub fn from_amount_volume_temperature(
195        amount: Amount,
196        volume: Volume,
197        temperature: Temperature,
198    ) -> Result<Self, GasError> {
199        let pressure = Pressure(checked(
200            amount.0 * MOLAR_GAS_CONSTANT * temperature.0 / volume.0,
201        )?);
202        Ok(Self {
203            pressure,
204            volume,
205            temperature,
206            amount,
207        })
208    }
209
210    /// Derives volume from pressure, amount, and temperature.
211    pub fn from_pressure_amount_temperature(
212        pressure: Pressure,
213        amount: Amount,
214        temperature: Temperature,
215    ) -> Result<Self, GasError> {
216        let volume = Volume(checked(
217            amount.0 * MOLAR_GAS_CONSTANT * temperature.0 / pressure.0,
218        )?);
219        Ok(Self {
220            pressure,
221            volume,
222            temperature,
223            amount,
224        })
225    }
226
227    /// Derives temperature from pressure, volume, and amount.
228    pub fn from_pressure_volume_amount(
229        pressure: Pressure,
230        volume: Volume,
231        amount: Amount,
232    ) -> Result<Self, GasError> {
233        let temperature = Temperature(checked(
234            pressure.0 * volume.0 / (amount.0 * MOLAR_GAS_CONSTANT),
235        )?);
236        Ok(Self {
237            pressure,
238            volume,
239            temperature,
240            amount,
241        })
242    }
243
244    /// Returns absolute pressure.
245    pub const fn pressure(self) -> Pressure {
246        self.pressure
247    }
248
249    /// Returns volume.
250    pub const fn volume(self) -> Volume {
251        self.volume
252    }
253
254    /// Returns absolute temperature.
255    pub const fn temperature(self) -> Temperature {
256        self.temperature
257    }
258
259    /// Returns amount of substance.
260    pub const fn amount(self) -> Amount {
261        self.amount
262    }
263}
264
265/// Converts an ideal-gas volume between pressure and temperature conditions.
266pub fn convert_volume(
267    volume: Volume,
268    from: GasCondition,
269    to: GasCondition,
270) -> Result<Volume, GasError> {
271    let converted =
272        volume.0 * from.pressure.0 / to.pressure.0 * to.temperature.0 / from.temperature.0;
273    Ok(Volume(checked(converted)?))
274}
275
276/// Converts ideal-gas volumetric flow between pressure and temperature conditions.
277pub fn convert_flow(
278    flow: VolumetricFlow,
279    from: GasCondition,
280    to: GasCondition,
281) -> Result<VolumetricFlow, GasError> {
282    let converted =
283        flow.0 * from.pressure.0 / to.pressure.0 * to.temperature.0 / from.temperature.0;
284    ensure_finite(converted)?;
285    Ok(VolumetricFlow(converted))
286}
287
288/// Invalid quantity or a result outside finite positive numeric range.
289#[derive(Debug, Clone, PartialEq, Eq)]
290pub enum GasError {
291    /// A named input was not finite.
292    NonFinite(&'static str),
293    /// A named input was negative.
294    Negative(&'static str),
295    /// A named input had to be positive but was zero.
296    Zero(&'static str),
297    /// Arithmetic produced a non-finite or non-positive derived state.
298    CalculationOutOfRange,
299}
300
301impl fmt::Display for GasError {
302    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
303        match self {
304            Self::NonFinite(name) => write!(formatter, "{name} must be finite"),
305            Self::Negative(name) => write!(formatter, "{name} must not be negative"),
306            Self::Zero(name) => write!(formatter, "{name} must be greater than zero"),
307            Self::CalculationOutOfRange => {
308                formatter.write_str("calculation produced an out-of-range result")
309            }
310        }
311    }
312}
313
314impl Error for GasError {}
315
316fn validate_non_negative_finite(value: f64, name: &'static str) -> Result<(), GasError> {
317    if !value.is_finite() {
318        return Err(GasError::NonFinite(name));
319    }
320    if value < 0.0 {
321        return Err(GasError::Negative(name));
322    }
323    Ok(())
324}
325
326fn validate_positive_finite(value: f64, name: &'static str) -> Result<(), GasError> {
327    validate_non_negative_finite(value, name)?;
328    if value == 0.0 {
329        return Err(GasError::Zero(name));
330    }
331    Ok(())
332}
333
334fn ensure_finite(value: f64) -> Result<(), GasError> {
335    if value.is_finite() {
336        Ok(())
337    } else {
338        Err(GasError::CalculationOutOfRange)
339    }
340}
341
342fn checked(value: f64) -> Result<f64, GasError> {
343    if value.is_finite() && value > 0.0 {
344        Ok(value)
345    } else {
346        Err(GasError::CalculationOutOfRange)
347    }
348}
349
350#[cfg(test)]
351mod tests {
352    use super::*;
353
354    fn pressure(value: f64) -> Pressure {
355        Pressure::pascals(value).unwrap()
356    }
357
358    fn volume(value: f64) -> Volume {
359        Volume::cubic_meters(value).unwrap()
360    }
361
362    fn temperature(value: f64) -> Temperature {
363        Temperature::kelvin(value).unwrap()
364    }
365
366    #[test]
367    fn derives_each_ideal_gas_variable() {
368        let p = pressure(100_000.0);
369        let t = temperature(300.0);
370        let n = Amount::moles(1.0).unwrap();
371        let v = volume(MOLAR_GAS_CONSTANT * 300.0 / 100_000.0);
372
373        let by_amount = IdealGasState::from_pressure_volume_temperature(p, v, t).unwrap();
374        let by_pressure = IdealGasState::from_amount_volume_temperature(n, v, t).unwrap();
375        let by_volume = IdealGasState::from_pressure_amount_temperature(p, n, t).unwrap();
376        let by_temperature = IdealGasState::from_pressure_volume_amount(p, v, n).unwrap();
377
378        assert!((by_amount.amount().0 - 1.0).abs() < 1e-12);
379        assert!((by_pressure.pressure().0 - p.0).abs() < 1e-9);
380        assert!((by_volume.volume().0 - v.0).abs() < 1e-15);
381        assert!((by_temperature.temperature().0 - t.0).abs() < 1e-12);
382    }
383
384    #[test]
385    fn pressure_conversion_is_explicit() {
386        let pressure = Pressure::kilopascals(101.325).unwrap();
387        assert!((pressure.as_pascals() - 101_325.0).abs() < 1e-10);
388        assert_eq!(pressure.as_kilopascals(), 101.325);
389    }
390
391    #[test]
392    fn celsius_is_stored_as_kelvin() {
393        let temperature = Temperature::celsius(26.85).unwrap();
394        assert!((temperature.as_kelvin() - 300.0).abs() < 1e-12);
395        assert!((temperature.as_celsius() - 26.85).abs() < 1e-12);
396    }
397
398    #[test]
399    fn pressure_change_converts_volume() {
400        let from = GasCondition::new(pressure(100_000.0), temperature(300.0));
401        let to = GasCondition::new(pressure(200_000.0), temperature(300.0));
402        let converted = convert_volume(volume(1.0), from, to).unwrap();
403        assert!((converted.0 - 0.5).abs() < 1e-12);
404    }
405
406    #[test]
407    fn temperature_change_converts_flow() {
408        let from = GasCondition::new(pressure(100_000.0), temperature(300.0));
409        let to = GasCondition::new(pressure(100_000.0), temperature(600.0));
410        let flow = VolumetricFlow::cubic_meters_per_second(0.25).unwrap();
411        let converted = convert_flow(flow, from, to).unwrap();
412        assert!((converted.0 - 0.5).abs() < 1e-12);
413    }
414
415    #[test]
416    fn zero_flow_remains_zero() {
417        let condition = GasCondition::new(pressure(100_000.0), temperature(300.0));
418        let flow = VolumetricFlow::cubic_meters_per_second(0.0).unwrap();
419        assert_eq!(convert_flow(flow, condition, condition).unwrap().0, 0.0);
420    }
421
422    #[test]
423    fn invalid_quantities_are_rejected() {
424        assert_eq!(
425            Pressure::pascals(0.0),
426            Err(GasError::Zero("absolute pressure"))
427        );
428        assert_eq!(Volume::liters(-1.0), Err(GasError::Negative("volume")));
429        assert_eq!(
430            Temperature::kelvin(f64::NAN),
431            Err(GasError::NonFinite("absolute temperature"))
432        );
433        assert_eq!(
434            Temperature::celsius(-273.15),
435            Err(GasError::Zero("absolute temperature"))
436        );
437        assert_eq!(Amount::moles(0.0), Err(GasError::Zero("amount")));
438    }
439
440    #[test]
441    fn calculation_overflow_is_reported() {
442        let result = IdealGasState::from_amount_volume_temperature(
443            Amount::moles(f64::MAX).unwrap(),
444            volume(f64::MIN_POSITIVE),
445            temperature(300.0),
446        );
447        assert_eq!(result, Err(GasError::CalculationOutOfRange));
448    }
449}