dump_modify command

Syntax:

dump_modify dump-ID keyword values ... 

• dump-ID = ID of dump to modify
• one or more keyword/value pairs may be appended
• these keywords apply to various dump styles
• keyword = delay or delta or fileper or first or flush or logfreq or loglinfreq or nfile or pad or region or sort or thresh or tol or vtk

    delay value = tdelay
      tdelay = delay dump until at least this time (seconds)
    delta arg = dt
      dt = time increment between dumps (seconds)
    fileper arg = Np
      Np = write one file for every this many processors
    first arg = Nfirst
      Nfirst = index of first snapshot produced, useful when restarting
    flush arg = yes or no
    logfreq or loglinfreq values = N factor
      N = number of repetitions per interval
      factor = scale factor between intervals
    nfile arg = Nf
      Nf = write this many files, one from each of Nf processors
    pad arg = Nchar = # of characters to convert timestep to
    region arg = region-ID or "none"
    sort arg = off or id or N or -N
       off = no sorting of per-site lines within a snapshot
       id = sort per-site lines by atom ID
       N = sort per-site lines in ascending order by the Nth column
       -N = sort per-site lines in descending order by the Nth column
    thresh args = attribute operation value
      attribute = same fields (id,lattice,x,etc) used by dump command
      operation = "<" or "<=" or ">" or ">=" or "==" or "!="
      value = numeric value to compare to
      these 3 args can be replaced by the word "none" to turn off thresholding
    tol value = epsilon
      epsilon = output a snapshot if time is within epsilon of target time (seconds)
    vtk args = Nx Ny Nz minval maxval
      Nx,Ny,Nz = site extent in x,y,z dimensions
      minval,maxval = min/max of any site's value 
  

• these keywords apply only to the image style
• keyword = backcolor or boundcolor or boxcolor or color or cwrap or dwrap or scolor or sdiam or smap

    backcolor arg = color
      color = name of color for background
    boundcolor arg = color
      color = name of color for boundaries between sites
    boxcolor arg = color
      color = name of color for box lines
    color args = name R G B
      name = name of color
      R,G,B = red/green/blue numeric values from 0.0 to 1.0
    cwrap arg = yes or no
      yes/no = do or do not wrap out-of-range color values into the defined crange
    dwrap arg = yes or no
      yes/no = do or do not wrap out-of-range diameter values into the defined drange
    scolor args = I color
      I = integer value or range of values (see below)
      color = name of color or color1/color2/... or random
    sdiam args = I diam
      I = integer value or range of values (see below)
      diam = diameter of sites of that value
    smap args = lo hi style delta N entry1 entry2 ... entryN
      lo = number or min = lower bound of range of color map
      hi = number or max = upper bound of range of color map
      style = 2 letters = "c" or "d" or "s" plus "a" or "f"
        "c" for continuous
        "d" for discrete
        "s" for sequential
        "a" for absolute
        "f" for fractional
      delta = binsize (only used for style "s", otherwise ignored)
        binsize = range is divided into bins of this width
      N = # of subsequent entries
      entry = value color (for continuous style)
        value = number or min or max = single value within range
        color = name of color used for that value
      entry = lo hi color (for discrete style)
        lo/hi = number or min or max = lower/upper bound of subset of range
        color = name of color used for that subset of values
      entry = color (for sequential style)
        color = name of color used for a bin of values 
  

Examples:

dump_modify 1 delay 30.0
dump_modify 1 loglinfreq 7 10.0 delay 100.0 flush yes
dump_modify mine thresh energy > 0.0 thresh id <= 1000 

Description:

Modify the parameters of a previously defined dump command. Not all parameters are relevant to all dump styles.

These keywords apply to various dump styles, including the dump image style, except as noted below. The descriptions give details.

The delay keyword will suppress output until the current time is tdelay or greater. Note that tdelay is not an elapsed time since the start of the run, but an absolute time.

The delta keyword will reset the dump interval delta used in the original dump command.

The fileper keyword is documented below with the nfile keyword.

The first keyword can be used to set the counter used to enumerate successive snapshots. This can be useful when continuing/restarting a previous simulation, so as not to overlap new snapshots with previous output.

The counter is used in the TIMESTEP field of snapshots produced by the dump text or dump sites styles. It is also used in the filenames generated by the "*" wildcard character in the user-specified dump file name, as explained on the dump command doc page.

