GitHub

Stoichiometric Matrix

ChemistryLab.union_atoms — Function
union_atoms(atom_dicts::AbstractVector{<:AbstractDict}, order_vec=ATOMIC_ORDER) -> Vector{Symbol}

Compute the union of all keys from dictionaries, sorted by a given order.

Arguments

  • atom_dicts: vector of dictionaries (e.g., atomic compositions).
  • order_vec: ordering vector for sorting keys (default: ATOMIC_ORDER).

Returns

  • Sorted vector of unique symbols appearing in any dictionary.

Examples

julia> d1 = OrderedDict(:H => 2, :O => 1);

julia> d2 = OrderedDict(:C => 1, :O => 2);

julia> union_atoms([d1, d2], ATOMIC_ORDER)
3-element Vector{Symbol}:
 :C
 :H
 :O
source
ChemistryLab.speciation — Function
speciation(species_list, atoms_list::AbstractVector{Symbol}; kwargs...) -> SubArray
speciation(species_list, short_species_list::AbstractVector{<:AbstractSpecies}; kwargs...) -> SubArray
speciation(species_list, short_species_list_symbols::AbstractVector{<:AbstractString}; kwargs...) -> SubArray

Filter a list of species to those whose atomic composition is a subset of the given atoms (or of the atoms found in short_species_list).

Arguments

  • species_list: full list of species to filter.
  • atoms_list: vector of atom symbols that define the chemical space.
  • short_species_list: seed species whose union of atoms defines the chemical space.
  • short_species_list_symbols: string symbols of seed species.

Keyword arguments

  • aggregate_state: filter by aggregate state (default: all states).
  • class: filter by species class (default: all classes).
  • exclude_species: species (or symbols) to always exclude.
  • include_species: species (or symbols) to always include regardless of composition.

Returns

  • A view (SubArray) of species_list containing the matching species.

Examples

julia> all_species = [Species("H2O"), Species("OH-"), Species("H+"), Species("Ca+2"), Species("CaCO3")];

julia> speciation(all_species, [:H, :O])
3-element view(::Vector{Species{Int64}}, [1, 2, 3]) with eltype Species{Int64}:
 H₂O {H₂O} [H₂O ◆ H2O]
 OH⁻ {OH⁻} [OH⁻ ◆ OH-]
 H⁺ {H⁺} [H⁺ ◆ H+]
source
ChemistryLab.pprint — Method
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.

source
ChemistryLab.CanonicalStoichMatrix — Function
    CanonicalStoichMatrix(species)

Construct a StoichMatrix from a list of species i.e. the matrix giving the stoichiometric coefficients of the species in columns with respect to the atoms in rows.

Arguments

  • species: list of species.

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> CSM = CanonicalStoichMatrix([H₂O, H⁺, OH⁻, CO₂, HCO₃⁻, CO₃²⁻])
┌────┬─────┬────┬─────┬─────┬───────┬───────┐
│    │ H₂O │ H⁺ │ OH⁻ │ CO₂ │ HCO₃⁻ │ CO₃²⁻ │
├────┼─────┼────┼─────┼─────┼───────┼───────┤
│  C │     │    │     │   1 │     1 │     1 │
│  H │   2 │  1 │   1 │     │     1 │       │
│  O │   1 │    │   1 │   2 │     3 │     3 │
│ Zz │     │  1 │  -1 │     │    -1 │    -2 │
└────┴─────┴────┴─────┴─────┴───────┴───────┘
source
ChemistryLab.StoichMatrix — Type
    StoichMatrix{T,P}

Container holding a stoichiometric matrix A together with the primaries (independent components) and the full species vector.

Fields

- `A`: matrix (components × species) of stoichiometric coefficients.
- `primaries`: vector of independent components (Symbols or `Species`).
- `species`: vector of `Species` corresponding to the columns of `A`.
- `N`: nullspace matrix (if possibly, built by the inner constructor): columns are vectors of the kernel of `A`.

Examples

julia> species = [Species("H₂O"), Species("OH⁻"), Species("H⁺")]
3-element Vector{Species{Int64}}:
 H₂O {H₂O} [H₂O ◆ H2O]
 OH⁻ {OH⁻} [OH⁻ ◆ OH-]
 H⁺ {H⁺} [H⁺ ◆ H+]

