[pastewka]

Implements RESTRUCTURING_PLAN.md: the flat simulator becomes a headless solver package and a separate viewer, connected by a run file, with TOML configuration, a CLI, restartable runs and a Quarto book as documentation.

Numerics are unchanged. Two reference runs (test/test_reference.py) were recorded on the original code before any refactoring and reproduce bit-identically after every commit: a sessile drop with global split and collapse, and a quasi-static sphere run with local remeshing and wetting.

What changes

• Two distributions (Python ≥ 3.12):
  • DropletRelaxer, the solver: numpy, scipy and h5py only; a test makes sure it never imports PyVista.
  • DropletViewer (viewer/): PyVista viewer.
• Driver with frame sinks (DropletRelaxer/driver.py, io/frame.py): the remesh loop from main.py. Every output is a sink: HDF5 writer, console, live window. Only a stop request flows back, so attaching a window or writer does not change results (tested).
• TOML scenarios with strict checking ("did you mean" hints) and --set section.key=value overrides. The field comments became attribute docstrings; a test enforces that every parameter is documented, and droplet-relax show-config prints them.
• Run file: HDF5 in the VTKHDF layout (temporal PolyData, topology may change per frame), checked with vtkHDFReader of VTK 9.3.1 and 9.7.1, so ParaView opens it.
  • Written in SWMR mode, so a running job can be watched.
  • Checkpoints in two alternating slots; a restart after a simulated kill ends bit-identically to the uninterrupted run, also for the quasi-static sphere scenario.
• CLIs:
  • droplet-relax run|restart|info|show-config; SIGTERM and Ctrl-C stop cleanly with a checkpoint.
  • droplet-view run.h5 [--follow | --video out.mp4].
  • droplet-view live scenario.toml: in-process live window with a Stop button. It always writes the run file and replays it after the run.
• Docs: docs/mathematical_background.tex converted to a Quarto book, with a new "Using the Code" part.
  • The parameter reference and the file-format tables are generated from the code; a test checks that every code name in the equation-to-code table imports.
  • The README design log moved to an appendix; the README is now short.
• Removed: run.sh, run_tests.sh, main.py, requirements.txt, the selftest, and the .npy export (the Save button now records the replay video). The vtk<9.5 cap is gone: the GLX crash it guarded against is handled by disabling multisampling.
• CI:
  • tests.yml: Python 3.12–3.14; viewer tests under xvfb with the latest VTK; slow tests nightly or with the slow label.
  • flake8.yml: pre-commit.
  • documentation.yml: renders the PDF as an artifact and attaches it to releases.
  • publish.yml: uploads to PyPI via trusted publishing on v* tags.

Where the implementation deviates from the plan

Section 8 of RESTRUCTURING_PLAN.md lists these:

• The package is flat, with the old module names; the planned geometry/, energies/ and optimizer/ subpackages would only have added import cycles.
• VTK constraints found by testing: the file must use the HDF5 1.10 format, and FieldDataSizes is ordered [components, tuples].
• Live reading relies on datasets only (SWMR readers cannot refresh attributes): the run status is a small dataset, and frames are counted by Steps/Values.

Testing

• Locally on macOS with Python 3.14: pytest -m "" passes (154 tests), and the reference runs are bit-identical with DROPLET_REFERENCE_HASH=1.
• The docs PDF builds with no unresolved references.
• Both distributions build and pass twine check.
• A real window was opened for a live run and the replay that follows.
• This PR is the first CI run of the new workflows.

Not covered

• Not tested interactively: closing the window during a live run, and the right-drag pan.
• Needs a check on Linux: the uncapped VTK, ideally on the machine that originally crashed with VTK 9.7.1.
• No release tag yet: publish.yml needs the PyPI projects and a pypi environment set up for trusted publishing first.

🤖 Generated with Claude Code