Initial conditions

Contains the classes to define the initial conditions such as the geometry of the physical domain, the mesh refinement or an initial field with a gaussian distribution. It generates symbolic expressions of the coordinates and initial field distribution.

Domain

In pTatin3d, the physical domain where the simulation is performed is defined by the coordinate system showed in the figure below.

The following code describes the physical domain. While most of the usage of this class is for 3 dimensional domains, it can also be used for 2 dimensional and 1 dimensional domains.

Eulerian Domain (with free-surface)

class genepy.Domain(dim: int, minCoor: ndarray, maxCoor: ndarray, size: ndarray, coor=None)

class Domain(dim, minCoor, maxCoor, size, coor=None)

Class to build a physical domain. Compatible with 1D, 2D and 3D domains. Coordinates (symbolic and numeric) are instantiated by the class constructor using provided coordinates or creating new if not provided.

Parameters:

dim (int) – dimension of the domain (can be 1, 2 or 3)
minCoor (np.ndarray) – minimum coordinates of the domain
maxCoor (np.ndarray) – maximum coordinates of the domain
size (np.ndarray) – size of the domain (number of points in each direction)
coor (np.ndarray) – coordinates of the domain (numerical), optional

Example

dim      = 3
minCoord = np.array([0,-1,-0.5], dtype=np.float64)
maxCoord = np.array([1,0,0.5], dtype=np.float64)
size     = np.array([9,5,17], dtype=np.int32)

domain   = genepy.Domain(dim,minCoord,maxCoord,size)

Attributes

dim: int: Dimension of the domain

O: np.ndarray: Minimum coordinates of the domain, expected shape: (dim,) and dtype: np.float64

L: np.ndarray: Maximum coordinates of the domain, expected shape: (dim,) and dtype: np.float64

O_num: np.ndarray: Minimum coordinates of the domain, expected shape: (dim,) and dtype: np.float64

L_num: np.ndarray: Maximum coordinates of the domain, expected shape: (dim,) and dtype: np.float64

n: np.ndarray: Size of the domain (number of nodes in each direction), expected shape: (dim,) and dtype: np.int32

nv: int: Total number of nodes in the domain

num_coor: tuple: Numerical coordinates of the domain created by numerical_coordinates() . Tuple (X), (X,Y) or (X,Y,Z) (depending on the number of dimensions) with each direction being of type ndarray and shape X.shape = (*n).

sym_coor: tuple: Symbolic coordinates of the domain. Tuple ('x'), ('x','y') or ('x','y','z')

Methods

numerical_coordinates(self): Computes the numerical coordinates of the domain as a uniform grid. Compatible with 1D, 2D and 3D. Attach the coordinates to the attribute num_coor as a tuple: self.num_coor = (X,Y,Z) with each direction being of the shape X.shape = (self.n[0],self.n[1],self.n[2]). Tuples are immutable, so to modify the coordinates, convert them to a list first and restore them as tuple once done.

shape_coor(self): Reshapes the coordinates from (n[0],n[1],n[2]) to (nv,dim)

sprint_option(self, model_name: str)

Returns a string formatted for pTatin3d input file using PETSc options format.

Parameters:: model_name (str) – name of the model to include in the options
Returns:: string with the options

symbolic_coordinates(): Computes the symbolic coordinates of the domain. Works in 1D, 2D and 3D. Attach the coordinates to the attribute sym_coor as a tuple ("x", "y", "z")

ALE Domain

In case an ALE simulation is performed, the domain can be defined as a moving domain. Therefore, its minumum and maximum coordinates will change in time and expressions relying on the size of the domain need to consider this. To do so, the following class introduce symbolic representation of the domain with the symbols "Ox", "Oy", "Oz" for the origin of the domain and "Lx", "Ly", "Lz" for the size of the domain.

class genepy.DomainALE(dim: int, minCoor: ndarray, maxCoor: ndarray, size: ndarray, coor=None)

class DomainALE(dim, minCoor, maxCoor, size, coor=None)

Class to build a physical domain for ALE simulations. This class creates sympy symbols for the min and max coordinates of the domain to evaluate expressions in which the size of the domain is a variable (typically ALE simulations). Inherits from Domain class.

