Species

• ChemistryLab.AbstractSpecies
• ChemistryLab.AggregateState
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.CemSpecies
• ChemistryLab.Class
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• ChemistryLab.Species
• Base.getindex
• Base.getproperty
• Base.hash
• Base.haskey
• Base.isequal
• Base.promote_rule
• Base.setindex!
• Base.setproperty!
• Base.show
• Base.show
• Base.show
• Base.show
• ChemistryLab.aggregate_state
• ChemistryLab.apply
• ChemistryLab.atoms
• ChemistryLab.atoms_charge
• ChemistryLab.cemformula
• ChemistryLab.charge
• ChemistryLab.check_mendeleev
• ChemistryLab.class
• ChemistryLab.colored
• ChemistryLab.colored
• ChemistryLab.complete_thermo_functions!
• ChemistryLab.components
• ChemistryLab.components
• ChemistryLab.expr
• ChemistryLab.expr
• ChemistryLab.find_species
• ChemistryLab.formula
• ChemistryLab.mainformula
• ChemistryLab.mainformula
• ChemistryLab.mendeleev_filter
• ChemistryLab.name
• ChemistryLab.ordered_dict_with_default
• ChemistryLab.oxides
• ChemistryLab.oxides_charge
• ChemistryLab.phreeqc
• ChemistryLab.phreeqc
• ChemistryLab.pprint
• ChemistryLab.pprint
• ChemistryLab.properties
• ChemistryLab.symbol
• ChemistryLab.unicode
• ChemistryLab.unicode
• ChemistryLab.with_class
• ChemistryLab.with_symbol

ChemistryLab.AbstractSpecies Type

abstract type AbstractSpecies end

Abstract base type for all chemical species representations.

All concrete species types (Species, CemSpecies) inherit from this type.

ChemistryLab.AggregateState Type

@enum AggregateState

Enumeration for species aggregate states.

Values

• AS_UNDEF: undefined state.

• AS_AQUEOUS: aqueous solution.

• AS_CRYSTAL: crystalline solid.

• AS_GAS: gas phase.

ChemistryLab.CemSpecies Type

struct CemSpecies{T<:Number,S<:Number} <: AbstractSpecies

Cement chemistry species representation using oxide notation.

Fields

• name::String: human-readable name.

• symbol::String: species symbol.

• formula::Formula{T}: atomic composition formula.

• cemformula::Formula{S}: oxide notation formula.

• aggregate_state::AggregateState: physical state.

• class::Class: chemical class.

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

Examples

julia> s = CemSpecies("C3A"; name="Tricalcium aluminate");

julia> oxides(s)
OrderedDict{Symbol, Int64} with 2 entries:
  :C => 3
  :A => 1

ChemistryLab.CemSpecies Method

CemSpecies(f::AbstractString; name, symbol, aggregate_state, class, properties) -> CemSpecies

Construct a CemSpecies from an oxide formula string.

Examples

julia> s = CemSpecies("C3S"; name="Alite");

julia> oxides(s)
OrderedDict{Symbol, Int64} with 2 entries:
  :C => 3
  :S => 1

ChemistryLab.CemSpecies Method

CemSpecies(s::CemSpecies; kwargs...) -> CemSpecies

Copy constructor for CemSpecies with optional field overrides.

ChemistryLab.CemSpecies Method

CemSpecies(cemformula::Formula; name, symbol, aggregate_state, class, properties) -> CemSpecies

Construct a CemSpecies from an oxide formula.

Arguments

• cemformula: Formula object in oxide notation.

• name: species name (default: formula expression).

• symbol: species symbol (default: formula expression).

• aggregate_state: physical state (default: AS_UNDEF).

• class: chemical class (default: SC_UNDEF).

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

ChemistryLab.CemSpecies Method

CemSpecies(s::Species; name, symbol, aggregate_state, class, properties) -> CemSpecies

Convert a Species to CemSpecies by decomposing into oxide notation.

Throws an error if the species cannot be decomposed into cement oxides.

Arguments

• s: source Species.

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

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

• aggregate_state: override state (default: keep original).

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

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

