Skip to content

Phase kinetics composition #7024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lhy11009 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Phase kinetics composition #7024

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions doc/modules/changes/20260713_lhy11009
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Added: A new composition type of "phase kinetics"
which is used to modify composition properties in
visco plastic material models base on phase transition
kinetics.
<br>
(Haoyuan Li, 2026/07/13)
4 changes: 2 additions & 2 deletions doc/sphinx/parameters/Compositional_20fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ The format of valid entries for this parameter is that of a map given as &ldquo;
:name: parameters:Compositional_20fields/Types_20of_20fields
**Default value:** unspecified

**Pattern:** [List of <[Selection chemical composition|stress|strain|grain size|porosity|density|entropy|generic|unspecified ]> of length 0...4294967295 (inclusive)]
**Pattern:** [List of <[Selection chemical composition|stress|strain|grain size|porosity|density|entropy|phase kinetics|generic|unspecified ]> of length 0...4294967295 (inclusive)]

**Documentation:** A comma separated list denoting a &ldquo;type&rdquo; for each of the compositional fields requested. ASPECT uses these types to determine how fields are handled when evaluating the material model and when solving the equations as described below.

Expand All @@ -76,7 +76,7 @@ Each entry of the list must be one of several recognized types: * &ldquo;chemica
* &ldquo;porosity&rdquo;: This type of field represents porosity in a two-phase flow or Darcy flow system. Note that setting the type of a compositional field to &ldquo;porosity&rdquo; does not automatically enable melt transport, which is done with the parameter &ldquo;Melt settings/Include melt transport&rdquo;.
* &ldquo;density&rdquo;: This type of field is a finite-element field representation of the density in the model. This field type is not usually used except for the projected density approximation of the compressible Stokes equations, which uses this field type to compute gradients and time-derivatives of the density.
* &ldquo;entropy&rdquo;: This type of field represents entropy. If one or more entropy fields are found in a model, they automatically replace temperature as the main thermodynamic state variable in the model. The temperature equation is then automatically changed to a pure diffusion equation, which is coupled to the entropy advection equation as described in the paper {cite}`dannberg:etal:2022`.
* &ldquo;generic&rdquo;: The generic type is intended to be a placeholder type that is not used by any component of ASPECT unless in user-provided source code.
* &ldquo;phase kinetics&rdquo;: This type of field represents the progress of a phase transition controlled by reaction kinetics. It will only be considered in material models that include models for time-dependent phase transition kinetics.* &ldquo;generic&rdquo;: The generic type is intended to be a placeholder type that is not used by any component of ASPECT unless in user-provided source code.
* &ldquo;unspecified&rdquo;: The unspecified type is intended to tell ASPECT that the user has not explicitly indicated the type of this field. ASPECT will then try to detect the type automatically based on the name, but will default to &ldquo;chemical composition&rdquo; if the name does not correspond to a known type.

