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)

Formula(expr::AbstractString="") -> Formula{T}

Parse an input chemical formula string and return a Formula. Supports simple formulas, parentheses, hydrates, and common charge notations. Special tokens like Zz (charge placeholder) and e (electron) are handled.

Arguments

• expr: input formula string.

Examples

julia> f = Formula("SO4-2");

julia> composition(f)[:S]
1

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

Formula(f::Formula) -> Formula

Copy constructor: return a new Formula built from f's composition.

Formula(composition::AbstractDict{Symbol,T}, charge=0; order=ATOMIC_ORDER) where {T<:Number} -> Formula{T}

Construct a Formula from an explicit composition mapping.

Arguments

• composition: mapping of Symbol to numeric coefficient.
• charge: explicit integer charge (default 0).
• order: atomic ordering used for serialization.

Charge placeholder keys (:Zz, :Zz⁺, :e, :e⁻) are removed from the stored composition and used to compute the formal charge when charge == 0.

Examples

julia> f = Formula(OrderedDict(:Ca=>1, :C=>1, :O=>3));

julia> expr(f)
"CaCO3"

*(f::Formula, x::T) where {T<:Number} -> Formula

Multiply all stoichiometric coefficients of f by scalar x.

+(a::AtomGroup, b::Symbol) -> Formula

Convenience: add an AtomGroup and a Symbol (converted to an AtomGroup of coef 1).

+(f::Formula, atom::AtomGroup) -> Formula

Add an AtomGroup to a Formula (adjust stoichiometric coefficient for the atom).

+(a::AtomGroup{T}, b::AtomGroup{S}) where {T,S} -> Formula

Combine two AtomGroup values into a Formula. If the symbols are equal the result is a singleton composition with summed coefficients, otherwise both are included.

Examples

julia> result = AtomGroup(:H, 2) + AtomGroup(:H, 1);

julia> composition(result)[:H]
3

/(f::Formula, x::T) where {T<:Number} -> Formula

Divide all stoichiometric coefficients of f by scalar x.

//(f::Formula, x::T) where {T<:Number} -> Formula

Produce rational coefficients by dividing f's coefficients by x (rational result).

Base.convert(T::Type{<:Number}, f::Formula) -> Formula{T}

Convert the stoichiometric coefficient type of f to numeric type T.

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)

Base.getindex(f::Formula{T}, i::Symbol) where {T} -> T

Return the stoichiometric coefficient associated with symbol i. If i is not present, return zero(T) where T is the formula's coefficient type.

Examples

julia> f = Formula("H2O");

julia> f[:H]
2

julia> f[:C]
0

Base.hash(f::Formula, h::UInt) -> UInt

Hash a Formula using its composition and charge for stable use in collections.

Base.isequal(f1::Formula, f2::Formula) -> Bool

Two formulas are equal if their compositions and formal charges are equal.

Examples

julia> Formula("H2O") == Formula(OrderedDict(:H=>2, :O=>1))
true

Base.length(f::Formula) -> Int

Return the number of distinct element symbols in the formula composition.

Examples

julia> length(Formula("(CaO)1.25(SiO2)1(Al2O3)0.125(Na2O)0.25(H2O)1.375"))
6

Base.show(io::IO, f::Formula)

Concise single-line representation for Formula objects, joining available textual forms.

Base.show(io::IO, ::MIME"text/plain", f::Formula)

Detailed multi-line pretty-printing used by the REPL. Shows type, formula, composition and charge.

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

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⁻¹

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

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)+"))

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"

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_formula(f::Formula, title::String, pad::Int)

Print a titled, padded representation of f using its available textual forms (expr, phreeqc, unicode, colored). This helper is used by pprint and by MIME/plain show helpers to render the "formula" field.

Arguments

• f : Formula to print.
• title : section title (e.g. "formula").
• pad : left-padding width.

print_formula(io::IO, f::Formula, title::String, pad::Int)

Helper to print a titled, padded multi-field representation of a Formula. Used by the MIME text/plain show method.

Arguments

• io: I/O stream.
• f: formula to print.
• title: section title.
• pad: left-padding width.

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

Return the numeric stoichiometric coefficient type T for formula f.

Examples

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

unicode(f::Formula) -> String

Return the Unicode pretty representation of f.

Examples

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