The flush option determines whether a flush operation in invoked after a dump snapshot is written to the dump file. A flush insures the output in that file is current (no buffering by the OS), even if SPPARKS halts before the simulation completes. The flush option is only relevant to the dump text style.

The logfreq and loglinfreq keywords will produce output at progressively larger intervals during the course of a simulation. There will be N outputs per interval where the size of each interval is initially delta and then scales up by factor each time. See the stats command for more information on how the output times are specified.

If N is specified as 0, then this will turn off logarithmic output, and revert to regular output every delta seconds.

The nfile or fileper keywords currently apply only to the text dump style. They can be used in conjunction with the "%" wildcard character in the specified dump file name. As explained on the dump command doc page, the "%" character causes the dump file to be written in pieces, one piece for each of P processors. By default P = the number of processors the simulation is running on. The nfile or fileper keyword can be used to set P to a smaller value, which can be more efficient when running on a large number of processors.

The nfile keyword sets P to the specified Nf value. For example, if Nf = 4, and the simulation is running on 100 processors, 4 files will be written, by processors 0,25,50,75. Each will collect information from itself and the next 24 processors and write it to a dump file.

For the fileper keyword, the specified value of Np means write one file for every Np processors. For example, if Np = 4, every 4th processor (0,4,8,12,etc) will collect information from itself and the next 3 processors and write it to a dump file.

The pad keyword only applies when the dump filename is specified with a wildcard "*" character which becomes the timestep. If pad is 0, which is the default, the timestep is converted into a string of unpadded length, e.g. 100 or 12000 or 2000000. When pad is specified with Nchar > 0, the string is padded with leading zeroes so they are all the same length = Nchar. For example, pad 7 would yield 0000100, 0012000, 2000000. This can be useful so that post-processing programs can easily read the files in ascending timestep order.

The region keyword allows sub-selection of lattice sites to output. If specified, only sites in the region will be written to the dump file or included in the image. Only one region can be applied as a filter (the last one specified). See the region command for more details. Note that a region can be defined as the "inside" or "outside" of a geometric shape, and it can be the "union" or "intersection" of a series of simpler regions.

The sort keyword determines whether lines of per-site output in a snapshot are sorted or not. A sort value of off means they will typically be written in indeterminate order, at least in parallel, since the sites are written to file in per-processor chunks. A sort value of id means sort the output by site ID. A sort value of N or -N means sort the output by the value in the Nth column of per-site info in either ascending or descending order.

If multiple processors are writing the dump file, via the "%" wildcard in the dump filename, then sorting cannot be performed.

IMPORTANT NOTE: Sorting dump file output requires extra overhead in terms of CPU and communication cost, as well as memory, versus unsorted output.

The thresh keyword allows sub-selection of lattice sites to output. Multiple thresholds can be specified. Specifying "none" turns off all threshold criteria. If thresholds are specified, only sites whose attributes meet all the threshold criteria are written to the dump file or included in the image. The possible attributes that can be tested for are the same as the fields that can be specified in the dump command. Note that different attributes can be output by the dump command than are used as threshold criteria by the dump_modify command. E.g. you can output the coordinates and propensity of sites whose energy is above some threshold.

The tol keyword will trigger a dump snapshot if the current time is within epsilon of the target time for dump output.

This can be useful when running with the sweep command and the time interval per sweep leads to small round-off differences in time. For example, if the time per sweep is 1/26 (for 26 neighbors per lattice site) and delta = 1.0, but an snapshot is not written at time 2.0 but at 2.0385 (0.385 = 1/26). I.e. one sweep beyond the desired dump time. Using a tol < 1/26 will give the desired snapshots at 1,2,3,4, etc.

The vtk keyword only applies to the vtk style, for which it is required. As explained on the dump vtk doc page, this style can only be used to output a single per-site value for a regular lattice of sites. The settings for this command provide information about the underlying lattice and site value bounds.

The nx,ny,nz settings are the extent of the regular lattice of sites, whether it is periodic in any dimension or not. Use a value of nz = 1 for 2d simulations and ny = nz = 1 for 1d simulations.

The minvalue and maxvalue settings are the min/max bounds within which all the per-site values for the specified single per-site field will fall. Note that the actual values do not need to extend to these bounds. E.g. the maximum initial spin value might be 1000 (e.g. for app_style potts), but at later times an individual snapshot would have no spins > 900.

These keywords apply only to the dump image style. The descriptions give details.

