quantui 0.5.2__tar.gz → 0.6.1__tar.gz

{quantui-0.5.2 → quantui-0.6.1}/CHANGELOG.md

@@ -7,6 +7,101 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-08-05
+
+### Fixed
+
+- **Reorganization-energy results now survive History.** Reloading one from
+  History showed the calculation's headline numbers as missing — λ, the
+  four-point energies and the per-channel breakdown were never written to disk,
+  so there was nothing to redisplay. Both the live and History result cards now
+  render from the same saved data, so anything visible during a run is visible
+  after reloading it.
+  **Results saved before this cannot be recovered** — λ requires two geometry
+  optimizations and four SCF energies. Those results now say so on the card and
+  tell you to re-run, rather than appearing silently incomplete.
+- **3-D backgrounds follow the theme** in the new geometry viewers, matching the
+  fix applied to the other viewers in 0.6.0.
+
+### Added
+
+- **A Geometries panel** for reorganization energy, on the Analysis tab — which
+  previously showed nothing at all for this calculation type. Step through the
+  distinct geometries behind the four energies, or overlay two of them with
+  arrows marking how each atom moved. The arrows can be scaled ×1–×10 for small
+  relaxations; the structures always show true computed positions.
+- **Geometry relaxation on the result card** — RMSD and the largest single-atom
+  shift between the neutral and ion geometries, which is what λ physically
+  measures.
+- **Compare λ across saved results.** Selecting several reorganization-energy
+  runs in the Compare tab now shows a λ table with a column per channel, for
+  screening candidates by how much they reorganize.
+
+### Changed
+
+- The NCShare GPU diagnostic notebook now reports the **CPU affinity mask**
+  alongside the core count, and states plainly when CPU timings cannot be
+  trusted. A job can be granted 6 cores while still *seeing* 192; whether that
+  matters depends on how the scheduler constrains it, and the core count alone
+  cannot distinguish the two cases.
+- `apptainer/README.md` records the first verified H200 run — driver, compute
+  capability, partition, and the measured CPU/GPU crossover.
+
+## [0.6.0] - 2026-08-04
+
+### Added
+
+- **Save orbital isosurfaces as images.** A **Save PNG** button sits under the
+  viewer and captures exactly what you are looking at, camera and all. Options
+  for the filename, the DPI written into the file (72–600; this sets the
+  *print* size, not the pixel count), and a transparent background for dropping
+  a figure onto a slide — the transparency applies only to the saved file, so
+  the viewer on screen is unchanged.
+- **Tunable isosurface resolution** — Coarse/Medium/Fine/Very fine grids,
+  remembered between launches.
+- **Live isosurface controls**: isovalue, opacity and a colour-scheme dropdown
+  (GaussView orange/blue, Avogadro/Jmol red/blue, journal yellow/blue, and
+  more). All three update the existing viewer without recomputing anything, so
+  the orientation you rotated into is preserved.
+- **The isovalue is explained in chemical terms.** Beside the slider, QuantUI
+  reports what fraction of the orbital's density the surface actually encloses
+  — "encloses 98.4% of the density" — because an amplitude threshold is rarely
+  the question anyone has.
+- **A Cancel button** for isosurface generation. The underlying PySCF call
+  cannot be interrupted, so the computation finishes in the background, but its
+  result is discarded and the controls come back immediately.
+- **The molecule is shown before you generate anything**, so the panel is never
+  empty — and you can orient the structure first, since that view carries into
+  the isosurface.
+
+### Changed
+
+- **Orbital isosurfaces are py3Dmol only.** The Plotly renderer is no longer
+  selectable for them: it downsamples the volume by construction, and it cannot
+  carry the new image export. Plotly remains available for the molecule viewers.
+- **Exported animations now match what you saw.** Vibrational modes and
+  optimization trajectories both export from py3Dmol — the renderer that drew
+  them on screen — instead of being rebuilt in Plotly. Exported files are also
+  now complete HTML documents declaring UTF-8, so labels no longer risk
+  mojibake when opened from disk.
+- **For geometry optimizations, the Orbital Isosurface panel opens by default**
+  on the Analysis tab.
+- **Isosurface viewers are framed** like the other 3-D viewers, and generating a
+  new one dims the current one in place rather than collapsing the panel.
+
+### Fixed
+
+- **3-D backgrounds follow the theme.** The isosurface, vibrational and
+  trajectory viewers, and the Analysis-tab molecule viewer, kept their old
+  background when switching Light/Dark until something happened to redraw them.
+- **The page no longer jumps** when generating an isosurface.
+- **Isosurface changes now apply correctly.** Adjusting the isovalue, opacity or
+  colours previously layered a new surface on top of the old one, so raising the
+  isovalue appeared to do nothing, lowering opacity did nothing, and switching
+  palettes made the surface progressively brighter.
+- Very large orbital grids are dramatically lighter in the browser — the cube
+  data was being embedded three times per render.
+
 ## [0.5.2] - 2026-08-03
 
 ### Fixed
