Skip to content

models.md

Latest commit

 

History

History
555 lines (397 loc) · 18.8 KB

models.md

File metadata and controls

555 lines (397 loc) · 18.8 KB
Raw

Model reference

Every residual model is built as feos.EquationOfState.<model>(parameters, ...) from a feos.Parameters (or feos.GcParameters) object. Parameters is constructed from one or more feos.PureRecord(identifier, molarweight, **kwargs), where **kwargs is a flat dict of the model-specific fields documented below (see parameters.md for PureRecord/Identifier/binary loading mechanics, association sites, and the group-contribution loading helpers in general). Fields not listed for a given model raise an error at construction time (unknown/missing field).

Ideal-gas contributions (Joback, DIPPR) are not built with a standalone constructor: they are attached to an already-built residual EquationOfState via chainable instance methods (eos.dippr(...), eos.joback(...)), which mutate and return the same object. Each EquationOfState can only have one ideal-gas part set this way.

Several models also support classical DFT via feos.HelmholtzEnergyFunctional.<model>(...), which mirrors the EquationOfState constructor plus an fmt_version: feos.FMTVersion argument (WhiteBear (default), AntiSymWhiteBear, KierlikRosinberg). Only PC-SAFT, gc-PC-SAFT, PeTS, and SAFT-VRQ Mie support DFT (dir(feos.HelmholtzEnergyFunctional)), plus the standalone fmt hard-sphere functional (see the last section).

PC-SAFT

For non-polar, polar, and associating small molecules and chains.

Constructor

feos.EquationOfState.pcsaft(parameters, max_eta=0.5, max_iter_cross_assoc=50, tol_cross_assoc=1e-10, dq_variant="dq35")
  • dq_variant: "dq35" or "dq44" — combining rule used in the dipole/quadrupole term.

Parameters

kwarg unit required/optional meaning
m – required segment number
sigma Å required segment diameter
epsilon_k K required dispersion energy
mu Debye optional (0) dipole moment
q Debye·Å optional (0) quadrupole moment
viscosity – optional entropy-scaling coefficients, 4 floats
diffusion – optional entropy-scaling coefficients, 5 floats
thermal_conductivity – optional entropy-scaling coefficients, 4 floats

Association sites (kappa_ab, epsilon_k_ab, plus na/nb/nc site counts) are supported via the general association-site mechanism — see parameters.md.

Binary parameters

kwarg unit meaning
k_ij – binary dispersion interaction parameter

Example

import feos

ident = feos.Identifier(name="methane")
pr = feos.PureRecord(ident, 16.04, m=1.0, sigma=3.7, epsilon_k=150.0)
params = feos.Parameters.new_pure(pr)
eos = feos.EquationOfState.pcsaft(params)

ePC-SAFT

PC-SAFT extended for electrolyte solutions (ions dissolved in molecular solvents).

Constructor

feos.EquationOfState.epcsaft(parameters, max_eta=0.5, max_iter_cross_assoc=50, tol_cross_assoc=1e-10, epcsaft_variant="advanced")
  • epcsaft_variant: "advanced" or "revised". "revised" only supports a single solvent component (raises if nsolvent > 1).

Parameters

kwarg unit required/optional meaning
m – required segment number
sigma Å required segment diameter
epsilon_k K required dispersion energy
z – optional (0) ionic charge number; 0 marks a neutral solvent component
permittivity_record – required for solvent components (z=0) if any ionic species is present either {"PerturbationTheory": {"dipole_scaling", "polarizability_scaling", "correlation_integral_parameter"}} or {"ExperimentalData": {"data": [[T, permittivity], ...]}}

Association sites (kappa_ab, epsilon_k_ab) use the same general mechanism as PC-SAFT.

Binary parameters

kwarg unit meaning
k_ij – binary dispersion interaction parameter
k_ij_1, k_ij_2, k_ij_3 – temperature-dependent expansion coefficients for k_ij (all optional, default 0)

Example

import feos

water = feos.Identifier(name="water")
na = feos.Identifier(name="na+")
pr_water = feos.PureRecord(
    water, 18.015, m=1.2047, sigma=2.7927, epsilon_k=353.95,
    kappa_ab=0.04509, epsilon_k_ab=2425.7,
    permittivity_record={"PerturbationTheory": {
        "dipole_scaling": 5.199, "polarizability_scaling": 0.0,
        "correlation_integral_parameter": 0.1276,
    }},
)
pr_na = feos.PureRecord(na, 22.99, m=1.0, sigma=2.8232, epsilon_k=230.0, z=1)
params = feos.Parameters.new_binary([pr_water, pr_na], k_ij=0.0045)
eos = feos.EquationOfState.epcsaft(params)

