ChemistryLab.jl

Appearance

Reactions ​

ChemistryLab.EQUAL_OPS Constant
julia
EQUAL_OPS

Union of all supported equality operators for chemical reactions.

Combines forward arrows, backward arrows, double arrows, rate arrows, and equality signs (excluding the first element of each collection to avoid duplicates).

This collection is used to dynamically generate reaction operator methods.

  • Forward: →, ↣, ↦, ⇾, ⟶, ⟼, ⥟, ⇀, ⇁, ⇒, ⟾

  • Backward: ←, ↢, ↤, ⇽, ⟵, ⟻, ⥚, ⥞, ↼, ↽, ⇐, ⟽

  • Equilibrium: ↔, ⟷, ⇄, ⇆, ⇌, ⇋, ⇔, ⟺

  • Rate: ⇐, ⟽, ⇒, ⟾

  • Equality: ≔, ⩴, ≕

ChemistryLab.bwd_arrows Constant
julia
bwd_arrows

Collection of backward arrow symbols used in chemical reaction notation.

Contains symbols representing reverse reaction directions, including:

  • Simple arrows: '<', '←'

  • Various Unicode arrows with different styles and weights

  • Specialized arrows for reverse reaction notation

Used to define reaction directionality from products to reactants.

ChemistryLab.double_arrows Constant
julia
double_arrows

Collection of double arrow symbols representing equilibrium reactions.

Contains symbols representing:

  • Simple equilibrium: '↔'

  • Various Unicode double arrows

  • Specialized equilibrium symbols

  • Bidirectional reaction indicators

Used to denote reversible reactions and equilibrium states.

ChemistryLab.equal_signs Constant
julia
equal_signs

Collection of equality signs used in chemical reaction equations.

Contains various forms of equality operators including:

  • Standard equals sign: '='

  • Definition operators: '≔'

  • Specialized equality symbols

  • Assignment operators

Used to separate reactants from products in balanced equations.

ChemistryLab.fwd_arrows Constant
julia
fwd_arrows

Collection of forward arrow symbols used in chemical reaction notation.

Contains symbols representing forward reaction directions, including:

  • Simple arrows: '>', '→'

  • Various Unicode arrows with different styles and weights

  • Specialized arrows for reaction notation

Used to define reaction directionality from reactants to products.

ChemistryLab.pure_rate_arrows Constant
julia
pure_rate_arrows

Collection of specialized arrows for rate-based reaction notation.

Contains symbols commonly used to represent:

  • Reaction rates

  • Kinetic directions

  • Specialized reaction mechanisms

These are often used in more advanced chemical kinetics notation.

ChemistryLab.Reaction Type
julia
Reaction(equation::AbstractString, S::Type{<:AbstractSpecies}=Species; properties, side, species_list) -> Reaction

Construct a Reaction from an equation string.

Arguments

  • equation: reaction equation string (e.g., "2H2 + O2 = 2H2O").

  • S: species type to use (default: Species).

  • properties: property dictionary (default: empty OrderedDict).

  • side: how to split species - :none, :sign, :reactants, :products (default: :none).

  • species_list: optional list of known species for lookup.

Examples

julia
julia> Reaction("2H2 + O2 = 2H2O")
  equation: 2H2 + O2 = 2H2O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0
ChemistryLab.Reaction Type
julia
struct Reaction{SR<:AbstractSpecies,TR<:Number,SP<:AbstractSpecies,TP<:Number}

Representation of a chemical reaction with reactants and products.

Fields

  • equation::String: Unicode equation string.

  • colored::String: colored terminal representation.

  • reactants::OrderedDict{SR,TR}: species => coefficient for reactants.

  • products::OrderedDict{SP,TP}: species => coefficient for products.

  • charge::IC: charge difference between products and reactants.

  • equal_sign::Char: equality operator character.

  • properties::OrderedDict{Symbol,PropertyType}: thermodynamic and other properties.

