PolymerEquilibration

class PolymerEquilibration(configuration, filename, object_id, log_filename_prefix='polymer_equilibration_', max_temperature=None, final_temperature=None, max_pressure=None, final_pressure=None, isotropic_pressure=None, time_scale_factor=None, log_interval=None, trajectory_interval=None)

Create a polymer simulation study object that executes a 21 step equilibration protocol. This is useful for equilibrating polymer configurations created by the MonteCarloPolymerBuilder to the correct density and temperature for the potential model.

Parameters:

• configuration (BulkConfiguration) – The configuration to be equilibrated.

• filename (str) – The full or relative path to save the restart information to.

• object_id (str) – The object id to use when saving the restart information.

• log_filename_prefix (str) – The prefix used in generated log files.
  Default: polymer_equilibration_.

• max_temperature (PhysicalQuantity of type temperature) – The maximum temperature used in the equilibration.
  Default: 1000 Kelvin.

• final_temperature (PhysicalQuantity of type temperature) – The final temperature the configuration is to be equilibrated to.
  Default: 300 Kelvin.

• max_pressure (PhysicalQuantity of type pressure) – The maximum pressure used in the equilibration.
  Default: 50000 bar.

• final_pressure (PhysicalQuantity of type pressure) – The final pressure the configuration is to be equilibrated to.
  Default: 1 bar.

• isotropic_pressure (bool) – If True, couples the cell vectors with each other and w.r.t. pressure. Isotropic pressure couples the 3 unit cell vectors together, maintaining the cell shape. Turning this off couples the vectors independently, allowing cell shape changes. It is recommended to turn off this option for non-isotropic materials or materials that contain periodic surfaces.

• time_scale_factor (float) – Factor to scale the total number of MD steps. A scale factor of one corresponds to 1.56 ns of simulation time.
  Default: 1.0.

• log_interval (int) – The frequency with which entries are written to the log files.
  Default: 100.

• trajectory_interval (int) – The frequency with which configurations are saved in the trajectory.
  Default: 1000.

dependentStudies()

Returns:

The list of dependent studies.

Return type:

list of Study

equilibratedConfiguration()

Return the final equilibrated structure from the equilibration simulation.

Returns:

The final equilibrated configuration.

Return type:

BulkConfiguration

filename()

Returns:

The filename where the study object is stored.

Return type:

str

logFilenamePrefix()

Returns:

The filename prefix for the logging output of the study.

Return type:

str | LogToStdOut

nlprint(stream=None)

Print a string containing an ASCII table useful for plotting the Study object.

Parameters:

stream (python stream) – The stream the table should be written to.
Default: NLPrintLogger()

numberOfProcessesPerTask()

Returns:

The number of processes to be used to execute each task. If None, all available processes should execute each task collaboratively.

Return type:

int | None | ProcessesPerNode

numberOfProcessesPerTaskResolved()

Returns:

The number of processes to be used to execute each task. Default values are resolved based on the current execution settings.

Return type:

int

objectId()

Returns:

The name of the study object in the file.

Return type:

str

saveToFileAfterUpdate()

Returns:

Whether the study is automatically saved after it is updated.

Return type:

bool

trajectory(step_number)

Returns:

The trajectory segment corresponding to the given step number. If that task has not finished running, then None is returned.

Return type:

MDTrajectory | None

uniqueString()

Return a unique string representing the state of the object.

update()

Run the calculations for the study object.

writeFullTrajectory(path, object_id=<class 'NL.ComputerScienceUtilities.NLFlag._NLFlag.Automatic'>)

Parameters:

• path (str) – The path to save the full MD trajectory to.

• object_id (str) – The object id of the trajectory in the HDF5 file.
  Default: Automatically chosen name

Returns:

The full trajectory combining all equilibration steps.

Return type:

MDTrajectory

Usage Examples

Create a polymer model of poly(methyl methacrylate). The script below uses the ForceCappedEquilibration object to remove atomic overlaps in the initial structure. The PolymerEquilibration object is then used to equilibrate the generated polymer system so that it is ready for production calculations of the properties of interest.

# Load the monomer for the polymer
monomer = nlread('Methyl_Methacrylate.hdf5')[-1]

# Define the polymer sequence as containing 10 chains of 100 monomers each, joined atactically.
sequence = PolymerSequence(
    [monomer],
    number_of_monomers=100,
    number_of_chains=10,
)

# Build the initial polymer structure to a correct density for the given polymer.
builder = PolymerMonteCarloBuilder(
    sequence,
    density=1.18*gram*cm**-3,
)
configuration = builder.buildPolymerConfiguration()

