`ccu.thermo.chempot`¶

Calculate thermodynamic properties via a DFT-parametrized calculator.

This module defines classes for the calculation of thermodynamic data via DFT-parametrized models. In this way, zero-point energies, chemical potentials, and Gibbs free energies can be calculated without the need of expensive vibrational calculations. That hard work has already been done!

In particular, this module defines two main classes:

ChemPotDatabase: a database for parametrization data.
ChemPotCalculator: a calculator for computing thermodynamic data from parametrization data in a ChemPotDatabase.

Additionally, ccu ships with a pre-defined dataset for a number of molecules. The dataset was produced from a set of DFT-D3 calculations and includes zero-point energies calculated under the rigid rotator and harmonic oscillator approximations. Calculated values are valid below 1100K. Chemical potentials are calculated via calculate_chemical_potential() using equation (1).

Examples

List all molecules included in the pre-defined dataset.

>>> from ccu.thermo.chempot import ChemPotDatabase
>>> from ccu.thermo.chempot import load_zpe_data
>>> zpe_data = load_zpe_data()
>>> for molecule in zpe_data:
...     print(molecule)
CO2
...

Retrieve parametrization data for CO₂ valid at 350 K.

>>> from ccu.thermo.chempot import ChemPotDatabase
>>> database = ChemPotDatabase()
>>> query = {"molecule": "CO2", "temperature": 350}
>>> database.get(**query)[0]
0.130...

Retrieve the vibrational zero-point energy of N₂.

>>> from ccu.thermo.chempot import ChemPotDatabase
>>> database = ChemPotDatabase()
>>> database.zpe_data["N2"]
0.15...

Calculate the chemical potential of H₂O at IUPAC STP (273.15 K, 1 bar).

>>> from ccu.thermo.chempot import ChemPotCalculator
>>> calc = ChemPotCalculator()
>>> chem_pot, _ = calc.calculate("H2O", 273.15, 1.0)
>>> chem_pot
0.114...

or simply,

>>> from ccu.thermo.chempot import calculate
>>> calculate("H2O")[0]
0.114...

Calculate the gibbs free energy of CH₄ at 900 K and 2.4 bar.

>>> from ccu.thermo.chempot import calculate
>>> sum(calculate("CH4", 900, 2.4))
-0.759...

Use a custom database to perform the above calculations.

>>> from ccu.thermo.chempot import ChemPotCalculator
>>> from ccu.thermo.chempot import ChemPotDatabase
>>> from ccu.thermo.chempot import load_zpe_data
... # specify the paths to your database files
>>> parameter_data = load_parameter_data(..., external=True)  
>>> zpe_data = load_zpe_data(...)  
... # load the database into the calculator
>>> database = ChemPotDatabase(
...     parameter_data=parameter_data, zpe_data=zpe_data
... )  
>>> calc = ChemPotCalculator(database)  
... # and then as above...  

class ccu.thermo.chempot.ChemPotCalculator(database: ChemPotDatabase | None = None)[source]¶

Bases: object

A chemical potential calculator.

Variables:: database – The underlying database used for calculations.

Example

>>> from ccu.thermo.chempot import ChemPotCalculator
>>>
>>> calc = ChemPotCalculator()
>>> calc.calculate("CO2", 298.15, 1.0)
-0.581856

Initialize the calculator from a database.

Parameters:: database – The database to use for the calculator. Defaults to None, in which case the pre-defined database is used.

calculate(molecule: str, temperature: float, pressure: float) → float[source]¶

Calculate the chemical potential of a molecule.

Parameters:

molecule – The molecule for which to calculate the chemical potential.
temperature – The temperature at which to calculate the chemical potential.
pressure – The pressure at which to calculated the chemical potential.

Returns:

The chemical potential.

property max_temperature: float¶: The maximum temperature supported by the underlying database.

Note

This property represents the maximum temperature of any data point irrespective of the molecule or parameter (“b” or “m”). Further, since the upper limit of an instance of ChemPotDataPoint represents an exclusive upper limit, the maximum reported upper limit is decremented by a tol to ensure non-empty queries with this value.

class ccu.thermo.chempot.ChemPotDataPoint(lower: float, molecule: str, param: Literal['b', 'm'], upper: float, value: float)[source]¶

Bases: NamedTuple

A thermodynamic parameter, valid in a certain temperature range.

Variables:

lower (float) – The lower temperature bound of the range (inclusive) in which the data point is valid.
molecule (str) – The molecule to which that data point applies.
term – The kind of term represented by the ChemPotDataPoint. If "b", the data point corresonds to a y-intercept. If "m", then the data point corresponds to a slope-like term.
upper (float) – The upper temperature bound of the range (exclusive) in which the data point is valid.
value (float) – The value of the parameter.

Create new instance of ChemPotDataPoint(lower, molecule, param, upper, value)

_asdict()¶: Return a new dict which maps field names to their values.

_field_defaults = {}¶

_fields = ('lower', 'molecule', 'param', 'upper', 'value')¶

classmethod _make(iterable)¶: Make a new ChemPotDataPoint object from a sequence or iterable

_replace(**kwds)¶: Return a new ChemPotDataPoint object replacing specified fields with new values

lower: float¶: Alias for field number 0

