adding final docstrings to feos-core

feos-org · g-bauer · Oct 13, 2025 · Aug 18, 2025 · Aug 18, 2025 · Aug 18, 2025
commit 898c9177a54d10da559d895709eb753628a31542
diff --git a/crates/feos-core/src/equation_of_state/mod.rs b/crates/feos-core/src/equation_of_state/mod.rs
@@ -124,6 +124,7 @@ pub trait IdealGas<D = f64> {
     fn ideal_gas_model(&self) -> &'static str;
 }
 
+/// A total Helmholtz energy model consisting of a [Residual] model and an [IdealGas] part.
 pub trait Total<N: Dim = Dyn, D: DualNum<f64> + Copy = f64>: Residual<N, D>
 where
     DefaultAllocator: Allocator<N>,

diff --git a/crates/feos-core/src/equation_of_state/residual.rs b/crates/feos-core/src/equation_of_state/residual.rs
@@ -27,6 +27,7 @@ where
     }
 }
 
+/// A model from which models for subsets of its components can be extracted.
 pub trait Subset {
     /// Return a model consisting of the components
     /// contained in component_list.

diff --git a/crates/feos-core/src/lib.rs b/crates/feos-core/src/lib.rs
@@ -37,7 +37,7 @@ pub use equation_of_state::{
     EquationOfState, IdealGas, Molarweight, NoResidual, Residual, ResidualDyn, Subset, Total,
 };
 pub use errors::{FeosError, FeosResult};
-pub use parameter_fit::{Estimator, ParametersAD};
+pub use parameter_fit::{ParameterFit, ParametersAD};
 #[cfg(feature = "ndarray")]
 pub use phase_equilibria::{PhaseDiagram, PhaseDiagramHetero};
 pub use phase_equilibria::{PhaseEquilibrium, TemperatureOrPressure};
@@ -133,6 +133,7 @@ const fn powi(x: f64, n: i32) -> f64 {
     }
 }
 
