Skip to content

About

Python bindings to ObjCryst++ Object-Oriented Crystallographic Library

Resources

Stars

19 stars

Watchers

6 watching

Forks

Latest commit

 

History

799 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PyPI Forge PythonVersion PR

CI Codecov Black Tracking

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.

Citation

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

Installation

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.

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 docs/examples/cystal_3d_widget.ipynb
  • a PowderPattern can be displayed (and live-updated) if matplotlib and ipympl are installed. See the notebook docs/examples/structure-solution-powder-cimetidine.ipynb

Getting Started

You may consult our online documentation for tutorials and API references.

Alternative methods of installation

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>.

Testing your installation

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

Support and Contribute

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.

  1. Install pre-commit in your working environment by running conda install pre-commit.
  2. 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.

Contact

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..

Acknowledgements

This package bundles the following IUCr data files for bona fide research use:

pyobjcryst is built and maintained with scikit-package.

About

Python bindings to ObjCryst++ Object-Oriented Crystallographic Library

Resources

Stars

19 stars

Watchers

6 watching

Forks

Releases

Packages

Used by

Contributors

Languages