4. `micmec.sampling` – Phase-space sampling.¶

4.1. `micmec.sampling.dof` – Abstraction layer for degrees of freedom.¶

Abstraction layer for degrees of freedom.

All these classes are called DOF classes, because they specify a set of degrees of freedom. These DOF classes are used for geometry/domain optimization and harmonic approximations.

class micmec.sampling.dof.BaseCellDOF(mmf, gpos_rms=1e-05, dpos_rms=0.001, grvecs_rms=1e-05, drvecs_rms=0.001, do_frozen=False, freemask=None)¶

Fractional coordinates and cell parameters.

Each subclass of BaseCellDOF considers a specific representation and subset of the cell parameters. The following variable names are consistently used (also in subclasses).

cellvars: An array with all variables for the cell (specific for BaseCellDOF subclass).
ncellvar: The number of cellvars (at most 9).
celldofs: A selection of the elements in cellvars, based on freemask.
ncelldof: The number of celldofs (less than or equal to ncellvar).
frac: Fractional coordinates.
x: All degrees of freedom, i.e. celldofs and frac (in that order, frac is optional).

Attributes

ncelldof: The number of celldofs (free cellvars)
ncellvar: The number of cellvars
ndof

Methods

`check_delta`([x, eps, zero])	Test the analytical derivatives.
`fun`(x[, do_gradient])	Computes the energy and optionally the gradient.

check_convergence
log
reset

fun(x, do_gradient=False)¶

Computes the energy and optionally the gradient.

Parameters

x: All degrees of freedom.
do_gradient: When True, the gradient is also returned.

property ncelldof¶: The number of celldofs (free cellvars)

property ncellvar¶: The number of cellvars

class micmec.sampling.dof.CartesianDOF(mmf, gpos_rms=1e-05, dpos_rms=0.001, select=None)¶

Cartesian degrees of freedom.

This DOF is also applicable to periodic systems. Domain parameters are not modified when this DOF is used.

Attributes

ndof

Methods

`check_delta`([x, eps, zero])	Test the analytical derivatives.
`fun`(x[, do_gradient])	Computes the energy and optionally the gradient.

check_convergence
log
reset

fun(x, do_gradient=False)¶

Computes the energy and optionally the gradient.

Parameters

xnumpy.ndarray: All degrees of freedom.
do_gradientbool, optional: When True, the gradient is also returned.

class micmec.sampling.dof.FullCellDOF(mmf, gpos_rms=1e-05, dpos_rms=0.001, grvecs_rms=1e-05, drvecs_rms=0.001, do_frozen=False, freemask=None)¶

DOF that includes all 9 components of the cell vectors.

The degrees of freedom are rescaled cell vectors ordered in one row: 3D periodic: [a_x/s, a_y/s, a_z/s, b_x/s, b_y/s, b_z/s, c_x/s, c_y/s, c_z/s]

where s is the cube root of the initial cell volume such that the cell DOFs become dimensionless.

2D periodic: [a_x/s, a_y/s, a_z/s, b_x/s, b_y/s, b_z/s]: where s is the square root of the initial cell surface such that the cell DOFs become dimensionless.
1D periodic: [a_x/s, a_y/s, a_z/s]: where s is the length of the initial cell vector such that the cell DOFs become dimensionless.

Attributes

ncelldof: The number of celldofs (free cellvars)
ncellvar: The number of cellvars
ndof

Methods

`check_delta`([x, eps, zero])	Test the analytical derivatives.
`fun`(x[, do_gradient])	Computes the energy and optionally the gradient.

check_convergence
log
reset

class micmec.sampling.dof.StrainCellDOF(mmf, gpos_rms=1e-05, dpos_rms=0.001, grvecs_rms=1e-05, drvecs_rms=0.001, do_frozen=False, freemask=None)¶

Eliminates rotations of the unit cell. thus six cell parameters are free.

The degrees of freedom are coefficients in symmetrix matrix transformation, A, that is applied to the initial cell vectors.

3D periodic: [A_00, A_11, A_22, 2*A_12, 2*A_20, 2*A_01] 2D periodic: [A_00, A_11, 2*A_01] 1D periodic: [A_00]

Attributes

ncelldof: The number of celldofs (free cellvars)
ncellvar: The number of cellvars
ndof

Methods

`check_delta`([x, eps, zero])	Test the analytical derivatives.
`fun`(x[, do_gradient])	Computes the energy and optionally the gradient.

check_convergence
log
reset

4.2. `micmec.sampling.iterative` – Base class for iterative algorithms.¶

Base class for iterative algorithms.

class micmec.sampling.iterative.EPotContribStateItem¶

