doc & test: copy examples over and add generator tests

.github/workflows/matrix-and-codecov-on-merge-to-main.yml

@@ -19,6 +19,6 @@ jobs:
       headless: false
       run: |
         set -Eeuo pipefail
-        python -m pip install --no-deps diffpy.srfit==3.4.0rc0
+        python -m pip install --no-deps diffpy.cmistructure
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/tests-on-pr.yml

@@ -13,6 +13,6 @@ jobs:
       headless: false
       run: |
         set -Eeuo pipefail
-        python -m pip install --no-deps diffpy.srfit==3.4.0rc0
+        python -m pip install --no-deps diffpy.cmistructure
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

README.rst

@@ -38,7 +38,17 @@
 
 The code of the PDF pack of the diffpy.cmi package.
 
-* LONGER DESCRIPTION HERE
+``diffpy.cmipdf`` calculates and refines atomic pair distribution functions
+(PDFs) with ``diffpy.srfit``. ``PDFGenerator`` and ``DebyePDFGenerator``
+calculate the PDF of a crystal or of an isolated scatterer, such as a
+nanoparticle or molecule, with ``diffpy.srreal``. ``PDFContribution`` sets up a
+PDF fit from a data file and one or more structures, ``PDFParser`` reads PDF
+data and its metadata, and ``diffpy.cmipdf.characteristicfunctions`` provides
+nanoparticle shape functions. Structures are adapted for refinement by
+``diffpy.cmistructure``.
+
+This code was moved from ``diffpy.srfit.pdf``. Example refinements are in
+`docs/examples <https://github.com/diffpy/diffpy.cmipdf/tree/main/docs/examples>`_.
 
 For more information about the diffpy.cmipdf library, please consult our `online documentation <https://diffpy.github.io/diffpy.cmipdf>`_.
 
@@ -82,7 +92,7 @@ and run the following ::
 
 This package also provides command-line utilities. To check the software has been installed correctly, type ::
 
-        diffpy.cmipdf --version
+        diffpy-cmipdf --version
 
 You can also type the following command to verify the installation. ::
 
@@ -91,7 +101,7 @@ You can also type the following command to verify the installation. ::
 
 To view the basic usage and available commands, type ::
 
-        diffpy.cmipdf -h
+        diffpy-cmipdf -h
 
 Getting Started
 ---------------