ChemistryLab.CemSpecies Method

CemSpecies(oxides::Pair{Symbol,T}...; name, symbol, aggregate_state, class, properties) where {T} -> CemSpecies

Construct a CemSpecies from oxide => coefficient pairs.

Examples

julia> s = CemSpecies(:C => 3, :S => 2; name="C3S2");

julia> oxides(s)
OrderedDict{Symbol, Int64} with 2 entries:
  :C => 3
  :S => 2

ChemistryLab.CemSpecies Method

CemSpecies(; expr, name, symbol, aggregate_state, class, properties) -> CemSpecies

Construct a CemSpecies from keyword arguments with an oxide formula string.

ChemistryLab.CemSpecies Method

CemSpecies(oxides::AbstractDict{Symbol,T}, charge=0; name, symbol, aggregate_state, class, properties) where {T} -> CemSpecies

Construct a CemSpecies from an oxide composition dictionary.

Arguments

• oxides: dictionary mapping oxide symbols to stoichiometric coefficients.

• charge: formal charge (default 0).

• name: species name (default: computed from formula).

• symbol: species symbol (default: name).

• aggregate_state: physical state (default: AS_UNDEF).

• class: chemical class (default: SC_UNDEF).

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

ChemistryLab.CemSpecies Method

CemSpecies{S}(s::CemSpecies; kwargs...) where {S} -> CemSpecies{S}

Construct a CemSpecies with a specific coefficient type from another CemSpecies.

ChemistryLab.CemSpecies Method

CemSpecies{S,T}(s::CemSpecies; kwargs...) where {S,T} -> CemSpecies{S,T}

Construct a CemSpecies with specific coefficient types from another CemSpecies.

ChemistryLab.Class Type

@enum Class

Enumeration for species chemical classes.

Values

• SC_UNDEF: undefined class.

• SC_AQSOLVENT: aqueous solvent.

• SC_AQSOLUTE: aqueous solute.

• SC_COMPONENT: component.

• SC_GASFLUID: gas or fluid.

• SC_SSENDMEMBER: end-member of a solid solution phase.

ChemistryLab.Species Type

struct Species{T<:Number} <: AbstractSpecies

Standard chemical species representation using atomic composition.

Fields

• name::String: human-readable name.

• symbol::String: species symbol.

• formula::Formula{T}: chemical formula with stoichiometric coefficients.

• aggregate_state::AggregateState: physical state.

• class::Class: chemical class.

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

Examples

julia> s = Species("H2O"; name="Water", aggregate_state=AS_AQUEOUS);

julia> atoms(s)
OrderedDict{Symbol, Int64} with 2 entries:
  :H => 2
  :O => 1

ChemistryLab.Species Method

Species(f::AbstractString; name, symbol, aggregate_state, class, properties) -> Species

Construct a Species from a formula string.

Arguments

• f: formula string to parse.

• name: species name (default: f).

• symbol: species symbol (default: f).

• aggregate_state: physical state (default: AS_UNDEF).

• class: chemical class (default: SC_UNDEF).

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

Examples

julia> s = Species("Ca+2"; aggregate_state=AS_AQUEOUS);

julia> charge(s)
2

ChemistryLab.Species Method

Species(s::CemSpecies; name, symbol, aggregate_state, class, properties) -> Species

Convert a CemSpecies to Species using atomic composition.

Arguments

• s: source CemSpecies.

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

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

• aggregate_state: override state (default: keep original).

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

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

ChemistryLab.Species Method

Species(formula::Formula; name, symbol, aggregate_state, class, properties) -> Species

Construct a Species from a Formula object.

Arguments

• formula: Formula object with atomic composition.

• name: species name (default: formula expression).

• symbol: species symbol (default: formula expression).

• aggregate_state: physical state (default: AS_UNDEF).

• class: chemical class (default: SC_UNDEF).

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

Examples

julia> f = Formula("NaCl");

julia> s = Species(f; name="Sodium chloride", aggregate_state=AS_CRYSTAL);

julia> name(s)
"Sodium chloride"

ChemistryLab.Species Method

