NetCDFReader

class mdcraft.io.reader.NetCDFReader(filename: str | Path, /, *, package: str = 'netcdf4', dt: float | Quantity | Quantity | None = None, **kwargs)

Bases: BaseTrajectoryReader

AMBER NetCDF trajectory/restart file reader.

See also

For more information on the AMBER NetCDF file format, see the AMBER NetCDF Trajectory/Restart Convention.

Parameters:

filenamestr or pathlib.Path, positional-only

Filename or path to the NetCDF file.

packagestr, optional, keyword-only, default: "netcdf4"

Specifies which package to use for reading the NetCDF file.

Valid values: "netcdf4" or "scipy".

dtfloat, optional

Simulation time step size.

Reference unit: \(\mathrm{ps}\).

Methods

close	Closes the NetCDF file and deletes the handle.
get_dimensions	Gets the dimensions (lattice parameters) of the simulation box.
get_extra_variables	Gets extra attvariablesributes found in the NetCDF file.
get_forces	Gets the forces acting on the atoms.
get_positions	Gets the atom positions.
get_remd_variables
get_times	Gets the simulation times.
get_velocities	Gets the atom velocities.
open	Opens the NetCDF file and stores a handle to it.
read_frames	Reads data from one or more frames from the trajectory file.

close() → None

Closes the NetCDF file and deletes the handle.

property dt: float | None

Time step size between timesteps in the trajectory. A value is returned only when a step size was specified using dt in the constructor since NetCDF trajectories do not contain this information.

Unit: \(\mathrm{ps}\).

get_dimensions(frame_indices: int | list[int] | slice | None = None, convert_units: bool = True, *, _file: 'nc.Dataset' | netcdf_file | None = None) → tuple[np.ndarray[np.float64] | np.ndarray[np.float64]]

Gets the dimensions (lattice parameters) of the simulation box.

Parameters:

frame_indicesint, list, or slice, optional

Frame indices. If None, the dimensions across all frames are returned.

convert_unitsbool, default True

Specifies whether to convert the data from AMBER NetCDF units to consistent MDCraft units.

Returns:

dimensionsnumpy.ndarray

Simulation box dimensions.

Shape: \((6,)\) or \((N_\mathrm{frames},6)\).

Reference units: \(\mathrm{Å}\) for the lengths and \(^\circ\) for the angles.

get_extra_variables(frame_indices: int | list[int] | slice | None = None, *, _file: 'nc.Dataset' | netcdf_file | None = None) → dict[str, np.ndarray[np.float64]]

Gets extra attvariablesributes found in the NetCDF file.

Parameters:

frame_indicesint, list, or slice, optional

Frame indices. If None, the dimensions across all frames are returned.

Returns:

variablesdict

Extra variables found in the NetCDF file.

get_forces(frame_indices: int | list[int] | slice | None = None, convert_units: bool = True, *, _file: 'nc.Dataset' | netcdf_file | None = None) → np.ndarray[np.float64]

Gets the forces acting on the atoms.

Parameters:

frame_indicesint, list, or slice, optional

Frame indices. If None, the dimensions across all frames are returned.

convert_unitsbool, default True

Specifies whether to convert the data from AMBER NetCDF units to consistent MDCraft units.

Returns:

forcesnumpy.ndarray or openmm.unit.Quantity

Forces acting on the atoms. If the NetCDF file does not contain this information, None is returned.

Shape: \((N_\mathrm{atoms},3)\) or \((N_\mathrm{frames},N_\mathrm{atoms},3)\).

Reference unit: \(\mathrm{kJ/(mol\cdot Å)}\).

get_positions(frame_indices: int | list[int] | slice | None = None, convert_units: bool = True, *, _file: 'nc.Dataset' | netcdf_file | None = None) → np.ndarray[np.float64]

Gets the atom positions.

Parameters:

frame_indicesint, list, or slice, optional

Frame indices. If None, the positions across all frames are returned.

convert_unitsbool, default True

Specifies whether to convert the data from AMBER NetCDF units to consistent MDCraft units.

Returns:

positionsnumpy.ndarray

Atom positions.

Shape: \((N_\mathrm{atoms},3)\) or \((N_\mathrm{frames},N_\mathrm{atoms},3)\).

Reference unit: \(\mathrm{Å}\).

get_times(frame_indices: int | list[int] | slice | None = None, convert_units: bool = True, *, _file: 'nc.Dataset' | netcdf_file | None = None) → int | np.ndarray[np.float64]

Gets the simulation times.

Parameters:

framesint, list, or slice, optional

Frame indices. If None, the times across all frames are returned.

convert_unitsbool, default True

Specifies whether to convert the data from AMBER NetCDF units to consistent MDCraft units.

Returns:

timesint or numpy.ndarray

Simulation times.

Shape: Scalar or \((N_\mathrm{frames},)\).

Reference unit: \(\mathrm{ps}\).

get_velocities(frame_indices: int | list[int] | slice | None = None, convert_units: bool = True, *, _file: 'nc.Dataset' | netcdf_file | None = None) → np.ndarray[np.float64]

Gets the atom velocities.

Parameters:

frame_indicesint, list, or slice, optional

Frame indices. If None, the velocities across all frames are returned.

convert_unitsbool, default True

Specifies whether to convert the data from AMBER NetCDF units to consistent MDCraft units.

Returns:

velocitiesnumpy.ndarray or openmm.unit.Quantity

Atom velocities. If the NetCDF file does not contain this information, None is returned.

Shape: \((N_\mathrm{atoms},3)\) or \((N_\mathrm{frames},N_\mathrm{atoms},3)\).

Reference unit: \(\mathrm{Å/ps}\).

property n_atoms: int

Number of atoms in each frame.

property n_frames: int

Number of frames in the trajectory.

open() → None

Opens the NetCDF file and stores a handle to it.

read_frames(frame_indices: int | slice | Iterable[int], /, *, _convert_units: bool = True) → dict[str, Any] | list[dict[str, Any]]

Reads data from one or more frames from the trajectory file.

Parameters:

frame_indicesint, slice, or array-like, positional-only

Indices of frames to read.

Returns:

datadict or list

Data from the frame(s).

property time_step: float | None

Time step between frames in the trajectory. If None, the time step is not constant across frames.

Unit: \(\mathrm{ps}\).

property times: ndarray[float64]

Simulation times.

Unit: \(\mathrm{ps}\).

property timesteps: ndarray[uint32] | None

Simulation timesteps found in the trajectory. An array is returned only when a step size was specified using dt in the constructor since NetCDF trajectories do not contain this information.