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 Columbia 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.11, 3.12 and 3.13. 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 or mamba and install from the "conda-forge" channel of Conda packages. mamba works in the same way as conda but has the advantage of being much faster when resolving dependencies during installation. It also uses by default the conda-forge repository, which is what almost all users would want.
To add "conda-forge" to the conda channels, 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.
To use mamba, replace conda with mamba in the commands 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
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.
To install using pip into your pyobjcryst_env environment, type
pip install pyobjcryst
If you prefer to install from sources, after installing the dependencies, obtain the source archive from
GitHub. Once installed, cd into your pyobjcryst directory
and run the following
pip install .
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):
conda install scons conda install --file requirements/conda.txt scons -j4 dev
See scons -h for description of build targets and options.
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
If this doesn't work, please see the requirements/conda.txt file for the latest list of requirements.
The libobjcryst library can also be installed as per the instructions at
https://github.com/diffpy/libobjcryst. 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 setup.py install --help for options to install to a user-writable location.
The installation integrity can be verified by executing the included tests with
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 C++ files with
SCons using the build=debug option, which compiles the extension
module with debug information and C-assertions checks
scons -j4 build=debug dev
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 [email protected].
You can also contact Vincent Favre-Nicolin ([email protected]) 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.