quantui 0.5.1__tar.gz → 0.6.0__tar.gz

{quantui-0.5.1 → quantui-0.6.0}/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [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
+
+- **Dark mode now has visible panel edges.** Borders, cards, and dividers were
+  effectively invisible in Dark mode — measured at 1.14:1 against the panel
+  background, well under the 3:1 that WCAG asks of a UI component. Dark mode is
+  a whole-page colour inversion rather than a separate palette, so a light grey
+  border inverts to a near-black one on a near-black page and disappears. The
+  borders are now a mid-tone that stays visible in *both* modes (3.20:1 light,
+  4.30:1 dark). Text contrast was measured too and was never the problem — it
+  is 7.24:1 in light mode and slightly *better* inverted — so text colours are
+  deliberately unchanged.
+
+### Added
+
+- **Every 3-D viewer now has a border around it**, so it is clear where the
+  view ends and where the page can be scrolled without dragging the structure.
+  This covers the molecule preview, the results and analysis structure views,
+  the geometry-optimization trajectory, the vibrational-mode animation, and the
+  classical pre-optimization preview. The frame hugs the plot itself rather
+  than spanning the window width, and looks the same whichever rendering
+  backend (py3Dmol or plotlymol3d) is active.
+
 ## [0.5.1] - 2026-07-31
 
 ### Fixed
@@ -484,7 +563,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.1...HEAD
+[Unreleased]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.6.0...HEAD
+[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
 [0.4.1]: https://github.com/The-Schultz-Lab/QuantUI/compare/v0.4.0...v0.4.1

{quantui-0.5.1/quantui.egg-info → quantui-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantui
-Version: 0.5.1
+Version: 0.6.0
 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
@@ -91,7 +91,7 @@ Dynamic: license-file
 
 # QuantUI
 
-[![PyPI](https://img.shields.io/pypi/v/quantui)](https://pypi.org/project/quantui/)
+[![PyPI](https://img.shields.io/pypi/v/quantui?v=2)](https://pypi.org/project/quantui/)
 [![CI](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/The-Schultz-Lab/QuantUI/blob/main/LICENSE)

{quantui-0.5.1 → quantui-0.6.0}/README.md

@@ -1,6 +1,6 @@
 # QuantUI
 
-[![PyPI](https://img.shields.io/pypi/v/quantui)](https://pypi.org/project/quantui/)
+[![PyPI](https://img.shields.io/pypi/v/quantui?v=2)](https://pypi.org/project/quantui/)
 [![CI](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Schultz-Lab/QuantUI/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://the-schultz-lab.github.io/QuantUI/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/The-Schultz-Lab/QuantUI/blob/main/LICENSE)

{quantui-0.5.1 → quantui-0.6.0}/pyproject.toml

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

{quantui-0.5.1 → quantui-0.6.0}/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.1"
+__version__ = "0.6.0"
 
 import logging
 from typing import Any

{quantui-0.5.1 → quantui-0.6.0}/quantui/app.py

@@ -32,6 +32,7 @@ import quantui
 import quantui.calc_log as _calc_log
 import quantui.issue_tracker as _issue_tracker
 from quantui import molecule_library as _ml
+from quantui import theme as _theme
 from quantui.app_analysis import (
     activate_ana_panel as _ana_activate_ana_panel,
 )
@@ -146,6 +147,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,
 )
@@ -332,6 +336,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,
 )
@@ -359,6 +369,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,
 )
@@ -450,9 +463,6 @@ try:
     from quantui.visualization_py3dmol import (
         VIZ_STYLE_OPTIONS as _VIZ_STYLE_OPTIONS,
     )
-    from quantui.visualization_py3dmol import (
-        display_molecule as _display_molecule,
-    )
     from quantui.visualization_py3dmol import (
         render_molecule_html as _render_molecule_html,
     )
@@ -460,7 +470,6 @@ try:
     VISUALIZATION_AVAILABLE = True
 except ImportError:
     VISUALIZATION_AVAILABLE = False
-    _display_molecule = None  # type: ignore[assignment]
     _render_molecule_html = None  # type: ignore[assignment]
     _PLOTLYMOL_VIZ = False
     _PY3DMOL_VIZ = False
@@ -616,7 +625,7 @@ h3 {
     color: #64748b !important;
     margin: 24px 0 10px !important;
     padding-bottom: 5px !important;
-    border-bottom: 1px solid #e2e8f0 !important;
+    border-bottom: 1px solid __Q_BORDER__ !important;
 }
 
 /* Rounded corners on inputs, dropdowns, and buttons -------------------- */
@@ -632,21 +641,6 @@ h3 {
     background: transparent !important;
 }
 
-/* 3D molecule-viewer frames — a subtle bounding box so the viewer
-   extent reads clearly. The light border inverts to dark automatically under
-   the global dark-mode invert filter. */
-.quantui-viewer-frame {
-    border: 1px solid #c0ccd8 !important;
-    border-radius: 6px !important;
-    overflow: hidden !important;
-}
-/* Collapse the frame to nothing when the viewer output is empty (e.g. before
-   a calc runs) so no hollow box shows. Degrades to an always-on border where
-   :has() is unsupported. */
-.quantui-viewer-frame:not(:has(.jp-OutputArea-child)) {
-    border-color: transparent !important;
-}
-
 /* Inline "calculating" spinner — shown next to slow on-demand
    controls (e.g. orbital-isosurface generation) while work is in flight. */
 @keyframes quantui-spin { to { transform: rotate(360deg); } }
@@ -654,13 +648,20 @@ h3 {
     display: inline-block;
     width: 14px;
     height: 14px;
-    border: 2px solid #c0ccd8;
+    border: 2px solid __Q_BORDER__;
     border-top-color: #2563eb;
     border-radius: 50%;
     animation: quantui-spin 0.7s linear infinite;
     vertical-align: middle;
 }
-</style>"""
+</style>""".replace(
+    # Sentinel substitution rather than an f-string: this block is dense with
+    # CSS braces, every one of which would need doubling. If a second sentinel
+    # is ever added, substitute the LONGER name first — "__Q_BORDER__" matches
+    # inside "__Q_BORDER_STRONG__" and would leave a dangling "_STRONG__".
+    "__Q_BORDER__",
+    _theme.BORDER,
+)
 
 _LAYOUT_TRAITS: frozenset[str] = frozenset(widgets.Layout.class_trait_names())
 
@@ -1639,9 +1640,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),
@@ -1990,6 +2013,27 @@ 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))
+        # 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 ────────────────────────────────────────────────────────
@@ -2383,7 +2427,7 @@ class QuantUIApp:
                     body = rows[1:]
                     head_html = "".join(
                         f'<th style="padding:4px 10px;text-align:left;'
-                        f"border-bottom:1px solid #cbd5e1;font-size:12px;"
+                        f"border-bottom:1px solid {_theme.BORDER};font-size:12px;"
                         f'color:#1e293b">{_html.escape(str(c))}</th>'
                         for c in header
                     )
@@ -2427,7 +2471,7 @@ class QuantUIApp:
                     # reach the parent app.
                     iframe_html = (
                         '<iframe sandbox="allow-scripts" '
-                        'style="width:100%;height:400px;border:1px solid #cbd5e1;'
+                        f'style="width:100%;height:400px;border:1px solid {_theme.BORDER};'
                         'border-radius:4px" '
                         f'srcdoc="{_html.escape(raw, quote=True)}"></iframe>'
                     )
@@ -2757,8 +2801,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
@@ -2871,7 +2925,7 @@ class QuantUIApp:
     def _rerender_3d_views(self) -> None:
         """Re-render visible 3D molecule viewers using the router to pick a
         backend per task. Updates the "Rendering with: X" label widgets."""
-        if _display_molecule is None:
+        if _render_molecule_html is None:
             return
 
         # Calculate-tab molecule preview (MOLECULE_PREVIEW task).
@@ -2884,15 +2938,19 @@ class QuantUIApp:
         if self._analysis_displayed_molecule is not None:
             chosen = self._resolve_backend(VizTask.ANALYSIS_STRUCTURE_VIEW)
             if chosen is not None:
-                self._analysis_mol_output.clear_output()
-                with self._analysis_mol_output:
-                    _display_molecule(
-                        self._analysis_displayed_molecule,
-                        backend=str(chosen),
-                        style=self._viz_style,
-                        lighting=self._viz_lighting,
-                        bgcolor=self._plotly_theme_colors()["scene_bgcolor"],
-                    )
+                # Same render path as the first draw (app_visualization.
+                # _show_result_3d), not display(): the fragment it returns
+                # carries the viewer's own border. Going through display()
+                # here would silently drop that border the moment a user
+                # toggled backends on the Analysis tab.
+                html = _render_molecule_html(
+                    self._analysis_displayed_molecule,
+                    backend=str(chosen),
+                    style=self._viz_style,
+                    lighting=self._viz_lighting,
+                    bgcolor=self._plotly_theme_colors()["scene_bgcolor"],
+                )
+                self._set_html_output(self._analysis_mol_output, html)
                 self._update_analysis_backend_label(chosen)
 
     def _update_analysis_backend_label(self, chosen: VizBackend) -> None:
@@ -3320,6 +3378,28 @@ class QuantUIApp:
     def _on_export_pdb(self, btn) -> None:
         _exp_on_export_pdb(self, btn)
 
+    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)
 
@@ -5514,7 +5594,7 @@ class QuantUIApp:
             rows.append(f'<div style="{style}">{esc}</div>')
         self._log_output_html.value = (
             '<div style="font-family:monospace;font-size:12px;line-height:1.4;'
-            "padding:8px 10px;background:#f8fafc;border:1px solid #e2e8f0;"
+            f"padding:8px 10px;background:#f8fafc;border:1px solid {_theme.BORDER};"
             'border-radius:4px;overflow-x:auto;max-height:550px;overflow-y:auto">'
             + "".join(rows)
             + "</div>"
@@ -5530,7 +5610,7 @@ class QuantUIApp:
         if key and key in HELP_TOPICS:
             entry = HELP_TOPICS[key]
             self.help_content_html.value = (
-                f'<div style="border:1px solid #e2e8f0;border-radius:6px;'
+                f'<div style="border:1px solid {_theme.BORDER};border-radius:6px;'
                 f'padding:14px 18px;margin:8px 0;background:#f8fafc;max-width:700px">'
                 f'<h4 style="margin:0 0 10px;color:#1e293b;font-size:15px;font-weight:700">'
                 f'{entry["title"]}</h4>'