chempy package

ChemPy is a Python package useful for solving problems in chemistry.

Subpackages

Submodules

chempy.arrhenius module

chempy.chemistry module

class chempy.chemistry.Equilibrium(reac, prod, param=None, inact_reac=None, inact_prod=None, name=None, ref=None, data=None, checks=None, dont_check=None)[source]

Bases: chempy.chemistry.Reaction

Represents an equilibrium reaction

See Reaction for parameters

Methods

K(\*args, \*\*kwargs)

K is deprecated.

Q(self, substances, concs)

Calculates the equilibrium qoutient

active_prod_stoich(self, substances)

Per substance product stoichiometry tuple (active)

active_reac_stoich(self, substances)

Per substance reactant stoichiometry tuple (active)

all_prod_stoich(self, substances)

Per substance product stoichiometry tuple (active & inactive)

all_reac_stoich(self, substances)

Per substance reactant stoichiometry tuple (active & inactive)

as_reactions(self[, kf, kb, units, …])

Creates a forward and backward Reaction pair

cancel(self, rxn)

Multiplier of how many times rxn can be added/subtracted.

charge_neutrality_violation(self, substances)

Net amount of charge produced

check_all_integral(self[, throw])

Checks if all stoichiometric coefficents are integers

check_all_positive(self[, throw])

Checks if all stoichiometric coefficients are positive

check_any_effect(self[, throw])

Checks if the reaction has any effect

composition_violation(self, substances[, …])

Net amount of constituent produced

eliminate(rxns, wrt)

Linear combination coefficients for elimination of a substance

equilibrium_constant(self[, variables, backend])

Return equilibrium constant

equilibrium_expr(self)

Turns self.param into a EqExpr instance (if not already)

from_string(string[, substance_keys, globals_])

Parses a string into a Reaction instance

html(self, substances[, with_param, with_name])

Returns a HTML representation of the reaction

latex(self, substances[, with_param, with_name])

Returns a LaTeX representation of the reaction

mass_balance_violation(self, substances)

Net amount of mass produced

net_stoich(self, substance_keys)

Per substance net stoichiometry tuple (active & inactive)

non_precipitate_stoich(self, substances)

Only stoichiometry of non-precipitates

order(self)

Sum of (active) reactant stoichiometries

precipitate_stoich(self, substances)

Only stoichiometry of precipitates

rate(self[, variables, backend, …])

Evaluate the rate of a reaction

rate_expr(self)

Turns self.param into a RateExpr instance (if not already)

string(self[, substances, with_param, with_name])

Returns a string representation of the reaction

unicode(self, substances[, with_param, …])

Returns a unicode string representation of the reaction

check_consistent_units

copy

dimensionality

equilibrium_equation

has_precipitates

keys

precipitate_factor

K(*args, **kwargs)[source]

K is deprecated. Use equilibrium_constant instead.

Q(self, substances, concs)[source]

Calculates the equilibrium qoutient

as_reactions(self, kf=None, kb=None, units=None, variables=None, backend=<module 'math' (built-in)>, new_name=None, **kwargs)[source]

Creates a forward and backward Reaction pair

Parameters
kffloat or RateExpr
kbfloat or RateExpr
unitsmodule
variablesdict, optional
backendmodule
cancel(self, rxn)[source]

Multiplier of how many times rxn can be added/subtracted.

Parameters
rxnEquilibrium

Examples

>>> e1 = Equilibrium({'Cd(OH)2(s)': 4, 'H2O': 4},
...                  {'Cd4(OH)4+4': 1, 'H+': 4, 'OH-': 8}, 7.94e-91)
>>> e2 = Equilibrium({'H2O': 1}, {'H+': 1, 'OH-': 1}, 10**-14)
>>> e1.cancel(e2)
-4
>>> print(e1 - 4*e2)
4 Cd(OH)2(s) = Cd4(OH)4+4 + 4 OH-; 7.94e-35
check_consistent_units(self, throw=False)[source]
dimensionality(self, substances)[source]
static eliminate(rxns, wrt)[source]

Linear combination coefficients for elimination of a substance

Parameters
rxnsiterable of Equilibrium instances
wrtstr (substance key)

Examples

>>> e1 = Equilibrium({'Cd+2': 4, 'H2O': 4}, {'Cd4(OH)4+4': 1, 'H+': 4}, 10**-32.5)
>>> e2 = Equilibrium({'Cd(OH)2(s)': 1}, {'Cd+2': 1, 'OH-': 2}, 10**-14.4)
>>> Equilibrium.eliminate([e1, e2], 'Cd+2')
[1, 4]
>>> print(1*e1 + 4*e2)
4 Cd(OH)2(s) + 4 H2O = Cd4(OH)4+4 + 4 H+ + 8 OH-; 7.94e-91
equilibrium_constant(self, variables=None, backend=<module 'math' (built-in)>)[source]

Return equilibrium constant

Parameters
variablesdict, optional
backendmodule, optional
equilibrium_equation(self, variables, backend=None, **kwargs)[source]
equilibrium_expr(self)[source]

Turns self.param into a EqExpr instance (if not already)

Examples

>>> r = Equilibrium.from_string('2 A + B = 3 C; 7')
>>> eqex = r.equilibrium_expr()
>>> eqex.args[0] == 7
True
param_char = 'K'
precipitate_factor(self, substances, sc_concs)[source]
class chempy.chemistry.Reaction(reac, prod, param=None, inact_reac=None, inact_prod=None, name=None, ref=None, data=None, checks=None, dont_check=None)[source]

Bases: object

Class representing a chemical reaction

Consider for example:

2 R –> A + P; r = k*A*R*R

this would be represented as Reaction({'A': 1, 'R': 2}, {'A': 2, 'P': 1}, param=k). Some reactions have a larger stoichiometric coefficient than what appears in the rate expression, e.g.:

5 A + B –> C; r = k*A*B

this can be represented as Reaction({'C1': 1, 'C2': 1}, {'B': 1}, inact_reac={'C1': 4}, param=k).

The rate constant information in param may be a subclass of chempy.kinetics.rates.RateExpr or carry a as_RateExpr(), if neither: param will be assumed to be a rate constant for a mass-action type of kinetic expression.

Additional data may be stored in the data dict.

Parameters
reacdict (str -> int)

If reac is a set, then multiplicities are assumed to be 1.

proddict (str -> int)

If prod is a set, then multiplicities are assumed to be 1.

paramfloat or callable

Special case (side-effect): if param is a subclass of kinetics.rates.RateExpr and its rxn is None it will be set to self.

inact_reacdict (optional)
inact_proddict (optional)
namestr (optional)
kdeprecated (alias for param)
refobject

Reference (e.g. a string containing doi number).

datadict (optional)
checksiterable of str

Raises ValueError if any method check_%s returns False for all %s in checks. Default: Reaction.default_checks.

Examples

>>> r = Reaction({'H2': 2, 'O2': 1}, {'H2O': 2})
>>> r.keys() == {'H2', 'O2', 'H2O'}
True
>>> r.order()
3
>>> r.net_stoich(['H2', 'H2O', 'O2'])
(-2, 2, -1)
>>> print(r)
2 H2 + O2 -> 2 H2O
Attributes
reacOrderedDict
prodOrderedDict
paramobject
inact_reacOrderedDict
inact_prodOrderedDict
namestr
refstr
datadict

Methods

active_prod_stoich(self, substances)

Per substance product stoichiometry tuple (active)

active_reac_stoich(self, substances)

Per substance reactant stoichiometry tuple (active)

all_prod_stoich(self, substances)

Per substance product stoichiometry tuple (active & inactive)

all_reac_stoich(self, substances)

Per substance reactant stoichiometry tuple (active & inactive)

charge_neutrality_violation(self, substances)

Net amount of charge produced