gc-PC-SAFT

Heterosegmented group-contribution PC-SAFT — builds molecules from functional-group segments instead of per-molecule fitted parameters.

Constructor

feos.EquationOfState.gc_pcsaft(parameters, max_eta=0.5, max_iter_cross_assoc=50, tol_cross_assoc=1e-10)

parameters must be a feos.GcParameters (not a plain feos.Parameters) — build it with GcParameters.from_segments(chemical_records, segment_records, binary_segment_records=None), GcParameters.from_smiles(...), GcParameters.from_json_segments(...), or GcParameters.from_json_smiles(...); see parameters.md for the general group-contribution loading mechanism (ChemicalRecord, SegmentRecord, SMARTS fragmentation).

Parameters (per-segment, via SegmentRecord(identifier, molarweight, **kwargs))

kwarg unit required/optional meaning
m – required segment shape factor
sigma Å required segment diameter
epsilon_k K required dispersion energy
mu Debye optional (0) dipole moment
psi_dft – optional, DFT only interaction-range parameter for the dispersion functional

Association sites (kappa_ab, epsilon_k_ab) are supported per segment via the general association-site mechanism.

Binary parameters (per segment pair, via BinarySegmentRecord(id1, id2, **kwargs))

kwarg unit meaning
k_ij – binary dispersion interaction parameter between two segment types

Example

import feos

ident = feos.Identifier(name="propane")
chem = feos.ChemicalRecord(ident, ["CH3", "CH2", "CH3"])
ch3 = feos.SegmentRecord("CH3", 15.03, m=0.61198, sigma=3.7202, epsilon_k=229.9)
ch2 = feos.SegmentRecord("CH2", 14.03, m=0.45606, sigma=3.8900, epsilon_k=239.0)
gc_params = feos.GcParameters.from_segments([chem], [ch3, ch2])
eos = feos.EquationOfState.gc_pcsaft(gc_params)

PeTS

Perturbed truncated-and-shifted Lennard-Jones potential; simple non-polar, non-associating spherical molecules.

Constructor

feos.EquationOfState.pets(parameters, max_eta=0.5)

Parameters

kwarg unit required/optional meaning
sigma Å required segment diameter
epsilon_k K required dispersion energy

Binary parameters

kwarg unit meaning
k_ij – binary dispersion interaction parameter

Example

import feos

ident = feos.Identifier(name="argon")
pr = feos.PureRecord(ident, 39.948, sigma=3.4050, epsilon_k=119.8)
params = feos.Parameters.new_pure(pr)
eos = feos.EquationOfState.pets(params)

SAFT-VR Mie

Variable-range Mie-potential SAFT for non-polar, polar, and associating molecules, including chains, with more flexible repulsive/attractive exponents than PC-SAFT.

Constructor

feos.EquationOfState.saftvrmie(parameters, max_eta=0.5, max_iter_cross_assoc=50, tol_cross_assoc=1e-10)

Parameters

kwarg unit required/optional meaning
m – required segment number
sigma Å required segment diameter
epsilon_k K required dispersion energy
lr – required repulsive Mie exponent
la – required attractive Mie exponent

Association uses model-specific site parameters rc_ab (association-range radius parameter) and epsilon_k_ab (K, association energy), supplied through the general association-site mechanism.

Binary parameters

kwarg unit meaning
k_ij – correction to the binary dispersion energy (optional, default 0)
gamma_ij – correction to the binary repulsive exponent (optional, default 0)

Example

import feos

ident = feos.Identifier(name="methane")
pr = feos.PureRecord(ident, 16.04, m=1.0, sigma=3.7412, epsilon_k=153.36, lr=12.65, la=6.0)
params = feos.Parameters.new_pure(pr)
eos = feos.EquationOfState.saftvrmie(params)

SAFT-VRQ Mie

SAFT-VR Mie with a Feynman-Hibbs quantum correction, for light gases (H2, He, Ne, ...). Only single-segment (m = 1) molecules are supported.

Constructor

feos.EquationOfState.saftvrqmie(parameters, max_eta=0.5, inc_nonadd_term=True)
  • inc_nonadd_term: include the non-additive correction to the hard-sphere reference.

Parameters

kwarg unit required/optional meaning
m – required segment number (must be 1.0)
sigma Å required segment diameter
epsilon_k K required dispersion energy
lr – required repulsive Mie exponent
la – required attractive Mie exponent
fh – required Feynman-Hibbs order (integer, 1 or 2); cannot mix order 1 and 2 in the same mixture

Binary parameters

