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 = append or buffer or every or fileper or first or flush or format or nfile or pad or region or thresh
*append* arg = *yes* or *no*
*buffer* arg = *yes* or *no*
*every* arg = N
N = dump every this many timesteps
N can be a variable (see below)
*fileper* arg = Np
Np = write one file for every this many processors
*first* arg = *yes* or *no*
*flush* arg = *yes* or *no*
*format* args = *line* string, *int* string, *float* string, M string, or *none*
string = C-style format string
M = integer from 1 to N, where N = # of per-atom quantities being output
*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"
*thresh* args = attribute operation value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
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
these keywords apply only to the (image} and movie styles
keyword = bcolor or bdiam or backcolor or bitrate or boxcolor or cmap or color or framerate or gcolor or glinecolor or pcolor or pdiam or scolor or slinecolor
*backcolor* arg = color
color = name of color for background
*bitrate* arg = rate
rate = target bitrate for movie in kbps
*boxcolor* arg = color
color = name of color for box lines
*cmap* args = mode lo hi style delta N entry1 entry2 ... entryN
mode = *particle* or *grid* or *surf* or *gridx* or *gridy* or *gridz*
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
*color* args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
*framerate* arg = fps
fps = frames per second for movie
*gcolor* args = proc color
proc = proc ID or range of IDs (see below)
color = name of color or color1/color2/...
*glinecolor* arg = color
color = name of color for grid cell outlines
*gridgroup* arg = group-ID
group-ID = name of a user-defined grid group, see the :ref:`group<group>` command
*pcolor* args = type color
type = particle type or range of types or proc ID or range of IDs (see below)
color = name of color or color1/color2/...
*pdiam* args = type diam
type = particle type or range of types (see below)
diam = diameter of particles of that type (distance units)
*scolor* args = proc color
proc = proc ID or range of IDs (see below)
color = name of color for surf one option
*slinecolor* arg = color
color = name of color for surface element outlines
*surfgroup* arg = group-ID
group-ID = name of a user-defined surf group, see the :ref:`group<group>` command
Examples:
dump_modify 1 format line "%d %d %20.15g %g %g"
dump_modify 1 format float %20.15g
dump_modify myDump thresh x < 0.0 thresh vx >= 3.0
dump_modify 1 every 1000
dump_modify 1 every v_myVar
dump_modify 1 cmap particle min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
Description:
Modify the parameters of a previously defined dump command. Not all parameters are relevant to all dump styles.
These keywords apply to all dump styles unless otherwise noted. The descriptions give details.
The append keyword applies to all dump styles except image and movie. It also applies only to text output files, not to binary or gzipped files. If specified as yes, then dump snapshots are appended to the end of an existing dump file. If specified as no, then a new dump file will be created which will overwrite an existing file with the same name. This keyword can only take effect if the dump_modify command is used after the dump command, but before the first command that causes dump snapshots to be output, e.g. a run command. Once the dump file has been opened, this keyword has no further effect.
The buffer keyword applies only all dump styles except image and movie. It also applies only to text output files, not to binary or gzipped files. If specified as yes, which is the default, then each processor writes its output into an internal text buffer, which is then sent to the processor(s) which perform file writes, and written by those processors(s) as one large chunk of text. If specified as no, each processor sends its per-atom data in binary format to the processor(s) which perform file wirtes, and those processor(s) format and write it line by line into the output file.
The buffering mode is typically faster since each processor does the relatively expensive task of formatting the output for its own atoms. However it requires about twice the memory (per processor) for the extra buffering.
The every keyword changes the dump frequency originally specified by the dump command to a new value. The every keyword can be specified in one of two ways. It can be a numeric value in which case it must be > 0. Or it can be an equal-style variable, which should be specified as v_name, where name is the variable name. In this case, the variable is evaluated at the beginning of a run to determine the next timestep at which a dump snapshot will be written out. On that timestep, the variable will be evaluated again to determine the next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() math functions for equal-style variables, as examples of useful functions to use in this context. Other similar math functions could easily be added as options for equal-style variables. When using the variable option with the every keyword, you also need to use the first option if you want an initial snapshot written to the dump file.
For example, the following commands will write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
variable s equal logfreq(10,3,10)
dump 1 particle all 100 tmp.dump id type x y z
dump_modify 1 every v_s first yes
The fileper keyword is documented below with the nfile keyword.
The first keyword determines whether a dump snapshot is written on the very first timestep after the dump command is invoked. This will always occur if the current timestep is a multiple of N, the frequency specified in the dump command, including timestep 0. But if this is not the case, a dump snapshot will only be written if the setting of this keyword is yes. If it is no, which is the default, then it will not be written.
The flush keyword applies to all dump styles except image and movie. It also applies only when the styles are used to write multiple successive snapshots to the same file. It determines whether a flush operation is 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 SPARTA halts before the simulation completes.
The format keyword can be used to change the default numeric format output by the text-based dump styles: particle, grid, surf, tally.
All the specified format strings are C-style formats, e.g. as used by the C/C++ printf() command. The line keyword takes a single argument which is the format string for an entire line of output with N fields for each particle, grid cell, or suraface elememt, which you must enclose in quotes if it is more than one field. The int and float keywords take a single format argument and are applied to all integer or floating-point quantities output. The setting for M string also takes a single format argument which is used for the Mth value output in each line, e.g. the 5th column is output in high precision for “format 5 %20.15g”.
The format keyword can be used multiple times. The precedence is that for each value in a line of output, the M format (if specified) is used, else the int or float setting (if specified) is used, else the line setting (if specified) for that value is used, else the default setting is used. A setting of none clears all previous settings, reverting all values to their default format.
Note
Grid cell IDs are stored internally as 4-byte or 8-byte signed integers, depending on how SPARTA was compiled. When specifying the format int option you can use a “%d”-style format identifier in the format string and SPARTA will convert this to the corresponding 8-byte form it it is needed when outputting those values. However, when specifying the line option or format M string option for those values, you should specify a format string appropriate for an 8-byte signed integer, e.g. one with “%ld”, if SPARTA was compiled with the -DSPARTA_BIGBIG option for 8-byte IDs.
The nfile or fileper keywords apply to all dump styles except image and movie. 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.
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.
Note
that different attributes can be output by the dump particle command than are used as threshold criteria by the dump_modify command. E.g. you can output the coordinates of particles whose velocity components are above some threshold.
These keywords apply only to the dump image and dump movie styles. Any keyword that affects an image, also affects a movie, since the movie is simply a collection of images. Some of the keywords only affect the dump movie style. The descriptions give details.
The backcolor keyword can be used with the dump image command to set 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 bitrate keyword can be used with the dump movie command to define the size of the resulting movie file and its quality via setting how many kbits per second are to be used for the movie file. Higher bitrates require less compression and will result in higher quality movies. The quality is also determined by the compression format and encoder. The default setting is 2000 kbit/s, which will result in average quality with older compression formats.
Important
Not all movie file formats supported by dump movie allow the bitrate to be set. If not, the setting is silently ignored.
The boxcolor keyword can be used with the dump image command to set the color of the simulation box drawn around the particles 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 cmap keyword can be used with the dump image command to define a color map that is used to draw “objects” which can be particles, grid cells, or surface elements. The mode setting must be particle or grid or surf or gridx or gridy or gridz which correspond to the same keywords in the dump image command.
Color maps are used to assign a specific RGB (red/green/blue) color value to an individual object when it is drawn, based on the object’s attribute, which is a numeric value, e.g. the x-component of velocity for a particle, if the particle-attribute “vx” was specified in the dump image command.
The basic idea of a color map is that the attribute will be within a range of values, and that range is associated with a a series of colors (e.g. red, blue, green). A specific value (vx = -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 cmap keyword. Here are the details.
The lo and hi settings determine the range of values allowed for the attribute. If numeric values are used for lo and/or hi, then values that are lower/higher than that value are set to the value. 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 objects 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 objects 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.
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 object, given the value X of its attribute. X will fall between 2 of the entry values. The color of the object 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 object’s color will be halfway between “red” and “blue”, which happens to be “purple”.
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 object, given the value X of its 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 objects will be drawn with one of the colors in the list of entries.
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.
The color keyword can be used with the dump image command to define 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 framerate keyword can be used with the dump movie command to define the duration of the resulting movie file. Movie files written by the dump movie command have a default frame rate of 24 frames per second and the images generated will be converted at that rate. Thus a sequence of 1000 dump images will result in a movie of about 42 seconds. To make a movie run longer you can either generate images more frequently or lower the frame rate. To speed a movie up, you can do the inverse. Using a frame rate higher than 24 is not recommended, as it will result in simply dropping the rendered images. It is more efficient to dump images less frequently.
The gcolor keyword can be used one or more times with the dump image command, only when its grid color setting is proc, to set the color that grid cells will be drawn in the image.
Note
that for this command, processor IDs range from 1 to Nprocs inclusive, instead of the more customary 0 to Nprocs-1.
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 processors. In the latter case, the list of colors are assigned in a round-robin fashion to each of the specified processors.
The glinecolor keyword can be used with the dump image command to set the color of the grid cell outlines drawn around the grid cells in each image. See the “dump image gline” command for how to specify that cell outlines 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 gridgroup keyword can be used with the dump image command to only draw a subset of the grid cells in the simulation. By default all the grid cells are rendered. The group-ID argument can be any valid grid group name, as defined by the group grid command.
The pcolor keyword can be used one or more times with the dump image command, only when its particle color setting is type or procs, to set the color that particles will be drawn in the image.
If the particle color setting is type, then the specified type for the pcolor keyword should be an integer from 1 to Ntypes = the number of particle types. A wildcard asterisk can be used in place of or in conjunction with the type argument to specify a range of particle types. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of particle types, then an asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive).
Note
that for this command, processor IDs range from 1 to Nprocs inclusive, instead of the more customary 0 to Nprocs-1.
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 particle types. In the latter case, the list of colors are assigned in a round-robin fashion to each of the specified particle types.
The pdiam keyword can be used with the dump image command, when its particle diameter setting is type, to set the size that particles of each type will be drawn in the image. The specified type should be an integer from 1 to Ntypes. As with the pcolor keyword, a wildcard asterisk can be used as part of the type argument to specify a range of particle types. The specified diam is the size in whatever distance units the input script is using.
The scolor keyword can be used one or more times with the dump image command, only when its surface element color setting is one or proc, to set the color that surface elements will be drawn in the image.
When the surf color is one, the proc setting for this command is ignored.
Note
that for this command, processor IDs range from 1 to Nprocs inclusive, instead of the more customary 0 to Nprocs-1.
When the surf color is one, the specified color setting for this command must 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.
When the surf color is proc, the color setting for this command can be one or more colors separated by a “/” character, e.g. red/green/blue. For a single color, that color is assigned to all the specified processors. For two or more colors, the list of colors are assigned in a round-robin fashion to each of the specified processors.
The slinecolor keyword can be used with the dump image command to set the color of the surface element outlines drawn around the surface elements in each image. See the “dump image sline” command for how to specify that surface element outlines 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 surfgroup keyword can be used with the dump image command to only draw a subset of the surface elements in the simulation. By default all the surface elements are rendered. The group-ID argument can be any valid surf group name, as defined by the group surf command.
Restrictions:
none
Default:
The option defaults are
append = no
buffer = yes for all dump styles except image and movie
backcolor = black
boxcolor = yellow
cmap = mode min max cf 0.0 2 min blue max red, for all modes
color = 140 color names are pre-defined as listed below
every = whatever it was set to via the dump command
fileper = # of processors
first = no
flush = yes
format = %d and %g for each integer or floating point value
gcolor = * red/green/blue/yellow/aqua/cyan
glinecolor = white
gridgroup = all
nfile = 1
pad = 0
pcolor = * red/green/blue/yellow/aqua/cyan
pdiam = * 1.0
region = none
scolor = * gray
slinecolor = white
surfgroup = all
thresh = none
These are the 140 colors that SPARTA 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.
aliceblue = 240, 248, 255 |
antiquewhite = 250, 235, 215 |
aqua = 0, 255, 255 |
aquamarine = 127, 255, 212 |
azure = 240, 255, 255 |
beige = 245, 245, 220 |
bisque = 255, 228, 196 |
black = 0, 0, 0 |
blanchedalmond = 255, 255, 205 |
blue = 0, 0, 255 |
blueviolet = 138, 43, 226 |
brown = 165, 42, 42 |
burlywood = 222, 184, 135 |
cadetblue = 95, 158, 160 |
chartreuse = 127, 255, 0 |
chocolate = 210, 105, 30 |
coral = 255, 127, 80 |
cornflowerblue = 100, 149, 237 |
cornsilk = 255, 248, 220 |
crimson = 220, 20, 60 |
cyan = 0, 255, 255 |
darkblue = 0, 0, 139 |
darkcyan = 0, 139, 139 |
darkgoldenrod = 184, 134, 11 |
darkgray = 169, 169, 169 |
darkgreen = 0, 100, 0 |
darkkhaki = 189, 183, 107 |
darkmagenta = 139, 0, 139 |
darkolivegreen = 85, 107, 47 |
darkorange = 255, 140, 0 |
darkorchid = 153, 50, 204 |
darkred = 139, 0, 0 |
darksalmon = 233, 150, 122 |
darkseagreen = 143, 188, 143 |
darkslateblue = 72, 61, 139 |
darkslategray = 47, 79, 79 |
darkturquoise = 0, 206, 209 |
darkviolet = 148, 0, 211 |
deeppink = 255, 20, 147 |
deepskyblue = 0, 191, 255 |
dimgray = 105, 105, 105 |
dodgerblue = 30, 144, 255 |
firebrick = 178, 34, 34 |
floralwhite = 255, 250, 240 |
forestgreen = 34, 139, 34 |
fuchsia = 255, 0, 255 |
gainsboro = 220, 220, 220 |
ghostwhite = 248, 248, 255 |
gold = 255, 215, 0 |
goldenrod = 218, 165, 32 |
gray = 128, 128, 128 |
green = 0, 128, 0 |
greenyellow = 173, 255, 47 |
honeydew = 240, 255, 240 |
hotpink = 255, 105, 180 |
indianred = 205, 92, 92 |
indigo = 75, 0, 130 |
ivory = 255, 240, 240 |
khaki = 240, 230, 140 |
lavender = 230, 230, 250 |
lavenderblush = 255, 240, 245 |
lawngreen = 124, 252, 0 |
lemonchiffon = 255, 250, 205 |
lightblue = 173, 216, 230 |
lightcoral = 240, 128, 128 |
lightcyan = 224, 255, 255 |
lightgoldenrodyellow = 250, 250, 210 |
lightgreen = 144, 238, 144 |
lightgrey = 211, 211, 211 |
lightpink = 255, 182, 193 |
lightsalmon = 255, 160, 122 |
lightseagreen = 32, 178, 170 |
lightskyblue = 135, 206, 250 |
lightslategray = 119, 136, 153 |
lightsteelblue = 176, 196, 222 |
lightyellow = 255, 255, 224 |
lime = 0, 255, 0 |
limegreen = 50, 205, 50 |
linen = 250, 240, 230 |
magenta = 255, 0, 255 |
maroon = 128, 0, 0 |
mediumaquamarine = 102, 205, 170 |
mediumblue = 0, 0, 205 |
mediumorchid = 186, 85, 211 |
mediumpurple = 147, 112, 219 |
mediumseagreen = 60, 179, 113 |
mediumslateblue = 123, 104, 238 |
mediumspringgreen = 0, 250, 154 |
mediumturquoise = 72, 209, 204 |
mediumvioletred = 199, 21, 133 |
midnightblue = 25, 25, 112 |
mintcream = 245, 255, 250 |
mistyrose = 255, 228, 225 |
moccasin = 255, 228, 181 |
navajowhite = 255, 222, 173 |
navy = 0, 0, 128 |
oldlace = 253, 245, 230 |
olive = 128, 128, 0 |
olivedrab = 107, 142, 35 |
orange = 255, 165, 0 |
orangered = 255, 69, 0 |
orchid = 218, 112, 214 |
palegoldenrod = 238, 232, 170 |
palegreen = 152, 251, 152 |
paleturquoise = 175, 238, 238 |
palevioletred = 219, 112, 147 |
papayawhip = 255, 239, 213 |
peachpuff = 255, 239, 213 |
peru = 205, 133, 63 |
pink = 255, 192, 203 |
plum = 221, 160, 221 |
powderblue = 176, 224, 230 |
purple = 128, 0, 128 |
red = 255, 0, 0 |
rosybrown = 188, 143, 143 |
royalblue = 65, 105, 225 |
saddlebrown = 139, 69, 19 |
salmon = 250, 128, 114 |
sandybrown = 244, 164, 96 |
seagreen = 46, 139, 87 |
seashell = 255, 245, 238 |
sienna = 160, 82, 45 |
silver = 192, 192, 192 |
skyblue = 135, 206, 235 |
slateblue = 106, 90, 205 |
slategray = 112, 128, 144 |
snow = 255, 250, 250 |
springgreen = 0, 255, 127 |
steelblue = 70, 130, 180 |
tan = 210, 180, 140 |
teal = 0, 128, 128 |
thistle = 216, 191, 216 |
tomato = 253, 99, 71 |
turquoise = 64, 224, 208 |
violet = 238, 130, 238 |
wheat = 245, 222, 179 |
white = 255, 255, 255 |
whitesmoke = 245, 245, 245 |
yellow = 255, 255, 0 |
yellowgreen = 154, 205, 50 |