Constitutive Models¶

Viscous Flow Models¶

ViscousFlowModel¶

class underworld3.constitutive_models.ViscousFlowModel[source]¶

Bases: Constitutive_Model

Viscous flow constitutive model for Stokes-type solvers.

Defines the relationship between deviatoric stress and strain rate:

\[\tau_{ij} = \eta_{ijkl} \cdot \frac{1}{2} \left[ \frac{\partial u_k}{\partial x_l} + \frac{\partial u_l}{\partial x_k} \right]\]

where \(\eta\) is the viscosity, which can be a scalar constant, SymPy function, Underworld mesh variable, or any valid combination. This results in an isotropic (but not necessarily homogeneous or linear) relationship between \(\tau\) and the velocity gradients.

Parameters:

unknowns (Unknowns) – The solver unknowns (typically velocity and pressure fields).
material_name (str, optional) – Name identifier for this material (used in multi-material setups).

Examples

>>> import underworld3 as uw
>>> stokes = uw.systems.Stokes(mesh)
>>> viscous = uw.constitutive_models.ViscousFlowModel(stokes.Unknowns)
>>> viscous.Parameters.shear_viscosity_0 = 1e21  # Pa.s
>>> stokes.constitutive_model = viscous

Diffusion Models¶

DiffusionModel¶

class underworld3.constitutive_models.DiffusionModel[source]¶

Bases: Constitutive_Model

Diffusion (Fourier/Fick) constitutive model for scalar transport.

Defines the flux-gradient relationship for scalar diffusion:

\[q_{i} = \kappa_{ij} \frac{\partial \phi}{\partial x_j}\]

For isotropic diffusion, \(\kappa_{ij} = \kappa \delta_{ij}\).

Parameters:

unknowns (Unknowns) – The solver unknowns (the scalar field being diffused).
material_name (str, optional) – Name identifier for this material.

Examples

>>> diffusion = uw.constitutive_models.DiffusionModel(poisson.Unknowns)
>>> diffusion.Parameters.diffusivity = 1e-6  # m^2/s
>>> poisson.constitutive_model = diffusion

TransverseIsotropicFlowModel¶

class underworld3.constitutive_models.TransverseIsotropicFlowModel[source]¶

Bases: ViscousFlowModel

Transversely isotropic (anisotropic) viscous flow model.

\[\tau_{ij} = \eta_{ijkl} \cdot \frac{1}{2} \left[ \frac{\partial u_k}{\partial x_l} + \frac{\partial u_l}{\partial x_k} \right]\]

where \(\eta\) is the viscosity tensor defined as:

\[\eta_{ijkl} = \eta_0 \cdot I_{ijkl} + (\eta_0-\eta_1) \left[ \frac{1}{2} \left[ n_i n_l \delta_{jk} + n_j n_k \delta_{il} + n_i n_l \delta_{jk} + n_j n_l \delta_{ik} \right] - 2 n_i n_j n_k n_l \right]\]

and \(\hat{\mathbf{n}} \equiv \{n_i\}\) is the unit vector defining the local orientation of the weak plane (a.k.a. the director).

The Mandel constitutive matrix is available in viscous_model.C and the rank-4 tensor form is in viscous_model.c.

Examples

>>> viscous_model = TransverseIsotropicFlowModel(dim)
>>> viscous_model.material_properties = viscous_model.Parameters(
...     eta_0=viscosity_fn,
...     eta_1=weak_viscosity_fn,
...     director=orientation_vector_fn
... )
>>> solver.constitutive_model = viscous_model
>>> tau = viscous_model.flux(gradient_matrix)
---

__init__(unknowns, material_name=None)[source]¶

Initialize a constitutive model.

Parameters:

unknowns (UnknownSet) – The solver’s unknowns (velocity, pressure, etc.)
material_name (str, optional) – A distinguishing name for this material’s symbols. If provided, symbols will be subscripted: η → η_{name} Useful when bundling multiple models in MultiMaterialModel.

property viscosity¶: Whatever the consistutive model defines as the effective value of viscosity in the form of an uw.expression

property K¶: Whatever the consistutive model defines as the effective value of viscosity in the form of an uw.expression

property grad_u¶: Symmetric strain rate tensor (with 1/2 factor).

