Solvers

Stokes Flow

SNES_Stokes

class underworld3.systems.solvers.SNES_Stokes[source]

Bases: SNES_Stokes_SaddlePt

Stokes equation solver for incompressible viscous flow.

This class provides functionality for a discrete representation of the Stokes flow equations assuming an incompressibility (or near-incompressibility) constraint.

The momentum equation is:

\[-\nabla \cdot \left[ \boldsymbol{\tau} - p \mathbf{I} \right] = \mathbf{f}\]

with the incompressibility constraint:

\[\nabla \cdot \mathbf{u} = 0\]

The flux term is a deviatoric stress (\(\boldsymbol{\tau}\)) related to velocity gradients (\(\nabla \mathbf{u}\)) through a viscosity tensor \(\eta\), and a volumetric (pressure) part \(p\):

\[\boldsymbol{\tau} = \frac{\eta}{2}\left( \nabla \mathbf{u} + \nabla \mathbf{u}^T \right)\]

The constraint equation gives incompressible flow by default but can be set to any function of the unknown \(\mathbf{u}\) and \(\nabla \cdot \mathbf{u}\).

Parameters:

  • mesh (uw.discretisation.Mesh) – The computational mesh.

  • velocityField (uw.discretisation.MeshVariable, optional) – Pre-existing velocity field. If None, one is created automatically.

  • pressureField (uw.discretisation.MeshVariable, optional) – Pre-existing pressure field. If None, one is created automatically.

  • degree (int, optional) – Polynomial degree for velocity interpolation. Default is 2.

  • p_continuous (bool, optional) – If True (default), pressure is continuous. Set False for discontinuous pressure.

  • verbose (bool, optional) – Enable verbose output during solving. Default is False.

  • DuDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Material derivative operator for velocity (used in derived classes).

  • DFDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Material derivative operator for flux (used in viscoelastic models).

Notes

Viscosity model: The viscosity tensor \(\boldsymbol{\eta}\) is provided by setting the constitutive_model property to one of the uw.constitutive_models classes. It may be constant, spatially varying, non-linear, or anisotropic.

Augmented Lagrangian: Setting penalty to a non-zero value adds \(\lambda \nabla \cdot \mathbf{u}\) to the weak form, improving convergence for incompressible flow (in addition to the constraint equation).

Mixed finite elements: The pressure field interpolation order determines the integration order of the mixed method and is typically lower than the velocity field order.

Viscoelastic models: For viscoelastic behaviour, the flux term contains stress history tracked on a particle swarm. See SNES_VE_Stokes.

See also

SNES_VE_Stokes

Viscoelastic Stokes solver with flux history.

SNES_NavierStokes

Navier-Stokes solver with inertial terms.

uw.constitutive_models

Available viscosity models.

Examples

>>> import underworld3 as uw
>>> mesh = uw.meshing.UnstructuredSimplexBox(minCoords=(0,0), maxCoords=(1,1), cellSize=0.1)
>>> stokes = uw.systems.Stokes(mesh, degree=2)
>>> stokes.constitutive_model = uw.constitutive_models.ViscousFlowModel()
>>> stokes.constitutive_model.Parameters.viscosity = 1.0
>>> stokes.bodyforce = [0, -1]  # gravity
>>> stokes.solve()
instances = 0
__init__(mesh, velocityField=None, pressureField=None, degree=2, p_continuous=True, verbose=False, DuDt=None, DFDt=None)[source]
Parameters:
F0

Velocity equation body force term (pointwise).

The \(\mathbf{f}_0\) term represents external body forces acting on the fluid, typically gravity. This is the negative of the bodyforce parameter.

F1

Velocity equation flux/stress term (pointwise).

The \(\mathbf{F}_1\) tensor represents the stress response of the fluid, combining deviatoric stress \(\boldsymbol{\tau}\), pressure \(p\), and penalty term for weak incompressibility.

PF0

Pressure equation constraint term (continuity).

The \(h_0\) term enforces the incompressibility constraint \(\nabla \cdot \mathbf{u} = 0\). Additional constraints can be added via add_condition().

stokes_problem_description()[source]

