GeochemicalModelDefinition

Defines the geochemical system. This extracts information from the geochemistry database and stores information pertinent to the model in computationally-efficient data structures, eliminating all extraneous information.

commentnote

All geochemistry models must contain a GeochemicalModelDefinition userobject

This userobject extensively uses utils/PertinentGeochemicalSystem, and it is useful to fully discuss the input parameters of this class.

basis_species

This is a list of basis components relevant to the aqueous equilibrium problem. The following requirements must be satisfied (otherwise a mooseError is produced and the simulation stops):

  • "H2O" must appear first in this list;

  • No member must appear more than once in this list;

  • These components must be chosen from the "basis species" in the database, the sorbing sites (if any) and the decoupled redox states that are in disequilibrium (if any).

Any redox pair that is not in this list or the kinetic_redox list, will be assumed to be at equilibrium with the aqueous solution and will be considered a secondary species.

All these species, except H2O, may be later swapped out of this list, either by a manual user-prescribed swap (and replaced by a mineral or a gas of fixed fugacity, for instance), or during the numerical solve. For simple examples of this swap, see GeochemicalModelInterrogator

minerals

This list contains the minerals that are in equilibrium with the aqueous solution. Conditions on the members of this list are:

  • They must be "minerals" in the database;

  • No member can appear more than once in this list;

  • Their equilibrium reaction must consist of only the basis_species, and secondary species and non-kinetically-controlled redox couples that can be expressed in terms of the basis_species;

  • If they are also "sorbing minerals" in the database then their sorption sites must consist of the basis_species only.

During simulation, the user can compute the saturation index of these minerals.

These minerals can be swapped into the basis if desired (or required during the numerical solve). For simple examples of this swap, see GeochemicalModelInterrogator. If the user performs a manual "swap" then an initial condition must be provided for the mineral.

The user chooses whether these minerals are allowed to precipitate or not — that is, they can be "suppressed".

This list, along with the kinetic_minerals list, comprises the entire list of minerals in the problem: all others are eliminated from consideration.

gases

This is a list of gases that are in equilibrium with the aqueous solution and can have their fugacities fixed, at least at some time and spatial location.

  • All members of this list must be a "gas" in the database file.

  • No gas must appear more than once in this list.

  • The equilibrium reaction of each gas must involve only the basis_species, or secondary species or non-kinetically-controlled redox couples that can be expressed in terms of the basis_species.

This list comprises all the gases that are in the simulation: all others are eliminated.

kinetic_minerals

This is a list of minerals that whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution.

  • The list can only include the "minerals" in the database file.

  • No member can appear more than once in this list.

  • The equilibrium reaction of each mineral must involve only the basis_species, or secondary species or non-kinetically-controlled redox couples that can be expressed in terms of the basis_species.

  • If a mineral is also a "sorbing mineral" in the database then their sorption sites must consist of the basis_speices only.

  • No members of this list must be in the minerals list.

These minerals can never be swapped into the basis, nor can they be "suppressed".

kinetic_redox

This is a list of redox pairs that whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution.

  • The list can only include the "redox couples" in the database file.

  • No member can appear more than once in this list.

  • The equilibrium reaction of each member must involve only the basis_species, or secondary species or non-kinetically-controlled redox couples that can be expressed in terms of the basis_species.

  • No members of this list must be in the basis_species list.

These species can never be swapped into the basis.

kinetic_surface_species

This is a list of surface sorbing species that whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution.

  • The list can only include the "surface species" in the database file.

  • No member can appear more than once in this list.

  • The equilibrium reaction of each member must involve only the basis_species, or secondary species or non-kinetically-controlled redox couples that can be expressed in terms of the basis_species.

These species can never be swapped into the basis.

kinetic_rate_descriptions

A list of GeochemistryKineticRate user objects that define the kinetic rates for the kinetic species should be supplied. If a kinetic species has no rate prescribed then its reaction rate will be zero. Multiple GeochemistryKineticRate user objects can apply to a single kinetic species: in this case the sum of all the rates defines the overall reaction rate for the kinetic species.

Secondary species

The complete list of secondary species is automatically computed based on the above information using the following algorithm:

  1. All "redox couples" in the database are queried one-by-one, and included if:

  • they are not part of the kinetic_redox list; and

  • they are not part of the basis_species list; and

  • their reaction involves only basis_species or secondary species already encountered. This means redox couples whose reactions involve already-encountered redox couples can be included in the secondary species' list.

  1. All secondary species in the database are queried one-by-one, and included if:

  • their reaction involves basis_species, or secondary species already encountered.

  1. All surface species in the database are queried one-by-one, and included if:

  • they are not in the kinetic_surface_species list; and

  • their reaction involves only basis_species or secondary species encountered so far

