Joback Group Contribution Method (thermo.group_contribution.joback)

This module contains an implementation of the Joback group-contribution method. This functionality requires the RDKit library to work.

For submitting pull requests, please use the GitHub issue tracker.

Warning

The Joback class method does not contain all the groups for every chemical. There are often multiple ways of fragmenting a chemical. Other times, the fragmentation algorithm will fail. These limitations are present in both the implementation and the method itself. You are welcome to seek to improve this code but no to little help can be offered.

class thermo.group_contribution.joback.Joback(mol, atom_count=None, MW=None, Tb=None)

Bases: object

Class for performing chemical property estimations with the Joback group contribution method as described in [1] and [2]. This is a very common method with low accuracy but wide applicability. This routine can be used with either its own automatic fragmentation routine, or user specified groups. It is applicable to organic compounds only, and has only 41 groups with no interactions between them. Each method’s documentation describes its accuracy. The automatic fragmentation routine is possible only because of the development of SMARTS expressions to match the Joback groups by Dr. Jason Biggs. The list of SMARTS expressions was posted publically on the RDKit mailing list.

Parameters:

molrdkitmol or smiles str

Input molecule for the analysis, [-]

atom_countint, optional

The total number of atoms including hydrogen in the molecule; this will be counted by rdkit if it not provided, [-]

MWfloat, optional

Molecular weight of the molecule; this will be calculated by rdkit if not provided, [g/mol]

Tbfloat, optional

An experimentally known boiling temperature for the chemical; this increases the accuracy of the calculated critical point if provided. [K]

Attributes:

calculated_Cpig_coeffs

calculated_mul_coeffs

Methods

Cpig(T)	Computes ideal-gas heat capacity at a specified temperature of an organic compound using the Joback method as a function of chemical structure only.
Cpig_coeffs(counts)	Computes the ideal-gas polynomial heat capacity coefficients of an organic compound using the Joback method as a function of chemical structure only.
Gf(counts)	Estimates the ideal-gas Gibbs energy of formation at 298.15 K of an organic compound using the Joback method as a function of chemical structure only.
Hf(counts)	Estimates the ideal-gas enthalpy of formation at 298.15 K of an organic compound using the Joback method as a function of chemical structure only.
Hfus(counts)	Estimates the enthalpy of fusion of an organic compound at its melting point using the Joback method as a function of chemical structure only.
Hvap(counts)	Estimates the enthalpy of vaporization of an organic compound at its normal boiling point using the Joback method as a function of chemical structure only.
Pc(counts, atom_count)	Estimates the critcal pressure of an organic compound using the Joback method as a function of chemical structure only.
Tb(counts)	Estimates the normal boiling temperature of an organic compound using the Joback method as a function of chemical structure only.
Tc(counts[, Tb])	Estimates the critcal temperature of an organic compound using the Joback method as a function of chemical structure only, or optionally improved by using an experimental boiling point.
Tm(counts)	Estimates the melting temperature of an organic compound using the Joback method as a function of chemical structure only.
Vc(counts)	Estimates the critcal volume of an organic compound using the Joback method as a function of chemical structure only.
estimate([callables])	Method to compute all available properties with the Joback method; returns their results as a dict.
mul(T)	Computes liquid viscosity at a specified temperature of an organic compound using the Joback method as a function of chemical structure only.
mul_coeffs(counts)	Computes the liquid phase viscosity Joback coefficients of an organic compound using the Joback method as a function of chemical structure only.

Notes

Be sure to check the status of the automatic fragmentation; not all chemicals with the Joback method are applicable.

Approximately 68% of chemcials in the thermo database seem to be able to be estimated with the Joback method.

If a group which was identified is missign a regressed contribution, the estimated property will be None. However, if not all atoms of a molecule are identified as particular groups, property estimation will go ahead with heavily reduced accuracy. Check the status attribute to be sure a molecule was properly fragmented.

References

[1]

Joback, Kevin G. “A Unified Approach to Physical Property Estimation Using Multivariate Statistical Techniques.” Thesis, Massachusetts Institute of Technology, 1984.

[2]

Joback, K.G., and R.C. Reid. “Estimation of Pure-Component Properties from Group-Contributions.” Chemical Engineering Communications 57, no. 1-6 (July 1, 1987): 233-43. doi:10.1080/00986448708960487.

[3] (1,2)

Elliott, J. Richard, Vladimir Diky, Thomas A. Knotts IV, and W. Vincent Wilding. The Properties of Gases and Liquids, Sixth Edition. 6th edition. New York: McGraw Hill, 2023.

Examples

Analysis of Acetone:

