Public Interface

ChemEquations

Write and balance chemical equations elegantly and efficiently.

struct ChemEquation{T<:Real}

• tuples::Array{Tuple{Compound,T},1} where T<:Real

Stores chemical equation's compounds and their coefficients in a structured way.

ChemEquation(str::AbstractString) -> ChemEquation{Int64}

Constructs a chemical equation from the given string. If no {Type} is provided, it defaults to Int.

Parsing is insensitive to whitespace. Any character in EQUALCHARS separates the equation into two sides, while + separates the equation into compounds.

Examples

julia> ChemEquation("N2+O2⇌2NO")
N2 + O2 = 2 NO

julia> ChemEquation("CH3COOH + Na → H2 + CH3COONa")
C2H4O2 + Na = H2 + C2H3O2Na

julia> ChemEquation("⏣H + Cl2 = ⏣Cl + HCl")
⏣H + Cl2 = ⏣Cl + HCl

julia> ChemEquation{Rational}("1//2 H2 → H")
1//2 H2 = H

julia> ChemEquation{Float64}("0.5 H2 + 0.5 Cl2 = HCl")
0.5 H2 + 0.5 Cl2 = HCl

```

struct Compound

• tuples::Array{Tuple{String,Int64},1}

• charge::Int64

Stores chemical compound's elements and charge in a structured way.

Compound(str::AbstractString) -> Compound

Constructs a compound from str.

An element begins with an uppercase unicode letter and ends with a lowercase unicode letter or a unicode symbol.

Parsing is insensitive to whitespace and underscores (_), but also to state symbols ((s), (l), (g), (aq)). Special parsing is implemented for:

• parens (e.g. "(CH3COO)2Mg")
• compounds with "*" (e.g. "CuSO4 * 5H2O")
• electrons ("e")

Charge is in the form "{±n}" or "{n±}". It is automatically deduced for electron ("e").

Examples

julia> Compound("H2O(s)")
H2O

julia> Compound("H3O{+}")
H3O{+}

julia> Compound("(CH3COO)2Mg")
C4H6O4Mg

julia> Compound("CuSO4 * 5H2O")
CuSO9H10

julia> Compound("⬡Cl")
⬡Cl

@cc_str

Constructs a compound with cc"str" syntax, instead of Compound(str).

Examples

julia> cc"H3O{+1}"
H3O{+}

@ce_str

Constructs a chemical equation with ce"str" syntax, instead of ChemEquation(str).

Examples

julia> ce"H2 + O2 → H2O"
H2 + O2 = H2O

==(equation_1::ChemEquation, equation_2::ChemEquation) -> Any

Checks whether two equations are chemically equal.

Examples

julia> ce"H2 + O2 = H2O" == ce"O2 + H2 → H2O"
true

==(compound_1::Compound, compound_2::Compound) -> Bool

Checks whether two compounds are chemically equal.

Examples

julia> cc"MgOHOH" == cc"Mg(OH)2"
true

show(io::IO, equation::ChemEquation)

Displays the chemical equation using Base.string(::Compound).

show(io::IO, compound::Compound)

Displays the compound using Base.string(::Compound).

string(equation::ChemEquation) -> String

Creates a string to represent the chemical equation.

All compounds are displayed with Base.string(::Compound), in the order in which they were originally given, with coefficients equal to 1 not displayed. '=' and '+' are used as separators, with spaces inserted for easier reading.

Examples

julia> string(ce"Cr2O7{2-} + H{+} + {-} = Cr{3+} + H2O")
"Cr2O7{-2} + H{+} + e = Cr{+3} + H2O"

string(compound::Compound) -> String

Creates a string to represent the compound.

All elements are displayed only once (e.g. "H2O" and not "HOH"), in the order in which they were originally given (e.g. "MgO2H2" from cc"Mg(OH)2"), with coefficients equal to 1 not displayed (e.g. "H" and not "H1").

Examples

julia> string(cc"CuSO4 * 5 H2O")
"CuSO9H10"

balance(equation::ChemEquation{var"#s15"} where var"#s15"<:(Union{Complex{S}, S} where S<:Integer); fractions) -> ChemEquation

Balances the coefficients of a chemical equation with integer coefficients.

The minimal integer solution is displayed by default. If fractions is true, they solution will be displayed as rational fractions instead.

Examples

julia> balance(ce"Fe + Cl2 = FeCl3", fractions=true)
Fe + 3//2 Cl2 = FeCl3

julia> balance(ce"Cr2O7{-2} + H{+} + {-} = Cr{+3} + H2O")
Cr2O7{-2} + 14 H{+} + 6 e = 2 Cr{+3} + 7 H2O

balance(equation::ChemEquation) -> ChemEquation

Balances the coefficients of a chemical equation. If the equation cannot be balanced, an error is thrown.

Examples

julia> balance(ce"Fe + Cl2 = FeCl3")
2 Fe + 3 Cl2 = 2 FeCl3

julia> balance(ChemEquation{Rational}("H2 + Cl2 = HCl"))
1//2 H2 + 1//2 Cl2 = HCl

balancematrix(equation::ChemEquation) -> Any

Balances an equation matrix using the nullspace method. Returns an array in which each column represents a solution.

References

• Thorne (2009)

balancematrix(equation::ChemEquation{T<:(Union{Complex{S}, S} where S<:Integer)}; fractions) -> Any

Same as balancematrix(::ChemEquation), but for a chemical equation with integer coefficients.

By default, the solutions of integer matrices are displayed as integers. If fractions is true, they will be displayed as rational fractions instead.

compounds(equation::ChemEquation) -> Array{_A,1} where _A

Returns chemical equation's compounds in a list.

elements(equation::ChemEquation) -> Array{String,1}

Returns chemical equation's unique elements.

Examples

julia> elements(ce"2 H2 + O2 → 2 H2O")
2-element Array{String,1}:
 "H"
 "O"

elements(compound::Compound) -> Array{String,1}

Returns compound's elements as strings.

Examples

julia> elements(cc"CH3COOH")
3-element Array{String,1}:
 "C"
 "H"
 "O"

equationmatrix(equation::ChemEquation{T}) -> Array

Creates an equation matrix in which rows correspond to atoms and columns correspond to compounds.

Examples

julia> equationmatrix(ce"H2 + Cl2 → HCl")
2×3 Array{Int64,2}:
 2  0  1
 0  2  1

hascharge(equation::ChemEquation) -> Bool

True if chemical equation has at least one compound with nonzero charge.

hascharge(compound::Compound) -> Bool

True if the compound's charge is nonzero.