Parameters:

dim (int) – dimension of the domain (can be 1, 2 or 3)
minCoor (np.ndarray) – minimum coordinates of the domain
maxCoor (np.ndarray) – maximum coordinates of the domain
size (np.ndarray) – size of the domain (number of points in each direction)
coor (np.ndarray) – coordinates of the domain (numerical), optional

Attributes

O_num: np.ndarray: Symbols of the minimum coordinates of the domain ["Ox","Oy","Oz"]

L_num: np.ndarray: Symbols of the maximum coordinates of the domain ["Lx","Ly","Lz"]

Other attributes are inherited from the Domain class.

sprint_option(self, model_name: str)

Returns a string formatted for pTatin3d input file using PETSc options format.

Parameters:

model_name (str) – name of the model to include in the options
ale_rm_component (list) – list of components to remove from the mesh. Valid values are "x", "y" and "z"

Returns:

string with the options

Rotation

This module contains the class to perform rotations of single vectors, vector fields and referential in 2D and 3D.

class genepy.Rotation(dim, theta, axis=array([0, 1, 0]))

class Rotation(dim, theta, axis=np.array([0, 1, 0]))

Class to perform rotation of a referential in 2D or 3D.

Parameters:

dim (int) – dimension of the rotation (can be 2 or 3)
theta (float) – angle of rotation in radians
axis (np.ndarray) – axis of rotation (default is y-axis)

Example

dim   = 3                                   # dimension
theta = np.deg2rad(-90.0)                   # angle of rotation
axis  = np.array([0,1,0], dtype=np.float64) # axis of rotation
# Create class instance
Rotation = genepy.Rotation(dim,theta,axis)

Attributes

dim: int: Spatial dimension in which the rotation is performed

theta: float: Angle of rotation in radians

axis: np.ndarray: Axis of rotation, expected shape: (dim,) and dtype: np.float64

Methods

rotate_referential(self, coor, O, L, ccw=True)

Rotate the referential of the coordinates \(\mathbf{x}\) given the rotation matrix \(\boldsymbol R\). The referential is first translated to be centred on \(\mathbf{0}\), then rotated and finally translated back to its original position.

\[\begin{split}\mathbf x_T &= \mathbf x - \frac{1}{2}(\mathbf L + \mathbf O) \\ \mathbf x_{TR} &= \boldsymbol R \mathbf x_T \\ \mathbf x_R &= \mathbf x_{TR} + \frac{1}{2}(\mathbf L + \mathbf O)\end{split}\]

Parameters:

coor (np.ndarray) – coordinates to be rotated of the shape (npoints,dim)
O (np.ndarray) – origin of the referential of the shape (dim,)
L (np.ndarray) – maximum coordinates of the referential of the shape (dim,)
ccw (bool) – rotate counter-clockwise (default is True)

Returns:

coorR rotated coordinates of the shape (npoints,dim)

rotate_vector(self, R, u, ccw=True)

Rotate vector(s) \(\mathbf u\) given the rotation matrix \(\boldsymbol R\).

Warning

This is not a rotation of the vector field, but a rotation of the vectors themselves. To rotate the vector field, have a look at how it is done in evaluate_velocity_symbolic().

Parameters:

R (np.ndarray) – rotation matrix of the shape (dim,dim)
u (np.ndarray) – vector(s) to be rotated of the shape (npoints,dim)
ccw (bool) – rotate counter-clockwise (default is True)

Returns:

u_R rotated vector(s) of the shape (npoints,dim)

rotation_matrix(self)

Return the rotation matrix depending on the spatial dimension. calls rotation_matrix_2d() or rotation_matrix_3d().

Returns:: R rotation matrix in 2D or 3D of the shape (2,2) or (3,3)

rotation_matrix_2d(self)

computes the 2D rotation matrix given the angle theta.

Returns:: R rotation matrix in 2D of the shape (2,2)

rotation_matrix_3d(self)

computes the 3D rotation matrix given the angle theta and the axis of rotation.

Returns:: R rotation matrix in 3D of the shape (3,3)