The resulting list contains only species whose equilibrium reactions can ultimately be expressed in terms of basis species. Once this list is created, the equilibrium reactions for the minerals, gases, kinetic_redox and kinetic_surface_species can also be checked that they can be ultimately expressed in terms of basis species as specified above in the conditions "the equilibrium reaction of each member must involve only the basis_species, or secondary species or non-kinetically-controlled redox couples that can be expressed in terms of the basis_species."

Creating the pertinent model

All the aforementioned species are included in the "pertinent model" created by this class, including their names, charges, molecular weights, ionic radii, molecular volumes, stoichiometric coefficients and equilibrium constants.

Executing

All computations in this Userobject are performed in its constructor during initial setup. During simulation, this Userobject does nothing.

Example

An example that simply outputs equilibrium reactions involving the clinoptilolite mineral is:

# Outputs equilibrium reactions fo Clinoptil-Ca for various different basis species, along with log10(K)
[GeochemicalModelInterrogator]
  model_definition = definition
  swap_out_of_basis = "Al+++     SiO2(aq) H+"
  swap_into_basis = "  Muscovite Quartz   OH-"
  equilibrium_species = "Clinoptil-Ca"
[]

[UserObjects]
  [definition]
    type = GeochemicalModelDefinition
    database_file = "../../../database/moose_geochemdb.json"
    basis_species = "H2O Ca++ Al+++ SiO2(aq) H+ K+"
    equilibrium_minerals = "Clinoptil-Ca Muscovite Quartz"
    piecewise_linear_interpolation = true # to get exact logK at 25degC with no best-fit interpolation
  []
[]
(modules/geochemistry/test/tests/interrogate_reactions/clinoptilolite.i)

Input Parameters

  • basis_speciesA list of basis components relevant to the aqueous-equilibrium problem. H2O must appear first in this list. These components must be chosen from the 'basis species' in the database, the sorbing sites (if any) and the decoupled redox states that are in disequilibrium (if any).

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:A list of basis components relevant to the aqueous-equilibrium problem. H2O must appear first in this list. These components must be chosen from the 'basis species' in the database, the sorbing sites (if any) and the decoupled redox states that are in disequilibrium (if any).

  • database_fileThe name of the geochemical database file

    C++ Type:FileName

    Controllable:No

    Description:The name of the geochemical database file

