Model documentation

Model Class

class peripy.model.Model(mesh_file, integrator, horizon, critical_stretch, bond_stiffness, transfinite=0, volume_total=None, write_path=None, connectivity=None, family=None, volume=None, initial_crack=None, dimensions=2, is_density=None, is_bond_type=None, is_displacement_boundary=None, is_force_boundary=None, is_tip=None, density=None, bond_types=None, stiffness_corrections=None, surface_correction=None, volume_correction=None, micromodulus_function=None, node_radius=None)

A peridynamics model.

This class allows users to define a bond-based peridynamics model for composite materials with non-linear micromodulus functions and stiffness correction factors. The model is defined by parameters and a set of initial conditions (coordinates, connectivity and optionally bond_types and stiffness_corrections). For this an peripy.integrators.Integrator is required, and optionally functions implementing the boundarys. The Model.simulate() method can be used to conduct a peridynamics simulation.

For learning how to use PeriPy, see complete documentation, and for getting started, please see quickstart.

Create a Model object.

Note that nnodes is the number of nodes in the mesh. nbond_types is the number of different bonds, i.e. the number of damage models (e.g. there might be a damage model for each material and interface in a composite). nregimes is the number of linear splines that define the damage model (e.g. An n-linear damage model has nregimes = n. The bond-based prototype microelastic brittle (PMB) model has nregimes = 1). Note that nregimes and nbond_types are defined by the size of the critical_stretch and bond_stiffness positional arguments.

