Python Scripts

A number of Python scripts are located in the tcc_python_scripts folder in the root directory of the TCC. These are provided for convenience interfacing with the TCC and post processing results.

Python Scrips Installation

To in use these python scripts as modules they must be installed locally. From the root TCC folder execute the command.

pip install .

If you are doing development work on the scripts, you can use the -e flag to create a “linked” .egg module which means the module is loaded from the directory at runtime. This avoids having to reinstall every time changes are made.

pip install -e .

Coordinate File Readers

The scripts in the file readers folder are designed to provide a unified interface for reading from different coordinate file types. These allow reading in configurations from XYZ, dynamo and .atom (LAMMPS) files.

Snapshot is the base class from which other file readers are defined. We define a snapshot as a single configuration of particles at one time. Regardless of the file format read, the data is stored in a common Snapshot object. Multiple snapshots may be present in an XYZ or atom file and these can be read in and each will be stored in a separate Snapshot object.

Example XYZ file reader script

The tcc_python_scripts.file_readers.xyz.read() method is a generator which returns sequential Snapshot objects from a file. The generator will iterate over all snapshots in the file returning them sequentially.

>>> xyz_file = xyz.read("sample.xyz")
... for frame in xyz_file:
...     print(frame.num_particles)
59
57
58

To load only some of the frames you can use the enumerate function.

>>> for frame_number, frame in enumerate(xyz.read("sample.xyz")):
...     if frame_number < 1:
...         print(frame.num_particles)
59

For more complex operations such as reading every other frame you can use the same method.

>>> for frame_number, frame in enumerate(xyz.read("sample.xyz"):
...     if frame_number %2 == 0:
...         print(frame.num_particles)
59
58

To retrieve all snapshots at once use the python list function to return a list containing all of the snapshots.

>>> from tcc_python_scripts.file_readers import xyz
...
... particle_coordinates = list(xyz.read("sample.xyz"))
... print(particle_coordinates)
[<snapshot n=59 t=None>, <snapshot n=57 t=None>, <snapshot n=58 t=None>]

Python Wrapper

The TCC Python wrapper is designed to be a lightweight way of automating simple TCC analyses and as such can analyse a single configuration at a time. Configurations are most easily loaded using the above file readers.

The tcc_python_scripts.tcc.wrapper.TCCWrapper.run() method will run the TCC with the provided coordinates and return the cluster counts after completion. By default the script will run the TCC in a temporary directory, deleting it after the run is complete. To save the results, for example raw or cluster XYZ files you can provide a directory to the tcc_python_scripts.tcc.wrapper.TCCWrapper.run() method where the results will be saved.

Input parameters are set to default values unless specified. They can be set by adding values to the relevant input_parameters attribute. For details on in input parameters see: TCC input parameters. Because the input parameters must be placed in the appropriate section, the input parameter must be preceded by the name of its section

TCC_setup.input_parameters['Run']['Frames'] = 1
TCC_setup.input_parameters['Output']['raw'] = 1

If the Python scripts are installed using the recommended method in the Python Scrips Installation section above, they can be run from anywhere on your computer. For this reason the folder which contains the compiled TCC executable must be specified in the invoking script using the tcc_python_scripts.tcc.wrapper.TCCWrapper.set_tcc_executable_directory() method. An example of this is shown below.

Example Wrapper Script

from tcc_python_scripts.file_readers import xyz
from tcc_python_scripts.tcc import wrapper

# Open a TCCWrapper object - this holds information about the simulation we want to run
TCC_setup = wrapper.TCCWrapper()
# Specify the directory that contains the compiled TCC executable. This can be a relative or static path.
TCC_setup.set_tcc_executable_directory(".")

# Get the box size. This can be read from a file or input manually
box = [26.996, 26.9987, 21.7012]

# Get the coordinates. The file_readers scripts are a good way to read in coordinates from a file.
particle_coordinates = list(xyz.read("sample_ka.xyz"))[0].particle_coordinates

TCC_setup.input_parameters['Run']['Frames'] = 1
results = TCC_setup.run(box, particle_coordinates)

print(results['Number of clusters'])
print("\n\n")
print(results['Mean Pop Per Frame'])

Net TCC

This is a simple python script to post process TCC output to find net TCC clusters. Written by Francesco Turci - February 2016, edited by Peter Crowther - March 2018.

Description of net clusters

The cluster populations output by the TCC are gross populations. This means that every particle in each cluster is reported. Some of these results are not very interesting since we know that the incidence of smaller clusters is much higher than that of larger clusters, e.g. almost everything is always in a 5A, 6A and 7A cluster.

A different measure of clusters is to consider the largest cluster each particle occurs in. If a particle is in an 11A and a 5A then we report only the 11A. We call these the net cluster populations.

This definition relies on a hierarchy of cluster types which determines which is the “most important” cluster a particle can appear in. Usually we define this priority list as the lowest energy structure for each number of particles in decreasing order of particle size for the system being considered. We give some examples of such priority lists for common structures below.

Using the net cluster script

Requires Python 3 and NumPy.

The list of clusters considered is determined by the priority list. The clusters listed first will be those of highest priority in the net calculation, those listed last will be lowest priority.

The code requires a TCC raw file for each cluster specified in the priority list. The net script can be run directly from the command line or by calling the net_cluster_calculation() function.

To run from the command line

The required command line argument is the directory containing the raw files and the priority list. For example:

./net.py ./raw_output  (FCC, 13A, 12E, 11F, 10B, 9B, 8B, sp5c, sp4c, sp3c)

The priority list must have the cluster names spelled exactly as the extensions on the raw files and the list must be in round brackets. The results are averaged over all frames in the input files and are output as a text file.

To run from a Python script

from tcc_python_scripts.post_processing import net
net.net_cluster_calculation("./raw_output, [FCC, 13A, 12E, 11F, 10B, 9B, 8B, sp5c, sp4c, sp3c])

Cluster priority lists for common systems

Hard Spheres: (FCC, 13A, 12E, 11F, 10B, 9B, 8B, sp5c, sp4c, sp3c)

Kob-Andersen: (13K, 12K, 11A, 10K, 9K, 8K, 7K, sp4c, sp3c)

Wahnstrom: (13A, 12B, 11W, 10B, 9B, 8A, sp5c, sp4c, sp3c)

Lennard-Jones: (13A, 12B, 11C, 10B, 9B, 8B, sp5c, sp4c, sp3c)

Sticky Spheres: (FCC, HCP, 13B, 12E, 11F, 10B, 9B, 8B, sp5c, sp4c, sp3c)

Cluster Movie Maker Script

To output pretty movies of the TCC requires combining the data from a subset of clusters into a single xyz file. This is done by the maovie maker script.

Running the script

Before running the script run the TCC with RAW output turned on. The arguments for the movie maker script are, the name of the xyz file containing particle coordinates, the stub of the raw file name specifying the location of the raw files relative to the current working directory and a space separated cluster list in order of decreasing priority.

If the script is run in a directory containing sample.xyz and a folder raw_output, containing the RAW files sample.xyz.rcAA1.88.rcAB1.88.rcBB1.88.Vor1.fc1.PBCs1.raw_6A etc. the command to create a hard sphere movie would be:

python cluster_movie_maker_script.py sample.xyz raw_output/sample.xyz.rcAA1.88.rcAB1.88.rcBB1.88.Vor1.fc1.PBCs1.raw_ "FCC 13A 12E 11F 10B 9B 8B sp5c sp4c sp3c"

Note that the second argument which indicates the location of the RAW files omits the cluster type. Only the common stub is given.