Skip to content

Commit 41b3e39

Browse files
st3107st3107
authored
Merge pull request #26 from vincefn/master
Update pyobjcryst: add QPA example, add notebooks to doc...
2 parents 2527fad + e0dc4bb commit 41b3e39

28 files changed

+17941
-7483
lines changed

‎CHANGELOG.md

+19-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,29 @@
11
# Release notes
22

3+
## Version 2.2.1 -- 2021-11-28
4+
5+
- Add quantitative phase analysis with PowderPattern.qpa(), including
6+
an example notebook using the QPA Round-Robin data.
7+
- Correct import of urllib.request.urllopen() when loading CIF or z-matrix
8+
files from http urls.
9+
- Fix blank line javascript output when updating the Crystal 3D view
10+
- Add RefinableObj.xml() to directly get the XMLOutput() as a string
11+
- Add example notebooks to the sphinx-generated html documentation
12+
- Fix issue when using Crystal.XMLInput() for a non-empty structure.
13+
Existing scattering power will be re-used when possible, and otherwise
14+
not deleted anymore (which could lead to crashes).
15+
316
## Version 2.2.0 -- 2021-06-08
417

518
Notable differences from version 2.1.0.
619

7-
- Add access to Radiation class & functions to change RadiationType, wavelength in PowderPattern and ScatteringData (and hence DiffractionDataSingleCrystal) classes.
20+
- Add access to Radiation class & functions to change RadiationType,
21+
wavelength in PowderPattern and ScatteringData (and hence
22+
DiffractionDataSingleCrystal) classes.
823

9-
- Fix the custodian_ward when creating a PowderPatternDiffraction: PowderPatternDiffraction must persist while PowderPattern exists, and Crystal must persist while PowderPatternDiffraction exists.
24+
- Fix the custodian_ward when creating a PowderPatternDiffraction:
25+
PowderPatternDiffraction must persist while PowderPattern exists, and
26+
Crystal must persist while PowderPatternDiffraction exists.
1027

1128
- Add 3D Crystal viewer `pyobjcryst.crystal.Crystal.widget_3d`.
1229

‎README.rst

+45-1
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,26 @@ parallel jobs (-j4)::
7676

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

79+
Optional graphical dependencies for jupyter notebooks
80+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
81+
Some of the classes can produce graphical outputs, which can be
82+
displayed in a jupyter notebook:
83+
84+
* a Crystal structure can be displayed in 3D: this requires the
85+
``py3dmol`` and ``ipywidgets`` modules. See the notebook
86+
``examples/cystal_3d_widget.ipynb``
87+
* a PowderPattern can be displayed (and live-updated) if
88+
``matplotlib`` (and optionnally ``ipympl``) are installed. See the
89+
notebook ``examples/cimetidine-structure-solution-powder.ipynb``
90+
91+
In short, ``pip install jupyter matplotlib ipywidgets py3dmol``
92+
will give you all the required dependencies. Note that you can also
93+
use this in jupyterlab.
94+
95+
Note that ``jupyter``, ``ipywidgets``, ``matplotlib`` and ``ipympl`` can
96+
be installed using conda(-forge), but ``py3dmol`` should be installed using
97+
``pip``, as the conda version is obsolete.
98+
7999

80100
DEVELOPMENT
81101
-----------
@@ -109,7 +129,7 @@ Anaconda environment. This can be achieved by setting the ``CPATH``,
109129
``LIBRARY_PATH`` and ``LDFLAGS`` environment variables as follows::
110130

111131
# resolve the prefix directory P of the active Anaconda environment
112-
P="$(conda info --json | grep default_prefix | cut -d\" -f4)"
132+
P=$CONDA_PREFIX
113133
export CPATH=$P/include
114134
export LIBRARY_PATH=$P/lib
115135
export LDFLAGS=-Wl,-rpath,$P/lib
@@ -120,6 +140,25 @@ Note the Anaconda package for the required libobjcryst library is built
120140
with a C++ compiler provided by Anaconda. This may cause incompatibility
121141
with system C++. In such case please use Anaconda C++ to build pyobjcryst.
122142

143+
Quick conda environment from libobjcryst and pyobjcryst sources
144+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
145+
146+
If ``conda`` is available, you can create a pyobjcryst environment
147+
from the git repositories (downloaded in the current directory) using::
148+
conda create --yes --name pyobjcryst numpy matplotlib ipywidgets jupyter
149+
conda install --yes -n pyobjcryst -c conda-forge boost scons py3dmol
150+
conda activate pyobjcryst
151+
git clone https://github.com/diffpy/libobjcryst.git
152+
cd libobjcryst
153+
scons -j4 install prefix=$CONDA_PREFIX
154+
cd ..
155+
git clone https://github.com/diffpy/pyobjcryst.git
156+
cd pyobjcryst
157+
export CPATH=$CONDA_PREFIX/include
158+
export LIBRARY_PATH=$CONDA_PREFIX/lib
159+
export LDFLAGS=-Wl,-rpath,$CONDA_PREFIX/lib
160+
scons -j4 install prefix=$CONDA_PREFIX
161+
123162

