xrayscatteringtools 1.1.0__tar.gz → 1.3.0__tar.gz

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/.github/workflows/tests.yml

@@ -8,16 +8,18 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # Pinned: ubuntu-latest is now 26.04, which has no Python 3.9 builds.
+    runs-on: ubuntu-24.04
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xrayscatteringtools
-Version: 1.1.0
+Version: 1.3.0
 Summary: A library for gas phase analysis at the CXI endstation
 Project-URL: Homepage, https://github.com/Weber-Group/xrayscatteringtools
 Project-URL: Issues, https://github.com/Weber-Group/xrayscatteringtools/issues
@@ -108,13 +108,13 @@ Calibration and correction tools:
 Theoretical scattering models:
 - **`iam`** — Independent Atom Model: isotropic and oriented elastic/inelastic scattering patterns (`iam_elastic_pattern`, `iam_inelastic_pattern`, `iam_total_pattern`, and their `_oriented` variants), `iam_compton_spectrum`, and `iam_inelastic_pattern_from_formula` (Compton intensity from a chemical formula alone, no coordinates needed).
 - **`geometries`** — Lazy-loaded optimized molecular geometries from bundled HDF5 data (accessed as module-level attributes, e.g. `geometries.SF6__CCSD_T_DHK__aug_cc_pV5Z_DK`).
-- **`patterns`** — Lazy-loaded _ab initio_ scattering patterns from bundled HDF5 data (accessed as module-level attributes named `molecule__method__basis_set`, e.g. `patterns.SF6__HF__aug_cc_pVDZ`). Available: SF6 at the HF, MP2, and CCSD levels (aug-cc-pVDZ), and Ne at the CCSD+X2C level (aug-cc-pVDZ/TZ/QZ+DK). Some patterns carry a `notes` attribute with details of the calculation.
+- **`patterns`** — Lazy-loaded _ab initio_ scattering patterns from bundled HDF5 data (accessed as module-level attributes named `molecule__method__basis_set`, e.g. `patterns.SF6__HF__aug_cc_pVDZ`). Available: SF6 at the HF, MP2, and CCSD levels (aug-cc-pVDZ), HF (cc-pVTZ), and frozen-core CCSD (aug-cc-pVDZ/TZ); Ne at the CCSD+X2C level (aug-cc-pVDZ/TZ/QZ+DK); and norbornadiene (`NBD`) and quadricyclane (`QC`) at HF (cc-pVTZ) and frozen-core CCSD (aug-cc-pVDZ). Every pattern has the total `I_q`; many also carry `I_q_elastic`/`I_q_inelastic`, and the newer ones add the `I_q_hartree`/`I_q_exchange`/`I_q_cumulant` decomposition. Some patterns carry a `notes` attribute with details of the calculation.
 
 ---
 
 ## Testing
 
