Formulas

• ChemistryLab.AtomGroup
• ChemistryLab.AtomGroup
• ChemistryLab.Formula
• ChemistryLab.Formula
• ChemistryLab.Formula
• ChemistryLab.Formula
• Base.:*
• Base.:+
• Base.:+
• Base.:+
• Base.:/
• Base.://
• Base.convert
• Base.convert
• Base.getindex
• Base.hash
• Base.isequal
• Base.length
• Base.show
• Base.show
• ChemistryLab.apply
• ChemistryLab.calculate_molar_mass
• ChemistryLab.charge
• ChemistryLab.check_mendeleev
• ChemistryLab.colored
• ChemistryLab.composition
• ChemistryLab.expr
• ChemistryLab.phreeqc
• ChemistryLab.pprint
• ChemistryLab.pprint_formula
• ChemistryLab.print_formula
• ChemistryLab.stoichtype
• ChemistryLab.unicode

ChemistryLab.AtomGroup Type

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)

ChemistryLab.AtomGroup Method

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)

ChemistryLab.Formula Type

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

ChemistryLab.Formula Type

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

ChemistryLab.Formula Method

Formula(f::Formula) -> Formula

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

ChemistryLab.Formula Method

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"

Base.:* Method

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

Multiply all stoichiometric coefficients of f by scalar x.

Base.:+ Method

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

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

Base.:+ Method

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

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

Base.:+ Method

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

Base.:/ Method

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

Divide all stoichiometric coefficients of f by scalar x.

Base.:// Method

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

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

Base.convert Method

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

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

Base.convert Method

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 Method

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 Method

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

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

Base.isequal Method

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 Method

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 Method

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

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

Base.show Method

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

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

ChemistryLab.apply Method

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

ChemistryLab.calculate_molar_mass Method

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

ChemistryLab.charge Method

charge(f::Formula) -> Int8

Return the formal integer charge of the formula.

Examples

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

ChemistryLab.check_mendeleev Method

check_mendeleev(f::Formula) -> Bool

Whether every symbol in f is one this package can weigh.

Three kinds pass: a real element of the elements registry, the charge placeholder :Zz, and a surface site symbol (SITE_SYMBOLS). Anything else — a typo, most often — makes this false, and a species built from such a formula is then left without a molar mass rather than given a wrong one.

It returns false; it does not throw. The docstring claimed otherwise until 0.20, and the difference matters: callers branch on it.

What a site symbol weighs

Nothing, by declaration. calculate_molar_mass sums over the symbols it recognizes, so XsOH weighs an O and an H — the adsorbed part alone. The mass of the support is carried once, by the host mineral species, and counting it again on every occupied site would be double counting.

Examples

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

julia> check_mendeleev(Formula("XsOH"))      # a surface site is weighable
true

julia> check_mendeleev(Formula("QqOH"))      # a symbol that is neither is not
false

ChemistryLab.colored Method

colored(f::Formula) -> String

Return the colored terminal representation of f.

Examples

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

ChemistryLab.composition Method

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

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

Examples

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

ChemistryLab.expr Method

expr(f::Formula) -> String

Return the original expression string stored in f.

Examples

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

ChemistryLab.phreeqc Method

phreeqc(f::Formula) -> String

Return the PHREEQC-compatible representation of f.

Examples

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

ChemistryLab.pprint Method

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.

ChemistryLab.pprint_formula Method

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.

ChemistryLab.print_formula Method

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.

ChemistryLab.stoichtype Method

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

Return the numeric stoichiometric coefficient type T for formula f.

Examples

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

ChemistryLab.unicode Method

unicode(f::Formula) -> String

Return the Unicode pretty representation of f.

Examples

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