From 32f71ace710f7adcd2439cb9768988d3992904a8 Mon Sep 17 00:00:00 2001 From: Simon Billinge Date: Wed, 6 Aug 2025 06:52:34 -0400 Subject: [PATCH 1/2] docs: synchronize readme with old one --- README.rst | 103 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 87 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 386430e..44e919d 100644 --- a/README.rst +++ b/README.rst @@ -38,22 +38,52 @@ 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. + Citation -------- -If you use pyobjcryst in a scientific publication, we would like you to cite this package as +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) - pyobjcryst Package, https://github.com/diffpy/pyobjcryst +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.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. :: @@ -71,7 +101,30 @@ To confirm that the installation was successful, type :: The output should print the latest version displayed on the badges above. -If the above does not work, you can use ``pip`` to download and install the latest release from +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 + +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`` + +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 `_. To install using ``pip`` into your ``pyobjcryst_env`` environment, type :: @@ -91,20 +144,38 @@ parallel jobs (-j4):: conda install --file requirements/conda.txt scons -j4 dev -See ``scons -h`` for description of build targets and options. Need to install test dependencies -(``requirements/test.txt``) to run SCons test mode. +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: +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. + +Testing your installation +------------------------- + +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 -* 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 --------------- From 9f63032c7daa8876cd7091f0b4524e214b2f490c Mon Sep 17 00:00:00 2001 From: Simon Billinge Date: Wed, 6 Aug 2025 07:01:04 -0400 Subject: [PATCH 2/2] docs: move getting started up in readme --- README.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 44e919d..edef84a 100644 --- a/README.rst +++ b/README.rst @@ -120,6 +120,11 @@ displayed in a jupyter notebook: ``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 ----------------------------------- @@ -177,11 +182,6 @@ First install test dependencies then type pytest:: pytest -Getting Started ---------------- - -You may consult our `online documentation `_ for tutorials and API references. - Support and Contribute ----------------------