dump_netcdf
Write per-atom data to a user-specified NetCDF trajectory file based on the AMBER 1.0 conventions.
Syntax
dump_netcdf <interval> <filename> [{optional_args}]
Parameters
The interval parameter is the output interval (number of steps) of the atom positions.
filename is the relative or absolute path of the output file.
The optional arguments (optional_args) provide additional functionality.
Currently, the following optional arguments are accepted:
groupWrite only the atoms of one group.
grouping_methodselects one of the grouping methods defined bygroup:I:number_of_grouping_methodsin the simulation model file. Grouping methods are numbered from 0.group_idselects a group label within that grouping method. Both values must identify an existing, non-empty group. Without this option all atoms in the system are written.Per-atom quantities
Any number of the names below can be given, in any order, each adding one quantity to the output, except that
unwrapped_position_onlyreplaces the wrapped positions. The atom types and positions are always written, as thetypeandcoordinatesvariables. The positions are wrapped by default.Argument
Variable
Dimensions
Unit
velocityvelocities(frame, atom, spatial)Å/ps
forceforces(frame, atom, spatial)kcal/mol/Å
unwrapped_positionunwrapped_coordinates(frame, atom, spatial)Å
unwrapped_position_onlycoordinates(unwrapped)(frame, atom, spatial)Å
potentialpotential_energy(frame, atom)eV
chargecharge(frame, atom)e
becbec(frame, atom, spatial, spatial)e
virialvirial(frame, atom, spatial, spatial)eV
massmass(frame, atom)amu
group_labelsgroup_labels(atom, grouping_method)–
The
unwrapped_positionoption keeps wrapped positions incoordinatesand addsunwrapped_coordinates. Theunwrapped_position_onlyoption writes only unwrapped positions incoordinatesand adds the global attributeposition_mode=unwrapped. These two options are mutually exclusive.The group labels are fixed by the simulation model file and are therefore written once, without a frame dimension. Masses are written for every frame because species can change during MC sampling. Omit
masswhen it can be recovered from the atom types to reduce file size. The rank-2 tensors are stored row-major, sovirial[frame, atom, i, j]is the ij component.precisionIf
valueissingle, the output data are 32-bit floating point numbers.If
valueisdouble, the output data are 64-bit floating point numbers.
The default value is
single.compression none|deflatenonewrites an uncompressed NetCDF file in the 64-bit-offset (CDF-2) format and is the default. Here, 64-bit offset refers to the file layout, not the precision of the coordinates and velocities; these data use 32-bit floating point numbers when the defaultprecision singleis used.deflatewrites a NetCDF4/HDF5 file using lossless compression and requires NetCDF-C built with NetCDF4/HDF5 and zlib support.levelmust be an integer from 0 to 9. Level 0 applies no compression. For large, frequently written trajectories, usenonefor maximum write speed,deflate 1for a practical balance, ordeflate 9when minimizing file size is more important than write speed. Requestingdeflatewithout NetCDF4/HDF5 support causes an error. See NetCDF setup for how to build NetCDF-C with NetCDF4/HDF5 support.
Output
The selected properties are written to filename in NetCDF format, with the variables and units listed under Parameters.
Examples
Single precision without velocities
To dump the whole-system positions every 1000 steps using the default single precision and no compression, use:
dump_netcdf 1000 movie.nc
Double precision with velocities
To dump the whole-system positions and velocities every 1000 steps with 64-bit floating point values, use:
dump_netcdf 1000 movie.nc velocity precision double
Group output with compression
To dump group 0 from grouping method 1 with lossless deflate compression, use:
dump_netcdf 15 group.nc group 1 0 velocity compression deflate 1
Unwrapped positions
To dump both wrapped and unwrapped positions with velocities every 15 steps, use:
dump_netcdf 15 both.nc unwrapped_position velocity
To dump only unwrapped positions with velocities every 15 steps, use:
dump_netcdf 15 movie.nc unwrapped_position_only velocity
Forces and per-atom virials
To dump forces, per-atom potential energies and per-atom virials every 100 steps with lossless deflate compression, use:
dump_netcdf 100 properties.nc force potential virial compression deflate 1
Multiple groups in one run
Multiple dump_netcdf commands can write different groups during the
same MD run. Each command must use a distinct filename and can use its own
output interval, so every output file contains one independently sampled group:
dump_netcdf 10 group_0.nc group 0 0 velocity compression deflate 1
dump_netcdf 25 group_1.nc group 0 1 velocity compression deflate 1
run 100000
Notes
This keyword requires an external package to operate. Instructions for how to set up the NetCDF package can be found here.
NetCDF output files can be read for example by VMD or OVITO for visualization.
The NetCDF files also contain atom types, cell lengths, and angles, which can be used in visualization and analysis software.
AMBER NetCDF represents a periodic cell using lengths and angles in a standard orientation. If the GPUMD cell has a different orientation, the output is rigidly transformed with the cell so that periodic geometry is preserved. Positions, velocities, forces and unwrapped positions are rotated as vectors, and the per-atom virial and the BEC as rank-2 tensors, so that every quantity in a frame refers to the same axes.
AMBER variables use AMBER units; GPUMD extensions use GPUMD units, as listed above. Check each variable’s
unitsattribute when reading a trajectory.For qNEP models the charge values are predicted by the model. For other models they are those specified in model.xyz via
charge:R:1.The Born effective charge (BEC) requires a qNEP model trained with target BEC, and is refused for any other model.
group_labelsrequires at least one grouping method to be defined in model.xyz.The
typeandmassvariables both carry a frame dimension, so the species and the mass of an atom always refer to the same frame. A trajectory sampled alongside MC trials is therefore self-consistent. For a compacted multi-element NEP potential, thetypevariable uses the active atom type mapping printed at initialization; for other potential models, the type numbering is unchanged.Repeat this command before each run that needs this output.
The output file has an appending behavior. Frames are added to an existing file of that name, whether it was written by an earlier run of the same GPUMD execution or by an earlier execution. A different filename creates a separate trajectory file.
The layout of a NetCDF file is fixed when the file is created, so the position mode, group, quantity, precision, and compression settings must match those the existing file was written with. If they do not, GPUMD stops with an error naming the file. Remove or rename that file to start a new trajectory.
The
timevariable restarts at the beginning of every GPUMD execution, whileframekeeps counting, so the times in a file appended to across executions are not monotonic.