Build residual terms for Stokes FEM assembly (deprecated).

property CM_is_setup

Whether the constitutive model is configured for this solver.

property strainrate

Symmetric strain rate tensor from velocity gradients.

The strain rate tensor \(\dot{\varepsilon}\) is computed as:

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

Symmetric tensor of shape (dim, dim) where dim is the mesh dimensionality.

Return type:

sympy.Matrix

See also

strainrate_1d

Voigt notation (vector) form.

stress_deviator

Deviatoric stress computed from strain rate.

property strainrate_1d

Strain rate in Voigt notation (vector form).

Converts the symmetric strain rate tensor to Voigt notation for use in constitutive model calculations. In 2D, returns a 3-component vector; in 3D, a 6-component vector.

Returns:

Strain rate in Voigt notation.

Return type:

sympy.Matrix

See also

strainrate

Full tensor form.

property strainrate_star_1d

Historical strain rate in Voigt notation (for viscoelastic models).

Used in viscoelastic formulations where the stress depends on both current and historical strain rates.

Returns:

Historical strain rate in Voigt notation.

Return type:

sympy.Matrix

See also

strainrate_1d

Current strain rate.

property stress_deviator

Deviatoric stress tensor from the constitutive model.

The deviatoric stress \(\boldsymbol{\tau}\) is the traceless part of the stress tensor, computed by the constitutive model from the strain rate:

\[\boldsymbol{\tau} = \boldsymbol{\eta} : \dot{\boldsymbol{\varepsilon}}\]

For a Newtonian fluid: \(\boldsymbol{\tau} = 2\eta\dot{\boldsymbol{\varepsilon}}\)

Returns:

Deviatoric stress tensor of shape (dim, dim).

Return type:

sympy.Matrix

See also

stress

Total stress (deviatoric + pressure).

constitutive_model

Provides the viscosity relationship.

property stress_deviator_1d

Deviatoric stress in Voigt notation.

Returns:

Deviatoric stress in Voigt notation.

Return type:

sympy.Matrix

See also

stress_deviator

Full tensor form.

property stress

Total Cauchy stress tensor.

The total stress combines the deviatoric stress and pressure:

\[\boldsymbol{\sigma} = \boldsymbol{\tau} - p\mathbf{I}\]

where \(\boldsymbol{\tau}\) is the deviatoric stress and \(p\) is the pressure (positive in compression).

Returns:

Total stress tensor of shape (dim, dim).

Return type:

sympy.Matrix

See also

stress_deviator

Deviatoric (traceless) part.

property stress_1d

Total stress in Voigt notation.

Returns:

Total stress in Voigt notation.

Return type:

sympy.Matrix

See also

stress

Full tensor form.

property div_u

Velocity divergence.

For incompressible flow, this should be zero:

\[\nabla \cdot \mathbf{u} = 0\]
Returns:

Scalar divergence expression.

Return type:

sympy.Expr

Notes

Non-zero divergence indicates compressibility or mass sources/sinks.

property constraints

Constraint equation for the saddle-point system.

By default, this is the incompressibility constraint \(\nabla \cdot \mathbf{u} = 0\). Can be modified for compressible or other constrained formulations.

Returns:

Constraint expression.

Return type:

sympy.Expr

property bodyforce

Body force vector (source term).

The volumetric body force \(\mathbf{f}\) appears on the right-hand side of the momentum equation:

\[-\nabla \cdot \boldsymbol{\sigma} = \mathbf{f}\]

Common examples include gravity (\(\rho\mathbf{g}\)) or buoyancy forces.

Returns:

Body force vector expression.

Return type:

UWexpression

property saddle_preconditioner

Preconditioner for the Schur complement in the saddle-point system.

For the Stokes system, the default preconditioner is \(1/\eta\) (inverse viscosity), which approximates the Schur complement \(\mathbf{S} \approx \mathbf{B}\mathbf{A}^{-1}\mathbf{B}^T\).

Returns:

Preconditioner expression (typically inverse viscosity).

Return type:

sympy.Expr

Notes

A good preconditioner significantly improves convergence of the iterative solver. For variable viscosity, use the local viscosity.

property penalty