Examples

julia
julia> length(Reaction("2H2 + O2 = 2H2O"))
3

julia> length(products(Reaction("2H2 + O2 = 2H2O")))
1
julia
julia> Reaction("2H2 + O2 = 2H2O")
  equation: 2H2 + O2 = 2H2O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0
julia
julia> Reaction("2H2 + O2 = 2H2O").products
OrderedDict{Species{Int64}, Int64} with 1 entry:
  H2O {H2O} [H2O ◆ H₂O] => 2
ChemistryLab.Reaction Method
julia
Reaction(reac::AbstractVector{<:AbstractSpecies}, prod::AbstractVector{<:AbstractSpecies}; kwargs...) -> Reaction

Construct a balanced Reaction from separate reactant and product vectors. Stoichiometric coefficients are computed automatically to balance the reaction.

Arguments

  • reac: vector of reactant species

  • prod: vector of product species

  • equal_sign: equality operator character (default: '=')

  • properties: property dictionary (default: empty OrderedDict)

  • scaling: scaling factor for all coefficients (default: 1)

  • auto_scale: if true, scale by GCD (default: false)

  • side: splitting criterion (default: :none)

Returns

  • A balanced Reaction object
ChemistryLab.Reaction Method
julia
Reaction(species::AbstractVector{<:AbstractSpecies}; equal_sign='=', properties, scaling=1, auto_scale=false, side=:sign) -> Reaction

Construct a balanced Reaction from a vector of species. The first species is treated as the dependent component, and stoichiometric coefficients are computed automatically.

Arguments

  • species: vector of species to balance (first is dependent component)

  • equal_sign: equality operator character (default: '=')

  • properties: property dictionary (default: empty OrderedDict)

  • scaling: scaling factor for all coefficients (default: 1)

  • auto_scale: if true, scale by GCD (default: false)

  • side: splitting criterion (default: :sign)

Returns

  • A balanced Reaction object
ChemistryLab.Reaction Method
julia
Reaction(r::R; symbol, equal_sign, properties, side) where {R<:Reaction} -> Reaction

Copy constructor for Reaction with optional field overrides.

Arguments

  • r: source Reaction.

  • equal_sign: override equality operator (default: keep original).

  • properties: override properties (default: keep original).

  • side: reorganization criterion (default: :none).

ChemistryLab.Reaction Method
julia
Reaction(s::S) where {S<:AbstractSpecies} -> Reaction

Construct a trivial Reaction from a single species.

ChemistryLab.Reaction Method
julia
Reaction(species_stoich::AbstractDict{S,T}; symbol, equal_sign='=', properties, side=:sign) where {S,T} -> Reaction

Construct a Reaction from a dictionary with signed stoichiometric coefficients.

Arguments

  • species_stoich: dictionary mapping species to signed coefficients (negative = reactants, positive = products).

  • symbol: symbol naming the reaction.

  • equal_sign: equality operator character (default '=').

  • properties: property dictionary (default: empty OrderedDict).

  • side: splitting criterion (default: :sign).

ChemistryLab.Reaction Method
julia
Reaction{U,T}(s::S) where {U,T,S} -> Reaction

Construct a typed Reaction from a single species.

ChemistryLab.Reaction Method
julia
Reaction(reactants::AbstractDict{SR,TR}, products::AbstractDict{SP,TP}; symbol, equal_sign='=', properties, side) where {SR,TR,SP,TP} -> Reaction

Construct a Reaction from reactants and products dictionaries.

Arguments

  • reactants: dictionary mapping reactant species to coefficients.

  • products: dictionary mapping product species to coefficients.

  • symbol: symbol naming the reaction.

  • equal_sign: equality operator character (default '=').

  • properties: property dictionary (default: empty OrderedDict).

  • side: how to reorganize species - :none, :sign, :reactants, :products (default: :none). Automatically balances electron charges in the equation.

