Prepare spatial plotting release 0.6.1

Author: Routhleck

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "canns-lib"
-version = "0.6.0"
+version = "0.6.1"
 edition = "2021"
 license = "Apache-2.0"
 authors = ["Sichao He <[email protected]>"]

README.md

@@ -85,9 +85,34 @@ Plots and CSV summaries are emitted to `benchmarks/spatial/outputs/`.
 - **Full parity** with RatInABox API (Environment, Agent, trajectory import/export)
 - **Polygon & hole support** with adaptive projection and wall vectors
 - **Parity comparison tools** in `example/trajectory_comparison.py`
+- **Visualization utilities**: drop-in replacements for RatInABox's plotting
+  helpers (trajectory, heatmaps, histograms)
 - **Benchmark scripts** for long-step drift and speedup under
   `benchmarks/spatial/`
 
+#### Visualization Helpers
+
+```python
+from canns_lib import spatial
+
+env = spatial.Environment(dimensionality="2D", boundary_conditions="solid")
+agent = spatial.Agent(env, rng_seed=2025)
+
+for _ in range(2_000):
+    agent.update(dt=0.02)
+
+# Trajectory with RatInABox-style colour fading and agent marker
+agent.plot_trajectory(color="changing", colorbar=True)
+
+# Other helpers mirror RatInABox naming
+agent.plot_position_heatmap()
+agent.plot_histogram_of_speeds()
+agent.plot_histogram_of_rotational_velocities()
+```
+
+See `example/spatial_plotting_demo.py` for a full script that produces the
+trajectory, heatmap, and histogram figures showcased above.
+
 ### 🚀 Coming Soon
 
 - **Dynamics**: High-performance dynamics computation for neural networks

example/spatial_plotting_demo.py

@@ -2,7 +2,7 @@
 """Demonstrate trajectory plotting helpers for canns_lib.spatial.Agent.
 
 The script mirrors RatInABox usage: we create an environment with walls and a
-central hole, simulate a stochastic agent, and save several plots:
+central hole, simulate two stochastic agents, and save several plots:
 
 - trajectory.png: path overlaid on the environment
 - heatmap.png: spatial occupancy heatmap
@@ -60,12 +60,24 @@
 def main() -> None:
     env = spatial.Environment(**ENVIRONMENT_PARAMS)
     agent = spatial.Agent(env, params=AGENT_PARAMS, rng_seed=2025, init_pos=[0.4, 0.2])
+    agent_two = spatial.Agent(
+        env,
+        params={**AGENT_PARAMS, "speed_std": 0.03},
+        rng_seed=2026,
+        init_pos=[0.75, 0.7],
+    )
 
     for _ in range(2000):
         agent.update(dt=0.02)
+        agent_two.update(dt=0.02)
 
     # Trajectory plot
-    fig, ax = agent.plot_trajectory()
+    fig, ax = agent.plot_trajectory(
+        color="changing",
+        colorbar=True,
+        decay_point_size=True,
+        plot_all_agents=True,
+    )
     fig.savefig(OUTPUT_DIR / "trajectory.png", dpi=150)
     plt.close(fig)
 

python/canns_lib/_version.py

@@ -1,3 +1,3 @@
 """Project-wide version string."""
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"