# Miscelaneous classes and functions¶

## Basic types¶

class chemfiles::Vector3D

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.

// equality and inequality
assert(Vector3D() == Vector3D(0, 0, 0));
assert(Vector3D(1, 2, 3) != Vector3D(0, 0, 0));

// Indexing
auto u = Vector3D(1.5, 2.0, -3.0);
assert(u[0] == 1.5);
assert(u[1] == 2.0);
assert(u[2] == -3.0);

// sum and difference
auto sum = Vector3D(1, 0, 1) + Vector3D(0, 2, 1);
assert(sum == Vector3D(1, 2, 2));

auto diff = Vector3D(1, 0, 1) - Vector3D(0, 2, 1);
assert(diff == Vector3D(1, -2, 0));

// product and division by a scalar
auto rhs = Vector3D(1, 0, 1) * 5;
assert(rhs == Vector3D(5, 0, 5));

auto lhs = 5 * Vector3D(1, 0, 1);
assert(lhs == Vector3D(5, 0, 5));

auto div = Vector3D(2, 0, 3) / 3;
assert(div == Vector3D(2.0/3, 0, 1));


Inherits from std::array< double, 3 >

Public Functions

Vector3D()

Create a Vector3D with all components equal to 0.

auto v = Vector3D();
assert(v[0] == 0.0);
assert(v[1] == 0.0);
assert(v[2] == 0.0);


Vector3D(double x, double y, double z)

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

auto u = Vector3D(1.5, 2.0, -3.0);
assert(u[0] == 1.5);
assert(u[1] == 2.0);
assert(u[2] == -3.0);


double norm() const

Compute the euclidean norm of this Vector3D.

auto v = Vector3D(1.0, 1.0, 1.0);
assert(v.norm() == sqrt(3));


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

Compute the dot product of the vectors lhs and rhs.

auto u = Vector3D(0, 1, 2);
auto v = Vector3D(1, 0, 2);

assert(dot(u, v) == 4);


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

Compute the cross product of the vectors lhs and rhs.

auto u = Vector3D(0, 1, 2);
auto v = Vector3D(1, 0, 2);

assert(cross(u, v) == Vector3D(2, 2, -1));


class chemfiles::Matrix3D

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 mulitplication between matrixes and between matrix and vector are defined, using the * operator.

// equality and inequality
assert(Matrix3D() == Matrix3D(0, 0, 0));
assert(Matrix3D(1, 2, 3) != Matrix3D(0, 0, 0));

// Indexing
auto M = Matrix3D(
11, 12, 13,
21, 22, 23,
31, 32, 33
);
assert(M[0][0] == 11);
assert(M[0][1] == 12);
assert(M[0][2] == 13);

assert(M[1][0] == 21);
assert(M[1][1] == 22);
assert(M[1][2] == 23);

assert(M[2][0] == 31);
assert(M[2][1] == 32);
assert(M[2][2] == 33);

// Matrix-vector multiplication
auto mat_vec = Matrix3D(1, 3, 2) * Vector3D(1, 1, 1);
assert(mat_vec == Vector3D(1, 3, 2));

// Matrix-Matrix multiplication
auto mat_mat = Matrix3D(1, 3, 2) * Matrix3D(0.5, 2, 1);
assert(mat_mat == Matrix3D(0.5, 6, 2));


Inherits from std::array< std::array< double, 3 >, 3 >

Public Functions

Matrix3D()

Create a Matrix3D with all components equal to 0

auto C = Matrix3D();
assert(C[0][0] == 0);
assert(C[0][1] == 0);
assert(C[0][2] == 0);

assert(C[1][0] == 0);
assert(C[1][1] == 0);
assert(C[1][2] == 0);

assert(C[2][0] == 0);
assert(C[2][1] == 0);
assert(C[2][2] == 0);


Matrix3D(double a, double b, double c)

Create a diagonal Matrix3D with the three diagonal elements a, b and c.

auto B = Matrix3D(11, 22, 33);
assert(B[0][0] == 11);
assert(B[0][1] == 0);
assert(B[0][2] == 0);

assert(B[1][0] == 0);
assert(B[1][1] == 22);
assert(B[1][2] == 0);

assert(B[2][0] == 0);
assert(B[2][1] == 0);
assert(B[2][2] == 33);


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.

auto A = Matrix3D(
11, 12, 13,
21, 22, 23,
31, 32, 33
);
assert(A[0][0] == 11);
assert(A[0][1] == 12);
assert(A[0][2] == 13);

assert(A[1][0] == 21);
assert(A[1][1] == 22);
assert(A[1][2] == 23);

assert(A[2][0] == 31);
assert(A[2][1] == 32);
assert(A[2][2] == 33);


Matrix3D invert() const

Compute the inverse of this matrix.

Exceptions
• Error: if the matrix is not inversible
assert(Matrix3D(3, 2, 1).invert() == Matrix3D(1.0/3.0, 1.0/2.0, 1.0));


## 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 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 thown by chemfiles will derive from chemfiles::Error. Catching chemfiles::Error will then catch any exception thown 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 exisiting C++ error handling.

struct chemfiles::Error

Base exception class for chemfiles library.

Inherits from std::runtime_error

struct chemfiles::FileError

Exception for files related failures.

Inherits from chemfiles::Error

struct chemfiles::MemoryError

Exception for memory related failures.

Inherits from chemfiles::Error

struct chemfiles::FormatError

Exception for formats related failures.

Inherits from chemfiles::Error

struct chemfiles::SelectionError

Exception for errors in selections.

Inherits from chemfiles::Error

struct chemfiles::ConfigurationError

Exception for errors in configuration files.

Inherits from chemfiles::Error

struct chemfiles::OutOfBounds

Exception for out of bounds error when accessing atoms or residues.

Inherits from chemfiles::Error

struct chemfiles::PropertyError

Exception for errors related to frame and atomic properties.

Inherits from chemfiles::Error

## 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 callback)

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

// a function to do some work with the warnings
void work_with_warning(const std::string&);

/// Use a function as warning callback
chemfiles::set_warning_callback(work_with_warning);

/// Use a lambda as warning callback
chemfiles::set_warning_callback([](const std::string& message){
std::cout << "got a warning from chemfiles: " << message << std::endl;
});


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

using chemfiles::warning_callback = typedef std::function<void(const std::string& message)>

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 from the file at path. If the same configuration data is already present in a previouly read configuration file, the data is replaced by the one in this file.

If the file at path can not be opened, or if the configuration file is invalid, a ConfigurationError is thrown.

chemfiles::add_configuration("local-file.toml");

// Reading a trajectory will now use data from local-file.toml


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