Neighbors Definition

This module reads the neighbor list from the saved file. The format of the saved neighbor list file (named as neighborlist.dat in default) must be identification of the centered particle (id), coordination number of the centered particle (cn), and identification of neighboring particles (neighborlist). That is, “id cn neighborlist”. The neighbors in the output file is sorted by their distances to the centered particle in ascending order.

This module is also heavily used to calculate the neighboring particles of a particle, or the properties about the neighboring list, which are the base for many different analyzing methods. There are many ways to recognize the neighbors, for example, by a certain number, by a certain cutoff, by particle-type specific cutoffs, by Voronoi tessellation (freud or Voro++ directly) etc. This module covers the above calculation methods and can be easily extended by individual purpose. Neighbor list of different snapshots is continuous without any gap and all start with the header id cn neighborlist. This formatting is made to be consistent with reading neighbor lists for different analyzing methods.

I. Reading Neighbors

neighbors.read_neighbors.read_neighbors() is used to read the property of neighboring particles from a saved file, as long as the format of file is compatible, as like neighborlist.dat (see below). Note that this module reads one snapshot a time to save computer memory. If you have multiple snapshots, you can import this module in a loop (see example).

Input Arguments

  • f (TextIO): opened file object which save the property of neighboring particles, f = open(filename, 'r', encoding='utf-8'). Opening the file outside of the function ensures that when reading a file containing multiple snapshots, the file pointer can move to the next snapshot.

  • Nmax (int): the maximum number of neighboring particles to consider. Setting Nmax to a sufficiently large value is ideal, with the default being 200. Nmax is defined to address the varying number of neighboring particles among different particles. In this way, we can create a regular two-dimensional NumPy array to save the property of neighboring particles.

Return

two-dimensional numpy array, with shape (nparticle, 1+Nmax_fact). Nmax_fact means the maximum coordination number for one particle in the system. The first column is the coordination number (cn). For particles with coordination number less than Nmax_fact (which is generally the case), the unoccupied positions in neighborprop (see source code) are padded with 0.

Important Notes

In the saved neighborlist.dat, the particle ID is counted from 1. While in this read module, the returned neighborlist is counted from 0. This is to facilitate subsequent indexing operations in python.

Example

  • Read neighbor list:

    from PyMatterSim.neighbors.read_neighbors import read_neighbors

filename = 'neighborlist.dat'
f = open(filename, 'r')
neighborprop = read_neighbors(f, nparticle=8100, Nmax=200)
f.close()

  • Read facearea list:

    from PyMatterSim.neighbors.read_neighbors import read_neighbors
filename = 'dump.facearea.dat'	### generated by carrying out Voronoi analysis module
f = open(filename, 'r')
neighborprop = read_neighbors(f, nparticle=8100, Nmax=200)
f.close()

  • Read in multiple snapshots:

    from PyMatterSim.neighbors.read_neighbors import read_neighbors

neighbors_snapshots = []
filename = 'neighborlist.dat'
f = open(filename, 'r')
for i in range(nsnapshots):	### number of snapshots
    neighbors_snapshots.append(read_neighbors(f, nparticle=8100, Nmax=200))
f.close()

II. Calculating Neighbors

1. Nnearests()

neighbors.calculate_neighbors.Nnearests() gets the N nearest neighbors around a particle. In this case, the coordination number is N for each particle.

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • N (int): the specified number of nearest neighbors, default 12

  • ppp (npt.NDArray): the periodic boundary conditions, setting 1 for yes and 0 for no

    default np.array([1,1,1]), that is, PBC is applied in all three dimensions for 3D box. Set np.array([1,1]) for two-dimensional system.

  • fnfile (str): the name of output file that stores the neighbor list, default neighborlist.dat

Example

from PyMatterSim.reader.dump_reader import DumpReader
from PyMatterSim.reader.reader_utils import DumpFileType
from PyMatterSim.neighbors.calculate_neighbors import Nnearests

filename = 'dump.atom'
readdump = DumpReader(filename, ndim=3, filetype=DumpFileType.LAMMPS, moltypes=None)
readdump.read_onefile()

Nnearests(readdump.snapshots, N=12, ppp=np.array([1,1,1]), fnfile='neighborlist.dat')

2. cutoffneighbors()

neighbors.calculate_neighbors.cutoffneighbors() gets the nearest neighbors around a particle by setting a global cutoff distance r_cut. Usually, the cutoff distance can be determined as the position of the first deep well in total pair correlation function.

