Skip to main content

Python bindings to the ObjCryst++ library.

Project description


Python bindings to ObjCryst++, the Object-Oriented Crystallographic Library.

The documentation for this release of pyobjcryst can be found on-line at


pyobjcryst is available for Python 3.7 (deprecated), and 3.8 to 3.11.

Complete new conda environment with optional GUI and jupyter dependencies

Assuming you have installed Mamba-forge, you can directly create a new conda environment named pyobjcryst with all useful dependencies (including jupyter-lab, python 3.11..) using

mamba create -n pyobjcryst python=3.11 pyobjcryst matplotlib py3dmol jupyterlab ipympl multiprocess

Then you can activate the environment and launch jupyter-lab using

conda activate pyobjcryst

From source

The requirements are:

  • libobjcryst - Object-Oriented Crystallographic Library for C++,

  • setuptools - tools for installing Python packages

  • NumPy - library for scientific computing with Python

  • python-dev - header files for interfacing Python with C

  • libboost-all-dev - Boost C++ libraries and development files

  • scons - software construction tool (optional)

The above requirements are easily installed through conda using e.g.:

conda install numpy compilers boost scons libobjcryst

Alternatively, on Ubuntu Linux the required software can be installed using:

sudo apt-get install \
   python-setuptools python-numpy scons \
   build-essential python-dev libboost-all-dev

The libobjcryst library can also be installed as per the instructions at Make sure other required software are also in place and then run from the pyobjcryst directory:

pip install .

You may need to use sudo with system Python so the process is allowed to copy files to system directories, unless you are installing into a conda environment. If administrator (root) access is not available, see the usage information from python install --help for options to install to a user-writable location. The installation integrity can be verified by executing the included tests with

python -m

An alternative way of installing pyobjcryst is to use the SCons tool, which can speed up the process by compiling C++ files in several parallel jobs (-j4):

scons -j4 install

See scons -h for description of build targets and options.

Optional graphical dependencies for jupyter notebooks

Some of the classes can produce graphical outputs, which can be displayed in a jupyter notebook:

  • a Crystal structure can be displayed in 3D: this requires the py3dmol and ipywidgets modules. See the notebook examples/cystal_3d_widget.ipynb

  • a PowderPattern can be displayed (and live-updated) if matplotlib and ipympl are installed. See the notebook examples/cimetidine-structure-solution-powder.ipynb

In short, conda install jupyter matplotlib ipympl py3dmol will give you all the required dependencies. You can also use this in jupyterlab.

These packages can also be installed using pip if you do not use conda.


pyobjcryst is an open-source software originally developed as a part of the DiffPy-CMI complex modeling initiative at the Brookhaven National Laboratory, and is also further developed at ESRF. The pyobjcryst sources are hosted at

Feel free to fork the project and contribute. To install pyobjcryst in a development mode, where its sources are directly used by Python rather than copied to a system directory, use

python develop --user

When developing it is preferable to compile the C++ files with SCons using the build=develop option, which compiles the extension module with debug information and C-assertions checks

scons -j4 build=debug develop

The build script checks for a presence of file, which can be used to permanently set the build variable. The SCons construction environment can be further customized in a sconscript.local script. The package integrity can be verified by executing unit tests with scons -j4 test.

When developing with Anaconda Python it is essential to specify header path, library path and runtime library path for the active Anaconda environment. This can be achieved by setting the CPATH, LIBRARY_PATH and LDFLAGS environment variables as follows:

# resolve the prefix directory P of the active Anaconda environment
export CPATH=$P/include
export LIBRARY_PATH=$P/lib
export LDFLAGS=-Wl,-rpath,$P/lib
# compile and re-install pyobjcryst
scons -j4 build=debug develop

Note the Anaconda package for the required libobjcryst library is built with a C++ compiler provided by Anaconda. This may cause incompatibility with system C++. In such case please use Anaconda C++ to build pyobjcryst.

Quick conda environment from libobjcryst and pyobjcryst sources

If conda is available, you can create a pyobjcryst environment from the git repositories (downloaded in the current directory) using:

conda create --yes --name pyobjcryst numpy matplotlib ipywidgets jupyter
conda install --yes  -n pyobjcryst -c conda-forge boost scons py3dmol
conda activate pyobjcryst
git clone
cd libobjcryst
scons -j4 install prefix=$CONDA_PREFIX
cd ..
git clone
cd pyobjcryst
export CPATH=$CONDA_PREFIX/include
export LDFLAGS=-Wl,-rpath,$CONDA_PREFIX/lib
scons -j4 install prefix=$CONDA_PREFIX


For more information on pyobjcryst please visit the project web-page

or email Prof. Simon Billinge at

You can also contact Vincent Favre-Nicolin ( if you are using pyobjcryst outside diffpy, e.g. to display structures in a notebook, refine powder patterns or solve structures using the global optimisation algorithms, etc..

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyobjcryst-2.2.6.tar.gz (160.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page