-The test suite uses [pytest](https://docs.pytest.org/) and covers all modules (460+ tests):
+The test suite uses [pytest](https://docs.pytest.org/) and covers all modules (580+ tests):
 ```bash
 pip install -e ".[dev]"
 python -m pytest tests/
@@ -138,4 +138,4 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 
 ## Acknowledgments
 
-This library was created by [David J. Romano](https://david.lizaanddavid.com) by compiling and standardizing code from previous data analysis pipelines. Maintained by the [Weber Research Group](https://sites.brown.edu/weber-lab/) and developed by collaborators to facilitate X-ray scattering research.
+This library was created by [David J. Romano](https://davidromano.dev) by compiling and standardizing code from previous data analysis pipelines. Maintained by the [Weber Research Group](https://sites.brown.edu/weber-lab/) and developed by collaborators to facilitate X-ray scattering research.

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/README.md

@@ -80,13 +80,13 @@ Calibration and correction tools:
 Theoretical scattering models:
 - **`iam`** — Independent Atom Model: isotropic and oriented elastic/inelastic scattering patterns (`iam_elastic_pattern`, `iam_inelastic_pattern`, `iam_total_pattern`, and their `_oriented` variants), `iam_compton_spectrum`, and `iam_inelastic_pattern_from_formula` (Compton intensity from a chemical formula alone, no coordinates needed).
 - **`geometries`** — Lazy-loaded optimized molecular geometries from bundled HDF5 data (accessed as module-level attributes, e.g. `geometries.SF6__CCSD_T_DHK__aug_cc_pV5Z_DK`).
-- **`patterns`** — Lazy-loaded _ab initio_ scattering patterns from bundled HDF5 data (accessed as module-level attributes named `molecule__method__basis_set`, e.g. `patterns.SF6__HF__aug_cc_pVDZ`). Available: SF6 at the HF, MP2, and CCSD levels (aug-cc-pVDZ), and Ne at the CCSD+X2C level (aug-cc-pVDZ/TZ/QZ+DK). Some patterns carry a `notes` attribute with details of the calculation.
+- **`patterns`** — Lazy-loaded _ab initio_ scattering patterns from bundled HDF5 data (accessed as module-level attributes named `molecule__method__basis_set`, e.g. `patterns.SF6__HF__aug_cc_pVDZ`). Available: SF6 at the HF, MP2, and CCSD levels (aug-cc-pVDZ), HF (cc-pVTZ), and frozen-core CCSD (aug-cc-pVDZ/TZ); Ne at the CCSD+X2C level (aug-cc-pVDZ/TZ/QZ+DK); and norbornadiene (`NBD`) and quadricyclane (`QC`) at HF (cc-pVTZ) and frozen-core CCSD (aug-cc-pVDZ). Every pattern has the total `I_q`; many also carry `I_q_elastic`/`I_q_inelastic`, and the newer ones add the `I_q_hartree`/`I_q_exchange`/`I_q_cumulant` decomposition. Some patterns carry a `notes` attribute with details of the calculation.
 
 ---
 
 ## Testing
 
-The test suite uses [pytest](https://docs.pytest.org/) and covers all modules (460+ tests):
+The test suite uses [pytest](https://docs.pytest.org/) and covers all modules (580+ tests):
 ```bash
 pip install -e ".[dev]"
 python -m pytest tests/
@@ -110,4 +110,4 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 
 ## Acknowledgments
 
-This library was created by [David J. Romano](https://david.lizaanddavid.com) by compiling and standardizing code from previous data analysis pipelines. Maintained by the [Weber Research Group](https://sites.brown.edu/weber-lab/) and developed by collaborators to facilitate X-ray scattering research.
+This library was created by [David J. Romano](https://davidromano.dev) by compiling and standardizing code from previous data analysis pipelines. Maintained by the [Weber Research Group](https://sites.brown.edu/weber-lab/) and developed by collaborators to facilitate X-ray scattering research.

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xrayscatteringtools"
-version = "1.1.0"
+version = "1.3.0"
 description = "A library for gas phase analysis at the CXI endstation"
 authors = [
     { name = "David Romano", email = "david_j_romano@brown.edu" }

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/src/xrayscatteringtools/calib/masking.py

@@ -511,6 +511,9 @@ class MaskMaker:
         q_map = compute_q_map(J4M.x, J4M.y, x0, y0, z0, tx, ty, keV, z_off)
         q_bins = np.linspace(np.nanmin(q_map[~np.isnan(sample_avg_masked)]), np.nanmax(q_map[~np.isnan(sample_avg_masked)]), n_q_bins)
 
+        # Per-ring histograms and chosen bounds, for the waterfall summary plot
+        ring_records = []
+
         for q_idx, q_lo in tqdm(enumerate(q_bins[:-1]), total=len(q_bins) - 1):
             q_hi = q_bins[q_idx + 1]
             ring_sel = (q_map >= q_lo) & (q_map < q_hi)
@@ -534,6 +537,7 @@ class MaskMaker:
                         100 * (1 - kept_frac),
                     )
                 self.sample_mask &= ring_mask
+                chosen_lb, chosen_ub, is_manual = lower_bound, upper_bound, False
             else:
                 # Manual review required — show histogram and detector ring
                 ring_data = q_ring[ring_sel].flatten()
@@ -555,6 +559,7 @@ class MaskMaker:
                 ax_hist.set_xlabel('Intensity')
                 ax_hist.set_ylabel('Counts')
                 ax_hist.grid(True)
+                ax_hist.minorticks_on()
 
                 # Right: pcolormesh of the ring pixels on the detector
                 ring_display = np.where(ring_sel, sample_avg_corrected, np.nan)
@@ -587,10 +592,38 @@ class MaskMaker:
                 manual_mask = np.ones_like(q_ring, dtype=bool)
                 manual_mask[valid] = (q_ring[valid] >= user_lb) & (q_ring[valid] <= user_ub)
                 self.sample_mask &= manual_mask
+                chosen_lb, chosen_ub, is_manual = user_lb, user_ub, True
+
+            if plotting:
+                ring_vals = q_ring[ring_sel]
+                ring_vals = ring_vals[np.isfinite(ring_vals)]
+                if ring_vals.size > 0:
+                    # Normalise by the ring median so weak high-q rings are as
+                    # readable as the bright low-q ones on a shared axis
+                    median = np.median(ring_vals)
+                    scale = median if median > 0 else 1.0
+                    ring_vals = ring_vals / scale
+                    lb_n, ub_n = chosen_lb / scale, chosen_ub / scale
+                    p01, p05, p995, p999 = np.percentile(ring_vals, [0.1, 0.5, 99.5, 99.9])
+                    # Widen the range out to the bounds so the cut region is
+                    # visible, but stop at the 0.1/99.9 percentiles so a few
+                    # hot pixels (or a very loose manual bound) don't stretch the axis
+                    counts, edges = np.histogram(
+                        ring_vals,
+                        bins=200,
+                        range=(min(p05, max(lb_n, p01)), max(p995, min(ub_n, p999))),
+                    )
+                    cut_frac = np.mean((ring_vals < lb_n) | (ring_vals > ub_n))
+                    ring_records.append(
+                        dict(q_lo=q_lo, q_hi=q_hi, counts=counts, edges=edges,
+                             lb=lb_n, ub=ub_n, manual=is_manual, cut_frac=cut_frac)
+                    )
 
         self.sample_mask = self.sample_mask.astype(bool)
 
         if plotting:
+            self._plot_q_ring_waterfall(ring_records, n_std)
+
             sample_avg_all_masked = np.where(self.sample_mask, sample_avg_masked, np.nan)
 
             fig, axes = plt.subplots(1, 3, figsize=(18, 8))
@@ -602,6 +635,73 @@ class MaskMaker:
 
         print(f'Masked percentage from sample: {100 * self._masked_fraction(self.sample_mask):.2f}%')
 
+    def _plot_q_ring_waterfall(self, ring_records: list[dict], n_std: float) -> None:
+        """Waterfall of per-ring intensity histograms with the mask bounds shaded.
+
+        Intensities are divided by each ring's median, and each histogram is
+        normalised to unit peak height and offset vertically by its ring index.
+        The intensity range that survives the mask is shaded in steel-blue for
+        auto-accepted rings and red for rings whose bounds were entered
+        manually; the range that is cut is shaded grey.  The percentage of
+        ring pixels cut is printed to the right of each row.
+        """
+        if not ring_records:
+            return
+
+        n_rings = len(ring_records)
+        spacing = 0.5
+        colors = {False: 'steelblue', True: 'tab:red'}
+        cut_color = 'tab:gray'
+
+        fig, ax = plt.subplots(figsize=(18, max(8, 0.12 * n_rings)))
+        for i, rec in enumerate(ring_records):
+            offset = i * spacing
+            centers = 0.5 * (rec['edges'][:-1] + rec['edges'][1:])
+            peak = rec['counts'].max()
+            height = rec['counts'] / peak if peak > 0 else rec['counts'].astype(float)
+            kept = (centers >= rec['lb']) & (centers <= rec['ub'])
+            # Lower rings are drawn in front so their peaks occlude the rows above
+            base_z = 4 * (n_rings - i)
+            ax.fill_between(centers, offset, offset + height, color='white', zorder=base_z)
+            ax.fill_between(
+                centers, offset, offset + height, where=kept,
+                color=colors[rec['manual']], alpha=0.6, linewidth=0, zorder=base_z + 1,
+            )
+            # Cut tails are usually near-zero counts, so shade at least the full
+            # row height there to keep them visible
+            ax.fill_between(
+                centers, offset, offset + np.maximum(height, spacing), where=~kept,
+                color=cut_color, alpha=0.5, linewidth=0, zorder=base_z + 2,
+            )
+            ax.plot(centers, offset + height, color='k', lw=0.6, zorder=base_z + 3)
+            ax.text(
+                1.005, offset, f"{100 * rec['cut_frac']:.1f}%",
+                transform=ax.get_yaxis_transform(), fontsize=6, va='bottom',
+                color=colors[rec['manual']],
+            )
+        ax.text(1.005, 1.0, '% cut', transform=ax.transAxes, fontsize=8, va='bottom')
+
+        # Label a subset of rows with their q-centre
+        tick_step = max(1, n_rings // 15)
+        tick_idx = np.arange(0, n_rings, tick_step)
+        ax.set_yticks(tick_idx * spacing)
+        ax.set_yticklabels(
+            [f"{0.5 * (ring_records[i]['q_lo'] + ring_records[i]['q_hi']):.3f}" for i in tick_idx]
+        )
+        ax.set_ylim(-spacing, (n_rings - 1) * spacing + 1.5)
+        ax.set_xlabel('Intensity / ring median (Thompson-corrected)')
+        ax.set_ylabel(r'$q\;(\AA^{-1})$')
+        ax.set_title(f'Run {self.sample_run_number} Q-ring Histograms  (n_std={n_std})')
+        legend_elements = [
+            Patch(facecolor='steelblue', alpha=0.6, edgecolor='k', label='Auto bounds (kept)'),
+            Patch(facecolor='tab:red', alpha=0.6, edgecolor='k', label='Manual bounds (kept)'),
+            Patch(facecolor=cut_color, alpha=0.5, edgecolor='k', label='Cut by mask'),
+        ]
+        ax.legend(handles=legend_elements, loc='lower left', bbox_to_anchor=(0, 1.0), ncol=3, frameon=False)
+        ax.grid(True, axis='x', alpha=0.3)
+        plt.tight_layout()
+        plt.show()
+
     def diagnose_q_bins(
         self,
         n_std: float = 2,

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/src/xrayscatteringtools/io.py

@@ -155,7 +155,10 @@ def combineRuns(runNumbers, folders, keys_to_combine, keys_to_sum, keys_to_check
         if isinstance(archPVs, str):
             archPVs = [archPVs]
         archive = EpicsArchive()
-        unixTime = data_combined['unixTime']
+        for i, data in enumerate(data_array):
+            if 'unixTime' not in data:
+                raise KeyError(f"'unixTime' not found in run {runNumbers[i]}; it is required for archPVs.")
+        unixTime = np.concatenate([np.squeeze(d['unixTime']) for d in data_array])
         for pv in tqdm(archPVs, desc="Loading EPICS PVs"):
             pv_chunks = []
             for i, runNumber in enumerate(runNumbers):

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/src/xrayscatteringtools/theory/__init__.py

@@ -4,4 +4,7 @@ from .iam import iam_compton_spectrum, iam_inelastic_pattern_from_formula
 
 from .geometries import SF6__CCSD_T_DHK__aug_cc_pV5Z_DK
 
-from .patterns import SF6__CCSD__aug_cc_pVDZ, SF6__MP2__aug_cc_pVDZ, SF6__HF__aug_cc_pVDZ
+from .patterns import SF6__CCSD__aug_cc_pVDZ, SF6__MP2__aug_cc_pVDZ, SF6__HF__aug_cc_pVDZ
+from .patterns import SF6__HF__cc_pVTZ, SF6__CCSD_FC__aug_cc_pVDZ, SF6__CCSD_FC__aug_cc_pVTZ
+from .patterns import Ne__CCSD_X2C__aug_cc_pVDZ_DK, Ne__CCSD_X2C__aug_cc_pVTZ_DK, Ne__CCSD_X2C__aug_cc_pVQZ_DK
+from .patterns import NBD__HF__cc_pVTZ, NBD__CCSD_FC__aug_cc_pVDZ, QC__HF__cc_pVTZ, QC__CCSD_FC__aug_cc_pVDZ

xrayscatteringtools-1.3.0/src/xrayscatteringtools/theory/data/patterns/convert_thistle_to_h5.py

@@ -0,0 +1,67 @@
+import json
+import numpy as np
+import h5py
+
+# Converts thistle .csv exports into the .h5 format read by xrayscatteringtools.theory.patterns.
+# Expected .csv layout:
+#   line 1: "# <label>  q in 1/A  {json metadata}"
+#   line 2: "q (1/A),total,elastic,inelastic,hartree,exchange[,cumulant]"
+#   rest:   comma separated data, q in inverse angstroms
+# The total satisfies I_q = n_electrons + hartree + exchange + cumulant (cumulant is zero for HF).
+# Paths are relative to the current working directory.
+
+##################### User Set Parameters #####################
+# (csv file, molecule, method, basis set, n_electrons, notes)
+# h5 file naming convention is molecule__method__basisset.h5
+NBD_NOTES = "NBD is norbornadiene (bicyclo[2.2.1]hepta-2,5-diene, C7H8)."
+QC_NOTES = "QC is quadricyclane (tetracyclo[3.2.0.0^{2,7}.0^{4,6}]heptane, C7H8), the valence isomer of norbornadiene."
+FC_NOTES = "CCSD with frozen core electrons."
+conversions = [
+    ("nb_hf_cc-pvtz.csv", "NBD", "HF", "cc_pVTZ", 50, NBD_NOTES),
+    ("nb_ccsd_aug-cc-pvdz_fc.csv", "NBD", "CCSD_FC", "aug_cc_pVDZ", 50, f"{NBD_NOTES} {FC_NOTES}"),
+    ("qd_hf_cc-pvtz.csv", "QC", "HF", "cc_pVTZ", 50, QC_NOTES),
+    ("qd_ccsd_aug-cc-pvdz_fc.csv", "QC", "CCSD_FC", "aug_cc_pVDZ", 50, f"{QC_NOTES} {FC_NOTES}"),
+    ("sf6_hf_cc-pvtz.csv", "SF6", "HF", "cc_pVTZ", 70, ""),
+    ("sf6_ccsd_aug-cc-pvdz_fc.csv", "SF6", "CCSD_FC", "aug_cc_pVDZ", 70, FC_NOTES),
+    ("sf6_ccsd_aug-cc-pvtz_fc.csv", "SF6", "CCSD_FC", "aug_cc_pVTZ", 70, FC_NOTES),
+]
+##################### End User Set Parameters #####################
+
+# csv column -> h5 dataset
+column_map = {
+    "q (1/A)": "q",
+    "total": "I_q",
+    "elastic": "I_q_elastic",
+    "inelastic": "I_q_inelastic",
+    "hartree": "I_q_hartree",
+    "exchange": "I_q_exchange",
+    "cumulant": "I_q_cumulant",
+}
+
+for csv_file, molecule, method, basis_set, n_electrons, notes in conversions:
+    with open(csv_file) as f:
+        header = f.readline()
+        columns = f.readline().strip().split(",")
+    metadata = json.loads(header[header.index("{"):])
+    if metadata["q_unit"] != "1/A":
+        raise ValueError(f"{csv_file}: expected q in 1/A, got {metadata['q_unit']}")
+    data = np.loadtxt(csv_file, delimiter=",", skiprows=2)
+    datasets = {column_map[c]: data[:, i] for i, c in enumerate(columns)}
+    # Forward scattering is n_electrons**2, catches a wrong electron count
+    if not np.isclose(datasets["I_q"][0], n_electrons**2, rtol=1e-6) or datasets["q"][0] != 0:
+        raise ValueError(f"{csv_file}: I(q=0) = {datasets['I_q'][0]}, expected {n_electrons**2}")
+
+    h5_filename = f"{molecule}__{method}__{basis_set}.h5"
+    with h5py.File(h5_filename, "w") as f:
+        for name, values in datasets.items():
+            f.create_dataset(name, data=values)
+        # Add metadata as attributes
+        f.attrs["molecule"] = molecule
+        f.attrs["method"] = method
+        f.attrs["basis_set"] = basis_set
+        f.attrs["n_electrons"] = n_electrons
+        f.attrs["source"] = f"{metadata['from']['source']} via thistle {metadata['thistle']} ({metadata['kind']}, computed {metadata['created']})"
+        f.attrs["metadata"] = json.dumps(metadata)
+        if notes:
+            f.attrs["notes"] = notes
+    print(f"{csv_file} -> {h5_filename}")

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/src/xrayscatteringtools/theory/patterns.py

@@ -10,7 +10,14 @@ __all__ = [
     'SF6__HF__aug_cc_pVDZ',
     'Ne__CCSD_X2C__aug_cc_pVDZ_DK',
     'Ne__CCSD_X2C__aug_cc_pVTZ_DK',
-    'Ne__CCSD_X2C__aug_cc_pVQZ_DK'
+    'Ne__CCSD_X2C__aug_cc_pVQZ_DK',
+    'SF6__HF__cc_pVTZ',
+    'SF6__CCSD_FC__aug_cc_pVDZ',
+    'SF6__CCSD_FC__aug_cc_pVTZ',
+    'NBD__HF__cc_pVTZ',
+    'NBD__CCSD_FC__aug_cc_pVDZ',
+    'QC__HF__cc_pVTZ',
+    'QC__CCSD_FC__aug_cc_pVDZ',
     ]
 def __dir__():
     # Tab completion for IPython
@@ -19,6 +26,17 @@ def __dir__():
 
 _data_path = pathlib.Path(__file__).parent / "data/patterns"
 
+# Optional I_q components a pattern file may carry, with their docstring descriptions.
+_COMPONENTS = {
+    "I_q_elastic": "Elastic scattering intensity values corresponding to `q`.",
+    "I_q_inelastic": "Inelastic scattering intensity values corresponding to `q`.",
+    "I_q_hartree": "Hartree (direct) part of the two-electron term, built from the one-electron density alone. Equal to `I_q_elastic`.",
+    "I_q_exchange": "Exchange part of the two-electron term.",
+    "I_q_cumulant": "Cumulant (electron correlation) part of the two-electron term. Absent for HF, where it is zero.",
+}
+# Provenance for files made before the 'source' attribute existed
+_DEFAULT_SOURCE = "Molpro & PyXSCAT Library. https://github.com/AMC-dyn/PyXSCAT"
+
 def __getattr__(name):
     if name in __all__:
         # Load from HDF5 only when first accessed
@@ -41,7 +59,7 @@ def _make_default_obj(f):
     -------
     obj : SimpleNamespace
         A SimpleNamespace object with attributes: q, I_q, molecule, method, basis_set, n_electrons,
-        and optionally I_q_elastic and I_q_inelastic if present in the file.
+        and optionally any of the I_q components in _COMPONENTS, notes, source, and metadata if present in the file.
     """
 
     attrs = dict(
@@ -52,22 +70,22 @@ def _make_default_obj(f):
         basis_set=f.attrs["basis_set"],
         n_electrons=f.attrs["n_electrons"],
     )
-    if "I_q_elastic" in f:
-        attrs["I_q_elastic"] = f["I_q_elastic"][:]
-    if "I_q_inelastic" in f:
-        attrs["I_q_inelastic"] = f["I_q_inelastic"][:]
-    if "notes" in f.attrs:
-        attrs["notes"] = f.attrs["notes"]
+    for name in _COMPONENTS:
+        if name in f:
+            attrs[name] = f[name][:]
+    for name in ("notes", "source", "metadata"):
+        if name in f.attrs:
+            attrs[name] = f.attrs[name]
     return SimpleNamespace(**attrs)
 
 def _make_default_docstring(obj):
     """
-    Generate a default docstring for a data object if created by tests\\convert_ab_initio_to_h5.py
+    Generate a default docstring for a data object if created by data\\patterns\\convert_ab_initio_to_h5.py or data\\patterns\\convert_thistle_to_h5.py
 
     Parameters
     ----------
     obj : SimpleNamespace
-        The data object with attributes: q, I_q, I_q_elastic, I_q_inelastic, molecule, method, basis_set, n_electrons.
+        The data object with attributes: q, I_q, molecule, method, basis_set, n_electrons, and any optional attributes from _make_default_obj.
 
     Returns
     -------
@@ -75,17 +93,17 @@ def _make_default_docstring(obj):
         The generated docstring.
     """
 
-    elastic_doc = ""
-    if hasattr(obj, "I_q_elastic"):
-        elastic_doc = f"""    I_q_elastic : ndarray of shape ({len(obj.I_q_elastic)},)
-        Elastic scattering intensity values corresponding to `q`.
-"""
-    inelastic_doc = ""
-    if hasattr(obj, "I_q_inelastic"):
-        inelastic_doc = f"""    I_q_inelastic : ndarray of shape ({len(obj.I_q_inelastic)},)
-        Inelastic scattering intensity values corresponding to `q`.
+    components_doc = ""
+    for name, description in _COMPONENTS.items():
+        if hasattr(obj, name):
+            components_doc += f"""    {name} : ndarray of shape ({len(getattr(obj, name))},)
+        {description}
 """
 
+    decomposition_doc = ""
+    if hasattr(obj, "I_q_hartree"):
+        decomposition_doc = "I_q = n_electrons + I_q_hartree + I_q_exchange + I_q_cumulant, and I_q = I_q_elastic + I_q_inelastic."
+
     notes_doc = ""
     if hasattr(obj, "notes"):
         notes_doc = obj.notes
@@ -99,8 +117,8 @@ def _make_default_docstring(obj):
         Momentum transfer values (q) in inverse angstroms. Ranges from {obj.q[0]} to {obj.q[-1]} Å⁻¹. ({invAngstroms2au(obj.q[0])} to {invAngstroms2au(obj.q[-1])} a.u.).
     I_q : ndarray of shape ({len(obj.I_q)},)
         Total scattering intensity values corresponding to `q`.
-{elastic_doc}{inelastic_doc}    molecule : str
-        The molecular formula of the species.
+{components_doc}    molecule : str
+        The molecular formula, or an abbreviation for isomers (e.g. NBD, QC).
     method : str
         The method used for the calculation.
     basis_set : str
@@ -110,8 +128,9 @@ def _make_default_docstring(obj):
 
     Notes
     -----
-    Calculated using Molpro & PyXSCAT Library. https://github.com/AMC-dyn/PyXSCAT
+    Calculated using {getattr(obj, "source", _DEFAULT_SOURCE)}
     Inverse angstroms to atomic units conversion factor used: {au2invAngstroms(1.0)} Å⁻¹/a.u.
+    {decomposition_doc}
     {notes_doc}
     """
     

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/src/xrayscatteringtools/theory/patterns.pyi

@@ -9,11 +9,16 @@ class _PatternData(SimpleNamespace):
     I_q: any  # ndarray
     I_q_elastic: Optional[any]  # ndarray, may not be present
     I_q_inelastic: Optional[any]  # ndarray, may not be present
+    I_q_hartree: Optional[any]  # ndarray, may not be present
+    I_q_exchange: Optional[any]  # ndarray, may not be present
+    I_q_cumulant: Optional[any]  # ndarray, may not be present
     molecule: str
     method: str
     basis_set: str
     n_electrons: int
     notes: Optional[any]
+    source: Optional[str]
+    metadata: Optional[str]  # JSON string
 
 SF6__CCSD__aug_cc_pVDZ: _PatternData
 SF6__MP2__aug_cc_pVDZ: _PatternData
@@ -21,3 +26,10 @@ SF6__HF__aug_cc_pVDZ: _PatternData
 Ne__CCSD_X2C__aug_cc_pVDZ_DK: _PatternData
 Ne__CCSD_X2C__aug_cc_pVTZ_DK: _PatternData
 Ne__CCSD_X2C__aug_cc_pVQZ_DK: _PatternData
+SF6__HF__cc_pVTZ: _PatternData
+SF6__CCSD_FC__aug_cc_pVDZ: _PatternData
+SF6__CCSD_FC__aug_cc_pVTZ: _PatternData
+NBD__HF__cc_pVTZ: _PatternData
+NBD__CCSD_FC__aug_cc_pVDZ: _PatternData
+QC__HF__cc_pVTZ: _PatternData
+QC__CCSD_FC__aug_cc_pVDZ: _PatternData

{xrayscatteringtools-1.1.0 → xrayscatteringtools-1.3.0}/tests/test_patterns.py

@@ -83,6 +83,13 @@ class TestDir:
         assert "SF6__CCSD__aug_cc_pVDZ" in result
 
 
+class TestTheoryExports:
+    @pytest.mark.parametrize("name", PATTERNS_ALL)
+    def test_pattern_exported_from_theory(self, name):
+        from xrayscatteringtools import theory
+        assert hasattr(theory, name), f"add {name} to theory/__init__.py"
+
+
 # ── _make_default_obj ──────────────────────────────────────────────────
 
 
@@ -137,6 +144,20 @@ class TestMakeDefaultObj:
         assert hasattr(obj, "I_q")
         assert not hasattr(obj, "I_q_elastic")
         assert not hasattr(obj, "I_q_inelastic")
+        assert not hasattr(obj, "I_q_hartree")
+        assert not hasattr(obj, "source")
+
+    def test_loads_decomposition_and_source(self, h5_with_elastic):
+        with h5py.File(h5_with_elastic, "a") as f:
+            f.create_dataset("I_q_hartree", data=np.ones(50) * 7)
+            f.create_dataset("I_q_exchange", data=np.ones(50) * -7)
+            f.attrs["source"] = "PySCF RHF via thistle"
+        with h5py.File(h5_with_elastic, "r") as f:
+            obj = _make_default_obj(f)
+        np.testing.assert_allclose(obj.I_q_hartree, 7)
+        np.testing.assert_allclose(obj.I_q_exchange, -7)
+        assert not hasattr(obj, "I_q_cumulant")
+        assert obj.source == "PySCF RHF via thistle"
 
 
 # ── _make_default_docstring ────────────────────────────────────────────
@@ -191,6 +212,26 @@ class TestMakeDefaultDocstring:
         # Should contain the a.u. conversion factor
         assert str(au2invAngstroms(1.0)) in doc
 
+    def test_docstring_source(self):
+        obj = SimpleNamespace(
+            q=np.linspace(0.5, 8.0, 30),
+            I_q=np.ones(30),
+            molecule="NBD",
+            method="HF",
+            basis_set="cc_pVTZ",
+            n_electrons=50,
+        )
+        assert "Molpro" in _make_default_docstring(obj)
+        obj.source = "PySCF RHF via thistle"
+        obj.I_q_hartree = np.ones(30)
+        obj.I_q_exchange = np.ones(30)
+        doc = _make_default_docstring(obj)
+        assert "PySCF RHF via thistle" in doc
+        assert "Molpro" not in doc
+        assert "I_q_hartree" in doc
+        assert "I_q_exchange" in doc
+        assert "I_q_cumulant" not in doc.split("Notes")[0]
+
 
 # ── Consistency between shipped patterns ───────────────────────────────
 
@@ -209,6 +250,25 @@ class TestShippedPatternConsistency:
             err_msg=f"elastic + inelastic != total for {name}",
         )
 
+    @pytest.mark.parametrize("name", PATTERNS_ALL)
+    def test_two_electron_decomposition_equals_total(self, name):
+        obj = getattr(patterns, name)
+        if not hasattr(obj, "I_q_hartree"):
+            pytest.skip(f"{name} does not have the hartree/exchange/cumulant decomposition")
+        cumulant = getattr(obj, "I_q_cumulant", 0)
+        np.testing.assert_allclose(
+            obj.I_q, obj.n_electrons + obj.I_q_hartree + obj.I_q_exchange + cumulant,
+            rtol=1e-9,
+            err_msg=f"n_electrons + hartree + exchange + cumulant != total for {name}",
+        )
+
+    @pytest.mark.parametrize("name", PATTERNS_ALL)
+    def test_forward_scattering_is_n_electrons_squared(self, name):
+        obj = getattr(patterns, name)
+        if obj.q[0] > 1e-6:
+            pytest.skip(f"{name} does not start at q = 0")
+        np.testing.assert_allclose(obj.I_q[0], obj.n_electrons**2, rtol=1e-6)
+
     @pytest.mark.parametrize("name", PATTERNS_ALL)
     def test_n_electrons_positive(self, name):
         obj = getattr(patterns, name)