Usage

Usage#

This section describes how to configure and run a Z3ST simulation using the reference example case, and how to execute the available verification and non-regression tests.

Input files#

A minimal demonstration case is provided in cases/00_example. It illustrates the complete workflow of a thermo-mechanical simulation: - YAML-based configuration input; - mesh generation and region tagging; - coupled thermal and mechanical solver execution.

To run the example:

cd cases/00_example
python3 -m z3st

Optional flags:

  • --mesh_plot — displays the generated mesh before solving

Example folder structure:

00_example/
├── input.yaml
├── geometry.yaml
├── boundary_conditions.yaml
└── mesh.msh

Each file defines one aspect of the model setup:

input.yaml#

This file controls the coupling strategy, solver tolerance, relaxation factors, and physical models (thermal/mechanical). The staggered scheme alternates between thermal and mechanical solves until both reach convergence.

 mesh_path: mesh.msh
 geometry_path: geometry.yaml
 boundary_conditions_path: boundary_conditions.yaml

 materials:
   steel: ../../materials/steel.yaml

regime: 2D

 solver_settings:
   coupling: staggered
   max_iters: 100
   relax_T: 0.9
   relax_u: 0.7
   relax_adaptive: true
   relax_growth: 1.2
   relax_shrink: 0.8
   relax_min: 0.05
   relax_max: 0.95

 models:
   thermal: true
   mechanical: true
   damage: true
   cluster_dynamics: false

 mechanical:
   solver: linear
   linear_solver: iterative_amg
   rtol: 1.0e-6
   stag_tol: 1.0e-6
   convergence: rel_norm

 thermal:
   solver: linear
   linear_solver: iterative_amg
   rtol: 1.0e-6
   stag_tol: 1.0e-6
   convergence: rel_norm

 damage:
   type: AT2 # AT1 | AT2
   solver: linear
   linear_solver: iterative_hypre
   rtol: 1.0e-6
   stag_tol: 1.0e-6
   convergence: rel_norm
   lc: 0.002 # (m) characteristic length

 lhr:
 - 0
 time:
 - 0
 n_steps: 1

geometry.yaml#

Defines the domain geometry, dimensions, and tagged boundaries.

name: box
geometry_type: rect

Lx: 0.100   # length in x (m)
Ly: 2.000   # length in y (m)
Lz: 2.000   # length in z (m)

labels:
  zmin: 1
  zmax: 2
  ymin: 3
  xmax: 4
  ymax: 5
  xmin: 6
  steel: 7

Z3ST automatically interprets these labels as physical regions and surfaces. Each label is used later to apply boundary conditions or assign material subdomains. Also, each label corresponds to a Physical Group defined in the mesh (either a surface or a volume). These integer IDs are essential for boundary condition assignment and material region identification.

Mesh labeling and physical groups#

Z3ST uses Gmsh to define and export all geometric entities. The mapping between the textual labels in geometry.yaml and the numeric tags in the mesh file mesh.msh is handled through Physical Groups.

Example from mesh.msh, created from mesh.geo:

$MeshFormat
4.1 0 8
$EndMeshFormat
$PhysicalNames
7
2 1 "zmin"
2 2 "ymin"
2 3 "xmax"
2 4 "ymax"
2 5 "xmin"
2 6 "zmax"
3 7 "steel"

Here: - the first number (2) indicates a surface (2D entity), - the second number is the ID used in geometry.yaml, - and the quoted string (e.g. “zmin”) is the name of the region.

The 3D entity labeled “steel” represents the solid volume domain. When the .msh file is read, Z3ST automatically associates each boundary or volume tag to its corresponding label in geometry.yaml.

boundary_conditions.yaml#

This file specifies the model boundary conditions applied during the simulation. The available models are thermal and mechanical. Each boundary condition is assigned to a material region (e.g. steel) and applied on a named region defined in mesh.msh and geometry.yaml.

An example is given here below:

thermal:
  steel:
  - type: Dirichlet
    region: xmin
    temperature: 490.0   # (K)

mechanical:
  steel:
  - type: Clamp_x
    region: xmin

  - type: Clamp_y
    region: ymin

  - type: Clamp_z
    region: zmin

In this configuration: - the thermal field is fixed at 490 K on the xmin face; - the mechanical problem applies a tri-directional clamping (fixed displacements in X, Y, and Z) on the corresponding faces.

