Formulas

struct AtomGroup{T}

Simple container pairing an atomic symbol with a numeric coefficient.

Fields

• coef::T: numeric coefficient.
• sym::Symbol: atomic symbol.

Examples

julia> AtomGroup(:H, 2)
AtomGroup{Int64}(2, :H)

julia> AtomGroup(:Ca)
AtomGroup{Int64}(1, :Ca)

AtomGroup(sym::Symbol) -> AtomGroup
AtomGroup(sym::Symbol, coef::T) where {T<:Number} -> AtomGroup{T}

Constructors for AtomGroup.

Arguments

• sym: atomic symbol.
• coef: numeric coefficient (default 1).

Examples

julia> AtomGroup(:C)
AtomGroup{Int64}(1, :C)

julia> AtomGroup(:C, 3)
AtomGroup{Int64}(3, :C)

Base.convert(::Type{AtomGroup}, sym::Symbol) -> AtomGroup

Convert a Symbol to a unit AtomGroup (coefficient = 1).

Examples

julia> convert(AtomGroup, :O)
AtomGroup{Int64}(1, :O)

stoichtype(f::Formula{T}) where {T} -> Type{T}

Return the numeric stoichiometric coefficient type T for formula f.

Examples

julia> stoichtype(Formula("H2O"))
Int64

struct Formula{T}

Canonical container for a chemical formula.

Fields

• expr::String: original input expression.
• phreeqc::String: PHREEQC-compatible representation.
• unicode::String: Unicode pretty representation.
• colored::String: colored terminal representation.
• composition::OrderedDict{Symbol,T}: mapping element symbol to coefficient.
• charge::Int8: formal integer charge.

Examples

julia> f = Formula("H2O");

julia> composition(f)[:H]
2

expr(f::Formula) -> String

Return the original expression string stored in f.

Examples

julia> expr(Formula("H2O"))
"H2O"

phreeqc(f::Formula) -> String

Return the PHREEQC-compatible representation of f.

Examples

julia> phreeqc(Formula("H2O"))
"H2O"

unicode(f::Formula) -> String

Return the Unicode pretty representation of f.

Examples

julia> phreeqc(Formula("C3A"))
"C3A"

colored(f::Formula) -> String

Return the colored terminal representation of f.

Examples

julia> colored(Formula("Ca(HSiO3)+"))

composition(f::Formula) -> OrderedDict{Symbol,T}

Return the composition mapping (element symbol => coefficient).

Examples

julia> composition(Formula("Ca(HSiO3)+"))

charge(f::Formula) -> Int8

Return the formal integer charge of the formula.

Examples

julia> charge(Formula("Ca(HSiO3)+"))
1

check_mendeleev(f::Formula) -> Bool

Validate that all element symbols in f exist in the package elements registry. Returns true when valid; otherwise throws an informative error.

Examples

julia> check_mendeleev(Formula("NaCl"))
true

calculate_molar_mass(atoms::AbstractDict{Symbol,T}) where {T<:Number} -> Quantity

Calculate the molar mass from an atomic composition dictionary.

Arguments

• atoms: dictionary mapping element symbols to stoichiometric coefficients.

Returns

• Molar mass as a Quantity in g/mol units.

Examples

julia> calculate_molar_mass(OrderedDict(:H => 2, :O => 1))
0.0180149999937744 kg mol⁻¹

apply(func::Function, f::Formula, args...; kwargs...) -> Formula

Element-wise apply func to all numeric components of f and to its charge. Quantities are handled, attempting to preserve dimensions when possible.

Examples

julia> result = apply(x -> x*2, Formula("H2O"));

julia> result[:H]
4

pprint(f::Formula)

Pretty-print a Formula to standard output. Shows type, a titled "formula" line, composition and charge. The output matches the multi-line representation used by show(io, MIME"text/plain", ...) but is sent to stdout.

Arguments

• f : Formula to pretty-print.

pprint(s::Species)

Pretty-print a Species to standard output using the same multi-line layout as the MIME "text/plain" show method.

Arguments

• s : Species instance to print.

Returns

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

pprint(s::CemSpecies)

Pretty-print a CemSpecies to standard output using the same multi-line layout as the MIME "text/plain" show method.

Arguments

• s : CemSpecies instance to print.

Returns

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

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.

pprint(A::AbstractMatrix, indep_comp_names::AbstractVector, dep_comp_names::AbstractVector)

Print a stoichiometric matrix with colored formatting.

Arguments

• A: stoichiometric matrix.
• indep_comp_names: row labels (independent components).
• dep_comp_names: column labels (dependent components).

Uses text highlighters to color positive (red), negative (blue), and zero (concealed) values.

    pprint(reactions::AbstractVector{<:Reaction})

Pretty print a list of reactions.

Arguments

• SM: StoichMatrix.

Examples

julia> H₂O, H⁺, OH⁻, CO₂, HCO₃⁻, CO₃²⁻ = Species.(split("H₂O H⁺ OH⁻ CO₂ HCO₃⁻ CO₃²⁻"))
6-element Vector{Species{Int64}}:
 H₂O {H₂O} [H₂O ◆ H2O]
 H⁺ {H⁺} [H⁺ ◆ H+]
 OH⁻ {OH⁻} [OH⁻ ◆ OH-]
 CO₂ {CO₂} [CO₂ ◆ CO2]
 HCO₃⁻ {HCO₃⁻} [HCO₃⁻ ◆ HCO3-]
 CO₃²⁻ {CO₃²⁻} [CO₃²⁻ ◆ CO3-2]

julia> SM = StoichMatrix([H₂O, H⁺, OH⁻, CO₂, HCO₃⁻, CO₃²⁻])
┌─────┬─────┬────┬─────┬─────┬───────┬───────┐
│     │ H₂O │ H⁺ │ OH⁻ │ CO₂ │ HCO₃⁻ │ CO₃²⁻ │
├─────┼─────┼────┼─────┼─────┼───────┼───────┤
│ H₂O │   1 │    │   1 │     │     1 │     1 │
│  H⁺ │     │  1 │  -1 │     │    -1 │    -2 │
│ CO₂ │     │    │     │   1 │     1 │     1 │
└─────┴─────┴────┴─────┴─────┴───────┴───────┘

julia> pprint(reactions(SM))
  OH⁻ │ H₂O = OH⁻ + H⁺
HCO₃⁻ │ H₂O + CO₂ = HCO₃⁻ + H⁺
CO₃²⁻ │ H₂O + CO₂ = CO₃²⁻ + 2H⁺