The backcolor sets the background color of the images. The color name can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option.

The boundcolor keyword sets the color used to draw boundaries between sites, each of which is a set of 4 cylinders, as described in the dump image doc page. The color name can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option.

The drawing of boundaries between neighboring sites is enabled by the boundary keyword of the dump image command.

The boxcolor keyword sets the color of the simulation box drawn around the sites in each image. See the "dump image box" command for how to specify that a box be drawn. The color name can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option.

The color keyword allows definition of a new color name, in addition to the 140-predefined colors (see below), and associates 3 red/green/blue RGB values with that color name. The color name can then be used with any other dump_modify keyword that takes a color name as a value. The RGB values should each be floating point values between 0.0 and 1.0 inclusive.

When a color name is converted to RGB values, the user-defined color names are searched first, then the 140 pre-defined color names. This means you can also use the color keyword to overwrite one of the pre-defined color names with new RBG values.

The cwrap keyword enables wrapping of integer values used to deterimine site colors in the image, into the range specified by the crange keyword in the dump image command.

The crange keyword defines a range of values lo to hi. If the cwrap argument is no, which is the default, then values outside the range lo to hi are clipped to that range. I.e. values < lo become lo and values > hi become hi. This means out-of-range values will all be drawn with either the lo or hi color, which may not be what you want.

If the cwrap argument is yes, then values outside the range lo to hi are wrapped back into the range. E.g. a value of hi+1 becomes lo, hi+2 becomes lo+1, etc. Similarly, a value of lo-1 becomes hi, lo-2 becomes hi-1, etc. This is a way to map a huge number N of possible integer values into a smaller number of M crange colors. This may be required if N = 2 billion spin values, since memory for that many colors cannot be allocated. Using a crange with M = 10000 would work in that scenario.

The dwrap keyword enables wrapping of integer values used to deterimine site diameters in the image, into the range specified by the drange keyword in the dump image command. It's purpose and the way it operates on diamenters is exactly the same as how the cwrap keyword operates of colors, as described above.

The scolor keyword can be used with the dump image command, when its site color setting is an integer attribute, and a crange setting from lo to hi has been specified to set the color associated with each integer value.

The specified I value should be an integer from lo to hi inclusive. A wildcard asterisk can be used in place of or in conjunction with the type argument to specify a range of values. This takes the form "*" or "*n" or "n*" or "m*n". An asterisk with no numeric values means all values from lo to hi. A leading asterisk means all values from lo to n (inclusive). A trailing asterisk means all values from n to hi (inclusive). A middle asterisk means all values from m to n (inclusive).

The specified color can be a single color which is any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option. Or it can be two or more colors separated by a "/" character, e.g. red/green/blue. In the former case, that color is assigned to all the specified integer values. In the latter case, the list of colors are assigned in a round-robin fashion to each of the specified integer values.

The specified color can also be the word random. In this case, random red/blue/green color values, each from 0.0 to 1.0, are generated for each I value. This is a convenient way to assign a large number of random colors, without having to list them explicitly by name.

The sdiam keyword can be used with the dump image command, when its site diameter setting is an integer attribute, and a drange setting from lo to hi has been specified to set the diameter associated with each integer value. The specified I value should be an integer from lo to hi. As with the scolor keyword, a wildcard asterisk can be used as part of the I argument to specify a range of values.

The smap keyword can be used with the dump image command, when its site color setting is a floating point attribute, to setup a color map. The color map is used to assign a specific RGB (red/green/blue) color value to an individual site when it is drawn, based on the atom's attribute, which is a numeric value, e.g. its x coordinate, if the attribute "x" was specified.

The basic idea of a color map is that the site-attribute will be within a range of values, and that range is associated with a series of colors (e.g. red, blue, green). An sites's specific value (x = -3.2) can then mapped to the series of colors (e.g. halfway between red and blue), and a specific color is determined via an interpolation procedure.

There are many possible options for the color map, enabled by the smap keyword. Here are the details.

The lo and hi settings determine the range of values allowed for the site attribute. If numeric values are used for lo and/or hi, then values that are lower/higher than lo/hi are set to either lo or hi. I.e. the range is static. If lo is specified as min or hi as max then the range is dynamic, and the lower and/or upper bound will be calculated each time an image is drawn, based on the set of sites being visualized.

