Syntax:
dump dump-ID style delta filename field1 field2 ...
text or sites or stitch or vtk fields =
id or site or x or y or z or
energy or propensity or iN or dN
image fields = discussed on dump image doc page
Examples:
dump 1 text 0.25 tmp.dump dump 1 text 1.0 my.dump id site x y z dump 1 sites 1.0 my.sites.* id site i2 i3 dump 1 vtk 1.0 my.vkt.* site dump 1 stitch 1.0 stitch_file.st site dump mydump text 5.0 snap.ising id site energy i1
Description:
The text, sites, vtk, and stitch styles dump a snapshot of site values to one or more files at time intervals of delta during a simulation. The image style creates a JPG or PPM image file of the site configuration every at time intervals of delta, as discussed on the dump image doc page. The remainder of this page describes the text, sites, vtk, and stitch styles.
The text style dump file is in the format of a LAMMPS dump file which can thus be read-in by the Pizza.py toolkit, converted to other formats, or used for visualization.
The sites style dump file is in the same format that is read by the read_sites command. The dumped files can thus be used as restart files to continue a simulation, using the read_sites command.
The vkt style dump file is in the VTI format that can be read by various visualization programs, including ParaView.
The stitch style dump file is in an SQLite format which can be read by the set stitch command or auxiliary tools provided with the Stitch library in lib/stitch. See the examples/stitch dir for examples of SPPARKS scripts that read and write stitch files.
As described below, the filename determines the kind of output (text or binary or gzipped, one big file or one per timestep, one big file or one per processor or one file per group of processors). The fields included in each snapshot are obtained from the application. Only on-lattice and off-lattice applications support dumps since they are spatial in nature. More that one dump command and output file can be used during a simulation by giving each a unique dump-ID and unique filename.
IMPORTANT NOTE: When running in parallel, unless the dump_modify sort option is invoked, the lines of per-site information written to dump files will be in an indeterminate order, i.e. not ordered by site ID. This is because the sites owned by each processor are written in a contiguous chunk. The ordering will be the same in every snapshot.
Dump snapshots will only be written on timesteps where the system time is a multiple of delta. Depending on now time advances in the application and solver (kinetic MC or rejection MC), the system time for a snapshot may be somewhat larger than an exact multiple of delta. I.e. SPPARKS will trigger the snapshot on the first timestep that the system time advances to a value >= a new delta interval.
Note that this means snapshots will not be written at the beginning or very end of a run, if the system time is not a multiple of delta. If multiple runs are performed, the same snapshot will not be written at the end of one run and the beginning of the next.
The dump_modify command can be used to alter the times at which snapshots are written out as well as define a subset of sites to write out. See the delay, delta, logfreq, loglinfreq, and tol keywords of the dump_modify command for details.
For the text format file, each snapshot begins with lines like these:
ITEM: TIMESTEP TIME 100 3.23945
The first field "100" denotes which snapshot it is, numbered as 0,1,2,etc. Snapshot 0 is thus typically for the state of the system before the first run command. The second field "3.23945" is the simualtion time when the snapshot is generated.
IMPORTANT NOTE: The second simulation time field is an addition to the standard LAMMPS-style header for each snapshot.
The next lines are like these:
ITEM: NUMBER OF ATOMS 314159
The word "ATOMS" is LAMMPS syntax, but simply means the number of sites in a SPPARKS simulation. The number "314159" will reflect any reduction in dumped site count due to the dump_modify command.
The next lines are like these:
ITEM: BOX BOUNDS 0 50 0 50 0 50
which denote the simulation box size in x,y,z. E.g, the last line is zlo and zhi.
The next line is like this:
ITEM: ATOMS id type x y z
which begins the per-site information. One line per site follows. The trailing "id type x y z" are labels for the per-site columns, using the requested fields in the dump command. The word "site" is converted to "type" so as to be compatible with how LAMMPS-style dump files are visualized. The LAMMPS default is to use the "type" value to color the object (e.g. a sphere) drawn at each site.
For the sites format file, each snapshot begins with lines like these.
Site file written by dump sites 2 command at time: 3 3.01
3 dimension 1000 sites id site columns 0 10 xlo xhi 0 10 ylo yhi 0 10 zlo zhi
This is followed by a "Values" section of per-site info, with one line per site. Each line begins with a site ID, followed by the per-site values listed in the "columns" header line
See the "read_sites" command for more explanation of this format. The two time fields at the end of the first (comment) line are the same TIME info described above the the text style format. The "id site" keywords that preceed "columns" define what per-site values are included in the file. The keyword "id" must be the first value in each per-site line. One or more per-site values can follow. Note that it only makes sense to include the "site" or "iN" or "dN" fields as output values, since the read_sites command can only process those as input.
IMPORTANT NOTE: For this style, a filename with the "*" wildcard must be used so that a different file is written for each snapshot. The is because the read_sites command only reads a file with a single snapshot.
IMPORTANT NOTE: This style of dump command will not write "Sites" or "Neighbors" sections to the sites file. When using the sites file to continue a simulation, it is assumed that the restart script will define the sites and their neighbors in an alternate way, e.g. via the "create_box" and "create_sites" commands. Or by reading a separate sites file with that information via an earlies "read sites" command.
IMPORTANT NOTE: You must write information for all sites to the sites style dump file. E.g. you cannot use the dump_modify command to limit the output to a subset of sites. This is because the read_sites requires information for all sites in the system.
For the vtk format file, each snapshot is wrapped with a VTK-specific header and footer. Only a single field can be listed, which must be a per-site value, e.g. "site" or "iN" or "dN".
A VTK-compatible visualization program will read the information in the dump snapshot and display one object (e.g. a cube or sphere) at each point on a regular 1d or 2d or 3d lattice.
IMPORTANT NOTE: Use of the "dump_modify vtk" command is required to use this dump style. This is to make additional simulation-specific settings included in the VTK-compatible dump file.
IMPORTANT NOTE: The vtk style can only be used to dump sites that are on a simple, regular lattice. In 1d, this is a "line/2n" lattice. In 2d, this is a square lattice, "sq/4n" or "sq/8n". In 3d, this is a simple cubic lattice, "sc/6n" or "sc/26n". See the lattice and create_sites commands for details on these lattice types.
If a lattice command was used to create sites, then SPPARKS will check that the lattice is one of these valid styles. However, if a read_sites command was used to define sites, e.g. by reading a previous sites-style dump file to continue a simulation, then no lattice is defined and SPPARKS cannot check this. It is up to you to insure the VTK output meets this restriction. Otherwise a visualization program may not be able to render a useful image.
IMPORTANT NOTE: The dump_modify sort command must be used to insure the per-site info for the regular lattice is written to the dump file in the regular ordering that VTK expects.
IMPORTANT NOTE: For this style, a filename with the "*" wildcard must be used so that a different file is written for each snapshot.
As mentioned above, the stitch format file is in an SQLite format.
In principle, any tool or library which reads SQLite files should be able to read a stitch file, but that is not recommended, For performance reasons, the Python or C API defind by the Stitch library should be used for reading and writing stitch files. SPPARKS itself reads stitch files using the set stitch command. Only a filename representing a single file (no wildcards) can be used with this style. A time stamp and associated SPPARKS simulation time for each snapshot is written into the SQLite file.
Note that style stitch 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. Many of the dump_modify options are ignored for this style. Snapshots for the entire lattice are written to the file. More info about stitch dump files will be added to this doc page later.
Only the specified fields will be included in the dump file for each site. If no fields are listed, then a default set of fields are output, namely "id site x y z".
These are the possible field values which may be specified.
The id is a unique integer ID for each site.
The site, iN, and dN fields specify a per-site value. Site is the same as i1. iN fields are integer values for integer fields 1 to N; dN fields are floating-point values. The application defines how many integer and floating-point values are stored for each site.
The x, y, z values are the coordinates of the site.
The energy value is what is computed by the energy() function in the application. Likewise for the propensity value which can be thought of as the relative probablity for that site to perform a KMC event. Note that if the application only performs rejection KMC or Metropolis MC, then no propensity is defined.
The specified filename determines how the dump file(s) is written. The default is to write one large text file, which is opened when the dump command is invoked and closed when an undump command is used or when SPPARKS exits.
IMPORTANT NOTE: Not all dump styles support all the filename options described next. See the Restrictions section below for details.
Dump filenames can contain two wildcard characters. If a "*" character appears in the filename, then one file per snapshot is written and the "*" character is replaced with the timestep value. This is a counter which starts at 0, and is incremented for each snapshot. For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.1, tmp.dump.2, etc. The initial value for this counter defaults to 0, but can be reset via the dump_modify first command.
If a "%" character appears in the filename, then one file is written for each processor and the "%" character is replaced with the processor ID from 0 to P-1. For example, tmp.dump.% becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller files and can be a fast mode of output on parallel machines that support parallel I/O for output.
Note that the "*" and "%" characters can be used together to produce a large number of small dump files!
If the filename ends with ".bin", the dump file (or files, if "*" or "%" is also used) is written in binary format. A binary dump file will be about the same size as a text version, but will typically write out much faster. Of course, when post-processing, you will need to convert it back to text format, using your own code to read the binary file. The format of the binary file can be understood by looking at the src/dump.cpp file.
If the filename ends with ".gz", the dump file (or files, if "*" or "%" is also used) is written in gzipped format. A gzipped dump file will be about 3x smaller than the text version, but will also take longer to write.
Restrictions:
This command can only be used as part of on-lattice or off-lattice applications. See the app_style command for further details.
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.
For the filename specified for the sites or vtk styles, a "*" wildcard must be used and a "%" wildcard cannot be used. Likewise a "*.bin" suffix cannot be used, but a "*.gz" suffix can be used.
To write gzipped dump files, you must compile SPPARKS with the -DSPPARKS_GZIP option - see the Making SPPARKS section of the documentation.
Related commands:
dump_one, dump_modify, undump, stats
Default: none