Gaussian

This module contains the class to evaluate gaussian distributions of a field in 2D. It is generally used to define the initial strain distribution to place weak zones in the domain.

class genepy.Gaussian(Domain: Domain)

class Gaussian(Domain)

Parent class of all the Gaussian distributions.

Attributes:

gaussian_sym: sympy.Expr: Symbolic expression of the gaussian distribution

gaussian_num: np.ndarray: Numerical values of the gaussian distribution

class genepy.GaussianConstructor(Domain: Domain, A: float, a: float | list[float] | ndarray, expression: Expr | list[Expr] | ndarray)

class GaussianConstructor(Domain, A, a, expression)

Child class of Gaussian to build a function describing a gaussian distribution defined by:

\[g(\mathbf a, \mathbf x) = A \exp\left( - \mathbf a \cdot \mathbf x \cdot \mathbf x \right)\]

where \(\mathbf a\) is an array of coefficients such that \(\mathbf a = [a_1,a_2,...,a_n]\), \(\mathbf x\) is an array such that \(\mathbf x = [x_1,x_2,...,x_n]\) where \(x_i, \, i = 1,2,...,n\) can be single variables or mathematical functions and \(A\) is the amplitude of the gaussian.

This class is low level and should be called by the user to create its own gaussian distribution if not already available with the child classes.

Parameters:

Domain (Domain) – instance of the Domain class
A (float) – amplitude of the gaussian
a (float | list | numpy.ndarray) – gaussian extent coefficient(s). Can be a single float, a list or a numpy array.
expression (sympy.Expr | list | numpy.ndarray) – expression(s) of the gaussian. Can be a single expression, a list or a numpy array.

evaluate_gaussian(): Evaluate numerically the expression of the gaussian distribution. Uses the method sympy.lambdify() to convert the symbolic expression to a python callable.

gaussian(): Compute the gaussian distribution for the given expression(s). Make use of the rule \(\exp(a+b) = \exp(a)\exp(b)\) to build the final multidimensional expression. The method is called by the class constructor and does not require to be called by the user.

class genepy.Gaussian2D(Domain: Domain, A: float, a: float, b: float, x0: float, z0: float, Rotation: Rotation | None = None)

class Gaussian2D(Domain, A, a, b, x0, z0, Rotation=None)

Child class of GaussianConstructor to build a 2D gaussian distribution defined by:

\[g((a,b);(x,z)) = A \exp\left( -\left( a(x-x_0)^2 + b(z-z_0)^2 \right) \right)\]

where \(a\) and \(b\) are coefficients controlling the shape of the gaussian in the \(x\) and \(z\) directions respectively, \(x_0\) and \(z_0\) are the coordinates of the centre of the gaussian and \(A\) is the amplitude of the gaussian.

Parameters:

Domain (Domain) – instance of the Domain class
A (float) – amplitude of the gaussian
a (float) – gaussian extent coefficient in the \(x\) direction
b (float) – gaussian extent coefficient in the \(z\) direction
x0 (float) – \(x\) coordinate of the centre of the gaussian
z0 (float) – \(z\) coordinate of the centre of the gaussian
Rotation (Rotation) – instance of the Rotation class (optional) to rotate the centre of the gaussian

Example:

import numpy as np
import genepy as gp

# Domain
O = np.array([ 0.0, -250e3, 0.0 ], dtype=np.float64)
L = np.array([ 600e3, 0.0, 300e3 ], dtype=np.float64)
n = np.array([ 64, 32, 64 ], dtype=np.int32)
Domain = gp.Domain(3,O,L,n)

a = 0.5 * 6.0e-5**2
b = 0.5 * 6.0e-5**2
x0 = 0.5*Domain.L_num[0]
z0 = 0.5*Domain.L_num[2]

Gaussian = gp.Gaussian2D(Domain,1.0,a,b,x0,z0)
print(Gaussian) # prints the expression and the parameters of the gaussian

If one wants to numerically evaluate the gaussian distribution use:

Gaussian.evaluate_gaussian()