Augmented Lagrangian penalty parameter.

The penalty \(\lambda\) adds a term to the weak form that penalizes non-zero divergence:

\[\lambda \int (\nabla \cdot \mathbf{u})(\nabla \cdot \mathbf{v}) \, dV\]

This improves convergence for incompressible flow without changing the solution (since \(\nabla \cdot \mathbf{u} = 0\) at convergence).

Returns:

Augmented Lagrangian penalty parameter (typically \(O(1)\)).

Return type:

UWexpression

Notes

Set to zero for standard Stokes without augmentation. Unlike classical penalty methods that require very large values, the Augmented Lagrangian approach uses modest penalties of \(O(1)\) to improve solver convergence.

References

Glowinski, R., & Le Tallec, P. (1989). Augmented Lagrangian and Operator-Splitting Methods in Nonlinear Mechanics. SIAM. https://doi.org/10.1137/1.9781611970838

estimate_dt()[source]

Calculates an appropriate advective timestep for the Stokes solver.

The Stokes equations are quasi-static (no time derivative ∂v/∂t), so there is no diffusive CFL constraint. The only relevant timescale is the advective one: how long it takes material to cross an element.

This method computes a per-element timestep:

\[\delta t_i = h_i / \|\mathbf{v}_i\|\]

where \(h_i\) is the element radius and \(\mathbf{v}_i\) is the velocity at the element centroid, then returns the global minimum. This is more accurate than using global max velocity with global min element size, especially for non-uniform meshes with spatially varying velocity.

Returns:

Pint Quantity or float: The advective timestep with physical time units if a model with reference scales is available, otherwise nondimensional.

SNES_VE_Stokes

Viscoelastic extension of the Stokes solver.

class underworld3.systems.solvers.SNES_VE_Stokes[source]

Bases: SNES_Stokes

Viscoelastic Stokes equation solver.

Provides a discrete representation of the Stokes flow equations with incompressibility (or near-incompressibility) constraint and a flux history term for viscoelastic modelling. Inherits from SNES_Stokes.

Momentum equation:

\[-\nabla \cdot \underbrace{\left[ \boldsymbol{\tau} - p \mathbf{I} \right]}_{\mathbf{F}} = \underbrace{\mathbf{f}}_{\mathbf{h}}\]

Continuity equation:

\[\underbrace{\nabla \cdot \mathbf{u}}_{\mathbf{h}_p} = 0\]

The flux term is a deviatoric stress \(\boldsymbol{\tau}\) related to velocity gradients \(\nabla \mathbf{u}\) through a viscosity tensor \(\eta\), plus a volumetric (pressure) part \(p\):

\[\mathbf{F}: \quad \boldsymbol{\tau} = \frac{\eta}{2} \left( \nabla \mathbf{u} + \nabla \mathbf{u}^T \right)\]

The constraint equation \(\mathbf{h}_p = 0\) is incompressible flow by default but can be set to any function of \(\mathbf{u}\) and \(\nabla \cdot \mathbf{u}\).

Parameters:

  • mesh (Mesh) – The computational mesh.

  • velocityField (MeshVariable, optional) – Mesh variable for velocity. Created automatically if not provided.

  • pressureField (MeshVariable, optional) – Mesh variable for pressure. Created automatically if not provided.

  • degree (int, default=2) – Polynomial degree for velocity elements.

  • order (int, default=2) – Order parameter (typically same as degree).

  • p_continuous (bool, default=True) – If False, use discontinuous pressure elements.

  • verbose (bool, default=False) – Enable verbose output.

  • DuDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Time derivative operator (may be used in child classes).

Notes

  • The viscosity tensor \(\boldsymbol{\eta}\) is set via the constitutive_model property

  • For viscoelastic problems, the flux term contains stress history tracked on a particle swarm

  • Augmented Lagrangian approach adds \(\lambda \nabla \cdot \mathbf{u}\) to penalize incompressibility

  • Pressure element order determines mixed FEM integration order

See also

SNES_Stokes

Base Stokes solver.

uw.constitutive_models.ViscoElasticPlasticFlowModel

Constitutive model for VE flow.

