3. micmec.pes – Micromechanical potential energy surfaces (PESs).

3.1. micmec.pes.ext – C routines

C routines

This extension module is used by various modules of the micmec.pes package.

class micmec.pes.ext.Domain(ndarray rvecs)

Representation of periodic boundary conditions.

Attributes

gvecs

Domain._get_gvecs(self, full=False)

nvec

Domain._get_nvec(self)

parameters

Domain._get_parameters(self)

rvecs

Domain._get_rvecs(self, full=False)

volume

Domain._get_volume(self)

Methods

update_rvecs(self, ndarray rvecs)

property gvecs

property nvec

property parameters

property rvecs

update_rvecs(self, ndarray rvecs)

property volume

3.2. micmec.pes.mmff – MicMecForceField, the micromechanical force field.

MicMecForceField, the micromechanical force field.

class micmec.pes.mmff.ForcePart(name, system)

Base class for anything that can compute energies (and optionally gradient and virial) for a System object, as part of a larger micromechanical force field (MMFF) model.

Parameters

namestr

A name for this part of the micromechanical force field (MMFF). This name must adhere to the following conventions: all lower case, no white space, and short. It is used to construct part_* attributes in the MicMecForceField class, where * is the name.

systemmicmec.system.System

The system to which this part of the MMFF applies.

Methods

clear()	Fill in nan values in the cached results to indicate that they have become invalid.
compute([gpos, vtens])	Compute the energy of this part of the MMFF.
update_pos(pos)	Let the ForcePart object know that the nodal positions have changed.
update_rvecs(rvecs)	Let the ForcePart object know that the domain vectors have changed.

clear()

Fill in nan values in the cached results to indicate that they have become invalid.

compute(gpos=None, vtens=None)

Compute the energy of this part of the MMFF.

The only variable inputs for the compute routine are the nodal positions and the domain vectors, which can be changed through the update_rvecs and update_pos methods. All other aspects of the MMFF are considered to be fixed between subsequent compute calls. If changes other than positions or domain vectors are needed, one must construct a new MMFF instance.

Parameters

gposnumpy.ndarray, shape=(nnodes, 3), optional

The derivatives of the energy towards the Cartesian coordinates of the nodes. (“g” stands for gradient and “pos” for positions.)

vtensnumpy.ndarray, shape=(3, 3), optional

The force contribution to the pressure tensor, also known as the virial tensor. It represents the derivative of the energy towards uniform deformations, including changes in the shape of the unit domain. (“v” stands for virial and “tens” stands for tensor.)

Returns

energyfloat

The (potential) energy (of the MMFF).

Raises

ValueError

If the energy is not-a-number (nan) or if the gpos or vtens array contains a nan.

Notes

The optional arguments are Fortran-style output arguments. When they are present, the corresponding results are computed and added to the current contents of the array.

update_pos(pos)

Let the ForcePart object know that the nodal positions have changed.

Parameters

posnumpy.ndarray, shape=(nnodes, 3)

The new nodal coordinates.

update_rvecs(rvecs)

Let the ForcePart object know that the domain vectors have changed.

Parameters

rvecsnumpy.ndarray, shape=(nper, 3)

The new domain vectors.

class micmec.pes.mmff.ForcePartMechanical(system)

The micromechanical part of the MMFF.

Methods

clear()	Fill in nan values in the cached results to indicate that they have become invalid.
compute([gpos, vtens])	Compute the energy of this part of the MMFF.
update_pos(pos)	Let the ForcePart object know that the nodal positions have changed.
update_rvecs(rvecs)	Let the ForcePart object know that the domain vectors have changed.

get_mic
get_pbc

class micmec.pes.mmff.MicMecForceField(system, parts)

A complete micromechanical force field (MMFF) model.

Parameters

systemmicmec.system.System

The micromechanical system.

partslist of micmec.pes.mmff.ForcePart

The different types of contributions to the MMFF.

Methods

add_part(part)	Add a ForcePart object to the MMFF.
clear()	Fill in nan values in the cached results to indicate that they have become invalid.
compute([gpos, vtens])	Compute the energy of this part of the MMFF.
update_pos(pos)	Let the ForcePart object know that the nodal positions have changed.
update_rvecs(rvecs)	Let the ForcePart object know that the domain vectors have changed.

add_part(part)

Add a ForcePart object to the MMFF.

update_pos(pos)

Let the ForcePart object know that the nodal positions have changed.

Parameters

posnumpy.ndarray, shape=(nnodes, 3)

The new nodal coordinates.

update_rvecs(rvecs)

Let the ForcePart object know that the domain vectors have changed.

Parameters

rvecsnumpy.ndarray, shape=(nper, 3)

The new domain vectors.

3.3. micmec.pes.nanocell – Micromechanical description of a single nanocell state.

Micromechanical description of a single nanocell state.

A single state of a nanocell, on the micromechanical level, is described by means of its elastic deformation energy and the gradient of that energy, which represents the forces acting on the micromechanical nodes.

