Documentation hard-sphere contributions

.github/workflows/test.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        crate: [feos-core, feos-dft, feos-saft]
+        crate: [feos-core, feos-dft]
     steps:
       - uses: actions/checkout@v3
       - name: Build

Cargo.toml

@@ -16,7 +16,7 @@ categories = ["science"]
 features = ["all_models"]
 
 [workspace]
-members = ["feos-core", "feos-dft", "feos-saft"]
+members = ["feos-core", "feos-dft"]
 
 [lib]
 crate-type = ["rlib", "cdylib"]
@@ -26,7 +26,6 @@ quantity = "0.5"
 num-dual = "0.5"
 feos-core = { version = "0.3", path = "feos-core" }
 feos-dft = { version = "0.3", path = "feos-dft", optional = true }
-feos-saft = { version = "0.1", path = "feos-saft", optional = true }
 numpy = { version = "0.16", optional = true }
 ndarray = { version = "0.15", features = ["approx"] }
 petgraph = { version = "0.6", optional = true }
@@ -48,11 +47,12 @@ approx = "0.4"
 
 [features]
 default = []
-dft = ["feos-dft", "petgraph", "feos-saft?/dft"]
+dft = ["feos-dft", "petgraph"]
 estimator = []
-pcsaft = ["feos-saft/association"]
-gc_pcsaft = ["feos-saft/association"]
+association = []
+pcsaft = ["association"]
+gc_pcsaft = ["association"]
 uvtheory = ["lazy_static"]
-pets = ["feos-saft"]
-python = ["pyo3", "numpy", "feos-core/python", "feos-dft?/python", "feos-saft?/python"]
+pets = []
+python = ["pyo3", "numpy", "feos-core/python", "feos-dft?/python"]
 all_models = ["dft", "estimator", "pcsaft", "gc_pcsaft", "uvtheory", "pets"]

feos-saft/src/association/dft.rs → src/association/dft.rs

@@ -1,5 +1,5 @@
 use super::*;
