Species

abstract type AbstractSpecies end

Abstract base type for all chemical species representations.

All concrete species types (Species, CemSpecies) inherit from this 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.

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

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

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

Copy constructor for CemSpecies with optional field overrides.

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

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

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

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

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

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

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

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

Construct a CemSpecies with specific coefficient types from another CemSpecies.

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

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

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

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

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

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"

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

Copy constructor for Species with optional field overrides.

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

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

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

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

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

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(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(s::AbstractSpecies, h::UInt) -> UInt

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

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

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

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(::Type{Species}, ::Type{<:AbstractSpecies}) -> Type{Species}

Define promotion rule to convert AbstractSpecies to Species.

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

Set a property value for the species.

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(io::IO, s::CemSpecies)

Compact single-line representation of a CemSpecies.

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

Detailed multi-line REPL display for CemSpecies.

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

Detailed multi-line REPL display for Species.

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

Compact single-line representation of a Species.

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

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.

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

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

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

cemformula(s::CemSpecies) -> Formula

Return the oxide notation formula of the cement species.

charge(s::AbstractSpecies) -> Int8

Return the formal charge of the species.

Examples

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

julia> charge(s1) == 1
true

check_mendeleev(s::AbstractSpecies) -> Bool

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

class(s::AbstractSpecies) -> Class

Return the chemical class of the species.

colored(s::CemSpecies) -> String

Return the colored terminal representation of the cement formula.

colored(s::Species) -> String

Return the colored terminal representation of the species formula.

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

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

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

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

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

expr(s::CemSpecies) -> String

Return the expression string of the cement formula.

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

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

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

mainformula(s::CemSpecies) -> Formula

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

mainformula(s::Species) -> Formula

Return the main formula representation for the species.

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

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

name(s::AbstractSpecies) -> String

Return the name of the species.

Examples

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

julia> s1.name == "H2O"
true

ordered_dict_with_default(gen, key_type, val_type) -> OrderedDict

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

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

Return the oxide composition of the cement species.

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

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

phreeqc(s::CemSpecies) -> String

Return the PHREEQC-compatible representation of the cement formula.

phreeqc(s::Species) -> String

Return the PHREEQC-compatible representation of the species formula.

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

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

Return the properties dictionary of the species.

symbol(s::AbstractSpecies) -> String

Return the symbol of the species.

unicode(s::CemSpecies) -> String

Return the Unicode representation of the cement formula.

unicode(s::Species) -> String

Return the Unicode pretty representation of the species formula.

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