Input Arguments

  • snapshots (reader.reader_utils.Snapshots):Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • r_cut (float): the global cutoff distance to screen the nearest neighbors

  • ppp (npt.NDArray): the periodic boundary conditions, setting 1 for yes and 0 for no

    default np.array([1,1,1]), that is, PBC is applied in all three dimensions for 3D box. Set np.array([1,1]) for two-dimensional system.

  • fnfile (str): the name of output file that stores the neighbor list, default neighborlist.dat

Example

from PyMatterSim.reader.dump_reader import DumpReader
from PyMatterSim.reader.reader_utils import DumpFileType
from PyMatterSim.neighbors.calculate_neighbors import cutoffneighbors

filename = 'dump.atom'
readdump = DumpReader(filename, ndim=3, filetype=DumpFileType.LAMMPS, moltypes=None)
readdump.read_onefile()

cutoffneighbors(readdump.snapshots, r_cut=3.8, ppp=np.array([1,1,1]), fnfile='neighborlist.dat')

3. cutoffneighbors_particletype()

neighbors.calculate_neighbors.cutoffneighbors_particletype() gets the nearest neighbors around a particle by setting a cutoff distance r_cut. Taken Cu-Zr system as an example, r_cut should be a 2D numpy array:

\[\begin{split} \begin{bmatrix} &r_{\rm cut}^{\rm Cu-Cu} & r_{\rm cut}^{\rm Cu-Zr}&\\ &r_{\rm cut}^{\rm Zr-Cu} & r_{\rm cut}^{\rm Zr-Zr}&\\ \end{bmatrix} \end{split}\]

Usually, these cutoff distances can be determined as the position of the individual first deep well in partial pair correlation function of each particle pair.

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • r_cut (npt.NDArray): the cutoff distances of each particle pair

  • ppp (npt.NDArray): the periodic boundary conditions, setting 1 for yes and 0 for no

    default np.array([1,1,1]), that is, PBC is applied in all three dimensions for 3D box. Set np.array([1,1]) for a two-dimensional system

  • fnfile (str): the name of output file that stores the neighbor list, default neighborlist.dat

Example

import numpy as np
from PyMatterSim.reader.dump_reader import DumpReader
from PyMatterSim.reader.reader_utils import DumpFileType
from PyMatterSim.neighbors.calculate_neighbors import cutoffneighbors_particletype

filename = 'dump.atom'
readdump = DumpReader(filename, ndim=3, filetype=DumpFileType.LAMMPS, moltypes=None)
readdump.read_onefile()

### a binary system
r_cut = np.zeros((2, 2))
r_cut[0, 0] = 3.6
r_cut[0, 1] = 3.4
r_cut[1, 0] = 3.4
r_cut[1, 1] = 3.9
cutoffneighbors_particletype(readdump.snapshots, r_cut=r_cut, ppp=np.array([1,1,1]), fnfile='neighborlist.dat')

III. Freud Neighbors

freud is a trajectory analysis package developed by Glotzer&###39;s group. To use freud easily, a function neighbors.freud_neighbors.convert_configuration is used to convert the dump file from our reader module to freud style. Correspondingly the list of box information and the list of the particle coordinates are returned for further analysis.

1. convert_configuration

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

Return

  • list_box (list): the list of box information for freud analysis

  • list_points (list): the list of particle positions for freud analysis

Example

from PyMatterSim.reader.dump_reader import DumpReader
from PyMatterSim.reader.reader_utils import DumpFileType
from PyMatterSim.neighbors.freud_neighbors import convert_configuration

filename = 'dump.atom'
readdump = DumpReader(filename, ndim=3, filetype=DumpFileType.LAMMPS, moltypes=None)
readdump.read_onefile()

list_box, list_points = convert_configuration(readdump.snapshots)

2. cal_neighbors

Calling neighbors.freud_neighbors.Voro_neighbors() first and then performing Voronoi analysis with voro++ package to calculate neighbors for both 2D and 3D systems. Three classes of information will be output:

  • neighbor list: atom coordination and ids of each atom

  • Voronoi face area (3D) or edge length (2D) list: between the center and each of its neighbors

  • overall information: coordination number, Voronoi volume or area of each atom

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • outputfile (str): filename of neighbor list and bond info, such as edge length (2D) or facearea(3D), default None

Return

None (result is saved to file). For neighbor list, file with name outputfile+’.neighbor.dat’. For edgelength list (2D box), file with name outputfile+’.edgelength.dat’. For facearea list (3D box), file with name outputfile+’.facearea.dat’

Example

from PyMatterSim.reader.lammps_reader_helper import read_lammps_wrapper
from PyMatterSim.neighbors.freud_neighbors import cal_neighbors