124163
CONTACTS
125164
--------
@@ -129,3 +168,8 @@ For more information on pyobjcryst please visit the project web-page
129168
http://www.diffpy.org
130169

131170
or email Prof. Simon Billinge at [email protected].
171+
172+
You can also contact Vincent Favre-Nicolin ([email protected]) if you
173+
are using pyobjcryst outside diffpy, e.g. to display structures
174+
in a notebook, refine powder patterns or solve structures using the
175+
global optimisation algorithms, etc..

‎doc/manual/source/api/modules.rst

+64
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ pyobjcryst.crystal module
2929
:undoc-members:
3030
:show-inheritance:
3131

32+
pyobjcryst.diffractiondatasinglecrystal module
33+
----------------------------------------------
34+
35+
.. automodule:: pyobjcryst.diffractiondatasinglecrystal
36+
:members:
37+
:undoc-members:
38+
:show-inheritance:
39+
3240
pyobjcryst.general module
3341
-------------------------
3442

@@ -37,6 +45,22 @@ pyobjcryst.general module
3745
:undoc-members:
3846
:show-inheritance:
3947

48+
pyobjcryst.globaloptim module
49+
-----------------------------
50+
51+
.. automodule:: pyobjcryst.globaloptim
52+
:members:
53+
:undoc-members:
54+
:show-inheritance:
55+
56+
pyobjcryst.indexing module
57+
--------------------------
58+
59+
.. automodule:: pyobjcryst.indexing
60+
:members:
61+
:undoc-members:
62+
:show-inheritance:
63+
4064
pyobjcryst.io module
4165
--------------------
4266

@@ -45,6 +69,14 @@ pyobjcryst.io module
4569
:undoc-members:
4670
:show-inheritance:
4771

72+
pyobjcryst.lsq module
73+
---------------------
74+
75+
.. automodule:: pyobjcryst.lsq
76+
:members:
77+
:undoc-members:
78+
:show-inheritance:
79+
4880
pyobjcryst.molecule module
4981
--------------------------
5082

@@ -61,6 +93,22 @@ pyobjcryst.polyhedron module
6193
:undoc-members:
6294
:show-inheritance:
6395

96+
pyobjcryst.powderpattern module
97+
-------------------------------
98+
99+
.. automodule:: pyobjcryst.powderpattern
100+
:members:
101+
:undoc-members:
102+
:show-inheritance:
103+
104+
pyobjcryst.radiation module
105+
---------------------------
106+
107+
.. automodule:: pyobjcryst.radiation
108+
:members:
109+
:undoc-members:
110+
:show-inheritance:
111+
64112
pyobjcryst.refinableobj module
65113
------------------------------
66114

@@ -69,6 +117,14 @@ pyobjcryst.refinableobj module
69117
:undoc-members:
70118
:show-inheritance:
71119

120+
pyobjcryst.reflectionprofile module
121+
-----------------------------------
122+
123+
.. automodule:: pyobjcryst.reflectionprofile
124+
:members:
125+
:undoc-members:
126+
:show-inheritance:
127+
72128
pyobjcryst.scatterer module
73129
---------------------------
74130

@@ -77,6 +133,14 @@ pyobjcryst.scatterer module
77133
:undoc-members:
78134
:show-inheritance:
79135

136+
pyobjcryst.scatteringdata module
137+
--------------------------------
138+
139+
.. automodule:: pyobjcryst.scatteringdata
140+
:members:
141+
:undoc-members:
142+
:show-inheritance:
143+
80144
pyobjcryst.scatteringpower module
81145
---------------------------------
82146

‎doc/manual/source/conf.py

+5-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
import sys, os
66
import time
7+
import sphinx_py3doc_enhanced_theme
78
# Requires sphinx >= 0.6
89

910
# If extensions (or modules to document with autodoc) are in another directory,
@@ -23,7 +24,9 @@
2324
extensions = [
2425
'sphinx.ext.ifconfig',
2526
'sphinx.ext.autodoc',
26-
'm2r',
27+
'm2r2',
28+
'nbsphinx',
29+
'nbsphinx_link'
2730
]
2831

2932
# Add any paths that contain templates here, relative to this directory.
@@ -101,6 +104,7 @@
101104
# a list of builtin themes.
102105
#
103106
html_theme = 'sphinx_py3doc_enhanced_theme'
107+
html_theme_path = [sphinx_py3doc_enhanced_theme.get_html_theme_path()]
104108

105109
# Theme options are theme-specific and customize the look and feel of a theme
106110
# further. For a list of options available for each theme, see the

‎doc/manual/source/examples/Quantitative-phase-analysis.nblink

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"path": "../../../../examples/QPA-Quantitative phase analysis.ipynb"
3+
}

‎doc/manual/source/examples/crystal_3d_widget.nblink

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"path": "../../../../examples/crystal_3d_widget.ipynb"
3+
}

