shape-plotters 0.1.0__tar.gz

shape_plotters-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,77 @@
+name: wheels
+on:
+  push:
+    tags: ['[0-9]+.[0-9]+.[0-9]+']
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # tags for setuptools_scm
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build sdist and wheel
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION_FOR_SHAPE_PLOTTERS: ${{ github.ref_name }}
+        run: |
+          python -m pip install --upgrade build
+          python -m build --outdir dist
+      - name: Verify wheel in clean venv
+        # Everything runs from a copy of the tests outside the checkout, so
+        # the tests import the installed wheel and not the source tree (and
+        # pip cannot mistake the checkout's egg-info for an installed copy).
+        # The timing budgets are skipped: they are calibrated for a developer
+        # machine, not a shared runner.
+        env:
+          MPLBACKEND: Agg
+        run: |
+          python -m venv /tmp/verify-wheel
+          mkdir /tmp/verify-tests
+          cp -r tests conftest.py /tmp/verify-tests/
+          cd /tmp/verify-tests
+          /tmp/verify-wheel/bin/pip install "$GITHUB_WORKSPACE"/dist/*.whl pytest
+          /tmp/verify-wheel/bin/python -m pytest tests -q --ignore=tests/test_perf.py
+          /tmp/verify-wheel/bin/shape-plotters --help
+      - name: Verify sdist installs from the tarball
+        run: |
+          python -m venv /tmp/verify-sdist
+          cd /tmp
+          /tmp/verify-sdist/bin/pip install "$GITHUB_WORKSPACE"/dist/*.tar.gz
+          /tmp/verify-sdist/bin/shape-plotters --help
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+  release:
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write        # create/upload the Release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+  pypi:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/shape-plotters
+    permissions:
+      id-token: write        # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

shape_plotters-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.idea/
+*.egg-info/
+*.png
+/docs
+dist/
+build/

shape_plotters-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+Notable changes to shape-plotters. Versions follow semantic versioning.
+
+## 0.1.0
+
+First release.
+
+### Added
+
+- **Installable package.** `pip install shape-plotters` provides the
+  `shape-plotters` command; the parameterization libraries are pinned
+  dependencies.
+- **Shared engine, one render per parameterization.** `shape-plotters beta`
+  and `shape-plotters fos` open the same interactive figure; everything
+  shape-specific comes from the render (contract in
+  `shape_plotters/core/result.py`).
+- **Beta render** over beta-parameterization 4.0.1: sliders β1–β8, volume
+  conserved by the library. An orange overlay shows the centre-of-mass
+  corrected shape whenever its β1 differs from the slider value; a corrected
+  shape that turns out invalid is drawn greyed instead of vanishing.
+- **FoS render** over fos-parameterization 3.0.0: sliders c and a3–a8 with
+  practical-limit markers, an extra ρ(z) panel with the library's dρ/dz, the
+  library's neck, and an orange overlay of the R(θ) star-convex representation
+  when its centre of mass is shifted. Separated shapes draw both fragments.
+- **Energy-model grid.** R(θ) and the analytic dR/dθ are evaluated by the
+  libraries on a 2048-node Gauss-Legendre grid in cos θ, the dense grid of
+  the WMMM energy model, so the plot shows the shape the model evaluates.
+- **Stats panel:** volume, surface and centre of mass by Gauss-Legendre
+  quadrature on that grid, neck position, radius and depth, and the fragment
+  volume and mass split at the neck.
+- **Invalid shapes** stay visible: greyed, with the library's status name and
+  message as the panel title.
+- **Display units:** fm / R₀ toggle with Z and N boxes (R₀ = 1.16 A^(1/3) fm).
+- **Scission bands:** the neck-radius range 1.2–1.5 fm is shaded on the
+  cross-section panel.
+- **Controls:** ± nudge buttons on every slider, Reset, and Save (300 dpi PNG
+  named after the parameters).
+- **Optional Energy button.** Shown only when a local `wmmm` package is
+  importable; prints WMMM energies for the shape on screen. `wmmm` is not a
+  dependency and no model code, data or output is part of this repository.
+- **Performance guards:** pytest budgets for artist mutation and frame time
+  (`tests/test_perf.py`).
+
+## Before 0.1.0
+
+No changelog was kept during initial development (from 2026-07-03). See the
+git history.

shape_plotters-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksander Augustyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shape_plotters-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: shape-plotters
+Version: 0.1.0
+Summary: Interactive matplotlib plotters for axially symmetric nuclear shapes (beta, FoS)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AleksanderAugustyn/shape-plotters
+Project-URL: Repository, https://github.com/AleksanderAugustyn/shape-plotters
+Project-URL: Changelog, https://github.com/AleksanderAugustyn/shape-plotters/blob/master/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: matplotlib>=3.8.4
+Requires-Dist: beta-parameterization==4.0.1
+Requires-Dist: fos-parameterization==3.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# shape-plotters
+
+Interactive matplotlib plotters for axially symmetric nuclear shapes. Move a
+slider and the shape, its derivative and its integral properties update. One
+shared engine draws the figure; each shape parameterization is a render module.
+
+| render | parameterization | sliders | library |
+|---|---|---|---|
+| `beta` | spherical-harmonic (Legendre) expansion | β1–β8 | [beta-parameterization](https://github.com/AleksanderAugustyn/beta-parameterization) |
+| `fos` | Fourier-over-Spheroid | c, a3–a8 | [fos-parameterization](https://github.com/AleksanderAugustyn/fos-parameterization) |
+
+The shapes are not re-implemented here. R(θ) and the analytic dR/dθ come from
+the compiled libraries, evaluated on a 2048-node Gauss-Legendre grid in cos θ.
+That is the dense grid of the WMMM macroscopic-microscopic energy model, so
+the plot shows exactly the shape the model evaluates.
+
+## What the figure shows
+
+- **R(θ) and dR/dθ**, and the **cross-section** ρ(z) with equal axes. The FoS
+  render adds a ρ(z) panel with the library's dρ/dz.
+- **Stats:** volume, surface and centre of mass by Gauss-Legendre quadrature,
+  the neck position, radius and depth, and the fragment volume and mass split
+  at the neck.
+- **Overlays** (orange, dashed): for beta, the centre-of-mass corrected shape
+  when its β1 differs from the slider value; for FoS, the R(θ) star-convex
+  representation when its centre of mass is shifted.
+- **Scission bands:** the neck-radius range 1.2–1.5 fm, shaded.
+- **Invalid shapes** stay on screen, greyed, with the library's status as the
+  panel title.
+
+Controls: ± nudge buttons on every slider, an fm / R₀ unit toggle with Z and N
+boxes (R₀ = 1.16 A^(1/3) fm), Reset, and Save (300 dpi PNG named after the
+parameters, written to the current directory). Red dotted marks on the FoS
+sliders are practical limits.
+
+## Requirements
+
+- Linux x86-64. The parameterization libraries ship manylinux wheels only;
+  WSL2 with WSLg works.
+- Python 3.10 or newer with a matplotlib GUI backend. Tk is the default
+  (`python3-tk` on Debian/Ubuntu).
+
+## Install
+
+    pip install shape-plotters
+
+or `pipx install shape-plotters` to get the command without touching another
+environment. The parameterization libraries come along as prebuilt wheels
+(Fortran shared library and libgfortran bundled), pinned to the exact versions
+each render is written against.
+
+Under WSL, keep the virtual environment on the Linux filesystem, not under
+`/mnt/c`. The Windows drive is a 9P mount; a venv there makes matplotlib
+rendering sluggish (~5× slower).
+
+## Run
+
+    shape-plotters beta
+    shape-plotters fos
+
+`python -m shape_plotters beta` does the same.
+
+## Energy button
+
+An Energy button appears when a Python package named `wmmm` is importable. It
+prints the WMMM energies of the shape on screen. WMMM is not public yet and is
+not a dependency: without it the button is absent and nothing else changes.
+This repository contains the calling convention only, no model code, data or
+output.
+
+## Development
+
+    git clone https://github.com/AleksanderAugustyn/shape-plotters.git
+    cd shape-plotters
+    python3 -m venv ~/.venvs/shape-plotters
+    source ~/.venvs/shape-plotters/bin/activate
+    pip install -e ".[test]"
+    python -m pytest
+
+The WMMM smoke tests skip when `wmmm` is not installed. The frame-time budgets
+in `tests/test_perf.py` assume a venv on the Linux filesystem.
+
+    shape_plotters/cli.py          entry point and render registry
+    shape_plotters/core/           engine, widgets, quadrature, neck and fragment helpers
+    shape_plotters/core/result.py  the render contract (what a render gives the engine)
+    shape_plotters/renders/        one module per parameterization
+    tests/                         pytest suite, including frame-time budgets
+
+A new parameterization is a new module in `shape_plotters/renders/` that
+implements the render contract, plus one registry entry in `cli.py` and a
+pinned library in `pyproject.toml`. The engine needs no change.
+
+Releases are cut by pushing a version tag such as `0.1.0`; the `wheels`
+workflow builds, tests and publishes to PyPI.
+
+## License
+
+MIT, see [LICENSE](https://github.com/AleksanderAugustyn/shape-plotters/blob/master/LICENSE).
+Changes are recorded in
+[CHANGELOG.md](https://github.com/AleksanderAugustyn/shape-plotters/blob/master/CHANGELOG.md).

shape_plotters-0.1.0/README.md

@@ -0,0 +1,100 @@
+# shape-plotters
+
+Interactive matplotlib plotters for axially symmetric nuclear shapes. Move a
+slider and the shape, its derivative and its integral properties update. One
+shared engine draws the figure; each shape parameterization is a render module.
+
+| render | parameterization | sliders | library |
+|---|---|---|---|
+| `beta` | spherical-harmonic (Legendre) expansion | β1–β8 | [beta-parameterization](https://github.com/AleksanderAugustyn/beta-parameterization) |
+| `fos` | Fourier-over-Spheroid | c, a3–a8 | [fos-parameterization](https://github.com/AleksanderAugustyn/fos-parameterization) |
+
+The shapes are not re-implemented here. R(θ) and the analytic dR/dθ come from
+the compiled libraries, evaluated on a 2048-node Gauss-Legendre grid in cos θ.
+That is the dense grid of the WMMM macroscopic-microscopic energy model, so
+the plot shows exactly the shape the model evaluates.
+
+## What the figure shows
+
+- **R(θ) and dR/dθ**, and the **cross-section** ρ(z) with equal axes. The FoS
+  render adds a ρ(z) panel with the library's dρ/dz.
+- **Stats:** volume, surface and centre of mass by Gauss-Legendre quadrature,
+  the neck position, radius and depth, and the fragment volume and mass split
+  at the neck.
+- **Overlays** (orange, dashed): for beta, the centre-of-mass corrected shape
+  when its β1 differs from the slider value; for FoS, the R(θ) star-convex
+  representation when its centre of mass is shifted.
+- **Scission bands:** the neck-radius range 1.2–1.5 fm, shaded.
+- **Invalid shapes** stay on screen, greyed, with the library's status as the
+  panel title.
+
+Controls: ± nudge buttons on every slider, an fm / R₀ unit toggle with Z and N
+boxes (R₀ = 1.16 A^(1/3) fm), Reset, and Save (300 dpi PNG named after the
+parameters, written to the current directory). Red dotted marks on the FoS
+sliders are practical limits.
+
+## Requirements
+
+- Linux x86-64. The parameterization libraries ship manylinux wheels only;
+  WSL2 with WSLg works.
+- Python 3.10 or newer with a matplotlib GUI backend. Tk is the default
+  (`python3-tk` on Debian/Ubuntu).
+
+## Install
+
+    pip install shape-plotters
+
+or `pipx install shape-plotters` to get the command without touching another
+environment. The parameterization libraries come along as prebuilt wheels
+(Fortran shared library and libgfortran bundled), pinned to the exact versions
+each render is written against.
+
+Under WSL, keep the virtual environment on the Linux filesystem, not under
+`/mnt/c`. The Windows drive is a 9P mount; a venv there makes matplotlib
+rendering sluggish (~5× slower).
+
+## Run
+
+    shape-plotters beta
+    shape-plotters fos
+
+`python -m shape_plotters beta` does the same.
+
+## Energy button
+
+An Energy button appears when a Python package named `wmmm` is importable. It
+prints the WMMM energies of the shape on screen. WMMM is not public yet and is
+not a dependency: without it the button is absent and nothing else changes.
+This repository contains the calling convention only, no model code, data or
+output.
+
+## Development
+
+    git clone https://github.com/AleksanderAugustyn/shape-plotters.git
+    cd shape-plotters
+    python3 -m venv ~/.venvs/shape-plotters
+    source ~/.venvs/shape-plotters/bin/activate
+    pip install -e ".[test]"
+    python -m pytest
+
+The WMMM smoke tests skip when `wmmm` is not installed. The frame-time budgets
+in `tests/test_perf.py` assume a venv on the Linux filesystem.
+
+    shape_plotters/cli.py          entry point and render registry
+    shape_plotters/core/           engine, widgets, quadrature, neck and fragment helpers
+    shape_plotters/core/result.py  the render contract (what a render gives the engine)
+    shape_plotters/renders/        one module per parameterization
+    tests/                         pytest suite, including frame-time budgets
+
+A new parameterization is a new module in `shape_plotters/renders/` that
+implements the render contract, plus one registry entry in `cli.py` and a
+pinned library in `pyproject.toml`. The engine needs no change.
+
+Releases are cut by pushing a version tag such as `0.1.0`; the `wheels`
+workflow builds, tests and publishes to PyPI.
+
+## License
+
+MIT, see [LICENSE](https://github.com/AleksanderAugustyn/shape-plotters/blob/master/LICENSE).
+Changes are recorded in
+[CHANGELOG.md](https://github.com/AleksanderAugustyn/shape-plotters/blob/master/CHANGELOG.md).

shape_plotters-0.1.0/conftest.py

@@ -0,0 +1,5 @@
+import os
+import sys
+
+os.environ.setdefault("MPLBACKEND", "Agg")
+sys.path.insert(0, os.path.dirname(__file__))

shape_plotters-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shape-plotters"
+description = "Interactive matplotlib plotters for axially symmetric nuclear shapes (beta, FoS)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=2.0",
+    # First releases that install alongside numpy 2.
+    "scipy>=1.13",
+    "matplotlib>=3.8.4",
+    # Exact pins: each render is written against one library API version.
+    "beta-parameterization==4.0.1",
+    "fos-parameterization==3.0.0",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+shape-plotters = "shape_plotters.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/AleksanderAugustyn/shape-plotters"
+Repository = "https://github.com/AleksanderAugustyn/shape-plotters"
+Changelog = "https://github.com/AleksanderAugustyn/shape-plotters/blob/master/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["shape_plotters*"]
+
+# Version from git tags (setuptools_scm), as in the parameterization libraries.
+[tool.setuptools_scm]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shape_plotters-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shape_plotters-0.1.0/shape_plotters/__main__.py

@@ -0,0 +1,3 @@
+from shape_plotters.cli import main
+
+main()

shape_plotters-0.1.0/shape_plotters/cli.py

@@ -0,0 +1,19 @@
+"""Command-line entry point: shape-plotters beta|fos (or python -m shape_plotters)."""
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from shape_plotters.core.engine import ShapePlotterApp
+from shape_plotters.renders.beta import BetaRender
+from shape_plotters.renders.fos import FoSRender
+
+RENDERS = {"beta": BetaRender, "fos": FoSRender}
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="shape-plotters", description="Interactive nuclear-shape plotter")
+    parser.add_argument("render", choices=sorted(RENDERS))
+    args = parser.parse_args(argv)
+    ShapePlotterApp(RENDERS[args.render]()).run()

shape_plotters-0.1.0/shape_plotters/core/energy.py

@@ -0,0 +1,91 @@
+"""Optional WMMM energy adapter — the only module allowed to import wmmm.
+
+The energy model is strictly local: wmmm is never a dependency of this
+package (not even an optional extra) and is installed out-of-band as a local
+editable install. This module carries the calling convention only — no model
+code, data, or paths. The engine consults available() to decide whether the
+Energy button exists; compute() returns EnergyResult, with failures in
+EnergyResult.error rather than exceptions.
+"""
+from __future__ import annotations
+
+import importlib.util
+from dataclasses import dataclass
+from typing import Sequence
+
+
+@dataclass(frozen=True)
+class EnergyResult:
+    """One WMMM point result (energies in MeV); zero-filled when error is set."""
+    is_valid: bool
+    mass_excess: float
+    total_energy: float
+    macro_energy: float
+    micro_energy: float
+    surface_energy: float
+    coulomb_energy: float
+    proton_pairing_gap: float
+    neutron_pairing_gap: float
+    proton_k: int
+    neutron_k: int
+    corrected_beta10: float     # cross-check channel (vs the render scalar), not displayed
+    error: str | None = None
+
+
+# Model handles are configuration-immutable: one per (param_type,
+# com_correction) for the app lifetime (~20 ms per compute thereafter).
+_models: dict[tuple[str, bool], object] = {}
+
+
+def available() -> bool:
+    """True when the wmmm package is importable; performs no import."""
+    return importlib.util.find_spec("wmmm") is not None
+
+
+def _error(message: str) -> EnergyResult:
+    return EnergyResult(False, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
+                        0, 0, 0.0, error=message)
+
+
+def _get_model(param_type: str, com_correction: bool):
+    key = (param_type, com_correction)
+    model = _models.get(key)
+    if model is None:
+        import wmmm  # deferred: loads the Fortran library on first use only
+        model = wmmm.Model(param_type)
+        if not com_correction:
+            model.set("beta_10_com_shift", 0.0)
+        _models[key] = model
+    return model
+
+
+def compute(param_type: str, z: int, n: int, shape: Sequence[float],
+            com_correction: bool = True) -> EnergyResult:
+    """One WMMM point computation; never raises.
+
+    Parameters
+    ----------
+    param_type : str
+        "legendre" (20 shape params) or "fos" (7).
+    z, n : int
+        Proton and neutron numbers.
+    shape : Sequence[float]
+        Shape parameters in WMMM's convention (raw slider values).
+    com_correction : bool
+        WMMM's beta_10_com_shift flag. False evaluates beta10 as given
+        (legendre only — inert on the fos path).
+    """
+    try:
+        model = _get_model(param_type, com_correction)
+        r = model.compute(int(z), int(n), list(shape))
+    except Exception as exc:  # any wmmm failure becomes a stats-box message
+        return _error(f"{type(exc).__name__}: {exc}")
+    return EnergyResult(
+        is_valid=bool(r.is_valid), mass_excess=r.mass_excess,
+        total_energy=r.total_energy, macro_energy=r.macro_energy,
+        micro_energy=r.micro_energy, surface_energy=r.surface_energy,
+        coulomb_energy=r.coulomb_energy,
+        proton_pairing_gap=r.proton_pairing_gap,
+        neutron_pairing_gap=r.neutron_pairing_gap,
+        proton_k=int(r.proton_k), neutron_k=int(r.neutron_k),
+        corrected_beta10=r.corrected_beta10)