Keeps track of all the contributions to the potential energy.

Methods

copy
get_value
iter_attrs
update

4.3. `micmec.sampling.npt` – Barostats.¶

Barostats.

class micmec.sampling.npt.BerendsenBarostat(mmf, temp, press, start=0, step=1, timecon=41341.37333664682, beta=13445.401558486123, anisotropic=True, vol_constraint=False, restart=False)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre

method = 'barostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.npt.LangevinBarostat(mmf, temp, press, start=0, step=1, timecon=41341.37333664682, anisotropic=True, vol_constraint=False)¶

Methods

__call__(iterative)

Call self as a function.

baro
expects_call
getR
init
post
pre

method = 'barostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.npt.MTKBarostat(mmf, temp, press, start=0, step=1, timecon=41341.37333664682, anisotropic=True, vol_constraint=False, baro_thermo=None, vel_press0=None, restart=False)¶

Methods

__call__(iterative)

Call self as a function.

add_press_cont
baro
expects_call
init
post
pre

method = 'barostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.npt.TBCombination(thermostat, barostat, start=0)¶

Attributes

kind
method

Methods

__call__(iterative)

Call self as a function.

expects_call
expectscall
init
post
pre
verify

4.4. `micmec.sampling.nvt` – Thermostats.¶

Thermostats.

class micmec.sampling.nvt.AndersenThermostat(temp, start=0, step=1, select=None, annealing=1.0)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre

method = 'thermostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.nvt.BerendsenThermostat(temp, start=0, timecon=4134.137333664683, restart=False)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre

method = 'thermostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.nvt.CSVRThermostat(temp, start=0, timecon=4134.137333664683)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre

method = 'thermostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.nvt.GLEThermostat(temp, a_p, c_p=None, start=0)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre
thermo

method = 'thermostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.nvt.LangevinThermostat(temp, start=0, timecon=4134.137333664683)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre
thermo

method = 'thermostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

class micmec.sampling.nvt.NHCThermostat(temp, start=0, timecon=4134.137333664683, chainlength=3, chain_pos0=None, chain_vel0=None, restart=False)¶

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre

method = 'thermostat'¶

Base class for any routine called during a simulation.

Parameters

startint: The first iteration at which this hook should be called.
stepint: The hook will be called every step iterations.

4.5. `micmec.sampling.opt` – Geometry optimization.¶

Geometry optimization.

class micmec.sampling.opt.CGOptimizer(dof, state=None, hooks=None, counter0=0)¶

A conjugate gradient optimizer.

Methods

call_hooks
finalize
fun
initialize
propagate
run

class micmec.sampling.opt.QNOptimizer(dof, state=None, hooks=None, counter0=0, trust_radius=1.0, small_radius=1e-05, too_small_radius=1e-10, hessian0=None)¶

A Quasi-Newtonian optimizer.

Methods

call_hooks
finalize
fun
initialize
make_step
propagate
run

micmec.sampling.opt.solve_trust_radius(grad, evals, radius, threshold=1e-05)¶: Find a step in eigenspace with the given radius.

4.6. `micmec.sampling.trajectory` – Trajectory writers.¶

Trajectory writers.

4.7. `micmec.sampling.utils` – Auxiliary routines for initial velocities.¶

Auxiliary routines for initial velocities.

micmec.sampling.utils.angular_moment(pos, vel, masses)¶

Compute the angular moment of a set of point particles.

Parameters

pos: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal positions (Cartesian coordinates).
vel: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal velocities.
masses: SHAPE: (nnodes,) TYPE: numpy.ndarray DTYPE: float The nodal masses.

Returns

ang_mom: SHAPE: (3,) TYPE: numpy.ndarray DTYPE: float The angular momentum vector.

micmec.sampling.utils.angular_velocity(amom, itens, epsilon=1e-10)¶

Derive the angular velocity from the angular moment and the inertia tensor.

Parameters

amom: SHAPE: (3,) TYPE: numpy.ndarray DTYPE: float The angular momentum vector.
itens: SHAPE: (3,3) TYPE: numpy.ndarray DTYPE: float The inertia tensor.
epsilonfloat: A threshold for the low eigenvalues of the inertia tensor. When an eigenvalue is below this threshold, it is assumed to be zero plus some (irrelevant) numerical noise.

Returns

avel: SHAPE: (3,) TYPE: numpy.ndarray DTYPE: float The angular velocity vector.

Notes

In principle, this routine should merely return: np.linalg.solve(itens, amom). However, when the inertia tensor has zero eigenvalues, this routine will use a proper pseudo-inverse of the inertia tensor.