>>> J = Joback('CC(=O)C')
>>> J.Hfus(J.counts)
5125.0
>>> J.Cpig(350)
84.69109750000001
>>> J.status
'OK'

All properties can be obtained in one go with the estimate method:

>>> J.estimate(callables=False)
{'Tb': 322.11, 'Tm': 173.5, 'Tc': 500.5590049525365, 'Pc': 4802499.604994407, 'Vc': 0.0002095, 'Hf': -217829.99999999997, 'Gf': -154540.00000000003, 'Hfus': 5125.0, 'Hvap': 29018.0, 'mul_coeffs': [839.1099999999998, -14.99], 'Cpig_coeffs': [7.520000000000003, 0.26084, -0.0001207, 1.545999999999998e-08]}

The results for propionic anhydride (if the status is not OK) should not be used.

>>> J = Joback('CCC(=O)OC(=O)CC')
>>> J.status
'Matched some atoms repeatedly: [4]'
>>> J.Cpig(300)
175.85999999999999

None of the routines need to use the automatic routine; they can be used manually too:

>>> Joback.Tb({1: 2, 24: 1})
322.11

Example from [3] comparing against manually calculated literature values for 2-methylphenol (using a known Tb values for extra accuracy):

>>> J = Joback('CC1=CC=CC=C1O',  Tb=464.15)
>>> res = J.estimate(callables=False)
>>> [res['Tc'], res['Pc']/1e5, res['Vc']*1e6]
[692.64, 50.30, 285.5]
>>> J.status
'OK'

This matches exactly with the values given in [3] from Joback’s method. They also mention experimental values of Tc = 697.55 K, Pc = 50.10 bar, and Vc = 282 cm³/mol, values all within 1.5%.

Cpig(T)

Computes ideal-gas heat capacity at a specified temperature of an organic compound using the Joback method as a function of chemical structure only.

$$C_p^{ig} = \sum_i a_i - 37.93 + \left[ \sum_i b_i + 0.210 \right] T + \left[ \sum_i c_i - 3.91 \cdot 10^{-4} \right] T^2 + \left[\sum_i d_i + 2.06 \cdot 10^{-7}\right] T^3$$

Parameters:

Tfloat

Temperature, [K]

Returns:

Cpigfloat

Ideal-gas heat capacity, [J/mol/K]

Examples

>>> J = Joback('CC(=O)C')
>>> J.Cpig(300)
75.32642000000001

static Cpig_coeffs(counts)

Computes the ideal-gas polynomial heat capacity coefficients of an organic compound using the Joback method as a function of chemical structure only.

$$C_p^{ig} = \sum_i a_i - 37.93 + \left[ \sum_i b_i + 0.210 \right] T + \left[ \sum_i c_i - 3.91 \cdot 10^{-4} \right] T^2 + \left[\sum_i d_i + 2.06 \cdot 10^{-7}\right] T^3$$

288 compounds were used by Joback in this determination. No overall error was reported.

The ideal gas heat capacity values used in developing the heat capacity polynomials used 9 data points between 298 K and 1000 K.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

coefficientslist[float]

Coefficients which will result in a calculated heat capacity in in units of J/mol/K, [-]

Examples

>>> c = Joback.Cpig_coeffs({1: 2, 24: 1})
>>> c
[7.520000000000003, 0.26084, -0.0001207, 1.545999999999998e-08]
>>> Cp = lambda T : c[0] + c[1]*T + c[2]*T**2 + c[3]*T**3
>>> Cp(300)
75.32642000000001

static Gf(counts)

Estimates the ideal-gas Gibbs energy of formation at 298.15 K of an organic compound using the Joback method as a function of chemical structure only.

$$G_{formation} = 53.88 + \sum {G_{f,i}}$$

In the above equation, Gibbs energy of formation is calculated in kJ/mol; it is converted to J/mol here.

328 compounds were used by Joback in this determination, with an absolute average error of 2.0 kcal/mol, standard devaition 4.37 kcal/mol, and AARE of 15.7%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Gffloat

Estimated ideal-gas Gibbs energy of formation at 298.15 K, [J/mol]

Examples

>>> Joback.Gf({1: 2, 24: 1})
-154540.0

static Hf(counts)

Estimates the ideal-gas enthalpy of formation at 298.15 K of an organic compound using the Joback method as a function of chemical structure only.

$$H_{formation} = 68.29 + \sum_i {H_{f,i}}$$

In the above equation, enthalpy of formation is calculated in kJ/mol; it is converted to J/mol here.

370 compounds were used by Joback in this determination, with an absolute average error of 2.2 kcal/mol, standard devaition 2.0 kcal/mol, and AARE of 15.2%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Hffloat

