Working with parameters¶
Goal¶
Read in parameters for pure substances and mixtures from json files, and
create parameters for pure substances and mixtures within Python.
For both regular parameters as well as via the homo-segmented group contribution method.
Learn how to access information stored in parameter objects.
Parameters and the equation of state¶
Before we can start to compute physical properties, two steps are needed:
Build a parameter object.
Instatiate the equation of state using the parameter object.
In principle, every implementation of an equation of state can manage parameters differently but typically the workflow is similar for each implementation.
For pcsaft
we first generate the parameters object, PcSaftParameters
, which we then use to generate the equation of state object using EquationOfState.pcsaft()
. The PcSaftParameters
object is part of the feos.pcsaft
module while EquationOfState
is part of the feos.eos
module.
[1]:
from feos.pcsaft import *
Read parameters from json file(s)¶
The easiest way to create the PcSaftParameters
object is to read information from one or more json files.
To read information from a single file, use
PcSaftParameters.from_json
To read information from multiple files, use
PcSaftParameters.from_multiple_json
From a single file¶
Pure substance¶
Querying a substance from a file requires an identifier. This identifier can be one of Name
, Cas
, Inchi
, IupacName
, Formula
, or Smiles
with Name
(common english name) being the default. We can change the identifier type usig the identifier_option
argument with an IdentifierOption
object. Given a list of identifiers and a path to the parameter file, we can conveniently generate our object.
[2]:
# path to parameter file for substances that are non-associating, i.e. defined by three parameters: m, sigma, and epsilon_k.
file_na = '../parameters/pcsaft/gross2001.json'
# a system containing a single substance, "methane", using "Name" as identifier (default)
parameters = PcSaftParameters.from_json(['methane'], pure_path=file_na)
parameters
[2]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
methane |
16.043 |
1 |
3.7039 |
150.03 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
[3]:
# a system containing a single substance, "methane", using "Smiles" ("C") as identifier
parameters = PcSaftParameters.from_json(['C'], pure_path=file_na, identifier_option=IdentifierOption.Smiles)
parameters
[3]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
methane |
16.043 |
1 |
3.7039 |
150.03 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
Mixtures¶
Reading parameters for more than one substance from a single file is very straight forward: simply add more identifiers to the list. Note that the order in which which identifiers are provided is important. When computing vector valued properties, the order of the physical properties matches the order of the substances within the parameter object.
[4]:
# a system containing a ternary mixture
parameters = PcSaftParameters.from_json(
['methane', 'hexane', 'dodecane'],
pure_path=file_na
)
parameters
[4]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
methane |
16.043 |
1 |
3.7039 |
150.03 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
hexane |
86.177 |
3.0576 |
3.7983 |
236.77 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
dodecane |
170.338 |
5.306 |
3.8959 |
249.21 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
From multiple files¶
There may be cases where we have to split our parameter information across different files. For example, the feos
repository has parameters stored in different files where each file corresponds to the parameter’s original publication. Constructing the parameter object using multiple different json files is a bit more complicated. We can provide a list tuples, each of which contains the list of substances and the file where parameters are stored.
In the example below, we define a 4 component mixture from three input files:
methane is read from a file containing non-associating substance parameters.
parameters for 1-butanol and water are read from a file containing associating substances, and
acetone parameters are read from a file that contains substances modelled with dipolar interactions.
[6]:
# na = non-associating
# assoc = associating
file_na = '../parameters/pcsaft/gross2001.json'
file_assoc = '../parameters/pcsaft/gross2002.json'
file_dipolar = '../parameters/pcsaft/gross2006.json'
parameters = PcSaftParameters.from_multiple_json(
[
(['C'], file_na),
(['CCCCO', 'O'], file_assoc),
(['CC(C)=O'], file_dipolar)
],
identifier_option=IdentifierOption.Smiles
)
parameters
[6]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
methane |
16.043 |
1 |
3.7039 |
150.03 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.123 |
2.7515 |
3.6139 |
259.59 |
0 |
0 |
0.006692 |
2544.6 |
1 |
1 |
0 |
water |
18.015 |
1.0656 |
3.0007 |
366.51 |
0 |
0 |
0.034868 |
2500.7 |
1 |
1 |
0 |
acetone |
58.08 |
2.7447 |
3.2742 |
232.99 |
2.88 |
0 |
0 |
0 |
0 |
0 |
0 |
With binary interaction parameters¶
Some mixtures cannot be adequately described with combination rules from pure substance parameters. In PC-SAFT, we can use a binary interaction parameter, k_ij
, to enhance the description of mixture behavior. These interaction parameters can be supplied from a json file via the binary_path
option.
This parameter is not shown in the default representation of the parameter object. You can access the matrix of k_ij
via the getter, PcSaftParameters.k_ij
.
[7]:
file_na = '../parameters/pcsaft/gross2001.json'
file_assoc = '../parameters/pcsaft/gross2002.json'
file_binary = '../parameters/pcsaft/gross2002_binary.json'
parameters = PcSaftParameters.from_multiple_json(
[
(['CCCC'], file_na),
(['CCCCO',], file_assoc)
],
binary_path=file_binary,
identifier_option=IdentifierOption.Smiles
)
parameters
[7]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
butane |
58.123 |
2.3316 |
3.7086 |
222.88 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.123 |
2.7515 |
3.6139 |
259.59 |
0 |
0 |
0.006692 |
2544.6 |
1 |
1 |
0 |
[8]:
parameters.k_ij
[8]:
array([[0. , 0.015],
[0.015, 0. ]])
Building parameters in Python¶
Building PcSaftParameters
in Python is a bit more involved since the PcSaftParameters
object is built from multiple intermediate objects. We need
the
Identifier
object that stores information about how a substance can be identified,the
PcSaftRecord
object that stores our SAFT parameters,and the
PureRecord
object that bundles identifier and parameters together with the molar weight.
All these objects are imported from the feos.pcsaft
module.
[9]:
from feos.pcsaft import Identifier, PcSaftRecord, PureRecord
[10]:
identifier = Identifier(
cas='106-97-8',
name='butane',
iupac_name='butane',
smiles='CCCC',
inchi='InChI=1/C4H10/c1-3-4-2/h3-4H2,1-2H3',
formula='C4H10'
)
identifier
[10]:
Identifier(cas=106-97-8, name=butane, iupac_name=butane, smiles=CCCC, inchi=InChI=1/C4H10/c1-3-4-2/h3-4H2,1-2H3, formula=C4H10)
The PcSaftRecord
contains the model parameters for a pure substance. Mandatory parameters are
the number of segments,
m
, which is a dimensionless floating point number,the Lennard-Jones structure parameter (diameter),
sigma
, in units of Angstrom, andthe Lennard-Jones energy parameter,
epsilon_k
, in units of Kelvin.
Optional parameters are
the dipole moment,
mu
, in units of Debye used to model dipolar substances,the quadrupole moment,
q
, in units of Debye used to model quadrupolar substances,parameters to model association:
kappa_ab
,epsilon_k_ab
,na
,nb
and parameters for entropy scaling:
viscosity
,diffusion
, andthermal_conductivity
each of which is a list containing coefficients for the respective correlation functions.
[11]:
# parameters for a non-associating, non-polar substance (butane)
psr = PcSaftRecord(m=2.3316, sigma=3.7086, epsilon_k=222.88)
psr
[11]:
PcSaftRecord(m=2.3316, sigma=3.7086, epsilon_k=222.88)
A PureRecord
is built from an Identifier
, the molar weight (in gram per mole) and a PcSaftRecord
. Optionally, but not shown in this example, we can provide an ideal_gas_record
depending on the ideal gas model used in the equation of state. We will not discuss this contribution here but address the topic in a different example.
[12]:
butane = PureRecord(identifier, molarweight=58.123, model_record=psr)
butane
[12]:
PureRecord(
identifier=Identifier(cas=106-97-8, name=butane, iupac_name=butane, smiles=CCCC, inchi=InChI=1/C4H10/c1-3-4-2/h3-4H2,1-2H3, formula=C4H10),
molarweight=58.123,
model_record=PcSaftRecord(m=2.3316, sigma=3.7086, epsilon_k=222.88),
)
For a single substance, we can use the PcSaftParameters.new_pure
constructor.
[13]:
parameters = PcSaftParameters.new_pure(butane)
parameters
[13]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
butane |
58.123 |
2.3316 |
3.7086 |
222.88 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
We can create another PureRecord
for a second component. Then, the PcSaftParameters.new_binary
constructor let’s us build the parameters. Optionally, we can also directly provide a k_ij
value for this system. Here, we build a record for an associating substance.
[14]:
butan_1_ol = PureRecord(
identifier=Identifier(
cas='71-36-3',
name='1-butanol',
iupac_name='butan-1-ol',
smiles='CCCCO',
inchi='InChI=1/C4H10O/c1-2-3-4-5/h5H,2-4H2,1H3',
formula='C4H10O'
),
molarweight=74.123,
model_record=PcSaftRecord(
m=2.7515,
sigma=3.6139,
epsilon_k=259.59,
kappa_ab=0.006692,
epsilon_k_ab=2544.6
)
)
[15]:
parameters = PcSaftParameters.new_binary([butane, butan_1_ol], binary_record=0.015)
parameters
[15]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
butane |
58.123 |
2.3316 |
3.7086 |
222.88 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.123 |
2.7515 |
3.6139 |
259.59 |
0 |
0 |
0.006692 |
2544.6 |
0 |
0 |
0 |
[16]:
parameters.k_ij
[16]:
array([[0. , 0.015],
[0.015, 0. ]])
For mixtures with more than two components, we can use the PcSaftParameters.from_records
constructor which takes a list of PureRecords
and a numpy.ndarray
containing the matrix of k_ij
values.
[17]:
import numpy as np
k_ij = np.zeros((2, 2))
k_ij[0, 1] = k_ij[1, 0] = 0.015
parameters = PcSaftParameters.from_records(
[butane, butan_1_ol],
binary_records=k_ij
)
parameters
[17]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
butane |
58.123 |
2.3316 |
3.7086 |
222.88 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.123 |
2.7515 |
3.6139 |
259.59 |
0 |
0 |
0.006692 |
2544.6 |
0 |
0 |
0 |
[18]:
parameters.k_ij
[18]:
array([[0. , 0.015],
[0.015, 0. ]])
Parameters from homo-segmented group contribution (homo-GC)¶
An alternative to substance specific parameters are parameters that combine information from functional groups (molecule segments). A simple variant that only uses the number of segments (not how these segments are connected to form the molecule) is the so-called homo-segmented group contribution method (homo-GC).
As with regular SAFT parameters, we can build a PcSaftParameters
object from json or from Python - using segment information.
From json files¶
We need at least two files:
pure_path
: a file containing the substance identifiers and the segments that form the moleculesegments_path
: a file that contains the segments (identifier and model parameters)
As before, we can specify our substance identifier using identifier_option
and we can provide binary interaction parameters (segment-segment k_ij
) via the binary_path
argument.
[19]:
pure_path = '../parameters/pcsaft/gc_substances.json'
segments_path = '../parameters/pcsaft/sauer2014_homo.json'
parameters = PcSaftParameters.from_json_segments(
['CCCC', 'CCCCO'],
pure_path,
segments_path,
identifier_option=IdentifierOption.Smiles
)
parameters
[19]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
butane |
58.122159999999994 |
2.1360799999999998 |
3.7945688260994523 |
233.79002902513017 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.12158 |
2.3821600000000003 |
3.7568140627964164 |
278.79916705846796 |
0 |
0 |
0.006825 |
2517 |
1 |
1 |
0 |
From Python¶
Building parameters in Python follows a similar approach as for regular parameters. To build PcSaftParameters
from segments, we need to specify:
The
ChemicalRecord
which contains theIdentifier
and the segments (as list ofstr
s),and the
SegmentRecord
which specifies the identifier of the segment (has to be the same as in the list of theChemicalRecord
), the molar weight and thePcSaftRecord
for the segment.
If both are available, we can use the PcSaftParameters.from_segments
constructor to build the parameters.
[20]:
from feos.pcsaft import ChemicalRecord, SegmentRecord
cr1 = ChemicalRecord(
identifier=Identifier(
cas='106-97-8',
name='butane',
iupac_name='butane',
smiles='CCCC',
inchi='InChI=1/C4H10/c1-3-4-2/h3-4H2,1-2H3',
formula='C4H10'
),
segments=['CH3', 'CH2', 'CH2', 'CH3']
)
cr2 = ChemicalRecord(
identifier=Identifier(
cas='71-36-3',
name='1-butanol',
iupac_name='butan-1-ol',
smiles='CCCCO',
inchi='InChI=1/C4H10O/c1-2-3-4-5/h5H,2-4H2,1H3',
formula='C4H10O'
),
segments=['CH3', 'CH2', 'CH2', 'CH2', 'OH']
)
Each segment has a PcSaftRecord
which can be constructed just like we did before for a substance.
[21]:
ch3 = SegmentRecord(
'CH3',
molarweight=15.0345,
model_record=PcSaftRecord(m=0.61198, sigma=3.7202, epsilon_k=229.90)
)
ch2 = SegmentRecord(
'CH2',
molarweight=14.02658,
model_record=PcSaftRecord(m=0.45606, sigma=3.8900, epsilon_k=239.01)
)
oh = SegmentRecord(
'OH',
molarweight=17.00734,
model_record=PcSaftRecord(
m=0.40200,
sigma=3.2859,
epsilon_k=488.66,
epsilon_k_ab=2517.0,
kappa_ab=0.006825
)
)
[22]:
parameters = PcSaftParameters.from_segments(
chemical_records=[cr1, cr2],
segment_records=[ch3, ch2, oh]
)
parameters
[22]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
butane |
58.122159999999994 |
2.1360799999999998 |
3.7945688260994523 |
233.79002902513017 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.12158 |
2.3821600000000003 |
3.7568140627964164 |
278.79916705846796 |
0 |
0 |
0.006825 |
2517 |
0 |
0 |
0 |
Accessing information from parameter objects¶
Once the PcSaftParameter
object is constructed, within a jupyter notebook, we get a nice representation in form of a markdown table. Sometimes, however you might want to access information not presented in this table or you might want to store information in a variable.
Let’s build parameters for the four-component mixture we looked at earlier:
[24]:
file_na = '../parameters/pcsaft/gross2001.json'
file_assoc = '../parameters/pcsaft/gross2002.json'
file_dipolar = '../parameters/pcsaft/gross2006.json'
parameters = PcSaftParameters.from_multiple_json(
[
(['C'], file_na),
(['CCCCO', 'O'], file_assoc),
(['CC(C)=O'], file_dipolar)
],
identifier_option=IdentifierOption.Smiles
)
parameters
[24]:
component |
molarweight |
\(m\) |
\(\sigma\) |
\(\varepsilon\) |
\(\mu\) |
\(Q\) |
\(\kappa_{AB}\) |
\(\varepsilon_{AB}\) |
\(N_A\) |
\(N_B\) |
\(N_C\) |
---|---|---|---|---|---|---|---|---|---|---|---|
methane |
16.043 |
1 |
3.7039 |
150.03 |
0 |
0 |
0 |
0 |
0 |
0 |
0 |
1-butanol |
74.123 |
2.7515 |
3.6139 |
259.59 |
0 |
0 |
0.006692 |
2544.6 |
1 |
1 |
0 |
water |
18.015 |
1.0656 |
3.0007 |
366.51 |
0 |
0 |
0.034868 |
2500.7 |
1 |
1 |
0 |
acetone |
58.08 |
2.7447 |
3.2742 |
232.99 |
2.88 |
0 |
0 |
0 |
0 |
0 |
0 |
As we’ve seen before, we can directly access the binary interaction parameter, k_ij
, which is zero here for all binary interactions (we did not provide a file).
[25]:
parameters.k_ij
Get PureRecord
s via parameters.pure_records
¶
We have seen above that it is possible to generate parameters in Python using intermediate objects, such as Identifier
, PcSaftRecord
and PureRecord
. You can generate these objects for all substances via the pure_records
method (getter). This getter returns PureRecord
objects which can be further deconstructed to yield the Identifier
and PcSaftRecord
objects and the molar weight.
Note that the order in which substances are returned matches the order in which we specified the substances above.
[26]:
parameters.pure_records
[26]:
[PureRecord(
identifier=Identifier(cas=74-82-8, name=methane, iupac_name=methane, smiles=C, inchi=InChI=1/CH4/h1H4, formula=CH4),
molarweight=16.043,
model_record=PcSaftRecord(m=1, sigma=3.7039, epsilon_k=150.03, association_record=AssociationRecord(kappa_ab=0, epsilon_k_ab=0)),
),
PureRecord(
identifier=Identifier(cas=71-36-3, name=1-butanol, iupac_name=butan-1-ol, smiles=CCCCO, inchi=InChI=1/C4H10O/c1-2-3-4-5/h5H,2-4H2,1H3, formula=C4H10O),
molarweight=74.123,
model_record=PcSaftRecord(m=2.7515, sigma=3.6139, epsilon_k=259.59, association_record=AssociationRecord(kappa_ab=0.006692, epsilon_k_ab=2544.6, na=1, nb=1)),
),
PureRecord(
identifier=Identifier(cas=7732-18-5, name=water, iupac_name=oxidane, smiles=O, inchi=InChI=1/H2O/h1H2, formula=H2O),
molarweight=18.015,
model_record=PcSaftRecord(m=1.0656, sigma=3.0007, epsilon_k=366.51, association_record=AssociationRecord(kappa_ab=0.034868, epsilon_k_ab=2500.7, na=1, nb=1)),
),
PureRecord(
identifier=Identifier(cas=67-64-1, name=acetone, iupac_name=propan-2-one, smiles=CC(C)=O, inchi=InChI=1/C3H6O/c1-3(2)4/h1-2H3, formula=C3H6O),
molarweight=58.08,
model_record=PcSaftRecord(m=2.7447, sigma=3.2742, epsilon_k=232.99, mu=2.88, association_record=AssociationRecord(kappa_ab=0, epsilon_k_ab=0)),
)]
[27]:
for pure_record in parameters.pure_records:
print(f"σ ({pure_record.identifier.name})\t = {pure_record.model_record.sigma} A")
σ (methane) = 3.7039 A
σ (1-butanol) = 3.6139 A
σ (water) = 3.0007 A
σ (acetone) = 3.2742 A
[28]:
# get identifier of substance 0
parameters.pure_records[0].identifier
[28]:
Identifier(cas=74-82-8, name=methane, iupac_name=methane, smiles=C, inchi=InChI=1/CH4/h1H4, formula=CH4)
[29]:
# get molarweight of substance 0
parameters.pure_records[0].molarweight
[29]:
16.043
A PureRecord
object can be used to generate a json string which then can conveniently be stored in a file.
[30]:
# generate a json string from identifier of substance 0
parameters.pure_records[0].to_json_str()
[30]:
'{"identifier":{"cas":"74-82-8","name":"methane","iupac_name":"methane","smiles":"C","inchi":"InChI=1/CH4/h1H4","formula":"CH4"},"molarweight":16.043,"model_record":{"m":1.0,"sigma":3.7039,"epsilon_k":150.03}}'
Summary¶
In \(\text{FeO}_\text{s}\), handling of parameters is not predefined within the underlying library. Each implementation of an equation of state has complete autonomy about the way parameters are handled. Howevery, we offer some convenient ways to automatize parameter handling which result in the methods presented in this example.
We looked at different ways to get parameters for the EquationOfState.pcsaft()
equation of state, i.e.
how to read parameters for substances from one or more files where we use the json format to store information, and
how to generate parameters the same parameters in Python.
In a similar fashion, we showed how parameters can be assembled using a homo-GC method.
Once parameters are created, we can retrieve information by extracting the intermediate objects such as PureRecord
, Identifier
and PcSaftRecord
.
Further reading¶
For more information about group contribution methods, see this paper by Sauer et al.
Files of published parameters can be found in the ``feos` github repositoy <https://github.com/feos-org/feos/tree/main/parameters/pcsaft>`__.
Concluding remkars¶
Hopefully you found this example helpful. If you have comments, critique or feedback, please let us know and consider opening an issue on github.
[31]:
from feos.ideal_gas import JobackParameters