Computational Crystallography Toolbox

Welcome to CCTBX’s documentation!

The Computational Crystallography Toolbox (cctbx) is being developed as the open source component of the PHENIX system. The goal of the PHENIX project is to advance automation of macromolecular structure determination. PHENIX depends on the cctbx, but not vice versa. This hierarchical approach enforces a clean design as a reusable library. The cctbx is therefore also useful for small-molecule crystallography and even general scientific applications.

To maximize reusability and, maybe even more importantly, to give individual developers a notion of privacy, the cctbx is organized as a set of smaller modules. This is very much like a village (the cctbx project) with individual houses (modules) for each family (groups of developers, of any size including one).

The cctbx code base is available without restrictions and free of charge to all interested developers, both academic and commercial. The entire community is invited to actively participate in the development of the code base. A sophisticated technical infrastructure that enables community based software development is provided by GitHub. This service is also free of charge and open to the entire world.

The cctbx is designed with an open and flexible architecture to promote extendability and easy incorporation into other software environments. The package is organized as a set of ISO C++ classes with Python bindings. This organization combines the computational efficiency of a strongly typed compiled language with the convenience and flexibility of a dynamically typed scripting language in a strikingly uniform and very maintainable way.

Use of the Python interfaces is highly recommended, but optional. The cctbx can also be used purely as a C++ class library.

High level organization

The SourceForge cctbx project currently contains these modules. The core libraries required for most other applications are libtbx, boost_adaptbx, scitbx, cctbx, and usually iotbx. Functionality specific to macromolecules and small molecules lives in mmtbx and smtbx, respectively.


The build system common to all other modules. This includes a very thin wrapper around the SCons software construction tool. It also contains many useful frameworks and utilities to simplify application development, including tools for regression testing, parallelization across multiprocessor systems and managed clusters, and a flexible, modular configuration syntax called PHIL (Python Hierarchial Interface Language) used throughout the CCTBX.

API Documentation for libtbx


A very small adaptor toolbox with platform-independent instructions for building the Boost.Python library.

API Documentation for boost_adaptbx


Libraries for general scientific computing (i.e. libraries that are not specific to crystallographic applications). This includes a family of high-level C++ array types, a fast Fourier transform library, and a C++ port of the popular L-BFGS quasi-Newton minimizer, and many mathematical utilities, all including Python bindings. These libraries are separated from the crystallographic code base to make them easily accessible for non-crystallographic application developers.

API Documentation for scitbx


Libraries for general crystallographic applications, useful for both small-molecule and macro-molecular crystallography. The libraries in the cctbx module include algorithms and data structures for the handling of crystal symmetry, basic geometry restraints, reflection data, atomic displacement parameters, X-ray scattering, and high-level building blocks for refinement algorithms. Note the distinction between the CCTBX project and the cctbx module.

API Documentation for cctbx


Libraries for reading and writing common file formats, including PDB, CIF, many reflection formats, electron density maps, and sequences.

API Documentation for iotbx


Functionality specific to macromolecular crystallography. This includes all of the machinery required for setup of geometry restraints, bulk solvent correction and scaling, analysis of macromolecular diffraction data, calculation of weighted map coefficients, and most of the methods implemented in phenix.refine. The majority of infrastructure for the MolProbity validation server (and Phenix equivalent) is also located here.

API Documentation for mmtbx


Software for processing serial data collected using an X-ray free electron laser. Includes spotfinding, integration, data clustering/filering and merging tools.

API Documentation for xfel


Functionality specific to small-molecule crystallography, including a complete refinement program (smtbx.refine).

API Documentation for smtbx


The Diffraction Image Toolbox, a library for handling X-ray detector data of arbitrary complexity from a variety of standard formats. (Also used by routines in iotbx.)

API documentation for dxtbx


Many additional libraries have more specialized functionality, including:

  • spotfinder - fast detection of Bragg peaks in diffraction images
  • ucif - the core CIF I/O library (used by iotbx)
  • rstbx - Reciprocal Space Toolbox, used for data processing
  • gltbx - OpenGL bindings, including a wxPython-based viewer framework
  • crys3d - Modules for the display of molecules, electron density, and reciprocal space data
  • fable - a program (and compatibility library) for porting Fortran77 to C++
  • wxtbx - wxPython controls used in the Phenix GUI and various utilities
  • cma_es - a library of derivative-free optimization methods

Newsletter articles and examples


Installation instructions for both binary installation and installation from sources.

The cctbx build system is based on SCons.

Reference Documentation

cctbx C++ interfaces

Most documented C++ interfaces are also available at the Python layer. Unfortunately the documentation tools available are not capable of merging the documentations. Therefore Python users need to also consult the C++ documention.


We would like to thank David Abrahams for creating the amazing Boost.Python library and for patiently supporting the entire open source community. We would like to thank Airlie McCoy for allowing us to adapt some parts of the Phaser package (FFT structure factor calculation). Kevin Cowtan has contributed algorithms for the handling of reciprocal space asymmetric units. We are also grateful for his development of the Clipper library from which we have adapted some source code fragments. Our work was funded in part by the US Department of Energy under Contract No. DE-AC03-76SF00098. We gratefully acknowledge the financial support of NIH/NIGMS.

The cctbx git development tree is hosted by GitHub.


There is also a mailing list (cctbxbb) where developers can answer questions from the community. To join/manage your subscription, please visit