class genepy.Gaussian3D(Domain: Domain, A: float, a: float, b: float, c: float, x0: float, y0: float, z0: float, Rotation: Rotation | None = None)

class Gaussian3D(Domain, A, a, b, c, x0, y0, z0, Rotation=None)

Child class of GaussianConstructor to build a 3D gaussian distribution defined by:

\[g((a,b,c);(x,y,z)) = A \exp\left( -\left( a(x-x_0)^2 + b(y-y_0)^2 + c(z-z_0)^2 \right) \right)\]

where \(a\), \(b\) and \(c\) are coefficients controlling the shape of the gaussian in the \(x\), \(y\) and \(z\) directions respectively, \(x_0\), \(y_0\) and \(z_0\) are the coordinates of the centre of the gaussian and \(A\) is the amplitude of the gaussian.

Parameters:

Domain (Domain) – instance of the Domain class
A (float) – amplitude of the gaussian
a (float) – gaussian extent coefficient in the \(x\) direction
b (float) – gaussian extent coefficient in the \(y\) direction
c (float) – gaussian extent coefficient in the \(z\) direction
x0 (float) – \(x\) coordinate of the centre of the gaussian
y0 (float) – \(y\) coordinate of the centre of the gaussian
z0 (float) – \(z\) coordinate of the centre of the gaussian
Rotation (Rotation) – instance of the Rotation class (optional) to rotate the centre of the gaussian

Example:

import numpy as np
import genepy as gp

# Domain
O = np.array([ 0.0, -250e3, 0.0 ], dtype=np.float64)
L = np.array([ 600e3, 0.0, 300e3 ], dtype=np.float64)
n = np.array([ 64, 32, 64 ], dtype=np.int32)
Domain = gp.Domain(3,O,L,n)

a = 0.5 * 6.0e-5**2
b = 0.5 * 6.0e-5**2
c = 0.5 * 6.0e-5**2
x0 = 0.5*Domain.L_num[0]
y0 = 0.5*Domain.L_num[1]
z0 = 0.5*Domain.L_num[2]

Gaussian = gp.Gaussian3D(Domain,1.0,a,b,c,x0,y0,z0)
print(Gaussian) # prints the expression and the parameters of the gaussian

If one wants to numerically evaluate the gaussian distribution use:

Gaussian.evaluate_gaussian()

class genepy.GaussianPlane(Domain: Domain, A: float, a: float, coeff: ndarray)

class GaussianPlane(Domain, A, a, plane_coeff)

Child class of GaussianConstructor to build a 3D gaussian distribution around a plane defined by:

\[g( a, D(\mathbf x) ) = A \exp\left( - a D(\mathbf x)^2 \right)\]

where \(a\) is the coefficient controlling the shape of the gaussian around the plane and

\[D(\mathbf x) = \frac{n_0 x + n_1 y + n_2 z + d}{\sqrt{n_0^2 + n_1^2 + n_2^2}} = \frac{\mathbf n \cdot \mathbf x + d}{|| \mathbf n ||} \]

is the equation describing the distance between a point of coordinates \(\mathbf x\) and the plane defined by the normal vector \(\mathbf n = [n_0, n_1, n_2]\) and the parameter \(d\).

Parameters:

Domain (Domain) – instance of the Domain class
A (float) – amplitude of the gaussian
a (float) – gaussian extent coefficient
plane_coeff (np.ndarray) – plane coefficients: numpy.array([n_0, n_1, n_2, d]) where \(n_0 x + n_1 y + n_2 z + d = 0\)

Example:

import numpy as np
import genepy as gp

# Domain
O = np.array([ 0.0, -250e3, 0.0 ], dtype=np.float64)
L = np.array([ 600e3, 0.0, 300e3 ], dtype=np.float64)
n = np.array([ 64, 32, 64 ], dtype=np.int32)
Domain = gp.Domain(3,O,L,n)

# gaussian extent coefficient
a = 0.5 * 6.0e-5**2

# points defining the plane
pt_A = np.array([200.0, 0.0, 0.0], dtype=np.float64) * 1e3
pt_B = np.array([200.0, 0.0, 300.0], dtype=np.float64) * 1e3
pt_C = np.array([600.0, -100.0, 0.0], dtype=np.float64) * 1e3

