RandomDisplacementsParameters

class RandomDisplacementsParameters(reference_configurations, supercell_repetitions_list=None, strain_tensors=None, sample_size=None, system_sizes=None, atomic_rattling_amplitudes=None, cell_rattling_amplitudes=None, random_seed=None, log_filename_prefix=None, data_tag=None)

Class for storing parameters for generating a set of training configurations using a series of random atomic displacements.

Parameters:

  • reference_configurations (MoleculeConfiguration | BulkConfiguration | sequence of[ MoleculeConfiguration | BulkConfiguration] | Table) – One or more reference configurations to be used to generate the training set. For bulk configurations, this is the unit cell from which a supercell can be defined and additional strain can be applied.

  • supercell_repetitions_list (sequence (size 3) of int | sequence of sequence (size 3) of int | None) – The list of supercells to construct for each configuration, given as the number of repetitions of the bulk unit cell along the (a, b, c) directions. Cannot be specified if there are molecules in the list of reference configurations. If None: No repetitions.
    Default: None.

  • strain_tensors (sequence (size 3) of sequence (size 3) of float | sequence of sequence (size 3) of sequence (size 3) of float | None) – The list of strains to apply to each configuration. Cannot be specified if there are molecules in the list of reference configurations. If None: No strain.
    Default: None.

  • sample_size (int) – The number of training configurations to generate for each combination of reference configuration, supercell, strain tensor, atomic rattling amplitude, and cell rattling amplitude.
    Default: 20.

  • system_sizes (int | sequence of int) – Minimum number of atoms in the system. If None then supercell_repetitions_list will be used to do the repetition of the cell. If set, supercell_repetitions_list will be ignored.
    Default: None

  • atomic_rattling_amplitudes (PhysicalQuantity of type length | sequence of|PHYSICALQUANTITY| of typ e length) – The list of maximum random displacements of the atomic positions.
    Default: 0.1 * Angstrom.

  • cell_rattling_amplitudes (float | sequence of [float, None]) – The list of maximum random strains of the cell volume. Only applies to bulk configurations. If None: No strain. DEFAULT| None.

  • random_seed (int) – The random seed used for generating the displacements.
    Default: Generated automatically.

  • log_filename_prefix (str) – Filename prefix for the logging output of the tasks associated with this set.
    Default: Defined by the MomentTensorPotentialTraining object.

  • data_tag (str) – Label for this training set to enable selection of different data in MTP fitting.
    Default: None.

atomicRattlingAmplitudes()
Returns:

The list of maximum random displacements of the atomic positions.

Return type:

list of PhysicalQuantity of type length

cellRattlingAmplitudes()
Returns:

The list of maximum random strains of the cell volume (None for no strain).

Return type:

list of [float | None]

dataTag()
Returns:

The selection tag added to the data in the training set.

Return type:

str

logFilenameIdentifier()
Returns:

Filename identifier for the logging output of the tasks associated with this set, or None if it hasn’t been set yet.

Return type:

str | None

logFilenamePrefix()
Returns:

Filename prefix for the logging output of the tasks associated with this set, or None if it is to be defined by the MomentTensorPotentialTraining object.

Return type:

str | LogToStdOut | None

randomSeed()
Returns:

The random seed used for generating the displacements, or None if it should be generated automatically.

Return type:

int | None

referenceConfigurations()
Returns:

The list of reference configurations to be used to generate the training set.

Return type:

list of [MoleculeConfiguration | BulkConfiguration]

sampleSize()
Returns:

The number of training configurations for each combination of list parameters.

Return type:

int

strainTensors()
Returns:

The list of strains to apply to each configuration (None for no strain).

Return type:

list of [numpy.ndarray | None]

supercellRepetitionsList()
Returns:

The list of supercells to construct for each configuration, given as the number of repetitions of the bulk unit cell along the (a, b, c) directions.

Return type:

list of tuple (size 3) of int

systemSizes()
Parameters:

system_sizes (int | sequence of int) – Minimum number of atoms in the system. If None then supercell_repetitions_list will be used to do the repetition of the cell. If set, supercell_repetitions_list will be ignored.
Default: None

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Setup of a training set of quartz using RandomDisplacementsParameters.

# Set up lattice
lattice = Hexagonal(4.966693338812276*Angstrom, 5.4647751809821905*Angstrom)

# Define elements
elements = [Silicon, Silicon, Silicon, Oxygen, Oxygen, Oxygen, Oxygen, Oxygen,
            Oxygen]

# Define coordinates
fractional_coordinates = [[ 0.469217958328,  0.            ,  0.            ],
                          [ 0.            ,  0.469217958328,  0.666666666667],
                          [ 0.530782041672,  0.530782041672,  0.333333333333],
                          [ 0.409091887977,  0.269718793416,  0.115058361235],
                          [ 0.269718793416,  0.409091887977,  0.551608638765],
                          [ 0.730281206584,  0.139373094561,  0.781725361235],
                          [ 0.590908112023,  0.860626905439,  0.218274638765],
                          [ 0.860626905439,  0.590908112023,  0.448391361235],
                          [ 0.139373094561,  0.730281206584,  0.884941638765]]

# Set up reference configuration of quartz
reference_configuration = BulkConfiguration(
   bravais_lattice=lattice,
   elements=elements,
   fractional_coordinates=fractional_coordinates,
)

# Set up the list of isotropic volume strains that should be applied.
volume_strain = [0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15]
identity_matrix = numpy.eye(3)

# Define RandomDisplacementsParameters used to generate the training set.
training_sets = RandomDisplacementsParameters(
   reference_configurations=reference_configuration,
   supercell_repetitions_list=[(1, 1, 1), (2, 2, 2)],
   strain_tensors=[identity_matrix*s**0.3333333 for s in volume_strain],
   sample_size=10,
   atomic_rattling_amplitudes=0.15*Angstrom,
   cell_rattling_amplitudes=0.07,
   log_filename_prefix=None,
)

Note here that each combination of input arguments creates sample_size=10 configurations.

Notes

The RandomDisplacementsParameters class can be used to generate training configurations by randomly displacing the atoms of a given reference configuration around their equilibrium positions. Additionally, isotropic and anisotropic strain can be applied to the cell. For the actual training data generation a RandomDisplacementsParameters object needs to be passed into a MomentTensorPotentialTraining object.

To achieve a broadly applicable training set of configurations, a combination of different displacement magnitudes should be used. Small displacement magnitudes typically provide a good description of vibrations and phonons, while larger displacement magnitudes typically increase the stability of the simulation over a wider temperate range below the melting point. This provides a very efficient way to generate training data for crystal materials without having to run long expensive ab-initio MD simulations. It is recommended to use various supercell sizes to improve the training of the total energy.

A good default protocol, that provides a balanced combination of different displacement and strain magnitudes can be set up via the function crystalTrainingRandomDisplacements.

Note, that such a displacement protocol can also be used to generate training data for crystal surfaces and interfaces. Here, one would include the most relevant surfaces or interface configurations, such as combinations of different cleave planes, and proceed as outlined above.