Chemharp, an efficient IO library for chemistry file formats

---

Chemharp 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 Chemharp (libchemharp) 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 simulation (either Quantum Dynamic, Monte Carlo, Molecular Dynamic, or
any other method) often produce enormous amounts of data, which had to be
post-processed in order to extract informations. This post-processing step involve
reading and parsing the data, and computing physical values with the help of
statistical thermodynamic. Chemharp tries to help you on the first point, by providing
the same interface to all the trajectory formats. If you ever need to change your
output format, your analysis tools will still work the same way. Chemharp is
efficient because it allow you to write and debug your code only once, and then
to re-use it as needed.

Goals

The Chemharp library tries to:

• Be easy and simple to use. There are only five main classes, which are really
  easy to understand. No messy templates and uninformative functions names;
• Be a multi-languages library, usable from whatever language you prefer. If your
  favorite language is not supported, Chemharp have a clean C interface so that you
  can add a binding;
• Do one thing, and do it well. Following the UNIX idea, Chemharp tries to do
  only one thing, but doing it well.

Features

• Automatic recognition of file type based on filename extension;
• Open-source under the Mozilla Public License;
• Cross platform: it runs on Windows, Linux, Mac OS X, and maybe others systems;
• Support for a number of atoms which is not constant;
• Bindings to the most used scientific languages: Python, C, Fortran 95;
• Work with binary formats, if the corresponding libraries are available.

Compilers, architecture and OS support

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

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

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

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 Chemharp, 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.

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 libboost-filesystem-dev libboost-dev

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

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

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 (~/Chemharp is assumed here):

cd ~/Chemharp

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, and how to build the
bindings to Python or Fortran, please read the doc!

Usage

The documentation is hosted at readthedocs, but here
are some examples of how the API feels in all the supported languages:

C++

#include <iostream>
#include "Chemharp.cpp"

int main() {
    harp::Trajectory trajectory("filename.xyz");
    harp::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 !
}

Python

from chemharp import Trajectory, Frame

trajectory = Trajectory("filename.xyz")
frame = trajectory.read()

print("There are {} atoms in the frame".format(frame.natoms()))
positions = frame.positions()

# Do awesome things with the positions here !

Julia

using Chemharp

trajectory = Trajectory("filename.xyz")
frame = read(trajectory)

println("There are $(natoms(frame)) atoms in the frame")
positions = positions(frame)

# Do awesome things with the positions here !

Rust

extern crate chemharp;

use chemharp::Trajectory;

fn main() {
    let mut trajectory = Trajectory::new("filename.xyz").unwrap();
    let mut frame = Frame::new(0).unwrap();

    trajectory.read(&mut frame).unwrap();

    println!("There are {} atoms in the frame", frame.natoms().unwrap())

    let positions = frame.positions.unwrap();

    // Do awesome things with the positions here !
}

C

#include <stdint.h>
#include <stdio.h>

#include "chemharp.h"

int main(){
    CHRP_TRAJECTORY * trajectory = chrp_open("filename.xyz", "r");
    CHRP_FRAME * frame = chrp_frame(0);
    size_t natoms = 0;

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

    if (!chrp_trajectory_read(trajectory, frame)){
        // handle error here
    }
    chrp_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 (!chrp_frame_positions(frame, positions, natoms)){
        // handle error
    }

    // Do awesome things with the positions here !

    chrp_frame_free(frame);
    chrp_close(trajectory);
}

Fortran

program example
    use chemharp
    use iso_fortran_env, only: int64, real32

    implicit none
    type(chrp_trajectory) :: trajectory
    type(chrp_frame) :: frame
    integer(int64) :: natoms
    real(real32), dimension(:, :), allocatable :: positions
    integer :: status

    call trajectory%open("filename.xyz", "r", status=status)
    if status /= 0 stop "Error while opening file"
    call frame%init(0)

    call file%read(frame, status=status)
    if status /= 0 stop "Error while reading file"

    call frame%atoms_count(natoms)
    write(*, *) "There are ", natoms, "atoms in the frame"

    allocate(positions(3, natoms))

    call frame%positions(positions, natoms)

    // Do awesome things with the positions here !

    call frame%free()
    call trajectory%close()
}

License

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