Species(s::Species; kwargs...) -> Species

Copy constructor for Species with optional field overrides.

ChemistryLab.Species Method

Species(atoms::Pair{Symbol,T}...; name, symbol, aggregate_state, class, properties) where {T} -> Species

Construct a Species from element => coefficient pairs.

Examples

julia> s = Species(:H => 2, :O => 1; name="Water");

julia> atoms(s)
OrderedDict{Symbol, Int64} with 2 entries:
  :H => 2
  :O => 1

ChemistryLab.Species Method

Species(; expr, name, symbol, aggregate_state, class, properties) -> Species

Construct a Species from keyword arguments.

Arguments

• expr: formula string to parse (default: "").

• name: species name (default: expr).

• symbol: species symbol (default: expr).

• aggregate_state: physical state (default: AS_UNDEF).

• class: chemical class (default: SC_UNDEF).

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

ChemistryLab.Species Method

Species(atoms::AbstractDict{Symbol,T}, charge=0; name, symbol, aggregate_state, class, properties) where {T} -> Species

Construct a Species from an atomic composition dictionary.

Arguments

• atoms: dictionary mapping element symbols to stoichiometric coefficients.

• charge: formal charge (default 0).

• name: species name (default: computed from formula).

• symbol: species symbol (default: name).

• aggregate_state: physical state (default: AS_UNDEF).

• class: chemical class (default: SC_UNDEF).

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

ChemistryLab.Species Method

Species{T}(s::Species; kwargs...) where {T} -> Species{T}

Construct a Species with a specific coefficient type from another Species.

Base.getindex Method

Base.getindex(s::AbstractSpecies, i::Symbol) -> Any

Access species components, atoms, or properties by symbol key.

Returns 0 if the key is not found.

Examples

julia> s = Species("H2O");

julia> s[:H]
2

julia> s[:N]
0

Base.getproperty Method

Base.getproperty(s::AbstractSpecies, sym::Symbol) -> Any

Access species fields or registered properties.

Throws an error if the symbol is neither a field nor a property.

Base.hash Method

Base.hash(s::AbstractSpecies, h::UInt) -> UInt

Compute hash for a species based on symbol, formula, aggregate state, and class.

Base.haskey Method

Base.haskey(s::AbstractSpecies, sym::Symbol) -> Bool

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

Base.isequal Method

Base.isequal(s1::AbstractSpecies, s2::AbstractSpecies) -> Bool

Compare two species for equality based on formula, aggregate state, and class.

Examples

julia> s1 = Species("H2O"; aggregate_state=AS_AQUEOUS);

julia> s2 = Species("H₂O"; aggregate_state=AS_AQUEOUS);

julia> s1 == s2
true

Base.promote_rule Method

Base.promote_rule(::Type{Species}, ::Type{<:AbstractSpecies}) -> Type{Species}

Define promotion rule to convert AbstractSpecies to Species.

Base.setindex! Method

Base.setindex!(s::AbstractSpecies, value, i::Symbol)

Set a property value for the species.

Base.setproperty! Method

Base.setproperty!(s::AbstractSpecies, sym::Symbol, value)

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

Throws an error if attempting to modify a structural field directly.

Base.show Method

Base.show(io::IO, s::CemSpecies)

Compact single-line representation of a CemSpecies.

Base.show Method

Base.show(io::IO, ::MIME"text/plain", s::CemSpecies)

Detailed multi-line REPL display for CemSpecies.

Base.show Method

Base.show(io::IO, ::MIME"text/plain", s::Species)

Detailed multi-line REPL display for Species.

Base.show Method

Base.show(io::IO, s::Species)

Compact single-line representation of a Species.

ChemistryLab.aggregate_state Method

aggregate_state(s::AbstractSpecies) -> AggregateState

Return the aggregate state of the species.

Examples

julia> s1 = Species("H2O"; aggregate_state=AS_AQUEOUS);

julia> aggregate_state(s1) == AS_AQUEOUS
true

ChemistryLab.apply Method

apply(func::Function, s::S, args...; kwargs...) where {S<:AbstractSpecies} -> S

