diffpy · sbillinge · Sep 19, 2025 · Sep 16, 2025 · Sep 16, 2025 · Sep 16, 2025
diff --git 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).
 
 <a name="reference-section-note">*Note:*</a> 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
 
 
 <a name="reference-section-2"></a>
-### 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/_includes/substitutions.rst b/_includes/substitutions.rst
@@ -0,0 +1,2 @@
+.. define global names and alias here
+.. |diffpycmi| replace:: diffpy.cmi
diff --git a/_templates/menu01.html b/_templates/menu01.html
@@ -7,7 +7,7 @@
   <ul class="dropdown-menu menu01"
       role="menu"
       aria-labelledby="dLabelMenu01">
-      <li><a href="{{pathto('products/diffpycmi/index')}}">DiffPy-CMI</a></li>
+      <li><a href="{{pathto('products/diffpycmi/index')}}">diffpy.cmi</a></li>
       <li><a href="{{pathto('products/xPDFsuite')}}">xPDFsuite</a></li>
       <li><a href="{{pathto('products/pdfgetx')}}">PDFgetX3, PDFgetN3 and PDFgetS3</a></li>
       <li><a href="{{pathto('products/pdfgui')}}">PDFgui</a></li>

diff --git a/abbreviations.txt b/abbreviations.txt
@@ -66,7 +66,7 @@
 
 
 .. |DiffPyCMI| replace::
-   :doc:`DiffPy-CMI </products/diffpycmi/index>`
+   :doc:`diffpy.cmi </products/diffpycmi/index>`
 
 .. |citeShiPRL14| replace:: Chenyang Shi, Majid Beidaghi, Michael
    Naguib, Olha Mashtalir, Yury Gogotsi, and Simon J. L. Billinge,

diff --git a/conf.py b/conf.py
@@ -40,6 +40,11 @@
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
+# The reST default prolog, included at the beginning of every source file.
+rst_prolog = """
+.. include:: _includes/substitutions.rst
+"""
+
 # The master toctree document.
 master_doc = 'index'
 

diff --git a/products/diffpycmi/LICENSE.txt b/products/diffpycmi/LICENSE.txt
@@ -14,15 +14,15 @@ Copyright (c) 2014-2019, Brookhaven Science Associates, Brookhaven National
     Laboratory
 
 
-The "DiffPy-CMI" is distributed subject to the following license conditions:
+The "diffpy.cmi" is distributed subject to the following license conditions:
 
 
 SOFTWARE LICENSE AGREEMENT
 
