KiThe 0.3.9

A numerical suite for chemical kinetics and thermodynamics, combustion, heat and mass transfer,chemical equilibrium, chemical engeneering
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Canonical physical-state declarations used by thermodynamic lookup.
//!
//! A physical state is a request constraint for a library record, not a
//! thermodynamic activity model.  For example, a liquid record may later be
//! evaluated as a pure condensed phase or as part of a solution model.

/// Requested or observed physical state of a thermodynamic record.
///
/// `Condensed` is an intentionally coarse request meaning either liquid or
/// solid.  It is useful for legacy callers but does not make an ambiguous
/// liquid/solid lookup deterministic.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PhysicalState {
    Gas,
    Liquid,
    Solid,
    Condensed,
}

/// Policy controlling the optional live NIST lookup after local catalog
/// resolution has failed.
///
/// The exact-state variant is deliberately fail-closed: a request for a
/// liquid record may query NIST for liquid data, but it may never silently
/// accept a gas or solid record.  `LegacyGasDefault` exists only for the old
/// `SubsData` compatibility method and must not be used by new phase specs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum NistFallbackPolicy {
    /// Do not access the network and do not attempt NIST fallback.
    Disabled,
    /// Query NIST only when the component has an explicit physical-state
    /// requirement matching the requested phase.
    ExactRequestedState,
    /// Historical compatibility behavior: an unconstrained component is
    /// queried as a gas.  This is intentionally not the canonical phase API.
    LegacyGasDefault,
}

impl NistFallbackPolicy {
    /// Returns whether this policy can issue a network request.
    pub const fn enabled(self) -> bool {
        !matches!(self, Self::Disabled)
    }
}

impl PhysicalState {
    /// Returns whether an observed record state satisfies this request.
    pub const fn accepts(self, observed: Self) -> bool {
        matches!(
            (self, observed),
            (Self::Gas, Self::Gas)
                | (Self::Liquid, Self::Liquid)
                | (Self::Solid, Self::Solid)
                | (
                    Self::Condensed,
                    Self::Liquid | Self::Solid | Self::Condensed
                )
                | (Self::Liquid | Self::Solid, Self::Condensed)
        )
    }
}

/// Typed lookup request.  The string remains the canonical substance name
/// supplied by an application; state is deliberately a separate field.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ThermoRecordQuery {
    substance: String,
    physical_state: Option<PhysicalState>,
}

impl ThermoRecordQuery {
    pub fn new(substance: impl Into<String>) -> Self {
        Self {
            substance: substance.into(),
            physical_state: None,
        }
    }

    pub fn with_physical_state(mut self, physical_state: PhysicalState) -> Self {
        self.physical_state = Some(physical_state);
        self
    }

    pub fn with_physical_state_opt(mut self, physical_state: Option<PhysicalState>) -> Self {
        self.physical_state = physical_state;
        self
    }

    pub fn substance(&self) -> &str {
        &self.substance
    }

    pub const fn physical_state(&self) -> Option<PhysicalState> {
        self.physical_state
    }
}

/// Why a record was classified as belonging to a physical state.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PhysicalStateEvidence {
    /// The state is encoded in this library family's record key convention.
    KeyConvention,
    /// The library family represents one physical state unless a key says otherwise.
    LibraryDefault,
}

#[cfg(test)]
mod tests {
    use super::{NistFallbackPolicy, PhysicalState};

    #[test]
    fn exact_state_policy_is_the_only_non_legacy_enabled_choice() {
        assert!(!NistFallbackPolicy::Disabled.enabled());
        assert!(NistFallbackPolicy::ExactRequestedState.enabled());
        assert!(NistFallbackPolicy::LegacyGasDefault.enabled());
    }

    #[test]
    fn physical_state_acceptance_does_not_widen_liquid_or_solid_requests() {
        assert!(PhysicalState::Liquid.accepts(PhysicalState::Liquid));
        assert!(!PhysicalState::Liquid.accepts(PhysicalState::Gas));
        assert!(PhysicalState::Solid.accepts(PhysicalState::Solid));
        assert!(!PhysicalState::Solid.accepts(PhysicalState::Gas));
    }
}