check_all_integral(self[, throw])

Checks if all stoichiometric coefficents are integers

check_all_positive(self[, throw])

Checks if all stoichiometric coefficients are positive

check_any_effect(self[, throw])

Checks if the reaction has any effect

composition_violation(self, substances[, …])

Net amount of constituent produced

from_string(string[, substance_keys, globals_])

Parses a string into a Reaction instance

html(self, substances[, with_param, with_name])

Returns a HTML representation of the reaction

latex(self, substances[, with_param, with_name])

Returns a LaTeX representation of the reaction

mass_balance_violation(self, substances)

Net amount of mass produced

net_stoich(self, substance_keys)

Per substance net stoichiometry tuple (active & inactive)

non_precipitate_stoich(self, substances)

Only stoichiometry of non-precipitates

order(self)

Sum of (active) reactant stoichiometries

precipitate_stoich(self, substances)

Only stoichiometry of precipitates

rate(self[, variables, backend, …])

Evaluate the rate of a reaction

rate_expr(self)

Turns self.param into a RateExpr instance (if not already)

string(self[, substances, with_param, with_name])

Returns a string representation of the reaction

unicode(self, substances[, with_param, …])

Returns a unicode string representation of the reaction

check_consistent_units

copy

has_precipitates

keys

active_prod_stoich(self, substances)[source]

Per substance product stoichiometry tuple (active)

active_reac_stoich(self, substances)[source]

Per substance reactant stoichiometry tuple (active)

all_prod_stoich(self, substances)[source]

Per substance product stoichiometry tuple (active & inactive)

all_reac_stoich(self, substances)[source]

Per substance reactant stoichiometry tuple (active & inactive)

charge_neutrality_violation(self, substances)[source]

Net amount of charge produced

Parameters
substances: dict
Returns
float: amount of net charge produced/consumed
check_all_integral(self, throw=False)[source]

Checks if all stoichiometric coefficents are integers

check_all_positive(self, throw=False)[source]

Checks if all stoichiometric coefficients are positive

check_any_effect(self, throw=False)[source]

Checks if the reaction has any effect

check_consistent_units(self, throw=False)[source]
composition_violation(self, substances, composition_keys=None)[source]

Net amount of constituent produced

If composition keys correspond to conserved entities e.g. atoms in chemical reactions, this function should return a list of zeros.

Parameters
substancesdict
composition_keysiterable of str, None or True

When None or True: composition keys are taken from substances. When True the keys are also return as an extra return value

Returns
  • If composition_keys == True: a tuple: (violations, composition_keys)
  • Otherwise: violations (list of coefficients)
copy(self, **kwargs)[source]
default_checks = {'all_integral', 'all_positive', 'any_effect', 'consistent_units'}
classmethod from_string(string, substance_keys=None, globals_=None, **kwargs)[source]

Parses a string into a Reaction instance

Parameters
stringstr

String representation of the reaction.

substance_keysconvertible to iterable of strings or string or None

Used prevent e.g. misspelling. if str: split is invoked, if None: no checking done.

globals_dict (optional)

Dictionary for eval for (default: None -> {‘chempy’: chempy}) If False: no eval will be called (useful for web-apps).

**kwargs :

Passed on to constructor.

Notes

chempy.util.parsing.to_reaction() is used which in turn calls eval() which is a severe security concern for untrusted input.

Examples

>>> r = Reaction.from_string("H2O -> H+ + OH-; 1e-4", 'H2O H+ OH-')
>>> r.reac == {'H2O': 1} and r.prod == {'H+': 1, 'OH-': 1}
True
>>> r2 = Reaction.from_string("2 H2O -> 2 H2 + O2", 'H2O H2 O2')
>>> r2.reac == {'H2O': 2} and r2.prod == {'H2': 2, 'O2': 1}
True
>>> r3 = Reaction.from_string("A -> B; 1/second", 'A B')
>>> from chempy.units import to_unitless, default_units as u
>>> to_unitless(r3.param, u.hour**-1)
3600.0
>>> r4 = Reaction.from_string("A -> 2 B; 'k'", 'A B')
>>> r4.rate(dict(A=3, B=5, k=7)) == {'A': -3*7, 'B': 2*3*7}
True
>>> r5 = Reaction.from_string("A -> B; 1/molar/second", 'A B')
Traceback (most recent call last):
    ...
ValueError: Unable to convert between units ...
has_precipitates(self, substances)[source]
html(self, substances, with_param=False, with_name=False, **kwargs)[source]

Returns a HTML representation of the reaction

Examples

>>> keys = 'H2O H+ OH-'.split()
>>> subst = {k: Substance.from_formula(k) for k in keys}
>>> r = Reaction.from_string("H2O -> H+ + OH-; 1e-4", subst)
>>> r.html(subst)
'H<sub>2</sub>O &rarr; H<sup>+</sup> + OH<sup>-</sup>'
>>> r2 = Reaction.from_string("H+ + OH- -> H2O; 1e8/molar/second", subst)
>>> r2.html(subst, with_param=True)
'H<sup>+</sup> + OH<sup>-</sup> &rarr; H<sub>2</sub>O&#59; 10<sup>8</sup> 1/(s*M)'
keys(self)[source]
latex(self, substances, with_param=False, with_name=False, **kwargs)[source]

Returns a LaTeX representation of the reaction

Parameters
substances: dict

mapping substance keys to Substance instances

with_param: bool

whether to print the parameter (default: False)

with_name: bool

whether to print the name (default: False)

Examples

>>> keys = 'H2O H+ OH-'.split()
>>> subst = {k: Substance.from_formula(k) for k in keys}
>>> r = Reaction.from_string("H2O -> H+ + OH-; 1e-4", subst)
>>> r.latex(subst) == r'H_{2}O \rightarrow H^{+} + OH^{-}'
True
>>> r2 = Reaction.from_string("H+ + OH- -> H2O; 1e8/molar/second", subst)
>>> ref = r'H^{+} + OH^{-} \rightarrow H_{2}O; 10^{8} $\mathrm{\frac{1}{(s{\cdot}M)}}$'
>>> r2.latex(subst, with_param=True) == ref
True
mass_balance_violation(self, substances)[source]

Net amount of mass produced

Parameters
substances: dict
Returns
float: amount of net mass produced/consumed
net_stoich(self, substance_keys)[source]

Per substance net stoichiometry tuple (active & inactive)

non_precipitate_stoich(self, substances)[source]

Only stoichiometry of non-precipitates

order(self)[source]

Sum of (active) reactant stoichiometries

param_char = 'k'
precipitate_stoich(self, substances)[source]

Only stoichiometry of precipitates

rate(self, variables=None, backend=<module 'math' (built-in)>, substance_keys=None, ratex=None)[source]

Evaluate the rate of a reaction

Parameters
variablesdict
backendmodule, optional
substance_keysiterable of str, optional
ratexRateExpr
Returns
Dictionary mapping substance keys to the reactions contribution to overall rates.

Examples

>>> rxn1 = Reaction.from_string('2 H2 + O2 -> 2 H2O; 3')
>>> ref1 = 3*5*5*7
>>> rxn1.rate({'H2': 5, 'O2': 7}) == {'H2': -2*ref1, 'O2': -ref1, 'H2O': 2*ref1}
True
>>> from sympy import Symbol
>>> k = Symbol('k')
>>> rxn2 = Reaction(rxn1.reac, rxn1.prod, k)
>>> concentrations = {key: Symbol(key) for key in set.union(set(rxn1.reac), set(rxn1.prod))}
>>> import pprint
>>> pprint.pprint(rxn2.rate(concentrations))
{'H2': -2*H2**2*O2*k, 'H2O': 2*H2**2*O2*k, 'O2': -H2**2*O2*k}
rate_expr(self)[source]

