Guide¶
Welcome to the \(\text{FeO}_\text{s}\) Rust guide. On the following pages we discuss the structure of the \(\text{FeO}_\text{s}\) project and how to use, compile and extend it.
Introduction¶
\(\text{FeO}_\text{s}\) is primarily developed on Linux but it is tested and runs on Linux, macOS and Windows. You need a Rust compiler to compile the code. For development, Visual Studio Code with the rust-analyzer plugin works pretty well, but you should use what you are comfortable in.
Prerequisites¶
If you are unfamiliar with Rust a good place to start is the Rust Programming Language Book. To start following our guide, you should understand the following topics:
how Rust projects, called crates, are structured (the module system),
data types and
structs
,the Rust ownership model,
enums
and pattern matching,traits,
With these foundations you should be able to follow the discussion. Eventually you’ll need to learn and understand
limitations of traits and trait objects,
smart pointers (
Rc
andBox
),and the
pyO3
crate if you are interested in the Python interface.
Project Structure¶
Some common functionalities of \(\text{FeO}_\text{s}\) are contained in separate workspace crates so that they can be used as standalone dependencies outside of \(\text{FeO}_\text{s}\). The most important ones are
feos-core
(core
for short): defines traits and structs for equations of state and implements thermodynamic states, phase equilibria and critical point routines.feos-dft
(dft
for short): builds oncore
and defines traits and structs for classical density functional theory and implements utilities to work with convolutions, external potentials, etc.
These crates offer abstractions for tasks that are common for all equations of state and Helmholtz energy functionals.
Using core
and dft
, the following implementations of equations of state and functionals are currently available:
pcsaft
: the PC-SAFT equation of state and Helmholtz energy functional.gc-pcsaft
: the hetero-segmented group contribution method of the PC-SAFT equation of state.uv-theory
: the equation of state based on uv-Theory.pets
: the PeTS equation of state and Helmholtz energy functional.
In addition to that, the hard_sphere
and assocation
modules contain implementations of the corresponding Helmholtz energy contributions that are used across multiple models.
To reduce compile times during development, every model is gated by its own feature
. Specific parts of the library can be built and tested by passing the corresponding feature flags to the Rust compiler.
Due to the particular treatment of procedural macros in Rust, an additional workspace crate feos-derive
provides procedural macros for the implementation of the EquationOfState
and HelmholtzEnergyFunctional
traits for enum
s used in FFIs like PyO3
.
Where to Get Help¶
\(\text{FeO}_\text{s}\) is openly developed on github. Each crate has it’s own github repository where you can use the discussion feature or file an issue.