Skip to content

Release v0.12.1: Animation Performance Optimization

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 27 Dec 11:20
· 186 commits to master since this release
v0.12.1
59e63c7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's New

🎨 11.2x Animation Performance Boost

  • MP4 encoding is now 36.8x faster than GIF (986 FPS vs 27 FPS)
  • Jupyter notebook display is 2x faster with HTML5 video (vs jshtml)
  • Blitting optimization provides 4.6x faster rendering for custom animations
  • New high-performance animation infrastructure with parallel rendering support

🔧 Code Quality & Organization

  • Refactored visualization core into dedicated core/ submodule
  • Fixed linting issues and addressed code review feedback
  • Improved module organization with backward compatibility

Major Features / Key Changes

🚀 Animation Performance Optimization

Complete animation workflow speedup (11.2x total):

  • MP4 vs GIF encoding: 36.8x faster encoding (986 FPS vs 27 FPS)
  • Jupyter HTML5 display: 2x faster rendering (1.3s vs 2.6s for 100 frames)
  • File size reduction: 36x smaller files (134 KB vs 4837 KB for notebook display)
  • Blitting optimization: 4.6x faster 2D animation rendering
  • Automatic fallback: Graceful degradation to jshtml when FFmpeg unavailable
from canns.analyzer.visualization import AnimationConfig, OptimizedAnimationWriter

# Fast MP4 encoding (recommended)
config = AnimationConfig(fps=30, quality='high')
writer = OptimizedAnimationWriter('output.mp4', fps=30, encoding_speed='balanced')

# Animation automatically uses optimal format
ani.save('animation.mp4')  # 36.8x faster than .gif

🏗️ New Core Animation Infrastructure

Modular architecture for high-performance animations:

  • core/animation.py: OptimizedAnimationBase class with blitting support
  • core/rendering.py: ParallelAnimationRenderer for multi-process rendering
  • core/writers.py: OptimizedAnimationWriter with automatic format detection
  • core/config.py: Unified PlotConfig and AnimationConfig classes
  • core/jupyter_utils.py: Jupyter integration with HTML5 video support
from canns.analyzer.visualization.core import (
    OptimizedAnimationBase,
    ParallelAnimationRenderer,
    AnimationConfig
)

# Use parallel rendering for long animations (>500 frames)
config = AnimationConfig(use_parallel=True, num_workers=4)
renderer = ParallelAnimationRenderer(num_workers=4)

🎯 Enhanced Bump Animation Functions

Improved CANN1D and CANN2D visualization:

  • cann1d.create_1d_bump_animation(): Optimized with geometry reuse
  • cann2d.plot_3d_bump_on_torus(): Enhanced with better frame computation
  • Better memory efficiency: Pre-computed geometries and color mappings
  • Progress tracking: tqdm integration for long animations

🔧 Code Quality Improvements

Fixed multiple issues identified in code review:

  • Removed global matplotlib backend setting that broke interactive sessions
  • Fixed import paths to match actual module structure
  • Added pickle limitation warnings for parallel rendering
  • Updated to importlib.util.find_spec() to avoid F401 lint warnings
  • Fixed docstring mismatches for better API clarity

New Components Added

  • src/canns/analyzer/visualization/core/__init__.py - Core module exports
  • src/canns/analyzer/visualization/core/animation.py - Optimized animation base class (245 lines)
  • src/canns/analyzer/visualization/core/rendering.py - Parallel rendering engine (276 lines)
  • src/canns/analyzer/visualization/core/writers.py - Video encoding optimization (438 lines)
  • src/canns/analyzer/visualization/core/jupyter_utils.py - Moved from parent directory

Technical Improvements

Performance Metrics

  • Encoding speed: MP4 at 986 FPS vs GIF at 27 FPS (36.8x faster)
  • Notebook display: HTML5 at 75 FPS vs jshtml at 38 FPS (2x faster)
  • Blitting rendering: 4.6x speedup for 2D animations
  • Combined workflow: 11.2x total performance improvement

Code Organization

  • Backward compatibility: All existing imports continue to work via re-exports
  • Module structure: Clear separation of core infrastructure from high-level APIs
  • Updated imports: 7 files updated to use new core/ structure
  • Documentation: Comprehensive performance guidelines in CLAUDE.md

Breaking Changes

None - all additions are backward compatible. Existing code will automatically benefit from performance improvements.

Technical Notes

  • FFmpeg requirement: HTML5 video display in Jupyter requires FFmpeg. Automatic fallback to jshtml if unavailable.
  • Parallel rendering: Experimental feature with pickle limitations for matplotlib objects. Use use_parallel=False if encountering issues.
  • Format recommendations:
    • Use MP4 for production (fastest, smallest, best quality)
    • Use GIF only for GitHub README inline display
    • HTML5 is now default for Jupyter notebooks (2x faster than jshtml)

Files Modified (26 total)

Core infrastructure:

  • src/canns/analyzer/visualization/core/ - New directory with 5 modules
  • src/canns/analyzer/visualization/__init__.py - Updated exports
  • CLAUDE.md - Added animation performance best practices (+192 lines)

Animation functions:

  • src/canns/analyzer/data/cann1d.py - Optimized bump animation
  • src/canns/analyzer/data/cann2d.py - Enhanced 3D visualization (+335 lines)

Import updates:

  • src/canns/analyzer/visualization/theta_sweep_plots.py
  • src/canns/analyzer/visualization/energy_plots.py
  • src/canns/analyzer/visualization/spatial_plots.py
  • tests/analyzer/test_jupyter_integration.py

Examples updated:

  • All example scripts now use MP4 format for better performance

Full Changelog: v0.12.0...v0.12.1

Assets 2
Loading