Chemfiles, an efficient IO library for chemistry file formats

---

Chemfiles is a multi-language library written in modern C++ for reading and writing
from and to molecular trajectory files. These files are created by your favorite
theoretical chemistry program, and contains informations about atomic or residues
names and positions. Some format also have additional informations, such as
velocities, forces, energy, …

The main targeted audience of chemfiles (libchemfiles) is chemistry researcher
working on their own code to do some kind of awesome science, without wanting to
bother about handling all the format that may exist in the world.

Running molecular or quantum simulations produce enormous amounts of data, which had to be
post-processed in order to extract physical informations about the system. This
post-processing step involve reading and parsing the data, and computing physical values
with various algorithms. Chemfiles helps YOU on the first part of this, by providing the
same interface to all the trajectory formats. If you need to change the output format,
your analysis tools will still work the same way.

Quick links

• Goals of chemfiles
• Features
• Supported file formats
• Getting started
• Full documentation
• Python interface
• Fortran interface
• Julia interface
• Rust interface

Goals

The chemfiles library tries to:

• Be easy and simple to use. There are only five main classes, which are really
  easy to understand. The interface is coherent and easy to understand.
• Be a multi-languages library, usable from whatever language you prefer. If your
  favorite language is not supported, chemfiles have a clean C interface so that you
  can add a binding;
• Following the UNIX moto, do one thing, and do it well.
• Be cross-platform, and usable from Linux, OS X and Windows;
• Have high-quality code, using modern software building technics (unit testing, code
  coverage, git for code versioning, ...).

Why you should use chemfiles

You should use chemfiles if (at least) one of theses assertions is true for you:

• you want to write analysis algorithm, but not have to worry about reading the data;
• you want to use binary formats, because they are faster or you have to;
• you want to write some analyse code that will work with any format, leaving you free
  to change the simulation software as you need but keeping any code working the same;
• you want to write a simulation software, and provide rich input-output interface to your
  users;

Non-goals of chemfiles

Chemfiles also have non goals, or explicitly refused goals:

• It will not contains any code for analysis. You can find implementation of some
  analysis algorithms and a ready-to-use command line program in the
  chrp repository.
• It will not contain molecular dynamics, Monte-Carlo, energy minimization or quantum
  chemistry code. If you want such code with access to the chemfiles features, please see
  the cymbalum molecular simulation engine, by the
  same author.

Features

• Automatic recognition of file type based on filename extension;
• Support for a number of atoms which is not constant;
• Set custom UnitCell or Topology when reading/writing;
• Bindings to the most used scientific languages: Python, C, Fortran 95;
• Work with binary formats, if the corresponding libraries are available.
• Open-source and freely available under the Mozilla Public License;

File formats

Supported formats

The following formats are supported through the VMD molfile plugins, and are read-only:

Planned formats

See the issue list for
planned formats. If you want a new format to be added to chemfiles, you can either
do it by yourself (it is easy !) and create a pull-request to incorporate your
changes, or create a new issue with a link to the format reference and some
example of well-formed files.

Getting started

The whole installation is documented here, this page only
show the basic steps. Please refer to the link below in case of problem.

If you want to use chemfiles from one of the available bindings, please refer to the
corresponding repository:

• Python interface
• Fortran interface
• Julia interface
• Rust interface

Getting the dependencies

Long story made short, just use the right commands for your system:

# On apt-get based distributions
apt-get update
apt-get install cmake libnetcdf-dev

# On yum based distributions
yum install epel-release # The EPEL repository have the netcdf lib
yum install cmake netcdf-devel netcdf-cxx-devel

# On OS X with Homebrew (brew.sh)
brew tap homebrew/science
brew install cmake netcdf

You will also need a recent C++ compiler: gcc 4.9, clang 3.5 and icpc 14 are
known to work.

Getting the code, building, installing

Get the code from the release page,
and extract the archive. Then in a terminal, go to the folder where you put the
code (~/chemfiles is assumed here):

cd ~/chemfiles

Then, cmake is used to build the code. So, create a folder
and go for the build:

mkdir build
cd build
cmake ..

Then, you can build install the library:

make
make install

For more informations about how to configure the build, please read the doc!

Usage

The documentation is hosted at readthedocs, but here
are some examples of how the usage feels in c++ and in C:

// C++ version
#include <iostream>
#include "chemfiles.hpp"

int main() {
    chemfiles::Trajectory trajectory("filename.xyz");
    chemfiles::Frame frame;

    trajectory >> frame;
    std::cout << "There are " << frame.natoms() << " atoms in the frame" << std::endl;
    auto positions = frame.positions();

    // Do awesome things with the positions here !
}

// C version
#include <stdint.h>
#include <stdio.h>

#include "chemfiles.h"

int main(){
    CHFL_TRAJECTORY * trajectory = chfl_trajectory_open("filename.xyz", "r");
    CHFL_FRAME * frame = chfl_frame(0);
    size_t natoms = 0;

    if (!traj) {
        printf("Error while opening file: %s", chfl_last_error());
    }

    if (!chfl_trajectory_read(trajectory, frame)){
        // handle error here
    }
    chfl_frame_atoms_count(frame, &natoms);
    printf("There are %d atoms in the frame", natoms);

    float (*positions)[3] = (float(*)[3])malloc(sizeof(float[natoms][3]));

    if (!chfl_frame_positions(frame, positions, natoms)){
        // handle error
    }

    // Do awesome things with the positions here !

    chfl_frame_free(frame);
    chfl_close(trajectory);
    free(positions);
}

Contributing

Any contribution is very welcome, from feedback to pull request.

Please report any bug you find and any feature you may want as a github issue.

Compilers, architecture and OS support

Chemfiles have been tested on the following platforms, with the following compilers :

• Linux (64 bit)
  • GCC: gcc/g++ 4.9.2
  • Intel: icc/icpc 14
• OS X (64 bit)
  • GCC: gcc/g++ 4.9.2
  • LLVM: clang/clang++ 3.5
  • Intel: icc/icpc 14
• Windows (32 & 64 bit) (only the C++ and C interfaces have been tested)
  • Visual Studio 2015 (Visual Studio 2013 DO NOT work)
  • mingw64 gcc/g++ 4.9.2

If you manage to compile chemfiles on any other OS/compiler/architecture combination,
please let me know so that I can add it to this list.

License

All this code is copyrighted by Guillaume Fraux, and put to your disposition
under the terms of the Mozilla Public License v2.0.