Renamed and restructured benchmarks, added README for benchmarks, add…

…ed Cargo profile for LTO
feos-org · g-bauer · Dec 15, 2022 · Dec 7, 2022 · Dec 7, 2022 · Dec 13, 2022
commit 71c730b867bec0754117f5b90a45eb4783902600
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Added SAFT-VRQ Mie equation of state and Helmholtz energy functional for first order Feynman-Hibbs corrected Mie fluids. [#79](https://github.com/feos-org/feos/pull/79)
 - Added `estimator` module to documentation. [#86](https://github.com/feos-org/feos/pull/86)
+- Added benchmarks for the evaluation of the Helmholtz energy and some properties of the `State` object for PC-SAFT. [#89](https://github.com/feos-org/feos/pull/89)
 
 ### Changed
 - Export `EosVariant` and `FunctionalVariant` directly in the crate root instead of their own modules. [#62](https://github.com/feos-org/feos/pull/62)

diff --git a/Cargo.toml b/Cargo.toml
@@ -46,14 +46,14 @@ optional = true
 
 [dev-dependencies]
 approx = "0.4"
-criterion = "*"
+criterion = "0.4"
 
 [[bench]]
-name = "benchmarks"
+name = "state_properties"
 harness = false
 
 [[bench]]
-name = "biogas"
+name = "dual_numbers"
 harness = false
 
 [profile.release-lto]

diff --git a/README.md b/README.md
@@ -96,37 +96,52 @@ If there is no compiled package for your system available from PyPI and you have
 pip install git+https://github.com/feos-org/feos
 ```
 
+This command builds the package without link-time optimization (LTO) which results in considerably worse performance.
+See the *Building from source* section for information about building the wheel including LTO.
+
 ### Building from source
 
 To compile the code you need the Rust compiler and `maturin` (>=0.13,<0.14) installed.
-To install the package directly into the active environment, use
+To install the package directly into the active environment (virtualenv or conda), use
 
 ```
-maturin develop --release --features python
+maturin develop --release
 ```
 
-and specify the models that you want to include in the python package as additional features, e.g.
+which uses the `python` and `all_models` feature as specified in the `pyproject.toml` file.
+
+Alternatively, you can specify the models or features that you want to include in the python package explicitly, e.g.
 
 ```
 maturin develop --release --features "python pcsaft dft"
 ```
 
-for the PC-SAFT equation of state and Helmholtz energy functional. If you want to include all available models, use
+for the PC-SAFT equation of state and Helmholtz energy functional.
+
+To build wheels including link-time optimization (LTO), use
 
 ```
-maturin develop --release --features "python all_models"
+maturin build --profile="release-lto"
 ```
 
-To build wheels, use
+which will use the `python` and `all_models` features specified in the `pyproject.toml` file.
+Use the following command to build a wheel with specific features:
 
 ```
-maturin build --release --out dist --features "python ..."
+maturin build --profile="release-lto" --features "python ..."
 ```
 
+LTO increases compile times drastically but the resulting wheel is way more performant and has a smaller size.
+For development however, we recommend using the `--release` flag.
+
 ## Documentation
 
 For a documentation of the Python API, Python examples, and a guide to the underlying Rust framework check out the [documentation](https://feos-org.github.io/feos/).
 
+## Benchmarks
+
+Check out the [benches](https://github.com/feos-org/feos/tree/main/benches) directory for information about provided Rust benchmarks and how to run them.
+
 ## Developers
 
 This software is currently maintained by members of the groups of

diff --git a/benches/README.md b/benches/README.md
@@ -0,0 +1,16 @@
+# Benchmarks
+
+This directory contains different benchmarks.
+For best performance, use the `release-lto` profile.
+Depending on the benchmark, you might have to consider different Cargo `features` as denoted in the table below.
+
+For example, to run the benchmarks in `dual_numbers`, which uses PC-SAFT, use
+
+```
+cargo bench --profile=release-lto --features=pcsaft --bench=dual_numbers
+``` 
+
+|Name|Description|Cargo features|
+|--|--|--|
+|`dual_numbers`|Helmholtz energy function evaluated using `StateHD` with different dual number types. Substances: methane + carbon dioxide. Model: PC-SAFT incl. dipole-dipole contributions.|`pcsaft`|
+|`state_properties`|Properties of `State`. Including state creation using the natural variables of the Helmholtz energy (no density iteration). Substances: methane + ethane + propane. Model: PC-SAFT (hard-sphere, hard-chain, dispersion).|`pcsaft`|
diff --git a/benches/benchmarks.rs b/benches/benchmarks.rs