FreeVolume¶

class FreeVolume(md_trajectory, polymer_tags=None, start_time=None, end_time=None, time_resolution=None, probe_size=PhysicalQuantity(0.0, Ang), overlap_ratio=1.0, samples=10000, random_seed=None, gui_worker=None)¶

Create an analyzer for the free volume in a polymer structure.

Parameters:

md_trajectory (MDTrajectory | AtomicConfiguration) – The MDTrajectory or AtomicConfiguration that contains the polymers.
polymer_tags (list of type str | None | Automatic) – A list of tags for the polymers. If not specified default tags are used. Tags can also be set automatically with the flag Automatic
start_time (PhysicalQuantity of the type time) – The start time.
Default: 0.0 * fs.
end_time (PhysicalQuantity of the type time) – The end time.
Default: The last time image.
time_resolution (PhysicalQuantity of type time) – The time interval between snapshots in the MD trajectory that are included in the analysis.
probe_size (PhysicalQuantity of type length) – The size of the probe to add into calculating the excluded volume.
Default: 0 Angstrom.
overlap_ratio (float) – The fraction of the probe and atom radii that is considered to be part of the polymer.
Default: 1.0.
samples (int) – The number of volume samples to attempt.
random_seed (int | None) – The random seed used in the random number generator. If None is given then it will be generated using values from the system entropy pool.
Default: None.
gui_worker (PolymerAnalysisWorker) – Handle to the worker, for displaying the calculation progress.
Default: None.

freeVolumes()¶

Returns:: The free volume for each image in the given trajectory.
Return type:: PhysicalQuantity of type volume

polymerTags()¶

Return the polymer tags used for the analysis.

Returns:: A list of the polymer tags.
Return type:: list

ratio()¶

Returns:: The ratio of free to total volume for each image in the given trajectory.
Return type:: ndarray

times()¶

Returns:: Times for each image used in the analysis.
Return type:: PhysicalQuantity of type time

totalVolumes()¶

Returns:: The total unit cell volume for each image in the given trajectory.
Return type:: PhysicalQuantity of type volume

Usage Examples¶

Calculate the free volume of a polystyrene melt during a molecular dynamics simulation starting from a well equilibrated configuration.

# -------------------------------------------------------------
# Initial Configuration
# -------------------------------------------------------------
bulk_configuration = nlread('Polystyrene.hdf5')[-1]

# -------------------------------------------------------------
# OPLS-AA Calculator
# -------------------------------------------------------------
potential_builder = OPLSPotentialBuilder()
calculator = potential_builder.createCalculator(bulk_configuration)
bulk_configuration.setCalculator(calculator)

# -------------------------------------------------------------
# Molecular Dynamics
# -------------------------------------------------------------
initial_velocity = ConfigurationVelocities(
    remove_center_of_mass_momentum=True
)

method = NPTMartynaTobiasKlein(
    time_step=1*femtoSecond,
    reservoir_temperature=300*Kelvin,
    reservoir_pressure=1*bar,
    thermostat_timescale=100*femtoSecond,
    barostat_timescale=500*femtoSecond,
    initial_velocity=initial_velocity,
    heating_rate=0*Kelvin/picoSecond,
)

constraints = [FixCenterOfMass()]

md_trajectory = MolecularDynamics(
    bulk_configuration,
    constraints=constraints,
    trajectory_filename='Polystyrene_Trajectory.hdf5',
    steps=100000,
    log_interval=10,
    trajectory_interval=1000,
    method=method
)

# -------------------------------------------------------------
# Calculate End to End Distance
# -------------------------------------------------------------
analyzer = FreeVolume(
      md_trajectory,
      start_time=0*ps,
      end_time=100*ps,
      time_resolution=10*ps,
      overlap_ratio=1.0,
      samples=10000
)
free_volume_ratio = analyzer.ratio()
time = analyzer.times().convertTo(ps)

# -------------------------------------------------------------
# Plot The Results
# -------------------------------------------------------------
import pylab
pylab.figure()
pylab.plot(time, free_volume_ratio)
pylab.xlabel('Time / ps')
pylab.ylabel('Free volume ratios')
pylab.savefig('Free_Volume_Ratio_Plot.png')

FreeVolume_Example.py Polystyrene.hdf5

The script will run a short molecular dynamics calculation from the given starting structure and then calculate free volume ratio of 11 images in the 101 image trajectory. This is shown in the following plot.

../../../_images/Free_Volume_Ratio_Plot.png

Notes¶

This class enables the calculation of the free volumes of different polymer systems from a MDTrajectory or BulkConfiguration.

The free volume of a polymer system is defined as the volume not occupied by atoms. The free volume of polymer structures has been shown to be related to important macroscopic properties, such as the glass transition temperature[1]. Assuming atoms can be represented as hard spheres, the free volume can be estimated using a simple Monte Carlo sampling procedure. This process randomly selects a number of positions within the structure, and tests whether or not the position is within the hard sphere radius of any atom. The ratio of the number of empty points to total number of selected positions gives the free volume ratio.

To calculate the hard sphere free volume a FreeVolume object first needs to be created. This takes a MDTrajectory or BulkConfiguration and calculates the end-to-end distances and autocorrelation function for the specified configurations. The specific frames in the MDTrajectory to be analyzed are selected using the start_time, end_time and time_resolution arguments. There are also a arguments that control the Monte Carlo procedure used to calculate the free volume. The size of the probe placed at each point can be set using the probe_size argument. By default a probe size of zero is used, equivalent to an infinitesimally small probe. The relative size of both the probe and atoms can be scaled using the overlap_ratio argument. The total number of Monte Carlo trials per configuration is set with the samples argument. Increasing this both increases the accuracy of the calculation and the calculation time. Finally the random_seed argument allows passing in a seed to the random number generator, so that calculations can be repeated.

Once the FreeVolume object is created and the volumes of each of the configurations has been calculated, the values can be queried using the remaining methods. The method ratio() returns a list of the free volume ratios of each configuration. Similarly the method freeVolumes() returns a list of the absolute free volumes. The method totalVolumes() returns a list of the total volume of each configuration, which is calculated simply from the lattice parameters.