xrayscatteringtools 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xrayscatteringtools
-Version: 1.1.0
+Version: 1.2.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.2.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.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "xrayscatteringtools"
-version = "1.1.0"
+version = "1.2.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.2.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.2.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.2.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.2.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.2.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)