kwarg unit meaning
k_ij – correction to the binary dispersion energy
l_ij – correction to the binary diameter

Example

import feos

ident = feos.Identifier(name="hydrogen")
pr = feos.PureRecord(ident, 2.0157, m=1.0, sigma=3.0243, epsilon_k=26.706, lr=9.0, la=6.0, fh=1)
params = feos.Parameters.new_pure(pr)
eos = feos.EquationOfState.saftvrqmie(params)

UV-Theory

Perturbation theory for the Mie potential based directly on the pure-component u-v exponents, without the SAFT segment/chain formalism (spherical molecules only).

Constructor

feos.EquationOfState.uvtheory(parameters, max_eta=0.5, perturbation="WCA")
  • perturbation: "BH", "WCA", or "WCA_B3" — division type of the Mie potential used to compute the temperature-dependent hard-sphere diameter.

Parameters

kwarg unit required/optional meaning
rep – required repulsive Mie exponent
att – required attractive Mie exponent
sigma Å required segment diameter
epsilon_k K required dispersion energy

Binary parameters

The binary record is a bare scalar k_ij rather than a named-field record. As of feos 0.10.1 this cannot be set through Parameters.new_binary(pure_records, k_ij=...) — it raises invalid type: map, expected f64 — so binary mixtures currently only work with the default (no interaction correction, i.e. k_ij = 0):

params = feos.Parameters.new_binary([pr1, pr2])  # no binary correction

Example

import feos

ident = feos.Identifier(name="methane")
pr = feos.PureRecord(ident, 16.04, rep=12.0, att=6.0, sigma=3.7039, epsilon_k=150.03)
params = feos.Parameters.new_pure(pr)
eos = feos.EquationOfState.uvtheory(params)

Peng-Robinson

Classic cubic equation of state, for quick engineering-accuracy estimates.

Constructor

feos.EquationOfState.peng_robinson(parameters)

Parameters

kwarg unit required/optional meaning
tc K required critical temperature
pc Pa required critical pressure
acentric_factor – required acentric factor

Binary parameters

kwarg unit meaning
k_ij – binary interaction parameter

Example

import feos

ident = feos.Identifier(name="methane")
pr = feos.PureRecord(ident, 16.04, tc=190.6, pc=4.6e6, acentric_factor=0.011)
params = feos.Parameters.new_pure(pr)
eos = feos.EquationOfState.peng_robinson(params)

Multiparameter (reference equations of state)

High-precision, multi-term reference/multiparameter Helmholtz-energy equations of state (e.g. Span-Wagner-style correlations), covering both the residual and ideal-gas contributions jointly. Only pure components are supported (parameters.pure must have length 1).

Unlike the other models, the record (tc, rhoc, plus lists of residual and ideal-gas term specifications) is a large, low-level, functional-form-per-term description that is meant to be loaded from a published reference-EOS database file, not hand-authored. Build the Parameters with Parameters.from_json(...), Parameters.from_multiple_json(...), or Parameters.from_database(...) (see parameters.md), pointing at a JSON file that provides these fields for the substance(s) you need.

Constructor

feos.EquationOfState.multiparameter(parameters)

Returns a full equation of state (residual + ideal gas from the same record). To use only the ideal-gas part of a multiparameter record together with a different residual model (e.g. pair a reference ideal-gas correlation with a PC-SAFT residual), use the chainable instance method eos.multiparameter_ideal_gas(parameters) instead — analogous to .dippr()/.joback() below.

Parameters

field unit meaning
tc K critical temperature used to reduce the term expansions
rhoc mol/dm³ critical density used to reduce the term expansions
residual – list of residual Helmholtz-energy term specifications (database-defined)
ideal_gas – list of ideal-gas Helmholtz-energy term specifications (database-defined)

Example

This model has no hand-authored minimal example: pure_path must point at a reference-EOS JSON database providing tc/rhoc/residual/ideal_gas records for the requested substance (e.g. in the CoolProp-derived format), which is not part of a plain pip install feos. The call pattern is:

import feos

params = feos.Parameters.from_json(["water"], "path/to/multiparameter_database.json")
eos = feos.EquationOfState.multiparameter(params)

Ideal-gas-only equation of state

An equation of state with only an ideal-gas contribution (no residual part) — useful as a baseline or for testing.

Constructor

feos.EquationOfState.ideal_gas()

No parameters.

Example

import feos

eos = feos.EquationOfState.ideal_gas()

Joback ideal-gas heat capacity

Group-contribution correlation (Joback and Reid) for the ideal-gas isobaric heat capacity, attached to a residual model rather than constructed standalone.

Constructor

Instance method — chain onto an already-built residual EquationOfState:

