finalcif 161__tar.gz → 162__tar.gz

{finalcif-161 → finalcif-162}/AGENTS.md

@@ -16,15 +16,15 @@
 - **Entry Point:** The application starts from `finalcif/finalcif_start.py` (registered as `finalcif` in `pyproject.toml`).
 - **Main Window:** `AppWindow` (QMainWindow) in `finalcif/appwindow.py` is the orchestrator wiring all subsystems; UI defined in `finalcif/gui/finalcif_gui_ui.ui`.
 - **Subpackage Map:**
-  - `finalcif/cif/` — CIF I/O via `gemmi.cif` wrapped in `CifContainer` (`cif_file_io.py`); dict definitions (core/powder/modulation/twin/restraints); subpackages `checkcif/` (IUCr CheckCIF HTML/PDF parsing) and `cod/` (COD/CCDC deposition: `deposit.py`, `upload.py`, `doi.py`, `website_parser.py`).
+  - `finalcif/cif/` — CIF I/O via `gemmi.cif` wrapped in `CifContainer` (`cif_file_io.py`); dict definitions (core/powder/modulation/twin/restraints); subpackages `checkcif/` (IUCr CheckCIF HTML/PDF parsing) and `cod/` (COD/CCDC deposition: `deposit.py`, `deposit_check.py`, `deposition_list.py`, `upload.py`, `doi.py`, `website_parser.py`).
   - `finalcif/ciforder/` — CIF key ordering dialog.
   - `finalcif/datafiles/` — raw instrument data importers: Bruker (`bruker_data.py`, `bruker_frame.py`), SAINT, SADABS, SHELX `.lst` (`shelx_lst.py`), `.p4p`, CCDC deposition mail parser (`ccdc_mail.py`).
   - `finalcif/displaymol/` — 3D molecular display (`vtk_molecule.py`) is not used; 2D rendering is provided by the external `fastmolwidget` package (custom widget in `finalcif_gui_ui.ui`).
   - `finalcif/equip_property/` — Equipment/Properties/AuthorLoops template tables (`equipment.py`, `properties.py`, `author_loop_templates.py`).
   - `finalcif/gui/` — Qt widgets; `.ui` files compiled to sibling `*_ui.py` modules.
-  - `finalcif/report/` — DOCX report generation via `docxtpl` (`DocxTemplate`, `RichText`, `InlineImage`) in `templated_report.py`; also archive reports, tables, references, symmetry.
+  - `finalcif/report/` — DOCX report generation via `docxtpl` (`DocxTemplate`, `RichText`, `InlineImage`) in `templated_report.py`; also archive reports (`archive_report.py`), tables, references, symmetry. The `report/gui/` subpackage hosts the standalone report-options window (`mainwindow.py` + `mainwindow.ui`).
   - `finalcif/template/` — Report template infrastructure (`ReportTemplates`).
-  - `finalcif/tools/` — cross-cutting helpers: `platon.py` (`PlatonRunner`), `shred.py`, `space_groups.py`, `sumformula.py`, `settings.py` (`FinalCifSettings` QSettings wrapper), `download.py`, `pupdate.py` (auto-updater), `statusbar.py`, `chemparse.py`, `dsrmath.py`.
+  - `finalcif/tools/` — cross-cutting helpers: `platon.py` (`PlatonRunner`), `shred.py`, `space_groups.py` / `spgr_format.py`, `sumformula.py`, `settings.py` (`FinalCifSettings` QSettings wrapper), `options.py`, `download.py`, `pupdate.py` (auto-updater), `statusbar.py`, `chemparse.py`, `dsrmath.py`, `z_from_packing.py`, `misc.py`.
 - **External Tool Integration:**
   - Offline CheckCIF uses PLATON via `finalcif/tools/platon.py`; executable resolution checks bundled `platon/platon_special.exe`, then `C:\pwt\platon.exe` (Windows), then `platon` on `PATH`.
   - Online CheckCIF (IUCr) via HTTP in `finalcif/cif/checkcif/checkcif.py`.
