1. micmec – MicMec, the micromechanical model.

1.1. micmec.log – Screen logger.

Screen logger.

The log object is an instance of the molmod.log.ScreenLog class. The logger comes with a timer infrastructure, which is also implemented in the molmod.log module.

1.2. micmec.system – Representation of a micromechanical system.

Representation of a micromechanical system.

class micmec.system.System(pos, masses, rvecs, surrounding_cells, surrounding_nodes, boundary_nodes=None, grid=None, types=None, params=None)

Construct a micromechanical system.

Parameters

posnumpy.ndarray, shape=(nnodes, 3)

The Cartesian coordinates of the micromechanical nodes.

massesnumpy.ndarray, shape=(nnodes,)

The masses of the micromechanical nodes.

rvecsnumpy.ndarray, shape=(nper, 3)

The domain vectors, which represent the periodicity of the simulation domain.

• nper = 3 corresponds to periodic boundary conditions in the a, b and c directions, where a, b and c are the domain vectors.

• nper = 0 corresponds to an absence of periodicity, used to simulate finite (three-dimensional) crystals.

surrounding_cellsnumpy.ndarray, dtype=int, shape=(nnodes, 8)

The cells adjacent to each node. Each node has, at most, eight surrounding cells. In some cases, nodes have less than eight surrounding cells, due to internal surfaces (mesopores) or external surfaces (finite crystals). In that case, the specific order in which the surrounding cells are listed, is preserved, but the indices of the missing cells are replaced with -1.

surrounding_nodesnumpy.ndarray, dtype=int, shape=(ncells, 8)

The nodes adjacent to each cell. Each cell has eight surrounding nodes, always. The order in which the surrounding nodes of a given cell are listed, is specific and must not be changed.

boundary_nodesnumpy.ndarray, dtype=int, optional

The nodes at the boundary of the micromechanical system. The minimum image convention is only relevant for these boundary nodes.

gridnumpy.ndarray, dtype=int, shape=(nx, ny, nz), optional

A three-dimensional grid that maps the types of cells present in the micromechanical system. An integer value of 0 in the grid signifies an empty cell, a vacancy. An integer value of 1 signifies a cell of type 1, a value of 2 signifies a cell of type 2, etc.

typesnumpy.ndarray, dtype=int, shape=(ncells,), optional

The cell types present in the micromechanical system.

paramsdict, optional

The coarse-grained parameters of the micromechanical system. A system may consist of several cell types, each with one or more metastable states. A single metastable state is represented by an equilibrium cell matrix, a free energy, and an elasticity tensor.

Notes

All quantities are expressed in atomic units. The optional arguments of the System class are technically not required to initialize a system, but all of them are required to perform a simulation.

Methods

from_file(fn, **user_kwargs)	Construct a micromechanical system from a CHK file.
from_hdf5(f)	Construct a micromechanical system from an HDF5 file with a system group.
to_file(fn)	Write the micromechanical system to a CHK, HDF5 or XYZ file.
to_hdf5(f)	Write the system to an HDF5 file.

update_params

classmethod from_file(fn, **user_kwargs)

Construct a micromechanical system from a CHK file.

Parameters

fnstr

The name of the CHK file to load.

user_kwargsdict, optional

Additional information to construct the micromechanical system.

Returns

micmec.system.System

The micromechanical system, constructed from the CHK file.

Raises

IOError

If the input is not a CHK file.

classmethod from_hdf5(f)

Construct a micromechanical system from an HDF5 file with a system group.

Parameters

fh5py.File

An HDF5 file with a system group. The system group must at least contain a pos dataset.

Returns

micmec.system.System

The micromechanical system, constructed from the HDF5 file.

to_file(fn)

Write the micromechanical system to a CHK, HDF5 or XYZ file.

Parameters

fnstr

The name of the file to write to.

Raises

NotImplementedError

If the extension of the file does not match .chk, .h5 or .xyz.

Notes

Supported file formats are:

• CHK (.chk) : internal text-based checkpoint format. This format includes all information about the System instance.

• HDF5 (.h5) : internal binary checkpoint format. This format includes all information about the System instance.

• XYZ (.xyz) : a simple file with node positions.

All data are stored in atomic units.

to_hdf5(f)

Write the system to an HDF5 file.

Parameters

fh5py.File

A writable HDF5 file.

Raises

ValueError

If the HDF5 file already contains a system description.

1.3. micmec.utils – Auxiliary routines for system construction.

Auxiliary routines for system construction.

micmec.utils.build_system(data, grid, pbc=None)

Prepare a micromechanical system and store it in a dictionary.

Parameters

datadict

The micromechanical cell types, stored in a dictionary with integer keys. The corresponding values are dictionaries which contain information about the cell type.

gridnumpy.ndarray, dtype=int, shape=(nx, ny, nz)

A three-dimensional grid that maps the types of cells present in the micromechanical system. An integer value of 0 in the grid signifies an empty cell, a vacancy. An integer value of 1 signifies a cell of type 1, a value of 2 signifies a cell of type 2, etc.

pbclist of bool, default=[True, True, True], optional

The domain vectors for which periodic boundary conditions should be enabled.

Returns

outputdict

A dictionary which is ready to be stored as a CHK file, containing a complete description of the micromechanical system.

Notes

This method is also used by the Micromechanical Model Builder, specifically by the builder_io.py script. If the Builder application does not work, the user can still benefit from the automatic creation of a micromechanical structure by using this method manually. The output dictionary can be stored as a CHK file by using:

molmod.io.chk.dump_chk("output.chk", output).

Then, the CHK file can be used as the input of a micmec.system.System instance.

micmec.utils.build_type(material, mass, cell0, elasticity0, free_energy=None, effective_temp=None, topology=None)

Prepare a micromechanical cell type and store it in a dictionary.

Parameters

materialstr

The name of the cell type’s material.

massfloat

The total mass of the cell type.

cell0(list of) numpy.ndarray, shape=(3, 3)

The equilibrium cell matrix for each metastable state of the cell type.

elasticity0(list of) numpy.ndarray, shape=(3,3,3,3)

The elasticity tensor for each metastable state of the cell type.

free_energy(list of) float, optional

The free energy for each metastable state of the cell type.

effective_tempfloat, optional

The effective temperature for a multistable cell type.

topologystr, optional

The topology of the cell type’s atomic structure.

Returns

outputdict

A dictionary which is ready to be stored as a PICKLE file, containing a complete description of the micromechanical cell type.

Raises

ValueError

If the number of metastable states is not consistent for the equilibrium cell matrix, elasticity tensor or free energy.