\[\dot{\varepsilon}_{ij} = \frac{1}{2}\left(\frac{\partial u_i}{\partial x_j} + \frac{\partial u_j}{\partial x_i}\right)\]

Viscoelastic Models¶

ViscoElasticPlasticFlowModel¶

class underworld3.constitutive_models.ViscoElasticPlasticFlowModel[source]¶

Bases: ViscousFlowModel

Viscoelastic-plastic flow constitutive model.

The stress (flux term) is given by:

\[\tau_{ij} = \eta_{ijkl} \cdot \frac{1}{2} \left[ \frac{\partial u_k}{\partial x_l} + \frac{\partial u_l}{\partial x_k} \right]\]

where \(\eta\) is the viscosity, a scalar constant, SymPy function, Underworld mesh variable, or any valid combination. This results in an isotropic (but not necessarily homogeneous or linear) relationship between \(\tau\) and the velocity gradients. You can also supply \(\eta_{IJ}\), the Mandel form of the constitutive tensor, or \(\eta_{ijkl}\), the rank-4 tensor.

The Mandel constitutive matrix is available in viscous_model.C and the rank 4 tensor form is in viscous_model.c. Apply the constitutive model using:

__init__(unknowns, order=1, material_name=None)[source]¶

Initialize a constitutive model.

Parameters:

unknowns (UnknownSet) – The solver’s unknowns (velocity, pressure, etc.)
material_name (str, optional) – A distinguishing name for this material’s symbols. If provided, symbols will be subscripted: η → η_{name} Useful when bundling multiple models in MultiMaterialModel.

property order¶: Time integration order (1 or 2).

property stress_star¶: Previous timestep stress \(\boldsymbol{\sigma}^*\) from history.

property stress_2star¶: Second-order stress history \(\boldsymbol{\sigma}^{**}\) (for 2nd order integration).

property E_eff¶: Effective strain rate including elastic contribution.

\[\dot{\varepsilon}_{\mathrm{eff}} = \dot{\varepsilon} + \frac{\boldsymbol{\sigma}^*}{2 G \Delta t}\]

property E_eff_inv_II¶

\(\dot{\varepsilon}_{II} = \sqrt{\frac{1}{2}\dot{\varepsilon}_{ij}\dot{\varepsilon}_{ij}}\).

Type:: Second invariant of effective strain rate

property K¶: Effective stiffness parameter (viscosity for visco-elastic-plastic flow).

property viscosity¶

Effective viscosity combining visco-elastic and plastic limits.

Returns \(\min(\eta_{\mathrm{ve}}, \tau_y / 2\dot{\varepsilon}_{II})\).

plastic_correction()[source]¶: Scaling factor to reduce stress to yield surface: \(f = \tau_y / \tau_{II}\).

property flux¶: Computes the effect of the constitutive tensor on the gradients of the unknowns. (always uses the c form of the tensor). In general cases, the history of the gradients may be required to evaluate the flux. For viscoelasticity, the

stress_projection()[source]¶: viscoelastic stress projection (no plastic response)

stress()[source]¶: viscoelastic stress projection (no plastic response)

property is_elastic¶: True if elastic behavior is active (finite dt_elastic and shear_modulus).

property is_viscoplastic¶: True if plastic yielding is active (finite yield_stress).

Darcy Flow¶

DarcyFlowModel¶

class underworld3.constitutive_models.DarcyFlowModel[source]¶

Bases: Constitutive_Model

Darcy flow constitutive model for porous media flow.

Relates the Darcy flux to pressure gradients and body forces:

\[q_{i} = \kappa_{ij} \left( \frac{\partial p}{\partial x_j} - s_j \right)\]

where \(\kappa\) is the permeability (or hydraulic conductivity), \(p\) is the pressure (or hydraulic head), and \(s\) is the body force term (e.g., gravity: \(s = \rho g\)).

Parameters:

unknowns (Unknowns) – The solver unknowns (the pressure/head field).
material_name (str, optional) – Name identifier for this material.

Examples

>>> darcy = uw.constitutive_models.DarcyFlowModel(solver.Unknowns)
>>> darcy.Parameters.permeability = 1e-12  # m^2
>>> darcy.Parameters.s = [0, -rho * g]  # Gravity in y-direction
>>> solver.constitutive_model = darcy