CosmoRealSpecies¶

class CosmoRealSpecies(configuration, solvation_energy=None, melting_point=None, enthalpy_of_fusion=None, specific_heat_capacity_change=None, antoine_a=None, antoine_b=None, antoine_c=None, boiling_point=None, flash_point=None, density=None)¶

The chemical species to be used in COSMO-RS calculations.

Parameters:

configuration (MoleculeConfiguration | SurfaceConfiguration) – The solute with an attached COSMO DFT calculator.
solvation_energy (SolvationEnergy | SolvationEnergyDatabaseContainer) – The solvation energy analysis for the molecule.
melting_point (PhysicalQuantity of type temperature) – The melting point of the pure substance.
enthalpy_of_fusion (PhysicalQuantity of type energy) – The enthalpy or heat of fusion of the pure substance.
specific_heat_capacity_change (PhysicalQuantity of type energy per temperature) – The difference the molar isobaric specific heat capacity between the liquid and solid phase.
antoine_a (PhysicalQuantity of type pressure) – The A parameter of the Antoine equation. Note that here the units indicate the units of pressure in the equation.
antoine_b (PhysicalQuantity of type temperature) – The B parameter of the Antoine equation.
antoine_c (PhysicalQuantity of type temperature) – The C parameter of the Antoine equation.
boiling_point (PhysicalQuantity of type temperature) – The boiling point of the pure substance.
flash_point – Minimum temperature required for the vaporized pure substance to be combustible in air.
density (PhysicalQuantity of type density) – The liquid density of the pure compound.

antoineA()¶

Returns:: The A parameter of the Antoine equation. The units indicate the resulting unit of pressure.
Return type:: PhysicalQuantity of type pressure

antoineB()¶

Returns:: The B parameter of the Antoine equation.
Return type:: PhysicalQuantity of type temperature

antoineC()¶

Returns:: The C parameter of the Antoine equation.
Return type:: PhysicalQuantity of type temperature

antoinePressure(temperature)¶

Estimate the partial pressure based on the Antoine equation. If one or more parameters are not set None is returned.

Parameters:: temperature (PhysicalQuantity of type temperature) – The temperature at which the partial pressure is evaluated.
Returns:: The partial pressure.
Return type:: PhysicalQuantity of type pressure

boilingPoint()¶

Returns:: The boiling point of the pure substance, if defined, None if not.
Return type:: PhysicalQuantity of type temperature

cavitySurfaceArea()¶

Returns:: The cavity surface area.
Return type:: PhysicalQuantity of type area

cavityVolume()¶

Returns:: The cavity volume.
Return type:: PhysicalQuantity of type volume

configuration()¶

Returns:: The updated COSMO configuration.
Return type:: MoleculeConfiguration | SurfaceConfiguration | BulkConfiguration

density()¶

Returns:: Liquid phase density.
Return type:: PhysicalQuantity of type temperature

enthalpyOfFusion()¶

Returns:: The enthalpy of fusion of the molecule, if defined, None if not
Return type:: PhysicalQuantity of type energy.

flashPoint()¶

Returns:: Minimum temperature required for the vaporized pure substance to be combustible in air, if defined, None if not.
Return type:: PhysicalQuantity of type temperature

gasEnergy()¶

Returns:: The gas phase energy of the molecule
Return type:: PhysicalQuantity of type energy

meltingPoint()¶

Returns:: The melting point of the molecule, if defined, None if not
Return type:: PhysicalQuantity of type temperature.

molarMass()¶

Returns:: The molar mass of the species.
Return type:: PhysicalQuantity of type mass.

setAntoineA(antoine_a)¶

Set the stored A parameter of the Antoine equation. The units indicate the vapor pressure units.

Parameters:: enthalpy_of_vaporization (PhysicalQuantity of type pressure) – The Antoine A parameter.

setAntoineB(antoine_b)¶

Set the stored B parameter of the Antoine equation.

Parameters:: enthalpy_of_vaporization (PhysicalQuantity of type temperature) – The Antoine B parameter.

setAntoineC(antoine_c)¶

Set the stored C parameter of the Antoine equation.

Parameters:: enthalpy_of_vaporization (PhysicalQuantity of type temperature) – The Antoine C parameter.

setBoilingPoint(boiling_point)¶

Set the stored boiling point.

Parameters:: boiling_point (PhysicalQuantity of type temperature) – The melting point.

setDensity(density)¶

Set the stored density.

Parameters:: density (PhysicalQuantity of type mass per volume) – The density.

setEnthalpyOfFusion(enthalpy_of_fusion)¶

Set the stored enthalpy of fusion.

Parameters:: enthalpy_of_fusion (PhysicalQuantity of type energy) – The enthalpy of fusion.

setFlashPoint(flash_point)¶