micmec.sampling.utils.clean_momenta(pos, vel, masses, domain)¶

Remove any relevant external momenta.

Parameters

pos: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal positions (Cartesian coordinates). This array is modified in-place.
vel: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal velocities. This array is modified in-place.
masses: SHAPE: (nnodes,) TYPE: numpy.ndarray DTYPE: float The nodal masses.
domainmicmec.pes.ext.Domain object: An instance of the simulation domain describing the periodic boundary conditions.

micmec.sampling.utils.domain_lower(rvecs)¶

Transform the simulation domain matrix to its lower diagonal form. The transformation is described here:

https://lammps.sandia.gov/doc/Howto_triclinic.html,

bearing in mind that domain vectors are stored as rows, not columns.

Parameters

rvecs: SHAPE: (3,3) TYPE: numpy.ndarray DTYPE: float The cell matrix of the simulation domain.

Returns

new_rvecs: SHAPE: (3,3) TYPE: numpy.ndarray DTYPE: float The lower-diagonal form of rvecs.
rot: SHAPE: (3,3) TYPE: numpy.ndarray DTYPE: float The rotation matrix to go from rvecs to new_rvecs.

Notes

The transformation is described here:: https://lammps.sandia.gov/doc/Howto_triclinic.html,

bearing in mind that domain vectors are stored as rows, not columns.

micmec.sampling.utils.domain_symmetrize(mmf, vector_lst=None, tensor_lst=None)¶

Symmetrize the simulation domain tensor, and update the position vectors.

Parameters

mmfmicmec.pes.mmff.MicMecForceField object: A micromechanical force field.
vector_lstlist of numpy.ndarray: A list of vectors which should be transformed under the symmetrization. Note that the positions are already transformed automatically.
tensor_lstlist of numpy.ndarray: A list of tensors which should be transformed under the symmetrization.

micmec.sampling.utils.get_ndof_baro(dim, anisotropic, vol_constraint)¶

Calculate the number of degrees of freedom associated with the simulation domain fluctuation.

Parameters

dimint: The dimensionality of the system.
anisotropicbool: Whether anisotropic domain fluctuations are allowed.
vol_constraintbool: Whether the domain volume can change.

micmec.sampling.utils.get_ndof_internal_md(nnodes, nper)¶

Return the effective number of internal degrees of freedom for MD simulations.

Parameters

nnodesint: The number of nodes.
nperint: The number of periodic boundary conditions (0 for isolated systems).

micmec.sampling.utils.get_random_vel(temp0, scalevel0, masses, select=None)¶

Generate random nodal velocities using a Maxwell-Boltzmann distribution.

Parameters

temp0float: The temperature for the Maxwell-Boltzmann distribution.
scalevel0bool: When set to True, the velocities are rescaled such that the instantaneous temperature coincides with temp0.
masses: SHAPE: (nnodes,) TYPE: numpy.ndarray DTYPE: float The nodal masses.
selectlist of int: When given, this must be an array of integer indexes. Only for these nodes (masses) initial velocities will be generated.

Returns

vel0: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The random nodal velocities.

micmec.sampling.utils.get_random_vel_press(mass, temp)¶

Generate symmetric tensor of barostat velocities.

Parameters

massfloat: The mass of the barostat.
tempfloat: The temperature at which the velocities are selected.

micmec.sampling.utils.inertia_tensor(pos, masses)¶

Compute the inertia tensor for a given set of point particles.

Parameters

pos: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal positions (Cartesian coordinates). This array is modified in-place.
masses: SHAPE: (nnodes,) TYPE: numpy.ndarray DTYPE: float The nodal masses.

Returns

itens: SHAPE: (3,3) TYPE: numpy.ndarray DTYPE: float The inertia tensor.

micmec.sampling.utils.remove_angular_moment(pos, vel, masses)¶

Zero the global angular momentum.

Parameters

pos: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal positions (Cartesian coordinates). This array is modified in-place.
vel: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal velocities. This array is modified in-place.
masses: SHAPE: (nnodes,) TYPE: numpy.ndarray DTYPE: float The nodal masses.

Notes

The zero angular momentum is achieved by subtracting angular rigid body motion from the nodal velocities. The angular momentum is measured with respect to the center of mass to avoid that this routine reintroduces a linear center-of-mass velocity. This is also beneficial for the numerical stability.

micmec.sampling.utils.remove_com_moment(vel, masses)¶

Zero the global linear momentum.

Parameters

vel: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal velocities. This array is modified in-place.
masses: SHAPE: (nnodes,) TYPE: numpy.ndarray DTYPE: float The nodal masses.