Turns self.param into a RateExpr instance (if not already)

Default is to create a MassAction instance. The parameter will be used as single instance in unique_keys if it is a string, otherwise it will be used as args.

Examples

>>> r = Reaction.from_string('2 A + B -> 3 C; 7')
>>> ratex = r.rate_expr()
>>> ratex.args[0] == 7
True
string(self, substances=None, with_param=False, with_name=False, **kwargs)[source]

Returns a string representation of the reaction

Parameters
substances: dict

mapping substance keys to Substance instances

with_param: bool

whether to print the parameter (default: False)

with_name: bool

whether to print the name (default: False)

Examples

>>> r = Reaction({'H+': 1, 'Cl-': 1}, {'HCl': 1}, 1e10)
>>> r.string(with_param=False)
'Cl- + H+ -> HCl'
unicode(self, substances, with_param=False, with_name=False, **kwargs)[source]

Returns a unicode string representation of the reaction

Examples

>>> keys = 'H2O H+ OH-'.split()
>>> subst = {k: Substance.from_formula(k) for k in keys}
>>> r = Reaction.from_string("H2O -> H+ + OH-; 1e-4", subst)
>>> r.unicode(subst) == u'H₂O → H⁺ + OH⁻'
True
>>> r2 = Reaction.from_string("H+ + OH- -> H2O; 1e8/molar/second", subst)
>>> r2.unicode(subst, with_param=True) == u'H⁺ + OH⁻ → H₂O; 10⁸ 1/(s·M)'
True
class chempy.chemistry.Solute(*args, **kwargs)[source]

Bases: chempy.chemistry.Solute

Solute is deprecated since (not including) 0.3.0, it will be missing in 0.8.0. Use Species instead.

[DEPRECATED] Use .Species instead

Counter-intuitive to its name Solute has an additional property ‘precipitate’

Attributes
charge

Convenience property for accessing composition[0]

mass

Convenience property for accessing data['mass']

Methods

composition_keys(substance_iter[, skip_keys])

Occuring composition keys among a series of substances

from_formula(formula, \*\*kwargs)

Creates a Substance instance from its formula

molar_mass(self[, units])

Returns the molar mass (with units) of the substance

class chempy.chemistry.Species(*args, **kwargs)[source]

Bases: chempy.chemistry.Substance

Substance belonging to a phase

Species extends Substance with the new attribute phase_idx

Attributes
phase_idx: int

Index of the phase (default is 0)

Methods

composition_keys(substance_iter[, skip_keys])

Occuring composition keys among a series of substances

from_formula(formula[, phases, …])

Create a Species instance from its formula

molar_mass(self[, units])

Returns the molar mass (with units) of the substance

classmethod from_formula(formula, phases=('(s)', '(l)', '(g)'), default_phase_idx=0, **kwargs)[source]

Create a Species instance from its formula

Analogous to Substance.from_formula() but with the addition that phase_idx is determined from the formula (and a mapping provided by phases)

Parameters
formula: str

e.g. ‘H2O’, ‘NaCl(s)’, ‘CO2(aq)’, ‘CO2(g)’

phases: iterable of str or dict mapping str -> int

if not in **kwargs, phase_idx is determined from the suffix of formula where the suffixes is mapped from phases:

if phases is a dictionary:

phase_idx = phases[suffix]

else:

phase_idx = phases.index(suffix) + 1

and if suffixes is missing in phases phase_idx is taken to be 0

default_phase_idx: int or None (default: 0)
If default_phase_idx is None, ValueError is raised for

unkown suffixes.

Else default_phase_idx is used as phase_idx in those cases.

**kwargs:

Keyword arguments passed on.

Raises
ValueError:

if default_phase_idx is None and no suffix found in phases

Examples

>>> water = Species.from_formula('H2O')
>>> water.phase_idx
0
>>> NaCl = Species.from_formula('NaCl(s)')
>>> NaCl.phase_idx
1
>>> Hg_l = Species.from_formula('Hg(l)')
>>> Hg_l.phase_idx
2
>>> CO2g = Species.from_formula('CO2(g)')
>>> CO2g.phase_idx
3
>>> CO2aq = Species.from_formula('CO2(aq)', default_phase_idx=None)
Traceback (most recent call last):
    ...
ValueError: Could not determine phase_idx
>>> CO2aq = Species.from_formula('CO2(aq)')
>>> CO2aq.phase_idx
0
>>> CO2aq = Species.from_formula('CO2(aq)', ['(aq)'],
...     default_phase_idx=None)
>>> CO2aq.phase_idx
1
>>> Species.from_formula('CO2(aq)', {'(aq)': 0}, None).phase_idx
0
property precipitate

precipitate is deprecated since (not including) 0.3.0, it will be missing in 0.8.0.

deprecated attribute, provided for compatibility for now

class chempy.chemistry.Substance(name=None, charge=None, latex_name=None, unicode_name=None, html_name=None, composition=None, data=None)[source]

Bases: object

Class representing a chemical substance

Parameters
namestr
chargeint (optional, default: None)

Will be stored in composition[0], prefer composition when possible.

latex_namestr
unicode_namestr
html_namestr
compositiondict or None (default)

Dictionary (int -> number) e.g. {atomic number: count}, zero has special meaning (net charge). Avoid using the key 0 unless you specifically mean net charge. The motivation behind this is that it is easier to track a net-charge of e.g. 6 for U(VI) than it is to remember that uranium has 92 electrons and use 86 as the value).

datadict

Free form dictionary. Could be simple such as {'mp': 0, 'bp': 100} or considerably more involved, e.g.: {'diffusion_coefficient': { 'water': lambda T: 2.1*m**2/s/K*(T - 273.15*K)}}.

Examples

>>> ammonium = Substance('NH4+', 1, 'NH_4^+', composition={7: 1, 1: 4},
...     data={'mass': 18.0385, 'pKa': 9.24})
>>> ammonium.name
'NH4+'
>>> ammonium.composition == {0: 1, 1: 4, 7: 1}  # charge represented by key '0'
True
>>> ammonium.data['mass']
18.0385
>>> ammonium.data['pKa']
9.24
>>> ammonium.mass  # mass is a special case (also attribute)
18.0385
>>> ammonium.pKa
Traceback (most recent call last):
    ...
AttributeError: 'Substance' object has no attribute 'pKa'
>>> nh4p = Substance.from_formula('NH4+')  # simpler
>>> nh4p.composition == {7: 1, 1: 4, 0: 1}
True
>>> nh4p.latex_name
'NH_{4}^{+}'
Attributes
mass

Convenience property for accessing data['mass']

attrs

A tuple of attribute names for serialization.

compositiondict or None

Dictionary mapping fragment key (str) to amount (int).

data

Free form dictionary.

Methods

composition_keys(substance_iter[, skip_keys])

Occuring composition keys among a series of substances

from_formula(formula, \*\*kwargs)

Creates a Substance instance from its formula

molar_mass(self[, units])

Returns the molar mass (with units) of the substance

attrs = ('name', 'latex_name', 'unicode_name', 'html_name', 'composition', 'data')
property charge

Convenience property for accessing composition[0]

static composition_keys(substance_iter, skip_keys=())[source]

Occuring composition keys among a series of substances

classmethod from_formula(formula, **kwargs)[source]

Creates a Substance instance from its formula

Parameters
formula: str

e.g. ‘Na+’, ‘H2O’, ‘Fe(CN)6-4’

**kwargs:

keyword arguments passed on to .Substance

Examples

>>> NH3 = Substance.from_formula('NH3')
>>> NH3.composition == {1: 3, 7: 1}
True
>>> '%.2f' % NH3.mass
'17.03'
>>> NH3.charge
0
>>> NH3.latex_name
'NH_{3}'
property mass

Convenience property for accessing data['mass']