# normal vector to the plane
normal = np.cross(pt_B - pt_A, pt_C - pt_A)
# d parameter
d = -np.dot(normal,pt_A)

plane_coeff = np.array([normal[0], normal[1], normal[2], d], dtype=np.float64)

Gaussian = gp.GaussianPlane(Domain,1.0,a,plane_coeff)

class genepy.GaussianCircle(Domain: Domain, A: float, a: float, xc: float, zc: float, r: float, Rotation: Rotation | None = None)

class GaussianCircle(Domain, A, a, xc, zc, r, Rotation=None)

Child class of GaussianConstructor to build a 2D gaussian distribution around a circle defined by:

\[g( a, D(\mathbf x) ) = A \exp\left( - a D(\mathbf x)^2 \right)\]

where \(a\) is the coefficient controlling the shape of the gaussian around the circle and

\[D(\mathbf x) = \sqrt{(x-x_c)^2 + (z-z_c)^2} - r\]

is the equation describing the distance between a point of coordinates \(\mathbf x\) and the circle defined by the centre \((x_c,z_c)\) and the radius \(r\).

Parameters:

Domain (Domain) – instance of the Domain class
A (float) – amplitude of the gaussian
a (float) – gaussian extent coefficient
xc (float) – \(x\) coordinate of the centre of the circle
zc (float) – \(z\) coordinate of the centre of the circle
r (float) – radius of the circle
Rotation (Rotation) – instance of the Rotation class (optional) to rotate the centre of the circle

Example:

import numpy as np
import genepy as gp

# Domain
O = np.array([ 0.0, -250e3, 0.0 ], dtype=np.float64)
L = np.array([ 600e3, 0.0, 300e3 ], dtype=np.float64)
n = np.array([ 64, 32, 64 ], dtype=np.int32)
Domain = gp.Domain(3,O,L,n)

# gaussian extent coefficient
coeff = 0.5*6.0e-5**2
# centre of the circle
xc = 0.5*Domain.L_num[0]
zc = 0.5*Domain.L_num[2]
# radius of the circle
r  = 0.25*Domain.L_num[2]

Gaussian = gp.GaussianCircle(Domain,1.0,coeff,xc,zc,r)

class genepy.GaussiansOptions(gaussians: list[Gaussian], blocksize: int = 10)

class GaussiansOptions(gaussians, blocksize=10)

Class to generate the options for the input file of pTatin3d. The class takes a list of gaussians and can sum them in blocks of size blocksize to reduce the number of options. The class instance can be used to generate the options for the gaussian distributions. If the gaussians are used to set an initial plastic strain, it should be passed to the class InitialPlasticStrain.

Parameters:

gaussians (list) – list of Gaussian instances
blocksize (int) – (Optional) size of the block to sum the gaussians.

Example:

import numpy as np
import genepy as gp

# Domain
O = np.array([ 0.0, -250e3, 0.0 ], dtype=np.float64)
L = np.array([ 600e3, 0.0, 300e3 ], dtype=np.float64)
n = np.array([ 64, 32, 64 ], dtype=np.int32)
Domain = gp.Domain(3,O,L,n)

# gaussian distribution
coeff = 0.5*6.0e-5**2
x0 = [0.25 * Domain.L_num[0], 0.75 * Domain.L_num[0]]
z0 = [0.25 * Domain.L_num[2], 0.75 * Domain.L_num[2]]
gaussians = []
for i in range(2):
  gaussians.append(gp.Gaussian2D(Domain,1.0,coeff,coeff,x0[i],z0[i]))

Gopt = gp.GaussiansOptions(gaussians,blocksize=5)

Pass the instance Gopts to the class InitialPlasticStrain:

IPS = gp.InitialPlasticStrain(Gopt)

sum_gaussians(self, blocksize)

Sum the gaussians in blocks of size blocksize. Can be utilized to reduce the amount of options in the input file for pTatin3d.

Parameters:: blocksize (int) – size of the block to sum the gaussians.

Plastic strain

This module contains the class to generate options for the initial plastic strain.