@@ -32,6 +32,7 @@
   - DOI / CrossRef lookups via `crossrefapi` (see `finalcif/cif/cod/doi.py`).
   - SHELX parsing via the external `shelxfile` package (used in `report/templated_report.py`); in-tree `.lst` parser in `datafiles/shelx_lst.py`.
 - **CIF Parsing:** Standardized on `gemmi` (>=0.7.5); `gemmi.set_leak_warnings(False)` is set at startup.
+- **Key Third-Party Runtime Deps:** `qtpy` + `pyside6` / `pyside6-addons`, `gemmi`, `docxtpl[subdoc]`, `python-docx`, `shelxfile`, `fastmolwidget`, `crossrefapi`, `QtAwesome` (icon fonts), `pyenchant` (spell-check), `html2text`, `lxml`, `numpy<2.4`, `chardet` / `charset-normalizer`, `requests`/`urllib3`, `packaging`, `pefile` (see `pyproject.toml`).
 
 ## Conventions
 - **UI Files:** Edit `.ui` files in Qt Designer (`scripts/designer.py`), then regenerate via `python scripts/compile_ui_files.py`. Never hand-edit generated `*_ui.py`.
@@ -48,8 +49,9 @@
   - *Network-Gated Tests:* set `NO_NETWORK=1` to skip network-dependent checks (CheckCIF/DOI/deposit/PLATON; see `tests/test_checkcif.py`, `tests/test_doi.py`).
   - *Helpers:* shared base class `AppWindowTestCase` and `processevents()` in `tests/helpers.py`; `get_platon_exe()` resolves `C:\pwt\platon.exe` on Windows or `which('platon')`. Fixtures live in `tests/examples/`, `tests/statics/`, `tests/checkcif_results/`, and top-level `test-data/`.
 - **Linting:** 
-  - *Command (local):* `ruff check .` — configured via `.ruff.toml` (line-length 120, target py312).
-  - *CI Lint:* GitHub Actions runs `flake8` in `.github/workflows/python_tests.yml` (ruff is not invoked in CI).
+  - *Command (local):* `ruff check .` — configured via `.ruff.toml` (line-length 120, target py312, rule set `E,F,B,UP,ANN,A,C4,DTZ,NPY,PL,FURB,RUF`).
+  - *CI Lint:* GitHub Actions runs `flake8` in `.github/workflows/python_tests.yml` (installed on the fly via `uv add flake8 pytest`; ruff is not invoked in CI).
+- **Type Checking:** The dev dependency group includes `ty` and `pyside6-stubs`; `[tool.pyrefly]` in `pyproject.toml` configures Pyrefly project includes/excludes. There is no CI gate for type checks.
 - **UI Compilation:** 
   - *Command:* `python scripts/compile_ui_files.py` (discovers `.ui` files, compiles them, and hot-fixes imports to `qtpy`).
 - **Build/Releases:**

{finalcif-161 → finalcif-162}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finalcif
-Version: 161
+Version: 162
 Summary: CIF file editor
 Project-URL: Homepage, https://dkratzert.de/finalcif.html
 Project-URL: Bug Tracker, https://github.com/dkratzert/FinalCif/issues
@@ -17,15 +17,15 @@ Requires-Dist: chardet
 Requires-Dist: charset-normalizer
 Requires-Dist: crossrefapi
 Requires-Dist: docxtpl[subdoc]>=0.20.2
-Requires-Dist: fastmolwidget>=0.9.5
+Requires-Dist: fastmolwidget>=0.9.7
 Requires-Dist: gemmi>=0.7.5
 Requires-Dist: hatchling
 Requires-Dist: html2text
 Requires-Dist: lxml==6.1.0
 Requires-Dist: numpy<2.4,>=2.3.5
-Requires-Dist: packaging
+Requires-Dist: packaging==26.2
 Requires-Dist: pefile
-Requires-Dist: pybind11
+Requires-Dist: pybind11==3.0.4
 Requires-Dist: pyenchant
 Requires-Dist: pyside6
 Requires-Dist: pyside6-addons
@@ -34,8 +34,8 @@ Requires-Dist: qtawesome
 Requires-Dist: qtpy
 Requires-Dist: requests
 Requires-Dist: shelxfile