filename = 'dump_2D.atom'
snapshots = read_lammps_wrapper(filename, ndim=2)
cal_neighbors(snapshots, outputfile='dump')

IV. Voro++ direct neighbors

neighbors.voronoi_neighbors() is used to perform radical Voronoi tessellation using voro++ for both PBC and non-PBC system.

The voro++ package considers non-periodic boundary conditions by default, so there may be some negative numbers in the neighbor list for non-periodic boundary conditions (please refer to the voro++ manual to know this well).

  1. neighbors.voronoi_neighbors.voronowalls(): used for any non-periodic boundary condition(s)

  2. neighbors.voronoi_neighbors.cal_voro(): used for all periodic boundary conditions

1. get_input()

neighbors.voronoi_neighbors.get_input() is used to design input file for Voro++ by considering particle radii.

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • radii (dict): radii of particles, must be a dict like {1 : 1.28, 2 : 1.60}

    if you do not want to consider radii, set the radii the same, default {1:0.5, 2:0.5}

Return

  • position (list): input file for Voro++ with the format:

  • bounds (list): box bounds for snapshots

Example

from PyMatterSim.reader.dump_reader import DumpReader
from PyMatterSim.reader.reader_utils import DumpFileType
from PyMatterSim.neighbors.voronoi_neighbors import get_input

filename = 'dump.atom'
readdump = DumpReader(filename, ndim=3, filetype=DumpFileType.LAMMPS, moltypes=None)
readdump.read_onefile()

get_input(readdump.snapshots, radii={1:1.0, 2:1.0})

2. cal_voro()

voronoi.voropp.cal_voro() is used to perform radical Voronoi tessellation if radii are given using voro++ for periodic boundary conditions.

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • ppp (str): Make the container periodic in all three directions, default ppp='-p'

  • radii (dict): radii of particles, must be a dict like {1 : 1.28, 2 : 1.60}

    if you do not want to consider radii, set the radii the same, default {1:0.5, 2:0.5}

  • outputfile (str): filename of output, including neighborlist, facearealist, voronoi index, overall (facearea and volume of particle).

Return

  • None [saved to file]

  • for neighbor list, file with name outputfile.neighbor.dat'

  • for facearea list, file with name outputfile.facearea.dat'

  • for voronoi index, file with name outputfile.voroindex.dat'

  • for overall, file with name outputfile.overall.dat'

Output files from voroindex and overall include a header for all snapshots. neighborlist and facearealist output files are in align with the format needed in the module neighbors and have headers for each individual snapshot.

Example

from PyMatterSim.reader.lammps_reader_helper import read_lammps_wrapper
from PyMatterSim.neighbors.voronoi_neighbors import cal_voro

test_file_3d = 'dump.atom'
snapshots = read_lammps_wrapper(test_file_3d, 3)

cal_voro(snapshots, outputfile='dump')

3. voronowalls()

voronoi.voropp.voronowalls() is used to perform radical Voronoi tessellation using voro++ for periodic boundary conditions.

Input Arguments

  • snapshots (reader.reader_utils.Snapshots): Snapshots data class returned by reader.dump_reader.DumpReader from input configuration file

  • ppp (str): Make the container periodic in a desired direction

    '-px', '-py', and '-pz' for x, y, and z directions, respectively

  • radii (dict): radii of particles, must be a dict like {1 : 1.28, 2 : 1.60}

    if you do not want to consider radii, set the radii the same, default {1:0.5, 2:0.5}

  • outputfile (str): filename of output, including neighborlist, facearealist, voronoi index, overall (facearea and volume of particle).

Return

  • None [saved to file]

  • for neighbor list, file with name outputfile.neighbor.dat'

  • for facearea list, file with name outputfile.facearea.dat'

  • for voronoi index, file with name outputfile.voroindex.dat'

  • for overall, file with name outputfile.overall.dat'

Output files from voroindex and overall include a header for all snapshots. neighborlist and facearealist output files are in align with the format needed in the module neighbors and have headers for each individual snapshot.

4. indicehis()

Statistics the frequency of voronoi index from the output of voronoi analysis. Only the top 50 voronoi index will be output along with their fractions.

Input Arguments

  • inputfile (str): the filename of saved Voronoi index

  • outputfile (str): the output filename of the frequency of voronoi index, default None

Return

  • None [saved to file], frequency of Voronoi Indices

Example

from PyMatterSim.neighbors.voronoi_neighbors import indicehis

indicehis('dump.voroindex.dat', outputfile='voroindex_frction.dat')