SimulationCellLengthProfile¶

Included in QATK.Dynamics

class SimulationCellLengthProfile(direction, initial_value, initial_gradient=None, update_frequency=None, total_steps=None)¶

Class for creating a profile of temperature values for use during a dynamics simulation.

Parameters:

direction (str) – The cell length to set.Must be one of: "xx", "yy", "zz", "xy", "xz", "yx", "yz", "zx", "zy".
initial_value (PhysicalQuantity of type length) – The initial value of the cell length at step 0.
initial_gradient (PhysicalQuantity of type length | None) – The initial gradient of the cell length. if None is given the gradient is assumed to be zero. The gradient is in terms of change of the cell length over the fraction of the simulation.
update_frequency (int | None) – The step frequency with which the cell length is updated during the simulation.
total_steps (int | None) – The total number of steps in the simulation. This allows the conversion from fraction of simulation to step number. If None is given it must be set later before use.

addQuantityValue(fraction, value, gradient=None)¶

Add a new value of the quantity at the given fraction of the simulation.

Parameters:

fraction (float) – The fraction of the simulation at which the quantity value is defined. Must be between 0 and 1.
value (PhysicalQuantity) – The value of the quantity at the given fraction.
gradient (PhysicalQuantity | None) – The gradient of the quantity at the given fraction. If None is given the gradient is assumed to be zero. The gradient is in terms of change of the quantity over the fraction of the simulation.

direction()¶

Returns:: The cell length direction being controlled.
Return type:: "xx" | "yy" | "zz" | "xy" | "xz" | "yx"

setTotalSteps(total_steps)¶

Set the total number of steps in the simulation.

Parameters:: total_steps (int) – The total number of steps in the simulation.

setUpdateFrequency(frequency)¶

Set the frequency, in number of steps, the quantity from the profile is used to update the simulation.

Parameters:: frequency (int) – The number of steps between quantity updates.

setValueFunction(function)¶

Set a custom function for calculating the value of the quantity at a given step in the simulation. The function takes in the fraction of the simulation performed, which ranges from 0 to 1, and returns the value corresponding to that fraction.

An example use of this might be to set a function might be to sinusoidally vary a parameter during the simulations.

Parameters:: function (function | None) – A function that takes in a float between 0 and 1, and returns a PhysicalQuantity. None restores the default linear interpolation function.

totalSteps()¶

Returns:: The total number of steps in the simulation, if set.
Return type:: int | None

uniqueString()¶: Return a unique string representing the state of the object.

updateFrequency()¶

Returns:: The step frequency with which the quantity is updated during the simulation.
Return type:: int

value(step)¶

Get the value of the quantity at the given step in the simulation.

Parameters:: step (int) – The step in the simulation for which the quantity value is requested.
Returns:: The value of the quantity at the given step.
Return type:: PhysicalQuantity

Usage Examples¶

Perform a stress-strain calculation on a configuration of amorphous polystyrene. The cell is strained in the C direction. The stress is also calculated in this direction to estimate the Young’s modulus. The strain in the transverse directions are also calculated to estimate the Poisson ratio.

# Measure the stress and strain during the simulation
measurement = SoftMatterDynamicsMeasurements(
    strain=["xx", "yy", "zz"], stress=["zz"], call_interval=100
)

# Set the cell length profile to implement a strain of 0.02
initial_length = configuration.primitiveVectors().norm(axis=1)[2]
length_profile = SimulationCellLengthProfile(
    "zz",
    initial_value=initial_length,
    initial_gradient=0.02*initial_length
)

# Run the simulation
simulation.simulate(
    100000, hook_functions=[measurement], profiles=[length_profile]
)

equilibrated_ps.hdf5 cell_length_profile_example.py

Notes¶

The SimulationCellLengthProfile adds a strain profile to a soft matter dynamics simulation. The profile is implemented so that the simulation cell length can be constantly updated during the simulation. Profiles work by taking both the value, and optionally the gradient of the cell length at different points. These can then be used to construct a piecewise linear function of the cell length during the simulation. This can be used to implement calculations such as a stress-strain simulation.

When specifying cell lengths and gradients, everything is specified with reference to the fraction of the simulation completed. In this the profile is both independent of the number of steps in the simulation and also the time step. Gradients are likewise given as the instantaneous rate of change over the whole simulation.

When creating a cell length profile a strain direction must first be given. This can be a linear strain using the values "xx", "yy" and "zz" or a shear strain using the values "xy", "xz" or "yz". After the direction an initial cell length and optionally a length charge rate is given. Gradients are optional, and when not specified are assumed to be zero. Note also that cell lengths are given as absolute distances and not as relative strains. Additional points on the profile are added with the addQuantityValue method. This takes the fraction of the simulation progress, the cell length at that point and optionally a gradient in the cell length from that point. If the value from the last segment does not match the new cell length the cell length profile is discontinuous.

It is also possible to define a profile using a user-defined function. In this way profiles such as sinusoidal or other shapes can be easily implemented. The function is given with the setValueFunction method. This function should take as an argument the fraction of the simulation and return a cell length. Custom functions are not saved as part of the profile when it is written with nlsave, and thus must be re-set if a profile is used from a file.