Syntax:
set label style args keyword values ...
value arg = nvalue
nvalue = value to set sites to
range args = lo hi
lo,hi = range of values to set sites to
unique args = none
displace arg = delta
delta = max distance to displace the site
stitch args = stitchfile tstamp
stitchfile = name of STITCH file
tstamp = first or last or a floating point value
if first: then site values from first timestamp in stitch file are read in
if last: then site values from last timestamp in stitch file are read in
if floating point value: site values for this timestamp are read in
bfile args = bfilename
bfilename = name of binary file
fraction value = frac
frac = number > 0 and <= 1.0
region args = region-ID
region-ID = ID of region that sites must be part of
loop arg = all or local
all = loop over all sites
local = loop over only sites I own
if args = label2 op nvalue2
label2 = id or site or iN or dN or x or y or z
op = "<" or "<=" or ">" or "<=" or "=" or "!="
nvalue2 = value to compare site value to
Examples:
set i1 value 2 fraction 0.5 set d1 range 1.0 2.0 loop local set xyz displace 0.2 set i1 range 1 50 if x < 20 if i2 = 3 set site stitch equiaxed.st first set site stitch equiaxed.st last set site stitch equiaxed.st 1.0 set i1 stitch equiaxed.st 1.0 set d1 stitch equiaxed.st 1.0
Description:
Reset a per-site value for one or more sites. Each on-lattice or off-lattice application defines what per-site values are stored with each site in its model. When sites are created by the create_sites or read_sites commands, their per-site values may be set to zero or to values specified by those commands. This command enables the values to be changed, either before the first run, or between runs.
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. For off-lattice applications, the x or y or z or xyz coordinates of each site can be adjusted.
For label iN or dN or site, the styles value or range can be used.
For style value, the per-site 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.
For style range, the per-site quantity is set to a random value between lo and hi (inclusive). Both lo and hi should be either integer or floating-point numeric values, depending on what kind of per-site quantity is being set.
For style unique, the per-site quantity is set to the site ID, which is effectively a value unique to each site. This can be useful, for example, for setting the initial spin of each site to a unique value.
NOTE: The displace style is not yet implemented but will be soon. The following text explains how it will work for off-lattice applications.
For style displace, the label must be x or y or z or xyz For labels x or y or z, the corresponding coordinate of each site is displaced by a random distance between -delta and delta. For lables xyz the site is displaced to a new random point within a sphere of radius delta surrounding the site (or a circle for 2d models, or a line segement for 1d models).
Styles stitch and bfile can only be used for simple regular lattices. This means lattice = line (line/2n) for 1d models, square (sq/4n or sq/8n) for 2d, or simple cubic (sc/6n or sc/26n) for 3d. See the create_sites command for more details. The fraction, loop, region and if keywords are ignored for these styles; these styles set values for all sites in the system.
For style stitch, a stitch file is read to extract values associated with a specified label. The stitch file can be created by the dump stitch command or an external program. A stitch file can store multiple values for the same site, each with a different timestamp. A different number of values can also be associated with each site. The specified tstamp value is used to determine which of the multiple values is used for initializing each site. The specified time value tstamp should exist in the file for at least some sites; it can exist on all the sites or just some of them. For sites that do not have a value for the tstamp time but have a value at an earlier time, those sites will be set with the value matching the most recent time stamp stored in the file. It is an error if the file does not contain any values for the specified tstamp. A subsequent set command can be used to initialize the value of any sites in a different way.
See the examples/stitch dir for examples of SPPARKS scripts that read and write stitch files.
For style bfile, a binary file is read to extract the values associated with the specified label. The binary file must be created by an external program. It should contain 3 integer header values: Nx, Ny, Nz. These must match the size of the regular lattice defined for the enitre simulation box. For 2d simulations, Nz = 1.
The file must then contain N integer or double values, depending on whether the label is for integer or floating point site values. N must be Nx * Ny * Nz. The site values in the file must be ordered with x varying fastest, then y, and z slowest. The binary file is read by a single processor, and the values are broadcast to all processors. Each processor then extracts the subset of values from the 3d array of sites that correspond to the sites in its sub-domain of the simulation box.
The optional keywords enables selection of sites whose label quantity will be reset to a new value. Note that these optional keywords can be used in various combinations, and the if keyword can be used multiple times, to select desired sites.
The keyword fraction means that only a fraction of the sites will be reset, where 0 < frac <= 1.0. For each site a random number R is generated and the reset only occurs if R < frac.
The keyword region means that only sites in the specified region will be reset. Note that a defined region can be a union or intersection of several regions and can be either inside or outside a geometric boundary; see the region command for details.
The keyword loop determines how sites in the simulation box are looped over when their per-site quantity is reset. In general, each processor will own some subset Nlocal of the total number of sites Nglobal in the simulation box. The entire set of sites are assumed to have IDs from 1 to Nglobal. For loop all, each processor performs a loop from 1 to Nglobal and generates the new value for that site. If it owns the site, then it resets its value. This means that the changes to per-site values will be the same, independent of which processor owns which site. For loop local, each processor loops over only its sites from 1 to Nlocal. This may be faster, but if random numbers are used to determine new per-site values, it will give different answers depending on the the number of processors used.
The keyword if sets a condition that must be met in order for the per-site quantity to be reset. The per-site quantity specified by label2 is compared to the numeric nvalue2 and if the condition is not met, then the site is skipped.
Restrictions:
The stitch style is part the STITCH package. It is only enabled if SPPARKS was built with that package. See Section 2.3 for more info on how to do this.
Related commands:
Default:
The default values for the optional keywords is fraction 1.0 and loop all. No region is defined by default nor are any if-tests.