Parameters:
  • mesh_file (str) – Path of the mesh file defining the systems nodes and connectivity.
  • integrator (peripy.integrators.Integrator) – The integrator to use, see peripy.integrators for options.
  • horizon (float) – The horizon radius. Nodes within horizon of another interact with that node and are said to be within its neighbourhood.
  • critical_stretch (numpy.ndarray or float) – An (nregimes, nbond_types) array of critical stretch values, each corresponding to a bond type and a regime, or a float value of the critical stretch of the Peridynamic bond-based prototype microelastic brittle (PMB) model.
  • bond_stiffness (numpy.ndarray or float) – An (nregimes, nbond_types) array of bond stiffness values, each corresponding to a bond type and a regime, or a float value of the bond stiffness the Peridynamic bond-based prototype microelastic brittle (PMB) model.
  • transfinite (bool) – Set to 1 for Cartesian cubic (tensor grid) mesh. Set to 0 for a tetrahedral mesh (default). If set to 1, the volumes of the nodes are approximated as the average volume of nodes on a cuboidal tensor-grid mesh.
  • volume_total (float) – Total volume of the mesh. Must be provided if transfinite mode (transfinite=1) is used.
  • write_path (path-like or str) – The path where the model arrays, (volume, family, connectivity, stiffness_corrections, bond_types) should be written to file to avoid doing time expensive calculations each time that the model is initiated.
  • connectivity (tuple(numpy.ndarray, numpy.ndarray)) – The initial connectivity for the model. A tuple of a neighbour list and the number of neighbours for each node. If None the connectivity at the time of construction of the Model object will be used. Default None.
  • family (numpy.ndarray) – The family array. An array of the intial number of nodes within the horizon of each node. If None the family at the time of construction of the Model object will be used. Default None.
  • volume (numpy.ndarray) – Array of volumes for each node. If None the volume at the time of construction of the Model object will be used. Default None.
  • initial_crack (list(tuple(int, int)) or function) – The initial crack of the system. The argument may be a list of tuples where each tuple is a pair of integers representing nodes between which to create a crack. Alternatively, the arugment may be a function which takes the (nnodes, 3) numpy.ndarray of coordinates as an argument, and returns a list of tuples defining the initial crack. Default is None
  • dimensions (int) – The dimensionality of the model. The default is 2.
  • is_density (function) – A function that returns a float of the material density, given a node coordinate as input.
  • is_bond_type (function) – A function that returns an integer value (a flag) of the bond_type, given two node coordinates as input.
  • is_displacement_boundary (function) – A function to determine if a node is on the boundary for a displacement boundary condition, and if it is, which direction and magnitude the boundary conditions are applied (positive or negative cartesian direction). It has the form is_displacement_boundary(numpy.ndarray). The argument is the initial coordinates of a node being simulated. is_displacement_boundary returns a (3) list of the boundary types in each cartesian direction. A boundary type with an int value of None if the node is not on a displacement controlled boundary, a value of 1 if is is on a boundary and displaced in the positive cartesian direction, a value of -1 if it is on the boundary and displaced in the negative direction, and a value of 0 if it is clamped.
  • is_force_boundary (function) – As ‘is_displacement_boundary’ but applying to force boundary conditions as opposed to displacement boundary conditions.
  • is_tip (function) – A function to determine if a node is to be measured for its state variables or reaction force over time, and if it is, which cartesian direction the measurements are made. It has the form is_tip(numpy.ndarray). The argument is the initial coordinates of a node being simulated. is_tip returns a (3) list of the tip types in each cartesian direction: A value of None if the node is not on the tip, and a value of not None (e.g. a string or an int) if it is on the tip and to be measured.
  • density (numpy.ndarray) – An (nnodes, ) array of node density values, each corresponding to a material
  • bond_types (numpy.ndarray) – The bond_types for the model. If None the bond_types at the time of construction of the Model object will be used. Default None.
  • stiffness_corrections (numpy.ndarray) – The stiffness_corrections for the model. If None the stiffness_corrections at the time of construction of the Model object will be used. If not None then these stiffness corrections will be used, overiding the positional arguments surface_correction, volume_correction and micromodulus_function. Default None.
  • surface_correction (int) – A flag variable only denoting the algorithm for correcting the peridynamic surface softening effect. Le and Bobaru [Q. V. Le, F. Bobaru, Surface corrections for peridynamic models in elasticity and fracture, Computational Mechanics 61 (2018) 499–518. URL: https://link.springer.com/article/10.1007/s00466-017-1469-1.] provide a detailed comparison of the most common surface correction techniques. The ‘volume method’ proposed by Bobaru et al. [Chapter 2 in Bobaru F, Foster JT, Geubelle PH, Silling SA, Handbook of peridynamic modeling, (2017) (p51 – 52)] is used when surface_correction= 1 or 0. Set to 1: Surface corrections are calculated more accurately using actual nodal volumes. Set to 0: Surface corrections are calculated using an average nodal volume. Set to None: All no surface correction is applied. Default None.
  • volume_correction (int) – A flag variable denoting the algorithm for approximation of the partial nodal volumes applied when integrating the bond force over the horizon. Set to 0: The ‘Partial Volume algorithm’ as proposed by Hu, Ha, and Bobaru [W. Hu, Y.D. Ha and F. Bobaru, Numerical integration in peridynamics, Tech. Rep., University of Nebraska-Lincoln, Department of Mechanical & Materials Engineering (September 2010)] is used. Set to None: The ‘Full Volume algorithm’ is used; partial nodal volumes are approximated by their full nodal volumes. Defauly None.
  • micromodulus_function (int) – A flag variable denoting the normalised micromodulus function. Set to 0: A conical micromodulus function is used, which is normalised such that the maximum value of the micromodulus function is the bond stiffness. Set to None: A constant noramlised micromodulus function is used such that the maximum value of the micromodulus function is the bond stiffness. Default None.
  • node_radius (float) – Average peridynamic node radius . Must be provided if volume corrections (volume_correction=1) are applied.
Raises:
  • DimensionalityError – when an invalid dimensions argument is provided.
  • FamilyError – when a node has no neighbours (other nodes it interacts with) in the initial state.
Returns:

A new Model object.
Return type:

Model
simulate(steps, u=None, ud=None, connectivity=None, regimes=None, critical_stretch=None, bond_stiffness=None, displacement_bc_magnitudes=None, force_bc_magnitudes=None, first_step=1, write=None, write_path=None)

Simulate the peridynamics model.

Parameters:
  • steps (int) – The number of simulation steps to conduct.
  • u (numpy.ndarray) – The initial displacements for the simulation. If None the displacements will be initialised to zero. Default None.
  • ud (numpy.ndarray) – The initial velocities for the simulation. If None the velocities will be initialised to zero. Default None.
  • connectivity (tuple(numpy.ndarray, numpy.ndarray)) – The initial connectivity for the simulation. A tuple of a neighbour list and the number of neighbours for each node. If None the connectivity at the time of construction of the Model object will be used. Default None.
  • regimes (numpy.ndarray) – The initial regimes for the simulation. A (nodes, max_neighbours) array of type numpy.ndarray of the regimes of the bonds.
  • critical_stretch (numpy.ndarray or float) – An (nregimes, nbond_types) array of critical stretch values, each corresponding to a bond type and a regime, or a float value of the critical stretch of the Peridynamic bond-based prototype microelastic brittle (PMB) model.
  • bond_stiffness (numpy.ndarray or float) – An (nregimes, nbond_types) array of bond stiffness values, each corresponding to a bond type and a regime, or a float value of the bond stiffness the Peridynamic bond-based prototype microelastic brittle (PMB) model.
  • displacement_bc_magnitudes (numpy.ndarray) – (steps, ) array of the magnitude applied to the displacement boundary conditions over time.
  • force_bc_magnitudes (numpy.ndarray) – (steps, ) array of the magnitude applied to the force boundary conditions over time.
  • first_step (int) – The starting step number. This is useful when restarting a simulation.
  • write (int) – The frequency, in number of steps, to write the system to a mesh file by calling Model.write_mesh(). If None then no output is written. Default None.
  • write_path (path-like or str) – The path where the periodic mesh files should be written.
Returns:

A tuple of the final displacements (u); damage, a tuple of the connectivity; the final node forces (force); the final node velocities (ud) and a dictionary object containing the displacement, velocity and acceleration (average of), and the forces and body forces for each of the writes (read ‘over time’), for each unique tip_type (read ‘for each of the set of nodes the user has chosen to measure datum for, as defined by the is_tip function).
Return type:

tuple( numpy.ndarray, numpy.ndarray, tuple(numpy.ndarray, numpy.ndarray), numpy.ndarray, numpy.ndarray, dict)
write_mesh(filename, damage=None, displacements=None, file_format=None)

Write the model’s nodes, connectivity and boundary to a mesh file.

Parameters:
  • filename (str) – Path of the file to write the mesh to.
  • damage (numpy.ndarray) – The damage of each node. Default is None.
  • displacements (numpy.ndarray) – An array with shape (nnodes, dim) where each row is the displacement of a node. Default is None.
  • file_format (str) – The file format of the mesh file to write. Inferred from filename if None. Default is None.
Returns:

None
Return type:

NoneType

Decorators

Warnings

model.this_may_take_a_while(calculation)

Raise a UserWarning if nnodes is over 9000! (an arbritrarily large value).

Parameters:
  • nnodes (int) – The number of nodes.
  • calculation (str) – A string message of the calculation being performed.
Return type:

UserWarning or None

Exceptions

exception peripy.model.DimensionalityError(dimensions)

An invalid dimensionality argument used to construct a model.

Construct the exception.

Parameters:dimensions (int) – The number of dimensions passed as an argument to Model().
Return type:DimensionalityError
exception peripy.model.FamilyError(family)

One or more nodes have no bonds in the initial state.

Construct the exception.

Parameters:family (numpy.ndarray) – The family array.
Return type:FamilyError
exception peripy.model.DamageModelError(critical_stretch)

An invalid critical stretch argument was used to construct a model.

Construct the exception.

Parameters:critical_stretch (numpy.ndarray or list) – The critical_stretch array.
Return type:DamageModelError
exception peripy.model.InvalidIntegrator(integrator)

An invalid integrator has been passed to simulate.

Construct the exception.

Parameters:integrator – The object passed to Model.simulate() as the integrator argument.
Return type:InvalidIntegrator