Base.:* Method
julia
*(ν::Number, s::AbstractSpecies) -> Reaction

Create a Reaction with a single species and stoichiometric coefficient.

Arguments

  • ν: stoichiometric coefficient

  • s: species to include in the reaction

Returns

  • A Reaction object with the single species and given coefficient

Examples

julia
julia> 2Species("H2O")
  equation: ∅ = 2H₂O
 reactants: ∅
  products: H₂O => 2
    charge: 0
Base.:* Method
julia
*(ν::Number, r::Reaction) -> Reaction

Multiply all stoichiometric coefficients in a reaction by a scalar.

Arguments

  • ν: scaling factor

  • r: reaction to scale

Returns

  • A new Reaction with all coefficients multiplied by ν

Examples

julia
julia> 3Reaction("2H2 + O2 = 2H2O")
  equation: 6H₂ + 3O₂ = 6H₂O
 reactants: H₂ => 6, O₂ => 3
  products: H₂O => 6
    charge: 0
Base.:+ Method
julia
+(s::S1, t::S2) where {S1<:AbstractSpecies,S2<:AbstractSpecies} -> Reaction

Add two species to create a Reaction.

Arguments

  • s: first species

  • t: second species

Returns

  • A Reaction with both species as reactants (coefficient 1 each)

Examples

julia
julia> 2Species("H2") + Species("O2") - 2Species("H2O")
  equation: 2H₂O = 2H₂ + O₂
 reactants: H₂O => 2
  products: H₂ => 2, O₂ => 1
    charge: 0
Base.:+ Method
julia
+(r::R, s::S) where {R<:Reaction,S<:AbstractSpecies} -> Reaction

Add a species to a reaction.

Arguments

  • r: reaction to modify

  • s: species to add as product

Returns

  • A new Reaction with the species added as product

Examples

julia
julia> Reaction("2H2 + O2 = H2O") + Species("H2O")
  equation: 2H₂ + O₂ = 2H₂O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0
Base.:+ Method
julia
+(r::R, u::U) where {R<:Reaction,U<:Reaction} -> Reaction

Add two reactions.

Arguments

  • r: first reaction

  • u: second reaction

Returns

  • A new Reaction combining both reactions
Base.:- Method
julia
-(s::AbstractSpecies) -> Reaction

Create a Reaction with a single species with coefficient -1.

Arguments

  • s: species to include in the reaction

Returns

  • A Reaction object with the single species and coefficient -1

Examples

julia
julia> -Species("H2O")
  equation: H₂O = ∅
 reactants: H₂O => 1
  products: ∅
    charge: 0
Base.:- Method
julia
-(r::Reaction) -> Reaction

Reverse a reaction (swap reactants and products).

Arguments

  • r: reaction to reverse

Returns

  • A new Reaction with reactants and products swapped

Examples

julia
julia> 3Reaction("2H2 + O2 = 2H2O") - 2Reaction("2H2 + O2 = 2H2O")
  equation: 6H₂ + 3O₂ + 4H₂O = 6H₂O + 4H₂ + 2O₂
 reactants: H₂ => 6, O₂ => 3, H₂O => 4
  products: H₂O => 6, H₂ => 4, O₂ => 2
    charge: 0
Base.:- Method
julia
-(s::S1, t::S2) where {S1<:AbstractSpecies,S2<:AbstractSpecies} -> Reaction

Subtract two species to create a Reaction.

Arguments

  • s: first species (positive coefficient)

  • t: second species (negative coefficient)

Returns

  • A Reaction with s as reactant and t as product
Base.:- Method
julia
-(r::R, s::S) where {R<:Reaction,S<:AbstractSpecies} -> Reaction

Subtract a species from a reaction.

Arguments

  • r: reaction to modify

  • s: species to remove from products (or add as reactant)

Returns

  • A new Reaction with the species subtracted

Examples

julia
julia> Reaction("2H2 + O2 = 3H2O") - Species("H2O")
  equation: 2H₂ + O₂ = 2H₂O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0