instances = 0
__init__(mesh, velocityField=None, pressureField=None, degree=2, order=2, p_continuous=True, verbose=False, DuDt=None, DFDt=None)[source]
Parameters:
property delta_t

Elastic timestep from the constitutive model.

solve(zero_init_guess=True, timestep=None, _force_setup=False, verbose=False, evalf=False, order=None)[source]

Generates solution to constructed system.

Params

zero_init_guess:

If True, a zero initial guess will be used for the system solution. Otherwise, the current values of self.u will be used.

Parameters:

Scalar Equations

SNES_Poisson

class underworld3.systems.solvers.SNES_Poisson[source]

Bases: SNES_Scalar

Poisson equation solver.

Provides a discrete representation of the Poisson equation:

\[\nabla \cdot \left[ \boldsymbol{\kappa} \nabla u \right] = f\]

where \(\mathbf{F} = \boldsymbol{\kappa} \nabla u\) relates the flux to gradients in the unknown \(u\).

Parameters:

  • mesh (Mesh) – The computational mesh.

  • u_Field (MeshVariable, optional) – Pre-existing mesh variable for the solution. If None, one is created.

  • verbose (bool, optional) – Enable verbose output during solve.

  • degree (int, optional) – Polynomial degree for the solution field (default: 2).

  • DuDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Time derivative operator for time-dependent problems.

  • DFDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Time derivative operator for the flux.

__init__(mesh, u_Field=None, verbose=False, degree=2, DuDt=None, DFDt=None)[source]
Parameters:
F0

Source term for the Poisson equation (pointwise).

The \(f_0\) term represents the source/sink in the diffusion equation. Set via the f property (e.g., poisson.f = heat_source).

F1

Diffusive flux term for the Poisson equation (pointwise).

The \(\mathbf{F}_1\) vector represents the flux \(k \nabla u\) from the constitutive model, where \(k\) is the diffusivity.

poisson_problem_description()[source]

Build residual terms for Poisson FEM assembly.

property f

Source term for the Poisson equation.

The source term \(f\) appears on the right-hand side:

\[\nabla \cdot (\kappa \nabla u) = f\]
Returns:

Source term expression (scalar, shape (1, 1)).

Return type:

sympy.Matrix

See also

constitutive_model

Provides the diffusivity \(\kappa\).

property CM_is_setup

Whether the constitutive model is configured for this solver.

SNES_Darcy

class underworld3.systems.solvers.SNES_Darcy[source]

Bases: SNES_Scalar

Darcy flow equation solver for groundwater problems.

Provides a discrete representation of the groundwater flow equations:

\[\underbrace{S_s \frac{\partial h}{\partial t}}_{\dot{u}} - \nabla \cdot \underbrace{\left[ \boldsymbol{\kappa} \nabla h - \boldsymbol{s} \right]}_{\mathbf{F}} = \underbrace{W}_{h}\]

The flux term \(\mathbf{F}\) relates the effective velocity to pressure gradients:

\[\boldsymbol{v} = \boldsymbol{\kappa} \nabla h - \boldsymbol{s}\]
Parameters:

  • mesh (Mesh) – The computational mesh.

  • h_Field (MeshVariable, optional) – Mesh variable for hydraulic head. Created automatically if not provided.

  • v_Field (MeshVariable, optional) – Mesh variable for Darcy velocity. Created automatically if not provided.

  • degree (int, default=2) – Polynomial degree for the finite element discretization.

  • verbose (bool, default=False) – Enable verbose output.

  • DuDt (optional) – Time derivative operator for the unknown.

  • DFDt (optional) – Time derivative operator for the flux.

Notes

  • The unknown is \(h\), the hydraulic head

  • The permeability tensor \(\kappa\) is set via the constitutive_model property using one of the uw.constitutive_models classes

  • \(W\) is a pressure source term

  • \(S_s\) is the specific storage coefficient

  • The time-dependent term \(\dot{f}\) is not implemented in this version

  • The solver returns both the primary field and the Darcy flux (mean-flow velocity)

See also

SNES_Poisson

Related diffusion-only solver.

uw.constitutive_models.DarcyFlowModel

