  (Rough-draft documentation for dump2data.py and raw2data.py)

   ---- Description ----

"dump2data.py" was originally designed to convert dump files into LAMMPS DATA format (for restarting a simulation from where it left off).  However it also reads and writes .XYZ and .RAW (simple 3-column text format) files also.

   Comparison with pizza.py:
This script duplicates some of the tools in pizza.py, but you don't have to learn python to use it.  If you are willing to learn a little python, pizza.py, can handle more general dump files which might cause dump2data.py to crash (eg "atom_style tri").  Unlike "dump2data.py", pizza.py is maintained by the lammps team:
http://pizza.sandia.gov/doc/Manual.html

   ----- General Usage -----

General usage:

dump2data.py [old_data_file -xyz -raw -last -t time -tstart ta -tstop tb -interval n -multi -center -scale x  -atomstyle style]  < DUMP_FILE > OUTPUT_FILE

    ----- examples -----

   If your LAMMPS dump file is named "traj.lammpstrj", you can
extract the coordinates this way:

dump2data.py -xyz < traj.lammpstrj > traj.xyz

This generates a 3-column text file containing the xyz coordinates on each line of each atom (sorted by atomid).  If there are multiple frames in the trajectory file, it will concatenate them together this way:

8192
LAMMPS data from timestep 50000
1 -122.28 -19.2293 -7.93705
2 -121.89 -19.2417 -8.85591
3 -121.6 -19.2954 -7.20586
:   :          :            :
8192
LAMMPS data from timestep 100000
1 -121.59 -20.3273 -2.0079
2 -122.2 -19.8527 -2.64669
3 -120.83 -19.7342 -2.2393

(When using the "-raw" argument to create simple 3-column .RAW files, blank lines are used to delimit different frames in the trajectory.)

---- optional command line arguments ---

If you want to select a particular frame from the trajectory, use:

dump2data.py -xyz -t 10000 < traj.lammpstrj > coords.xyz

To select the most recent (complete) frame, use:

dump2data.py -xyz -last < traj.lammpstrj > coords.xyz

(If the last frame is incomplete, this script will attempt to use the previous frame.)

If you want to select multiple frames, but there are too many frames in your trajectory, you can run dump2data.py this way...

dump2data.py -xyz -interval 10000 < traj.lammpstrj > traj.xyz

...to indicate the desired interval between frames (it must be a multiple of
the save interval).  You can also use "-tstart 500000 and "-tstop 1000000" arguments to limit the output to a particular range of time.  (500000-1000000 in this example).

--- creating DATA files ---

"dump2data.py" can also create lammps DATA files.  You must supply it with an existing DATA file containing the correct number of atoms and topology information.

If your coordinates are stored in a DUMP file (eg "traj.lammpstrj"), you can create a new data file this way:

dump2data.py -t 10000 data_file < traj.lammpstrj > new_file

Again, in this example, "10000" is the timestep for the frame you have selected.  You can use "-last" to select the last frame.  If you do not specify the frame you want, multiple data files may be created...

Creating multiple data files:
The "-multi" command line argument tells "dump2data.py" to generate a new data file for each frame in the trajectory/dump-file.  Those files will have names ending in ".1", ".2", ".3", ...  (If you use the "-interval" argument, frames in the trajectory whose timestep is not a multiple of the interval will be discarded.)  I can't remember if this behavior is switched on by default.  

Reading simple 3-column coordinate files:
If you have a file containing only the coordinates of the atoms (in sorted order), you can use "raw2data.py" to create a data file with those atoms coordinates.

raw2data.py -atomstyle ATOMSTYLE data_file < coords.raw  > new_data_file

(where ATOMSTYLE is a quoted string, such as "full" or "hybrid sphere dipole" discussed earlier.  Warning: "raw2data.py" is not a stand-alone script.  Make sure raw2data.py is located in the same directory with dump2data.py.)

--- scaling and centering coordinates ---

-center
  This will center the coordinates around the geometric center, so that the average position of the atoms in each frame is located at the origin.  (This script attempts to pay attention to the periodic image flags.  As such, I think this script works with triclinic cells, but I have not tested that feature carefully.)

-scale 1.6
  This will multiply the coordinates by a constant (eg "1.6")  (Please email me if this fails with periodic image flags.)

---- limitations ----

Speed.
The program is somewhat slow, although it should be able to handle big trajectories.  If speed is important to you, you probably should write your own custom script or use pizza.py which might be faster.

triclinic cells
  Support for triclinic cells has been added, but not tested.

exotic atom_styles

  This script was designed to work with point-like atoms, and it extracts the x,y,z (and if present vx,vy,vz velocity) degrees of freedom and (by default) copies it to the new data being created by this script.

By default, this script assumes you are using "atom_style full".
If you are using some other atom style (eg "hybrid bond dipole"), then you can try to run it this way:

dump2data.py -t 10000 \
  -atomstyle "hybrid bond dipole" \
  old_data_file < traj.lammpstrj > new_data_file

In general, the -atomstyle argument can be any of the atom styles listed in the
table at:
http://lammps.sandia.gov/doc/atom_style.html
...such as "angle", "bond", "charge", "full", "molecular", "dipole", "ellipsoid", or any hybrid combination of these styles.  (When using hybrid atom styles, you must enclose the argument in quotes, for example: "hybrid sphere dipole")
Warning: I have not tested using dump2data.py with exotic (non-point-like) atom
styles.  (I suspect that the script will not crash, but the dipole orientations
will not be updated.)

You can also customize the order columns you want to appear in that file using -atomstyle ”molid x y z atomid atomtype mux muy muz”, but again, I don't think the mux, muy, muz information in the new data file will be accurate.

I also strongly suspect that "dump2data.py" does not currently work with the "tri", "ellipsoid", and new "body" styles.

Again, try using pizza.py if you are simulating systems with exotic data types.
http://pizza.sandia.gov/doc/Manual.html

I hope this is useful to someone.