Note that while ASPECT&rsquo;s functionality can make use of the field types, not all of the code will make use of it. It is the user&rsquo;s responsibility to check that the chosen material model and other plugins interpret the compositional fields as intended.
Expand Down
36 changes: 36 additions & 0 deletions doc/sphinx/parameters/Material_20model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1539,6 +1539,15 @@ Units: \si{\pascal\second}
**Documentation:** A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition kinetics mapping<parameters:Material_20model/Grain_20size_20model/Phase_20transition_20kinetics_20mapping>`
:name: parameters:Material_20model/Grain_20size_20model/Phase_20transition_20kinetics_20mapping
**Default value:** -1

**Pattern:** [Anything]

**Documentation:** A list of indices that maps each phase transition to a phase-kinetics compositional field. For example, an entry of 0 indicates that the corresponding phase transition uses the 0th phase-kinetics composition. All following phase transitions will be affected by the metastablity of that transition kinetics. A negative value means the phase transition is assumed to be equilibrium.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition pressure widths<parameters:Material_20model/Grain_20size_20model/Phase_20transition_20pressure_20widths>`
:name: parameters:Material_20model/Grain_20size_20model/Phase_20transition_20pressure_20widths
**Default value:**
Expand Down Expand Up @@ -1903,6 +1912,15 @@ Units: \si{\pascal\second}
**Documentation:** A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition kinetics mapping<parameters:Material_20model/Latent_20heat/Phase_20transition_20kinetics_20mapping>`
:name: parameters:Material_20model/Latent_20heat/Phase_20transition_20kinetics_20mapping
**Default value:** -1

**Pattern:** [Anything]

**Documentation:** A list of indices that maps each phase transition to a phase-kinetics compositional field. For example, an entry of 0 indicates that the corresponding phase transition uses the 0th phase-kinetics composition. All following phase transitions will be affected by the metastablity of that transition kinetics. A negative value means the phase transition is assumed to be equilibrium.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition pressure widths<parameters:Material_20model/Latent_20heat/Phase_20transition_20pressure_20widths>`
:name: parameters:Material_20model/Latent_20heat/Phase_20transition_20pressure_20widths
**Default value:**
Expand Down Expand Up @@ -3421,6 +3439,15 @@ A typical example would be to set this runtime parameter to &lsquo;pi=3.14159265
**Documentation:** A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition kinetics mapping<parameters:Material_20model/Multicomponent_20compressible/Phase_20transition_20kinetics_20mapping>`
:name: parameters:Material_20model/Multicomponent_20compressible/Phase_20transition_20kinetics_20mapping
**Default value:** -1

**Pattern:** [Anything]

**Documentation:** A list of indices that maps each phase transition to a phase-kinetics compositional field. For example, an entry of 0 indicates that the corresponding phase transition uses the 0th phase-kinetics composition. All following phase transitions will be affected by the metastablity of that transition kinetics. A negative value means the phase transition is assumed to be equilibrium.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition pressure widths<parameters:Material_20model/Multicomponent_20compressible/Phase_20transition_20pressure_20widths>`
:name: parameters:Material_20model/Multicomponent_20compressible/Phase_20transition_20pressure_20widths
**Default value:**
Expand Down Expand Up @@ -5206,6 +5233,15 @@ Note that melt does not freeze unless the &rsquo;Freezing rate&rsquo; parameter
**Documentation:** A list of phase indicators in a look-up table for each phase transition. This parameter selectively assign different rheologies to specific phases, rather than having a unique rheology for each phase in the table. For example, if the table has phases 0, 1, and 2, and one only want a distinct rheology for phase 2, then only phase 2 is needed in the list of indicator. And phases 0, 1 will just be assigned the rheology of the base phase.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition kinetics mapping<parameters:Material_20model/Visco_20Plastic/Phase_20transition_20kinetics_20mapping>`
:name: parameters:Material_20model/Visco_20Plastic/Phase_20transition_20kinetics_20mapping
**Default value:** -1

**Pattern:** [Anything]

**Documentation:** A list of indices that maps each phase transition to a phase-kinetics compositional field. For example, an entry of 0 indicates that the corresponding phase transition uses the 0th phase-kinetics composition. All following phase transitions will be affected by the metastablity of that transition kinetics. A negative value means the phase transition is assumed to be equilibrium.
::::

::::{dropdown} __Parameter:__ {ref}`Phase transition pressure widths<parameters:Material_20model/Visco_20Plastic/Phase_20transition_20pressure_20widths>`
:name: parameters:Material_20model/Visco_20Plastic/Phase_20transition_20pressure_20widths
**Default value:**
Expand Down
7 changes: 5 additions & 2 deletions include/aspect/introspection.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,9 @@ namespace aspect
porosity = 4,
density = 5,
entropy = 6,
generic = 7,
unspecified = 8
phase_kinetics = 7,
generic = 8,
unspecified = 9
} type;

/**
Expand Down Expand Up @@ -94,6 +95,8 @@ namespace aspect
return CompositionalFieldDescription::density;
else if (input == "entropy")
return CompositionalFieldDescription::entropy;
else if (input == "phase kinetics")
return CompositionalFieldDescription::phase_kinetics;
else if (input == "generic")
return CompositionalFieldDescription::generic;
else if (input == "unspecified")
Expand Down
2 changes: 2 additions & 0 deletions include/aspect/material_model/equation_of_state/interface.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,8 @@ namespace aspect
phase_average_equation_of_state_outputs(const EquationOfStateOutputs<dim> &eos_outputs_all_phases,
const std::vector<double> &phase_function_values,
const std::vector<unsigned int> &n_phase_transitions_per_composition,
const std::vector<double> &phase_kinetics_values,
const std::vector<int> &phase_kinetics_mapping,
EquationOfStateOutputs<dim> &eos_outputs);
}
}
Expand Down
36 changes: 35 additions & 1 deletion include/aspect/material_model/utilities.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -516,15 +516,41 @@ namespace aspect
* on phase functions and the change of variables on the trajectory of phase boundaries.
* Thus on a single phase boundary, values of variables change gradually from one phase
* to the other. The values of the phase function used to average the properties varies
* between 0 and 1.
* between 0 and 1. In addition, values in @p phase_kinetics_values is used the modify
* the results based on phase transition kinetics.
*/
double phase_average_value (const std::vector<double> &phase_function_values,
const std::vector<unsigned int> &n_phase_transitions_per_composition,
const std::vector<double> &parameter_values,
const unsigned int composition_index,
const PhaseUtilities::PhaseAveragingOperation operation = PhaseUtilities::arithmetic);

double phase_average_value (const std::vector<double> &phase_function_values,
const std::vector<unsigned int> &n_phase_transitions_per_composition,
const std::vector<double> &phase_kinetics_values,
const std::vector<int> &phase_kinetics_mapping,
const std::vector<double> &parameter_values,
const unsigned int composition_index,
const PhaseUtilities::PhaseAveragingOperation operation = PhaseUtilities::arithmetic);

/**
* Extract the phase-transition kinetics information associated with a
* particular composition. The number of phase transitions for each
* composition is given in @p n_phase_transitions_per_composition, while
* @p phase_transition_kinetics_mapping contains one entry for every phase
* transition across all compositions. A non-negative mapping entry gives
* the index of the corresponding value in @p phase_kinetics_values, whereas
* a negative entry indicates that the phase transition is not associated
* with a kinetics variable.
* For the composition specified by @p composition_index, this function
* returns a pair containing the relevant phase-kinetics values and their
* corresponding local phase-transition indices.
*/
std::pair<std::vector<double>, std::vector<unsigned int>>
map_transition_kinetics_to_phases (const std::vector<unsigned int> &n_phase_transitions_per_composition,
const std::vector<int> &phase_transition_kinetics_mapping,
const std::vector<double> &phase_kinetics_values,
const unsigned int composition_index);

/**
* A data structure with all inputs for the
Expand Down Expand Up @@ -787,6 +813,13 @@ namespace aspect
*/
unsigned int n_phases_over_all_chemical_compositions () const;

/**
* Return the mapping to the transition kinetics
*/
const std::vector<int>
get_transition_kinetics_mapping () const;


/**
* Return the Clapeyron slope (dp/dT of the transition) for
* phase transition number @p phase_transition_index.
Expand Down Expand Up @@ -861,6 +894,7 @@ namespace aspect
std::vector<double> transition_slopes;
std::vector<double> transition_temperature_upper_limits;
std::vector<double> transition_temperature_lower_limits;
std::vector<double> transition_kinetics_mapping;

/**
* Whether to define the phase transitions based on depth, or pressure.
Expand Down
28 changes: 22 additions & 6 deletions source/material_model/equation_of_state/interface.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,22 +45,36 @@ namespace aspect
phase_average_equation_of_state_outputs(const EquationOfStateOutputs<dim> &eos_outputs_all_phases,
const std::vector<double> &phase_function_values,
const std::vector<unsigned int> &n_phase_transitions_per_composition,
const std::vector<double> &phase_kinetics_values,
const std::vector<int> &phase_transition_kinetics_mapping,
EquationOfStateOutputs<dim> &eos_outputs)
{
for (unsigned int c=0; c<eos_outputs.densities.size(); ++c)
{
eos_outputs.densities[c] =
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition, eos_outputs_all_phases.densities, c);
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition,
phase_kinetics_values, phase_transition_kinetics_mapping,
eos_outputs_all_phases.densities, c);
eos_outputs.thermal_expansion_coefficients[c] =
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition, eos_outputs_all_phases.thermal_expansion_coefficients, c);
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition,
phase_kinetics_values, phase_transition_kinetics_mapping,
eos_outputs_all_phases.thermal_expansion_coefficients, c);
eos_outputs.specific_heat_capacities[c] =
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition, eos_outputs_all_phases.specific_heat_capacities, c);
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition,
phase_kinetics_values, phase_transition_kinetics_mapping,
eos_outputs_all_phases.specific_heat_capacities, c);
eos_outputs.compressibilities[c] =
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition, eos_outputs_all_phases.compressibilities, c);
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition,
phase_kinetics_values, phase_transition_kinetics_mapping,
eos_outputs_all_phases.compressibilities, c);
eos_outputs.entropy_derivative_pressure[c] =
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition, eos_outputs_all_phases.entropy_derivative_pressure, c);
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition,
phase_kinetics_values, phase_transition_kinetics_mapping,
eos_outputs_all_phases.entropy_derivative_pressure, c);
eos_outputs.entropy_derivative_temperature[c] =
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition, eos_outputs_all_phases.entropy_derivative_temperature, c);
MaterialModel::MaterialUtilities::phase_average_value(phase_function_values, n_phase_transitions_per_composition,
phase_kinetics_values, phase_transition_kinetics_mapping,
eos_outputs_all_phases.entropy_derivative_temperature, c);
}
}
}
Expand All @@ -76,6 +90,8 @@ namespace aspect
template void phase_average_equation_of_state_outputs<dim> (const EquationOfStateOutputs<dim> &, \
const std::vector<double> &phase_function_values, \
const std::vector<unsigned int> &n_phase_transitions_per_composition, \
const std::vector<double> &phase_kinetics_values, \
const std::vector<int> &phase_transition_kinetics_mapping,\
EquationOfStateOutputs<dim> &);

ASPECT_INSTANTIATE(INSTANTIATE)
Expand Down
2 changes: 2 additions & 0 deletions source/material_model/multicomponent_compressible.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,8 @@ namespace aspect
phase_average_equation_of_state_outputs(eos_outputs_all_phases,
phase_function_values,
n_phase_transitions_for_each_chemical_composition,
{},
{},
eos_outputs);

// Calculate volume fractions from mass fractions
Expand Down
Loading
Loading