Notes

The zero linear center-of-mass momentum is achieved by subtracting translational rigid body motion from the nodal velocities.

micmec.sampling.utils.rigid_body_angular_velocities(pos, avel)¶

Generate the velocities of a set of nodes that move as a rigid body.

Parameters

pos: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal positions (Cartesian coordinates).
avel: SHAPE: (3,) TYPE: numpy.ndarray DTYPE: float The angular velocity vector of the rigid body.

Returns

vel: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal velocities in the rigid body. The linear momentum of the rigid body is zero.

micmec.sampling.utils.stabilized_cholesky_decomp(mat)¶: Do (LDL)^T and transform to (MM)^T with negative diagonal entries of D put equal to zero. Assume mat is square and symmetric (but not necessarily positive definite).

micmec.sampling.utils.transform_lower_triangular(pos, rvecs, reorder=False)¶

Transform coordinate axes such that the cell matrix is lower diagonal.

The transformation is derived from the QR decomposition and performed in-place. Because the lower triangular form puts restrictions on the size of off-diagonal elements, lattice vectors are by default reordered from largest to smallest; this feature can be disabled using the reorder keyword. The domain vector lengths and angles remain exactly the same.

Parameters

pos: SHAPE: (nnodes,3) TYPE: numpy.ndarray DTYPE: float The nodal positions (Cartesian coordinates).
rvecs: SHAPE: (3,3) TYPE: numpy.ndarray DTYPE: float The cell matrix of the simulation domain. The domain vectors appear as rows in this matrix.
reorderbool: Whether domain vectors are reordered from largest to smallest.

4.8. `micmec.sampling.verlet` – The velocity Verlet algorithm.¶

The velocity Verlet algorithm.

class micmec.sampling.verlet.ConsErrTracker¶

A class that tracks the errors on the conserved quantity.

Given its superior numerical accuracy, the algorithm below is used to calculate the running average. Its properties are discussed in Donald Knuth”s Art of Computer Programming, vol. 2, p. 232, 3rd edition.

Methods

get
update

class micmec.sampling.verlet.VerletHook(start=0, step=1)¶

Specialized Verlet hook.

This is mainly used for the implementation of thermostats and barostats.

Attributes

kind
method
name

Methods

__call__(iterative)

Call self as a function.

expects_call
init
post
pre

class micmec.sampling.verlet.VerletScreenLog(start=0, step=1)¶

A screen logger for the Verlet algorithm.

Attributes

kind
method
name

Methods

__call__(iterative)

Call self as a function.

expects_call

4. `micmec.sampling` – Phase-space sampling.¶

4.1. `micmec.sampling.dof` – Abstraction layer for degrees of freedom.¶

4.2. `micmec.sampling.iterative` – Base class for iterative algorithms.¶

4.3. `micmec.sampling.npt` – Barostats.¶

4.4. `micmec.sampling.nvt` – Thermostats.¶

4.5. `micmec.sampling.opt` – Geometry optimization.¶

4.6. `micmec.sampling.trajectory` – Trajectory writers.¶

4.7. `micmec.sampling.utils` – Auxiliary routines for initial velocities.¶

4.8. `micmec.sampling.verlet` – The velocity Verlet algorithm.¶

Table of Contents

Previous topic

Next topic

This Page

4. micmec.sampling – Phase-space sampling.¶

4.1. micmec.sampling.dof – Abstraction layer for degrees of freedom.¶

4.2. micmec.sampling.iterative – Base class for iterative algorithms.¶

4.3. micmec.sampling.npt – Barostats.¶

4.4. micmec.sampling.nvt – Thermostats.¶

4.5. micmec.sampling.opt – Geometry optimization.¶

4.6. micmec.sampling.trajectory – Trajectory writers.¶

4.7. micmec.sampling.utils – Auxiliary routines for initial velocities.¶

4.8. micmec.sampling.verlet – The velocity Verlet algorithm.¶

4. `micmec.sampling` – Phase-space sampling.¶

4.1. `micmec.sampling.dof` – Abstraction layer for degrees of freedom.¶

4.2. `micmec.sampling.iterative` – Base class for iterative algorithms.¶

4.3. `micmec.sampling.npt` – Barostats.¶

4.4. `micmec.sampling.nvt` – Thermostats.¶

4.5. `micmec.sampling.opt` – Geometry optimization.¶

4.6. `micmec.sampling.trajectory` – Trajectory writers.¶

4.7. `micmec.sampling.utils` – Auxiliary routines for initial velocities.¶

4.8. `micmec.sampling.verlet` – The velocity Verlet algorithm.¶