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/*****************************************************************************************************************************************************************************************************/