medypt.utils

Convenient tools for the package.

Attributes

SQRT_PI

Square root of pi.

Classes

L2RError

Class for computing L2 relative error between two sets of DOLFINx Functions.

Projector

Projector for a given function.

TMat

Assemble and store temperature matrix for a given function space.

Functions

create_mesh(→ dolfinx.io.gmsh.MeshData)

Create a DOLFINx mesh from a Gmsh model and output to file.

f1_2(→ Any)

Approximate analytic expression for Fermi-Dirac integral of order 1/2.

d_density(→ Any)

Neutral or ionized defect density function.

ufl_mat2voigt4strain(→ ufl.core.expr.Expr)

Convert a UFL strain matrix to Voigt notation (a UFL vector).

young_poisson2stiffness(→ list[list[float]])

Convert Young's modulus and Poisson's ratio to stiffness tensor in Voigt notation.

ufl_tr_voigt(→ ufl.core.expr.Expr)

Calculate the trace of a UFL matrix in Voigt notation.

gen_therm_noise(Tmat, dissipUmat, rng, noise)

Generate thermal noise based on the fluctuation-dissipation theorem.

Module Contents

medypt.utils.SQRT_PI = 1.77245385091

Square root of pi.

medypt.utils.create_mesh(comm: mpi4py.MPI.Comm, model: gmsh.model | str, out_file: str | None = None, **kwargs: Any) → dolfinx.io.gmsh.MeshData

Create a DOLFINx mesh from a Gmsh model and output to file.

Parameters:

  • comm (MPI.Comm) – MPI communicator top create the mesh on.

  • model (gmsh.model | str) – Gmsh model or name of a file containing the mesh (.msh or .xdmf). Reading from .xdmf file is the most efficient and is recommended for large mesh.

  • out_file (str | None) – .xdmf file name for writing. Default to None for not writing to .xdmf file.

  • kwargs (dict[str, Any]) –

    Additional keyword arguments:

    • mesh_dim (int): Geometric dimension of mesh of the gmsh model or .msh file. Required if model is a gmsh.model or a .msh file.

    • rank (int): Rank of the MPI process used for generating from gmsh model or reading from .msh files. Required if model is a gmsh.model or a .msh file.

    • mesh_name (str): Name (identifier) of the mesh to read from the input .xdmf file and to add to the output file. Required if model is a .xdmf file.

    • mode (str): Mode for writing mesh to .xdmf file. 'w' (write) or 'a' (append). Required if out_file is not None.

Returns:

The created mesh data.

Return type:

gmshio.MeshData

Attention

This function is copied from https://docs.fenicsproject.org/dolfinx/main/python/demos/demo_gmsh.html and modified.

medypt.utils.f1_2(x: Any, exp: collections.abc.Callable = ufl.exp) → Any

Approximate analytic expression for Fermi-Dirac integral of order 1/2.

Parameters:

  • x (Any) – Input value.

  • exp (Callable) – Exponential function to use. Default to UFL exponential.

Returns:

Approximated Fermi-Dirac integral of order 1/2 at x.

Return type:

Any

medypt.utils.d_density(x1: Any, x2: Any, Nmax: float, exp: collections.abc.Callable = ufl.exp) → Any

Neutral or ionized defect density function.

Parameters:

  • x1 (Any) – Reduced chemical potential of neutral or ionized defects.

  • x2 (Any) – Reduced chemical potential of ionized or neutral defects.

  • Nmax (float) – Maximum defect density.

  • exp (Callable) – Exponential function to use. Default to UFL exponential.

Returns:

Defect density.

Return type:

Any

Note

Pass respectively reduced chemical potentials of neutral and ionized defects to x1 and x2 to get neutral defect density, and vice versa to get ionized defect density.

medypt.utils.ufl_mat2voigt4strain(eps: ufl.core.expr.Expr) → ufl.core.expr.Expr

Convert a UFL strain matrix to Voigt notation (a UFL vector).

Parameters:

eps (Expr) – Input strain matrix.

Returns:

Strain in Voigt notation.

Return type:

Expr

medypt.utils.young_poisson2stiffness(E: float, nu: float, dim: int) → list[list[float]]

Convert Young’s modulus and Poisson’s ratio to stiffness tensor in Voigt notation.

Parameters:

  • E (float) – Young’s modulus.

  • nu (float) – Poisson’s ratio.

  • dim (int) – Dimension (1, 2, or 3).

Returns:

Stiffness tensor in Voigt notation.

Return type:

list[list[float]]

medypt.utils.ufl_tr_voigt(a: ufl.core.expr.Expr) → ufl.core.expr.Expr

Calculate the trace of a UFL matrix in Voigt notation.

Parameters:

a (Expr) – Input matrix in Voigt notation (a vector).

Returns:

Trace of the input matrix.

Return type:

Expr

class medypt.utils.L2RError(ref: dict[str, dolfinx.fem.Function], u: dict[str, dolfinx.fem.Function], jit_options: dict | None = None, form_compiler_options: dict | None = None, metadata: dict | None = None)

Class for computing L2 relative error between two sets of DOLFINx Functions.

setup(ref: dict[str, dolfinx.fem.Function], u: dict[str, dolfinx.fem.Function], jit_options: dict | None = None, form_compiler_options: dict | None = None, metadata: dict | None = None)

Compile forms for computing L2 relative error.