@@ -508,7 +603,9 @@ Initial public scaffolding of the QuantUI package: `quantui` package with
 `calculator.py`, basic notebook launcher, Apptainer container definition,
 MIT license, and project metadata.
 
-[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.2...HEAD
+[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.4.1...v0.5.0

{quantui-0.5.2/quantui.egg-info → quantui-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantui
-Version: 0.5.2
+Version: 0.6.1
 Summary: An open-source frontend for DFT and post-HF quantum chemistry with PySCF
 Author-email: Jonathan Schultz <nccu-schultz-lab@users.noreply.github.com>
 License: MIT License

{quantui-0.5.2 → quantui-0.6.1}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantui"
-version = "0.5.2"
+version = "0.6.1"
 description = "An open-source frontend for DFT and post-HF quantum chemistry with PySCF"
 readme = "README.md"
 requires-python = ">=3.9"

{quantui-0.5.2 → quantui-0.6.1}/quantui/__init__.py

@@ -7,7 +7,7 @@ Calculations run locally in the Jupyter session — no cluster or SLURM required
 PySCF requires Linux/macOS/WSL. Windows users should use the Apptainer container.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.6.1"
 
 import logging
 from typing import Any

{quantui-0.5.2 → quantui-0.6.1}/quantui/app.py

@@ -45,6 +45,9 @@ from quantui.app_analysis import (
 from quantui.app_analysis import (
     deactivate_all_ana_panels as _ana_deactivate_all_ana_panels,
 )
+from quantui.app_analysis import (
+    on_reorg_view_changed as _ana_on_reorg_view_changed,
+)
 from quantui.app_analysis import (
     pop_energies as _ana_pop_energies,
 )
@@ -69,6 +72,9 @@ from quantui.app_analysis import (
 from quantui.app_analysis import (
     pop_preopt_trajectory as _ana_pop_preopt_trajectory,
 )
+from quantui.app_analysis import (
+    pop_reorg_geometries as _ana_pop_reorg_geometries,
+)
 from quantui.app_analysis import (
     pop_uv_vis as _ana_pop_uv_vis,
 )
@@ -147,6 +153,9 @@ from quantui.app_exports import (
 from quantui.app_exports import (
     on_iso_export_cube as _exp_on_iso_export_cube,
 )
+from quantui.app_exports import (
+    on_orb_png_captured as _exp_on_orb_png_captured,
+)
 from quantui.app_formatters import (
     format_freq_result as _fmt_freq_result,
 )
@@ -333,6 +342,12 @@ from quantui.app_visualization import (
 from quantui.app_visualization import (
     on_ir_mode_changed as _viz_on_ir_mode_changed,
 )
+from quantui.app_visualization import (
+    on_iso_appearance_changed as _viz_on_iso_appearance_changed,
+)
+from quantui.app_visualization import (
+    on_iso_cancel as _viz_on_iso_cancel,
+)
 from quantui.app_visualization import (
     on_iso_generate as _viz_on_iso_generate,
 )
@@ -360,6 +375,9 @@ from quantui.app_visualization import (
 from quantui.app_visualization import (
     render_vib_mode as _viz_render_vib_mode,
 )
+from quantui.app_visualization import (
+    rerender_3d_scenes_for_theme as _viz_rerender_3d_scenes_for_theme,
+)
 from quantui.app_visualization import (
     show_ir_spectrum as _viz_show_ir_spectrum,
 )
@@ -1618,6 +1636,7 @@ class QuantUIApp:
         ("IR Spectrum", "_ir_accordion", "Frequency"),
         ("PES Scan", "_pes_scan_accordion", "PES Scan"),
         ("Isosurface", "_iso_accordion", "Single Point (Linux/WSL only)"),
+        ("Geometries", "_reorg_geom_accordion", "Reorganization Energy"),
         ("UV-Vis", "_tddft_accordion", "UV-Vis (TD-DFT)"),
         ("NMR", "_nmr_accordion", "NMR Shielding"),
     ]
@@ -1628,9 +1647,31 @@ class QuantUIApp:
             ("Isosurface", "_pop_isosurface", False),
         ],
         "geometry_opt": [
-            ("Trajectory", "_pop_geo_trajectory", True),
+            # ORDER MATTERS: the FIRST entry whose populator returns True and
+            # carries auto_select=True becomes the default panel (see the rules
+            # above). Isosurface therefore leads (requested 2026-08-04); an
+            # earlier attempt put it last, which did nothing because Trajectory
+            # had already claimed the selection.
+            #
+            # Trajectory keeps auto_select=True as the fallback: when a result
+            # has no orbital data, _pop_isosurface returns False, Isosurface
+            # never activates, and Trajectory becomes the default instead.
+            # ORDER IS LOAD-BEARING TWICE OVER.
+            #
+            # 1. Execution: _pop_energies calls show_orbital_diagram, which is
+            #    what populates _last_orb_mo_coeff / _mol_atom / _mol_basis —
+            #    the very state _pop_isosurface checks. Energies MUST run
+            #    first, or Isosurface reports "required data is missing" on a
+            #    result that has it. (Putting Isosurface first did exactly
+            #    that, 2026-08-04.)
+            # 2. Selection: the FIRST entry with auto_select=True that returns
+            #    True becomes the default panel. Energies is False, so
+            #    Isosurface is the first candidate and opens by default —
+            #    which is the request — while Trajectory keeps True as the
+            #    fallback for results with no orbital data.
             ("Energies", "_pop_energies", False),
-            ("Isosurface", "_pop_isosurface", False),
+            ("Isosurface", "_pop_isosurface", True),
+            ("Trajectory", "_pop_geo_trajectory", True),
         ],
         "frequency": [
             ("Vibrational", "_pop_vibrational", True),
@@ -1644,6 +1685,16 @@ class QuantUIApp:
         "nmr": [
             ("NMR", "_pop_nmr_shielding", True),
         ],
+        # reorganization_energy had NO entry at all until 2026-08-05, so the
+        # Analysis tab populated nothing for these runs — not a missing panel,
+        # no panels. Order matters twice over: the FIRST auto_select=True that
+        # returns True wins, AND _pop_energies loads the orbital state
+        # _pop_isosurface checks, so Energies must precede Isosurface.
+        "reorganization_energy": [
+            ("Energies", "_pop_energies", False),
+            ("Geometries", "_pop_reorg_geometries", True),
+            ("Isosurface", "_pop_isosurface", False),
+        ],
         "pes_scan": [
             ("PES Scan", "_pop_pes_plot", True),
             ("Trajectory", "_pop_pes_trajectory", False),
@@ -1659,6 +1710,9 @@ class QuantUIApp:
     def _pop_energies(self, ctx: _AnalysisContext) -> bool:
         return _ana_pop_energies(self, ctx)
 
+    def _pop_reorg_geometries(self, ctx: _AnalysisContext) -> bool:
+        return _ana_pop_reorg_geometries(self, ctx)
+
     def _pop_isosurface(self, ctx: _AnalysisContext) -> bool:
         return _ana_pop_isosurface(self, ctx)
 
@@ -1979,6 +2033,35 @@ class QuantUIApp:
         )
         # Cube + bundle exports
         self._iso_export_cube_btn.on_click(self._on_iso_export_cube)
+        self._iso_cancel_btn.on_click(self._safe_cb(self._on_iso_cancel))
+        # Reorg geometry views (REORG.3): both redraw from data already in
+        # memory, so they respond directly rather than behind an Apply button.
+        for _w in (
+            self._reorg_view_toggle,
+            self._reorg_overlay_pair,
+            self._reorg_exaggerate,
+        ):
+            _w.observe(self._safe_cb(self._on_reorg_view_changed), names="value")
+        # PNG capture arrives from the browser, so there is no button to bind
+        # here — the viewer's own Save-PNG button posts into this Textarea and
+        # ipywidgets syncs it back, firing this observer (ORBX.1).
+        self._orb_png_inbox.observe(
+            self._safe_cb(self._on_orb_png_captured), names="value"
+        )
+        # Persist the grid choice so it survives a relaunch (ORBX.2).
+        self._iso_resolution_dd.observe(
+            self._safe_cb(self._on_iso_resolution_changed), names="value"
+        )
+        # Appearance controls redraw from the cube on disk — no cubegen — so
+        # they can respond directly rather than behind an Apply button.
+        for _w in (
+            self._iso_isovalue_slider,
+            self._iso_opacity_slider,
+            self._iso_colors_dd,
+            # NOT _iso_png_transparent: it is an export-only option, applied at
+            # capture time. Observing it here would change the live viewer.
+        ):
+            _w.observe(self._safe_cb(self._on_iso_appearance_changed), names="value")
         self._export_bundle_btn.on_click(self._on_export_bundle)
 
     # ── Files tab ────────────────────────────────────────────────────────
@@ -2746,8 +2829,18 @@ class QuantUIApp:
         _last_pes = getattr(self, "_last_pes_result", None)
         if _last_pes is not None:
             self._show_pes_scan_result(_last_pes)
-        # Re-render 3D molecule viewer so scene_bgcolor updates immediately.
-        self._refresh_calc_mol_viewer()
+        # Re-render BOTH 3D molecule viewers so scene_bgcolor updates
+        # immediately. This used to call _refresh_calc_mol_viewer directly,
+        # which covered the Calculate tab only — the Analysis-tab viewer kept
+        # its old background until something else happened to redraw it.
+        # _rerender_3d_views already handled both; it just was not reached from
+        # here. Reported 2026-08-04.
+        self._rerender_3d_views()
+        # ...and the isosurface / vibrational viewers, which bake the same
+        # colour into their generated HTML. Without this they keep the old
+        # background until the user regenerates — reported 2026-08-04. Both
+        # re-render from cached inputs; neither re-runs a calculation.
+        _viz_rerender_3d_scenes_for_theme(self)
 
     def _initialize_viz_state_from_preference(self) -> None:
         """Align _viz_backend and the three preference widgets with the
@@ -3313,6 +3406,31 @@ class QuantUIApp:
     def _on_export_pdb(self, btn) -> None:
         _exp_on_export_pdb(self, btn)
 
+    def _on_reorg_view_changed(self, change) -> None:
+        _ana_on_reorg_view_changed(self, change)
+
+    def _on_iso_cancel(self, btn) -> None:
+        _viz_on_iso_cancel(self, btn)
+
+    def _on_iso_appearance_changed(self, change) -> None:
+        _viz_on_iso_appearance_changed(self, change)
+
+    def _on_orb_png_captured(self, change) -> None:
+        _exp_on_orb_png_captured(self, change)
+
+    def _on_iso_resolution_changed(self, change) -> None:
+        """Persist the isosurface grid choice.
+
+        Saved on change rather than at generate time so the preference sticks
+        even if the user picks a grid and then closes the app without running
+        anything.
+        """
+        new_val = (change or {}).get("new")
+        if not new_val or new_val == self._user_settings.viz.iso_resolution:
+            return
+        self._user_settings.viz.iso_resolution = str(new_val)
+        self._user_settings.save()
+
     def _on_iso_export_cube(self, btn) -> None:
         _exp_on_iso_export_cube(self, btn)
 

{quantui-0.5.2 → quantui-0.6.1}/quantui/app_analysis.py

@@ -253,6 +253,110 @@ def pop_energies(app: Any, ctx: Any) -> bool:
     return bool(app._show_orbital_diagram(result))
 
 
+def pop_reorg_geometries(app: Any, ctx: Any) -> bool:
+    """Populate the Geometries panel for a reorganization-energy result.
+
+    Works from a live result OR a saved one by reading the same channel payload
+    both now carry — the shape REORG.1 introduced. That is deliberate: the
+    original bug was two paths reading different things, so this one never had
+    the chance to grow a second reader.
+
+    Returns False when the payload is absent, which is exactly the pre-REORG.1
+    case; the panel then stays unavailable rather than showing an empty viewer,
+    and the results card explains why.
+    """
+    channels, neutral = _reorg_payload(app, ctx)
+    if not channels or not neutral:
+        _set_panel_unavailable_message(
+            app,
+            "Geometries",
+            (
+                "Not available for this result: the per-channel geometries were "
+                "not saved. Re-run the calculation to enable the comparison."
+            ),
+        )
+        return False
+
+    from quantui.reorganization_energy import reorg_geometries
+
+    geoms = reorg_geometries(channels, neutral)
+    if len(geoms) < 2:
+        return False
+    app._reorg_geometries = geoms
+    app._reorg_overlay_pair.options = [
+        (f"{geoms[0]['label'].split(' — ')[0]} vs {g['label'].split(' — ')[0]}", i)
+        for i in range(1, len(geoms))
+        for g in [geoms[i]]
+    ]
+    if app._reorg_overlay_pair.options:
+        app._reorg_overlay_pair.value = app._reorg_overlay_pair.options[0][1]
+    render_reorg_geometries(app)
+    return True
+
+
+def _reorg_payload(app: Any, ctx: Any) -> tuple[list, dict]:
+    """Channel list + neutral geometry, from a live result or a saved one."""
+    live = getattr(ctx, "live_result", None)
+    if live is not None and getattr(live, "channels", None):
+        from quantui.results_storage import _reorg_channels_payload
+
+        payload = _reorg_channels_payload(live) or []
+        neutral = payload[0].get("neutral_geometry") if payload else None
+        return payload, neutral or {}
+
+    result_dir = getattr(ctx, "result_dir", None)
+    if result_dir is not None:
+        try:
+            from quantui import load_result
+
+            data = load_result(result_dir)
+            payload = data.get("reorg_channels") or []
+            neutral = payload[0].get("neutral_geometry") if payload else None
+            return payload, neutral or {}
+        except Exception:  # noqa: BLE001 — a missing panel, never a crash
+            return [], {}
+    return [], {}
+
+
+def render_reorg_geometries(app: Any) -> None:
+    """Draw the current view (stepper or overlay) into the Geometries panel."""
+    geoms = getattr(app, "_reorg_geometries", None)
+    if not geoms:
+        return
+    from quantui.app_visualization import (
+        build_reorg_geometry_viewer_html,
+        build_reorg_overlay_html,
+    )
+
+    bg = app._plotly_theme_colors()["scene_bgcolor"]
+    try:
+        if app._reorg_view_toggle.value == "overlay":
+            idx = int(app._reorg_overlay_pair.value or 1)
+            html = build_reorg_overlay_html(
+                geoms[0],
+                geoms[idx],
+                bgcolor=bg,
+                exaggerate=float(getattr(app._reorg_exaggerate, "value", 1.0)),
+            )
+        else:
+            html = build_reorg_geometry_viewer_html(geoms, bgcolor=bg)
+        app._set_html_output(app._reorg_geom_output, html)
+    except Exception as exc:  # noqa: BLE001
+        app._set_html_output(
+            app._reorg_geom_output,
+            f'<p style="color:#b91c1c;padding:8px">Geometry view failed: {exc}</p>',
+        )
+
+
+def on_reorg_view_changed(app: Any, change: Any = None) -> None:
+    """Toggle between stepper and overlay; the pair picker only applies to one."""
+    is_overlay = app._reorg_view_toggle.value == "overlay"
+    app._reorg_overlay_pair.layout.display = "" if is_overlay else "none"
+    # Only meaningful for the overlay — the stepper shows true positions.
+    app._reorg_exaggerate.layout.display = "" if is_overlay else "none"
+    render_reorg_geometries(app)
+
+
 def pop_isosurface(app: Any, ctx: Any) -> bool:
     """Populate Isosurface availability from orbital state.