vascularsim 0.1.0__tar.gz

vascularsim-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Training artifacts
+checkpoints/
+*.zip
+*.pt
+*.pth
+
+# Build
+*.so

vascularsim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MicroBot Intelligence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vascularsim-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: vascularsim
+Version: 0.1.0
+Summary: Open-source vascular microbot simulation platform for autonomous surgical microbot navigation
+Project-URL: Repository, https://github.com/HassDhia/vascularsim
+Project-URL: Documentation, https://github.com/HassDhia/vascularsim#readme
+Author-email: Hass <hass@microbotintelligence.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: gymnasium
+Requires-Dist: networkx
+Requires-Dist: numpy
+Requires-Dist: pyvista
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: train
+Requires-Dist: stable-baselines3>=2.0; extra == 'train'
+Description-Content-Type: text/markdown
+
+# VascularSim
+
+Open-source simulation platform for autonomous surgical microbot navigation through vascular networks.
+
+VascularSim provides a complete stack for training RL agents to navigate blood vessel graphs: TubeTK data ingestion, Gymnasium environments with physics-based observations, analytical hemodynamics and magnetic field models, a neural flow surrogate, and a benchmark suite across 5 difficulty tiers.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+With RL training support (requires PyTorch):
+
+```bash
+pip install -e ".[train]"
+```
+
+Development (includes pytest):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Load a vascular graph and explore it
+
+```python
+from vascularsim import VascularGraph
+from vascularsim.benchmarks import make_benchmark_graph
+
+# Create a benchmark vascular graph (tier 1 = straight vessel, 20 nodes)
+graph = make_benchmark_graph(tier=1, seed=42)
+
+print(f"Nodes: {graph.graph.number_of_nodes()}")
+print(f"Edges: {graph.graph.number_of_edges()}")
+
+# Access node properties
+for node in list(graph.graph.nodes)[:3]:
+    pos = graph.get_node_pos(node)
+    radius = graph.get_node_radius(node)
+    print(f"  {node}: pos={pos}, radius={radius:.4f}")
+```
+
+### 2. Run the RL environment
+
+```python
+import gymnasium as gym
+from vascularsim import VascularGraph
+from vascularsim.benchmarks import make_benchmark_graph
+
+# Create a graph and pass it to the environment
+graph = make_benchmark_graph(tier=1, seed=42)
+env = gym.make("VascularNav-v0", graph=graph)
+obs, info = env.reset()
+print(f"Observation keys: {list(obs.keys())}")
+
+# Step through the environment
+for _ in range(10):
+    action = env.action_space.sample()
+    obs, reward, terminated, truncated, info = env.step(action)
+    if terminated:
+        print(f"Reached target!")
+        break
+
+env.close()
+
+# Physics-aware environments (use default graph if none provided)
+flow_env = gym.make("FlowAwareNav-v0")
+mag_env = gym.make("MagneticNav-v0")
+```
+
+### 3. Train a PPO agent and evaluate
+
+```bash
+# Train PPO for 200k steps (CPU, ~68 seconds)
+python -m vascularsim.training.train --timesteps 200000 --output-dir ./checkpoints
+
+# Evaluate trained agent vs random baseline
+python -m vascularsim.training.evaluate --model-path ./checkpoints/ppo_vascularnav.zip
+
+# Run benchmark suite across all 5 difficulty tiers
+python -m vascularsim.benchmarks.runner --agent random --tiers 1 2 3 4 5 --output results.json
+```
+
+## Physics Modules
+
+### Hemodynamics
+
+Analytical Hagen-Poiseuille flow with Murray's law bifurcation distribution:
+
+```python
+from vascularsim.physics import compute_hemodynamics
+
+result = compute_hemodynamics(graph)
+# result.edge_velocities   — flow velocity per edge (mm/s)
+# result.edge_pressures    — pressure drop per edge (Pa)
+# result.edge_wall_shear   — wall shear stress per edge (Pa)
+# result.node_pressures    — pressure at each node (Pa)
+```
+
+### Magnetic Fields
+
+Helmholtz coil pairs with gradient-based force and torque on magnetic microbots:
+
+```python
+from vascularsim.physics import CoilSystem, magnetic_force, magnetic_torque
+import numpy as np
+
+coils = CoilSystem.three_axis(coil_radius=0.05, current=1.0)
+point = np.array([0.0, 0.0, 0.0])
+
+field = coils.field_at(point)          # Tesla
+gradient = coils.gradient_at(point)    # T/m (3x3 Jacobian)
+
+moment = np.array([0.0, 0.0, 1e-12])  # A*m^2
+force = magnetic_force(gradient, moment)
+torque = magnetic_torque(field, moment)
+```
+
+### Neural Flow Surrogate
+
+Pure NumPy MLP trained in log-space for fast flow prediction (<10% MRE):
+
+```python
+from vascularsim.physics import FlowSurrogate
+
+surrogate = FlowSurrogate.from_graph(graph)
+predicted_velocities = surrogate.predict(features)
+```
+
+## Benchmark Tiers
+
+| Tier | Name | Nodes | Topology |
+|------|------|-------|----------|
+| 1 | Straight | 20 | Linear vessel |
+| 2 | Bifurcation | 35 | Single branch point |
+| 3 | Tree | 50 | Two-level branching |
+| 4 | Ring | 43 | Vessel loops |
+| 5 | Dense Mesh | 147 | Sub-branches and dead-ends |
+
+## Architecture
+
+```
+vascularsim/
+  data/          TubeTK .tre parser + Girder API downloader
+  graph.py       VascularGraph (NetworkX DiGraph wrapper)
+  envs/          Gymnasium environments
+    vascular_nav.py    VascularNav-v0 (base discrete navigation)
+    flow_nav.py        FlowAwareNav-v0 (+ hemodynamic observations)
+    magnetic_nav.py    MagneticNav-v0 (+ magnetic field observations)
+    wrappers.py        FlatNavObservation (Dict→Box for SB3)
+  physics/       Analytical physics models
+    hemodynamics.py    Poiseuille flow + Murray's law + WSS
+    magnetic.py        Helmholtz coils + force/torque
+    surrogate.py       Neural MLP flow surrogate
+  training/      RL training pipeline
+    train.py           PPO training CLI
+    evaluate.py        Evaluation + comparison CLI
+  benchmarks/    Benchmark suite
+    environments.py    5 difficulty tier generators
+    runner.py          Benchmark runner CLI
+```
+
+## Test Suite
+
+```bash
+pytest tests/ -v    # 139 tests, ~2 seconds
+```
+
+## License
+
+MIT

