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 and Box),

  • 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 on core 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 enums 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.