You are reading the documentation for version 1.6 of OpenStructure. You may also want to read the documentation for: 1.1 1.2 1.3 1.4 1.5 devel

Creating a New Module

OpenStructure can be extended by writing additional modules. A module will usually consist of a set of C++ classes and methods, most of which will also be exported to Python. It is also possible to write modules completely in Python.

The build system of OpenStructure is quite simple. The main difference to other projects is the use of a so-called stage directory. The stage directory replicates the normal layout of a standard Linux directory structure, with an ‘include’ directory for the headers, a ‘lib’ directory containing the shared library files, a bin directory for the executables and a ‘share’ directory for the platform-independent data like icons, images and examples.

OpenStructure uses CMake to build the project. The rules for the build-system are defined in CMakeLists.txt files. When running cmake, the files are compiled and copied into stage. The real installation, if necessary, happens at a later stage. This is referred to as staging of the files.

If a new module is written following the guidelines in this page, it will be seamlessly included in the build system and will then be available form both the DNG python console and the OpenStructure command line as any other native module.

As a first step, a new directory structure must be created to accommodate the new module.

Directory Structure

For the purpose of this example, let’s assume we are creating a new module called ‘mod’ (for ‘modeling’). Let’s create a directory named mod under the ‘modules’ directory in the OpenStructure development tree, and populate it with the three subdirectories src, pymod, and tests. Then we add a CMakeLists.txt file in the ‘mod’ directory, consisting of three lines:


The Module Code

In the src subdirectory we put the code that implements the functionality of the new module, plus a config.hh header file.

Here is a skeleton of one of the files in the directory , modeling_new_class.hh:


#include <ost/mod/module_config.hh>

// All other necessary includes go here

namespace ost { namespace mod {

class DLLEXPORT_OST_MOD NewClass {
   void NewMethod();

  // All declarations of NewClass go here


}} // namespaces


And here is the skeleton of the corresponding file:

#include "modeling_new_class.hh"

using namespace ost::mol;
using namespace ost::mod;

// All other necessary includes and namespace directives
// go here

void NewClass::NewMethod():
  // Implementation

// Implementation code for NewClass goes here

Obviously, the src directory can contain many files, each implementing classes and functions that will end up in the module. In order to build and stage the module shared library, a CMakeLists.txt file needs to be written for the src directory:

// All other source files

// All other header files

        DEPENDS_ON mol mol_alg)

The line containing the DEPENDS_ON directive lists all the modules on which the new module depends (in this case mol and ost.mol.alg). The module macro will take care of staging the headers, in this case into ost/mod and compiling, linking and staging of a library with the name (libost_gmod.dylib on MacOS X).


Due to a limitation in the built-int install command of CMake, for modules that have their headers in several directories, it is required to group the headers by directory, leading to a call of module like:

module(NAME mol SOURCES impl/
       HEADERS atom_impl.hh IN_DIR impl

The module_config.hh header is required for each module to setup the environment on Windows: Each public class, method and function needs to marked with DLLEXPORT or DLLIMPORT to teach the linker where to look for the symbol. The correct use of either DLLIMPORT and DLLEXPORT is depending on the context: While compiling a header file that is part of the same shared library, DLLEXPORT must be used. When compiling a header that is part of an external shared library, DLLIMPORT must be used. A typical module_config header looks like this:


#include <ost/base.hh>

#if defined(OST_MODULE_OST_MOD)

The Testing Framework

The tests directory contains code for unit tests. The code is compiled and executed when one invokes compilation using the ‘make check’ command. Tests are run by means of the Boost Unitests Library. Before coding the test routines, the required skeleton needs to be put in place.

The main code is put into ‘’, which will become the test executable. There are only 3 lines required

#define BOOST_TEST_MODULE ost_mod
#include <boost/test/unit_test.hpp>

Based on the two macros BOOST_TEST_DYN_LINK and BOOST_TEST_MODULE, the boost unit test framework will introduce a main function that executes all the unit tests that we will define next.

The definition of the actual unit tests is done in separate .cc files. Create the file and fill it with the following code:

#include <boost/test/unit_test.hpp>

#include <ost/mod/modeling_new_class.hh>

      using namespace ost;
using namespace ost::mod;


  // ... your test code here...

  // ... your test code here...


We again have to define the BOOST_TEST_DYN_LINK macro before including the boost unit test headers. This will tell the boost unit test libraries that we intend to use dynamic linking. Then we include the functions and classes we would like to write unit tests for. In this file, all the normal Boost Test Library macros and functions can be used. (For example BOOST_CHECK, BOOST_FAIL, etc.)

Here is finally the build script skeleton that needs to be put into mod/tests/:


ost_unittest(mod "${OST_MOD_UNIT_TESTS}")
target_link_libraries(ost_mol ost_mol_alg ost_mod)

In the last line the call to the ‘target_link_libraries’ function contains the names of the modules on which the ‘mod’ unit test code depends (in this case, the mol and ost.mol.alg modules), in addition to the mod module itself.

The Python Wrapper

Finally, the module API is exported to Python using the Boost Python Library. In mod/pymod, the wrapper code for the classes in the new module is put into a file named

#include <boost/python.hpp>
using namespace boost::python;

#include <ost/mod/modeling_new_class.hh>

using namespace ost::mol;
using namespace ost::mod;

// All other necessary includes and namespace directives
// go here

  class_<NewClass>("NewClass", init<>() )
    .def("NewMethod", &NewClass::NewMethod)

  // All other Boost Python code goes here

The mod/pymod directory must obviously contain a CMakeLists.txt file:


pymod(NAME mod OUTPUT_DIR ost/mod

The directory should also contain an file with the following content:

from _mod import *

In case one wants to implement Python-only functionality for the new module, any number of function definitions can be added to the file.

That’s it! The next time the OpenStructure project is compiled, the new module will be built and made available at both the C++ and the Python level.



Enter search terms or a module, class or function name.

Previous topic


Next topic

Using External Programs within OpenStructure

You are here