-use crate::HardSphereProperties;
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::EosResult;
 use feos_dft::{
     FunctionalContributionDual, WeightFunction, WeightFunctionInfo, WeightFunctionShape,

feos-saft/src/association/mod.rs → src/association/mod.rs

@@ -1,6 +1,6 @@
 //! Generic implementation of the SAFT association contribution
 //! that can be used across models.
-use crate::HardSphereProperties;
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::{EosError, HelmholtzEnergyDual, StateHD};
 use ndarray::*;
 use num_dual::linalg::{norm, LU};
@@ -385,7 +385,8 @@ mod tests_pcsaft {
 
     #[test]
     fn helmholtz_energy() {
-        let assoc = Association::new(&Rc::new(water_parameters()), 50, 1e-10);
+        let params = Rc::new(water_parameters());
+        let assoc = Association::new(&params, &params.association, 50, 1e-10);
         let t = 350.0;
         let v = 41.248289328513216;
         let n = 1.23;
@@ -396,7 +397,8 @@ mod tests_pcsaft {
 
     #[test]
     fn helmholtz_energy_cross() {
-        let assoc = Association::new_cross_association(&Rc::new(water_parameters()), 50, 1e-10);
+        let params = Rc::new(water_parameters());
+        let assoc = Association::new_cross_association(&params, &params.association, 50, 1e-10);
         let t = 350.0;
         let v = 41.248289328513216;
         let n = 1.23;
@@ -419,8 +421,8 @@ mod tests_gc_pcsaft {
 
     #[test]
     fn test_assoc_propanol() {
-        let parameters = propanol();
-        let contrib = Association::new(&Rc::new(parameters), 50, 1e-10);
+        let params = Rc::new(propanol());
+        let contrib = Association::new(&params, &params.association, 50, 1e-10);
         let temperature = 300.0;
         let volume = METER
             .powi(3)
@@ -439,8 +441,8 @@ mod tests_gc_pcsaft {
 
     #[test]
     fn test_cross_assoc_propanol() {
-        let parameters = propanol();
-        let contrib = Association::new_cross_association(&Rc::new(parameters), 50, 1e-10);
+        let params = Rc::new(propanol());
+        let contrib = Association::new_cross_association(&params, &params.association, 50, 1e-10);
         let temperature = 300.0;
         let volume = METER
             .powi(3)
@@ -459,8 +461,8 @@ mod tests_gc_pcsaft {
 
     #[test]
     fn test_cross_assoc_ethanol_propanol() {
-        let parameters = ethanol_propanol(false);
-        let contrib = Association::new(&Rc::new(parameters), 50, 1e-10);
+        let params = Rc::new(ethanol_propanol(false));
+        let contrib = Association::new(&params, &params.association, 50, 1e-10);
         let temperature = 300.0;
         let volume = METER
             .powi(3)

feos-saft/src/association/python.rs → src/association/python.rs

@@ -3,11 +3,9 @@ use feos_core::impl_json_handling;
 use feos_core::parameter::ParameterError;
 use pyo3::prelude::*;
 
-/// Create a set of PC-Saft parameters from records.
+/// Pure component association parameters
 #[pyclass(name = "AssociationRecord", unsendable)]
-#[pyo3(
-    text_signature = "(m, sigma, epsilon_k, mu=None, q=None, kappa_ab=None, epsilon_k_ab=None, na=None, nb=None, viscosity=None, diffusion=None, thermal_conductivity=None)"
-)]
+#[pyo3(text_signature = "(kappa_ab, epsilon_k_ab, na, nb)")]
 #[derive(Clone)]
 pub struct PyAssociationRecord(pub AssociationRecord);
 

src/gc_pcsaft/dft/dispersion.rs

@@ -1,10 +1,10 @@
 use super::parameter::GcPcSaftFunctionalParameters;
 use crate::gc_pcsaft::eos::dispersion::{A0, A1, A2, B0, B1, B2};
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::EosError;
 use feos_dft::{
     FunctionalContributionDual, WeightFunction, WeightFunctionInfo, WeightFunctionShape,
 };
-use feos_saft::HardSphereProperties;
 use ndarray::*;
 use num_dual::DualNum;
 use std::f64::consts::{FRAC_PI_6, PI};

src/gc_pcsaft/dft/hard_chain.rs

@@ -1,9 +1,9 @@
 use super::GcPcSaftFunctionalParameters;
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::EosError;
 use feos_dft::{
     FunctionalContributionDual, WeightFunction, WeightFunctionInfo, WeightFunctionShape,
 };
-use feos_saft::HardSphereProperties;
 use ndarray::*;
 use num_dual::DualNum;
 use petgraph::visit::EdgeRef;

src/gc_pcsaft/dft/mod.rs

@@ -1,9 +1,10 @@
 use super::eos::GcPcSaftOptions;
+use crate::association::Association;
+use crate::hard_sphere::{FMTContribution, FMTVersion, HardSphereProperties, MonomerShape};
 use feos_core::parameter::ParameterHetero;
 use feos_core::MolarWeight;
 use feos_dft::adsorption::FluidParameters;
 use feos_dft::{FunctionalContribution, HelmholtzEnergyFunctional, MoleculeShape, DFT};
-use feos_saft::{Association, FMTContribution, FMTVersion, HardSphereProperties, MonomerShape};
 use ndarray::Array1;
 use num_dual::DualNum;
 use petgraph::graph::UnGraph;

src/gc_pcsaft/dft/parameter.rs

@@ -1,9 +1,9 @@
+use crate::association::AssociationParameters;
 use crate::gc_pcsaft::record::GcPcSaftRecord;
 use feos_core::joback::JobackRecord;
 use feos_core::parameter::{
     BinaryRecord, ChemicalRecord, ParameterError, ParameterHetero, SegmentRecord,
 };
-use feos_saft::AssociationParameters;
 use indexmap::IndexMap;
 use ndarray::{Array1, Array2};
 use petgraph::dot::{Config, Dot};

src/gc_pcsaft/eos/dispersion.rs

@@ -1,6 +1,6 @@
 use super::GcPcSaftEosParameters;
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::{HelmholtzEnergyDual, StateHD};
-use feos_saft::HardSphereProperties;
 use num_dual::DualNum;
 use std::f64::consts::PI;
 use std::fmt;

src/gc_pcsaft/eos/hard_chain.rs

@@ -1,6 +1,6 @@
 use super::GcPcSaftEosParameters;
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::{HelmholtzEnergyDual, StateHD};
-use feos_saft::HardSphereProperties;
 use num_dual::*;
 use std::fmt;
 use std::rc::Rc;

src/gc_pcsaft/eos/mod.rs

@@ -1,7 +1,8 @@
+use crate::association::Association;
+use crate::hard_sphere::HardSphere;
 use feos_core::joback::Joback;
 use feos_core::parameter::ParameterHetero;
 use feos_core::{EquationOfState, HelmholtzEnergy, IdealGasContribution, MolarWeight};
-use feos_saft::{Association, HardSphere};
 use ndarray::Array1;
 use quantity::si::*;
 use std::f64::consts::FRAC_PI_6;

src/gc_pcsaft/eos/parameter.rs

@@ -1,10 +1,11 @@
+use crate::association::AssociationParameters;
 use crate::gc_pcsaft::record::GcPcSaftRecord;
+use crate::hard_sphere::{HardSphereProperties, MonomerShape};
 use feos_core::joback::JobackRecord;
 use feos_core::parameter::{
     BinaryRecord, ChemicalRecord, FromSegments, Identifier, ParameterError, ParameterHetero,
     SegmentCount, SegmentRecord,
 };
-use feos_saft::{AssociationParameters, HardSphereProperties, MonomerShape};
 use indexmap::IndexMap;
 use ndarray::{Array1, Array2};
 use num_dual::DualNum;
@@ -395,8 +396,8 @@ impl std::fmt::Display for GcPcSaftEosParameters {
 #[cfg(test)]
 pub mod test {
     use super::*;
+    use crate::association::AssociationRecord;
     use feos_core::parameter::{ChemicalRecord, Identifier};
-    use feos_saft::AssociationRecord;
 
     fn ch3() -> SegmentRecord<GcPcSaftRecord, JobackRecord> {
         SegmentRecord::new(

src/gc_pcsaft/eos/polar.rs

@@ -1,6 +1,6 @@
 use super::GcPcSaftEosParameters;
+use crate::hard_sphere::HardSphereProperties;
 use feos_core::{HelmholtzEnergyDual, StateHD};
-use feos_saft::HardSphereProperties;
 use ndarray::prelude::*;
 use num_dual::DualNum;
 use std::f64::consts::{FRAC_PI_3, PI};

src/gc_pcsaft/python/mod.rs

@@ -2,14 +2,14 @@
 use super::dft::GcPcSaftFunctionalParameters;
 use super::eos::GcPcSaftEosParameters;
 use super::record::GcPcSaftRecord;
+use crate::association::PyAssociationRecord;
 use feos_core::joback::JobackRecord;
 use feos_core::parameter::{
     BinaryRecord, IdentifierOption, ParameterError, ParameterHetero, SegmentRecord,
 };
 use feos_core::python::joback::PyJobackRecord;
 use feos_core::python::parameter::{PyBinarySegmentRecord, PyChemicalRecord, PyIdentifier};
 use feos_core::{impl_json_handling, impl_parameter_from_segments, impl_segment_record};
-use feos_saft::PyAssociationRecord;
 #[cfg(feature = "dft")]
 use numpy::{PyArray2, ToPyArray};
 use pyo3::prelude::*;

src/gc_pcsaft/record.rs

@@ -1,4 +1,4 @@
-use feos_saft::AssociationRecord;
+use crate::association::AssociationRecord;
 use serde::{Deserialize, Serialize};
 
 /// gc-PC-SAFT pure-component parameters.

feos-saft/src/hard_sphere/dft.rs → src/hard_sphere/dft.rs

@@ -1,4 +1,3 @@
-//! Helmholtz energy functionals from fundamental measure theory.
 use feos_core::EosResult;
 use feos_dft::adsorption::FluidParameters;
 use feos_dft::solvation::PairPotential;
@@ -12,12 +11,12 @@ use std::f64::consts::PI;
 use std::fmt;
 use std::rc::Rc;
 
-use crate::{HardSphereProperties, MonomerShape};
+use super::{HardSphereProperties, MonomerShape};
 
 const PI36M1: f64 = 1.0 / (36.0 * PI);
 const N3_CUTOFF: f64 = 1e-5;
 
-/// Different versions of fundamental measure theory
+/// Different versions of fundamental measure theory.
 #[derive(Clone, Copy)]
 #[cfg_attr(feature = "python", pyo3::pyclass)]
 pub enum FMTVersion {
@@ -30,6 +29,38 @@ pub enum FMTVersion {
 }
 
 /// The [FunctionalContribution] for the hard sphere functional.
+///
+/// The struct provides an implementation of different variants of fundamental measure theory ([Rosenfeld, 1989](https://doi.org/10.1103/PhysRevLett.63.980)). Currently, only variants that are consistent with the BMCSL equation of state for hard-sphere mixtures are considered (exluding, e.g., the original Rosenfeld and White-Bear II variants).
+///
+/// The Helmholtz energy density is calculated according to
+/// $$\beta f=-n_0\ln\left(1-n_3\right)+\frac{n_{12}}{1-n_3}+\frac{1}{36\pi}n_2n_{22}f_3(n_3)$$
+/// The expressions for $n_{12}$ and $n_{22}$ depend on the [FMTVersion].
+///
+/// |[FMTVersion]|$n_{12}$|$n_{22}$|
+/// |-|:-:|:-:|
+/// |WhiteBear|$n_1n_2-\vec n_1\cdot\vec n_2$|$n_2^2-3\vec n_2\cdot\vec n_2$|
+/// |KierlikRosinberg|$n_1n_2$|$n_2^2$|
+/// |AntiSymWhiteBear|$n_1n_2-\vec n_1\cdot\vec n_2$|$n_2^2\left(1-\frac{\vec n_2\cdot\vec n_2}{n_2^2}\right)^3$|
+///
+/// The value of $f(n_3)$ numerically diverges for small $n_3$. Therefore, it is approximated with a Taylor expansion.
+/// $$f_3=\begin{cases}\frac{n_3+\left(1-n_3\right)^2\ln\left(1-n_3\right)}{n_3^2\left(1-n_3\right)^2}&\text{if }n_3>10^{-5}\\\\
+/// \frac{3}{2}+\frac{8}{3}n_3+\frac{15}{4}n_3^2+\frac{24}{5}n_3^3+\frac{35}{6}n_3^4&\text{else}\end{cases}$$
+///
+/// The weighted densities $n_k(\mathbf{r})$ are calculated by convolving the density profiles $\rho_\alpha(\mathbf{r})$ with weight functions $\omega_k^\alpha(\mathbf{r})$
+/// $$n_k(\mathbf{r})=\sum_\alpha\int\rho_\alpha(\mathbf{r}\')\omega_k^\alpha(\mathbf{r}-\mathbf{r}\')\mathrm{d}\mathbf{r}\'$$
+///
+/// The weight functions differ between the different [FMTVersion]s.
+///
+/// ||WhiteBear/AntiSymWhiteBear|KierlikRosinberg|
+/// |-|:-:|:-:|
+/// |$\omega_0^\alpha(\mathbf{r})$|$\frac{C_{0,\alpha}}{\pi\sigma_\alpha^2}\\,\delta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|$C_{0,\alpha}\left(-\frac{1}{8\pi}\\,\delta\'\'\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)+\frac{1}{2\pi\|\mathbf{r}\|}\\,\delta\'\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)\right)$|
+/// |$\omega_1^\alpha(\mathbf{r})$|$\frac{C_{1,\alpha}}{2\pi\sigma_\alpha}\\,\delta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|$\frac{C_{1,\alpha}}{8\pi}\\,\delta\'\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|
+/// |$\omega_2^\alpha(\mathbf{r})$|$C_{2,\alpha}\\,\delta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|$C_{2,\alpha}\\,\delta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|
+/// |$\omega_3^\alpha(\mathbf{r})$|$C_{3,\alpha}\\,\Theta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|$C_{3,\alpha}\\,\Theta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|
+/// |$\vec\omega_1^\alpha(\mathbf{r})$|$C_{3,\alpha}\frac{\mathbf{r}}{2\pi\sigma_\alpha\|\mathbf{r}\|}\\,\delta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|-|
+/// |$\vec\omega_2^\alpha(\mathbf{r})$|$C_{3,\alpha}\frac{\mathbf{r}}{\|\mathbf{r}\|}\\,\delta\\!\left(\frac{d_\alpha}{2}-\|\mathbf{r}\|\right)$|-|
+///
+/// The geometry coefficients $C_{k,\alpha}$ and the segment diameters $d_\alpha$ are specified via the [HardSphereProperties] trait.
 pub struct FMTContribution<P> {
     pub properties: Rc<P>,
     version: FMTVersion,