read command
Purpose
Command for reading a file. The file can be either a restart, a data or a dump (either LAMMPS style or VTK) file.
Note
This command is supported by Aspherix GPU.Syntax
read file file_name keyword value
file = obligatory keyword
filename = name of the file to read
zero or more keyword/value pairs may be appended
keyword = type (effective and obligatory only when the filename constains a “*”) or reset_timestep (effective only when the filename is a restart file) or mode (effective only when the filename is a data file) or fields or box or replace or purge or trim or add or scaled or wrapped or label or timestep (the last ten keywords are effective only when the filename is dump or a VTK file) or ignore_missing_file
type value = file_type
file_type = restart or dump or data or vtk
reset_timestep = yes or no
mode value = mode_style
mode_style = new or append
fields value = {field_1, field_2, ...}
field_i = x or y or z or vx or vy or vz or q or ix or iy or iz
x, y, z = particle coordinates
radius = particle radii
vx, vy, vz = velocity components
q = charge
ix, iy, iz = image flags in each dimension
box value = yes or no
yes = replace the simulation box with dump box
replace value = yes o no
yes = overwrite particles with dump particles
purge value = yes or no
yes = delete all particles before adding dump particles
trim value = yes or no
yes = trim particles that are not in dump snapshot
add value = yes or no
yes = add new dump particles to system
scaled value = yes or no
yes = coords in dump file are scaled
wrapped value = yes or no
yes = coords in dump file are wrapped
label value = {field, column}
field = one of the listed fields or id or type
column = label on corresponding column in dump file
timestep value = ts
ts = time step of dump that should be read
ignore_missing_file value = yes or no
yes = disables the error message if the file is missing
Examples
read file restart.*.% type restart
read file ../run7/dump.file.gz
read file post/aspherix.restart reset_timestep yes
read file aspherix_auto_restart_%.basx
read file aspherix_auto_restart_*.basx
read file aspherix_auto_restart_base.basx
read file dump.2000.vtk fields {x,y,z} box no purge yes replace no
read file dump.2000.vtk ignore_missing_file yes
Description
This command allows to load four different types of files: restart, dump, VTK and data files. For more information, please consult the specific sections: Read a restart file, Read a dump and VTK file and Read a data file.
Type detection
If the type keyword is not specified Aspherix® will try and deduct the file type automatically. The following rules are applied:
Filename ends with .gz: file is a data file
Filename ends with .basx or .restart: file is a restart file
First line in file indicates classical or xml VTK file: file is a VTK file
First non-empty lines contain atoms and atom types and Atoms: file is a data file
File starts with Aspherix® version information: file is a restart file
Default: file is a dump file
Note, if the file contains placeholders like * or % then the type keyword must be specified.
Read a restart file
Read in a previously saved simulation from a restart file. This allows continuation of a previous run. Information about what is stored in a restart file is given below.
Restart files are saved in binary format to enable exact restarts, meaning that the trajectories of a restarted run will precisely match those produced by the original run had it continued on. Several things can prevent exact restarts due to round-off effects, in which case the trajectories in the two runs will slowly diverge (e.g., running on a different number of processors). Aspherix® will issue a warning in these cases.
Certain commands and pair styles will not restart exactly, though they should provide statistically similar results. This is because the forces they compute depend on particle velocities, which are used at half-step values every timestep when forces are computed. When a run restarts, forces are initially evaluated with a full-step velocity, which is different than if the run had continued. These pair styles include the granular pair style. If a restarted run is immediately different than the run which produced the restart file, it could be an Aspherix® bug, so consider reporting it if you think the behavior is wrong.
Similar to how restart files are written (see the write_restart and restart commands), the restart filename can contain two wild-card characters. If a “*” appears in the filename, the directory is searched for all filenames that match the pattern where “*” is replaced with a timestep value. The file with the largest timestep value is read in. Thus, this effectively means, read the latest restart file. It’s useful if you want your script to continue a run from where it left off. See the simulate command and its “target_time_steps” and “target_time” option for how to specify the run command so it doesn’t need to be changed either.
If a “%” character appears in the restart filename, Aspherix® expects a set of multiple files to exist. The restart and write_restart commands explain how such sets are created. The read command will first read a filename where “%” is replaced by “base”. This file tells Aspherix® how many processors created the set and how many files are in it. The command then reads the additional files. For example, if the restart file was specified as save.% when it was written, then the read command reads the files save.base, save.0, save.1, … save.P-1, where P is the number of processors that created the restart file. The processors in the current Aspherix® simulation share the work of reading these files; each reads a roughly equal subset of the files. The number of processors which created the set can be different from the number of processors in the current Aspherix® simulation. This can be a fast mode of input on parallel machines that support parallel I/O.
A restart file stores the following information about a simulation: units and particle style, simulation box size and shape and boundary settings, group definitions, per-type particle settings such as mass, per-particle attributes including their group assignments, force field styles and coefficients. This means that commands for these quantities do not need to be re-specified in the input script that reads the restart file, though you can redefine settings after the restart file is read.
One exception is that some pair styles do not store their info in restart files. The documentation pages for individual pair styles note if this is the case.
The list of commands used for a simulation is not stored in the restart file. This means that the new input script should specify all the commands it will use. Note that some commands store an internal “state” which is written to the restart file. This allows the command to continue on with its calculations in a restarted simulation. To re-enable such a command, the command in the new input script must use the same ID and group-ID as was used in the input script that wrote the restart file. If a match is found, Aspherix® prints a message indicating that the command is being re-enabled. If no match is found before the first run or minimization is performed by the new script, the “state” information for the saved command is discarded. See the doc pages for individual commands for info on which ones can be restarted in this manner.
The optional keyword reset_timestep allows to reset the current timestep of the restart file to 0 during loading. In particular this is useful, if you want to start a ‘new’ simulation (e.g. for a coupled simulation) starting from a previous state.
By default if the specified file is missing an error message will be output, unless the keyword ignore_missing_file is set to yes: in this case the read command will be ignored for that file. This is also valid for other file formats.
Warning
No other information is stored in the restart file. This means that an input script that reads a restart file should specify settings for quantities like simulation timestep, neighbor list criteria including settings made via the neigh_modify command, output settings, geometric regions, etc.
Read a dump and VTK file
Read particle information from a dump file to overwrite the current particle coordinates, and optionally the particle velocities and image flags and the simulation box dimensions. This is useful for restarting a run from a particular snapshot in a dump file.
Note that a simulation box must already be defined before using the read dump command. This can be done by the materials command, by first reading a data file (see Sec. Read a data file) or a restart file (see Sec. Read a restart file). The read dump command can reset the simulation box dimensions, as explained below.
Since Aspherix® needs valid radii, the radius field is mandatory to be read.
Also note that reading per-particle information from a dump snapshot is limited to the particle coordinates, radii, velocities and image flags, as explained below. Other particle properties, which may be necessary to run a valid simulation, such as particle charge, or bond topology information for a molecular system, are not read from (or even contained in) dump files. Thus this auxiliary information should be defined in the usual way, e.g. in a data file (see Sec. Read a data file), before using the read dump command, or by the set command, after the dump snapshot is read.
If the dump filename specified as file ends with “.gz”, the dump file is read in gzipped format. You cannot (yet) read a dump file that was written in binary format with a “.bin” suffix, or to multiple files via the “%” option in the dump file name. See the dump command for details.
The format of the dump file is selected through the format keyword. If specified, it must be the last keyword used, since all remaining arguments are passed on to the dump reader. The native format is for native Aspherix® dump files, written with a “dump atom”.html or dump custom command. The xyz format is for generic XYZ formatted dump files. The vtk format is for files written by Aspherix® with dump custom/vtk and the vtk-reader is able to read ASCII and binary .vtk and .vtp files. The auto-generated “boundaryBox”-vtk files automatically ignored.
Support for other dump format readers may be added in the future.
Global information is first read from the dump file, namely timestep and box information.
The dump file is scanned for a snapshot with a time stamp that matches the specified Nstep. This means the Aspherix® timestep the dump file snapshot was written on for the native format. However, the xyz formats do not store the timestep. For these formats, timesteps are numbered logically, in a sequential manner, starting from 0. Thus to access the 10th snapshot in an xyz or mofile formatted dump file, use Nstep = 9.
The dimensions of the simulation box for the selected snapshot are also read; see the box keyword discussion below. For the native format, an error is generated if the snapshot is for a triclinic box and the current simulation box is orthogonal or vice versa. A warning will be generated if the snapshot box boundary conditions (periodic, shrink-wrapped, etc) do not match the current simulation boundary conditions, but the boundary condition information in the snapshot is otherwise ignored. See the “boundary” command for more details.
For the xyz and vtk format, no information about the box is available, so you must set the box flag to no. See details below.
Per-atom information from the dump file snapshot is then read from the dump file snapshot. This corresponds to the specified fields listed in the read_dump command. It is an error to specify a z-dimension field, namely z, vz, or iz, for a 2d simulation.
For dump files in native format, each column of per-atom data has a text label listed in the file. A matching label for each field must appear, e.g. the label “vy” for the field vy. For the x, y, z fields any of the following labels are considered a match:
x, xs, xu, xsu for field x y, ys, yu, ysu for field y z, zs, zu, zsu for field z
The meaning of xs (scaled), xu (unwrapped), and xsu (scaled and unwrapped) is explained on the dump command doc page. These labels are searched for in the list of column labels in the dump file, in order, until a match is found.
The dump file must also contain atom IDs, with a column label of id, which should start at 1.
If the add keyword is specified with a value of yes, as discussed below, the dump file must contain atom types, with a column label of “type”.
If a column label you want to read from the dump file is not a match to a specified field, the label keyword can be used to specify the specific column label from the dump file to associate with that field. An example is if a time-averaged coordinate is written to the dump file via the fix ave/atom command. The column will then have a label corresponding to the fix-ID rather than “x” or “xs”. The label keyword can also be used to specify new column labels for fields id and type.
For dump files in xyz format, only the x, y, and z fields are supported. The dump file does not store atom IDs, so these are assigned consecutively to the atoms as they appear in the dump file, starting from 1. Thus you should ensure that order of atoms is consistent from snapshot to snapshot in the the XYZ dump file. See the dump_modify sort command if the XYZ dump file was written by Aspherix®.
Information from the dump file snapshot is used to overwrite or replace properties of the current system. There are various options for how this is done, determined by the specified fields and optional keywords.
The timestep of the snapshot becomes the current timestep for the simulation. See the reset_timestep command if you wish to change this after the dump snapshot is read.
If the box keyword is specified with a yes value, then the current simulation box dimensions are replaced by the dump snapshot box dimensions. If the box keyword is specified with a no value, the current simulation box is unchanged.
If the purge keyword is specified with a yes value, then all current atoms in the system are deleted before any of the operations invoked by the replace, trim, or add keywords take place.
If the replace keyword is specified with a yes value, then atoms with IDs that are in both the current system and the dump snapshot have their properties overwritten by field values. If the replace keyword is specified with a no value, atoms with IDs that are in both the current system and the dump snapshot are not modified.
If the trim keyword is specified with a yes value, then atoms with IDs that are in the current system but not in the dump snapshot are deleted. These atoms are unaffected if the trim keyword is specified with a no value.
If the add keyword is specified with a yes value, then atoms with IDs that are in the dump snapshot, but not in the current system are added to the system. These dump atoms are ignored if the add keyword is specified with a no value. Note, this by default this value is yes.
Note that atoms added via the add keyword will have only the attributes read from the dump file due to the field arguments. If x or y or z is not specified as a field, a value of 0.0 is used for added atoms. Added atoms must have an atom type, so this value must appear in the dump file.
Any other attributes (e.g. charge or particle diameter for spherical particles) will be set to default values, the same as if the create_atoms command were used.
Note that atom IDs are not preserved for new dump snapshot atoms added via the add keyword. The procedure for assigning new atom IDS to added atoms is the same as is described for the create_atoms command.
Atom coordinates read from the dump file are first converted into unscaled coordinates, relative to the box dimensions of the snapshot. These coordinates are then be assigned to an existing or new atom in the current simulation. The coordinates will then be remapped to the simulation box, whether it is the original box or the dump snapshot box. If periodic boundary conditions apply, this means the atom will be remapped back into the simulation box if necessary. If shrink-wrap boundary conditions apply, the new coordinates may change the simulation box dimensions. If fixed boundary conditions apply, the atom will be lost if it is outside the simulation box.
For native format dump files, the 3 xyz image flags for an atom in the dump file are set to the corresponding values appearing in the dump file if the ix, iy, iz fields are specified. If not specified, the image flags for replaced atoms are not changed and image flags for new atoms are set to default values. If coordinates read from the dump file are in unwrapped format (e.g. xu) then the image flags for read-in atoms are also set to default values. The remapping procedure described in the previous paragraph will then change images flags for all atoms (old and new) if periodic boundary conditions are applied to remap an atom back into the simulation box.
Aspherix® knows how to compute unscaled and remapped coordinates for the snapshot column labels discussed above, e.g. x, xs, xu, xsu. If another column label is assigned to the x or y or z field via the label keyword, e.g. for coordinates output by the fix ave/atom command, then Aspherix® needs to know whether the coordinate information in the dump file is scaled and/or wrapped. This can be set via the scaled and wrapped keywords. Note that the value of the scaled and wrapped keywords is ignored for fields x or y or z if the label keyword is not used to assign a column label to that field.
The scaled/unscaled and wrapped/unwrapped setting must be identical for any of the x, y, z fields that are specified. Thus you cannot read xs and yu from the dump file. Also, if the dump file coordinates are scaled and the simulation box is triclinic, then all 3 of the x, y, z fields must be specified, since they are all needed to generate absolute, unscaled coordinates.
Read a data file
Read in a data file containing information Aspherix® needs to run a simulation. The file can be ASCII text or a gzipped text file (detected by a .gz suffix).
Warning
Data files can only be used for spherical particles.
The structure of the data file is important, though many settings and sections are optional or can come in any order. See the examples directory for sample data files for different problems.
A data file has a header and a body. The header appears first. The first line of the header is always skipped; it typically contains a description of the file. Then lines are read one at a time. Lines can have a trailing comment starting with ‘#’ that is ignored. If the line is blank (only whitespace after comment is deleted), it is skipped. If the line contains a header keyword, the corresponding value(s) is read from the line. If it doesn’t contain a header keyword, the line begins the body of the file.
The body of the file contains zero or more sections. The first line of a section has only a keyword. The next line is skipped. The remaining lines of the section contain values. The number of lines depends on the section keyword as described below. Zero or more blank lines can be used between sections. Sections can appear in any order, with a few exceptions as noted below.
The formatting of individual lines in the data file (indentation, spacing between words and numbers) is not important except that header and section keywords (e.g. atoms, xlo xhi, Masses) must be capitalized as shown and can’t have extra white space between their words - e.g. two spaces or a tab between the 2 words in “xlo xhi” is not valid.
These are the recognized header keywords. Header lines can come in any order. The value(s) are read from the beginning of the line. Thus the keyword atoms should be in a line like “1000 atoms”; the keyword ylo yhi should be in a line like “-10.0 10.0 ylo yhi”; the keyword xy xz yz should be in a line like “0.0 5.0 6.0 xy xz yz”. All these settings have a default value of 0, except the lo/hi box size defaults are -0.5 and 0.5. A line need only appear if the value is different than the default.
atoms = # of atoms in system
atom types = # of atom types in system
xlo xhi = simulation box boundaries in x dimension
ylo yhi = simulation box boundaries in y dimension
zlo zhi = simulation box boundaries in z dimension
xy xz yz = simulation box tilt factors for triclinic system
The initial simulation box size is determined by the lo/hi settings. In any dimension, the system may be periodic or non-periodic; see the boundary_conditions command.
If the xy xz yz line does not appear, Aspherix® will set up an axis-aligned (orthogonal) simulation box. If the line does appear, Aspherix® creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. The parallelepiped has its “origin” at (xlo,ylo,zlo) and is defined by 3 edge vectors starting from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). Xy,xz,yz can be 0.0 or positive or negative values and are called “tilt factors” because they are the amount of displacement applied to faces of an originally orthogonal box to transform it into the parallelepiped.
The tilt factors (xy,xz,yz) can not skew the box more than half the distance of the corresponding parallel box length. For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations with tilt = …, -15, -5, 5, 15, 25, … are all geometrically equivalent.
See the HowTo for triclinic simulations of the doc pages for a geometric description of triclinic boxes, as defined by Aspherix®, and how to transform these parameters to and from other commonly used triclinic representations.
When a triclinic system is used, the simulation domain must be periodic in any dimensions with a non-zero tilt factor, as defined by the boundary_conditions command. I.e. if the xy tilt factor is non-zero, then both the x and y dimensions must be periodic. Similarly, x and z must be periodic if xz is non-zero and y and z must be periodic if yz is non-zero.
If the system is periodic (in a dimension), then atom coordinates can be outside the bounds (in that dimension); they will be remapped (in a periodic sense) back inside the box.
Warning
If the system is non-periodic (in a dimension), then all particles in the data file must have coordinates (in that dimension) that are “greater than or equal to” the lo value and “less than or equal to” the hi value. If the non-periodic dimension is of style “fixed” (see the boundary command), then the particle coords must be strictly “less than” the hi value, due to the way Aspherix® assign particles to processors. Note that you should not make the lo/hi values radically smaller/larger than the extent of the particles. For example, if your particles extend from 0 to 50, you should not specify the box bounds as -10000 and 10000. This is because Aspherix® uses the specified box size to layout the 3d grid of processors.
These are the section keywords for the body of the file.
Atoms, Velocities = particle-property sections
Each section is listed below in alphabetic order. The format of each section is described including the number of lines it must contain and rules (if any) for where it can appear in the data file.
Any individual line in the various sections can have a trailing comment starting with “#” for annotation purposes. E.g. in the Atoms section:
10 1 17 -1.0 10.0 5.0 6.0 # salt ion
Atoms section:
one line per particle
line syntax: depends on particle style
An Atoms section must appear in the data file if natoms > 0 in the header section. The particles can be listed in any order. These are the line formats for each particle shape in Aspherix®. As discussed below, each line can optionally have 3 flags (nx,ny,nz) appended to it, which indicate which image of a periodic simulation box the particle is in. These may be important to include for some kinds of analysis.
sphere |
particle-ID particle-type diameter density x y z |
The keywords have these meanings:
particle-ID = integer ID of the particle
particle-type = type of particle (1-Ntype)
diameter = diameter of spherical particle (distance units)
density = density of particle (mass/distance^3 or mass/distance^2 or mass/distance units, depending on dimensionality of particle)
x,y,z = coordinates of the particle
The units for these quantities depend on the unit style; see the units command for details.
The particle-ID is used to identify the particle throughout the simulation and in dump files. Normally, it is a unique value from 1 to Natoms for each particle. Unique values larger than Natoms can be used, but they will cause extra memory to be allocated on each processor, if a particle map array is used (see the atom_modify command). If a particle map array is not used , and velocities are not assigned in the data file, and you don’t care if unique particle IDs appear in dump files, then the particle-IDs can all be set to 0.
The diameter specifies the size of a finite-size spherical particle. It can be set to 0.0, which means that atom is a point particle.
Particle velocities and other particle quantities not defined above are set to 0.0 when the Atoms section is read. Velocities can be set later by a Velocities section in the data file or by a velocity or set command in the input script.
Velocities section:
one line per atom
line syntax: depends on atom style
all styles except those listed |
atom-ID vx vy vz |
sphere |
atom-ID vx vy vz wx wy wz |
where the keywords have these meanings:
vx,vy,vz = translational velocity of atom wx,wy,wz = angular velocity of spherical atom:ul
The velocity lines can appear in any order. This section can only be used after an Atoms section. This is because the Atoms section must have assigned a unique atom ID to each atom so that velocities can be assigned to them.
Vx, vy, vz, and ervel are in units of velocity. Wx, Wy, Wz are in units of angular velocity (radians/time).
Restrictions
Reading legacy dump or vtk files might lead to an error message from the integrator, because this legacy files do not store information about the particle group. A possible workaround is to define a particle template and use the integrator command explicitly in the input script.
Default
reset_timestep = no