Skip to main content

chemapp_rs/
lib.rs

1//! Unofficial Rust bindings and high-level workflows for the proprietary
2//! [ChemApp](https://gtt-technologies.de/software/chemapp/) thermochemical
3//! equilibrium library.
4//!
5//! ChemApp performs the thermodynamic calculations; this crate dynamically
6//! loads a separately obtained ChemApp DLL or shared library. No ChemApp
7//! binary, licence, or commercial thermodynamic database is distributed in
8//! the crates.io package.
9//!
10//! Most applications should start with [`Calculator`]. [`Engine`] exposes the
11//! lower-level, native-oriented `TQ...` interface when exact ChemApp control is
12//! required. Live entities reflect the current native state, while
13//! [`CalculatorSnapshot`] owns a result that remains usable after later native
14//! calls change that state.
15//!
16//! # Loading and inspecting a system
17//!
18//! ```no_run
19//! use chemapp_rs::{Calculator, ChemAppError};
20//!
21//! fn main() -> Result<(), ChemAppError> {
22//!     let calculator = Calculator::from_library(
23//!         "path/to/chemapp/library",
24//!         "path/to/system.dat",
25//!     )?;
26//!     println!("ChemApp version: {}", calculator.engine().tqvers()?);
27//!     for phase in calculator.phases()? {
28//!         println!("{}: {}", phase.name()?, phase.model()?);
29//!     }
30//!     Ok(())
31//! }
32//! ```
33//!
34//! ChemApp and the Rust process must have matching architectures. Native
35//! execution may also require a valid ChemApp licence. See the repository
36//! README for installation, examples, platform evidence, and troubleshooting.
37
38extern crate libloading;
39
40pub use crate::calculator::Calculator;
41pub use crate::entities::bond::{Bond, BondKind};
42pub use crate::entities::species::{Species, SpeciesRef};
43pub use crate::error::ChemAppError;
44pub use crate::interactions::{
45    Interaction, InteractionChannel, InteractionCrossCheck, InteractionCrossCheckRequest,
46    InteractionDescriptor, InteractionDescriptorCrossCheck, InteractionDescriptorRecovery,
47    InteractionDescriptorSource, InteractionMember, InteractionMutationSupport, InteractionOrder,
48    InteractionParameter, InteractionParameterAddress, InteractionParameterCell,
49    InteractionParameterRole, InteractionRaw, InteractionRecoveryReason,
50    InteractionRecoveryRequest, InteractionResolution, MagneticInteractionRole,
51    NativeInteractionIndex, NativePoweredMember, PhaseInteractionReport,
52    ResolvedInteractionDescriptor, ResolvedPoweredMember,
53};
54pub use crate::iterator::{
55    BondIterator, ConstituentIterator, PhaseIterator, SpeciesIterator, SystemComponentIterator,
56};
57pub use crate::native::Engine;
58pub use crate::snapshot::{CalculatorSnapshot, SnapshotOptions, StreamSnapshot};
59use std::fmt;
60
61mod abi;
62pub mod cache;
63pub mod calculator;
64pub mod defs;
65pub mod entities;
66pub mod error;
67pub mod interactions;
68pub mod iterator;
69pub mod native;
70pub mod parse;
71pub mod snapshot;
72mod table;
73
74/// The eleven dimensions returned by [`Engine::tqsize`] and [`Engine::tqused`].
75///
76/// `TQSIZE` reports compiled capacities; `TQUSED` reports the corresponding
77/// maxima required by the currently loaded system.
78#[derive(Clone, Default)]
79pub struct SystemDimensions {
80    /// `NA`: total phase constituents.
81    pub constituents: i32,
82    /// `NB`: system components.
83    pub system_components: i32,
84    /// `NC`: mixture phases.
85    pub mixture_phases: i32,
86    /// `ND`: excess Gibbs-energy coefficients for one mixture phase.
87    pub excess_gibbs_coefficients_per_phase: i32,
88    /// `NE`: excess magnetic coefficients for one mixture phase.
89    pub excess_magnetic_coefficients_per_phase: i32,
90    /// `NF`: sublattices for one mixture phase.
91    pub sublattices_per_phase: i32,
92    /// `NG`: constituents on one sublattice.
93    pub constituents_per_sublattice: i32,
94    /// `NH`: oxide constituents in one Gaye–Kapoor–Frohberg or modified
95    /// quasichemical phase.
96    pub gkf_mqm_oxide_constituents_per_phase: i32,
97    /// `NI`: Gibbs-energy/heat-capacity equations for one constituent and the
98    /// native leading dimension of the `TQGPAR` value array.
99    pub equations_per_constituent: i32,
100    /// `NJ`: total Gibbs-energy/heat-capacity equations.
101    pub equations: i32,
102    /// `NK`: constituents with pressure- and temperature-dependent molar volume.
103    pub pt_dependent_volume_constituents: i32,
104}
105
106impl SystemDimensions {
107    /// Returns an all-zero dimension set for FFI output initialization.
108    pub fn new() -> Self {
109        Self::default()
110    }
111}
112
113impl fmt::Debug for SystemDimensions {
114    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
115        writeln!(f, "SystemDimensions:")?;
116        writeln!(f, "  {:<44} {:?}", "Constituents (NA)", self.constituents)?;
117        writeln!(
118            f,
119            "  {:<44} {:?}",
120            "System components (NB)", self.system_components
121        )?;
122        writeln!(
123            f,
124            "  {:<44} {:?}",
125            "Mixture phases (NC)", self.mixture_phases
126        )?;
127        writeln!(
128            f,
129            "  {:<44} {:?}",
130            "Excess Gibbs coefficients / phase (ND)", self.excess_gibbs_coefficients_per_phase
131        )?;
132        writeln!(
133            f,
134            "  {:<44} {:?}",
135            "Excess magnetic coefficients / phase (NE)",
136            self.excess_magnetic_coefficients_per_phase
137        )?;
138        writeln!(
139            f,
140            "  {:<44} {:?}",
141            "Sublattices / phase (NF)", self.sublattices_per_phase
142        )?;
143        writeln!(
144            f,
145            "  {:<44} {:?}",
146            "Constituents / sublattice (NG)", self.constituents_per_sublattice
147        )?;
148        writeln!(
149            f,
150            "  {:<44} {:?}",
151            "GKF/MQM oxide constituents / phase (NH)", self.gkf_mqm_oxide_constituents_per_phase
152        )?;
153        writeln!(
154            f,
155            "  {:<44} {:?}",
156            "G/CP equations / constituent (NI)", self.equations_per_constituent
157        )?;
158        writeln!(f, "  {:<44} {:?}", "G/CP equations (NJ)", self.equations)?;
159        writeln!(
160            f,
161            "  {:<44} {:?}",
162            "P,T-dependent volume constituents (NK)", self.pt_dependent_volume_constituents
163        )?;
164        Ok(())
165    }
166}
167
168/*****************************************************************************************************************************************************************************************************/
169/*****************************************************************************************************************************************************************************************************/
170
171/// Licensing and provenance metadata returned from a transparent `.cst` file.
172#[derive(Clone)]
173pub struct TransparentHeader {
174    /// Transparent-file format version.
175    pub version: i32,
176    /// Program that wrote the file.
177    pub name_writing_program: String,
178    /// Three-part version of the writing program.
179    pub version_writing_program: [i32; 3],
180    /// Program permitted to read the file.
181    pub name_reading_program: String,
182    /// Minimum permitted three-part reading-program version.
183    pub minversion_reading_program: [i32; 3],
184    /// File creation date/time fields returned by ChemApp.
185    pub creation_date: [i32; 6],
186    /// File expiry date/time fields returned by ChemApp.
187    pub expiry_date: [i32; 6],
188    /// Allowed ChemApp user identifiers.
189    pub user_ids_allowed: String,
190    /// Allowed ChemApp licence-holder names.
191    pub license_holders_allowed: String,
192    /// File remark text.
193    pub remark: String,
194}
195
196impl fmt::Debug for TransparentHeader {
197    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
198        writeln!(f, "TransparentHeader:")?;
199        writeln!(f, "  {:<30} {:?}", "Version", self.version)?;
200        writeln!(
201            f,
202            "  {:<30} {:?}",
203            "Writing program name", self.name_writing_program
204        )?;
205        writeln!(
206            f,
207            "  {:<30} {:?}",
208            "Writing program version", self.version_writing_program
209        )?;
210        writeln!(
211            f,
212            "  {:<30} {:?}",
213            "Reading program name", self.name_reading_program
214        )?;
215        writeln!(
216            f,
217            "  {:<30} {:?}",
218            "Reading program min version", self.minversion_reading_program
219        )?;
220        writeln!(f, "  {:<30} {:?}", "Creation date", self.creation_date)?;
221        writeln!(f, "  {:<30} {:?}", "Expiration date", self.expiry_date)?;
222        writeln!(
223            f,
224            "  {:<30} {:?}",
225            "Allowed user ids", self.user_ids_allowed
226        )?;
227        writeln!(
228            f,
229            "  {:<30} {:?}",
230            "Allowed license holders", self.license_holders_allowed
231        )?;
232        writeln!(f, "  {:<30} {:?}", "Remark", self.remark)?;
233        Ok(())
234    }
235}
236
237/*****************************************************************************************************************************************************************************************************/
238/*****************************************************************************************************************************************************************************************************/