.. image:: https://travis-ci.org/diffpy/pyobjcryst.svg?branch=master
:target: https://travis-ci.org/diffpy/pyobjcryst
.. image:: https://codecov.io/gh/diffpy/pyobjcryst/branch/master/graph/badge.svg
:target: https://codecov.io/gh/diffpy/pyobjcryst
pyobjcryst
==========
Python bindings to ObjCryst++, the Object-Oriented Crystallographic Library.
The documentation for this release of pyobjcryst can be found on-line at
https://pyobjcryst.readthedocs.io/
INSTALLATION
------------
pyobjcryst is available for Python 3.7 (deprecated), and 3.8 to 3.11.
Using conda (recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^
We recommend to use **conda** as it allows to install all software dependencies
together with pyobjcryst, without too much compiling hastle.
Two distributions can be used:
* `Anaconda Python <https://www.anaconda.com/download>`_, the historical
main conda-based distribution
* `Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_ , which
has the advantage off providing **mamba** in addition to conda, and is
*much faster* when resolving dependencies during installation. It also
uses by default the conda-forge repository, which is what almost all
users would want.
Using conda, we you can install pyobjcryst using the "conda-forge" channel ::
conda install -c conda-forge pyobjcryst
Alternatively using mamba ::
mamba install pyobjcryst
You can also install from the "diffpy" channel - especially if you use
pyobjcryst allong with the other diffpy tools for PDF calculations,
but it is not updated as often as conda-forge.
pyobjcryst is also included in the "diffpy-cmi" collection
of packages for structure analysis ::
conda install -c diffpy diffpy-cmi
Complete new conda environment with optional GUI and jupyter dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Assuming you have installed `Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_,
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
jupyter-lab
From source
^^^^^^^^^^^
The requirements are:
* ``libobjcryst`` - Object-Oriented Crystallographic Library for C++,
https://github.com/diffpy/libobjcryst
* ``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
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 ::
python -m pyobjcryst.tests.run
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.
DEVELOPMENT
-----------
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
https://github.com/diffpy/pyobjcryst.
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 setup.py 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 ``sconsvars.py`` 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
P=$CONDA_PREFIX
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 https://github.com/diffpy/libobjcryst.git
cd libobjcryst
scons -j4 install prefix=$CONDA_PREFIX
cd ..
git clone https://github.com/diffpy/pyobjcryst.git
cd pyobjcryst
export CPATH=$CONDA_PREFIX/include
export LIBRARY_PATH=$CONDA_PREFIX/lib
export LDFLAGS=-Wl,-rpath,$CONDA_PREFIX/lib
scons -j4 install prefix=$CONDA_PREFIX
CONTACTS
--------
For more information on pyobjcryst please visit the project web-page
http://www.diffpy.org
or email Prof. Simon Billinge at sb2896@columbia.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..
Raw data
{
"_id": null,
"home_page": "https://github.com/diffpy/pyobjcryst",
"name": "pyobjcryst",
"maintainer": "Vincent-Favre-Nicolin",
"docs_url": null,
"requires_python": "",
"maintainer_email": "favre@esrf.fr",
"keywords": "objcryst atom structure crystallography powder diffraction",
"author": "Simon J.L. Billinge",
"author_email": "sb2896@columbia.edu",
"download_url": "https://files.pythonhosted.org/packages/d6/91/2ed10a248654d4d22421ab501ea0b9827d479a27c35e0ee3763a40aa638b/pyobjcryst-2.2.6.tar.gz",
"platform": null,
"description": ".. image:: https://travis-ci.org/diffpy/pyobjcryst.svg?branch=master\n :target: https://travis-ci.org/diffpy/pyobjcryst\n\n.. image:: https://codecov.io/gh/diffpy/pyobjcryst/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/diffpy/pyobjcryst\n\npyobjcryst\n==========\n\nPython bindings to ObjCryst++, the Object-Oriented Crystallographic Library.\n\nThe documentation for this release of pyobjcryst can be found on-line at\nhttps://pyobjcryst.readthedocs.io/\n\n\nINSTALLATION\n------------\npyobjcryst is available for Python 3.7 (deprecated), and 3.8 to 3.11.\n\nUsing conda (recommended)\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nWe recommend to use **conda** as it allows to install all software dependencies\ntogether with pyobjcryst, without too much compiling hastle.\n\nTwo distributions can be used:\n\n* `Anaconda Python <https://www.anaconda.com/download>`_, the historical\n main conda-based distribution\n* `Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_ , which\n has the advantage off providing **mamba** in addition to conda, and is\n *much faster* when resolving dependencies during installation. It also\n uses by default the conda-forge repository, which is what almost all\n users would want.\n\nUsing conda, we you can install pyobjcryst using the \"conda-forge\" channel ::\n\n conda install -c conda-forge pyobjcryst\n\nAlternatively using mamba ::\n\n mamba install pyobjcryst\n\nYou can also install from the \"diffpy\" channel - especially if you use\npyobjcryst allong with the other diffpy tools for PDF calculations,\nbut it is not updated as often as conda-forge.\n\npyobjcryst is also included in the \"diffpy-cmi\" collection\nof packages for structure analysis ::\n\n conda install -c diffpy diffpy-cmi\n\nComplete new conda environment with optional GUI and jupyter dependencies\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nAssuming you have installed `Mamba-forge <https://github.com/conda-forge/miniforge/releases>`_,\nyou can directly create a new conda environment named `pyobjcryst` with all useful dependencies (including\njupyter-lab, python 3.11..) using ::\n\n mamba create -n pyobjcryst python=3.11 pyobjcryst matplotlib py3dmol jupyterlab ipympl multiprocess\n\nThen you can activate the environment and launch jupyter-lab using ::\n\n conda activate pyobjcryst\n jupyter-lab\n\nFrom source\n^^^^^^^^^^^\nThe requirements are:\n\n* ``libobjcryst`` - Object-Oriented Crystallographic Library for C++,\n https://github.com/diffpy/libobjcryst\n* ``setuptools`` - tools for installing Python packages\n* ``NumPy`` - library for scientific computing with Python\n* ``python-dev`` - header files for interfacing Python with C\n* ``libboost-all-dev`` - Boost C++ libraries and development files\n* ``scons`` - software construction tool (optional)\n\nThe above requirements are easily installed through conda using e.g.::\n\n conda install numpy compilers boost scons libobjcryst\n\nAlternatively, on Ubuntu Linux the required software can be installed using::\n\n sudo apt-get install \\\n python-setuptools python-numpy scons \\\n build-essential python-dev libboost-all-dev\n\n\nThe libobjcryst library can also be installed as per the instructions at\nhttps://github.com/diffpy/libobjcryst. Make sure other required\nsoftware are also in place and then run from the pyobjcryst directory::\n\n pip install .\n\nYou may need to use ``sudo`` with system Python so the process is\nallowed to copy files to system directories, unless you are installing\ninto a conda environment. If administrator (root)\naccess is not available, see the usage information from\n``python setup.py install --help`` for options to install to\na user-writable location. The installation integrity can be\nverified by executing the included tests with ::\n\n python -m pyobjcryst.tests.run\n\nAn alternative way of installing pyobjcryst is to use the SCons tool,\nwhich can speed up the process by compiling C++ files in several\nparallel jobs (-j4)::\n\n scons -j4 install\n\nSee ``scons -h`` for description of build targets and options.\n\nOptional graphical dependencies for jupyter notebooks\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nSome of the classes can produce graphical outputs, which can be\ndisplayed in a jupyter notebook:\n\n* a Crystal structure can be displayed in 3D: this requires the\n ``py3dmol`` and ``ipywidgets`` modules. See the notebook\n ``examples/cystal_3d_widget.ipynb``\n* a PowderPattern can be displayed (and live-updated) if\n ``matplotlib`` and ``ipympl`` are installed. See the\n notebook ``examples/cimetidine-structure-solution-powder.ipynb``\n\nIn short, ``conda install jupyter matplotlib ipympl py3dmol``\nwill give you all the required dependencies. You can also\nuse this in jupyterlab.\n\nThese packages can also be installed using ``pip`` if you do not use conda.\n\nDEVELOPMENT\n-----------\n\npyobjcryst is an open-source software originally developed as a part of the\nDiffPy-CMI complex modeling initiative at the Brookhaven National\nLaboratory, and is also further developed at ESRF.\nThe pyobjcryst sources are hosted at\nhttps://github.com/diffpy/pyobjcryst.\n\nFeel free to fork the project and contribute. To install pyobjcryst\nin a development mode, where its sources are directly used by Python\nrather than copied to a system directory, use ::\n\n python setup.py develop --user\n\nWhen developing it is preferable to compile the C++ files with\nSCons using the ``build=develop`` option, which compiles the extension\nmodule with debug information and C-assertions checks ::\n\n scons -j4 build=debug develop\n\nThe build script checks for a presence of ``sconsvars.py`` file, which\ncan be used to permanently set the ``build`` variable. The SCons\nconstruction environment can be further customized in a ``sconscript.local``\nscript. The package integrity can be verified by executing unit tests with\n``scons -j4 test``.\n\nWhen developing with Anaconda Python it is essential to specify\nheader path, library path and runtime library path for the active\nAnaconda environment. This can be achieved by setting the ``CPATH``,\n``LIBRARY_PATH`` and ``LDFLAGS`` environment variables as follows::\n\n # resolve the prefix directory P of the active Anaconda environment\n P=$CONDA_PREFIX\n export CPATH=$P/include\n export LIBRARY_PATH=$P/lib\n export LDFLAGS=-Wl,-rpath,$P/lib\n # compile and re-install pyobjcryst\n scons -j4 build=debug develop\n\nNote the Anaconda package for the required libobjcryst library is built\nwith a C++ compiler provided by Anaconda. This may cause incompatibility\nwith system C++. In such case please use Anaconda C++ to build pyobjcryst.\n\nQuick conda environment from libobjcryst and pyobjcryst sources\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf ``conda`` is available, you can create a pyobjcryst environment\nfrom the git repositories (downloaded in the current directory) using::\n\n conda create --yes --name pyobjcryst numpy matplotlib ipywidgets jupyter\n conda install --yes -n pyobjcryst -c conda-forge boost scons py3dmol\n conda activate pyobjcryst\n git clone https://github.com/diffpy/libobjcryst.git\n cd libobjcryst\n scons -j4 install prefix=$CONDA_PREFIX\n cd ..\n git clone https://github.com/diffpy/pyobjcryst.git\n cd pyobjcryst\n export CPATH=$CONDA_PREFIX/include\n export LIBRARY_PATH=$CONDA_PREFIX/lib\n export LDFLAGS=-Wl,-rpath,$CONDA_PREFIX/lib\n scons -j4 install prefix=$CONDA_PREFIX\n\n\nCONTACTS\n--------\n\nFor more information on pyobjcryst please visit the project web-page\n\nhttp://www.diffpy.org\n\nor email Prof. Simon Billinge at sb2896@columbia.edu.\n\nYou can also contact Vincent Favre-Nicolin (favre@esrf.fr) if you\nare using pyobjcryst outside diffpy, e.g. to display structures\nin a notebook, refine powder patterns or solve structures using the\nglobal optimisation algorithms, etc..\n",
"bugtrack_url": null,
"license": "BSD-style license",
"summary": "Python bindings to the ObjCryst++ library.",
"version": "2.2.6",
"split_keywords": [
"objcryst",
"atom",
"structure",
"crystallography",
"powder",
"diffraction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6912ed10a248654d4d22421ab501ea0b9827d479a27c35e0ee3763a40aa638b",
"md5": "6ebc754b9ce1b18cd9bd60c9a19528df",
"sha256": "898d7d7584c547771c4bc42fb430dfcf4f71f89093a268088e0a7caa7d2373fd"
},
"downloads": -1,
"filename": "pyobjcryst-2.2.6.tar.gz",
"has_sig": false,
"md5_digest": "6ebc754b9ce1b18cd9bd60c9a19528df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 160729,
"upload_time": "2023-03-14T11:26:40",
"upload_time_iso_8601": "2023-03-14T11:26:40.657350Z",
"url": "https://files.pythonhosted.org/packages/d6/91/2ed10a248654d4d22421ab501ea0b9827d479a27c35e0ee3763a40aa638b/pyobjcryst-2.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-14 11:26:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "diffpy",
"github_project": "pyobjcryst",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"lcname": "pyobjcryst"
}
JSON
