NetCDF file reader

For loading particle trajectories stored in binary NetCDF files that follow the AMBER NetCDF trajectory convention. Files of this kind are written by the dump netcdf command of LAMMPS, by the NetCDFTrajectory class of the Atomic Simulation Environment (ASE), by the Atomistica code, by the AMBER molecular dynamics package and its cpptraj tool, and by the SimPARTIX particle simulation code. OVITO itself can write files in this format, too.

NetCDF is a self-describing container format: a file consists of named dimensions, variables (multi-dimensional data arrays), and attributes. The AMBER convention prescribes a fixed set of dimension and variable names for trajectory data (see the table below), which OVITO recognizes, while all further per-atom variables found in a file get imported as user-defined particle properties. This makes the format an efficient alternative to text-based formats such as XYZ or LAMMPS dump.

OVITO reads files stored in the classic NetCDF-3 formats (CDF-1, 64-bit offset CDF-2, and CDF-5) as well as in the HDF5-based NetCDF-4 format. Compressed files (“.gz” suffix) cannot be read directly and must be decompressed first. The file reader identifies a NetCDF file as an AMBER trajectory by its global attribute Conventions, whose value must be AMBER (the ConventionVersion attribute is not checked). The trajectory data may reside either in the root group of the file or in a subgroup named AMBER.

Imported data

Frames

The number of trajectory frames is given by the length of the frame dimension, which must be present in every file. Each entry along this dimension is loaded as one animation frame. Variables with a leading frame dimension hold time-dependent data, while variables without it (e.g. a static type array) are shared by all frames.

Particles

The atom dimension defines the maximum number of particles per frame. Every file must contain a floating-point variable named coordinates or unwrapped_coordinates with dimensions (frame, atom, spatial) or (atom, spatial), from which the Position particle property is read. If the number of atoms varies from frame to frame, unused trailing entries of the coordinates array should be set to the NetCDF fill value; such entries are discarded by the file reader, and only the actual atoms are imported.

All other numeric variables whose first dimension is atom (or frame followed by atom) are read as per-particle properties. A variable may have up to two extra trailing dimensions: (atom, N) yields a vector property with N components (e.g. (atom, spatial) for 3-vectors), and (atom, N, M) yields a vector property with N*×*M components, which stores the matrix elements in row-major order. The following NetCDF variable names are automatically mapped to OVITO’s standard particle properties (case-insensitive):

NetCDF variable	OVITO particle property
coordinates, unwrapped_coordinates	Position
velocities	Velocity
forces, force	Force
id, identifier	Particle Identifier
type, atom_types, element, species	Particle Type
mass	Mass
radius	Radius
color	Color
selection	Selection
c_epot	Potential Energy
c_kpot	Kinetic Energy
c_cna, pattern	Structure Type

A variable whose name exactly matches the name of any other standard particle property (e.g. Charge or Stress Tensor) is mapped to that property as well. The automatic mapping to a standard property requires the number of vector components stored in the file to match the number of components of the OVITO property; otherwise, and for all variables with unrecognized names, a user-defined particle property with the name of the NetCDF variable is created. Dots, slashes, and colons in variable names are replaced with underscores. The data type of a user-defined property is inherited from the NetCDF variable: byte, short/int, int64, float, and double variables are stored as 8-bit, 32-bit, and 64-bit integer, and 32-bit and 64-bit floating-point properties, respectively. Variables of any other NetCDF data type (char strings, unsigned integer types) are ignored.

The particle types read from the type variable (or one of its aliases) are numeric IDs. The file reader creates one particle type per distinct numeric ID occurring in the file; the types remain unnamed. If the file contains a Velocity property, the reader also computes the Velocity Magnitude property automatically.

Simulation cell

The simulation cell is constructed from the per-frame variables cell_lengths and cell_angles (dimensions (frame, cell_spatial) and (frame, cell_angular)), which specify the three cell edge lengths and the angles \(\alpha\), \(\beta\), \(\gamma\) in degrees. The cell vector \(\mathbf{a}\) is aligned with the Cartesian x-axis and \(\mathbf{b}\) lies in the x-y plane. Two extensions to the AMBER convention are supported: the optional variable cell_origin (written by LAMMPS, ASE, and OVITO) specifies the position of the cell corner, which is placed at the coordinate origin otherwise, and the optional variable shear_dx (written by Atomistica) specifies an additional shear displacement of the \(\mathbf{c}\) vector in the x-y plane.

