Add ensemble trajectory overlay and examples

[iribirii]

Summary

• Add a standalone xyzrender.ensemble module and API that builds an ensemble Molecule from a multi-frame XYZ trajectory by RMSD-aligning all frames onto a reference frame using the Kabsch algorithm (index-based atom pairing).
• Extend the CLI with a --ensemble flag for trajectory overlays, including additional validation (mutually exclusive with --overlay, --gif-ts, --gif-trj, and stdin input) and support for rotation GIFs that spin the pre-built ensemble graph.
• Default ensemble rendering to ignore bond orders (all bonds drawn as single) and keep explicit hydrogens visible, while preserving standard CPK colouring.
• Add unit tests for _build_ensemble_molecule, document the ensemble feature in the README and CLI reference, and include static and rotating ensemble figures for the triphenylbenzol trajectory.

Details

• Core logic

  • New src/xyzrender/ensemble.py implements:
    • align(frames, reference_frame=0) to align all frames from load_trajectory_frames() onto a chosen reference frame via Kabsch, with shape and symbol consistency checks.
    • merge_graphs(reference_graph, aligned_positions) to replicate the reference graph per conformer, add molecule_index attributes to nodes/edges, avoid overlay/bond_color_override, and apply a small per-conformer z-nudge to prevent SVG z-fighting.
  • _build_ensemble_molecule(...) in api.py:
    • Loads frames and a reference graph for the chosen frame.
    • Flattens any existing bond_order values on the reference graph to 1 (render-time single bonds).
    • Constructs an ensemble graph via ensemble.align + ensemble.merge_graphs, wrapped in a Molecule.

• Public API

  • New ensemble(...) -> SVGResult in api.py:
    • Accepts a trajectory path plus styling options similar to render().
    • Forbids surfaces (mo, dens, esp, nci) for ensembles.
    • Defaults:
      • hy=True (unless hy/no_hy explicitly overridden).
      • bo=False (ignore bond orders by default, though explicit bo is still respected).
  • __init__.py now exports ensemble for from xyzrender import ensemble.

• CLI

  • New --ensemble flag in the “overlay / ensemble” group:
    • Requires a positional input file; errors out with stdin.
    • Mutually exclusive with --overlay, --overlay-color, --gif-ts, and --gif-trj.
  • Static SVG path:
    • When --ensemble is set, the CLI calls api.ensemble(...) instead of render(...).
  • GIF path:
    • For --ensemble --gif-rot, builds the ensemble once via _build_ensemble_molecule(...) and passes it to render_gif(...) so the GIF shows the ensemble, not just a single frame.

• Docs and examples

  • README.md:
    • Adds an “Ensemble overlay” section with a CLI example.
    • Includes tables comparing:
      • SN2 ensemble and triphenylbenzol ensemble (static).
      • Triphenylbenzol ensemble static SVG vs rotating ensemble GIF.
  • docs/source/cli_reference.md:
    • Documents the --ensemble flag under “Structural overlay”.
  • New figures:
    • examples/images/triphenylbenzol_ensemble.svg
    • examples/images/triphenylbenzol_ensemble.gif
    • Trajectory input stored as examples/structures/triphenylbenzol.xyz.

• Tests

  • New tests/test_ensemble.py:
    • _write_multiframe_xyz(...) helper to generate small test trajectories.
    • test_build_ensemble_molecule:
      • Verifies node/edge counts, molecule_index labelling, and absence of overlay/bond_color_override attributes.
    • test_ensemble_api_returns_svg:
      • Checks that ensemble(...) writes a valid SVG and returns an SVGResult.