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. .. _installation: 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. :class:`~tcc_python_scripts.file_readers.snapshot.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 :class:`~tcc_python_scripts.file_readers.snapshot.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 :class:`~tcc_python_scripts.file_readers.snapshot.Snapshot` object. Example XYZ file reader script -------------------------------- The :meth:`tcc_python_scripts.file_readers.xyz.read()` method is a generator which returns sequential :class:`~tcc_python_scripts.file_readers.snapshot.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 :class:`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) [, , ] 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 :meth:`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 :meth:`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: :doc:`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 :ref:`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 :meth:`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 :func:`~tcc_python_scripts.post_processing.net.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.