when data['mass'] is missing the mass is calculated from the composition using chempy.util.parsing.mass_from_composition().

molar_mass(self, units=None)[source]

Returns the molar mass (with units) of the substance

Examples

>>> nh4p = Substance.from_formula('NH4+')  # simpler
>>> from chempy.units import default_units as u
>>> nh4p.molar_mass(u)
array(18.0384511...) * g/mol
chempy.chemistry.balance_stoichiometry(reactants, products, substances=None, substance_factory=<bound method Substance.from_formula of <class 'chempy.chemistry.Substance'>>, parametric_symbols=None, underdetermined=True, allow_duplicates=False)[source]

Balances stoichiometric coefficients of a reaction

Parameters
reactantsiterable of reactant keys
productsiterable of product keys
substancesOrderedDict or string or None

Mapping reactant/product keys to instances of Substance.

substance_factorycallback
parametric_symbolsgenerator of symbols

Used to generate symbols for parametric solution for under-determined system of equations. Default is numbered “x-symbols” starting from 1.

underdeterminedbool

Allows to find a non-unique solution (in addition to a constant factor across all terms). Set to False to disallow (raise ValueError) on e.g. “C + O2 -> CO + CO2”. Set to None if you want the symbols replaced so that the coefficients are the smallest possible positive (non-zero) integers.

allow_duplicatesbool

If False: raises an excpetion if keys appear in both reactants and products.

Returns
balanced reactantsdict
balanced productsdict

Examples

>>> ref = {'C2H2': 2, 'O2': 3}, {'CO': 4, 'H2O': 2}
>>> balance_stoichiometry({'C2H2', 'O2'}, {'CO', 'H2O'}) == ref
True
>>> ref2 = {'H2': 1, 'O2': 1}, {'H2O2': 1}
>>> balance_stoichiometry('H2 O2'.split(), ['H2O2'], 'H2 O2 H2O2') == ref2
True
>>> reac, prod = 'CuSCN KIO3 HCl'.split(), 'CuSO4 KCl HCN ICl H2O'.split()
>>> Reaction(*balance_stoichiometry(reac, prod)).string()
'4 CuSCN + 7 KIO3 + 14 HCl -> 4 CuSO4 + 7 KCl + 4 HCN + 7 ICl + 5 H2O'
>>> balance_stoichiometry({'Fe', 'O2'}, {'FeO', 'Fe2O3'}, underdetermined=False)
Traceback (most recent call last):
    ...
ValueError: The system was under-determined
>>> r, p = balance_stoichiometry({'Fe', 'O2'}, {'FeO', 'Fe2O3'})
>>> list(set.union(*[v.free_symbols for v in r.values()]))
[x1]
>>> b = balance_stoichiometry({'Fe', 'O2'}, {'FeO', 'Fe2O3'}, underdetermined=None)
>>> b == ({'Fe': 3, 'O2': 2}, {'FeO': 1, 'Fe2O3': 1})
True
>>> d = balance_stoichiometry({'C', 'CO'}, {'C', 'CO', 'CO2'}, underdetermined=None, allow_duplicates=True)
>>> d == ({'CO': 2}, {'C': 1, 'CO2': 1})
True
chempy.chemistry.equilibrium_quotient(concs, stoich)[source]

Calculates the equilibrium quotient of an equilbrium

Parameters
concs: array_like

per substance concentration

stoich: iterable of integers

per substance stoichiometric coefficient

Examples

>>> '%.12g' % equilibrium_quotient([1.0, 1e-7, 1e-7], [-1, 1, 1])
'1e-14'
chempy.chemistry.mass_fractions(stoichiometries, substances=None, substance_factory=<bound method Substance.from_formula of <class 'chempy.chemistry.Substance'>>)[source]

Calculates weight fractions of each substance in a stoichiometric dict

Parameters
stoichiometriesdict or set

If a set: all entries are assumed to correspond to unit multiplicity.

substances: dict or None

Examples

>>> r = mass_fractions({'H2': 1, 'O2': 1})
>>> mH2, mO2 = 1.008*2, 15.999*2
>>> abs(r['H2'] - mH2/(mH2+mO2)) < 1e-4
True
>>> abs(r['O2'] - mO2/(mH2+mO2)) < 1e-4
True
>>> mass_fractions({'H2O2'}) == {'H2O2': 1.0}
True

chempy.debye_huckel module

chempy.einstein_smoluchowski module

chempy.einstein_smoluchowski.electrical_mobility_from_D(D, charge, T, constants=None, units=None)[source]

Calculates the electrical mobility through Einstein-Smoluchowski relation.

Parameters
D: float with unit

Diffusion coefficient

charge: integer

charge of the species

T: float with unit

Absolute temperature

constants: object (optional, default: None)
if None:

T assumed to be in Kelvin and b0 = 1 mol/kg

else:

see source code for what attributes are used. Tip: pass quantities.constants

units: object (optional, default: None)

attributes accessed: meter, Kelvin and mol

Returns
Electrical mobility

chempy.electrolytes module

This modules collects expressions related to ionic strenght, e.g. the Debye-Hückel expressions.

chempy.electrolytes.A(eps_r, T, rho, b0=1, constants=None, units=None, backend=None)[source]

Debye Huckel constant A

Parameters
eps_r: float

relative permittivity

T: float with unit

Temperature (default: assume Kelvin)

rho: float with unit

density (default: assume kg/m**3)

b0: float, optional

Reference molality, optionally with unit (amount / mass) IUPAC defines it as 1 mol/kg. (default: 1).

units: object (optional, default: None)

attributes accessed: meter, Kelvin and mol

constants: object (optional, default: None)
if None:

T assumed to be in Kelvin and b0 = 1 mol/kg

else:

see source code for what attributes are used. Tip: pass quantities.constants

Notes

Remember to divide by ln(10) if you want to use the constant with log10 based expression.

References

Atkins, De Paula, Physical Chemistry, 8th edition

chempy.electrolytes.B(eps_r, T, rho, b0=1, constants=None, units=None, backend=None)[source]

Extended Debye-Huckel parameter B

Parameters
eps_r: float

relative permittivity

T: float with unit

temperature

rho: float with unit

density

b0: float with unit

reference molality

units: object (optional, default: None)

attributes accessed: meter, Kelvin and mol

constants: object (optional, default: None)
if None:

T assumed to be in Kelvin, rho in kg/m**3 and b0 = 1 mol/kg

else:

attributes accessed: molar_gas_constant, Faraday_constant Tip: pass quantities.constants

Returns
Debye Huckel B constant (default in m**-1)
class chempy.electrolytes.ExtendedDebyeHuckelActivityProduct(stoich, *args)[source]

Bases: chempy.electrolytes._ActivityProductBase

Methods

__call__(self, c)

Call self as a function.

class chempy.electrolytes.LimitingDebyeHuckelActivityProduct(stoich, *args)[source]

Bases: chempy.electrolytes._ActivityProductBase

Methods

__call__(self, c)

Call self as a function.

chempy.electrolytes.davies_activity_product(I, stoich, z, a, T, eps_r, rho, C=-0.3, backend=None)[source]
chempy.electrolytes.davies_log_gamma(I, z, A, C=-0.3, I0=1, backend=None)[source]

Davies formula

chempy.electrolytes.extended_activity_product(I, stoich, z, a, T, eps_r, rho, C=0, backend=None)[source]
chempy.electrolytes.extended_log_gamma(I, z, a, A, B, C=0, I0=1, backend=None)[source]

Debye-Huckel extended formula

chempy.electrolytes.ionic_strength(molalities, charges=None, units=None, substances=None, substance_factory=<bound method Substance.from_formula of <class 'chempy.chemistry.Substance'>>, warn=True)[source]

Calculates the ionic strength

Parameters
molalities: array_like or dict