vascularsim-0.1.0/README.md

@@ -0,0 +1,174 @@
+# VascularSim
+
+Open-source simulation platform for autonomous surgical microbot navigation through vascular networks.
+
+VascularSim provides a complete stack for training RL agents to navigate blood vessel graphs: TubeTK data ingestion, Gymnasium environments with physics-based observations, analytical hemodynamics and magnetic field models, a neural flow surrogate, and a benchmark suite across 5 difficulty tiers.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+With RL training support (requires PyTorch):
+
+```bash
+pip install -e ".[train]"
+```
+
+Development (includes pytest):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Load a vascular graph and explore it
+
+```python
+from vascularsim import VascularGraph
+from vascularsim.benchmarks import make_benchmark_graph
+
+# Create a benchmark vascular graph (tier 1 = straight vessel, 20 nodes)
+graph = make_benchmark_graph(tier=1, seed=42)
+
+print(f"Nodes: {graph.graph.number_of_nodes()}")
+print(f"Edges: {graph.graph.number_of_edges()}")
+
+# Access node properties
+for node in list(graph.graph.nodes)[:3]:
+    pos = graph.get_node_pos(node)
+    radius = graph.get_node_radius(node)
+    print(f"  {node}: pos={pos}, radius={radius:.4f}")
+```
+
+### 2. Run the RL environment
+
+```python
+import gymnasium as gym
+from vascularsim import VascularGraph
+from vascularsim.benchmarks import make_benchmark_graph
+
+# Create a graph and pass it to the environment
+graph = make_benchmark_graph(tier=1, seed=42)
+env = gym.make("VascularNav-v0", graph=graph)
+obs, info = env.reset()
+print(f"Observation keys: {list(obs.keys())}")
+
+# Step through the environment
+for _ in range(10):
+    action = env.action_space.sample()
+    obs, reward, terminated, truncated, info = env.step(action)
+    if terminated:
+        print(f"Reached target!")
+        break
+
+env.close()
+
+# Physics-aware environments (use default graph if none provided)
+flow_env = gym.make("FlowAwareNav-v0")
+mag_env = gym.make("MagneticNav-v0")
+```
+
+### 3. Train a PPO agent and evaluate
+
+```bash
+# Train PPO for 200k steps (CPU, ~68 seconds)
+python -m vascularsim.training.train --timesteps 200000 --output-dir ./checkpoints
+
+# Evaluate trained agent vs random baseline
+python -m vascularsim.training.evaluate --model-path ./checkpoints/ppo_vascularnav.zip
+
+# Run benchmark suite across all 5 difficulty tiers
+python -m vascularsim.benchmarks.runner --agent random --tiers 1 2 3 4 5 --output results.json
+```
+
+## Physics Modules
+
+### Hemodynamics
+
+Analytical Hagen-Poiseuille flow with Murray's law bifurcation distribution:
+
+```python
+from vascularsim.physics import compute_hemodynamics
+
+result = compute_hemodynamics(graph)
+# result.edge_velocities   — flow velocity per edge (mm/s)
+# result.edge_pressures    — pressure drop per edge (Pa)
+# result.edge_wall_shear   — wall shear stress per edge (Pa)
+# result.node_pressures    — pressure at each node (Pa)
+```
+
+### Magnetic Fields
+
+Helmholtz coil pairs with gradient-based force and torque on magnetic microbots:
+
+```python
+from vascularsim.physics import CoilSystem, magnetic_force, magnetic_torque
+import numpy as np
+
+coils = CoilSystem.three_axis(coil_radius=0.05, current=1.0)
+point = np.array([0.0, 0.0, 0.0])
+
+field = coils.field_at(point)          # Tesla
+gradient = coils.gradient_at(point)    # T/m (3x3 Jacobian)
+
+moment = np.array([0.0, 0.0, 1e-12])  # A*m^2
+force = magnetic_force(gradient, moment)
+torque = magnetic_torque(field, moment)
+```
+
+### Neural Flow Surrogate
+
+Pure NumPy MLP trained in log-space for fast flow prediction (<10% MRE):
+
+```python
+from vascularsim.physics import FlowSurrogate
+
+surrogate = FlowSurrogate.from_graph(graph)
+predicted_velocities = surrogate.predict(features)
+```
+
+## Benchmark Tiers
+
+| Tier | Name | Nodes | Topology |
+|------|------|-------|----------|
+| 1 | Straight | 20 | Linear vessel |
+| 2 | Bifurcation | 35 | Single branch point |
+| 3 | Tree | 50 | Two-level branching |
+| 4 | Ring | 43 | Vessel loops |
+| 5 | Dense Mesh | 147 | Sub-branches and dead-ends |
+
+## Architecture
+
+```
+vascularsim/
+  data/          TubeTK .tre parser + Girder API downloader
+  graph.py       VascularGraph (NetworkX DiGraph wrapper)
+  envs/          Gymnasium environments
+    vascular_nav.py    VascularNav-v0 (base discrete navigation)
+    flow_nav.py        FlowAwareNav-v0 (+ hemodynamic observations)
+    magnetic_nav.py    MagneticNav-v0 (+ magnetic field observations)
+    wrappers.py        FlatNavObservation (Dict→Box for SB3)
+  physics/       Analytical physics models
+    hemodynamics.py    Poiseuille flow + Murray's law + WSS
+    magnetic.py        Helmholtz coils + force/torque
+    surrogate.py       Neural MLP flow surrogate
+  training/      RL training pipeline
+    train.py           PPO training CLI
+    evaluate.py        Evaluation + comparison CLI
+  benchmarks/    Benchmark suite
+    environments.py    5 difficulty tier generators
+    runner.py          Benchmark runner CLI
+```
+
+## Test Suite
+
+```bash
+pytest tests/ -v    # 139 tests, ~2 seconds
+```
+
+## License
+
+MIT

