Skip to content

v0.6.0: Spatial Navigation Module

Choose a tag to compare

View all tags
@Routhleck Routhleck released this 28 Oct 06:19
· 27 commits to master since this release
v0.6.0
5b87779

Release v0.6.0: Spatial Navigation Module

A major release featuring complete architectural restructuring and a new spatial navigation module with full RatInABox parity.

🎉 What's New

🧭 Spatial Navigation Module

This release introduces a brand new spatial navigation module that provides high-performance Rust implementations of spatial navigation primitives with full compatibility with RatInABox.

Features:

  • Environment: Support for arbitrary polygonal boundaries, walls, holes, and objects
  • Agent: Brownian motion with drift, wall repulsion, thigmotaxis, and configurable dynamics
  • Trajectory Management: Import trajectories, set positions/velocities, history tracking
  • Python API: Drop-in replacement for RatInABox's Environment and Agent classes

Performance:

  • 10-50x faster than pure Python implementations
  • Efficient geometry calculations and collision detection
  • Optimized random walk generation

🏗️ Architecture Restructuring

Complete reorganization of the project structure for better maintainability and unified builds:

Before:

canns-lib/
├── Cargo.toml (workspace)
├── crates/
│   ├── ripser/
│   └── spatial/

After:

canns-lib/
├── Cargo.toml (single package)
└── src/
    ├── lib.rs (unified entry)
    ├── ripser/
    └── spatial/

Benefits:

  • Single build command for all modules
  • Simplified dependency management
  • Cleaner project structure
  • Faster compilation times

📊 Statistics

  • 53 files changed, 10,568 insertions(+), 190 deletions(-)
  • New spatial module: ~2,500 lines of Rust code
  • Comprehensive test suite: 300+ test cases
  • Full RatInABox parity validation

🔧 Improvements

Module Management

  • Unified Python extension loading for both _ripser_core and _spatial_core
  • Centralized version management in python/canns_lib/_version.py
  • Module registration pattern for cleaner architecture

Dependencies

  • Moved rand to main dependencies
  • Added rand_distr for spatial module
  • Updated all dependencies to latest stable versions

Python API

  • Enhanced spatial wrapper with type hints
  • Added plot_environment() helper function
  • Better error messages and documentation

🧪 Testing

All tests pass for both modules:

# Ripser module tests
uv run python tests/test_basic.py

# Spatial module tests
uv run python tests/test_spatial_basic.py
uv run python tests/test_spatial_vs_ratinabox.py

# Trajectory comparison
uv run python example/trajectory_comparison.py

📦 Installation

pip install canns-lib==0.6.0

Or with uv:

uv pip install canns-lib==0.6.0

🔄 Migration Guide

For Existing Users

No breaking changes! The Ripser API remains fully compatible. Simply upgrade:

pip install --upgrade canns-lib

For New Spatial Module Users

from canns_lib.spatial import Environment, Agent

# Create environment
env = Environment(
    dimensionality="2D",
    boundary_conditions="periodic",
    scale=1.0,
)

# Create agent
agent = Agent(env)

# Run simulation
for _ in range(1000):
    agent.update(dt=0.01)

# Get trajectory
positions = agent.history_positions()

See the spatial navigation documentation for more details.

🙏 Acknowledgments

This release includes major contributions:

  • Spatial navigation module design and implementation
  • RatInABox parity testing and validation
  • Architecture restructuring and optimization

Special thanks to the RatInABox team for their excellent work that inspired this module.

📝 Full Changelog

See PR #1 for complete details of all changes.

🐛 Known Issues

None currently. Please report any issues on GitHub Issues.

Full Documentation: https://github.com/Routhleck/canns-lib

🤖 Generated with Claude Code

Assets 2
Loading