I would like to add a new model named cp-pcsaft

[fredj-jct]

What are the step to step procedure to add a new model named cp-pcsaft. How do I compiled it?

[g-bauer]

Hi,

since you are asking about compilation, I presume you want to implement the model in Rust? Here are the steps that get you started after forking the repository.

Install rust

You need the rust compiler to build the code. Follow the instructions here.

Copy existing equation of state as starting point

Equations of state are rust modules that live inside src. Since you want to build a SAFT-type EoS, src/pcsaft or src/saftvrmie are probably good starting points. Copy an existing directory and rename it appropriately. To import your module, you have to use it in src/lib.rs.

You can add a so-called feature for your new equation of state rust module using #[cfg(feature = "cppcsaft")] (see here). A feature allows you to only include specific pieces of the code during compilation. After adding a feature into your source code, you'll have to also add it to Cargo.toml (see here). Once you added your feature (for example cppcsaft), you can compile the code via

cargo build --features cppcsaft

If you can, reuse models/Helmholtz contributions that are already part of FeOs if they are compatible (see for example, src/hard_sphere).

Structure

There are two things that you'll have to think about when implementing a model. The calculation of the Helmholtz energy and how to handle its parameters. In our implementations, you'll usually find a parameters.rs file for the parameter structure and an eos directory where we implement the Helmholtz energy. Often, we split the calculation of the Helmholtz energy into contributions with each contribution sitting in a single file and then collect the contributions in one struct in eos/mod.rs.

An equation of state in FeOs has to implement several interfaces (rust traits). Here you can find the implementation for PC-SAFT. The most important function is the residual_helmholtz_energy_contributions function which returns a vector containing tuples of (name_of_contribution, helmholtz_energy) given the thermodynamic conditions. When you implement the residual_helmholtz_energy_contributions function, FeOs will add the contributions to evaluate the total Helmholtz energy. You only have to implement this function, not derivatives.

In general, you can structure the implementation of the Helmholtz energy as you wish - e.g. you could put all contributions into a single function. We usually have modules and structs for each contribution. For example, our PC-SAFT implementation defines dispersion, hard chains, and polar Helmholtz energy contributions. The folder and file structure can look like so

src/pcsaft
├── eos
│   ├── dispersion.rs # implements dispersive contribution
│   ├── hard_chain.rs # implements hard chain contribution
│   ├── mod.rs.  # implements the actual model by collecting the contributions in a struct
│   └── polar.rs # implements polar contributions
├── mod.rs # exports everything needed for the model    
└── parameters.rs.    # how to handle parameters

Parameters

You are completely free in the way you handle model parameters. If you use our implementations as example, you'll find that we assemble parameters from records. You can use this structure as well (it enables deriving some functionalities for automatic JSON parsing) or do a simple implementation first and then come back to these kinds of features later.

Tests

Before you expose your implementation to Python, I'd suggest implementing tests for contributions (and possibly intermediate properties needed) in rust. Here is an example for the tests of the PC-SAFT dispersion term where we used values from a prior implementation.

Expose equation of state and parameters to Python

Once everything is implemented and tested, you can expose the equation of state and parameters to Python. This is done by adding your model as variant here. After that, you'll have to define how your parameters and equation of state can be built from Python.

---

This is a very high level view on the steps needed. There are a lot of details I left out in each step - feel free to ask about specific issues as they appear. As said above, I'd start with copying an existing implementation of an equation of state, e.g. src/pcsaft. Then, delete what is not needed and implement your contributions copying the structure of our implementations.

If you already have a working/validated implementation in a different programming language, you can point me to it and I mighty be able to provide some support for bringing it over to rust. If there is an implementation, it is also extremely valuable to build tests for small code pieces and implement and test the whole model step by step.

Let us know if there any more questions.