Apply a function element-wise to all numeric components and properties of a species.

Arguments

• func: function to apply.

• s: source species.

• args...: additional arguments for func.

• kwargs...: keyword arguments (including potential overrides for name, symbol, etc.).

Returns

• New species with transformed values.

Handles Quantity types, attempting to preserve dimensions when possible.

ChemistryLab.atoms Method

atoms(s::AbstractSpecies) -> OrderedDict{Symbol,Number}

Return the atomic composition (element => coefficient) of the species.

ChemistryLab.atoms_charge Method

atoms_charge(s::AbstractSpecies) -> OrderedDict{Symbol,Number}

Return atomic composition including the charge as a :Zz key if non-zero.

Examples

julia> s = Species("Ca+2");

julia> atoms_charge(s)
OrderedDict{Symbol, Int64} with 2 entries:
  :Ca => 1
  :Zz => 2

ChemistryLab.cemformula Method

cemformula(s::CemSpecies) -> Formula

Return the oxide notation formula of the cement species.

ChemistryLab.charge Method

charge(s::AbstractSpecies) -> Int8

Return the formal charge of the species.

Examples

julia> s1 = Species("Ca(HSiO3)+");

julia> charge(s1) == 1
true

ChemistryLab.check_mendeleev Method

check_mendeleev(s::AbstractSpecies) -> Bool

Validate that all element symbols in the species exist in the periodic table.

ChemistryLab.class Method

class(s::AbstractSpecies) -> Class

Return the chemical class of the species.

ChemistryLab.colored Method

colored(s::CemSpecies) -> String

Return the colored terminal representation of the cement formula.

ChemistryLab.colored Method

colored(s::Species) -> String

Return the colored terminal representation of the species formula.

ChemistryLab.complete_thermo_functions! Method

complete_thermo_functions!(s::AbstractSpecies)

Populate thermodynamic properties (Cp⁰, ΔₐH⁰, S⁰, ΔₐG⁰, V⁰) from parameters in s.properties.

If thermo_params dictionary is present in properties, it initializes thermodynamic functions using :thermo_method (e.g., "cp_ft_equation", "solute_hkf88_reaktoro") or scalar defaults. New thermodynamic models are registered by dispatching build_thermo_functions(Val(:model_name), params).

ChemistryLab.components Method

components(s::CemSpecies) -> OrderedDict{Symbol,Number}

Return the components of a CemSpecies (oxide composition with charge).

ChemistryLab.components Method

components(s::Species) -> OrderedDict{Symbol,Number}

Return the components of a Species (atomic composition with charge).

ChemistryLab.expr Method

expr(s::CemSpecies) -> String

Return the expression string of the cement formula.

ChemistryLab.expr Method

expr(s::Species) -> String

Return the original expression string of the species formula.

Examples

julia> expr(Species("H2O"; name="Water", aggregate_state=AS_AQUEOUS))
"H2O"

julia> expr(Species("H2O"; name="Water", aggregate_state=AS_AQUEOUS)) == expr(Formula("H2O"))
true

ChemistryLab.find_species Function

find_species(s::AbstractString, species_list=nothing, S::Type{<:AbstractSpecies}=Species; aggregate_state=AS_UNDEF, class=SC_UNDEF) -> AbstractSpecies

Find or construct a species from a string identifier.

Arguments

• s: species identifier string (formula, symbol, or name).

• species_list: optional list of species to search (default: nothing constructs new species).

• S: species type to construct if not found (default: Species).

• aggregate_state: filter by aggregate state (default: AS_UNDEF, no filter).

• class: filter by chemical class (default: SC_UNDEF, no filter).

Returns

• Matching species from list, or newly constructed species if not found.

The function searches by symbol, PHREEQC format, Unicode format, formula expression, and name. If multiple matches are found, a warning is displayed and the first match is returned.

Examples

julia> species_list = [
           Species("H2O"; aggregate_state=AS_AQUEOUS), Species("H2O"; aggregate_state=AS_GAS)
       ];

julia> s = find_species("H2O", species_list; aggregate_state=AS_AQUEOUS);