molecule: str¶: Alias for field number 1

param: Literal['b', 'm']¶: Alias for field number 2

upper: float¶: Alias for field number 3

value: float¶: Alias for field number 4

class ccu.thermo.chempot.ChemPotDatabase(parameter_data: list[~ccu.thermo.chempot.ChemPotDataPoint] = <factory>, zpe_data: dict[str, float] = <factory>)[source]¶

Bases: object

A database of parametrized thermochemical data.

Variables:

parameter_data (list[ccu.thermo.chempot.ChemPotDataPoint]) – A list of ChemPotDataPoint representing thermodynamic data for a parametrization.
zpe_data (dict[str, float]) – A dictionary mapping molecule names to vibrational zero-point energies.

Example

Retrieve b parameter data for CO₂ that is valid at 350 K.

>>> from ccu.thermo.chempot import ChemPotDatabase
>>> database = ChemPotDatabase()
>>> # Note that the following returns a list
>>> database.get(molecule="CO2", temperature=350, param="b")
[ChemPotDataPoint(param='b', lower=350.0, upper=400.0, molecule='CO...

Example

Retrieve ZPE data for CO₂.

>>> from ccu.thermo.chempot import ChemPotDatabase
>>> database = ChemPotDatabase()
>>> database.zpe_data["CO2"]
0.306

get(temperature: float | None = None, **query) → list[ChemPotDataPoint][source]¶

Retrieve values from the parametrization database.

Parameters:

temperature – The temperature to use as a search key. Defaults to None. Note, however, that specifying this instead results in all database entries with lower and upper values which bracket temperature to be used. If values with a specific lower or upper range are desired, use the keys "lower" and "upper", respectively.
**query – Specify filtering criteria with which to search for entries. Any keys corresponding to fields in a ChemPotDataPoint

Raises:

LookupError – You specified a key that is not a field of ChemPotDataPoint.

Returns:

A list of every ChemPotDataPoint with fields matching your query.

Note

Although it doesn’t affect the results returned, the order that keyword arguments are specied affects the speed in which results are returned. Except for temperature, filtering criteria is applied in the order it is supplied in the function call. If supplied, the temperature criteria is always applied first.

parameter_data: list[ChemPotDataPoint]¶

zpe_data: dict[str, float]¶

ccu.thermo.chempot._construct_lines_to_print(full_width: int, short_width: int, buffer: int) → tuple[list[str], list[str]][source]¶

Construct the lines of the instruction text.

Parameters:

full_width – The full width of the instruction text. This is used to set the boxsize.
short_width – The half width of the instruction text. This is used to wrap the upper text.
buffer – The size of the margins. This is used as a starting point for setting the margins of all text.

Returns:

The wrapped instruction text.

ccu.thermo.chempot.calculate(molecule: str, temperature: float = 273.15, pressure: float = 1.0) → tuple[float, float][source]¶

Calculate molecular thermodynamic properties with the default data.

Parameters:

molecule – The name of the molecule for which the calculation will be performed. Must be present in the default database.
temperature – The temperature (in Kelvin) at which to perform the calculation. Defaults to 298.15.
pressure – The pressure (in bar) at which to perform the calculation. Defaults to 1.0.

Returns:

A 2-tuple (chem_pot, zpe) corresponding to the calculated chemical potential and vibrational zero-point energy, respectively.

Note

The model is only parametrized up to 1000K. Although values up to 1100K may still be reliable, at temperatures higher than 1100K, results become unreliable.

ccu.thermo.chempot.calculate_chemical_potential(b: float, m: float, temperature: float, pressure: float) → float[source]¶

Calculate the chemical potential from parametrized model.

This equation is consistent with (1).

Parameters:

b – The y-intercept.
m – The “slope”-like term in the interpolation.
temperature – The temperature at which to calculate the chemical potential.
pressure – The pressure at which to calculate the chemical potential.

Returns:

The chemical potential at the conditions specified.

ccu.thermo.chempot.load_parameter_data(*, filename: str | Path = 'param_data.csv', external: bool = False) → list[ChemPotDataPoint][source]¶

Load parametrized data from a file of comma-separated values.

Parameters:

filename – The file from which to load the data. Defaults to “param_data.csv”.
external – Whether to load the file from in external source. Defaults to False.

Returns:

A dictionary mapping molecule names to lists of ChemPotDataPoints.

Note

The fields of the CSV file must include those of a ChemPotDataPoint, and the values for the keys “lower”, “upper”, and “value” must be able to be converted into floats.

ccu.thermo.chempot.load_zpe_data(*, filename: str | Path = 'zpe_data.csv', external: bool = False) → dict[str, float][source]¶

Load vibrational zero-point energy data from a CSV file.

Parameters:

filename – The file from which to load the data. Defaults to “zpe_data.csv”.
external – Whether to load the file from an external source. Defaults to False.

Returns:

A dictionary mapping molecule names to their vibrational zero-point energies.

Note

The fields of the CSV file must include “molecule” and “zpe”, and the values corresponding to “zpe” must be able to be converted into floats.

ccu.thermo.chempot.print_instructions() → None[source]¶: Print instructions for using ccu.chempot interactively.

ccu.thermo.chempot¶

`ccu.thermo.chempot`¶