Format classes

Interface for formats

class Format

The Format class defines the interface to implement in order to add a new format to chemfiles. For text-based formats, it might be simpler to implement the TextFormat interface instead.

It is possible to implement only one of Format::read; Format::read_step or Format::write. In that case, only the corresponding operations will be available from the corresponding chemfiles::Trajectory.

Subclassed by chemfiles::AmberNetCDFBase, chemfiles::CIFFormat, chemfiles::CMLFormat, chemfiles::DCDFormat, chemfiles::mmCIFFormat, chemfiles::MMTFFormat, chemfiles::Molfile< F >, chemfiles::TextFormat, chemfiles::TNGFormat, chemfiles::TPRFormat, chemfiles::TRRFormat, chemfiles::XTCFormat

Public Functions

virtual void read_step(size_t step, Frame &frame)

Read a specific step from the trajectory file.

Throws:
  • FormatError – if the file does not follow the format

  • FileError – if their is an OS error while reading the file

Parameters:
  • step – The step to read

  • frame – The frame to fill

virtual void read(Frame &frame)

Read the next step from the trajectory file.

Throws:
  • FormatError – if the file does not follow the format

  • FileError – if their is an OS error while reading the file

Parameters:

frame – The frame to fill

virtual void write(const Frame &frame)

Write a frame to the trajectory file.

Throws:
  • FormatError – if the file does not follow the format

  • FileError – if their is an OS error while reading the file

Parameters:

frame – The frame to be written

virtual size_t nsteps() = 0

Get the number of frames in the associated file. This function can be expensive to call since it may needs to scan the whole file.

Returns:

The number of frames

class TextFormat : public chemfiles::Format

The TextFormat class defines a common, simpler interface for text based formats.

It is possible to implement only one of TextFormat::read_next or TextFormat::write_next. In that case, only the corresponding operations will be available from the corresponding chemfiles::Trajectory.

Subclassed by chemfiles::CSSRFormat, chemfiles::GROFormat, chemfiles::LAMMPSDataFormat, chemfiles::LAMMPSTrajectoryFormat, chemfiles::MOL2Format, chemfiles::PDBFormat, chemfiles::SDFFormat, chemfiles::SMIFormat, chemfiles::TinkerFormat, chemfiles::XYZFormat

Public Functions

virtual void read_step(size_t step, Frame &frame) override

Read a specific step from the trajectory file.

Throws:
  • FormatError – if the file does not follow the format

  • FileError – if their is an OS error while reading the file

Parameters:
  • step – The step to read

  • frame – The frame to fill

virtual void read(Frame &frame) override

Read the next step from the trajectory file.

Throws:
  • FormatError – if the file does not follow the format

  • FileError – if their is an OS error while reading the file

Parameters:

frame – The frame to fill

virtual void write(const Frame &frame) override

Write a frame to the trajectory file.

Throws:
  • FormatError – if the file does not follow the format

  • FileError – if their is an OS error while reading the file

Parameters:

frame – The frame to be written

virtual size_t nsteps() override

Get the number of frames in the associated file. This function can be expensive to call since it may needs to scan the whole file.

Returns:

The number of frames

virtual optional<uint64_t> forward() = 0

Fast-forward the file for one step, returning a valid position if the file does contain one more step or nullopt if it does not.

Implemented formats

These classes implement the format interface defined previously.

class AmberTrajectory : public chemfiles::AmberNetCDFBase

Amber NetCDF trajectory file format.

class AmberRestart : public chemfiles::AmberNetCDFBase

Amber NetCDF restart file format.

class TNGFormat : public chemfiles::Format

TNG file format reader.

class TinkerFormat : public chemfiles::TextFormat

Tinker XYZ file format.

The format is described here: http://chembytes.wikidot.com/tnk-tut00#toc2. Additionally to the original Tinker XYZ format, chemfiles also supports the files with unit cell data, as introduced in Tinker 6.3.

This format is associated with the .arc extension, but not the .xyz extension, which is used for the standard XYZ format.

template<MolfileFormat F>
class Molfile : public chemfiles::Format

Use of VMD Molfile plugins as format reader. This class is templated by a value in the MolfileFormat enum.

enum chemfiles::MolfileFormat

List all the VMD molfile plugins enabled. For more documentation about VMD molfile plugins, please see: http://www.ks.uiuc.edu/Research/vmd/plugins/molfile/

Values:

enumerator TRJ

Gromacs .trj file format.

enumerator PSF

PSF topology files.

enumerator MOLDEN

Molden file format.

class CIFFormat : public chemfiles::Format

CIF (Crystallographic Information Framework) files reader and writer.

The reader code is based on the gemmi project.

class CMLFormat : public chemfiles::Format

CML file format reader.

class mmCIFFormat : public chemfiles::Format

mmCIF Crystallographic Information Framework for MacroMolecules reader and writer.

class MMTFFormat : public chemfiles::Format

MMTF file format reader and writer.

For multi-frame trajectories, we follow the PyMOL convention to use multiple models for different frames

class TRRFormat : public chemfiles::Format

GROMACS TRR file format reader.

class XTCFormat : public chemfiles::Format

GROMACS XTC file format reader.

class XYZFormat : public chemfiles::TextFormat

XYZ file format reader and writer.

This class also support the extended XYZ specification, as defined in ASE

class CSSRFormat : public chemfiles::TextFormat

CSSR (Cambridge Structure Search and Retrieval) file format reader and writer. Only one frame can be read or written to this format.

class GROFormat : public chemfiles::TextFormat

GRO file format reader and writer.

class LAMMPSDataFormat : public chemfiles::TextFormat

LAMMPS Data file format reader and writer.

LAMMPS data files are not fully stand-alone, as one needs to know the atom style to read the data. This reader will try to guess the atom style by checking the first line of the header for atom_style <style>, and by reading any comment after the Atoms section name. If no atom style is specified, the code default to full and send a warning.

The code also tries to read atomic names at the end of data lines. For example, the atom at index 44 will have C2 as atomic name.

44 44 2 0.000000 1.094000 2.061000 69.552002 # C2 RES
class MOL2Format : public chemfiles::TextFormat

Tripos MOL2 format reader and writer.

class PDBFormat : public chemfiles::TextFormat

PDB file format reader and writer.

For multi-frame trajectories, we support both the convention from VMD to use multiple END records separating the steps; or the use of multiple MODEL/ENDMODEL pairs.

class SDFFormat : public chemfiles::TextFormat

SDF file format reader and writer.

class SMIFormat : public chemfiles::TextFormat

SMI/OpenSMILES file format reader and writer.