Set the stored flash point.

Parameters:: flash_point (PhysicalQuantity of type temperature) – The flash point.

setMeltingPoint(melting_point)¶

Set the stored melting point.

Parameters:: melting_point (PhysicalQuantity of type energy) – The melting point.

setSpecificHeatCapacityChange(specific_heat_capacity_change)¶

Set the stored difference in the liquid and solid isobaric molar specific heat capacity.

Parameters:: specific_heat_capacity_change (PhysicalQuantity of type energy per temperature) – The specific heat capacity change.

sigmaProfile(r_average=None, bin_size=None, min_charge_density=None, max_charge_density=None, normalize=False)¶

Method to compute the sigma profile.

Parameters:

r_average (PhysicalQuantity of type length) – The radius used for sigma averaging.
bin_size (PhysicalQuantity of type charge per surface area) – The spacing in the sigma profile.
min_charge_density (PhysicalQuantity of type charge per surface area) – The minimum charge density range. If not given or greater than the minimum species surface charge density, the minimum species charge density is used.
Default: Determined by species surface charge density
max_charge_density (PhysicalQuantity of type charge per surface area) – The maximum charge density range. If not given or less than the maximum species surface charge density, the maximum species charge density is used.
Default: Determined by species surface charge density
normalize (bool) – Whether or not the sigma profile is normalized.
Default: False

Returns:

Tuple of the charge densities and sigma profile for the species.

Return type:

tuple

sigmaProfilePlot(r_average=None, bin_size=None, normalize=False)¶

Method to plot the smoothed sigma profile of the species.

Parameters:

r_average (PhysicalQuantity of type distance) – The averaging radius used to smooth the charge densities.
bin_size (PhysicalQuantity of type charge per surface area.) – The bin size for the sigma profile histogram.
normalize (bool) – Whether to normalize the profile or not.
Default: False

Returns:

The PlotModel of the sigma profile.

Return type:

PlotModel

solventEnergy()¶

Returns:: The solution phase energy of the molecule
Return type:: PhysicalQuantity of type energy

specificHeatCapacityChange()¶

Returns:: The difference the molar isobaric specific heat capacity between the liquid and solid phase, if defined, None if not.
Return type:: PhysicalQuantity of type energy per temperature

totalSolvationEnergy()¶

Returns:: The difference between the gas and solution phases of the molecule
Return type:: PhysicalQuantity of type energy

uniqueString()¶: Return a unique string representing the state of the object.

Usage Examples¶

Set up a water CosmoRealSpecies.

# Create the species.
water_species = CosmoRealSpecies(
    water,
    solvation_energy=solvation_energy,
    melting_point=273.15*Kelvin,
    density=1*gram*cm**-3,
)

# Add boiling point data.
water_species.setBoilingPoint(373.15*Kelvin)

# Retrieve sigma profile.
charge_densities, sigma_profile = water_species.sigmaProfile()

# Retrieve the sigma profile plot.
plot = water_species.sigmaProfilePlot()
Plot.show(plot)

water_species_example.py

Notes¶

The CosmoRealSpecies object constitutes one of the fundamental objects within the present COSMO-RS implementation. It holds all the DFT information to describe interactions with a solvent, as well as any additional experimental data that may be used. Once the object is instantiated the additional experimental data can subsequently be modified with further information by using the set-prefixed methods. With the stored information the CosmoRealSpecies object is able to calculate the \(\sigma\) profile of the molecule. The \(\sigma\) profile, along with the corresponding charge densities, can be returned using the sigmaProfile method. If the profile is normalized, the profile represents the probability of finding the given charge density. Without normalization the profile represents the total surface area with the given charge density.

Due to the linear equations used to fit charges to the COSMO surface, some unreasonably large charge densities might occur on the COSMO cavity surface. This can be corrected by a charge smoothing process called \(\sigma\)-averaging. This is performed within the CosmoRealSpecies object according to the following equation [1]

\[\sigma_i = \frac{\sum_j \frac{q_j}{s_j + s_{av}} \text{exp} \left(\frac{d_{ij}^2}{r_{av}^2}\right)} {\sum_j \frac{s_j}{s_j + s_{av}} \text{exp} \left(\frac{d_{ij}^2}{r_{av}^2}\right)}\]

Here \(r_{av}\) is the averaging radius which is one of the parameters in CosmoRSParameters. \(s_{av}\) is directly related to \(r_{av}\) as \(s_{av} = \pi r_{av}^2\). \(s_j\) and \(q_j\) are the COSMO area and surface charge of the \(j`th segment, respectively. :math:`d_{ij}\) is the Cartesian distance between the segments \(i\) and \(j\) where \(\sigma_i\) is the charge density being smoothed. This smoothing is done whenever the sigma profile is calculated.