eos = feos.EquationOfState.<residual model>(...).joback(joback_parameters)

joback_parameters must be a feos.GcParameters (built like gc-PC-SAFT's, but with Joback's fields on each SegmentRecord) — even for a single-segment "whole molecule" record.

Parameters (per segment, via SegmentRecord(identifier, molarweight, **kwargs))

kwarg unit required/optional meaning
a – required 0th-order heat-capacity polynomial coefficient
b – required 1st-order (T) coefficient
c – required 2nd-order (T²) coefficient
d – required 3rd-order (T³) coefficient
e – required 4th-order (T⁴) coefficient — not in the original 1987 publication but used by later parametrizations

Group contributions are combined additively (with fixed offsets a=-37.93, b=0.21, c=-3.91e-4, d=2.06e-7 baked into the combining rule) when built from multiple segments.

Example

import feos

ident = feos.Identifier(name="methane")
chem = feos.ChemicalRecord(ident, ["CH4"])
seg = feos.SegmentRecord("CH4", 16.04, a=1.0, b=2.0, c=3.0, d=4.0, e=5.0)
joback_params = feos.GcParameters.from_segments([chem], [seg])

pr_res = feos.PureRecord(ident, 16.04, tc=190.6, pc=4.6e6, acentric_factor=0.011)
eos = feos.EquationOfState.peng_robinson(feos.Parameters.new_pure(pr_res))
eos = eos.joback(joback_params)

DIPPR ideal-gas heat capacity

DIPPR-correlation ideal-gas isobaric heat capacity (equations #100, #107, #127), attached to a residual model rather than constructed standalone.

Constructor

Instance method — chain onto an already-built residual EquationOfState:

eos = feos.EquationOfState.<residual model>(...).dippr(dippr_parameters)

dippr_parameters is a plain feos.Parameters (built with Parameters.new_pure/new_binary, not GcParameters).

Parameters

Exactly one of the following externally-tagged variants per PureRecord (all use T in K and cp in J/kmol/K):

kwarg value shape meaning
DIPPR100 list of floats, any length polynomial: cp = A + B·T + C·T² + D·T³ + ...
DIPPR107 list of 5 floats [A, B, C, D, E] cp = A + B·[(C/T)/sinh(C/T)]² + D·[(E/T)/cosh(E/T)]²
DIPPR127 list of 7 floats [A, B, C, D, E, F, G] sum of three Einstein-like terms plus constant A

Example

import feos

ident = feos.Identifier(name="methane")
pr_res = feos.PureRecord(ident, 16.04, tc=190.6, pc=4.6e6, acentric_factor=0.011)
eos = feos.EquationOfState.peng_robinson(feos.Parameters.new_pure(pr_res))

pr_ig = feos.PureRecord(ident, 16.04, DIPPR107=[1.0, 2.0, 3.0, 4.0, 5.0])
dippr_params = feos.Parameters.new_pure(pr_ig)
eos = eos.dippr(dippr_params)

Python-defined models

feos.EquationOfState.python_residual(residual) and (instance method) eos.python_ideal_gas(ideal_gas) wrap a user-defined Python class implementing the required residual/ideal-gas methods, instead of a PureRecord-based model. There are no PureRecord fields to document here — the "parameters" are whatever the Python class exposes.

Classical DFT / Helmholtz energy functionals

feos.HelmholtzEnergyFunctional.<model>(parameters, fmt_version, ...) mirrors the EquationOfState constructor and parameters for PC-SAFT, gc-PC-SAFT, PeTS, and SAFT-VRQ Mie (same PureRecord/GcParameters fields as documented above), plus a required fmt_version positional argument selecting the free-energy functional variant used for the hard-sphere/FMT term: feos.FMTVersion.WhiteBear, .AntiSymWhiteBear, or .KierlikRosinberg (no default — always pass one explicitly).

In addition, there is a standalone hard-sphere-only functional that takes no PureRecord at all:

feos.HelmholtzEnergyFunctional.fmt(sigma, fmt_version)
  • sigma: numpy.ndarray[float] — hard-sphere diameters (Å), one per component.
  • fmt_version: feos.FMTVersion.

Example

import feos
import numpy as np

ident = feos.Identifier(name="methane")
pr = feos.PureRecord(ident, 16.04, m=1.0, sigma=3.7, epsilon_k=150.0)
params = feos.Parameters.new_pure(pr)
func = feos.HelmholtzEnergyFunctional.pcsaft(params, feos.FMTVersion.WhiteBear)

hs_func = feos.HelmholtzEnergyFunctional.fmt(np.array([3.7]), feos.FMTVersion.WhiteBear)