Base.:- Method
julia
-(r::R, u::U) where {R<:Reaction,U<:Reaction} -> Reaction

Subtract two reactions.

Arguments

  • r: first reaction

  • u: second reaction to subtract

Returns

  • A new Reaction representing r - u
Base.convert Method
julia
Base.convert(::Type{Reaction}, s::S) where {S<:AbstractSpecies} -> Reaction

Convert a species to a trivial Reaction (species = species).

Base.convert Method
julia
Base.convert(::Type{Reaction{U,T}}, s::S) where {U,T,S} -> Reaction

Convert a species to a typed Reaction.

Base.getindex Method
julia
Base.getindex(r::Reaction, s::AbstractSpecies) -> Number

Get the stoichiometric coefficient for a species in the reaction. Return negative values for reactants, positive for products, and 0 if the species is not present.

Examples

julia
julia> Reaction("2H2 + O2 = 2H2O")[Species("H2")]
-2

julia> Reaction("2H2 + O2 = 2H2O")[Species("O2")]
-1

julia> Reaction("2H2 + O2 = 2H2O")[Species("H2O")]
2

julia> Reaction("2H2 + O2 = 2H2O")[Species("CO2")]
0
Base.getindex Method
julia
Base.getindex(r::Reaction, i::Symbol) -> Any

Access a reaction property by symbol key. Return nothing if the property is not found.

Base.getproperty Method
julia
Base.getproperty(r::Reaction, sym::Symbol) -> Any

Access reaction fields or registered properties. Throws an error if the symbol is neither a field nor a property.

Base.haskey Method
julia
Base.haskey(r::Reaction, sym::Symbol) -> Bool

Check if a property key exists in the reaction properties dictionary.

Base.iterate Function
julia
Base.iterate(r::Reaction, state=(1, nothing))

Iterate over all species in the reaction with signed coefficients. Yields (species, coefficient) pairs where coefficients are negative for reactants and positive for products.

Base.keys Method
julia
Base.keys(r::Reaction)

Return an iterator over all species in the reaction (reactants and products).

Examples

julia
julia> collect(keys(Reaction("2H2 + O2 = 2H2O")))
3-element Vector{Species{Int64}}:
 H2 {H2} [H2 ◆ H₂]
 O2 {O2} [O2 ◆ O₂]
 H2O {H2O} [H2O ◆ H₂O]
Base.setindex! Method
julia
Base.setindex!(r::Reaction, value, i::Symbol)

Set a property value for the reaction.

Examples

julia
julia> Reaction("H2 + O2 = H2O")[:ΔᵣH⁰] = -241.8
-241.8
Base.setproperty! Method
julia
Base.setproperty!(r::Reaction, sym::Symbol, value)

Set a property value, preventing direct modification of structural fields.

Examples

julia
julia> setproperty!(Reaction("H2 + O2 = H2O"), :ΔᵣH⁰, -241.8)
Base.show Method
julia
Base.show(io::IO, ::MIME"text/plain", r::Reaction)

Display a reaction in a detailed form.

Arguments

  • io: output stream

  • r: reaction to display

Base.show Method
julia
Base.show(io::IO, r::Reaction)

Display a reaction in a compact form.

Arguments

  • io: output stream

  • r: reaction to display

Examples

julia
julia> Reaction("H2 + O2 = H2O")
  equation: H2 + O2 = H2O
 reactants: H₂ => 1, O₂ => 1
  products: H₂O => 1
    charge: 0
Base.values Method
julia
Base.values(r::Reaction)

Return an iterator over all stoichiometric coefficients (negative for reactants, positive for products).

Examples

julia
julia> collect(values(Reaction("2H2 + O2 = 2H2O")))
3-element Vector{Int64}:
 -2
 -1
  2
ChemistryLab.CemReaction Method
julia
CemReaction(equation::AbstractString, args...; kwargs...) -> Reaction