Estimated ideal-gas enthalpy of formation at 298.15 K, [J/mol]

Examples

>>> Joback.Hf({1: 2, 24: 1})
-217830.0

static Hfus(counts)

Estimates the enthalpy of fusion of an organic compound at its melting point using the Joback method as a function of chemical structure only.

$$\Delta H_{fus} = -0.88 + \sum_i H_{fus,i}$$

In the above equation, enthalpy of fusion is calculated in kJ/mol; it is converted to J/mol here.

For 155 compounds tested by Joback, the absolute average error was 485.2 cal/mol and standard deviation was 661.4 cal/mol; the average relative error was 38.7%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Hfusfloat

Estimated enthalpy of fusion of the compound at its melting point, [J/mol]

Examples

>>> Joback.Hfus({1: 2, 24: 1})
5125.0

static Hvap(counts)

Estimates the enthalpy of vaporization of an organic compound at its normal boiling point using the Joback method as a function of chemical structure only.

$$\Delta H_{vap} = 15.30 + \sum_i H_{vap,i}$$

In the above equation, enthalpy of fusion is calculated in kJ/mol; it is converted to J/mol here.

For 368 compounds tested by Joback, the absolute average error was 303.5 cal/mol and standard deviation was 429 cal/mol; the average relative error was 3.88%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Hvapfloat

Estimated enthalpy of vaporization of the compound at its normal boiling point, [J/mol]

Examples

>>> Joback.Hvap({1: 2, 24: 1})
29018.0

static Pc(counts, atom_count)

Estimates the critcal pressure of an organic compound using the Joback method as a function of chemical structure only. This correlation was developed using the actual number of atoms forming the molecule as well.

$$P_c = \left [0.113 + 0.0032N_A - \sum_i {P_{c,i}}\right ]^{-2}$$

In the above equation, critical pressure is calculated in bar; it is converted to Pa here.

392 compounds were used by Joback in this determination, with an absolute average error of 2.06 bar, standard devaition 3.2 bar, and AARE of 5.2%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

atom_countint

Total number of atoms (including hydrogens) in the molecule, [-]

Returns:

Pcfloat

Estimated critical pressure, [Pa]

Examples

>>> Joback.Pc({1: 2, 24: 1}, 10)
4802499.6

static Tb(counts)

Estimates the normal boiling temperature of an organic compound using the Joback method as a function of chemical structure only.

$$T_b = 198.2 + \sum_i {T_{b,i}}$$

For 438 compounds tested by Joback, the absolute average error was 12.91 K and standard deviation was 17.85 K; the average relative error was 3.6%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Tbfloat

Estimated normal boiling temperature, [K]

Examples

>>> Joback.Tb({1: 2, 24: 1})
322.11

static Tc(counts, Tb=None)

Estimates the critcal temperature of an organic compound using the Joback method as a function of chemical structure only, or optionally improved by using an experimental boiling point. If the experimental boiling point is not provided it will be estimated with the Joback method as well.

$$T_c = T_b \left[0.584 + 0.965 \sum_i {T_{c,i}} - \left(\sum_i {T_{c,i}}\right)^2 \right]^{-1}$$

For 409 compounds tested by Joback, the absolute average error was 4.76 K and standard deviation was 6.94 K; the average relative error was 0.81%.

Appendix BI of Joback’s work lists 409 estimated critical temperatures.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Tbfloat, optional

Experimental normal boiling temperature, [K]

Returns:

Tcfloat

Estimated critical temperature, [K]

Examples

>>> Joback.Tc({1: 2, 24: 1}, Tb=322.11)
500.559

static Tm(counts)

Estimates the melting temperature of an organic compound using the Joback method as a function of chemical structure only.

$$T_m = 122.5 + \sum_i {T_{m,i}}$$

For 388 compounds tested by Joback, the absolute average error was 22.6 K and standard deviation was 24.68 K; the average relative error was 11.2%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Tmfloat

Estimated melting temperature, [K]

Examples

>>> Joback.Tm({1: 2, 24: 1})
173.5

static Vc(counts)

Estimates the critcal volume of an organic compound using the Joback method as a function of chemical structure only.

$$V_c = 17.5 + \sum_i {V_{c,i}}$$

In the above equation, critical volume is calculated in cm^3/mol; it is converted to m^3/mol here.

310 compounds were used by Joback in this determination, with an absolute average error of 7.54 cm^3/mol, standard devaition 13.16 cm^3/mol, and AARE of 2.27%.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

Vcfloat

Estimated critical volume, [m^3/mol]

Examples