Constitutive model for Darcy flow.

__init__(mesh, h_Field=None, v_Field=None, degree=2, verbose=False, DuDt=None, DFDt=None)[source]
Parameters:

  • mesh (Mesh)

  • h_Field (EnhancedMeshVariable | None)

  • v_Field (EnhancedMeshVariable | None)

  • degree (int)

F0

Source term for the Darcy pressure equation (pointwise).

The \(f_0\) term represents fluid sources/sinks. Set via the f property.

F1

Darcy flux term (pointwise).

The \(\mathbf{F}_1\) vector is the Darcy flux \(K \nabla p\), where \(K\) is the permeability.

darcy_problem_description()[source]

Build residual terms for Darcy flow FEM assembly.

property f

Source term for the Darcy equation.

property darcy_flux

Darcy flux velocity computed from pressure gradient.

property v

Projected Darcy velocity field.

solve(zero_init_guess=True, timestep=None, verbose=False, _force_setup=False)[source]

Solve the Darcy flow system.

Computes the pressure field and Darcy flux velocity.

Parameters:

  • zero_init_guess (bool, optional) – If True (default), start from zero initial guess. If False, use current field values as initial guess.

  • timestep (float, optional) – Timestep value for inertial terms (if applicable).

  • verbose (bool, optional) – If True, print solver progress information.

  • _force_setup (bool, optional) – Force re-setup of solver even if already configured.

Notes

After solving, the pressure field self.u and velocity field self.v contain the solution.

SNES_AdvectionDiffusion

class underworld3.systems.solvers.SNES_AdvectionDiffusion[source]

Bases: SNES_Scalar

Advection-diffusion equation solver using semi-Lagrangian Crank-Nicolson.

Implements the characteristics-based method described in Spiegelman & Katz (2006):

\[\underbrace{\frac{\partial u}{\partial t} + \left( \mathbf{v} \cdot \nabla \right) u}_{\dot{u}} - \nabla \cdot \underbrace{\left[ \boldsymbol{\kappa} \nabla u \right]}_{\mathbf{F}} = \underbrace{f}_{\mathbf{h}}\]

The flux term \(\mathbf{F}\) relates diffusive fluxes to gradients in \(u\). Advective fluxes along the velocity field \(\mathbf{v}\) are handled in the \(\dot{u}\) term.

The time derivative \(\dot{u}\) involves upstream sampling to find \(u^*\), the value of \(u\) at points which later arrive at mesh nodes. This is achieved using a hidden swarm variable advected backwards from nodal points automatically during solve.

Parameters:

  • mesh (Mesh) – The computational mesh.

  • u_Field (MeshVariable) – Mesh variable for the transported scalar.

  • V_fn (MeshVariable or sympy.Basic) – Velocity field for advection.

  • order (int, default=1) – Time integration order (1 or 2).

  • restore_points_func (callable, optional) – Function to restore particles to valid domain.

  • verbose (bool, default=False) – Enable verbose output.

  • DuDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Time derivative operator for the unknown.

  • DFDt (SemiLagrangian_DDt or Lagrangian_DDt, optional) – Time derivative operator for the flux.

Notes

  • The diffusivity \(\kappa\) is set via the constitutive_model property

  • Sources \(f\) can be any sympy expression involving mesh/swarm variables

References

Spiegelman, M., & Katz, R. F. (2006). A semi-Lagrangian Crank-Nicolson algorithm for the numerical solution of advection-diffusion problems. Geochemistry, Geophysics, Geosystems, 7(4). https://doi.org/10.1029/2005GC001073

See also

SNES_Diffusion

Pure diffusion solver without advection.

SNES_Navier_Stokes

Full momentum advection-diffusion.

__init__(mesh, u_Field, V_fn, order=1, restore_points_func=None, verbose=False, DuDt=None, DFDt=None)[source]
Parameters:
property F0

Pointwise source term including time derivative.

property F1

Pointwise diffusive flux term (Adams-Moulton integration).

adv_diff_slcn_problem_description()[source]

Build residual terms for advection-diffusion FEM assembly.

property f

Source term for the advection-diffusion equation.

The source \(f\) appears on the right-hand side:

\[\frac{\partial u}{\partial t} + \mathbf{V} \cdot \nabla u = \nabla \cdot (\kappa \nabla u) + f\]
Returns:

Source term expression.

Return type:

sympy.Matrix

property V_fn

Velocity field for advection.

The advection velocity \(\mathbf{V}\) transports the scalar field \(u\). Can be a MeshVariable or symbolic expression.

Returns:

Velocity vector expression.

Return type:

sympy.Matrix

property delta_t

Timestep for time integration.

The timestep \(\Delta t\) controls the temporal discretization. For explicit advection, this should satisfy the CFL condition:

\[\Delta t < \frac{h}{|\mathbf{V}|}\]

where \(h\) is the element size and \(|\mathbf{V}|\) is the velocity magnitude.

Returns:

Timestep value.

Return type:

UWexpression

See also

estimate_dt

Computes a stable timestep automatically.

estimate_dt()[source]

Estimate an appropriate timestep for the advection-diffusion solver.

This is an implicit solver so the returned \(\delta t\) is the minimum of:

  • \(\delta t_{\textrm{diff}}\): typical time for diffusion across an element

  • \(\delta t_{\textrm{adv}}\): typical element-crossing time for a fluid parcel

Returns:

The recommended timestep with physical time units if a model with reference scales is available, otherwise nondimensional.

Return type:

pint.Quantity or float

solve(zero_init_guess=True, timestep=None, _force_setup=False, _evalf=False, verbose=False)[source]

Generates solution to constructed system.

Params

zero_init_guess:

If True, a zero initial guess will be used for the system solution. Otherwise, the current values of self.u will be used.

Parameters:

SNES_Diffusion

class underworld3.systems.solvers.SNES_Diffusion[source]

Bases: SNES_Scalar

Diffusion equation solver using mesh-based finite elements.

Solves the scalar diffusion equation:

\[\underbrace{\frac{\partial u}{\partial t}}_{\dot{f}} - \nabla \cdot \underbrace{\left[ \boldsymbol{\kappa} \nabla u \right]}_{\mathbf{F}} = \underbrace{f}_{h}\]

The flux term \(\mathbf{F}\) relates diffusive fluxes to gradients in the unknown \(u\).

Parameters:

  • mesh (Mesh) – The computational mesh.

  • u_Field (MeshVariable) – Mesh variable for the diffusing scalar.

  • order (int, default=1) – Time integration order.

  • theta (float, default=0.0) – Time integration parameter (0=explicit, 0.5=Crank-Nicolson, 1=implicit).

  • evalf (bool, default=False) – Numerically evaluate symbolic expressions during setup.

  • verbose (bool, default=False) – Enable verbose output.

  • DuDt (Eulerian_DDt, SemiLagrangian_DDt, or Lagrangian_DDt, optional) – Time derivative operator for the unknown.

  • DFDt (Eulerian_DDt, SemiLagrangian_DDt, or Lagrangian_DDt, optional) – Time derivative operator for the flux.

Notes

  • The diffusivity \(\kappa\) is set via the constitutive_model property

  • Sources \(f\) can be any sympy expression involving mesh/swarm variables

See also

SNES_AdvectionDiffusion

Adds advection transport.

SNES_Poisson

Steady-state diffusion (no time derivative).

__init__(mesh, u_Field, order=1, theta=0.0, evalf=False, verbose=False, DuDt=None, DFDt=None)[source]
Parameters:
property F0

Pointwise source term including time derivative.

property F1

Pointwise diffusive flux term.

property f

Source term for the diffusion equation.

property delta_t

Timestep for time integration.

estimate_dt()[source]

Estimate an appropriate timestep for the diffusion solver.

This solver only has a diffusive component, so the returned \(\delta t\) is:

  • \(\delta t_{\textrm{diff}}\): typical time for diffusion across an element

Returns:

The diffusive timestep with physical time units if a model with reference scales is available, otherwise nondimensional.

Return type:

pint.Quantity or float

solve(zero_init_guess=True, timestep=None, evalf=False, _force_setup=False, verbose=False)[source]

Generates solution to constructed system.

Params

