Syntax:
read_sites file
Examples:
read_sites data.potts read_sites ../run7/data.potts.gz
Description:
Read in a data file containing information SPPARKS needs to setup an on-lattice or off-lattice application. The file can be ASCII text or a gzipped text file (detected by a .gz suffix). This is one of 2 ways to specify event sites; see the create_sites command for another method.
A data file has a header and a body, as described below. The body of the file contains up to 3 sections in the following order: Sites, Neighbors, Values. Sites defines the coordinates of event sites. Neighbors define the neighbors of each site (only for on-lattice applications). Values assign per-site values to each site, which can also be done via the set command.
The read_sites command can be used in one of 3 scenarios:
If a simulation box has not already been created and no event sites exist, then the data file defines the box size (in the header), and it must define Sites. It must also define Neighbors for on-lattice applications. The Values section is optional, since these can be set later via the set command.
If a simulation box has already been defined (by the "create_box" command), but no sites have previously been defined, then the data file must define Sites. It must also define Neighbors for on-lattice applications. The Values section is optional. If the data file defines a box size, it must be consistent with the simulation box that already exists.
If a simulation box has already been defined, and sites have previosly been defined (by the "create_sites" command or a previous read_sites command), then no Sites or Neighbors can be specfied, but the Values section is used to set all or a subset of the per-site values defined by the application. This is a means of continuing a previous simulation using a file written by the dump sites command as a restart file, since it writes in the format that this command reads.
Note that the periodicity of the simulation box, as defined by the boundary command is not considered by this command when defining sites or neighbors. It is up to you to insure sites are not duplicated on a periodic boundary, or that a site's neighbor list does not include sites that are on the other side of the simulation box when the boundary is not periodic. This is in contrast to the create_sites command which accounts for both of these issues when defining sites and their neighbors.
The first line of the header of the data file is always skipped; it typically contains a description of the file. Then lines are read one at a time. Lines can have a trailing comment starting with '#' that is ignored. If the line is blank (only whitespace after comment is deleted), it is skipped. If the line contains a header keyword, the corresponding value(s) is read from the line. If it doesn't contain a header keyword, the line begins the body of the file.
The body of the file contains zero or more sections. The first line of a section has only a keyword. The next line is skipped. The remaining lines of the section contain values. The number of lines depends on the section keyword as described below. Zero or more blank lines can be used between sections. Sections can appear in any order, with a few exceptions as noted below.
The formatting of individual lines in the data file (indentation, spacing between words and numbers) is not important except that header and section keywords (e.g. dimension, xlo xhi, Sites, Values) must be capitalized as shown and can't have extra white space between their words - e.g. two spaces or a tab between "xlo and "xhi" is not valid.
These are the recognized header keywords. Header lines can come in any order. The value(s) are read from the beginning of the line. Thus the keyword sites should be in a line like "1000 sites"; the keyword ylo yhi should be in a line like "-10.0 10.0 ylo yhi". All these numeric settings have a default value of 0, except the lo/hi box size defaults which are -0.5 and 0.5. A line need only appear if the value is different than the default. If the keyword values have already been defined (e.g. box sizes for a previously created simulation box), then the values in the data file must match.
The max neighbors setting is only needed if the file contains a Neighbors section, which is only used for on-lattice applications.
The values setting is only needed if a Values section is included in the file, and if it does not list per-site info for all the integer and floating point values defined by the application. If only a subset of per-site values are listed in each line, then the values setting labels what they are. The labels have the same syntax as those defined by the dump sites command, namely "id", "site", "iN", or "dN". Note that "id" must always be included and come first, so that SPPARKS can assign the values that follow to the correct site.
The simulation box size is determined by the lo/hi settings. For 2d simulations, the zlo zhi values should be set to bound the z coords for atoms that appear in the file; the default of -0.5 0.5 is valid if all z coords are 0.0. The same rules hold for ylo and yhi for 1d simulations.
These are the possible section keywords for the body of the file: Sites, Neighbors, Values.
Each section is listed below. The format of each section is described including the number of lines it must contain and rules (if any) for where it can appear in the data file.
Any individual line in the various sections can have a trailing comment starting with "#" for annotation purposes. E.g. in the Sites section:
10 10.0 5.0 6.0 # impuity site
Sites section:
ID = global site ID (1-N) x y z = coordinates of site
101 7.0 0.0 3.0
There must be N lines in this section where N = number of sites and is defined by the sites keyword in the header section of the file. The lines can appear in any order.
Neighbors section:
ID = global site ID (1-N) n1 n2 n3 ... = IDs of neighbor sites
101 7 32 15 1004 ...
There must be N lines in this section where N = number of sites and is defined by the sites keyword in the header section of the file. The lines can appear in any order.
The number of neighbors can vary from site to site, but there can be no more than max neighbors for any one site. The neighbors of an individual site can be listed in any order.
Values section:
ID = global site ID (1-N) value1,value2,... = integer or floating point values for the site
101 1 3 4.0
There must be N lines in this section where N = number of sites and is defined by the sites keyword in the header section of the file. The lines can appear in any order.
The number of values per site depends on the comment keyword in the header section of the file. If it is not defined, then the default line syntax is assumed to be:
meaning that all per-site values must be listed on each line. In the default case, they are listed in order, with the integer values first, followed by the floating-point values.
Restrictions:
To write gzipped dump files, you must compile SPPARKS with the -DSPPARKS_GZIP option - see the Making SPPARKS section of the documentation.
Related commands:
Default: none