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:

  • group

    Write only the atoms of one group. grouping_method selects one of the grouping methods defined by group:I:number_of_grouping_methods in the simulation model file. Grouping methods are numbered from 0. group_id selects 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_only replaces the wrapped positions. The atom types and positions are always written, as the type and coordinates variables. The positions are wrapped by default.

    Argument

    Variable

    Dimensions

    Unit

    velocity

    velocities

    (frame, atom, spatial)

    Å/ps

    force

    forces

    (frame, atom, spatial)

    kcal/mol/Å

    unwrapped_position

    unwrapped_coordinates

    (frame, atom, spatial)

    Å

    unwrapped_position_only

    coordinates (unwrapped)

    (frame, atom, spatial)

    Å

    potential

    potential_energy

    (frame, atom)

    eV

    charge

    charge

    (frame, atom)

    e

    bec

    bec

    (frame, atom, spatial, spatial)

    e

    virial

    virial

    (frame, atom, spatial, spatial)

    eV

    mass

    mass

    (frame, atom)

    amu

    group_labels

    group_labels

    (atom, grouping_method)

    –

    The unwrapped_position option keeps wrapped positions in coordinates and adds unwrapped_coordinates. The unwrapped_position_only option writes only unwrapped positions in coordinates and adds the global attribute position_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 mass when it can be recovered from the atom types to reduce file size. The rank-2 tensors are stored row-major, so virial[frame, atom, i, j] is the ij component.

  • precision

    • If value is single, the output data are 32-bit floating point numbers.

    • If value is double, the output data are 64-bit floating point numbers.

    The default value is single.

  • compression none|deflate

    • none writes 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 default precision single is used.

    • deflate writes a NetCDF4/HDF5 file using lossless compression and requires NetCDF-C built with NetCDF4/HDF5 and zlib support. level must be an integer from 0 to 9. Level 0 applies no compression. For large, frequently written trajectories, use none for maximum write speed, deflate 1 for a practical balance, or deflate 9 when minimizing file size is more important than write speed. Requesting deflate without 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 units attribute 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_labels requires at least one grouping method to be defined in model.xyz.

  • The type and mass variables 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, the type variable 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 time variable restarts at the beginning of every GPUMD execution, while frame keeps counting, so the times in a file appended to across executions are not monotonic.