-    Software: DiffPy-CMI
+    Software: diffpy.cmi
 
 
-(1) The "Software", below, refers to the aforementioned DiffPy-CMI (in either
+(1) The "Software", below, refers to the aforementioned diffpy.cmi (in either
 source code, or binary form and accompanying documentation).
 
 Part of the software was derived from the DANSE, ObjCryst++ (with permission),

diff --git a/products/diffpycmi/cmi_exchange.rst b/products/diffpycmi/cmi_exchange.rst
@@ -2,9 +2,9 @@ CMI Exchange
 =============
 
 The `CMI Exchange`_ is a collection of community developed scripts,
-functions, and IPython plugins that make use of the DiffPy-CMI
-framework. If you are new to DiffPy-CMI it is a great place to get
-started.  If you've been working with DiffPy-CMI for a while and feel
+functions, and IPython plugins that make use of the |diffpycmi|
+framework. If you are new to |diffpycmi| it is a great place to get
+started.  If you've been working with |diffpycmi| for a while and feel
 that others would benefit from seeing your code please contribute!
 
 .. _cmi exchange: https://github.com/diffpy/cmi_exchange#cmi-exchange

diff --git a/products/diffpycmi/contents.rst b/products/diffpycmi/contents.rst
@@ -1,9 +1,9 @@
 .. _contents:
 
-DiffPy-CMI Contents
+|diffpycmi| Contents
 ===================
 
-The DiffPy-CMI release includes Python and C++ libraries developed by
+The |diffpycmi| release includes Python and C++ libraries developed by
 the DiffPy team as well as external libraries necessary for functionality.
 
 Libraries developed by the DiffPy team

diff --git a/products/diffpycmi/contributecode.rst b/products/diffpycmi/contributecode.rst
@@ -1,7 +1,7 @@
 How to Contribute Code
 ======================
 
-The DiffPy-CMI bundle consists of the following projects, all hosted on
+The |diffpycmi| bundle consists of the following projects, all hosted on
 github.  To contribute code simply fork the project you'd like to work
 on and issue a pull request.
 

diff --git a/products/diffpycmi/index.rst b/products/diffpycmi/index.rst
@@ -1,26 +1,19 @@
 ##########
-DiffPy-CMI
+|diffpycmi|
 ##########
 
-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 <https://pypi.python.org>`_.
+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 <pack_name>
+    cmi profile show <profile_name>
+
+Install a pack or profile (by name or path),
+
+.. code-block:: bash
+
+    cmi install <pack_name>
+    cmi install <profile_name>
+    cmi install </absolute/path/to/profile>
+
+.. admonition:: Example installation
+
+    For example, to install the pack for PDF modeling, type,
+
+    .. code-block:: bash
+
+        cmi install pdf
+
+    To check to see if the pack was installed, type,
+
+    .. code-block:: bash
+
+        cmi pack list
+
+    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 <example_name>
+
+.. admonition:: Example
+
+    For example, to see the example scripts for PDF fitting, type,
+
+    .. code-block:: bash
+
+        cmi example list
 
-Use of this software is subject to the conditions in
-software :doc:`LICENSE <license>`.
+    The output should look something like this,
 
-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|.
+    .. code-block:: bash
 
-.. 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. ::
+        ch03NiModelling
+        ch05Fit2Phase
+        ch06RefineCrystalStructureGen
+        ch07StructuralPhaseTransitions
+        ch08NPRefinement
+        ch11ClusterXYZ
 
-      conda create --name=py37 python=3.7
-      conda activate py37
+    To copy the example for bulk Ni PDF fitting, type,
 
-Once Anaconda is ready, DiffPy-CMI can be installed from the "diffpy"
-channel of Anaconda packages as follows ::
+    .. code-block:: bash
 
-   conda config --add channels diffpy
-   conda install diffpy-cmi
+        cmi example copy ch03NiModelling
 
-The software distribution over Anaconda makes it easy to publish
-frequent software updates.  To update your installation later use ::
+    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.
 
-   conda update diffpy-cmi
+    You can then run the fitting script with,
 
-If you don't want to use Anaconda you can
-:doc:`install DiffPy-CMI from sources <install>`.  Note that
-this method takes more time and requires more experience
-with the operating system.
+    .. code-block:: bash
 
+        python ch03NiModelling/solutions/diffpy-cmi/fitBulkNi.py
 
 What next?
 ==========
@@ -78,11 +168,14 @@ What next?
 Tutorials
 =========
 
-* ADD2019_ school and conference --
-  https://github.com/diffpy/add2019-diffpy-cmi
+* A step-by-step tutorial on using diffpy.cmi for PDF analysis is available at the documentation site for
+  ``diffpy.cmi`` -- https://www.diffpy.org/diffpy.cmi/tutorials/index.html.
 
-.. _ADD2019: https://workshops.ill.fr/event/133/page/32-home
+* Worked examples and experimental data from the book *Atomic Pair Distribution Function Analysis: A Primer* are freely available at our
+  `GitHub repository <https://github.com/Billingegroup/pdfttp_data>`_.
 
+* ADD2019 school and conference --
+  https://github.com/diffpy/add2019-diffpy-cmi.
 
 Documentation
 =============
@@ -101,16 +194,16 @@ at the links below.
 * |doc-libdiffpy|_ -- C++ library for calculation of PDF and other real-space
   quantities
 
-See :ref:`DiffPy-CMI contents <contents>` for a complete list
-of open-source libraries that are included in DiffPy-CMI and
+See :ref:`diffpy.cmi contents <contents>` for a complete list
+of open-source libraries that are included in |diffpycmi| and
 their respective project pages.
 
 
 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 |diffpycmi| by citing the following
 paper:
 
 * |citeJuhasAca15|
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		.. define global names and alias here
		.. \|diffpycmi\| replace:: diffpy.cmi