julia> SM = StoichMatrix(species)
┌─────┬─────┬─────┬────┐
│     │ H₂O │ OH⁻ │ H⁺ │
├─────┼─────┼─────┼────┤
│ H₂O │   1 │     │  1 │
│ OH⁻ │     │   1 │ -1 │
└─────┴─────┴─────┴────┘
source
ChemistryLab.pull_primaries — Function
    pull_primaries(SM::StoichMatrix)

Construct a StoichMatrix by reordering the species such that the primaries appear first (works only if primaries are contained within species).

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> pull_primaries(SM)
┌─────┬─────┬────┬─────┬─────┬───────┬───────┐
│     │ H₂O │ H⁺ │ CO₂ │ OH⁻ │ HCO₃⁻ │ CO₃²⁻ │
├─────┼─────┼────┼─────┼─────┼───────┼───────┤
│ H₂O │   1 │    │     │   1 │     1 │     1 │
│  H⁺ │     │  1 │     │  -1 │    -1 │    -2 │
│ CO₂ │     │    │   1 │     │     1 │     1 │
└─────┴─────┴────┴─────┴─────┴───────┴───────┘

julia> pull_primaries(SM).N
6×3 Matrix{Int64}:
 -1  -1  -1
  1   1   2
  0  -1  -1
  1   0   0
  0   1   0
  0   0   1
source
ChemistryLab.push_primaries — Function
    push_primaries(SM::StoichMatrix)

Construct a StoichMatrix by reordering the species such that the primaries appear at the end (works only if primaries are contained within species).

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> push_primaries(SM)
┌─────┬─────┬───────┬───────┬─────┬────┬─────┐
│     │ OH⁻ │ HCO₃⁻ │ CO₃²⁻ │ H₂O │ H⁺ │ CO₂ │
├─────┼─────┼───────┼───────┼─────┼────┼─────┤
│ H₂O │   1 │     1 │     1 │   1 │    │     │
│  H⁺ │  -1 │    -1 │    -2 │     │  1 │     │
│ CO₂ │     │     1 │     1 │     │    │   1 │
└─────┴─────┴───────┴───────┴─────┴────┴─────┘

julia> push_primaries(SM).N
6×3 Matrix{Int64}:
  1   0   0
  0   1   0
  0   0   1
 -1  -1  -1
  1   1   2
  0  -1  -1
source
ChemistryLab.mass_matrix — Function
    mass_matrix(SM::StoichMatrix)

Construct a StoichMatrix with mass correspondence instead of molar stoichiometry.

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> mass_matrix(SM)
┌─────┬─────┬─────┬────────────┬─────┬────────────┬────────────┐
│     │ H₂O │  H⁺ │        OH⁻ │ CO₂ │      HCO₃⁻ │      CO₃²⁻ │
├─────┼─────┼─────┼────────────┼─────┼────────────┼────────────┤
│ H₂O │ 1.0 │     │    1.05927 │     │    0.29525 │    0.30021 │
│  H⁺ │     │ 1.0 │ -0.0592697 │     │ -0.0165203 │ -0.0335955 │
│ CO₂ │     │     │            │ 1.0 │    0.72127 │   0.733386 │
└─────┴─────┴─────┴────────────┴─────┴────────────┴────────────┘

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

julia> mass_matrix(CSM)
┌────┬──────────┬─────┬───────────┬──────────┬───────────┬──────────┐
│    │      H₂O │  H⁺ │       OH⁻ │      CO₂ │     HCO₃⁻ │    CO₃²⁻ │
├────┼──────────┼─────┼───────────┼──────────┼───────────┼──────────┤
│  C │          │     │           │ 0.272921 │   0.19685 │ 0.200157 │
│  H │ 0.111907 │ 1.0 │ 0.0592697 │          │ 0.0165203 │          │
│  O │ 0.888093 │     │   0.94073 │ 0.727079 │   0.78663 │ 0.799843 │
│ Zz │          │     │           │          │           │          │
└────┴──────────┴─────┴───────────┴──────────┴───────────┴──────────┘
source
ChemistryLab.reactions — Function
    reactions(SM::StoichMatrix)

Construct the list of non trivial reactions from a StoichMatrix.

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> reactions(SM)
3-element Vector{Reaction{Species{Int64}, Int64, Species{Int64}, Int64, Int64}}:
 H₂O = OH⁻ + H⁺
 H₂O + CO₂ = HCO₃⁻ + H⁺
 H₂O + CO₂ = CO₃²⁻ + 2H⁺
source