vascularsim-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vascularsim"
+version = "0.1.0"
+description = "Open-source vascular microbot simulation platform for autonomous surgical microbot navigation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Hass", email = "hass@microbotintelligence.dev" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy",
+    "networkx",
+    "gymnasium",
+    "pyvista",
+    "requests",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "build"]
+train = ["stable-baselines3>=2.0"]
+
+[project.urls]
+Repository = "https://github.com/HassDhia/vascularsim"
+Documentation = "https://github.com/HassDhia/vascularsim#readme"
+
+[project.scripts]
+vascularsim-train = "vascularsim.training.train:main"
+vascularsim-evaluate = "vascularsim.training.evaluate:main"
+vascularsim-benchmark = "vascularsim.benchmarks.runner:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vascularsim"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vascularsim-0.1.0/src/vascularsim/__init__.py

@@ -0,0 +1,24 @@
+"""VascularSim - Open-source vascular microbot simulation platform.
+
+Provides tools for simulating autonomous microbot navigation through
+vascular networks, including:
+
+- Graph-based vascular anatomy representation
+- Gymnasium RL environments (VascularNav-v0, FlowAwareNav-v0, MagneticNav-v0)
+- Analytical hemodynamics (Poiseuille flow, Murray's law)
+- Magnetic field models (Helmholtz coils, gradient force, torque)
+- Neural flow surrogate for real-time prediction
+- PPO training pipeline and benchmark suite
+"""
+
+__version__ = "0.1.0"
+
+from vascularsim.graph import VascularGraph
+
+# Register Gymnasium environments on package import
+import vascularsim.envs  # noqa: F401
+
+__all__ = [
+    "__version__",
+    "VascularGraph",
+]

vascularsim-0.1.0/src/vascularsim/benchmarks/__init__.py

@@ -0,0 +1,6 @@
+"""Benchmark environments and runner for VascularSim."""
+
+from vascularsim.benchmarks.environments import TIER_NAMES, make_benchmark_graph
+from vascularsim.benchmarks.runner import run_benchmark, save_results
+
+__all__ = ["TIER_NAMES", "make_benchmark_graph", "run_benchmark", "save_results"]