Trajectory

class chemfiles::Trajectory

A Trajectory is a chemistry file on the hard drive. It is the entry point of the chemfiles library.

Public Functions

Trajectory(std::string path, char mode = 'r', const std::string &format = "")

Open a file, automatically gessing the file format from the extension.

The format parameter should be a string formatted as "<format>", "<format>/<compression>" or "/<compression>". <format> should be the format name (see the corresponding documentation section for the names) or an empty string. <compression> should be GZ for gzip files, BZ2 for bzip2 files, or XZ for lzma/.xz files. If <compression> is present, it will determine which compression method is used to read/write the file.

For example, format = "XYZ" will force usage of XYZ format regardless of the file extension; format = "XYZ / GZ" will additionally use gzip compression; and format = "/ GZ" will use the gzip compression, and the file extension to guess the format.

If the format is an empty string, the file extension will be used to guess the format. If <compression> is NOT present and the file path ends with .gz, .xz, or .bz2; the file will be treated as a compressed file and the next extension is used to guess the format. For example Trajectory("file.xyz.gz") will open the file for reading using the XYZ format and the gzip compression method.

// Simplest case: open a file for reading it, the format is guessed from
// the extension.
auto water = Trajectory("water.nc");

// Open a file in a specific mode
auto copper = Trajectory("copper.xyz", 'w');

// Specify the file format to use
auto nanotube = Trajectory("nanotube.lmp", 'r', "LAMMPS Data");

// Write a gzip-compressed file
auto protein = Trajectory("protein.arc.gz", 'w');

Parameters

  • path: The file path. In w or a modes, the file is created if it does not exist yet. In r mode, an exception is thrown is the file does not exist yet.

  • mode: Opening mode for the file. Default mode is r for read. Other supported modes depends on the underlying format and are w for write, and a for append. w mode discard any previously existing file.

  • format: Specific format to use. Needed when there is no way to guess the format from the extension of the file, or when this guess would be wrong.

Exceptions

  • FileError: for all errors concerning the physical file: can not open it, can not read/write it, etc.

  • FormatError: if the file is not valid for the used format.

Frame read()

Read the next frame in the trajectory.

The trajectory must have been opened in read mode, and the underlying format must support reading.

This function throws a FileError if there are no more frames to read in the trajectory.

auto trajectory = Trajectory("water.nc");

auto frame = trajectory.read();
// Use the frame for awesome science here!

// This is one way to iterate over all the frames in a trajectory
while (!trajectory.done()) {
    frame = trajectory.read();
    // ...
}

Exceptions

  • FileError: for all errors concerning the physical file: can not open it, can not read/write it, etc.

  • FormatError: if the file is not valid for the used format, or if the format does not support reading.

Frame read_step(size_t step)

Read a single frame at specified step from the trajectory.

The trajectory must have been opened in read mode, and the underlying format must support reading.

This function throws a FileError if the step is bigger than the number of steps in the trajectory.

auto trajectory = Trajectory("water.nc");

auto frame = trajectory.read_step(4);
// Use the frame for awesome science here!

// This is one way to iterate over all the frames in a trajectory
for (size_t i = 0; i < trajectory.nsteps(); i++) {
    frame = trajectory.read_step(i);
    // ...
}

Parameters

  • step: step to read from the trajectory

Exceptions

  • FileError: for all errors concerning the physical file: can not open it, can not read/write it, etc.

  • FormatError: if the file is not valid for the used format, or if the format does not support reading.

void write(const Frame &frame)

Write a single frame to the trajectory.

The trajectory must have been opened in write or append mode, and the underlying format must support reading.

auto trajectory = Trajectory("water.nc", 'w');

auto frame = Frame();
frame.add_atom(Atom("O"), {0, 0, 0});
frame.add_atom(Atom("H"), {1, 0, 0});
frame.add_atom(Atom("H"), {0, 1, 0});

trajectory.write(frame);

Parameters

  • frame: frame to write to this trajectory

Exceptions

  • FileError: for all errors concerning the physical file: can not open it, can not read/write it, etc.

  • FormatError: if the format does not support writing.

void set_topology(const Topology &topology)

Use the given topology instead of any pre-existing Topology when reading or writing.

This replace any topology in the file being read, or in the Frame being written.

This is mainly usefull when a format does not define topological information, as it can be the case with some molecular dynamic formats.

// A water topology
auto topology = Topology();
topology.add_atom(Atom("O"));
topology.add_atom(Atom("H"));
topology.add_atom(Atom("H"));
topology.add_bond(0, 1);
topology.add_bond(0, 2);

auto trajectory = Trajectory("water.nc");
trajectory.set_topology(topology);

auto frame = trajectory.read();
// The topology of the frame is now a water molecule, regardless of
// what was defined in the trajectory.

// One can also set the topology from a file
trajectory.set_topology("water.pdb");

// Or set it from a file with a specific format
trajectory.set_topology("water.mol", "XYZ");

Parameters

  • topology: the topology to use with this frame

Exceptions

  • Error: if the topology does not contain the right number of atoms at any step.

void set_topology(const std::string &filename, const std::string &format = "")

Use the Topology from the first Frame of the Trajectory at filename instead any pre-existing Topology when reading or writing.

This replace any topology in the file being read, or in the Frame being written.

This is mainly usefull when a format does not define topological information, as it can be the case with some molecular dynamic formats.