Required Parameters

  • equilibrium_gasesA list of gases that are in equilibrium with the aqueous solution and can have their fugacities fixed, at least for some time and spatial location. All members of this list must be in the 'gas' section of the database file

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:A list of gases that are in equilibrium with the aqueous solution and can have their fugacities fixed, at least for some time and spatial location. All members of this list must be in the 'gas' section of the database file

  • equilibrium_mineralsA list of minerals that are in equilibrium with the aqueous solution. All members of this list must be in the 'minerals' section of the database file

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:A list of minerals that are in equilibrium with the aqueous solution. All members of this list must be in the 'minerals' section of the database file

  • execute_onTIMESTEP_ENDThe list of flag(s) indicating when this object should be executed, the available options include FORWARD, ADJOINT, HOMOGENEOUS_FORWARD, ADJOINT_TIMESTEP_BEGIN, ADJOINT_TIMESTEP_END, NONE, INITIAL, LINEAR, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, CUSTOM.

    Default:TIMESTEP_END

    C++ Type:ExecFlagEnum

    Options:FORWARD, ADJOINT, HOMOGENEOUS_FORWARD, ADJOINT_TIMESTEP_BEGIN, ADJOINT_TIMESTEP_END, NONE, INITIAL, LINEAR, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, CUSTOM

    Controllable:No

    Description:The list of flag(s) indicating when this object should be executed, the available options include FORWARD, ADJOINT, HOMOGENEOUS_FORWARD, ADJOINT_TIMESTEP_BEGIN, ADJOINT_TIMESTEP_END, NONE, INITIAL, LINEAR, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, CUSTOM.

  • kinetic_mineralsA list of minerals whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution. All members of this list must be in the 'minerals' section of the database file.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:A list of minerals whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution. All members of this list must be in the 'minerals' section of the database file.

  • kinetic_rate_descriptionsA list of GeochemistryKineticRate UserObject names that define the kinetic rates. If a kinetic species has no rate prescribed to it, its reaction rate will be zero

    C++ Type:std::vector<UserObjectName>

    Controllable:No

    Description:A list of GeochemistryKineticRate UserObject names that define the kinetic rates. If a kinetic species has no rate prescribed to it, its reaction rate will be zero

  • kinetic_redoxA list alternative oxidation states (eg Fe+++) whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution. All members of this list must be in the 'redox couples' section of the database file.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:A list alternative oxidation states (eg Fe+++) whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution. All members of this list must be in the 'redox couples' section of the database file.

  • kinetic_surface_speciesA list surface sorbing species whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution. All members of this list must be in the 'surface species' section of the database file.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:A list surface sorbing species whose dynamics are governed by a rate law. These are not in equilibrium with the aqueous solution. All members of this list must be in the 'surface species' section of the database file.

  • piecewise_linear_interpolationFalseIf true then use a piecewise-linear interpolation of logK and Debye-Huckel parameters, regardless of the interpolation type specified in the database file. This can be useful for comparing with results using other geochemistry software

    Default:False

    C++ Type:bool

    Controllable:No

    Description:If true then use a piecewise-linear interpolation of logK and Debye-Huckel parameters, regardless of the interpolation type specified in the database file. This can be useful for comparing with results using other geochemistry software

  • prop_getter_suffixAn optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.

    C++ Type:MaterialPropertyName

    Controllable:No

    Description:An optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.

  • redox_electrone-The name of the free electron. For redox pairs that are in disequilibrium to be correctly recorded, and hence their Nernst potentials to be computed eqsily, the equilibrium reaction for redox_electron must involve redox_oxygen, and the basis species must be chosen to that redox_electron is an equilibrium species

    Default:e-

    C++ Type:std::string

    Controllable:No

    Description:The name of the free electron. For redox pairs that are in disequilibrium to be correctly recorded, and hence their Nernst potentials to be computed eqsily, the equilibrium reaction for redox_electron must involve redox_oxygen, and the basis species must be chosen to that redox_electron is an equilibrium species

  • redox_oxygenO2(aq)The name of the oxygen species that appears in redox reactions. For redox pairs that are in disequilibrium to be correctly recorded, and hence their Nernst potentials to be computed easily, redox_oxygen must be a basis species and it must appear in the reaction for each redox pair

    Default:O2(aq)

    C++ Type:std::string

    Controllable:No

    Description:The name of the oxygen species that appears in redox reactions. For redox pairs that are in disequilibrium to be correctly recorded, and hence their Nernst potentials to be computed easily, redox_oxygen must be a basis species and it must appear in the reaction for each redox pair

  • reexpress_free_electronTrueIf true then if: (1) the 'free electron' appears in the database file; and (2) its equilibrium reaction includes O2(g); and (3) O2(g) is a gas; and (4) O2(g)'s equilibrium reaction is O2(g)=O2(eq); and (5) O2(aq) exists as a basis species in the database file; then reexpress the free electron's equilibrium reaction in terms of O2(aq). Note that if you choose 'reexpress_free_electron=false' and these other 5 conditions are true, then the 'free electron' will not be available as a secondary species

    Default:True

    C++ Type:bool

    Controllable:No

    Description:If true then if: (1) the 'free electron' appears in the database file; and (2) its equilibrium reaction includes O2(g); and (3) O2(g) is a gas; and (4) O2(g)'s equilibrium reaction is O2(g)=O2(eq); and (5) O2(aq) exists as a basis species in the database file; then reexpress the free electron's equilibrium reaction in terms of O2(aq). Note that if you choose 'reexpress_free_electron=false' and these other 5 conditions are true, then the 'free electron' will not be available as a secondary species

  • remove_all_extrapolated_secondary_speciesFalseAfter reading the database file, immediately remove all secondary species that have extrapolated equilibrium constants. Sometimes these extrapolations are completely crazy and those secondary species greatly impact the results

    Default:False

    C++ Type:bool

    Controllable:No

    Description:After reading the database file, immediately remove all secondary species that have extrapolated equilibrium constants. Sometimes these extrapolations are completely crazy and those secondary species greatly impact the results

  • use_interpolated_stateFalseFor the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:For the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.

Optional Parameters

  • allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).

    Default:False

    C++ Type:bool

    Controllable:No

    Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).

  • control_tagsAdds user-defined labels for accessing object parameters via control logic.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:Adds user-defined labels for accessing object parameters via control logic.

  • enableTrueSet the enabled status of the MooseObject.

    Default:True

    C++ Type:bool

    Controllable:Yes

    Description:Set the enabled status of the MooseObject.

  • execution_order_group0Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.

    Default:0

    C++ Type:int

    Controllable:No

    Description:Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.

  • force_postauxFalseForces the UserObject to be executed in POSTAUX

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Forces the UserObject to be executed in POSTAUX

  • force_preauxFalseForces the UserObject to be executed in PREAUX

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Forces the UserObject to be executed in PREAUX

  • force_preicFalseForces the UserObject to be executed in PREIC during initial setup

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Forces the UserObject to be executed in PREIC during initial setup

  • use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Advanced Parameters

Input Files