Skip to content

Release v0.12.6: Unified Animation Backend and Project Governance

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 14 Jan 12:29
· 65 commits to master since this release
v0.12.6
03ab796

What's New

🎨 Unified Parallel Animation Backend

  • Centralized backend selection system supporting imageio (with parallel processing) and matplotlib
  • Intelligent auto-detection based on file format and available dependencies
  • 3-4x speedup for GIF rendering, 2-3x for MP4 with parallel processing

📖 Project Governance & Community Standards

  • Comprehensive CHANGELOG documenting all releases
  • CODE_OF_CONDUCT establishing community standards
  • CONTRIBUTING guide with development, testing, and documentation guidelines

Major Features / Key Changes

🎨 Unified Animation Backend System (PR #79)

  • Backend selection: New backend.py module with smart backend selection (select_animation_backend())

    • Automatically chooses optimal backend based on file format and available dependencies
    • Supports explicit backend selection: 'imageio', 'matplotlib', or 'auto'
    • Graceful fallback with helpful installation instructions

  • Parallel rendering: Implemented parallel frame rendering in rendering.py

    • 3-4x speedup for GIF rendering
    • 2-3x speedup for MP4 rendering
    • Automatic worker count detection (cpu_count - 1)
    • Platform-aware multiprocessing (fork on Linux, spawn elsewhere)

  • Refactored visualization modules: Updated energy_plots.py, spatial_plots.py, and theta_sweep_plots.py

    • All animation functions now use unified backend system
    • Consistent API across all visualization modules
    • Module-level render functions for pickle compatibility

  • Enhanced configuration: Extended PlotConfig with new options

    • render_backend: Backend selection ('auto', 'imageio', 'matplotlib')
    • render_workers: Number of parallel workers (None = auto-detect)
    • render_start_method: Multiprocessing start method

  • Dependencies: Updated imageio[ffmpeg]>=2.37.0 for video format support

from canns.analyzer.visualization import energy_landscape_1d_animation

# Automatic backend selection with parallel rendering
energy_landscape_1d_animation(
    x_data, ys_data,
    save_path="output.mp4",
    render_backend="auto",  # 'imageio', 'matplotlib', or 'auto'
    render_workers=None,     # Auto-detect optimal worker count
    output_dpi=150
)

📖 Project Governance Files

  • CHANGELOG.md: Comprehensive changelog following Keep a Changelog format

    • Documents all releases from v0.2.0 to present
    • Categorized changes: Added, Changed, Fixed, Removed
    • Includes PR references and version comparison links

  • CODE_OF_CONDUCT.md: Community standards based on Contributor Covenant

    • Establishes expected behavior and enforcement guidelines
    • Provides clear reporting and resolution procedures

  • CONTRIBUTING.md: Comprehensive development guidelines

    • Development setup with uv package manager
    • Testing guidelines with pytest
    • Documentation contribution workflow
    • Code style and commit message conventions

  • License update: Updated to Apache-2.0 in pyproject.toml for consistency

New Components Added

  • src/canns/analyzer/visualization/core/backend.py - Unified backend selection system (311 lines)
  • src/canns/analyzer/visualization/core/rendering.py - Extended with parallel rendering functions (254 new lines)
  • CHANGELOG.md - Project changelog (340 lines)
  • CODE_OF_CONDUCT.md - Community standards (131 lines)
  • CONTRIBUTING.md - Contribution guidelines (206 lines)

Technical Improvements

Performance

  • Parallel rendering: 3-4x speedup for GIF, 2-3x for MP4 animations
  • Smart thresholds: Only uses parallel rendering for animations ≥50 frames to avoid overhead
  • Platform-aware: Detects platform and adjusts multiprocessing strategy
    • Linux: Uses 'fork' for faster startup (with JAX detection)
    • macOS/Windows: Uses 'spawn' for compatibility

Code Quality

  • Type hints: Comprehensive type annotations with Literal types
  • Dataclasses: Clean configuration with BackendSelection and render options dataclasses
  • Error handling: Informative error messages with installation instructions
  • Module-level functions: Render functions at module level for multiprocessing pickle compatibility

Architecture

  • Separation of concerns: Backend selection logic separated from rendering implementation
  • Graceful degradation: System works even when optional dependencies are missing
  • Extensible design: Easy to add new backends or rendering strategies

New Dependencies

  • imageio[ffmpeg] (>=2.37.0): Video format support with FFmpeg plugin for MP4/AVI/WebM rendering

Breaking Changes

None - all additions are backward compatible.

Technical Notes

  • The unified backend system automatically selects the best rendering backend based on file format and available dependencies
  • For GIF files, imageio is preferred for parallel rendering support
  • For MP4/video files, imageio is used if FFmpeg plugin is available, otherwise falls back to matplotlib
  • Parallel rendering is automatically disabled for short animations (<50 frames) to avoid overhead
  • The render_backend parameter accepts: 'auto' (default), 'imageio', or 'matplotlib'
  • JAX detection prevents fork-related deadlocks on Linux systems

Files Modified

  • pyproject.toml: Updated imageio dependency to include ffmpeg plugin
  • src/canns/analyzer/visualization/core/__init__.py: Added backend and rendering exports
  • src/canns/analyzer/visualization/core/config.py: Added render configuration options
  • src/canns/analyzer/visualization/energy_plots.py: Refactored to use unified backend (505 insertions)
  • src/canns/analyzer/visualization/spatial_plots.py: Refactored to use unified backend (254 insertions)
  • src/canns/analyzer/visualization/theta_sweep_plots.py: Refactored to use unified backend (449 insertions)
  • uv.lock: Updated dependencies

Total changes: 1,626 insertions, 195 deletions across 9 files

Full Changelog: v0.12.5...v0.12.6

Assets 2
Loading