Optionally with unit (amount / mass). when dict: mapping substance key to molality.

charges: array_like

Charge of respective ion, taken for substances when None.

units: object (optional, default: None)

Attributes accessed: molal.

substances: dict, optional

Mapping of substance keys to Substance instances (used when molalities is a dict).

substance_factory: callback

Used if substances is a string.

warn: bool

Issue a warning if molalities violates net charge neutrality.

Examples

>>> ionic_strength([1e-3, 3e-3], [3, -1]) == .5 * (9 + 3) * 1e-3
True
>>> ionic_strength({'Mg+2': 6, 'PO4-3': 4})
30.0
chempy.electrolytes.limiting_activity_product(I, stoich, z, T, eps_r, rho, backend=None)[source]

Product of activity coefficients based on DH limiting law.

chempy.electrolytes.limiting_log_gamma(I, z, A, I0=1, backend=None)[source]

Debye-Hyckel limiting formula

chempy.equilibria module

Module collecting classes and functions for dealing with (multiphase) chemical equilibria.

Note

This module is provisional at the moment, i.e. the API is not stable and may break without a deprecation cycle.

class chempy.equilibria.EqSystem(rxns, substances=None, name=None, checks=None, dont_check=None, substance_factory=<class 'chempy.chemistry.Substance'>, missing_substances_from_keys=False, sort_substances=None)[source]

Bases: chempy.reactionsystem.ReactionSystem

Attributes
nr

Number of reactions

ns

Number of substances

precipitate_rxn_idxs

precipitate_rxn_idxs is deprecated since (not including) 0.3.1, it will be missing in 0.8.0. Use phase_transfer_reaction_idxs instead.

precipitate_substance_idxs

precipitate_substance_idxs is deprecated since (not including) 0.3.1, it will be missing in 0.8.0. Use other_phase_species_idxs instead.

Methods

as_per_substance_array(self, cont[, dtype, …])

Turns a dict into an ordered array

as_substance_index(self, substance_key)

Returns the index of a Substance in the system

bimolecular_html_table(\*args, \*\*kwargs)

bimolecular_html_table is deprecated since (not including) 0.5.7, it will be missing in 0.8.0.

categorize_substances(self, \*\*kwargs)