# Place an OPLS potential on the configuration as the basis of the force capped equilibration.
potential = OPLSPotentialBuilder()
calculator = potential.createCalculator(configuration)
configuration.setCalculator(calculator)

# Equilibrate the structure and save the resulting configuration to disk.
forcecap_equilibrator = ForceCappedEquilibration()
equilibrated_structure = forcecap_equilibrator.runEquilibration(configuration)
nlsave('ForceCapped_Configuration.hdf5', equilibrated_structure)

# Create a polymer equilibration object and run the equilibration process
polymer_equilibrator = PolymerEquilibrator(
    configuration=equilibrated_structure,
    filename='PolymerEquilibrationRestart.hdf5',
    object_id='PolymerEquilibration'
)
polymer_equilibrator.update()

# Return the final equilibrated configuration and save it to disk
final_configuration = polymer_equilibrator.equilibratedConfiguration()
nlsave('Final_Configuration.hdf5', final_configuration)

PolymerEquilibration_Example.py Methyl_Methacrylate.hdf5

Notes

Properly equilibrating polymer models is one of the significant challenges in simulating polymeric materials. As a result of the usually long timescales involved in polymer relaxation, this process is often accelerated by using cycles of high temperature and high pressure simulations. The PolymerEquilibration object automates one such process, by implementing a 21 step protocol for polymer equilibration [1]. The 21 steps involves 7 cycles of high temperature/pressure simulation and annealing. The temperature and pressure are varied between a maximum temperature and pressure and the final temperature and pressure at the desired conditions. Details of each step is shown in the table below.

Cycle	Ensemble	Time (ps)	Conditions
1	NVT	50	Tmax
2	NVT	50	Tfinal
3	NPT	50	Tfinal, 0.02 \(\times\) Pmax
4	NVT	50	Tmax
5	NVT	100	Tfinal
6	NPT	50	Tfinal, 0.6 \(\times\) Pmax
7	NVT	50	Tmax
8	NVT	100	Tfinal
9	NPT	50	Tfinal, Pmax
10	NVT	50	Tmax
11	NVT	100	Tfinal
12	NPT	5	Tfinal, 0.5 \(\times\) Pmax
13	NVT	5	Tmax
14	NVT	10	Tfinal
15	NPT	5	Tfinal, 0.1 \(\times\) Pmax
16	NVT	5	Tmax
17	NVT	10	Tfinal
18	NPT	5	Tfinal, 0.01 \(\times\) Pmax
19	NVT	5	Tmax
20	NVT	10	Tfinal
21	NPT	800	Tfinal, Pfinal

The PolymerEquilibration object has 3 required arguments. These are a BulkConfiguration object contining the polymer system to be equilibrated, a file where ongoing details of the calculation can be written and an object id for the data in the file. As equilibration may take a significant amount of computer time, PolymerEquilibration objects are restartable. If the simulation is interupted at some point it can be restarted from that point by calling the same PolymerEquilibration creation and update commands. The necessary information for the restart is contained in the file specified in the required filename argument.

The PolymerEquilibration class also has a number of optional arguments to control the equilibration process. The maximum and final temperatures can be defined using the max_temperature and final_temperature arguments respectively. Similarly the maximum and final pressures can be set using the max_pressure and final_pressure arguments. The coupling of pressure with the lattice vectors is set with the parameter isotropic_pressure. Setting this to True couples the three lattice together with pressure allowing the unit cell volume to vary. Setting this to False couples the three lattice vectors independently to pressure, allowing the cell lengths to change differently. This is useful in cases where the system is anisotropic, such as in polymer-surface interfaces. The number of molecular dynamics steps can be controlled using the scale argument. This provides a scaling factor for the number of steps and also the total simulation time used in the equilibration. By default the equilibration performs 1,560,000 steps, requiring 1.56ns of simulation time. This can be increased or decreased using the scale argument. Output of each equilibration trajectory to a file can also be controlled by using the trajectory_filename argument to specify a file to write to and the trajectory_interval argument to specify the frequency of writing to the trajectory. Output to log files can also be controlled using the log_filename_prefix and log_interval commands. During the equilibration a new log file is created for each step in the equilibration process. The prefix of each filename can be specified using the log_filename_prefix argument, while the frequency of writing to the log file is controlled using the log_interval argument.

Once the PolymerEquilibration object is created the equilibration is run using the update method. Once the equilibration is complete the final equilibrated configuration can be returned using the equilibratedConfiguration method.

[1]

Lauren J. Abbott, Kyle E. Hart, and Coray M. Colina. Polymatic: a generalized simulated polymerization algorithm for amorphous polymers. Theor. Chem. Acc., 132:1334, 2013. URL: https://link.springer.com/article/10.1007/s00214-013-1334-z, doi:10.1007/s00214-013-1334-z.