// A water topology
auto topology = Topology();
topology.add_atom(Atom("O"));
topology.add_atom(Atom("H"));
topology.add_atom(Atom("H"));
topology.add_bond(0, 1);
topology.add_bond(0, 2);

auto trajectory = Trajectory("water.nc");
trajectory.set_topology(topology);

auto frame = trajectory.read();
// The topology of the frame is now a water molecule, regardless of
// what was defined in the trajectory.

// One can also set the topology from a file
trajectory.set_topology("water.pdb");

// Or set it from a file with a specific format
trajectory.set_topology("water.mol", "XYZ");

Parameters

  • filename: trajectory file path.

  • format: Specific format to use. Needed when there is no way to guess the format from the extension of the file, or when this guess would be wrong.

Exceptions

  • FileError: for all errors concerning the physical file: can not open it, can not read it, etc.

  • FormatError: if the file is not valid for the used format.

  • Error: if the topology does not contain the right number of atoms at any step.

void set_cell(const UnitCell &cell)

Use the given cell instead of any pre-existing UnitCell when reading or writing.

This replace any unit cell in the file being read, or in the Frame being written.

This is mainly usefull when a format does not define unit cell information.

auto trajectory = Trajectory("water.xyz");
trajectory.set_cell(UnitCell({11, 11, 22}));

auto frame = trajectory.read();
// The frame cell is now an orthorhombic cell with lengths of
// 11 A, 11 A and 22 A, regardless of what was defined in the file.
assert(frame.cell() == UnitCell({11, 11, 22}));

Parameters

  • cell: the unit cell to use with this frame

size_t nsteps() const

Get the number of steps (the number of frames) in this trajectory.

auto trajectory = Trajectory("water.nc");

auto nsteps = trajectory.nsteps();
for (size_t i = 0; i < nsteps; i++) {
    auto frame = trajectory.read_step(i);
}

bool done() const

Check if all the frames in this trajectory have been read, i.e. if the last read frame is the last frame of the trajectory.

auto trajectory = Trajectory("water.nc");

while (!trajectory.done()) {
    auto frame = trajectory.read();
}

// When using `read_step`, `done()` returns `true` if the most recent call
// was used to read the last step (`nsteps() - 1`).
auto frame = trajectory.read_step(0);
assert(!trajectory.done());

auto nsteps = trajectory.nsteps();
frame = trajectory.read_step(nsteps - 1);
assert(trajectory.done());

void close()

Close a trajectory, and synchronize all buffered content with the drive.

Calling any function on a closed trajectory will throw a FileError.

auto trajectory = Trajectory("water.nc");

auto frame = Frame();
// setup the frame

trajectory.write(frame);
trajectory.close();

const std::string &path() const

Get the path used to open the trajectory

auto trajectory = Trajectory("water.nc");

assert(trajectory.path() == "water.nc");

optional<span<const char>> memory_buffer() const

Get the memory buffer used for writing if the trajectory was created with Trajectory::memory_writer.

If the trajectory was not created for writing to memory, this will return nullopt.

auto trajectory_memory = Trajectory::memory_writer("SMI");

auto ethane = Frame();
ethane.add_atom(Atom("C"), {0, 0, 0});
ethane.add_atom(Atom("C"), {0, 0, 0});
ethane.add_bond(0, 1, Bond::SINGLE);

trajectory_memory.write(ethane);

auto result = *trajectory_memory.memory_buffer();
CHECK( std::string(result.data(), result.size()) == std::string("CC\n"));

// This function will return nullopt if opened with a regular file
auto trajectory_file = Trajectory("ethane.smi", 'w');
CHECK(trajectory_file.memory_buffer() == nullopt);

Public Static Functions

Trajectory memory_reader(const char *data, size_t size, const std::string &format)

Read a memory buffer as though it were a formatted file

The format parameter should be follow the same rules as in the main Trajectory constructor.

// Text based formats and some binary support reading from memory
auto aromatics = std::string("c1ccccc1\nc1ccco1\nc1ccccn1\n");
auto trajectory = Trajectory::memory_reader(aromatics.data(), aromatics.size(), "SMI");
auto benzene = trajectory.read();
CHECK(benzene.size() == 6);

// Other formats do not and will throw an error
CHECK_THROWS_WITH(
    Trajectory::memory_reader(aromatics.data(), aromatics.size(), "DCD"),
    "in-memory IO is not supported for the 'DCD' format"
);

Parameters

  • data: The start of the memory buffer used to store the file. It does not need to be null terminated.

  • size: The size of the memory buffer.

  • format: Specific format to use.

Exceptions

  • FileError: If the compression given in format is not supported

  • FormatError: if the data in the buffer is not valid for the used format, or the format does not support reading from a memory buffer

Trajectory memory_writer(const std::string &format)

Write to a memory buffer as though it were a formatted file

The format parameter should be follow the same rules as in the main Trajectory constructor, except that compression specification are not supported.

To retreive the memory written to by the returned Trajectory object, make a call to the memory_buffer function.

// Text based formats support writing to memory
auto trajectory_memory = Trajectory::memory_writer("SMI");

// Binary formats typically do not support this feature
CHECK_THROWS_WITH(
    Trajectory::memory_writer("XTC"),
    "in-memory IO is not supported for the 'XTC' format"
);

Parameters

  • format: Specific format to use.

Exceptions

  • FileError: If any compression is given in format

  • FormatError: if the format does not support writing to a memory buffer