Chemical Reactions (chemicals.reaction)¶
This module contains lookup functions enthalpies and standard entropies of formation. Lookup functions are availa for the liquid, solid, and gas states. A compound may be in more than one lookup function.
For reporting bugs, adding feature requests, or submitting pull requests, please use the GitHub issue tracker.
Solid Heat of Formation¶
- chemicals.reaction.Hfs(CASRN, method=None)[source]¶
This function handles the retrieval of a chemical’s solid/crystaline standard phase heat of formation. The lookup is based on CASRNs. Will automatically select a data source to use if no method is provided; returns None if the data is not available.
- Parameters
- CASRN
str
CASRN [-]
- CASRN
- Returns
- Hfs
float
Solid standard-state heat of formation, [J/mol]
- Hfs
- Other Parameters
- method
str
,optional
A string for the method name to use, as defined by constants in Hfs_methods
- method
See also
Notes
Sources are:
References
- 1
Haynes, W.M., Thomas J. Bruno, and David R. Lide. CRC Handbook of Chemistry and Physics. [Boca Raton, FL]: CRC press, 2014.
- 2
Shen, V.K., Siderius, D.W., Krekelberg, W.P., and Hatch, H.W., Eds., NIST WebBook, NIST, http://doi.org/10.18434/T4M88Q
Examples
>>> Hfs('101-81-5') # Diphenylmethane 71500.0
- chemicals.reaction.Hfs_methods(CASRN)[source]¶
Return all methods available to obtain the solid-phase heat of formation for the desired chemical.
- Parameters
- CASRN
str
CASRN, [-]
- CASRN
- Returns
See also
- chemicals.reaction.Hfs_all_methods = ('CRC', 'WEBBOOK')¶
Tuple of method name keys. See the Hfs for the actual references
Liquid Heat of Formation¶
- chemicals.reaction.Hfl(CASRN, method=None)[source]¶
This function handles the retrieval of a chemical’s liquid standard phase heat of formation. The lookup is based on CASRNs. Will automatically select a data source to use if no method is provided; returns None if the data is not available.
- Parameters
- CASRN
str
CASRN [-]
- CASRN
- Returns
- Hfl
float
Liquid standard-state heat of formation, [J/mol]
- Hfl
- Other Parameters
- method
str
,optional
A string for the method name to use, as defined in the variable, Hfl_all_methods.
- method
See also
Notes
Sources are:
References
- 1
Ruscic, Branko, Reinhardt E. Pinzon, Gregor von Laszewski, Deepti Kodeboyina, Alexander Burcat, David Leahy, David Montoy, and Albert F. Wagner. “Active Thermochemical Tables: Thermochemistry for the 21st Century.” Journal of Physics: Conference Series 16, no. 1 (January 1, 2005): 561. doi:10.1088/1742-6596/16/1/078.
- 2
Haynes, W.M., Thomas J. Bruno, and David R. Lide. CRC Handbook of Chemistry and Physics. [Boca Raton, FL]: CRC press, 2014.
- 3
Shen, V.K., Siderius, D.W., Krekelberg, W.P., and Hatch, H.W., Eds., NIST WebBook, NIST, http://doi.org/10.18434/T4M88Q
Examples
>>> Hfl('67-56-1') -238400.0
- chemicals.reaction.Hfl_methods(CASRN)[source]¶
Return all methods available to obtain the standard liquid-state heat of formation for the desired chemical.
- Parameters
- CASRN
str
CASRN, [-]
- CASRN
- Returns
See also
- chemicals.reaction.Hfl_all_methods = ('ATCT_L', 'CRC', 'WEBBOOK', 'JANAF')¶
Tuple of method name keys. See the Hfl for the actual references
Gas Heat of Formation¶
- chemicals.reaction.Hfg(CASRN, method=None)[source]¶
This function handles the retrieval of a chemical’s gas heat of formation. Lookup is based on CASRNs. Will automatically select a data source to use if no method is provided; returns None if the data is not available.
- Parameters
- CASRN
str
CASRN [-]
- CASRN
- Returns
- Hfg
float
Ideal gas phase heat of formation, [J/mol]
- Hfg
- Other Parameters
- method
str
,optional
A string for the method name to use, as defined by constants in Hfg_methods
- method
See also
Notes
Function has data for approximately 8700 chemicals. Sources are:
‘ATCT_G’, the Active Thermochemical Tables version 1.112 (600 values) [1]
‘TRC’, from a 1994 compilation (1750 values) [2]
‘CRC’, from the CRC handbook (1360 values) [3]
‘WEBBOOK’, a NIST resource [6] containing mostly experimental and averaged values
‘JANAF’, the 1998 JANAF values online
‘JOBACK’, an estimation method for organic substances in [5]
‘YAWS’, a large compillation of values, mostly estimated (5000 values) [4]
‘TRC’ data may have come from computational procedures, for example petane is off by 30%.
References
- 1
Ruscic, Branko, Reinhardt E. Pinzon, Gregor von Laszewski, Deepti Kodeboyina, Alexander Burcat, David Leahy, David Montoy, and Albert F. Wagner. “Active Thermochemical Tables: Thermochemistry for the 21st Century.” Journal of Physics: Conference Series 16, no. 1 (January 1, 2005): 561. doi:10.1088/1742-6596/16/1/078.
- 2
Frenkel`, M. L, Texas Engineering Experiment Station, and Thermodynamics Research Center. Thermodynamics of Organic Compounds in the Gas State. College Station, Tex.: Thermodynamics Research Center, 1994.
- 3
Haynes, W.M., Thomas J. Bruno, and David R. Lide. CRC Handbook of Chemistry and Physics. [Boca Raton, FL]: CRC press, 2014.
- 4
Yaws, Carl L. Thermophysical Properties of Chemicals and Hydrocarbons, Second Edition. Amsterdam Boston: Gulf Professional Publishing, 2014.
- 5
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.
- 6
Shen, V.K., Siderius, D.W., Krekelberg, W.P., and Hatch, H.W., Eds., NIST WebBook, NIST, http://doi.org/10.18434/T4M88Q
Examples
>>> Hfg('67-56-1') -200700.0 >>> Hfg('67-56-1', method='YAWS') -200900.0 >>> Hfg('67-56-1', method='CRC') -201000.0 >>> Hfg('67-56-1', method='TRC') -190100.0
- chemicals.reaction.Hfg_methods(CASRN)[source]¶
Return all methods available to obtain the gas phase heat of formation for the desired chemical.
- Parameters
- CASRN
str
CASRN, [-]
- CASRN
- Returns
See also
- chemicals.reaction.Hfg_all_methods = ('ATCT_G', 'TRC', 'CRC', 'WEBBOOK', 'JANAF', 'YAWS', 'JOBACK')¶
Tuple of method name keys. See the Hfg for the actual references
Solid Absolute Entropy¶
- chemicals.reaction.S0s(CASRN, method=None)[source]¶
This function handles the retrieval of a chemical’s absolute entropy at a reference temperature of 298.15 K and pressure of 1 bar, in the solid state. Lookup is based on CASRNs. Will automatically select a data source to use if no method is provided; returns None if the data is not available.
- Parameters
- CASRN
str
CASRN [-]
- CASRN
- Returns
- S0s
float
Ideal gas standard absolute entropy of compound, [J/mol/K]
- S0s
- Other Parameters
- method
str
,optional
A string for the method name to use, as defined by constants in S0s_all_methods.
- method
See also
Notes
Sources are:
References
- 1
Haynes, W.M., Thomas J. Bruno, and David R. Lide. CRC Handbook of Chemistry and Physics. [Boca Raton, FL]: CRC press, 2014.
- 2
Shen, V.K., Siderius, D.W., Krekelberg, W.P., and Hatch, H.W., Eds., NIST WebBook, NIST, http://doi.org/10.18434/T4M88Q
Examples
>>> S0s('7439-93-2') # Lithium 29.1
- chemicals.reaction.S0s_methods(CASRN)[source]¶
Return all methods available to obtain the absolute entropy of the compound in the solid phase for the desired chemical.
- Parameters
- CASRN
str
CASRN, [-]
- CASRN
- Returns
See also
- chemicals.reaction.S0s_all_methods = ('CRC', 'WEBBOOK')¶
Tuple of method name keys. See the S0s for the actual references
Liquid Absolute Entropy¶
- chemicals.reaction.S0l(CASRN, method=None)[source]¶
This function handles the retrieval of a chemical’s absolute entropy at a reference temperature of 298.15 K and pressure of 1 bar, in the liquid state.
Lookup is based on CASRNs. Will automatically select a data source to use if no method is provided; returns None if the data is not available.
- Parameters
- CASRN
str
CASRN [-]
- CASRN
- Returns
- S0l
float
Ideal gas standard absolute entropy of compound, [J/mol/K]
- S0l
- Other Parameters
- method
str
,optional
A string for the method name to use, as defined in the variable, S0l_all_methods.
- method
See also
Notes
Sources are:
‘CRC’, from the CRC handbook
References
- 1
Haynes, W.M., Thomas J. Bruno, and David R. Lide. CRC Handbook of Chemistry and Physics. [Boca Raton, FL]: CRC press, 2014.
Examples
>>> S0l('7439-97-6') # Mercury 75.9
- chemicals.reaction.S0l_methods(CASRN)[source]¶
Return all methods available to obtain the absolute entropy for the desired chemical.
- Parameters
- CASRN
str
CASRN, [-]
- CASRN
- Returns
See also
- chemicals.reaction.S0l_all_methods = ('CRC', 'WEBBOOK', 'JANAF')¶
Tuple of method name keys. See the S0l for the actual references
Gas Absolute Entropy¶
- chemicals.reaction.S0g(CASRN, method=None)[source]¶
This function handles the retrieval of a chemical’s absolute entropy at a reference temperature of 298.15 K and pressure of 1 bar, in the ideal gas state.
Lookup is based on CASRNs. Will automatically select a data source to use if no method is provided; returns None if the data is not available.
- Parameters
- CASRN
str
CASRN [-]
- CASRN
- Returns
- S0g
float
Ideal gas standard absolute entropy of compound, [J/mol/K]
- S0g
- Other Parameters
- method
str
,optional
A string for the method name to use, as defined in the variable, S0g_all_methods
- method
See also
Notes
Function has data for approximately 5400 chemicals. Sources are:
‘CRC’, from the CRC handbook (520 values)
‘YAWS’, a large compillation of values, mostly estimated (4890 values)
‘WEBBOOK’, a NIST resource [3] containing mostly experimental and averaged values
References
- 1
Haynes, W.M., Thomas J. Bruno, and David R. Lide. CRC Handbook of Chemistry and Physics. [Boca Raton, FL]: CRC press, 2014.
- 2
Yaws, Carl L. Thermophysical Properties of Chemicals and Hydrocarbons, Second Edition. Amsterdam Boston: Gulf Professional Publishing, 2014.
- 3
Shen, V.K., Siderius, D.W., Krekelberg, W.P., and Hatch, H.W., Eds., NIST WebBook, NIST, http://doi.org/10.18434/T4M88Q
Examples
>>> S0g('67-56-1') 239.9 >>> S0g('67-56-1', method='YAWS') 239.88
- chemicals.reaction.S0g_methods(CASRN)[source]¶
Return all methods available to obtain the S0g for the desired chemical.
- Parameters
- CASRN
str
CASRN, [-]
- CASRN
- Returns
See also
- chemicals.reaction.S0g_all_methods = ('CRC', 'WEBBOOK', 'JANAF', 'YAWS')¶
Tuple of method name keys. See the S0g for the actual references
Utility Functions¶
- chemicals.reaction.Gibbs_formation(dHf, S0_abs, dHfs_std, S0_abs_elements, coeffs_elements, T_ref=298.15)[source]¶
This function calculates the Gibbs free energy of formation of a compound, from its constituent elements.
The calculated value will be for a “standard-state” value if dHf and S0_abs are provided in the standard state; or it will be in an “ideal gas” basis if they are both for an ideal gas. For compounds which are gases at STP, the two values are the same.
- Parameters
- dHf
float
Molar enthalpy of formation of the created compound, [J/mol]
- S0_abs
float
Absolute molar entropy of the created compound at the reference temperature, [J/mol/K]
- dHfs_std
list
[float
] List of standard molar enthalpies of formation of all elements used in the formation of the created compound, [J/mol]
- S0_abs_elements
list
[float
] List of standard absolute molar entropies at the reference temperature of all elements used in the formation of the created compound, [J/mol/K]
- coeffs_elements
list
[float
] List of coefficients for each compound (i.e. 1 for C, 2 for H2 if the target is methane), in the same order as dHfs_std and S0_abs_elements, [-]
- T_ref
float
,optional
The standard state temperature, default 298.15 K; few values are tabulated at other temperatures, [-]
- dHf
- Returns
- dGf
float
Gibbs free energy of formation for the created compound, [J/mol]
- dGf
Notes
Be careful for elements like Bromine - is the tabulated value for Br2 or Br?
References
- 1
“Standard Gibbs Free Energy of Formation Calculations Chemistry Tutorial.” Accessed March, 2019. https://www.ausetute.com.au/gibbsform.html.
Examples
Calculate the standard-state Gibbs free energy of formation for water, using water’s standard state heat of formation and absolute entropy at 298.15 K:
>>> Gibbs_formation(-285830, 69.91, [0, 0], [130.571, 205.147], [1, .5]) -237161.633825
Calculate the ideal-gas state Gibbs free energy of formation for water, using water’s ideal-gas state heat of formation and absolute entropy at 298.15 K as a gas:
>>> Gibbs_formation(-241818, 188.825, [0, 0], [130.571, 205.147], [1, .5]) -228604.141075
Calculate the Gibbs free energy of formation for CBrF3 (it is a gas at STP, so its standard-state and ideal-gas state values are the same) at 298.15 K:
>>> Gibbs_formation(-648980, 297.713, [0, 0, 0], [5.74, 152.206, 202.789], [1, .5, 1.5]) -622649.329975
Note in the above calculation that the Bromine’s S0 and Hf are for Br2; and that the value for Bromine as a liquid, which is its standard state, is used.
- chemicals.reaction.entropy_formation(Hf, Gf, T_ref=298.15)[source]¶
This function calculates the entropy of formation of a compound, from its constituent elements.
The calculated value will be for a “standard-state” value if Hf and Gf are provided in the standard state; or it will be in an “ideal gas” basis if they are both for an ideal gas. For compounds which are gases at STP, the two values are the same.
- Parameters
- Returns
- S0
float
Entropy of formation of the compound, [J/mol/K]
- S0
Examples
Entropy of formation of methane:
>>> entropy_formation(Hf=-74520, Gf=-50490) -80.59701492537314
Entropy of formation of water in ideal gas state:
>>> entropy_formation(Hf=-241818, Gf=-228572) -44.427301693778304
- chemicals.reaction.Hf_basis_converter(Hvapm, Hf_liq=None, Hf_gas=None)[source]¶
This function converts a liquid or gas enthalpy of formation to the other. This is useful, as thermodynamic packages often work with ideal- gas as the reference state and require ideal-gas enthalpies of formation.
- Parameters
- Returns
- Hf_calc
float
,optional
Enthalpy of formation of the compound in the other state to the one provided, [J/mol]
- Hf_calc
Examples
Calculate the ideal-gas enthalpy of formation for water, from its standard- state (liquid) value:
>>> Hf_basis_converter(44018, Hf_liq=-285830) -241812
Calculate the standard-state (liquid) enthalpy of formation for water, from its ideal-gas value:
>>> Hf_basis_converter(44018, Hf_gas=-241812) -285830
Chemical Reactions¶
- chemicals.reaction.balance_stoichiometry(matrix, rounding=9, allow_fractional=False)[source]¶
This function balances a chemical reaction.
- Parameters
- Returns
Notes
Balance the reaction 4 NH3 + 5 O2 = 4 NO + 6 H2O, without knowing the coefficients:
>>> matrix = stoichiometric_matrix([{'N': 1, 'H': 3}, {'O': 2}, {'N': 1, 'O': 1}, {'H': 2, 'O': 1}], [True, True, False, False]) >>> matrix [[3, 0, 0, -2], [1, 0, -1, 0], [0, 2, -1, -1]] >>> balance_stoichiometry(matrix) [4.0, 5.0, 4.0, 6.0] >>> balance_stoichiometry(matrix, allow_fractional=True) [1.0, 1.25, 1.0, 1.5]
This algorithm relies on scipy. The behavior of this function for inputs which do not have a unique solution is undefined.
This algorithm may suffer from floating point issues. If you believe there is an error in the result, please report your reaction to the developers.
References
- 1
Sen, S. K., Hans Agarwal, and Sagar Sen. “Chemical Equation Balancing: An Integer Programming Approach.” Mathematical and Computer Modelling 44, no. 7 (October 1, 2006): 678-91. https://doi.org/10.1016/j.mcm.2006.02.004.
- 2
URAVNOTE, NOVOODKRITI PARADOKSI V. TEORIJI, and ENJA KEMIJSKIH REAKCIJ. “New Discovered Paradoxes in Theory of Balancing Chemical Reactions.” Materiali in Tehnologije 45, no. 6 (2011): 503-22.
- chemicals.reaction.stoichiometric_matrix(atomss, reactants)[source]¶
This function calculates a stoichiometric matrix of reactants and stoichiometric matrix, as required by a solver to compute the reation coefficients.
- Parameters
- Returns
Notes
The rows of the matrix contain the element counts of each compound, and the columns represent each chemical.
References
- 1
Sen, S. K., Hans Agarwal, and Sagar Sen. “Chemical Equation Balancing: An Integer Programming Approach.” Mathematical and Computer Modelling 44, no. 7 (October 1, 2006): 678-91. https://doi.org/10.1016/j.mcm.2006.02.004.
- 2
URAVNOTE, NOVOODKRITI PARADOKSI V. TEORIJI, and ENJA KEMIJSKIH REAKCIJ. “New Discovered Paradoxes in Theory of Balancing Chemical Reactions.” Materiali in Tehnologije 45, no. 6 (2011): 503-22.
Examples
MgO2 -> Mg + 1/2 O2 (k=1)
>>> stoichiometric_matrix([{'Mg': 1, 'O': 1}, {'Mg': 1}, {'O': 2}], [True, False, False]) [[1, -1, 0], [1, 0, -2]]
Cl2 + propylene -> allyl chloride + HCl
>>> stoichiometric_matrix([{'Cl': 2}, {'C': 3, 'H': 6}, {'C': 3, 'Cl': 1, 'H': 5}, {'Cl': 1, 'H': 1}], [True, True, False, False, False]) [[0, 3, -3, 0], [2, 0, -1, -1], [0, 6, -5, -1]]
Al + 4HNO3 -> Al(NO3)3 + NO + 2H2O (k=1)
>>> stoichiometric_matrix([{'Al': 1}, {'H': 1, 'N': 1, 'O': 3}, {'Al': 1, 'N': 3, 'O': 9}, {'N': 1, 'O': 1}, {'H': 2, 'O': 1}], [True, True, False, False, False]) [[1, 0, -1, 0, 0], [0, 1, 0, 0, -2], [0, 1, -3, -1, 0], [0, 3, -9, -1, -1]]
4Fe + 3O2 -> 2(Fe2O3) (k=2)
>>> stoichiometric_matrix([{'Fe': 1}, {'O': 2}, {'Fe':2, 'O': 3}], [True, True, False]) [[1, 0, -2], [0, 2, -3]]
4NH3 + 5O2 -> 4NO + 6(H2O) (k=4)
>>> stoichiometric_matrix([{'N': 1, 'H': 3}, {'O': 2}, {'N': 1, 'O': 1}, {'H': 2, 'O': 1}], [True, True, False, False]) [[3, 0, 0, -2], [1, 0, -1, 0], [0, 2, -1, -1]]
No unique solution: C2H5NO2 + C3H7NO3 + 2C6H14N4O2 + 3C5H9NO2 + 2C9H11NO2 -> 8H2O + C50H73N15O11
>>> stoichiometric_matrix([{'C': 2, 'H': 5, 'N': 1, 'O': 2}, {'C': 3, 'H': 7, 'N': 1, 'O': 3}, {'C': 6, 'H': 14, 'N': 4, 'O': 2}, {'C': 5, 'H': 9, 'N': 1, 'O': 2}, {'C': 9, 'H': 11, 'N': 1, 'O': 2}, {'H': 2, 'O': 1}, {'C': 50, 'H': 73, 'N': 15, 'O': 11}], [True, True, True, True, True, False, False]) [[2, 3, 6, 5, 9, 0, -50], [5, 7, 14, 9, 11, -2, -73], [1, 1, 4, 1, 1, 0, -15], [2, 3, 2, 2, 2, -1, -11]]
- chemicals.reaction.stoichiometry_mass_to_molar(mass_coefficients, MWs)[source]¶
This function translates mass stoichiometric coefficients into the more commonly used mole-based stoichiometric coefficients.
- Parameters
- Returns
Notes
>>> stoichiometry_mass_to_molar([68.12208, 159.994, 120.0244, 108.09168], [17.03052, 31.9988, 30.0061, 18.01528]) [4.0, 5.0, 4.0, 6.0]
- chemicals.reaction.stoichiometry_molar_to_mass(coefficients, MWs)[source]¶
This function translates molar stoichiometric coefficients (most commonly used) into less commonly used mass-based stoichiometric coefficients.
- Parameters
- Returns
Notes
Note that mass-based reactions are usually not normalized to integers. Mass-based coefficients are used with components that don’t have well defined formulas.
Calculate the mass based coefficients for the reaction 4 NH3 + 5 O2 = 4 NO + 6 H2O:
>>> matrix = stoichiometric_matrix([{'N': 1, 'H': 3}, {'O': 2}, {'N': 1, 'O': 1}, {'H': 2, 'O': 1}], [True, True, False, False]) >>> coeffs = balance_stoichiometry(matrix) >>> stoichiometry_molar_to_mass(coeffs, [17.03052, 31.9988, 30.0061, 18.01528]) [68.12208, 159.994, 120.0244, 108.09168]
- chemicals.reaction.stoichiometry_MW_error(coefficients, MWs, reactants)[source]¶
This function calculates the molecular weight imbalance of a reaction given the coefficients and molecular weights of the involved components, and their statuses as reactants or product.
- Parameters
- coefficients
list
[float
] Molar balanced stoichiometric coefficients; all numbers are positive, [-]
- MWs
list
[float
] Molecular weights of all species in reaction ordered in the same way as the coefficients, [g/mol]
- reactants
list
[bool] List of booleans indicating whether each chemical is a reactant (True) or a product (False), [-]
- coefficients
- Returns
- MW_error
float
The molecular weight error, [g/mol]
- MW_error
Notes
A very small value may be returned for a properly balanced equation because of floating-point error.
>>> stoichiometry_MW_error([4.0, 5.0, 4.0, 6.0], [17.03052, 31.9988, 30.0061, 18.01528], [True, True, False, False]) 0.0
- chemicals.reaction.standard_formation_reaction(atoms)[source]¶
This function calculates the standard reaction to reduce a chemical compound to its standard state elements. Any hydrogen in the compound is transformed to H2; oxygen to O2; carbon to graphite (single C), calcium to Ca, etc.
- Parameters
- Returns
- reactant_coeff
float
The coefficient of the reactant; for compounds like CO that do not divide evenly, this will be something other than 1 [-]
- elemental_counts
list
[float
] Balanced coefficients of each of the products, [-]
- product_atomss
list
[dict
[(str
,float
)]] A list of dictionaries of the elements produced, and how many atoms of each element are in one unit of the element in its standard form. Each dictionary contains a single key:value, with the key being the element and the value being either 1 or 2 depending on the standard state [-]
- reactant_coeff
Examples
Methane
>>> standard_formation_reaction({'C': 1, 'H': 4}) (1.0, [1.0, 2.0], [{'C': 1}, {'H': 2}])
Carbon monoxide
>>> standard_formation_reaction({'C': 1, 'O': 1}) (2.0, [2.0, 1.0], [{'C': 1}, {'O': 2}])
Methylamine
>>> standard_formation_reaction({'C': 1, 'H': 5, 'N': 1}) (2.0, [2.0, 5.0, 1.0], [{'C': 1}, {'H': 2}, {'N': 2}])