Materials

Material Management System for Underworld3 Models

This module provides structured material management with property definitions, region assignments, and automatic propagation to constitutive models and solvers.

Material Property

class underworld3.MaterialProperty

Bases: Enum

Standard material properties for geodynamic models

VISCOSITY = 'viscosity'

DENSITY = 'density'

YIELD_STRESS = 'yield_stress'

COHESION = 'cohesion'

FRICTION_ANGLE = 'friction_angle'

THERMAL_CONDUCTIVITY = 'thermal_conductivity'

THERMAL_DIFFUSIVITY = 'thermal_diffusivity'

HEAT_CAPACITY = 'heat_capacity'

THERMAL_EXPANSION = 'thermal_expansion'

YOUNGS_MODULUS = 'youngs_modulus'

POISSONS_RATIO = 'poissons_ratio'

SHEAR_MODULUS = 'shear_modulus'

PERMEABILITY = 'permeability'

POROSITY = 'porosity'

CUSTOM = 'custom'

Material Registry

class underworld3.MaterialRegistry

Bases: object

Central registry for material definitions and region assignments.

Features:

• Material property database with validation

• Region-based material assignments

• Temperature/pressure dependent properties

• Integration with constitutive models

• Automatic property propagation to solvers

Example:

>>> registry = MaterialRegistry()
>>> mantle = registry.create_material('mantle')
>>> mantle.set_property('viscosity', 1e21)
>>> mantle.set_property('density', 3300)
>>> registry.assign_to_region('mantle', region_id=1)

__init__()

create_material(name, description='', reference='')

Create a new material definition.

Parameters:

namestr

Material name

descriptionstr

Human-readable description

referencestr

Literature reference

Returns:

MaterialDefinition

New material instance

Parameters:

• name (str)

• description (str)

• reference (str)

Return type:

MaterialDefinition

get_material(name)

Get a material by name

Parameters:

name (str)

Return type:

MaterialDefinition | None

list_materials()

List all material names

Return type:

List[str]

delete_material(name)

Delete a material definition

Parameters:

name (str)

assign_to_region(material_name, region_id)

Assign a material to a mesh region.

Parameters:

material_namestr

Name of material to assign

region_idint

Mesh region identifier

Parameters:

• material_name (str)

• region_id (int)

get_region_material(region_id)

Get the material assigned to a region

Parameters:

region_id (int)

Return type:

str | None

get_material_regions(material_name)

Get all regions assigned to a material

Parameters:

material_name (str)

Return type:

List[int]

evaluate_property_field(prop, region_field, temperature=None, pressure=None)

Evaluate a material property over a field of region IDs.

Parameters:

propMaterialProperty or str

Property to evaluate

region_fieldarray

Array of region IDs

temperaturearray, optional

Temperature field for evaluation

pressurearray, optional

Pressure field for evaluation

Returns:

array

Property values corresponding to each region

Parameters:

• prop (MaterialProperty | str)

• region_field (ndarray)

• temperature (ndarray | None)

• pressure (ndarray | None)

Return type:

ndarray

add_callback(callback)

Add a callback function for material changes.

Parameters:

callback (callable) – Function called as callback(event_type, *args)

export_config()

Export material configuration

Return type:

Dict[str, Any]

import_config(config)

Import material configuration from exported dict

Parameters:

config (Dict[str, Any])

Multi-Material Models

class underworld3.MultiMaterialConstitutiveModel

Bases: Constitutive_Model

Multi-material constitutive model using level-set weighted flux averaging.

Mathematical Foundation:

\[\mathbf{f}_{\text{composite}}(\mathbf{x}) = \sum_{i=1}^{N} \phi_i(\mathbf{x}) \cdot \mathbf{f}_i(\mathbf{x})\]

Critical Architecture:

• Solver owns Unknowns (including \(D\mathbf{F}/Dt\) stress history)

• All constituent models share solver’s Unknowns

• Composite flux becomes stress history for all materials

__init__(unknowns, material_swarmVariable, constitutive_models, normalize_levelsets=False)

Parameters:

• unknowns (UnknownSet) – The solver’s authoritative unknowns (\(\mathbf{u}\), \(D\mathbf{F}/Dt\), \(D\mathbf{u}/Dt\)).

• material_swarmVariable (IndexSwarmVariable) – Index variable tracking material distribution on particles.

• constitutive_models (list of Constitutive_Model) – Pre-configured constitutive models for each material.

• normalize_levelsets (bool, optional) – Whether to normalize level-set functions to enforce partition of unity. Set to True if IndexSwarmVariable does not maintain partition of unity. Default: False (assumes IndexSwarmVariable maintains partition of unity)

property flux

Compute level-set weighted average of constituent model fluxes.

CRITICAL: This composite flux becomes the stress history that all constituent models (including elastic ones) will read via DFDt.psi_star[0] in the next time step.

property K

Effective stiffness using level-set weighted harmonic average.

For composite materials, harmonic averaging gives the correct effective stiffness for preconditioning: \(1/K_{eff} = \sum(\phi_i / K_i) / \sum(\phi_i)\)