SPPARKS WWW Site - SPPARKS Documentation - SPPARKS Commands

create_sites command

Syntax:

create_sites style arg keyword values ... 

Examples:

create_sites box
create_sites region surf value site 1
create_sites box value i2 0 basis 1 1 basis 2* 2 

Description:

This command creates "sites" on a lattice for on-lattice and off-lattice applications. For on-lattice applications it also defines a connectivity between sites that is stored as a neighbor list of nearby sites that each site interacts with.

This command is an alternative to reading in site coordinates and neighbor connectivity via the read_sites command.

To use this command, a simulation box must already exist, created via the create_box command. Likewise a lattice must also be defined using the lattice command.

In SPPARKS, a "site" is a point in space at which an application, as defined by the app_style command, can perform events. For on-lattice applications, the site is static and has a static set of neighboring sites with which it interacts. For off-lattice applications, a site is like a particle. It moves and has a dynamic neighborhood of nearby particles with which it interacts.

This command generates the set of lattice points that fall within the simulation box. For any periodic dimension, as specified by the boundary command, the simulation box size must be an integer multiple of the lattice constant, to insure consistent placement of sites near periodic boundaries. SPPARKS is careful to put exactly one site at a periodic boundary (on either side of the box), not zero or two. For non-periodic dimensions, no checking near boundaries is done; if the point is inside or on the boundary, it is a site. The one exception is that points that lie exactly on the upper boundary (in a non-periodic dimension) are considered to be outside the box. Thus in non-periodic dimensions you may need to tweak the simulation box size to get precisely the sites you want.

For the box style, all lattice points that fall inside the simulation box are stored as sites, as described in the preceding paragraph. For the region style, a lattice point must additionally be consistent with the region volume to be stored as a site. Note that a region can be specified so that its volume is either inside or outside a geometric boundary.

For on-lattice applications, after sites have been created, a neighbor list is also generated for each site, as defined by each lattice style. Think of this as the set of lattice points near a central site, with which it interacts in the sense defined by an application. If the simulation box is periodic in a dimension, the neighbors of a central site may include sites on the other side of the box. This will not be the case for a non-periodic dimension. If some sites do not exist, e.g. when using the region style, then some sites will not have a complete set of neighbors.


SPPARKS attempts to create sites with consecutive IDs from 1 to N, where N is the total number of sites that fill the simulation box. The numbering is the same, independent of the number of processors. Note that if the simulation box is non-periodic or the region style is used, some sites may not exist, so the site IDs will not typically be contiguous. I.e. the largest ID will be greater than the number of created sites.

Depending on the application, each site stores zero of more integer and floating-point values. By default these are set to zero when a site is created by this command. The value and basis keywords can override the default.

The value keyword specifies a per-site value that will be assigned to every site as it is created. The label determines which per-site quantity is set. iN and dN mean the Nth integer or floating-point quantity, with 1 <= N <= Nmax. Nmax is defined by the application. If label is specified as site it is the same as i1. The quantity is set to the specified nvalue, which should be either an integer or floating-point numeric value, depending on what kind of per-site quantity is being set.

The basis keyword can be used to override the value keyword setting for individual basis sites as each unit cell is created. The per-site quantity (e.g. i2) specified by the value keyword is set for basis sites M. The quantity is set to the specified nvalue for the basis keyword, instead of the nvalue from the value keyword. See the lattice command for specifics on how basis atoms and unit cells are defined for each lattice style.

M can be specified in one of two ways. An explicit numeric value can be used, such as 2. A wild-card asterisk can also be used in place of or in conjunction with the M argument to specify multiple basis sites together. This takes the form "*" or "*n" or "n*" or "m*n". If N = the total number of basis sites, then an asterisk with no numeric values means all sites from 1 to N. A leading asterisk means all sites from 1 to n (inclusive). A trailing asterisk means all sites from n to N (inclusive). A middle asterisk means all sites from m to n (inclusive).

Restrictions:

The app_style command must be used to define an application before using the create_sites command. The create_box command must be used to to define the simulation box before using the create_sites_command.

Related commands:

lattice, region, create_box, read_sites

Default: none