Returns categories of substance keys (e.g.

check_balance(self[, strict, throw])

Checks if all reactions are balanced.

check_duplicate(self[, throw])

Raies ValueError if there are duplicates in self.rxns

composition_balance_vectors(self)

Returns a list of lists with compositions and a list of composition keys.

concatenate(rsystems[, cmp_attrs])

Concatenates ReactionSystem instances

dissolved(self, concs)

Return dissolved concentrations

from_string(s[, substances, …])

Create a reaction system from a string

html(self, \*args, \*\*kwargs)

Returns a string with an HTML representation

identify_equilibria(self)

Returns a list of index pairs of reactions forming equilibria.

obeys_charge_neutrality(self)

Returns False if any reaction violate charge neutrality.

obeys_mass_balance(self)

Returns True if all reactions obeys mass balance, else False.

params(self)

Returns list of per reaction param value

per_substance_varied(self, per_substance[, …])

Dense nd-array for all combinations of varied levels per substance

rates(self[, variables, backend, …])

Per substance sums of reaction rates rates.

roots(self, init_concs, varied_data, varied)

Parameters

sort_substances_inplace(self[, key])

Sorts the OrderedDict attribute substances

split(self, \*\*kwargs)

Splits the reaction system into multiple disjoint reaction systems.

stoichs(self[, non_precip_rids])

Conditional stoichiometries depending on precipitation status

subset(self, pred[, checks])

Creates two new instances with the distinct subsets of reactions

substance_names(self)

Returns a tuple of the substances’ names

substance_participation(self, substance_key)

Returns indices of reactions where substance_key occurs

unimolecular_html_table(\*args, \*\*kwargs)

unimolecular_html_table is deprecated since (not including) 0.5.7, it will be missing in 0.8.0.

upper_conc_bounds(self, init_concs[, min_, …])

Calculates upper concentration bounds per substance based on substance composition.

active_prod_stoichs

active_reac_stoichs

all_prod_stoichs

all_reac_stoichs

as_per_substance_dict

check_duplicate_names

check_substance_keys

composition_conservation

eq_constants

equilibrium_quotients

get_neqsys

get_neqsys_chained_conditional

get_neqsys_conditional_chained

get_neqsys_static_conditions

net_stoichs

non_precip_rids

other_phase_species_idxs

per_reaction_effect_on_substance

phase_transfer_reaction_idxs

plot_errors

root

solve

stoichs_constants

string

substance_labels

composition_conservation(self, concs, init_concs)[source]
dissolved(self, concs)[source]

Return dissolved concentrations

eq_constants(self, non_precip_rids=(), eq_params=None, small=0)[source]
equilibrium_quotients(self, concs)[source]
get_neqsys(self, neqsys_type, NumSys=<class 'chempy._eqsys.NumSysLin'>, **kwargs)[source]
get_neqsys_chained_conditional(self, rref_equil=False, rref_preserv=False, NumSys=<class 'chempy._eqsys.NumSysLin'>, **kwargs)[source]
get_neqsys_conditional_chained(self, rref_equil=False, rref_preserv=False, NumSys=<class 'chempy._eqsys.NumSysLin'>, **kwargs)[source]
get_neqsys_static_conditions(self, rref_equil=False, rref_preserv=False, NumSys=(<class 'chempy._eqsys.NumSysLin'>, ), precipitates=None, **kwargs)[source]
html(self, *args, **kwargs)[source]

Returns a string with an HTML representation

Parameters
with_parambool
with_namebool
checkstuple
color_categoriesbool
splitbool
print_fncallable

default: chempy.printing.html()

non_precip_rids(self, precipitates)[source]
other_phase_species_idxs(self, phase_idx=0)[source]
phase_transfer_reaction_idxs(self, phase_idx=0)[source]
plot_errors(self, concs, init_concs, varied_data, varied, axes=None, compositions=True, Q=True, subplot_kwargs=None)[source]
property precipitate_rxn_idxs

precipitate_rxn_idxs is deprecated since (not including) 0.3.1, it will be missing in 0.8.0. Use phase_transfer_reaction_idxs instead.

property precipitate_substance_idxs

precipitate_substance_idxs is deprecated since (not including) 0.3.1, it will be missing in 0.8.0. Use other_phase_species_idxs instead.

root(self, init_concs, x0=None, neqsys=None, NumSys=<class 'chempy._eqsys.NumSysLog'>, neqsys_type='chained_conditional', **kwargs)[source]
roots(self, init_concs, varied_data, varied, x0=None, NumSys=<class 'chempy._eqsys.NumSysLog'>, plot_kwargs=None, neqsys_type='chained_conditional', **kwargs)[source]
Parameters
init_concsarray or dict
varied_dataarray
varied_idxint or str
x0array
NumSys_NumSys subclass

See NumSysLin, NumSysLog, etc.

plot_kwargsdict

See py:meth:pyneqsys.NeqSys.solve. Two additional keys are intercepted here:

latex_names: bool (default: False) conc_unit_str: str (default: ‘M’)

neqsys_typestr

what method to use for NeqSys construction (get_neqsys_*)

**kwargs :

Keyword argumetns passed on to py:meth:pyneqsys.NeqSys.solve_series.

solve(self, init_concs, varied=None, **kwargs)[source]
stoichs_constants(self, eq_params=None, rref=False, Matrix=None, backend=None, non_precip_rids=())[source]
substance_labels(self, latex=False)[source]

chempy.eyring module

chempy.henry module

Module for dealing with constants Henry’s law.

class chempy.henry.Henry[source]

Bases: chempy.util.pyutil.Henry

Henry’s gas constant

Note that the reference temperature is set by the attribute T0 which defaults to 298.15 (Kelvin).

Parameters
Hcp: float

Henry’s constant [M/atm]

Tderiv: float

dln(kH)/d(1/T) [K] Equivalent to $Delta_{soln}H / R$

ref: object

Reference for origin of parameters

units: object (optional)

object with attributes: kelvin

Examples

>>> H_H2 = Henry(1.2e-3, 1800, ref='carpenter_1966')
>>> '%.2g' % H_H2(298.15)
'0.0012'
Attributes
Hcp

Alias for field number 0

T0

Alias for field number 2

Tderiv

Alias for field number 1

ref

Alias for field number 3

Methods

__call__(self, T[, units, backend])

Evaluates Henry’s constant for provided temperature

count(self, value, /)

Return number of occurrences of value.

get_P_at_T_and_c(self, T, c, \*\*kwargs)

Convenience method for calculating concentration

get_c_at_T_and_P(self, T, P, \*\*kwargs)

Convenience method for calculating concentration

get_kH_at_T(\*args, \*\*kwargs)

get_kH_at_T is deprecated since (not including) 0.3.1, it will be missing in 0.5.0.

index(self, value[, start, stop])

Return first index of value.

get_P_at_T_and_c(self, T, c, **kwargs)[source]

Convenience method for calculating concentration

Calculate the partial pressure for given temperature and concentration

Parameters
T: float

Temperature

P: float

Pressure

**kwargs:

Keyword arguments passed on to __call__()

get_c_at_T_and_P(self, T, P, **kwargs)[source]

Convenience method for calculating concentration

Calculate what concentration is needed to achieve a given partial pressure at a specified temperature

Parameters
T: float

Temperature

P: float

Pressure

**kwargs:

Keyword arguments passed on to __call__()

get_kH_at_T(*args, **kwargs)[source]

get_kH_at_T is deprecated since (not including) 0.3.1, it will be missing in 0.5.0. Use __call__ instead.

class chempy.henry.HenryWithUnits[source]

Bases: chempy.henry.Henry

Analogous to Henry

Examples

>>> from chempy.units import to_unitless, default_units as u
>>> H_CO = HenryWithUnits(9.7e-6 * u.mol/u.m**3/u.Pa, 1300*u.K, ref='sander_2015')
>>> '%.2g' % to_unitless(H_CO(298.15 * u.K), u.molar/u.bar)
'0.00097'
Attributes
Hcp

Alias for field number 0

T0

Alias for field number 2

Tderiv

Alias for field number 1

ref

Alias for field number 3

Methods

__call__(self, T[, units, backend])

Evaluates Henry’s constant for provided temperature

count(self, value, /)

Return number of occurrences of value.

get_P_at_T_and_c(self, T, c, \*\*kwargs)

Convenience method for calculating concentration

get_c_at_T_and_P(self, T, P, \*\*kwargs)

Convenience method for calculating concentration

get_kH_at_T(\*args, \*\*kwargs)

get_kH_at_T is deprecated since (not including) 0.3.1, it will be missing in 0.5.0.

index(self, value[, start, stop])

Return first index of value.

chempy.henry.Henry_H_at_T(T, H, Tderiv, T0=None, units=None, backend=None)[source]

Evaluate Henry’s constant H at temperature T

Parameters
T: float

Temperature (with units), assumed to be in Kelvin if units == None

H: float

Henry’s constant

Tderiv: float (optional)

dln(H)/d(1/T), assumed to be in Kelvin if units == None.

T0: float

Reference temperature, assumed to be in Kelvin if units == None default: 298.15 K

units: object (optional)

object with attributes: kelvin (e.g. chempy.units.default_units)

backendmodule (optional)

module with “exp”, default: numpy, math

chempy.reactionsystem module

class chempy.reactionsystem.ReactionSystem(rxns, substances=None, name=None, checks=None, dont_check=None, substance_factory=<class 'chempy.chemistry.Substance'>, missing_substances_from_keys=False, sort_substances=None)[source]

Bases: object

Collection of reactions forming a system (model).

Parameters
rxnssequence

Sequence of Reaction instances.

substancesOrderedDict or string or None

Mapping str -> Substance instances, None => deduced from reactions. If a set is passed as substances (or a string which is split), then substance_factory will be used to construct substances from the items.

namestring (optional)

Name of ReactionSystem (e.g. model name / citation key).

checksiterable of str, optional

Raises ValueError if any method check_%s returns False for all %s in checks. Default: ReactionSystem.default_checks.

substance_factorycallback

Could also be e.g. Substance.from_formula().

sort_substancesbool

Sort keys in substances lexicographically by key? default: None implies True unless substances is either one of OrderedDict, list, tuple or str.

Raises
ValueError

When any reaction occurs more than once

Examples

>>> from chempy import Reaction
>>> r1 = Reaction({'R1': 1}, {'P1': 1}, 42.0)
>>> rsys = ReactionSystem([r1], 'R1 P1')
>>> rsys.as_per_substance_array({'R1': 2, 'P1': 3})
array([2., 3.])
Attributes
rxnslist of objects

Sequence of Reaction instances.

substancesOrderedDict or string or iterable of strings/Substance

Mapping substance name to substance index.

nsint

Number of substances

nrint

Number of reactions

Methods

as_per_substance_array(self, cont[, dtype, …])

Turns a dict into an ordered array

as_substance_index(self, substance_key)

Returns the index of a Substance in the system

bimolecular_html_table(\*args, \*\*kwargs)

bimolecular_html_table is deprecated since (not including) 0.5.7, it will be missing in 0.8.0.

categorize_substances(self, \*\*kwargs)

Returns categories of substance keys (e.g.

check_balance(self[, strict, throw])

Checks if all reactions are balanced.

check_duplicate(self[, throw])

Raies ValueError if there are duplicates in self.rxns

composition_balance_vectors(self)

Returns a list of lists with compositions and a list of composition keys.

concatenate(rsystems[, cmp_attrs])

Concatenates ReactionSystem instances

from_string(s[, substances, …])

Create a reaction system from a string

html(self[, with_param, with_name, checks, …])

Returns a string with an HTML representation

identify_equilibria(self)

Returns a list of index pairs of reactions forming equilibria.

obeys_charge_neutrality(self)

Returns False if any reaction violate charge neutrality.

obeys_mass_balance(self)

Returns True if all reactions obeys mass balance, else False.

params(self)

Returns list of per reaction param value

per_substance_varied(self, per_substance[, …])

Dense nd-array for all combinations of varied levels per substance

rates(self[, variables, backend, …])

Per substance sums of reaction rates rates.

sort_substances_inplace(self[, key])

Sorts the OrderedDict attribute substances

split(self, \*\*kwargs)

Splits the reaction system into multiple disjoint reaction systems.

stoichs(self[, non_precip_rids])

Conditional stoichiometries depending on precipitation status

subset(self, pred[, checks])

Creates two new instances with the distinct subsets of reactions

substance_names(self)

Returns a tuple of the substances’ names

substance_participation(self, substance_key)

Returns indices of reactions where substance_key occurs

unimolecular_html_table(\*args, \*\*kwargs)

unimolecular_html_table is deprecated since (not including) 0.5.7, it will be missing in 0.8.0.

upper_conc_bounds(self, init_concs[, min_, …])

Calculates upper concentration bounds per substance based on substance composition.

active_prod_stoichs

active_reac_stoichs

all_prod_stoichs

all_reac_stoichs

as_per_substance_dict

check_duplicate_names

check_substance_keys

net_stoichs

per_reaction_effect_on_substance

string

active_prod_stoichs(self, keys=None)[source]
active_reac_stoichs(self, keys=None)[source]
all_prod_stoichs(self, keys=None)[source]
all_reac_stoichs(self, keys=None)[source]
as_per_substance_array(self, cont, dtype='float64', unit=None, raise_on_unk=False)[source]

Turns a dict into an ordered array

Parameters
contarray_like or dict
dtypestr or numpy.dtype object
unitunit, optional
raise_on_unkbool
as_per_substance_dict(self, arr)[source]
as_substance_index(self, substance_key)[source]

Returns the index of a Substance in the system

bimolecular_html_table(*args, **kwargs)[source]

bimolecular_html_table is deprecated since (not including) 0.5.7, it will be missing in 0.8.0. Use chempy.printing.tables.BimolecularTable instead.

categorize_substances(self, **kwargs)[source]

Returns categories of substance keys (e.g. nonparticipating, unaffected etc.)

Some substances are only accumulated (i.e. irreversibly formed) and are never net reactants in any reactions, others are depleted (they are never net proucts in any reaction). Some substanaces are unaffected since they appear with equal coefficients on both reactant and product side, while some may be nonparticipating (they don’t appear on either side and have thus no effect on the reactionsystem).

Parameters
**kwargs:

Keyword arguments passed on to ReactionSystem.

Returns
dict of sets of substance keys, the dictionary has the following keys:
  • 'accumulated': keys only participating as net products.

  • 'depleted': keys only participating as net reactants.

  • 'unaffected': keys appearing in reactions but with zero net effect.

  • 'nonparticipating': keys not appearing in any reactions.

check_balance(self, strict=False, throw=False)[source]

Checks if all reactions are balanced.

Parameters
strictbool

Puts a requirement on all substances to have their composition attribute set.

throwbool

Raies ValueError if there are unbalanecd reactions in self.rxns

check_duplicate(self, throw=False)[source]

Raies ValueError if there are duplicates in self.rxns

check_duplicate_names(self, throw=False)[source]
check_substance_keys(self, throw=False)[source]
composition_balance_vectors(self)[source]

Returns a list of lists with compositions and a list of composition keys.

The list of lists can be viewed as a matrix with rows corresponding to composition keys (which are given as the second item in the returned tuple) and columns corresponding to substances. Multiplying the matrix with a vector of concentrations give an equation which is an invariant (corresponds to mass & charge conservation).

Returns
A: list of lists
ck: (sorted) tuple of composition keys

Examples

>>> s = 'Cu+2 + NH3 -> CuNH3+2'
>>> import re
>>> substances = re.split(r' \+ | -> ', s)
>>> rsys = ReactionSystem.from_string(s, substances)
>>> rsys.composition_balance_vectors()
([[2, 0, 2], [0, 3, 3], [0, 1, 1], [1, 0, 1]], [0, 1, 7, 29])
static concatenate(rsystems, cmp_attrs=['reac', 'inact_reac', 'prod', 'inact_prod'])[source]

Concatenates ReactionSystem instances

Reactions with identical stoichiometries are added to a separated reactionsystem for “duplicates”

Parameters
rsystemsiterable of ReactionSystem instances
Returns
pair of ReactionSystem instaces: the “sum” and “duplicates”
default_checks = {'balance', 'duplicate', 'duplicate_names', 'substance_keys'}
classmethod from_string(s, substances=None, rxn_parse_kwargs=None, comment_tokens=('#', ), **kwargs)[source]

Create a reaction system from a string

Parameters
sstr

Multiline string.

substancesconvertible to iterable of str
rxn_parse_kwargsdict

Keyword arguments passed on to the Reaction baseclass’ method from_string.

comment_tokensiterable of str instances

Tokens which causes lines to be ignored when prefixed by any of them.

substance_factorycallable

Defaults to cls._BaseSubstance.from_formula. Can be set to e.g. Substance.

**kwargs:

Keyword arguments passed to the constructor of the class

Examples

>>> rs = ReactionSystem.from_string('\n'.join(['2 HNO2 -> H2O + NO + NO2; 3', '2 NO2 -> N2O4; 4']))
>>> r1, r2 = 5*5*3, 7*7*4
>>> rs.rates({'HNO2': 5, 'NO2': 7}) == {'HNO2': -2*r1, 'H2O': r1, 'NO': r1, 'NO2': r1 - 2*r2, 'N2O4': r2}
True
html(self, with_param=True, with_name=True, checks=(), color_categories=True, split=True, print_fn=None)[source]

Returns a string with an HTML representation

Parameters
with_parambool
with_namebool
checkstuple
color_categoriesbool
splitbool
print_fncallable

default: chempy.printing.html()

identify_equilibria(self)[source]

Returns a list of index pairs of reactions forming equilibria.

The pairs are sorted with respect to index (lowest first)

net_stoichs(self, keys=None)[source]
property nr

Number of reactions

property ns

Number of substances

obeys_charge_neutrality(self)[source]

Returns False if any reaction violate charge neutrality.

obeys_mass_balance(self)[source]

Returns True if all reactions obeys mass balance, else False.

params(self)[source]

Returns list of per reaction param value

per_reaction_effect_on_substance(self, substance_key)[source]
per_substance_varied(self, per_substance, varied=None)[source]

Dense nd-array for all combinations of varied levels per substance

Parameters
per_substance: dict or array
varied: dict
Returns
ndarraywith len(varied) + 1 number of axes, and with last axis length == self.ns

Examples

>>> rsys = ReactionSystem([], 'A B C')
>>> arr, keys = rsys.per_substance_varied({'A': 2, 'B': 3, 'C': 5}, {'C': [5, 7, 9, 11]})
>>> arr.shape, keys
((4, 3), ('C',))
>>> all(arr[1, :] == [2, 3, 7])
True
rates(self, variables=None, backend=<module 'math' (built-in)>, substance_keys=None, ratexs=None, cstr_fr_fc=None)[source]

Per substance sums of reaction rates rates.

Parameters
variablesdict
backendmodule, optional
substance_keysiterable of str, optional
ratexsiterable of RateExpr instances
cstr_fr_fctuple (str, tuple of str)

Continuously stirred tank reactor conditions. Pair of flow/volume ratio key (feed-rate/tank-volume) and dict mapping feed concentration keys to substance keys.

Returns
dict

per substance_key time derivatives of concentrations.

Examples

>>> r = Reaction({'R': 2}, {'P': 1}, 42.0)
>>> rsys = ReactionSystem([r])
>>> rates = rsys.rates({'R': 3, 'P': 5})
>>> abs(rates['P'] - 42*3**2) < 1e-14
True
sort_substances_inplace(self, key=<function ReactionSystem.<lambda> at 0x7fcbbb75f670>)[source]

Sorts the OrderedDict attribute substances

split(self, **kwargs)[source]

Splits the reaction system into multiple disjoint reaction systems.

stoichs(self, non_precip_rids=())[source]

Conditional stoichiometries depending on precipitation status

string(self, with_param=True, with_name=True)[source]
subset(self, pred, checks=())[source]

Creates two new instances with the distinct subsets of reactions

First ReactionSystem will contain the reactions for which the predicate is True, the second for which it is False.

Parameters
predcallable

Signature: pred(Reaction) -> bool.

checkstuple

See ReactionSystem.

Returns
length 2 tuple
substance_names(self)[source]

Returns a tuple of the substances’ names

substance_participation(self, substance_key)[source]

Returns indices of reactions where substance_key occurs

Parameters
substance_key: str
Returns
List of indices for self.rxns where substance_key participates

Examples

>>> rs = ReactionSystem.from_string('2 H2 + O2 -> 2 H2O\n 2 H2O2 -> 2 H2O + O2')
>>> rs.substance_participation('H2')
[0]
>>> rs.substance_participation('O2')
[0, 1]
>>> rs.substance_participation('O3')
[]
unimolecular_html_table(*args, **kwargs)[source]

unimolecular_html_table is deprecated since (not including) 0.5.7, it will be missing in 0.8.0. Use chempy.printing.tables.UnimolecularTable instead.

upper_conc_bounds(self, init_concs, min_=<built-in function min>, dtype=None, skip_keys=(0, ))[source]

Calculates upper concentration bounds per substance based on substance composition.

Parameters
init_concsdict or array_like

Per substance initial conidtions.

min_callbable
dtypedtype or None
skip_keystuple

What composition keys to skip.

Returns
numpy.ndarray :

Per substance upper limit (ordered as substances).

Notes

The function does not take into account wheter there actually exists a reaction path leading to a substance. Note also that the upper limit is per substance, i.e. the sum of all upper bounds amount to more substance than available in init_conc.

Examples

>>> rs = ReactionSystem.from_string('2 HNO2 -> H2O + NO + NO2 \n 2 NO2 -> N2O4')
>>> from collections import defaultdict
>>> c0 = defaultdict(float, HNO2=20)
>>> ref = {'HNO2': 20, 'H2O': 10, 'NO': 20, 'NO2': 20, 'N2O4': 10}
>>> rs.as_per_substance_dict(rs.upper_conc_bounds(c0)) == ref
True

chempy.symbolic module

chempy.symbolic.get_constant_symbols(Symbol=None)[source]

chempy.units module

The units module provides the following attributes:

  • chempy.units.default_units

  • chempy.units.default_constants

  • chempy.units.SI_base_registry

together with some functions.

Currently quantities is used as the underlying package to handle units. If it is possible you should try to only use the chempy.units module (since it is likely that ChemPy will change this backend at some point in the future). Therefore you should not rely on any attributes of the Quantity instances (and rather use getter & setter functions in chempy.units).

class chempy.units.Backend(underlying_backend=('numpy', 'math'))[source]

Bases: object

Wrapper around modules such as numpy and math

Instances of Backend wraps a module, e.g. numpy and ensures that arguments passed on are unitless, i.e. it raises an error if a transcendental function is used with quantities with units.

Parameters
underlying_backendmodule, str or tuple of str

e.g. ‘numpy’ or (‘sympy’, ‘math’)

Examples

>>> import math
>>> km, m = default_units.kilometre, default_units.metre
>>> math.exp(3*km) == math.exp(3*m)
True
>>> be = Backend('math')
>>> be.exp(3*km)
Traceback (most recent call last):
    ...
ValueError: Unable to convert between units of "km" and "dimensionless"
>>> import numpy as np
>>> np.sum([1000*pq.metre/pq.kilometre, 1])
1001.0
>>> be_np = Backend(np)
>>> be_np.sum([[1000*pq.metre/pq.kilometre, 1], [3, 4]], axis=1)
array([2., 7.])
chempy.units.allclose(a, b, rtol=1e-08, atol=None)[source]

Analogous to numpy.allclose.

chempy.units.compare_equality(a, b)[source]

Returns True if two arguments are equal.

Both arguments need to have the same dimensionality.

Parameters
aquantity
bquantity

Examples

>>> km, m = default_units.kilometre, default_units.metre
>>> compare_equality(3*km, 3)
False
>>> compare_equality(3*km, 3000*m)
True
chempy.units.concatenate(arrays, **kwargs)[source]

Patched version of numpy.concatenate

Examples

>>> from chempy.units import default_units as u
>>> all(concatenate(([2, 3]*u.s, [4, 5]*u.s)) == [2, 3, 4, 5]*u.s)
True
chempy.units.default_unit_in_registry(value, registry)[source]
chempy.units.fold_constants(arg)[source]
chempy.units.format_string(value, precision='%.5g', tex=False)[source]

Formats a scalar with unit as two strings

Parameters
value: float with unit
precision: str
tex: bool

LaTeX formatted or not? (no ‘$’ signs)

Examples

>>> print(' '.join(format_string(0.42*default_units.mol/default_units.decimetre**3)))
0.42 mol/decimetre**3
>>> print(' '.join(format_string(2/default_units.s, tex=True)))
2 \mathrm{\frac{1}{s}}
chempy.units.get_derived_unit(registry, key)[source]

Get the unit of a physcial quantity in a provided unit system.

Parameters
registry: dict (str: unit)

mapping ‘length’, ‘mass’, ‘time’, ‘current’, ‘temperature’, ‘luminous_intensity’, ‘amount’. If registry is None the function returns 1.0 unconditionally.

key: str

one of the registry keys or one of: ‘diffusivity’, ‘electricalmobility’, ‘permittivity’, ‘charge’, ‘energy’, ‘concentration’, ‘density’, ‘radiolytic_yield’.

Examples

>>> m, s = default_units.meter, default_units.second
>>> get_derived_unit(SI_base_registry, 'diffusivity') == m**2/s
True
chempy.units.get_physical_dimensionality(value)[source]
chempy.units.get_physical_quantity(*args, **kwargs)[source]

get_physical_quantity is deprecated, it will be missing in 0.8.0. Use get_physical_dimensionality instead.

chempy.units.html_of_unit(quant)[source]

Returns HTML reperesentation of the unit of a quantity

Examples

>>> print(html_of_unit(2*default_units.m**2))
m<sup>2</sup>
chempy.units.is_quantity(arg)[source]
chempy.units.is_unitless(expr)[source]

Returns True if expr is unitless, otherwise False

Examples

>>> is_unitless(42)
True
>>> is_unitless(42*default_units.kilogram)
False
chempy.units.latex_of_unit(quant)[source]

Returns LaTeX reperesentation of the unit of a quantity

Examples

>>> print(latex_of_unit(1/default_units.kelvin))
\mathrm{\frac{1}{K}}
chempy.units.linspace(start, stop, num=50)[source]

Analogous to numpy.linspace.

Examples

>>> abs(linspace(2, 8, num=3)[1] - 5) < 1e-15
True
chempy.units.logspace_from_lin(start, stop, num=50)[source]

Logarithmically spaced data points

Examples

>>> abs(logspace_from_lin(2, 8, num=3)[1] - 4) < 1e-15
True
chempy.units.magnitude(value)[source]
chempy.units.polyfit(x, y, deg, **kwargs)[source]
chempy.units.polyval(p, x)[source]
chempy.units.rescale(value, unit)[source]
chempy.units.simplified(value)[source]
chempy.units.tile(array, *args, **kwargs)[source]

Patched version of numpy.tile (with support for units)

chempy.units.to_unitless(value, new_unit=None)[source]

Nondimensionalization of a quantity.

Parameters
value: quantity
new_unit: unit

Examples

>>> '%.1g' % to_unitless(1*default_units.metre, default_units.nm)
'1e+09'
>>> '%.1g %.1g' % tuple(to_unitless([1*default_units.m, 1*default_units.mm], default_units.nm))
'1e+09 1e+06'
chempy.units.unicode_of_unit(quant)[source]

Returns unicode reperesentation of the unit of a quantity

Examples

>>> print(unicode_of_unit(1/default_units.kelvin))
1/K
chempy.units.uniform(container)[source]

Turns a list, tuple or dict with mixed units into one with uniform units.

Parameters
containertuple, list or dict

Examples

>>> km, m = default_units.kilometre, default_units.metre
>>> uniform(dict(a=3*km, b=200*m))  
{'b': array(200.0) * m, 'a': array(3000.0) * m}
chempy.units.unit_of(expr, simplified=False)[source]

Returns the unit of a quantity

Examples

>>> unit_of(42*pq.second) == unit_of(12*pq.second)
True
>>> unit_of(42)
1
chempy.units.unit_registry_from_human_readable(unit_registry)[source]

Deserialization of unit_registry.

chempy.units.unit_registry_to_human_readable(unit_registry)[source]

Serialization of a unit registry.

chempy.units.unitless_in_registry(value, registry)[source]