Python bindings to ObjCryst++, the Object-Oriented Crystallographic Library.
For more information about the pyobjcryst library, please consult our online documentation.
pyobjcryst is an open-source software package originally developed as a part of the DiffPy-CMI
complex modeling initiative which originated in the DANSE project
at Columbia University. It was further developed at Brookhaven National Laboratory,
and Columbia University and the European Synchrotron Radiation Source (ESRF) and is now
maintained at University of California, Santa Barbara and ESRF.
The pyobjcryst sources are hosted at https://github.com/diffpy/pyobjcryst.
If you use diffpy.srfit in a scientific publication, we would like you to cite this package as
P. Juhás, C. L. Farrow, X. Yang, K. R. Knox and S. J. L. Billinge, Complex modeling: a strategy and software program for combining multiple information sources to solve ill posed structure and nanostructure inverse problems, Acta Crystallogr. A 71, 562-568 (2015).
and
V. Favre-Nicolin and R. Cerný, FOX, 'free objects for crystallography': a modular approach to ab initio structure determination from powder diffraction, J. Appl. Cryst. 35, 734-743 (2002)
The second paper describes the c++ crystallographic objects in
ObjCryst++ that are wrapped by pyobjcryst
The latest release of pyobjcryst runs in python versions 3.12, 3.13, 3.14 and 3.15. You may
specify an earlier release if you need it to run in an earlier version of Python.
The preferred method is to use Miniconda Python and install from the "conda-forge" channel of Conda packages.
To permanently add "conda-forge" to the conda channels (recommended), run the following in a terminal.
conda config --add channels conda-forge
We want to install our packages in a suitable conda environment.
The following creates and activates a new environment named pyobjcryst-env
conda create -n pyobjcryst-env pyobjcryst conda activate pyobjcryst-env
To confirm that the installation was successful, type
python -c "import pyobjcryst; print(pyobjcryst.__version__)"
The output should print the latest version displayed on the badges above.
pyobjcryst is also included in the diffpy.cmi collection of packages for
structure analysis and so can be installed by
conda install -c conda-forge diffpy.cmi
and following the instructions in the diffpy.cmi documentation to install packs containing pyobjcryst and its libraries.
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
py3dmolandipywidgetsmodules. See the notebookdocs/examples/cystal_3d_widget.ipynb - a PowderPattern can be displayed (and live-updated) if
matplotlibandipymplare installed. See the notebookdocs/examples/structure-solution-powder-cimetidine.ipynb
You may consult our online documentation for tutorials and API references.
These approaches are not recommended but reproduced here for advanced users.
You can use pip to download and install the latest release from
Python Package Index. The PyPI wheels are
self-contained (ObjCryst++, cctbx and newmat are built in), so no compiler
or conda libraries are needed
pip install pyobjcryst
The optional graphical dependencies can be installed with
pip install ipywidgets matplotlib ipympl py3dmol
To build from source, a C++ compiler is required; CMake, nanobind and the
Boost headers are fetched automatically by pip. ObjCryst++ is included
as a git submodule, so clone with --recursive (or run
git submodule update --init in an existing clone)
git clone --recursive https://github.com/diffpy/pyobjcryst.git cd pyobjcryst pip install .
Outside a conda environment, e.g. on Ubuntu Linux, the compiler and Boost headers can be installed using
sudo apt-get install build-essential python3-dev python3-pip libboost-dev
Boost headers can also be installed from conda-forge (libboost-headers),
or their location given explicitly with
pip install . -Ccmake.define.BOOST_INCLUDE_DIR=<path>.
The installation integrity can be verified by executing the included tests.
First install test dependencies then type pytest:
conda install --file requirements/tests.txt pytest
If you see a bug or want to request a feature, please report it as an issue and/or submit a fix as a PR.
Feel free to fork the project and contribute. To install pyobjcryst in a development mode, with its sources being directly used by Python rather than copied to a package directory, use the following in the root directory
pip install -e .
To ensure code quality and to prevent accidental commits into the default branch, please set up the use of our pre-commit hooks.
- Install pre-commit in your working environment by running
conda install pre-commit. - Initialize pre-commit (one time only)
pre-commit install.
Thereafter your code will be linted by black and isort and checked against flake8 before you can commit. If it fails by black or isort, just rerun and it should pass (black and isort will modify the files so should pass after they are modified). If the flake8 test fails please see the error messages and fix them manually before trying to commit again.
When developing it is preferable to compile the extension module with debug information and C-assertions checks
pip install -e . -Ccmake.build-type=Debug
Improvements and fixes are always appreciated.
Before contributing, please read our Code of Conduct.
For more information on pyobjcryst please visit the project web-page or email Simon Billinge at sbillinge@ucsb.edu.
You can also contact Vincent Favre-Nicolin (favre@esrf.fr) 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..
This package bundles the following IUCr data files for bona fide research use:
cpd-1a.prn: Powder diffraction dataset from the IUCr CPD Round Robin on Quantitative Phase Analysis.
Source: https://www.iucr.org/__data/iucr/powder/QARR/col/cpd-1a.prn
Round Robin on Quantitative Phase Analysis: Madsen, I. (1997) ‘Round Robin on Quantitative Phase Analysis’, Powder Diffraction, 12(1), pp. 1–2. Available at: https://doi.org/10.1017/S0885715600020212.
pyobjcryst is built and maintained with scikit-package.