-Requires-Dist: urllib3
-Requires-Dist: wheel
+Requires-Dist: urllib3==2.7.0
+Requires-Dist: wheel==0.47.0
 Description-Content-Type: text/markdown
 
 ![Latest Release](https://img.shields.io/github/v/tag/dkratzert/FinalCif?label=Release)

finalcif-162/finalcif/__init__.py

@@ -0,0 +1,3 @@
+
+VERSION = 162
+__version__ = VERSION

{finalcif-161 → finalcif-162}/finalcif/appwindow.py

@@ -75,6 +75,7 @@ from finalcif.tools.platon import PlatonRunner
 from finalcif.tools.settings import FinalCifSettings
 from finalcif.tools.shred import ShredCIF
 from finalcif.tools.space_groups import SpaceGroups
+from finalcif.tools.z_from_packing import count_z_and_zprime, ZResult
 from finalcif.tools.spgr_format import spgrps
 from finalcif.tools.statusbar import StatusBar
 from finalcif.tools.sumformula import formula_str_to_dict, sum_formula_to_html
@@ -88,6 +89,42 @@ with suppress(ImportError):
     import qtawesome as qta
 
 
+class _ZEstimatorThread(QtCore.QThread):
+    """Background thread that computes Z and Z′ without blocking the UI.
+
+    Emits ``result`` (a :class:`ZResult`) on success, or ``failed`` (with an
+    empty :class:`ZResult`) on any exception so the caller can always clear
+    the label consistently.
+    """
+
+    result = QtCore.Signal(object)  # emits a ZResult
+
+    def __init__(
+            self,
+            atoms_fract: list,
+            symmops: list[str],
+            cell: tuple[float, ...],
+            formula_sum: str | None = None,
+            parent: QtCore.QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+        # Take immutable snapshots so the background thread never touches CIF state.
+        self._atoms_fract = list(atoms_fract)
+        self._symmops = list(symmops)
+        self._cell = tuple(cell)
+        self._formula_sum = formula_sum
+
+    def run(self) -> None:
+        try:
+            res = count_z_and_zprime(
+                self._atoms_fract, self._symmops, self._cell,
+                formula_sum=self._formula_sum,
+            )
+        except Exception:
+            res = None
+        self.result.emit(res)
+
+
 class AppWindow(QMainWindow):
 
     def __init__(self, file: Path | None = None):
@@ -96,6 +133,7 @@ class AppWindow(QMainWindow):
         self.ckf = None
         self.thread_version = None
         self.worker = None
+        self._z_thread: _ZEstimatorThread | None = None
         self.setAttribute(QtCore.Qt.WidgetAttribute.WA_DeleteOnClose)
         # This prevents some things to happen during unit tests:
         # Open of target dir of shred cif,
@@ -1766,6 +1804,7 @@ class AppWindow(QMainWindow):
             if self.ui.MainStackedWidget.on_info_page():
                 self.show_residuals()
                 self.redraw_molecule()
+            self._update_z_label()
             t = QtCore.QTimer(self)
             t.singleShot(1000, self.check_cecksums)
 
@@ -1987,6 +2026,79 @@ class AppWindow(QMainWindow):
                 self.ui.render_widget.grow_molecule(atom_tuples,
                                                     cell=self.cif.cell[:6])
 
+    def _update_z_label(self) -> None:
+        """Start a background computation of Z and Z′ and show a placeholder.
+
+        Cancels any in-flight worker before starting a new one so that opening
+        files in rapid succession never delivers a stale result to the label.
+
+        Uses the full symmetry expansion of the asymmetric unit to fill the unit
+        cell, then counts discrete connected molecular graphs. Disorder is handled
+        by retaining only the primary component of each disordered site so that
+        each atomic position is populated exactly once.
+
+        Z′ = Z / Z_sg indicates the number of formula units per asymmetric unit:
+        * Z′ = 1  → one molecule per ASU (most common, high confidence).
+        * Z′ = ½  → molecule on 2-fold special position (medium confidence).
+        * Z′ = ⅓  → molecule on 3-fold axis, trigonal/hexagonal (medium confidence).
+        * Z′ = ¼  → molecule on 4-fold axis, tetragonal (medium confidence).
+        * Z′ = ⅙  → molecule on 6-fold axis, hexagonal (medium confidence).
+        * Z′ not a multiple of 1/n (n∈{1,2,3,4,6}) → estimate likely unreliable (low).
+        """
+        # Abort any previous worker still running.
+        if self._z_thread is not None and self._z_thread.isRunning():
+            self._z_thread.result.disconnect()
+            self._z_thread.quit()
+            self._z_thread.wait(50)  # give it 50 ms to stop cleanly
+            self._z_thread = None
+
+        try:
+            atoms = list(self.cif.atoms_fract)
+            symmops = list(self.cif.symmops)
+            cell = tuple(self.cif.cell[:6])
+            formula_sum = self.cif['_chemical_formula_sum'] or None
+        except Exception:
+            self.ui.zEstimateLabel.setText('?')
+            self.ui.zEstimateLabel2.setText('?')
+            return
+
+        self.ui.zEstimateLabel.setText('Z = ')
+        self.ui.zEstimateLabel2.setText('Z = ')
+        self.ui.zEstimateLabel.setToolTip('')
+        self.ui.zEstimateLabel2.setToolTip('')
+
+        self._z_thread = _ZEstimatorThread(atoms, symmops, cell, formula_sum, parent=self)
+        self._z_thread.result.connect(self._on_z_result)
+        self._z_thread.start()
+
+    def _on_z_result(self, result: ZResult | None) -> None:
+        """Receive the computed :class:`ZResult` from the background thread and update the label."""
+        if result is None:
+            self.ui.zEstimateLabel.setText('?')
+            self.ui.zEstimateLabel2.setText('?')
+            return
+        confidence_icon = {'high': '✓', 'medium': '~', 'low': '?'}[result.confidence]
+        self.ui.zEstimateLabel.setText(f"Z = {result.z}  Z′ = {result.z_prime:.3g}  {confidence_icon}")
+        self.ui.zEstimateLabel2.setText(f"Z = {result.z}  Z′ = {result.z_prime:.3g}  {confidence_icon}")
+        tip_lines = [
+            f"Estimated Z = {result.z} formula units per unit cell",
+            f"Z′ = {result.z_prime:.4f}  (formula units per asymmetric unit)",
+            f"Z_sg = {result.z_sg}  (general positions in space group)",
+            "",
+        ]
+        if result.confidence == 'high':
+            tip_lines.append("Confidence: HIGH — Z′ is a positive integer.")
+        elif result.confidence == 'medium':
+            tip_lines.append("Confidence: MEDIUM — Z′ is a non-integer crystallographic")
+            tip_lines.append("fraction (½, ⅓, ¼, or ⅙), suggesting the molecule sits")
+            tip_lines.append("on a special position; the true Z may be higher.")
+        else:
+            tip_lines.append("Confidence: LOW — Z′ is not a multiple of ½.")
+            tip_lines.append("The bond-graph estimate is likely incorrect")
+            tip_lines.append("(common for polymers, frameworks, or salts).")
+        self.ui.zEstimateLabel.setToolTip('\n'.join(tip_lines))
+        self.ui.zEstimateLabel2.setToolTip('\n'.join(tip_lines))
+
     def _calc_grown_atoms(self):
         """Helper to generate the symmetry expanded atoms without drawing them."""
         atoms_fract = tuple(self.cif.atoms_fract)

{finalcif-161 → finalcif-162}/finalcif/cif/cif_file_io.py

@@ -70,8 +70,12 @@ class CifContainer:
                 raise GemmiError(e)
         # Starting with first block, but can use others with subsequent self._onload():
         self.block: gemmi.cif.Block = self.doc[0]
-        self.shx = Shelxfile(verbose=True)
-        self.shx.read_string(self.res_file_data[1:-1])
+        try:
+            self.shx = Shelxfile(verbose=True)
+            self.shx.read_string(self.res_file_data[1:-1])
+        except Exception:
+            print('Shelx file parsing failed.')
+            self.shx = None
         self._on_load()
         self.order = []
         self.essential_keys = []