The style setting is two letters, such as "ca". The first letter is either "c" for continuous, "d" for discrete, or "s" for sequential. The second letter is either "a" for absolute, or "f" for fractional.

A continuous color map is one in which the color changes continuously from value to value within the range. A discrete color map is one in which discrete colors are assigned to sub-ranges of values within the range. A sequential color map is one in which discrete colors are assigned to a sequence of sub-ranges of values covering the entire range.

An absolute color map is one in which the values to which colors are assigned are specified explicitly as values within the range. A fractional color map is one in which the values to which colors are assigned are specified as a fractional portion of the range. For example if the range is from -10.0 to 10.0, and the color red is to be assigned to atoms with a value of 5.0, then for an absolute color map the number 5.0 would be used. But for a fractional map, the number 0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.

The delta setting is only specified if the style is sequential. It specifies the bin size to use within the range for assigning consecutive colors to. For example, if the range is from -10.0 to 10.0 and a delta of 1.0 is used, then 20 colors will be assigned to the range. The first will be from -10.0 <= color1 < -9.0, then 2nd from -9.0 <= color2 < -8.0, etc.

The N setting is how many entries follow. The format of the entries depends on whether the color map style is continuous, discrete or sequential. In all cases the color setting can be any of the 140 pre-defined colors (see below) or a color name defined by the dump_modify color option.

For continuous color maps, each entry has a value and a color. The value is either a number within the range of values or min or max. The value of the first entry must be min and the value of the last entry must be max. Any entries in between must have increasing values. Note that numeric values can be specified either as absolute numbers or as fractions (0.0 to 1.0) of the range, depending on the "a" or "f" in the style setting for the color map.

Here is how the entries are used to determine the color of an individual site, given the value X of its site attribute. X will fall between 2 of the entry values. The color of the site is linearly interpolated (in each of the RGB values) between the 2 colors associated with those entries. For example, if X = -5.0 and the 2 surrounding entries are "red" at -10.0 and "blue" at 0.0, then the site's color will be halfway between "red" and "blue", which happens to be "purple".

For discrete color maps, each entry has a lo and hi value and a color. The lo and hi settings are either numbers within the range of values or lo can be min or hi can be max. The lo and hi settings of the last entry must be min and max. Other entries can have any lo and hi values and the sub-ranges of different values can overlap. Note that numeric lo and hi values can be specified either as absolute numbers or as fractions (0.0 to 1.0) of the range, depending on the "a" or "f" in the style setting for the color map.

Here is how the entries are used to determine the color of an individual site, given the value X of its site attribute. The entries are scanned from first to last. The first time that lo <= X <= hi, X is assigned the color associated with that entry. You can think of the last entry as assigning a default color (since it will always be matched by X), and the earlier entries as colors that override the default. Also note that no interpolation of a color RGB is done. All sites will be drawn with one of the colors in the list of entries.

For sequential color maps, each entry has only a color. Here is how the entries are used to determine the color of an individual site, given the value X of its site attribute. The range is partitioned into N bins of width binsize. Thus X will fall in a specific bin from 1 to N, say the Mth bin. If it falls on a boundary between 2 bins, it is considered to be in the higher of the 2 bins. Each bin is assigned a color from the E entries. If E < N, then the colors are repeated. For example if 2 entries with colors red and green are specified, then the odd numbered bins will be red and the even bins green. The color of the site is the color of its bin. Note that the sequential color map is really a shorthand way of defining a discrete color map without having to specify where all the bin boundaries are.

Restrictions:

This command can only be used as part of the lattice-based applications. See the app_style command for further details.

Related commands:

dump, dump image

Default:

The option defaults are

• backcolor = black
• boundcolor = white
• boxcolor = yellow
• color = 140 color names are pre-defined as listed below
• cwrap = no
• delay = 0.0
• delta = value for delta used in the dump command
• dwrap = no
• flush = yes
• logfreq = off
• loglinfreq = off
• pad = 0
• region = none
• scolor = * c1/c2/.../c140 where c1-c140 are the names of the 140 pre-defined colors
• sdiam = * 1.0
• smap = min max cf 2 min blue max red
• thresh = none
• tol = 0.0

These are the 140 colors that SPPARKS pre-defines for use with the dump image and dump_modify commands. Additional colors can be defined with the dump_modify color command. The 3 numbers listed for each name are the RGB (red/green/blue) values. Divide each value by 255 to get the equivalent 0.0 to 1.0 value.