+/// Conversion between reduced units and SI units.
 pub trait ReferenceSystem {
     type Inner;
     type T: Integer;

diff --git a/crates/feos-core/src/parameter_fit/mod.rs b/crates/feos-core/src/parameter_fit/mod.rs
@@ -2,7 +2,7 @@ use nalgebra::{Const, U1};
 use num_dual::{Derivative, DualSVec};
 
 mod properties;
-pub use properties::Estimator;
+pub use properties::ParameterFit;
 
 use crate::Residual;
 

diff --git a/crates/feos-core/src/parameter_fit/properties.rs b/crates/feos-core/src/parameter_fit/properties.rs
@@ -15,9 +15,11 @@ use quantity::{Density, Pressure, Temperature};
 #[cfg(feature = "rayon")]
 use quantity::{KELVIN, KILO, METER, MOL, PASCAL};
 
-pub struct Estimator;
+/// A collection of functions that calculate fit properties and their derivatives
+/// with respect to model parameters.
+pub struct ParameterFit;
 
-impl Estimator {
+impl ParameterFit {
     pub fn vapor_pressure<E: Residual<U1, Gradient<P>>, const P: usize>(
         eos: &E,
         temperature: Temperature,

diff --git a/crates/feos/src/pcsaft/eos/mod.rs b/crates/feos/src/pcsaft/eos/mod.rs
@@ -654,7 +654,7 @@ mod tests_parameter_fit {
     use approx::assert_relative_eq;
     use feos_core::DensityInitialization::Liquid;
     use feos_core::{Contributions, ReferenceSystem};
-    use feos_core::{Estimator, FeosResult, ParametersAD, PhaseEquilibrium, State};
+    use feos_core::{FeosResult, ParameterFit, ParametersAD, PhaseEquilibrium, State};
     use nalgebra::{U1, U3, U8, vector};
     use num_dual::{DualStruct, DualVec};
     use quantity::{BAR, KELVIN, LITER, MOL, PASCAL};
@@ -683,7 +683,7 @@ mod tests_parameter_fit {
         let (pcsaft, _) = pcsaft()?;
         let pcsaft_ad = PcSaftPure::<_, 8>::from_parameter_slice(&pcsaft.0, pcsaft_params);
         let temperature = 250.0 * KELVIN;
-        let p = Estimator::vapor_pressure(&pcsaft_ad, temperature)?;
+        let p = ParameterFit::vapor_pressure(&pcsaft_ad, temperature)?;
         let p = p.convert_into(PASCAL);
         let (p, grad) = (p.re, p.eps.unwrap_generic(U8, U1));
 
@@ -716,7 +716,7 @@ mod tests_parameter_fit {
         let pcsaft_ad =
             PcSaftPure::<_, 4>::from_parameter_slice(&pcsaft.0, ["m", "sigma", "epsilon_k"]);
         let temperature = 150.0 * KELVIN;
-        let p = Estimator::vapor_pressure(&pcsaft_ad, temperature)?;
+        let p = ParameterFit::vapor_pressure(&pcsaft_ad, temperature)?;
         let p = p.convert_into(PASCAL);
         let (p, grad) = (p.re, p.eps.unwrap_generic(U3, U1));
 
@@ -749,7 +749,7 @@ mod tests_parameter_fit {
         let pcsaft_ad =
             PcSaftPure::<_, 4>::from_parameter_slice(&pcsaft.0, ["m", "sigma", "epsilon_k"]);
         let temperature = 150.0 * KELVIN;
-        let (p, rho) = Estimator::equilibrium_liquid_density(&pcsaft_ad, temperature)?;
+        let (p, rho) = ParameterFit::equilibrium_liquid_density(&pcsaft_ad, temperature)?;
         let p = p.convert_into(PASCAL);
         let rho = rho.convert_into(MOL / LITER);
         let (p, p_grad) = (p.re, p.eps.unwrap_generic(U3, U1));
@@ -791,7 +791,7 @@ mod tests_parameter_fit {
             PcSaftPure::<_, 4>::from_parameter_slice(&pcsaft.0, ["m", "sigma", "epsilon_k"]);
         let temperature = 150.0 * KELVIN;
         let pressure = BAR;
-        let rho = Estimator::liquid_density(&pcsaft_ad, temperature, pressure)?;
+        let rho = ParameterFit::liquid_density(&pcsaft_ad, temperature, pressure)?;
         let rho = rho.convert_into(MOL / LITER);
         let (rho, grad) = (rho.re, rho.eps.unwrap_generic(U3, U1));
 
@@ -830,7 +830,7 @@ mod tests_parameter_fit {
         let pcsaft_ad = pcsaft.named_derivatives(["k_ij"]);
         let temperature = 500.0 * KELVIN;
         let x = vector![0.5, 0.5];
-        let p = Estimator::bubble_point_pressure(&pcsaft_ad, temperature, None, x)?;
+        let p = ParameterFit::bubble_point_pressure(&pcsaft_ad, temperature, None, x)?;
         let p = p.convert_into(BAR);
         let (p, [[grad]]) = (p.re, p.eps.unwrap_generic(U1, U1).data.0);
 
@@ -868,7 +868,7 @@ mod tests_parameter_fit {
         let pcsaft_ad: PcSaftBinary<_, 8> = PcSaftBinary::named_derivatives(&pcsaft, ["k_ij"]);
         let temperature = 500.0 * KELVIN;
         let y = vector![0.5, 0.5];
-        let p = Estimator::dew_point_pressure(&pcsaft_ad, temperature, None, y)?;
+        let p = ParameterFit::dew_point_pressure(&pcsaft_ad, temperature, None, y)?;
         let p = p.convert_into(BAR);
         let (p, [[grad]]) = (p.re, p.eps.unwrap_generic(U1, U1).data.0);
 

diff --git a/py-feos/Cargo.toml b/py-feos/Cargo.toml
@@ -39,7 +39,7 @@ feos-derive = { workspace = true }
 feos-dft = { workspace = true, optional = true }
 
 [features]
-default = ["pcsaft"]
+default = []
 dft = ["feos/dft", "feos-dft", "petgraph", "rayon"]
 pcsaft = ["feos/pcsaft"]
 epcsaft = ["feos/epcsaft"]

diff --git a/py-feos/src/ad/mod.rs b/py-feos/src/ad/mod.rs
@@ -1,6 +1,6 @@
 #[cfg(feature = "pcsaft")]
 use feos::pcsaft::{PcSaftBinary, PcSaftPure};
-use feos_core::{Estimator, ParametersAD};
+use feos_core::{ParameterFit, ParametersAD};
 use numpy::{PyArray1, PyArray2, PyReadonlyArray2, ToPyArray};
 use paste::paste;
 use pyo3::prelude::*;
@@ -26,8 +26,8 @@ impl From<PyModel> for BinaryModels {
     }
 }
 
-#[pyclass(name = "Estimator")]
-pub struct PyEstimator;
+#[pyclass(name = "ParameterFit")]
+pub struct PyParameterFit;
 
 type GradResult<'py> = (
     Bound<'py, PyArray1<f64>>,
@@ -38,7 +38,7 @@ type GradResult<'py> = (
 macro_rules! expand_models {
     ($enum:ty, $prop:ident, $($model:ident: $type:ty),*) => {
         #[pymethods]
-        impl PyEstimator {
+        impl PyParameterFit {
             #[staticmethod]
             fn $prop<'py>(
                 model: PyModel,
@@ -79,9 +79,9 @@ macro_rules! impl_evaluate_gradients {
             let (value, grad, status) =
             $(
             if let Ok(p) = parameter_names.extract::<[String; $p]>() {
-                Estimator::[<$prop _parallel>]::<R, $p>(p, parameters.as_array(), input.as_array())
+                ParameterFit::[<$prop _parallel>]::<R, $p>(p, parameters.as_array(), input.as_array())
             } else)* if let Ok(p) = parameter_names.extract::<[String; $max]>() {
-                Estimator::[<$prop _parallel>]::<R, $max>(p, parameters.as_array(), input.as_array())
+                ParameterFit::[<$prop _parallel>]::<R, $max>(p, parameters.as_array(), input.as_array())
             } else {
                 panic!("Gradients can only be evaluated for up to {} parameters!", $max)
             };

diff --git a/py-feos/src/lib.rs b/py-feos/src/lib.rs
@@ -89,7 +89,7 @@ fn feos(m: &Bound<'_, PyModule>) -> PyResult<()> {
     // AD
     #[cfg(feature = "ad")]
     {
-        m.add_class::<ad::PyEstimator>()?;
+        m.add_class::<ad::PyParameterFit>()?;
         m.add_class::<ad::PyModel>()?;
     }