docs/examples/coreshellnp.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python
+########################################################################
+#
+# (c) 2011 The Trustees of Columbia University in the City of New York.
+# (c) 2026 Contributors to diffpy.cmipdf.
+# All rights reserved.
+#
+# File coded by: Chris Farrow, Peng Tian and members of the diffpy community.
+#
+# Originally developed in diffpy.srfit by the DANSE Diffraction group and
+# Simon J. L. Billinge.
+#
+# See GitHub contributions for a more detailed list of contributors.
+# https://github.com/diffpy/diffpy.cmipdf/graphs/contributors
+#
+# See LICENSE.rst and LICENSE_DANSE.rst for license information.
+#
+########################################################################
+"""Refine the structure of a core-shell nanoparticle.
+
+This applies the characteristic function formalism described in
+nppdfcrystal.py to the case of a spherical core-shell nanoparticle. The
+modeling approach we use is to refine the core and shell as two
+different phases, each with an appropriate characteristic function.
+"""
+
+from pathlib import Path
+
+from pyobjcryst.crystal import create_crystal_from_cif
+from scipy.optimize import leastsq
+
+from diffpy.cmipdf import PDFGenerator, PDFParser
+from diffpy.srfit.fitbase import (
+    FitContribution,
+    FitRecipe,
+    FitResults,
+    Profile,
+)
+
+# Example Code
+
+
+def make_recipe(stru1, stru2, datname):
+    """Create a fitting recipe for crystalline PDF data."""
+    # The Profile
+    profile = Profile()
+
+    # Load data and add it to the profile
+    parser = PDFParser()
+    parser.parse_file(datname)
+    profile.load_parsed_data(parser)
+    profile.set_calculation_range(xmin=1.5, xmax=45, dx=0.1)
+
+    # The ProfileGenerator
+    # In order to fit the core and shell phases simultaneously, we must use two
+    # PDFGenerators.
+    #
+    # The generator for the CdS core. We call it "G_CdS" and will use this name
+    # later when we set the fitting equation in the FitContribution.
+    generator_cds = PDFGenerator("G_CdS")
+    generator_cds.set_structure(stru1)
+    generator_cds.set_qmax(26)
+    generator_cds.qdamp.value = 0.0396
+    # The generator for the ZnS shell. We call it "G_ZnS".
+    generator_zns = PDFGenerator("G_ZnS")
+    generator_zns.set_structure(stru2)
+    generator_zns.set_qmax(26)
+    generator_zns.qdamp.value = 0.0396
+
+    # The FitContribution
+    # Add both generators and the profile to the FitContribution.
+    contribution = FitContribution("cdszns")
+    contribution.add_profile_generator(generator_cds)
+    contribution.add_profile_generator(generator_zns)
+    contribution.set_profile(profile, xname="r")
+
+    # Set up the characteristic functions. We use a spherical CF for the core
+    # and a spherical shell CF for the shell. Since this is set up as two
+    # phases, we implicitly assume that the core-shell correlations contribute
+    # very little to the PDF.
+    from diffpy.cmipdf.characteristicfunctions import (
+        shell_particle,
+        spherical_particle,
+    )
+
+    contribution.register_function(spherical_particle, name="f_CdS")
+    contribution.register_function(shell_particle, name="f_ZnS")
+
+    # Write the fitting equation. We want to sum the PDFs from each phase and
+    # multiply it by a scaling factor.
+    contribution.set_equation("scale * (f_CdS * G_CdS +  f_ZnS * G_ZnS)")
+
+    # Make the FitRecipe and add the FitContribution.
+    recipe = FitRecipe()
+    recipe.add_contribution(contribution)
+
+    # Vary the inner radius and thickness of the shell. Constrain the core
+    # diameter to twice the shell radius.
+    recipe.add_variable(contribution.radius, 15)
+    recipe.add_variable(contribution.thickness, 11)
+    recipe.add_constraint(contribution.particle_diameter, "2 * radius")
+
+    # Configure the fit variables
+    # Start by configuring the scale factor and resolution factors.
+    # We want the sum of the phase scale factors to be 1.
+    recipe.create_new_variable("scale_CdS", 0.7)
+    recipe.add_constraint(generator_cds.scale, "scale_CdS")
+    recipe.add_constraint(generator_zns.scale, "1 - scale_CdS")
+    # We also want the resolution factor to be the same on each.
+
+    # Vary the global scale as well.
+    recipe.add_variable(contribution.scale, 0.3)
+
+    # Now we can configure the structural parameters. We tag the different
+    # structural variables so we can easily turn them on and off in the
+    # subsequent refinement.
+    phase_cds = generator_cds.phase
+    for par in phase_cds.sgpars.latpars:
+        recipe.add_variable(par, name=par.name + "_cds", tag="lat")
+    for par in phase_cds.sgpars.adppars:
+        recipe.add_variable(par, 1, name=par.name + "_cds", tag="adp")
+    recipe.add_variable(
+        phase_cds.sgpars.xyzpars.z_1, name="z_1_cds", tag="xyz"
+    )
+    # Since we know these have stacking disorder, constrain the B33 adps for
+    # each atom type.
+    recipe.add_constraint("B33_1_cds", "B33_0_cds")
+    recipe.add_variable(generator_cds.delta2, name="delta2_cds", value=5)
+
+    phase_zns = generator_zns.phase
+    for par in phase_zns.sgpars.latpars:
+        recipe.add_variable(par, name=par.name + "_zns", tag="lat")
+    for par in phase_zns.sgpars.adppars:
+        recipe.add_variable(par, 1, name=par.name + "_zns", tag="adp")
+    recipe.add_variable(
+        phase_zns.sgpars.xyzpars.z_1, name="z_1_zns", tag="xyz"
+    )
+    recipe.add_constraint("B33_1_zns", "B33_0_zns")
+    recipe.add_variable(generator_zns.delta2, name="delta2_zns", value=2.5)
+
+    # Give the recipe away so it can be used!
+    return recipe
+
+
+plot_styles = {
+    "xlabel": r"$r (\AA)$",
+    "ylabel": r"$G (\AA^{-2})$",
+}
+
+
+def main():
+    """Set up and refine the recipe."""
+    # Make the data and the recipe
+    cdsciffile = Path(__file__).parent / "data/CdS.cif"
+    znsciffile = Path(__file__).parent / "data/ZnS.cif"
+    data = Path(__file__).parent / "data/CdS_ZnS_nano.gr"
+
+    # Make the recipe
+    stru1 = create_crystal_from_cif(str(cdsciffile))
+    stru2 = create_crystal_from_cif(str(znsciffile))
+    recipe = make_recipe(stru1, stru2, data)
+    from diffpy.srfit.fitbase.fithook import PlotFitHook
+
+    recipe.push_fit_hook(PlotFitHook())
+    recipe.fithooks[0].verbose = 3
+
+    # Optimize - we do this in steps to help convergence
+    recipe.fix("all")
+
+    # Start with the lattice parameters. In make_recipe, these were tagged with
+    # "lat". Here is how we use that.
+    recipe.free("lat")
+    leastsq(recipe.residual, recipe.values, maxfev=50)
+
+    # Now the scale and phase fraction.
+    recipe.free("scale", "scale_CdS")
+    leastsq(recipe.residual, recipe.values, maxfev=50)
+
+    # The ADPs.
+    recipe.free("adp")
+    leastsq(recipe.residual, recipe.values, maxfev=100)
+
+    # The delta2 parameters.
+    recipe.free("delta2_cds", "delta2_zns")
+    leastsq(recipe.residual, recipe.values, maxfev=50)
+
+    # The shape parameters.
+    recipe.free("radius", "thickness")
+    leastsq(recipe.residual, recipe.values, maxfev=50)
+
+    # The positional parameters.
+    recipe.free("xyz")
+    leastsq(recipe.residual, recipe.values)
+
+    # Generate and print the FitResults
+    res = FitResults(recipe)
+    res.print_results()
+
+    # Plot!
+    recipe.plot_recipe(**plot_styles)
+    return
+
+
+if __name__ == "__main__":
+    main()
+
+# End of file