Following the AMBER convention, a cell edge length of zero indicates a non-periodic direction. Directions with non-zero length are treated as periodic. In non-periodic directions, the cell extent is replaced by the extent of the axis-aligned bounding box of the particle coordinates. If the file contains no cell information at all (or all cell lengths are zero), no simulation cell is created unless the option Generate bounding box if needed is enabled.

Global attributes

Every numeric variable that has the frame dimension as its only dimension (e.g. time) is imported as a global attribute named after the variable, holding the variable’s value for the current frame. This includes, for instance, the thermodynamic quantities written by the LAMMPS dump_modify thermo option. Entries equal to the variable’s NetCDF fill value are skipped, and variables named SourceFile or SourceFrame are ignored, because these attribute names are reserved by OVITO. The optional global attribute title of the NetCDF file is made available as the global attribute NetCDF_Title. The global attributes program, programVersion, and application are ignored.

Limitations

• The reader ignores the units and scale_factor attributes of variables. All values are imported as stored in the file, without unit conversion. Note that LAMMPS, for instance, stores the timestep number in the time variable and the timestep size in its scale_factor attribute; OVITO imports the unscaled timestep number as time attribute.

• String-valued per-atom variables (data type char) are not supported. In particular, chemical element names cannot be read from such variables; particle types must be given as integer IDs.

• The atomic numbers stored by ASE in a variable named Z are imported as a user-defined property Z rather than as particle types. You can map this variable to the Particle Type property via the Edit column mapping dialog if desired.

• The NetCDF format does not store bonds or other topology information.

• Bond generation during import (the Generate bonds option of other readers) is not available for this file reader. Bonds can be generated after import using the Create bonds modifier.

Options

Generate bounding box if needed

If this option is enabled and the file contains no cell dimensions (all cell edge lengths are zero or the cell_lengths variable is absent), OVITO will generate an axis-aligned bounding box enclosing all particles. This bounding box has open boundary conditions and serves as an approximate simulation cell.

Sort particles by ID

If enabled, OVITO reorders the loaded particles according to the values of the Particle Identifier property, i.e. the id or identifier variable of the file. Otherwise the storage order of the file is preserved.

File columns

By default, the mapping of NetCDF variables to OVITO particle properties is performed automatically according to the rules described above (Automatic mapping). Select User-defined mapping to particle properties and click Edit column mapping to override the mapping. The dialog lists all per-atom variables found in the file, and for each one you can choose the OVITO particle property it should be mapped to, or exclude it from the import. Mapping a 3×3 matrix variable with 9 components (e.g. a per-atom virial or stress tensor) to one of OVITO’s symmetric tensor properties with 6 components, such as Stress Tensor, performs an automatic conversion to Voigt notation by averaging the off-diagonal elements. The same mapping can be specified in Python using the columns parameter (see below).

Python parameters

The file reader accepts the following optional keyword parameters in a call to the import_file() or load() Python functions.

import_file(location, columns=None, bounding_box=False, sort_particles=False)

Parameters:

• columns (list[str|None]) – An optional list of particle property names, which overrides the automatic mapping of the per-atom NetCDF variables to OVITO particle properties. The list must contain one entry per per-atom variable of the file, in the order in which the variables appear in the file (i.e. the order shown in the Edit column mapping dialog). Use None to skip a variable. A 3×3 matrix variable can be mapped to a symmetric tensor property with six components (e.g. 'Stress Tensor'), which converts the values to Voigt notation.

• bounding_box (bool) – Generate an ad-hoc SimulationCell as an axis-aligned bounding box around the imported particles when the file contains no cell dimensions.

• sort_particles (bool) – Makes the file reader reorder the loaded particles before passing them to the pipeline. Sorting is based on the values of the Particle Identifier property loaded from the file.

Added in version 3.17.0: The columns parameter.