From e532e6bfeb9b7f0d378cd113bf057052b8915b76 Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Tue, 16 Sep 2025 15:59:09 -0400 Subject: [PATCH 1/4] docs: update installation instructions --- products/diffpycmi/index.rst | 186 ++++++++++++++++++++++++++--------- 1 file changed, 138 insertions(+), 48 deletions(-) diff --git a/products/diffpycmi/index.rst b/products/diffpycmi/index.rst index 4134436a..70f6a4d4 100644 --- a/products/diffpycmi/index.rst +++ b/products/diffpycmi/index.rst @@ -1,26 +1,19 @@ ########## -DiffPy-CMI +DiffPy.CMI ########## -DiffPy-CMI is our complex modeling framework. It is a highly flexible -library of Python modules for robust modeling of nanostructures in -crystals, nanomaterials, and amorphous materials. - -The software provides functionality for storage and manipulation of -structure data and calculation of structure-based quantities, such as -PDF, SAS, bond valence sums, atom overlaps, bond lengths, and -coordinations. Most importantly the DiffPy-CMI package contains a -fitting framework for combining multiple experimental inputs in a single -optimization problem. - -This is an early release of code that is under intense development, with -support for installation on Unix, Linux, and Macintosh machines. The -scope and documentation of the project will evolve rapidly, but we want -to make the code available at the earliest possible date. Please make -use of the software and provide feedback and suggestions for -improvement, but please be patient and check back frequently for -updates. +Diffpy.cmi is designed as an extensible complex modeling infrastructure. +Users and developers can readily integrate novel data types and constraints +into custom workflows. While widely used for advanced analysis of structural +data, the framework is general and can be applied to any problem where model +parameters are refined to fit calculated quantities to data. +Diffpy.cmi is a community-driven project that supports Unix, Linux, macOS, +and Windows platforms. It is designed to be used in Python scripts enabling +flexible scripting and automation for advanced and reproducible workflows. +Users are encouraged to leverage the software for their modeling needs and +to contribute feedback, use cases, and extensions through the project +community. .. figure:: ../../images/diffpycmi_screenshot.png @@ -30,38 +23,135 @@ updates. Installation ============ +To install ``diffpy.cmi``, create a new conda environment or activate an existing environment and install the package from the conda-forge channel. + +.. code-block:: bash + + conda create -n diffpy.cmi-env + conda install -c conda-forge diffpy.cmi + conda activate diffpy.cmi-env + +To confirm that the installation was successful, type + +.. code-block:: bash + + cmi --version + +The output should print the latest version. + +If the above does not work, you can use ``pip`` to download and install the latest release from +`Python Package Index `_. +To install using ``pip`` into your ``diffpy.cmi_env`` environment, type + +.. code-block:: bash + + pip install diffpy.cmi + +Pack and Profile Installation +----------------------------- + +Use the `cmi` command-line interface to install and manage modular optional dependencies, known as `packs`, +and to configure or execute user-defined workflows that combine multiple packs with optional post-installation steps, +known as `profiles`. To use `cmi`, you can run the following example commands: + +Show available commands and options with, + +.. code-block:: bash + + cmi -h + +List installed and available packs and profiles, + +.. code-block:: bash + + cmi pack list + cmi profile list + +Show details of a specific pack or profile, + +.. code-block:: bash + + cmi pack show + cmi profile show + +Install a pack or profile (by name or path), + +.. code-block:: bash -Use of this software is subject to the conditions in -software :doc:`LICENSE `. + cmi install + cmi install + cmi install -As of version 3.0 DiffPy-CMI is available for Linux and -Mac as a collection of packages for Anaconda Python. As -a first step download and install **Anaconda for Python 3.7** -from |anaconda-download|. +.. admonition:: Example installation -.. note:: - DiffPy-CMI is available from the "diffpy" channel of Anaconda packages. It requires Python 3.5 or later or 2.7. It is recommended to install it in a separate Anaconda environment, for example *py37* or other preferred python versions. - Make sure that *py37* environment is activated when working with DiffPy-CMI. :: + For example, to install the pack for PDF modeling, type, - conda create --name=py37 python=3.7 - conda activate py37 + .. code-block:: bash -Once Anaconda is ready, DiffPy-CMI can be installed from the "diffpy" -channel of Anaconda packages as follows :: + cmi install pdf - conda config --add channels diffpy - conda install diffpy-cmi + To check to see if the pack was installed, type, -The software distribution over Anaconda makes it easy to publish -frequent software updates. To update your installation later use :: + .. code-block:: bash - conda update diffpy-cmi + cmi pack list -If you don't want to use Anaconda you can -:doc:`install DiffPy-CMI from sources `. Note that -this method takes more time and requires more experience -with the operating system. + The output should look something like this, + .. code-block:: bash + + Installed: + - core + - pdf + Available to install: + - plotting + - tests + - docs + + +Download examples +----------------- + +To list and copy example scripts and data to your working directory, type, + +.. code-block:: bash + + cmi example list + cmi example copy + +.. admonition:: Example + + For example, to see the example scripts for PDF fitting, type, + + .. code-block:: bash + + cmi example list + + The output should look something like this, + + .. code-block:: bash + + ch03NiModelling + ch05Fit2Phase + ch06RefineCrystalStructureGen + ch07StructuralPhaseTransitions + ch08NPRefinement + ch11ClusterXYZ + + To copy the example for bulk Ni PDF fitting, type, + + .. code-block:: bash + + cmi example copy ch03NiModelling + + This will copy the example directory ``ch03NiModelling`` to your current working directory. Within this directory exists + the scripts and data to fit the bulk Ni PDF. + + You can then run the fitting script with, + + .. code-block:: bash + + python ch03NiModelling/solutions/diffpy-cmi/fitBulkNi.py What next? ========== @@ -78,11 +168,11 @@ What next? Tutorials ========= -* ADD2019_ school and conference -- - https://github.com/diffpy/add2019-diffpy-cmi - -.. _ADD2019: https://workshops.ill.fr/event/133/page/32-home +* Worked examples and experimental data from the book are freely available at our + `GitHub repository `_. +* ADD2019 school and conference -- + https://github.com/diffpy/add2019-diffpy-cmi Documentation ============= @@ -101,8 +191,8 @@ at the links below. * |doc-libdiffpy|_ -- C++ library for calculation of PDF and other real-space quantities -See :ref:`DiffPy-CMI contents ` for a complete list -of open-source libraries that are included in DiffPy-CMI and +See :ref:`DiffPy.CMI contents ` for a complete list +of open-source libraries that are included in DiffPy.CMI and their respective project pages. @@ -110,7 +200,7 @@ Reference ========= If you use this software in a research work which leads to publication, -we ask you to acknowledge the use of DiffPy-CMI by citing the following +we ask you to acknowledge the use of DiffPy.CMI by citing the following paper: * |citeJuhasAca15| From 140c0504c34d17b2cd1d6a0018349b53aff58099 Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Tue, 16 Sep 2025 15:59:18 -0400 Subject: [PATCH 2/4] move diffpy-cmi to diffpy.cmi --- README.md | 12 ++++++------ _templates/menu01.html | 2 +- abbreviations.txt | 2 +- products/diffpycmi/LICENSE.txt | 6 +++--- products/diffpycmi/cmi_exchange.rst | 6 +++--- products/diffpycmi/contents.rst | 4 ++-- products/diffpycmi/contributecode.rst | 2 +- products/diffpycmi/install.rst | 14 +++++++------- products/diffpycmi/license.rst | 4 ++-- products/diffpycmi/updatesources.rst | 2 +- products/mPDF.rst | 4 ++-- products/xPDFsuite.rst | 2 +- products/xinterpdf.rst | 4 ++-- publications.rst | 2 +- .../doc/pdfgetx/2.0.0/_sources/tutorial.rst.txt | 6 +++--- static_root/doc/pdfgetx/2.0.0/tutorial.html | 4 ++-- .../doc/pdfgetx/2.1.0/_sources/tutorial.rst.txt | 6 +++--- static_root/doc/pdfgetx/2.1.0/tutorial.html | 6 +++--- .../doc/pdfgetx/2.1.1/_sources/tutorial.rst.txt | 6 +++--- static_root/doc/pdfgetx/2.1.1/tutorial.html | 6 +++--- .../doc/pdfgetx/2.1.2/_sources/tutorial.rst.txt | 6 +++--- static_root/doc/pdfgetx/2.1.2/tutorial.html | 6 +++--- .../doc/pdfgetx/2.2.0/_sources/tutorial.rst.txt | 6 +++--- static_root/doc/pdfgetx/2.2.0/tutorial.html | 6 +++--- .../doc/pdfgetx/2.2.1/_sources/tutorial.rst.txt | 6 +++--- static_root/doc/pdfgetx/2.2.1/tutorial.html | 6 +++--- 26 files changed, 68 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 0a9c7c0c..966abed9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Sphinx sources for the [diffpy.org][site] web page. - [Where to Make Changes](#where-to-make-changes) - [Adding Citations](#adding-citations) - [Adding Publications that Describe a DiffPy Project (the "Reference" Section)](#reference-section-1) - - [Adding Other Publications (the "Publication Using DiffPy-CMI" Section)](#reference-section-2) + - [Adding Other Publications (the "Publication Using DiffPy.CMI" Section)](#reference-section-2) - [New Version of Existing Project](#new-version) - [New Project](#publishing-new-project) - [Publishing Changes](#publishing-changes) @@ -107,8 +107,8 @@ you add the reference to the proper section and do so in descending reverse chro (i.e., the newest citations should appear at the top of their respective sections). *Note:* In this example, the citation is for a publication -which describes a product of the DiffPy-CMI project (namely, PDFgetN3). For publications which -describe a component of DiffPy-CMI, we provide a link to download the publication directly from +which describes a product of the DiffPy.CMI project (namely, PDFgetN3). For publications which +describe a component of DiffPy.CMI, we provide a link to download the publication directly from the [diffpy.org][site] website. Here, the link is provided via the `|downloadJuhasJac18|` tag which is the identifier for another snippet within [abbreviations.txt](https://github.com/diffpy/diffpy.github.io/blob/source/abbreviations.txt#L294) following the definition of `|citeJuhasJac18|`, seen here as: @@ -130,10 +130,10 @@ placed within `pdfgetx`'s documentation directory and referenced accordingly wit -### Adding Other Publications (the "Publication Using DiffPy-CMI" Section) +### Adding Other Publications (the "Publication Using DiffPy.CMI" Section) -Adding references to publications that do not describe the release/use of a product within the DiffPy-CMI -project (e.g., papers which use some component of DiffPy-CMI), we simply provide the usual citation text (with +Adding references to publications that do not describe the release/use of a product within the DiffPy.CMI +project (e.g., papers which use some component of DiffPy.CMI), we simply provide the usual citation text (with appropriate DOI link). To add a citation of this type, refer to the information in [Reference Section](#reference-section-1), but disregard everything starting at, and following, the [Note](#reference-section-note). diff --git a/_templates/menu01.html b/_templates/menu01.html index 6dc9147d..3c291077 100644 --- a/_templates/menu01.html +++ b/_templates/menu01.html @@ -7,7 +7,7 @@