This setup results in a steady-state thermo-mechanical equilibrium problem on a 3D rectangular domain.

Thermal boundary conditions#

Dirichlet#

  • Enforces a fixed temperature (K) on a boundary region.

  • Example:

    - type: Dirichlet
  region: xmin
  temperature: 490.0

  • Mathematical form: T = T_0 on \Gamma_D

  • Used to impose constant temperature fields.

Neumann#

  • Applies a constant heat flux (\mathrm{W\,m^{-2}}).

  • Example:

    - type: Neumann
  region: zmax
  flux: 5000.0

  • Mathematical form: -k \nabla T \cdot \mathbf{n} = q_0 \text{ on } \Gamma_N

  • Positive flux, exiting from the region. Negative flux, entering in the region.

  • Used for convection or heat generation boundaries.

Mechanical boundary conditions#

Dirichlet#

  • Imposes a fixed displacement \mathbf{u} = (u_x, u_y, u_z) (m).

  • Example:

    - type: Dirichlet
  region: outer
  displacement: [0.0, 0.0, 0.0]

  • Mathematical form: \mathbf{u} = \mathbf{u}_0 \text{ on } \Gamma_D

Neumann#

  • Imposes a surface traction or pressure load \mathbf{t}_0 (\mathrm{N\,m^{-2}}) on the specified boundary.

  • Example:

    - type: Neumann
  region: inner
  traction: 1.0e6

  • Mathematical form: \boldsymbol{\sigma} \cdot \mathbf{n} = \mathbf{t}_0 \text{ on } \Gamma_N

  • A scalar value must be provided, it is interpreted as a pressure acting normal to the surface, i.e. \mathbf{t}_0 = p\, \mathbf{n}.

Clamp#

  • Constrains displacement in a single direction only, on the assigned region.

    Clamp_x

    • Constrains u_x = 0 on the assigned region.

    Clamp_y

    • Constrains u_y = 0 on the assigned region.

    Clamp_z

    • Constrains u_y = 0 on the assigned region.

  • Example

    - type: Clamp_x
  region: xmin

- type: Clamp_y
  region: ymin

- type: Clamp_z
  region: zmin

    Note: The combined effect of the tri-directional clamping above is a single fixed point, preventing rigid-body motion and rotation of the domain.

Slip#

  • Enforces a slip condition by constraining two displacement components while leaving the normal component free.

  • Used to prevent rigid-body motion while allowing tangential sliding along a boundary.

    Slip_x

    • Constrains u_y = 0 and u_z = 0

    • Allows displacement in the x direction

    Slip_y

    • Constrains u_x = 0 and u_z = 0

    • Allows displacement in the y direction

    Slip_z

    • Constrains u_x = 0 and u_y = 0

    • Allows displacement in the z direction

  • Example

    - type: Slip_x
  region: xmin

- type: Slip_y
  region: ymin

- type: Slip_z
  region: zmin

The slip boundary condition blocks motion tangential to the boundary while allowing displacement along the normal direction. It is typically used to remove rigid-body modes without fully clamping the structure.

Damage boundary conditions#

Dirichlet#

  • Imposes a fixed damage value D \in [0, 1].

  • Used to prescribe initial cracks or fully damaged regions.

  • Example:

    - type: Dirichlet
  region: crack
  value: 1.0

Notes:

  • Each boundary condition is applied to a region defined in geometry.yaml and associated with the corresponding physical tag in the mesh file (.msh).

Verification cases#

The cases/ directory contains a collection of verification and benchmark problems used to validate the numerical formulation and solver performance.

Each case reproduces a reference simulation and compares the computed results with analytical or previously validated data.

To run a verification case:

cd cases/1_thin_thermal_slab
./Allrun

Each verification folder contains: - Input and configuration files; - Reference output fields for comparison; - (Optional) post-processing or plotting scripts.

Non-Regression tests#

To maintain numerical consistency across code updates, Z3ST provides an automated non-regression test suite.

Run all tests with:

cd cases
./non-regression.sh

This script executes verification tests, compares each new result with its reference, and logs the outcome to non-regression_summary.txt.

Note

The non-regression workflow ensures that modifications to Z3ST preserve validated physics and solver consistency.

Contents