Parameters:

  • ref (dict[str, fem.Function]) – Reference DOLFINx Functions.

  • u (dict[str, fem.Function]) – DOLFINx Functions to compare against the reference. Only takes into account the items with the same keys as in ref.

  • jit_options (Optional[dict]) – Options to pass to just in time compiler

  • form_compiler_options (Optional[dict]) – Options to pass to the form compiler

  • metadata (Optional[dict]) – Data to pass to the integration measure

compute(eps: float = 1e-10) → float

Compute the L2 relative error between the two attached sets of DOLFINx Functions.

Parameters:

eps (float) – Small value to avoid division by zero.

Returns:

L2 relative error.

Return type:

float

class medypt.utils.Projector(space: dolfinx.fem.FunctionSpace, petsc_options: dict | None = None, jit_options: dict | None = None, form_compiler_options: dict | None = None, metadata: dict | None = None)

Projector for a given function.

Solves Ax=b, where

u, v = ufl.TrialFunction(Space), ufl.TestFunction(space)
dx = ufl.Measure("dx", metadata=metadata)
A = inner(u, v) * dx
b = inner(function, v) * dx(metadata=metadata)
Parameters:

  • function – UFL expression of function to project

  • space – Space to project function into

  • petsc_options – Options to pass to PETSc

  • jit_options – Options to pass to just in time compiler

  • form_compiler_options – Options to pass to the form compiler

  • metadata – Data to pass to the integration measure

Attention

This class is copied from http://jsdokken.com/FEniCS23-tutorial/src/approximations.html

reassemble_lhs()
assemble_rhs(h: ufl.core.expr.Expr)

Assemble the right hand side of the problem

project(h: ufl.core.expr.Expr) → dolfinx.fem.Function

Compute projection using a PETSc KSP solver

__del__()
class medypt.utils.TMat

Assemble and store temperature matrix for a given function space.

It provides Cholesky decomposition and lumped temperature/mass matrix for calculating properly correlated noise out of an uncorrelated noise. The temperature matrix T_ij is defined as: ∫ T(x) v_i(x) v_j(x) dx, where T(x) is the temperature field and v_i(x), v_j(x) are the basis functions of the function space.

Variables:

  • lumpedT (PETSc.Vec) – The lumped temperature matrix (a vector).

  • lumpedM (PETSc.Vec) – The lumped mass matrix (a vector).

lumpedT: petsc4py.PETSc.Vec
lumpedM: petsc4py.PETSc.Vec
setT(T: dolfinx.fem.Function | tuple[ufl.core.terminal.FormArgument | float, dolfinx.fem.FunctionSpace], jit_options: dict | None = None, form_compiler_options: dict | None = None, metadata: dict | None = None)

Attach the temperature field and assemble all the internal data for the first time.

Parameters:

  • T (fem.Function | tuple[FormArgument | float, fem.FunctionSpace]) – Temperature field, represented either as a dolfinx.fem.Function or a tuple (T_, V), where T_ is a UFL expression or a float (for constant temperature) and V is its (collapsed) function space.

  • jit_options (Optional[dict]) – Options to pass to just-in-time compiler

  • form_compiler_options (Optional[dict]) – Options to pass to the form compiler

  • metadata (Optional[dict]) – Data to pass to the integration measure

factorT(type: str)

Assemble and factor the temperature matrix for the attached temperature field with the current value.

Parameters:

type (str) – Type of factorization. E.g., “cholesky”.

solve_backwardT(b: petsc4py.PETSc.Vec, x: petsc4py.PETSc.Vec)

Given the factored temperature matrix T = L U, solve the system U x = b.

Parameters:

  • b (PETSc.Vec) – Right-hand side vector.

  • x (PETSc.Vec) – Solution vector.

Caution

Currently, parallel backward solving for Cholesky factorization through PETSc is only supported by MKL CPARDISO solver.

mat_solveM(B: petsc4py.PETSc.Mat, X: petsc4py.PETSc.Mat)

Solve the system M X = B, where M is the mass matrix.

Parameters:

  • B (PETSc.Mat) – Right-hand side matrix.

  • X (PETSc.Mat) – Solution matrix.

assemble_lumpedT()

Assemble the lumped temperature matrix lumpedT for the attached temperature field with the current value.

Hint

No need to call this function after setT() unless the temperature field has changed.

__del__()
medypt.utils.gen_therm_noise(Tmat: TMat, dissipUmat: Any, rng: numpy.random.Generator, noise: dolfinx.fem.Function)

Generate thermal noise based on the fluctuation-dissipation theorem.

It is calculated as: M w = √2 A η L^T, where M is the mass matrix and A, L are the Cholesky factors of the temperature and dissipation matrices, respectively. η is a matrix of shape (Tmat_dim, dissipUmat_dim) containing uncorrelated standard normal random numbers, and w of the same shape is the DOFs of the proper thermal noise function.

Attention

Currently only use method of lumped temperature and mass matrices for efficiency.

Parameters:

  • Tmat (TMat) – Assembled temperature matrix.

  • dissipUmat (Any) – Upper-triangular Cholesky factor of the dissipation matrix. Can be a scalar for isotropic dissipation.

  • rng (Generator) – Numpy random number generator.

  • noise (fem.Function) – Output noise field. It is the genuine thermal noise multiplied by √dt so that it is independent of dt, where dt is the time step size.