Skip to content

v0.5.0: Major Restructuring to canns-lib

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 27 Oct 06:23
· 29 commits to master since this release
v0.5.0
e2b21d0

🚀 Release v0.5.0: Major Restructuring to canns-lib

This is a major restructuring release that transforms canns-ripser into canns-lib, a modular computational acceleration library for CANNS (Continuous Attractor Neural Networks).

⚠️ Breaking Changes

Package Renamed: canns-ripser → canns-lib

Migration Guide:

# ❌ Old API (v0.4.x and earlier)
import canns_ripser
result = canns_ripser.ripser(data, maxdim=2)

# ✅ New API (v0.5.0+)
from canns_lib.ripser import ripser
result = ripser(data, maxdim=2)

# Alternative import style
from canns_lib import ripser
result = ripser.ripser(data, maxdim=2)

🏗️ New Modular Architecture

Current Modules

  • canns_lib.ripser: High-performance topological data analysis
    • Full compatibility with ripser.py
    • Optimized Rust implementation
    • Mean speedup: 1.13x across benchmarks
    • Peak speedup: up to 1.82x

Coming Soon

  • canns_lib.fastann: Approximate nearest neighbor search
  • canns_lib.dynamics: Neural network dynamics computation
  • canns_lib.spatial: Spatial indexing and queries
  • And more computational accelerations for CANNS!

📦 What's Changed

Package Structure

  • Modular organization: Ripser is now a submodule under canns_lib.ripser
  • Rust codebase: Moved to crates/ripser/src/ for better organization
  • Python bindings: Updated to canns_lib._ripser_core
  • Future-ready: Infrastructure for adding new acceleration modules

Documentation

  • README: Completely rewritten to reflect modular library concept
  • CLAUDE.md: Updated with new architecture and development guidelines
  • Examples: Updated to use new import paths

CI/CD

  • Updated workflows for new package name
  • All tests migrated to new import structure
  • Release automation configured for PyPI publishing

✅ Maintained Compatibility

100% API Compatibility: All ripser functionality remains fully compatible with ripser.py. Only the import path has changed.

  • ✅ Same function signatures
  • ✅ Same return values
  • ✅ Same numerical accuracy
  • ✅ Full feature parity with ripser.py

📊 Performance Highlights

The ripser module continues to deliver excellent performance:

  • Mean speedup: 1.13x across 54 benchmarks vs ripser.py
  • Peak speedup: Up to 1.82x on certain datasets
  • Memory efficiency: 1.01x memory ratio (stable usage)
  • Perfect accuracy: 100% match with ripser.py results

Top Performing Scenarios

Dataset Type Configuration Speedup
Random N(0,I) d=2, n=500, maxdim=2 1.82x
Two moons n=400, noise=0.08, maxdim=2 1.77x
Random N(0,I) d=2, n=200, maxdim=2 1.72x

🔧 Installation

From PyPI

pip install canns-lib

From Source

git clone https://github.com/Routhleck/canns-lib.git
cd canns-lib
pip install maturin
maturin develop --release

🧪 Quick Start

import numpy as np
from canns_lib.ripser import ripser

# Generate sample data
data = np.random.rand(100, 3)

# Compute persistence diagrams
result = ripser(data, maxdim=2)
diagrams = result['dgms']

print(f"H0: {len(diagrams[0])} features")
print(f"H1: {len(diagrams[1])} features")
print(f"H2: {len(diagrams[2])} features")

📝 Technical Details

Commits in This Release

  • Restructure: canns-ripser → canns-lib
  • Fix CI workflow to use new canns_lib package structure
  • Fix typo in CANNs acronym in README.md
  • Fix test imports to use new canns_lib package structure
  • Bump version to 0.5.0 for major restructuring release

Repository Changes

  • Repository URL: Updated to https://github.com/Routhleck/canns-lib
  • Package name: canns-lib on PyPI
  • Module name: canns_lib in Python

🙏 Acknowledgments

Ripser Module

  • Ulrich Bauer: Original Ripser algorithm and C++ implementation
  • Christopher Tralie & Nathaniel Saul: ripser.py Python implementation
  • Rust community: Amazing ecosystem of high-performance libraries

📚 Resources

🤖 Generated with Claude Code

Assets 2
Loading