Construct a Reaction using CemSpecies from an equation string. Convenience constructor equivalent to Reaction(equation, CemSpecies, args...; kwargs...).

Examples

julia
julia> CemReaction("C + H = CH")
  equation: C + H = CH
 reactants: C => 1, H => 1
  products: CH => 1
    charge: 0
ChemistryLab.add_stoich Method
julia
add_stoich(d1::AbstractDict{S1,T1}, d2::AbstractDict{S2,T2}) where {S1<:AbstractSpecies,T1<:Number,S2<:AbstractSpecies,T2<:Number} -> OrderedDict

Add stoichiometric coefficients from two dictionaries.

Arguments

  • d1: first dictionary of species => coefficients

  • d2: second dictionary of species => coefficients

Returns

  • A new dictionary with combined coefficients
ChemistryLab.apply Method
julia
apply(func::Function, r::Reaction{SR,TR,SP,TP}, args...; kwargs...) where {SR<:AbstractSpecies,TR<:Number,SP<:AbstractSpecies,TP<:Number}

Apply a function to all species and coefficients in a reaction.

Arguments

  • func: function to apply to species and coefficients

  • r: reaction to transform

  • args...: additional arguments for func

  • kwargs...: additional keyword arguments

Returns

  • A new Reaction with transformed species and coefficients

A function that throws leaves the coefficient untouched, silently

func is applied inside a try, and a coefficient it cannot handle is returned unchanged rather than raising. That is deliberate — a reaction can mix plain numbers with symbolic or dimensioned coefficients, and a transform meaningful for one kind is not meaningful for the others — but it means a transform that fails everywhere is indistinguishable from one with nothing to do.

The case that bites is a substitution. apply(x -> Int(substitute(x, d)), r) on an alkane combustion silently keeps the symbol wherever the coefficient is a half-integer, because Int(7//2) throws, and the result then reads as a mixture of numbers and symbols that looks like a partial substitution rather than like a bug:

n = 1 : CH₄  + 2O₂                   = 2H₂O + CO₂
n = 2 : C₂H₆ + (n+(1//4)(2+2n))O₂    = 3H₂O + 2CO₂     ← Int(7//2) threw

Drop the conversion — apply(x -> Symbolics.value(substitute(x, d)), r) keeps the rational and substitutes everywhere — and check the result rather than assuming it: a coefficient that is still symbolic after a full substitution is the signal.

ChemistryLab.build_species_stoich Method
julia
build_species_stoich(species::AbstractVector{<:AbstractSpecies}; scaling=1, auto_scale=false) -> OrderedDict

Build stoichiometric coefficients from a species vector using stoichiometric matrix analysis. The first species is treated as the dependent component.

Arguments

  • species: vector of species (first is the dependent component)

  • scaling: scaling factor for all coefficients (default: 1)

  • auto_scale: if true, scale by GCD to get integer coefficients (default: false)

Returns

  • OrderedDict mapping species to signed stoichiometric coefficients (negative for reactants)
ChemistryLab.charge Method
julia
charge(r::Reaction)

Return the charge difference between products and reactants.

Examples

julia
julia> charge(Reaction("Fe + 2H2O = FeO2- + 4H+"))
3
ChemistryLab.colored Method
julia
colored(r::Reaction) -> String

Return the colored terminal representation of the reaction.

Examples

julia
julia> r = Reaction("CaSO4 = Ca²⁺ + SO4²⁻");

julia> print(colored(r))  # Returns string with ANSI color codes
ChemistryLab.complete_thermo_functions! Method
julia
complete_thermo_functions!(r::Reaction)

Compute reaction thermodynamic properties from species properties. Calculates ΔᵣCp⁰, ΔᵣS⁰, ΔᵣH⁰, ΔᵣG⁰, and ΔᵣV⁰ if all species have the required properties.

ChemistryLab.equal_sign Method
julia
equal_sign(r::Reaction) -> Char

Return the equality operator character of the reaction.

ChemistryLab.equation Method
julia
equation(r::Reaction) -> String

Return the equation string of the reaction.

ChemistryLab.format_side Method
julia
format_side(side::AbstractDict{S,T}) where {S<:AbstractSpecies,T<:Number} -> (String, String, Int)

Format one side of a reaction equation.

Arguments

  • side: dictionary of species => coefficient for one side of the reaction.

Returns

  • Tuple of (equation_string, colored_string, total_charge).
ChemistryLab.merge_species_by_stoich Method
julia
merge_species_by_stoich(reactants::AbstractDict{SR,TR}, products::AbstractDict{SP,TP}) where {SR,TR,SP,TP} -> OrderedDict

Merge reactants and products into a single dictionary with signed coefficients. Reactants get negative coefficients, products get positive coefficients.

ChemistryLab.pprint Method
julia
pprint(r::Reaction)

Pretty-print a Reaction to standard output using the same multi-line layout as the MIME "text/plain" show method, but using the terminal-colored string when available.

Arguments

  • r : Reaction instance to print.

Returns

  • nothing (side-effect: formatted output to stdout).

Notes

  • The colored equation may not render correctly in non-interactive environments (CI, doctests, or redirected IO). This function uses colored(r) when available to produce a user-friendly output.
ChemistryLab.products Method
julia
products(r::Reaction) -> OrderedDict

Return the products dictionary (species => coefficient).

Examples

julia
julia> products(Reaction("CaCO3 = CO3-2 + Ca+2")) == Dict(Species("CO3-2") => 1, Species("Ca+2") => 1)
true
ChemistryLab.properties Method
julia
properties(r::Reaction) -> OrderedDict{Symbol,PropertyType}

Return the properties dictionary of the reaction.

Examples

julia
julia> properties(Reaction("H2 + O2 = H2O"))
OrderedDict{Symbol, Union{Missing, AbstractFunc, AbstractString, Function, Number, AbstractVector{<:Number}, AbstractVector{<:Pair{Symbol}}}}()
ChemistryLab.reactants Method
julia
reactants(r::Reaction) -> OrderedDict

Return the reactants dictionary (species => coefficient).

Examples

julia
julia> reactants(Reaction("CaCO3 = CO3-2 + Ca+2")) == Dict(Species("CaCO3") => 1)
true
ChemistryLab.remove_zeros Method
julia
remove_zeros(d::AbstractDict) -> AbstractDict

Remove all entries with zero values from a dictionary.

ChemistryLab.scale_stoich! Method
julia
scale_stoich!(species_stoich::AbstractDict{<:AbstractSpecies,<:Number})

Scale stoichiometric coefficients by their GCD if all are integers or rationals. Modifies the dictionary in place to ensure integer coefficients when possible.

Arguments

  • species_stoich: dictionary mapping species to stoichiometric coefficients
ChemistryLab.simplify_reaction Method
julia
simplify_reaction(r::Reaction) -> Reaction

Simplify a reaction by canceling common species from both sides.

Examples

julia
julia> simplify_reaction(Reaction("2H2 + O2 + H2O = 3H2O"))
  equation: 2H₂ + O₂ = 2H₂O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0
ChemistryLab.split_species_by_stoich Method
julia
split_species_by_stoich(species_stoich::AbstractDict{S,T}; side=:sign) where {S<:AbstractSpecies,T<:Number} -> (OrderedDict, OrderedDict)

Split a species-coefficient dictionary into reactants and products.

Arguments

  • species_stoich: dictionary mapping species to signed stoichiometric coefficients.

  • side: splitting criterion - :sign (by coefficient sign), :reactants, :left, :products, :right.

Returns

  • Tuple of (reactants_dict, products_dict) with positive coefficients.
ChemistryLab.symbol Method
julia
symbol(r::Reaction) -> String

Return the symbol string of the reaction.