zero_init_guess:

If True, a zero initial guess will be used for the system solution. Otherwise, the current values of self.u will be used.

Parameters:

Projection Solvers

SNES_Projection

class underworld3.systems.solvers.SNES_Projection[source]

Bases: SNES_Scalar

Scalar projection solver for mapping functions to mesh variables.

Solves \(u = \tilde{f}\) where \(\tilde{f}\) is a function that can be evaluated within an element and \(u\) is a mesh variable with associated shape functions.

Typically used to obtain a continuous representation of a function not well-defined at mesh nodes (e.g., derivatives or flux components). More broadly, it is a projection from one basis to another.

The projection is implemented by solving:

\[-\nabla \cdot \underbrace{\left[ \alpha \nabla u \right]}_{\mathbf{F}} - \underbrace{\left[ u - \tilde{f} \right]}_{\mathbf{h}} = 0\]

The term \(\mathbf{F}\) provides optional smoothing regularization. Setting \(\alpha = 0\) gives a pure L2 projection.

Parameters:

  • mesh (Mesh) – The computational mesh.

  • u_Field (MeshVariable, optional) – Target mesh variable for the projection.

  • scalar_Field (MeshVariable, optional) – Alternative name for the target field.

  • degree (int, default=2) – Polynomial degree for the finite element space.

  • solver_name (str, optional) – Name for the solver instance.

  • verbose (bool, default=False) – Enable verbose output.

See also

SNES_Vector_Projection

Vector field projection.

SNES_Tensor_Projection

Tensor field projection.

__init__(mesh, u_Field=None, degree=2, verbose=False)[source]
Parameters:

  • mesh (Mesh)

  • u_Field (EnhancedMeshVariable)

F0

Projection misfit term (pointwise).

The \(f_0\) term measures the weighted difference between the mesh variable and the target function for L2 projection.

F1

Projection smoothing term (pointwise).

The \(\mathbf{F}_1\) term provides optional regularization via \(\alpha \nabla u\), where \(\alpha\) is the smoothing parameter.

uw_function

Function to project onto mesh

property smoothing

Smoothing regularization parameter for the projection.

property uw_weighting_function

Weighting function applied during projection.

SNES_Vector_Projection

class underworld3.systems.solvers.SNES_Vector_Projection[source]

Bases: SNES_Vector

Vector projection solver for mapping vector functions to mesh variables.

Solves \(\mathbf{u} = \tilde{\mathbf{f}}\) where \(\tilde{\mathbf{f}}\) is a vector function that can be evaluated within an element and \(\mathbf{u}\) is a vector mesh variable with associated shape functions.

Typically used to obtain a continuous representation of a vector function not well-defined at mesh nodes (e.g., gradient or flux vectors).

The projection is implemented by solving:

\[-\nabla \cdot \underbrace{\left[ \alpha \nabla \mathbf{u} \right]}_{\mathbf{F}} - \underbrace{\left[ \mathbf{u} - \tilde{\mathbf{f}} \right]}_{\mathbf{h}} = 0\]

The term \(\mathbf{F}\) provides optional smoothing regularization. Setting \(\alpha = 0\) gives a pure L2 projection.

Parameters:

  • mesh (Mesh) – The computational mesh.

  • u_Field (MeshVariable, optional) – Target vector mesh variable for the projection.

  • degree (int, default=2) – Polynomial degree for the finite element space.

  • verbose (bool, default=False) – Enable verbose output.

See also

SNES_Projection

Scalar field projection.

SNES_Tensor_Projection

Tensor field projection.

__init__(mesh, u_Field=None, degree=2, verbose=False)[source]
Parameters:

  • mesh (Mesh)

  • u_Field (EnhancedMeshVariable)

F0

f_0(u)

Type:

Vector projection pointwise misfit term

F1

F_1(u)

Type:

Vector projection pointwise smoothing term

projection_problem_description()[source]

Build residual terms for vector projection FEM assembly.

uw_function

Vector function to project onto mesh

property smoothing

Smoothing regularization parameter for the projection.

property penalty

Divergence penalty parameter for incompressibility.

property uw_weighting_function

Weighting function applied during projection.