‎doc/manual/source/examples/index.rst

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
####################################################
2+
Example notebooks
3+
####################################################
4+
5+
Several examples available in the pyobjcryst repository:
6+
7+
8+
:doc:`3D Crystal structure display <crystal_3d_widget>`
9+
=======================================================
10+
11+
Example of importing a CIF file from a file or the
12+
`Crystallography Open Database <http://crystallography.net/cod/>`_
13+
and displaying it in a widget using
14+
`3dmol.js <https://3dmol.csb.pitt.edu/>`_.
15+
16+
:doc:`Solving the cimetidine structure from its powder pattern <structure-solution-powder-cimetidine>`
17+
======================================================================================================
18+
19+
In this example, a powder pattern is used to solve the crystal
20+
structure of Cimetidine. This covers all the steps: loading the
21+
data, indexing the pattern (determining the unit cell), finding
22+
the spacegroup, profile fitting, and solving the structure
23+
using a global optimisation algorithm.
24+
25+
:doc:`Solving the PbSO4 structure from its X and N powder patterns <structure-solution-powder-pbso4>`
26+
=====================================================================================================
27+
28+
In this example, two powder patterns (X-ray and neutron) are used to solve
29+
the crystal structure of PbSO4. This covers all the steps: loading the
30+
data, indexing the pattern (determining the unit cell), finding
31+
the spacegroup, profile fitting for the two patterns, and solving the
32+
structure using a global optimisation algorithm.
33+
34+
:doc:`Meta-structure solution using multi-processing <structure-solution-multiprocessing>`
35+
==========================================================================================
36+
37+
This is a more advanced example where 8 different spacegroups are
38+
tested in parallel to determine which one is correct. The solutions
39+
can then be compared and displayed individually.
40+
41+
:doc:`Quantitative phase analysis (QPA) <Quantitative-phase-analysis>`
42+
______________________________________________________________________
43+
44+
Example of QPA based on the data available from the `1999 Round Robin
45+
<https://www.iucr.org/__data/iucr/powder/QARR/samples.htm>`_,
46+
in the case where all present crystalline structures are known
47+
and there is no preferred orientation.

‎doc/manual/source/examples/structure-solution-multiprocessing.nblink

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"path": "../../../../examples/structure-solution-multiprocessing.ipynb"
3+
}

‎doc/manual/source/examples/structure-solution-powder-cimetidine.nblink

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"path": "../../../../examples/structure-solution-powder-cimetidine.ipynb"
3+
}

‎doc/manual/source/examples/structure-solution-powder-pbso4.nblink

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"path": "../../../../examples/structure-solution-powder-pbso4.ipynb"
3+
}

‎doc/manual/source/index.rst

+26
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ Christopher Farrow, Pavol Juhás, and Simon J.L. Billinge.
1717
The sources are now maintained as a part of the DiffPy-CMI complex
1818
modeling initiative at the Brookhaven National Laboratory.
1919

20+
Further developments including the ability to index and refine
21+
powder patterns, solve and display crystal structures, using the
22+
global optimisation and least squares algorithms (see the
23+
:doc:`examples/index`) are provided by Vincent Favre-Nicolin (ESRF).
24+
2025
For a complete list of contributors, see
2126
https://github.com/diffpy/pyobjcryst/graphs/contributors.
2227

@@ -29,6 +34,26 @@ Installation
2934
See the `README <https://github.com/diffpy/pyobjcryst#requirements>`_
3035
file included with the distribution.
3136

37+
======================================
38+
Usage
39+
======================================
40+
41+
pyobjcryst can be used in different ways:
42+
43+
* as a backend library to manage crystal structures description in an application
44+
like `DiffPy-CMI <https://www.diffpy.org/products/diffpycmi/index.html>`_
45+
* in python scripts or notebooks, allowing to display crystal structures,
46+
index and refine powder diffraction patterns, solve crystal structures
47+
from diffraction data using global optimisation algorithms, etc.. The
48+
functionality is similar to what is available in `Fox <http://fox.vincefn.net>`_.
49+
See the :doc:`examples/index`:
50+
51+
* :doc:`3D Crystal structure display <examples/crystal_3d_widget>`
52+
* :doc:`Solving the cimetidine structure from its powder pattern <examples/structure-solution-powder-cimetidine>`
53+
* :doc:`Solving the PbSO4 structure from its X and N powder patterns <examples/structure-solution-powder-pbso4>`
54+
* :doc:`Meta-structure solution using multi-processing <examples/structure-solution-multiprocessing>`
55+
* :doc:`Quantitative phase analysis (QPA) <examples/Quantitative-phase-analysis>`
56+
3257
======================================
3358
Table of contents
3459
======================================
@@ -39,6 +64,7 @@ Table of contents
3964
license
4065
release
4166
api/modules
67+
examples/index
4268

4369
========================================================================
4470
Indices

‎doc/manual/source/license.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ OPEN SOURCE LICENSE AGREEMENT
1414
the City of New York
1515
| Copyright (c) 2014-2019, Brookhaven Science Associates,
1616
Brookhaven National Laboratory
17-
17+
| Copyright (c) 2015-, ESRF-European Synchrotron Radiation Facility
1818
1919
The "DiffPy-CMI" is distributed subject to the following license conditions:
2020

0 commit comments

Comments
 (0)