julia> aggregate_state(s)
AS_AQUEOUS::AggregateState = 1

ChemistryLab.formula Method

formula(s::AbstractSpecies) -> Formula

Return the Formula object associated with the species.

Examples

julia> s1 = Species("H2O"; aggregate_state=AS_AQUEOUS);

julia> formula(s1) == Formula("H2O")
true

ChemistryLab.mainformula Method

mainformula(s::CemSpecies) -> Formula

Return the main formula representation (oxide notation) for the cement species.

ChemistryLab.mainformula Method

mainformula(s::Species) -> Formula

Return the main formula representation for the species.

ChemistryLab.mendeleev_filter Method

mendeleev_filter(s::AbstractSpecies) -> Union{AbstractSpecies,Nothing}

Return the species if valid according to Mendeleev check, otherwise nothing.

ChemistryLab.name Method

name(s::AbstractSpecies) -> String

Return the name of the species.

Examples

julia> s1 = Species("H2O"; aggregate_state=AS_AQUEOUS);

julia> s1.name == "H2O"
true

ChemistryLab.ordered_dict_with_default Method

ordered_dict_with_default(gen, key_type, val_type) -> OrderedDict

Create an OrderedDict from a generator, ensuring proper typing even when empty.

ChemistryLab.oxides Method

oxides(s::CemSpecies) -> OrderedDict{Symbol,Number}

Return the oxide composition of the cement species.

ChemistryLab.oxides_charge Method

oxides_charge(s::CemSpecies) -> OrderedDict{Symbol,Number}

Return oxide composition including the charge as a :Zz key if non-zero.

ChemistryLab.phreeqc Method

phreeqc(s::CemSpecies) -> String

Return the PHREEQC-compatible representation of the cement formula.

ChemistryLab.phreeqc Method

phreeqc(s::Species) -> String

Return the PHREEQC-compatible representation of the species formula.

ChemistryLab.pprint Method

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

ChemistryLab.pprint Method

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

ChemistryLab.properties Method

properties(s::AbstractSpecies) -> OrderedDict{Symbol,PropertyType}

Return the properties dictionary of the species.

ChemistryLab.symbol Method

symbol(s::AbstractSpecies) -> String

Return the symbol of the species.

ChemistryLab.unicode Method

unicode(s::CemSpecies) -> String

Return the Unicode representation of the cement formula.

ChemistryLab.unicode Method

unicode(s::Species) -> String

Return the Unicode pretty representation of the species formula.

ChemistryLab.with_class Method

with_class(s::Species, c::Class) -> Species

Return a copy of s with its class set to c. All other fields (name, symbol, formula, aggregate state, properties) are preserved unchanged.

Useful to requalify database species as SC_SSENDMEMBER before grouping them into a SolidSolutionPhase, since Species is immutable.

Examples

julia> s = Species("CaCO3"; aggregate_state=AS_CRYSTAL, class=SC_COMPONENT);

julia> class(s)
SC_COMPONENT::Class = 3

julia> s2 = with_class(s, SC_SSENDMEMBER);

julia> class(s2)
SC_SSENDMEMBER::Class = 5

ChemistryLab.with_symbol Method

with_symbol(s::Species, sym::AbstractString) -> Species

The same species under a different symbol, everything else shared.

Exists for one purpose: a miscibility gap needs the same substance present twice, as two coexisting compositions, and a formulation carrying one amount per species can only express that if the species appears twice. ChemicalSystem uses this to build the extra copies a SolidSolutionPhase declared with instances > 1 asks for — see SolidSolutionPhase.

The copy shares the formula and the whole property dictionary, so the two carry byte-identical thermodynamic data: they are one substance under two labels, not two substances. Only the label distinguishes them, and it is what keeps the solid-solution groups disjoint.

Examples

julia> s = Species("CaCO3"; aggregate_state=AS_CRYSTAL, class=SC_COMPONENT);

julia> s2 = with_symbol(s, "CaCO3#2");

julia> symbol(s2), atoms(s2) == atoms(s)
("CaCO3#2", true)