micmec.pes.nanocell.elastic_energy_nanocell(vertices, h0, C0)

The elastic deformation energy of a nanocell, with respect to one of its metastable states with parameters h0 and C0.

Parameters

verticesnumpy.ndarray, shape=(8, 3)

The coordinates of the surrounding nodes (i.e. the vertices).

h0numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix.

C0numpy.ndarray, shape=(3, 3, 3, 3)

The elasticity tensor.

Returns

energyfloat

The elastic deformation energy.

Notes

At first sight, the equations for bistable nanocells might seem absent from this derivation. They are absent here, but they have been implemented in the mmff.py script. This elastic deformation energy is only the energy of a single metastable state of a nanocell.

micmec.pes.nanocell.grad_elastic_energy_nanocell(vertices, h0, C0)

The gradient of the elastic deformation energy of a nanocell (with respect to one of its metastable states with parameters h0 and C0), towards the Cartesian coordinates of its surrounding nodes.

Parameters

verticesnumpy.ndarray, shape=(8, 3)

The coordinates of the surrounding nodes (i.e. the vertices).

h0numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix.

C0numpy.ndarray, shape=(3, 3, 3, 3)

The elasticity tensor.

Returns

gpos_statenumpy.ndarray, shape=(8, 3)

The gradient of the elastic deformation energy (of a single state of the nanocell).

3.4. micmec.pes.nanocell_original – Micromechanical description of a single nanocell state (original).

Micromechanical description of a single nanocell state (original).

This script contains the original equations of the micromechanical model, as proposed by S. M. J. Rogge. It is, however, NOT recommended to use these equations, as they are based on wrong assumptions. Use the default script (nanocell.py) instead.

micmec.pes.nanocell_original.elastic_energy_nanocell(vertices, h0, C0)

The elastic deformation energy of a nanocell, with respect to one of its metastable states with parameters h0 and C0.

Parameters

verticesnumpy.ndarray, shape=(8, 3)

The coordinates of the surrounding nodes (i.e. the vertices).

h0numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix.

C0numpy.ndarray, shape=(3, 3, 3, 3)

The elasticity tensor.

Returns

energyfloat

The elastic deformation energy.

Notes

At first sight, the equations for bistable nanocells might seem absent from this derivation. They are absent here, but they have been implemented in the mmff.py script. This elastic deformation energy is only the energy of a single metastable state of a nanocell.

micmec.pes.nanocell_original.grad_elastic_energy_nanocell(vertices, h0, C0)

The gradient of the elastic deformation energy of a nanocell (with respect to one of its metastable states with parameters h0 and C0), towards the Cartesian coordinates of its surrounding nodes.

Parameters

verticesnumpy.ndarray, shape=(8, 3)

The coordinates of the surrounding nodes (i.e. the vertices).

h0numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix.

C0numpy.ndarray, shape=(3, 3, 3, 3)

The elasticity tensor.

Returns

gpos_statenumpy.ndarray, shape=(8, 3)

The gradient of the elastic deformation energy (of a single state of the nanocell).

3.5. micmec.pes.nanocell_thesis – Micromechanical description of a single nanocell state (thesis).

Micromechanical description of a single nanocell state (thesis).

This script contains the same equations that were used in the master’s thesis of Joachim Vandewalle. It is, however, NOT recommended to use these equations, as they are based on wrong assumptions. Use the default script (nanocell.py) instead.

micmec.pes.nanocell_thesis.elastic_energy_nanocell(vertices, h0, C0)

The elastic deformation energy of a nanocell, with respect to one of its metastable states with parameters h0 and C0.

Parameters

verticesnumpy.ndarray, shape=(8, 3)

The coordinates of the surrounding nodes (i.e. the vertices).

h0numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix.

C0numpy.ndarray, shape=(3, 3, 3, 3)

The elasticity tensor.

Returns

energyfloat

The elastic deformation energy.

Notes

At first sight, the equations for bistable nanocells might seem absent from this derivation. They are absent here, but they have been implemented in the mmff.py script. This elastic deformation energy is only the energy of a single metastable state of a nanocell.

micmec.pes.nanocell_thesis.grad_elastic_energy_nanocell(vertices, h0, C0)

The gradient of the elastic deformation energy of a nanocell (with respect to one of its metastable states with parameters h0 and C0), towards the Cartesian coordinates of its surrounding nodes.

Parameters

verticesnumpy.ndarray, shape=(8, 3)

The coordinates of the surrounding nodes (i.e. the vertices).

h0numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix.

C0numpy.ndarray, shape=(3, 3, 3, 3)

The elasticity tensor.

Returns

gpos_statenumpy.ndarray, shape=(8, 3)

The gradient of the elastic deformation energy (of a single state of the nanocell).

3.6. micmec.pes.nanocell_utils – Fixed parameters for the evaluation of a nanocell’s potential energy surface. DO NOT CHANGE.

Fixed parameters for the evaluation of a nanocell’s potential energy surface. DO NOT CHANGE.