>>> Joback.Vc({1: 2, 24: 1})
0.0002095

calculated_Cpig_coeffs = None

calculated_mul_coeffs = None

estimate(callables=True)

Method to compute all available properties with the Joback method; returns their results as a dict. For the tempearture dependent values Cpig and mul, both the coefficients and objects to perform calculations are returned.

mul(T)

Computes liquid viscosity at a specified temperature of an organic compound using the Joback method as a function of chemical structure only.

$$\mu_{liq} = \text{MW} \exp\left( \frac{ \sum_i \mu_a - 597.82}{T} + \sum_i \mu_b - 11.202 \right)$$

Parameters:

Tfloat

Temperature, [K]

Returns:

mulfloat

Liquid viscosity, [Pa*s]

Examples

>>> J = Joback('CC(=O)C')
>>> J.mul(300)
0.0002940378347162687

static mul_coeffs(counts)

Computes the liquid phase viscosity Joback coefficients of an organic compound using the Joback method as a function of chemical structure only.

$$\mu_{liq} = \text{MW} \exp\left( \frac{ \sum_i \mu_a - 597.82}{T} + \sum_i \mu_b - 11.202 \right)$$

288 compounds were used by Joback in this determination. No overall error was reported.

The liquid viscosity data used was specified to be at “several temperatures for each compound” only. A small and unspecified number of compounds were used in this estimation.

Parameters:

countsdict

Dictionary of Joback groups present (numerically indexed) and their counts, [-]

Returns:

coefficientslist[float]

Coefficients which will result in a liquid viscosity in in units of Pa*s, [-]

Examples

>>> mu_ab = Joback.mul_coeffs({1: 2, 24: 1})
>>> mu_ab
[839.1099999999998, -14.99]
>>> MW = 58.041864812
>>> mul = lambda T : MW*exp(mu_ab[0]/T + mu_ab[1])
>>> mul(300)
0.0002940378347162687

class thermo.group_contribution.joback.DikyJoback(mol)

Bases: object

Class to estimate ideal-gas heat capacity using the a variant of the Joback method with contributions refit and extended by NIST’s Vladimir Diky, as shown in [1].

The correlation:

$$C_p^o(T) = \sum_{j} N_j \Bigl(A_{0j} + A_{1j} T + A_{2j} T^2 + A_{3j} T^3\Bigr)$$

where:

• The summation is over all first-order groups and exactly one “entity term” as part of the second-order corrections, and ring-size corrections are added for each 3 and 4 size ring.

Parameters:

molrdkit Mol or SMILES str

The molecule to analyze

Attributes:

coeffslist[float] or None

The polynomial coefficients [A0, A1, A2, A3] for calculating Cp. Will be None if molecule fragmentation failed.

statusstr

Status of the group contribution analysis

successbool

Whether all atoms were successfully matched to groups

Methods

Cpig(T)	Computes ideal-gas heat capacity at a specified temperature of an organic compound using the Joback method as a function of chemical structure only.
get_coefficients(counts)	Computes the polynomial coefficients for ideal-gas heat capacity calculation using the Diky-Joback method.

References

[1]

Elliott, J. Richard, Vladimir Diky, Thomas A. Knotts IV, and W. Vincent Wilding. The Properties of Gases and Liquids, Sixth Edition. 6th edition. New York: McGraw Hill, 2023.

Examples

Analysis of Acetone:

>>> J = DikyJoback('CC(=O)C')
>>> J.Cpig(350)
88.33193
>>> J.coeffs
[28.867, 0.1736, 3.19e-06, -3.932e-08]
>>> J.status
'OK'

Cpig(T)

Computes ideal-gas heat capacity at a specified temperature of an organic compound using the Joback method as a function of chemical structure only.

Parameters:

Tfloat

Temperature, [K]

Returns:

Cpigfloat

Ideal-gas heat capacity, [J/mol/K]

Examples

>>> J = DikyJoback('CC(=O)C')
>>> J.Cpig(300)
80.17246

static get_coefficients(counts)

Computes the polynomial coefficients for ideal-gas heat capacity calculation using the Diky-Joback method. The coefficients represent the terms of:

$$C_p^o(T) = A_0 + A_1T + A_2T^2 + A_3T^3$$

Parameters:

countsdict

Dictionary of Diky-Joback groups present and their counts

Returns:

coeffslist[float]

List of four coefficients [A0, A1, A2, A3] which give Cp in J/mol/K when evaluated with temperature in K

Examples

>>> coeffs = DikyJoback.get_coefficients({11: 3, 42: 1, 43: 1})
>>> coeffs
[1.589, 0.19505, 3.09e-06, -5.247e-08]