class genepy.InitialPlasticStrain(strain_expressions: Gaussian)

class InitialPlasticStrain(strain_expressions)

Class to generate options for the initial plastic strain.

Parameters:: strain_expressions – instance of the genepy.Gaussian class describing the initial plastic strain

Methods:

sprint_option(self, model_name: str)

Return a string formatted for pTatin3d input file using PETSc options format.

Parameters:: model_name (str) – name of the model
Returns:: string with the options

Heat source

This module contains the class to generate options for the initial heat source when set to genepy.EnergySourceMaterialPointValue.

class genepy.InitialHeatSource(hs_expression)

class InitialHeatSource(hs_expression)

Class to generate options for the initial heat source when using the class genepy.EnergySourceMaterialPointValue. The heat source should be given as an expression or an instance of the genepy.Gaussian class. If the expression is a constant value, prefer to use the genepy.EnergySourceConstant class.

Example:

In the following example we assume that the Domain class is already instantiated.

import numpy as np
import genepy as gp

# shape of the gaussian
coeff = 0.5 * 6.0e-5**2
a = np.array([coeff],dtype=np.float64)
b = np.zeros(shape=(1),dtype=np.float64)
c = np.array([coeff],dtype=np.float64)

# position of the centre of the gaussian
x0 = np.array([0.5 * (Domain.L_num[0] - Domain.O_num[0])], dtype=np.float64)
z0 = np.array([0.5 * (Domain.L_num[2] - Domain.O_num[2])], dtype=np.float64)

# amplitude of the gaussian (heat source)
A = np.array([1.5e-6],dtype=np.float64)

# Create gaussian object
Gaussian = gp.Gaussian(Domain,1,A,a,b,c,x0,z0)
Gaussian.evaluate_gaussians()

# Create initial heat source
Hini = gp.InitialHeatSource(Gaussian)

param hs_expression:: heat source expression (str or sympy expression) for a single expression or an instance of the genepy.Gaussian class

Methods:

sprint_option(self, model_name: str)

Return a string formatted for pTatin3d input file using PETSc options format.

Parameters:: model_name (str) – name of the model
Returns:: string with the options

sprint_option_gaussian(self, model_name: str)

Return a string formatted for pTatin3d input file using PETSc options format.

Parameters:: model_name (str) – name of the model
Returns:: string with the options

ICs pTatin3d options generation

This module contains the class to generate the options for the initial conditions of a 3D model running GENE3D in pTatin3d.

class genepy.InitialConditions(Domain: Domain, velocity, model_name: str = 'model_GENE3D', **kwargs)

class InitialConditions(Domain, velocity, model_name='model_GENE3D', **kwargs)

Abstract class to generate options for pTatin3d model initial conditions.

Parameters:

Domain (Domain) – instance of the Domain class
velocity – velocity function (str or sympy expression)
model_name (str) – name of the model (default: model_GENE3D)
kwargs – keyword arguments

Attributes

model_name: str: Name of the model to include in the options

Domain: Domain: Instance of the Domain class

u: velocity: Velocity function (str or sympy expression)

kwargs: dict: Keyword arguments

possible_kwargs: list

Possible keyword arguments

mesh_refinement: instance of the genepy.MeshRefinement class.

initial_strain: instance of the genepy.InitialPlasticStrain class

initial_heat_source: instance of the genepy.InitialHeatSource class

Methods:

sprint_initial_velocity(self)

Returns a string formatted for pTatin3d input file using PETSc options format for the initial velocity field.

Returns:: string formatted for pTatin3d input file
Return type:: str

sprint_option(self)

Returns a string formatted for pTatin3d input file using PETSc options format for all the initial conditions.

Returns:: string formatted for pTatin3d input file
Return type:: str

Initial conditions

Domain

Eulerian Domain (with free-surface)

Example

Attributes

Methods

ALE Domain

Attributes

Mesh refinement

Attributes

Methods

Rotation

Example

Attributes

Methods

Gaussian

Plastic strain

Methods:

Heat source

Example:

Methods:

ICs pTatin3d options generation

Attributes

Methods: