Reactions

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: ≔, ⩴, ≕

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.

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.

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.

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.

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.

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> Reaction("2H2 + O2 = 2H2O")
  equation: 2H2 + O2 = 2H2O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0

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> length(Reaction("2H2 + O2 = 2H2O"))
3

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

julia> Reaction("2H2 + O2 = 2H2O")
  equation: 2H2 + O2 = 2H2O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0

julia> Reaction("2H2 + O2 = 2H2O").products
OrderedDict{Species{Int64}, Int64} with 1 entry:
  H2O {H2O} [H2O ◆ H₂O] => 2

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

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

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).

Reaction(s::S) where {S<:AbstractSpecies} -> Reaction

Construct a trivial Reaction from a single species.

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).

Reaction{U,T}(s::S) where {U,T,S} -> Reaction

Construct a typed Reaction from a single species.

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.

*(ν::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> 2Species("H2O")
  equation: ∅ = 2H₂O
 reactants: ∅
  products: H₂O => 2
    charge: 0

*(ν::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> 3Reaction("2H2 + O2 = 2H2O")
  equation: 6H₂ + 3O₂ = 6H₂O
 reactants: H₂ => 6, O₂ => 3
  products: H₂O => 6
    charge: 0

+(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> 2Species("H2") + Species("O2") - 2Species("H2O")
  equation: 2H₂O = 2H₂ + O₂
 reactants: H₂O => 2
  products: H₂ => 2, O₂ => 1
    charge: 0

+(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> Reaction("2H2 + O2 = H2O") + Species("H2O")
  equation: 2H₂ + O₂ = 2H₂O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0

+(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

-(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> -Species("H2O")
  equation: H₂O = ∅
 reactants: H₂O => 1
  products: ∅
    charge: 0

-(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> 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

-(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

-(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> Reaction("2H2 + O2 = 3H2O") - Species("H2O")
  equation: 2H₂ + O₂ = 2H₂O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0

-(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(::Type{Reaction}, s::S) where {S<:AbstractSpecies} -> Reaction

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

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

Convert a species to a typed Reaction.

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> 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(r::Reaction, i::Symbol) -> Any

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

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(r::Reaction, sym::Symbol) -> Bool

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

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(r::Reaction)

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

Examples

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!(r::Reaction, value, i::Symbol)

Set a property value for the reaction.

Examples

julia> Reaction("H2 + O2 = H2O")[:ΔᵣH⁰] = -241.8
-241.8

Base.setproperty!(r::Reaction, sym::Symbol, value)

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

Examples

julia> setproperty!(Reaction("H2 + O2 = H2O"), :ΔᵣH⁰, -241.8)

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(io::IO, r::Reaction)

Display a reaction in a compact form.

Arguments

• io: output stream
• r: reaction to display

Examples

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

Base.values(r::Reaction)

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

Examples

julia> collect(values(Reaction("2H2 + O2 = 2H2O")))
3-element Vector{Int64}:
 -2
 -1
  2

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> CemReaction("C + H = CH")
  equation: C + H = CH
 reactants: C => 1, H => 1
  products: CH => 1
    charge: 0

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

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

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)

charge(r::Reaction)

Return the charge difference between products and reactants.

Examples

julia> charge(Reaction("Fe + 2H2O = FeO2- + 4H+"))
3

colored(r::Reaction) -> String

Return the colored terminal representation of the reaction.

Examples

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

julia> print(colored(r))  # Returns string with ANSI color codes

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.

equal_sign(r::Reaction) -> Char

Return the equality operator character of the reaction.

equation(r::Reaction) -> String

Return the equation string of the reaction.

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 (equationstring, coloredstring, total_charge).

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.

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.

products(r::Reaction) -> OrderedDict

Return the products dictionary (species => coefficient).

Examples

julia> products(Reaction("CaCO3 = CO3-2 + Ca+2")) == Dict(Species("CO3-2") => 1, Species("Ca+2") => 1)
true

properties(r::Reaction) -> OrderedDict{Symbol,PropertyType}

Return the properties dictionary of the reaction.

Examples

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

reactants(r::Reaction) -> OrderedDict

Return the reactants dictionary (species => coefficient).

Examples

julia> reactants(Reaction("CaCO3 = CO3-2 + Ca+2")) == Dict(Species("CaCO3") => 1)
true

remove_zeros(d::AbstractDict) -> AbstractDict

Remove all entries with zero values from a dictionary.

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

simplify_reaction(r::Reaction) -> Reaction

Simplify a reaction by canceling common species from both sides.

Examples

julia> simplify_reaction(Reaction("2H2 + O2 + H2O = 3H2O"))
  equation: 2H₂ + O₂ = 2H₂O
 reactants: H₂ => 2, O₂ => 1
  products: H₂O => 2
    charge: 0

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 (reactantsdict, productsdict) with positive coefficients.

symbol(r::Reaction) -> String

Return the symbol string of the reaction.