Miscelaneous¶

Basic types¶

class Vector3D : private std::array<double, 3>¶

3D vector for basic data storage in chemfiles.

This type defines the following operators, with the usual meaning:

Comparison operators: == and != performs strict float equality comparison;
Mathematical operators: + and - for addition and substraction of vectors, * and / for multiplication and division by double values. Multiplication with * is also defined for multiplication by a Matrix3D.

Public Functions

inline Vector3D()¶

Create a Vector3D with all components equal to 0.

inline Vector3D(double x, double y, double z)¶

Create a Vector3D from the three components x, y, and z.

inline double norm() const¶

Compute the euclidean norm of this Vector3D.

inline Vector3D &operator+=(const Vector3D &rhs)¶: Compound addition of two vectors.

inline Vector3D &operator-=(const Vector3D &rhs)¶: Compound subtraction of two vectors.

inline Vector3D &operator*=(double rhs)¶: Compound multiplication of a vector and a scalar.

inline Vector3D &operator/=(double rhs)¶: Compound division of a vector by a scalar.

inline double chemfiles::dot(const Vector3D &lhs, const Vector3D &rhs)¶

Compute the dot product of the vectors lhs and rhs.

inline Vector3D chemfiles::cross(const Vector3D &lhs, const Vector3D &rhs)¶

Compute the cross product of the vectors lhs and rhs.

class Matrix3D : private std::array<std::array<double, 3>, 3>¶

A 3x3 matrix class.

This type defines the following operators, with the usual meaning:

Comparison operators: == and != performs strict float equality comparison;
Mathematical operators: only multiplication between matrixes and between matrix and vector are defined, using the * operator.

Public Functions

inline Matrix3D(double m11, double m12, double m13, double m21, double m22, double m23, double m31, double m32, double m33)¶

Create a Matrix3D by explicitly specifying all the m_ij components of the matrix.

inline double determinant() const¶

Compute the determinant of this matrix.

inline Matrix3D invert() const¶

Compute the inverse of this matrix.

Throws:: Error – if the matrix is not invertible (i.e. if the determinant is zero)

inline Matrix3D transpose() const¶

Transpose the matrix.

inline Matrix3D &operator+=(const Matrix3D &rhs)¶: Compound addition of two matrices.

inline Matrix3D &operator-=(const Matrix3D &rhs)¶: Compound subtraction of two matrices.

inline Matrix3D &operator*=(double rhs)¶: Compound multiplication of a matrix and a scalar.

inline Matrix3D &operator/=(double rhs)¶: Compound division of a matrix by a scalar.

Public Static Functions

static inline Matrix3D zero()¶

Create a Matrix3D with all components set to zero.

static inline Matrix3D unit()¶

Create an unit Matrix3D (a diagonal matrix with all diagonal values set to 1).

Format list and Metadata¶

std::string chemfiles::guess_format(std::string path, char mode = 'r')¶

Get the format that chemfiles would use to read a file at the given path.

Most of the time, the format is only guessed from the filename extension, without reading the file to guess the format. When two or more format can share the same extension (for example CIF and mmCIF), chemfiles tries to read the file to distinguish between them. If reading fails, the default format for this extension is returned.

Opening the file using the returned format string might still fail. For example, it will fail if the file is not actually formatted according to the guessed format; or the format/compression combination is not supported (e.g. XTC / GZ will not work since the XTC reader does not support compressed files).

The format is represented in a way compatible with the various Trajectory constructors, i.e. "<format name> [/ <compression>]", where compression is optional.

Parameters:

path – path of the file we are trying to read
mode – the opening mode of the file, can be ‘r’, ‘a’ or ‘w’

Throws:

FormatError – if no format matching this filename is found.

Returns:

guessed format of the file

std::vector<std::reference_wrapper<const FormatMetadata>> chemfiles::formats_list()¶

Get the list of formats chemfiles knows about, and all associated metadata

class FormatMetadata¶

Metadata associated with a format.

Public Members

const char *name = ""¶: Name of the format.

optional<const char*> extension = nullopt¶: Potential extension associated with the format.

const char *description = ""¶: User facing format description.

const char *reference = ""¶: URL pointing to the format definition/reference.

bool read = false¶: Is reading files in this format implemented?

bool write = false¶: Is writing files in this format implemented?

bool memory = false¶: Does this format support in-memory IO?

bool positions = false¶: Does this format support storing atomic positions?

bool velocities = false¶: Does this format support storing atomic velocities?

bool unit_cell = false¶: Does this format support storing unit cell information?

bool atoms = false¶: Does this format support storing atom names or types?

bool bonds = false¶: Does this format support storing bonds between atoms?

bool residues = false¶: Does this format support storing residues?

Errors handling¶

In chemfiles, any error will throw an exception. Any program using chemfiles should thus wrap any call in a try ... catch block, and handle the errors in any pertinent way.

#include <iostream>
#include <chemfiles.hpp>

int main() {
    try {
        chemfiles::Trajectory file("filename.xyz");
        auto frame = file.read();
        auto positions = frame.positions();
        // Do something here
    } catch (const chemfiles::Error& e) {
        // Basic error handling logging error to stdout
        std::cout << "Error in chemfiles:" << e.what() << std::endl;
        return -1;
    }

    return 0;
}

Any exceptions thrown by chemfiles will derive from chemfiles::Error. Catching chemfiles::Error will then catch any exception thrown by chemfiles. You also can catch any other error if you need finer grain control. chemfiles::Error derives from std::runtime_error, so it should play nicely with any existing C++ error handling.

struct Error : public std::runtime_error¶

Base exception class for chemfiles library.

Subclassed by chemfiles::ConfigurationError, chemfiles::FileError, chemfiles::FormatError, chemfiles::MemoryError, chemfiles::OutOfBounds, chemfiles::PropertyError, chemfiles::SelectionError

struct FileError : public chemfiles::Error ¶: Exception for files related failures.

struct MemoryError : public chemfiles::Error ¶: Exception for memory related failures.

struct FormatError : public chemfiles::Error ¶: Exception for formats related failures.

struct SelectionError : public chemfiles::Error ¶: Exception for errors in selections.

struct ConfigurationError : public chemfiles::Error ¶: Exception for errors in configuration files.

struct OutOfBounds : public chemfiles::Error ¶: Exception for out of bounds error when accessing atoms or residues.

struct PropertyError : public chemfiles::Error ¶: Exception for errors related to frame and atomic properties.

Warnings¶

Chemfiles send warnings when it encounters malformed files, or any other condition that the user might want to know about. By default, these warnings are printed to the standard error stream. chemfiles::set_warning_callback() allow to redirect these warning by giving it a callback function to be called on each warning event.

void chemfiles::set_warning_callback(warning_callback_t callback)¶

Set the global callback for warning events. The default is to print them on the standard error stream.

Parameters:: callback – callback function that will be called on each warning

typedef std::function<void(const std::string &message)> chemfiles::warning_callback_t¶: Callback type used to process a warning event.

Configuration files¶

You can add more configuration file to chemfiles with chemfiles::add_configuration().

void chemfiles::add_configuration(const std::string &path)¶

Read configuration data from the file at path.

By default, chemfiles reads configuration from any file named .chemfiles.toml or chemfiles.toml in the current directory or any parent directory. This function can be used to add data from another configuration file.

This function will throw a ConfigurationError if there is no file at path, or if the file is incorrectly formatted. Data from the new configuration file will overwrite any existing data.

Parameters:: path – path to the configuration file to add
Throws:: ConfigurationError – if the file at path can not be read, or if it is invalid.