Kolmogorov-Arnold Networks (KAN) for Traversability Analysis

This repository provides an implementation of Kolmogorov-Arnold Networks (KAN) tailored for 3D point cloud traversability analysis. KANs replace standard linear weights with learnable 1D B-spline activation functions along edges, offering high interpretability and efficiency for geometric and radiometric feature classification.

---

🌟 Key Features

• Flexible Feature Modes: Train using geometric features (geom), geometric + remission features (geom+remission), or all features (all).
• Coarse-to-Fine Grid Refinement: Multi-stage training pipeline starting with coarse B-spline grids, followed by automated pruning of redundant weights and progressive grid refinement.
• Direct Deep Learning Evaluation: Evaluate trained KAN models directly using PyTorch (test_kan.py).
• Symbolic Formula Extraction: Extract interpretable mathematical equations from trained KAN models with user-defined decimal precision (produce_kan_formula.py).
• Pure NumPy Formula Evaluation: Evaluate extracted symbolic equations with high speed using vectorized NumPy modules without needing PyTorch (test_kan_formula.py).
• Configurable KAN Architecture: Easily tune grid resolution (--grid), hidden dimensions (--hidden_size), and spline degree (--k).
• Robust Dataset Handling: Supports dataset subsampling for rapid iteration, standardized dataset normalization, and flexible train/valid/test binary split configurations (automatically skipping test evaluation if test splits are unavailable).
• Comprehensive Evaluation: Computes ROC AUC, PR AUC, Accuracy, Balanced Accuracy, positive/negative IoU, positive/negative F1 score, mIoU, and mF1.

---

⚙️ Installation & Requirements

Ensure you have Python 3.8+ installed along with PyTorch, SymPy, and common scientific libraries:

pip install torch numpy scipy sympy scikit-learn tqdm

Clone the pykan repository:

git clone https://github.com/kindxiaoming/pykan
cd pykan
git checkout v0.2.8
pip install -e .
cd ..

# we extended the symbolic library with some additional functions, so we need to patch the original pykan/kan/utils.py file
mv utils.py pykan/kan/utils.py

---

📁 Dataset Format

The dataset loaders (dataset.py) expect binary files (.bin) containing float32 arrays reshaped into -1 x 37 matrix columns (36 feature dimensions + 1 binary traversability label).

Files must follow the naming convention:

• <basename>_train.bin (Required)
• <basename>_valid.bin (Required)
• <basename>_test.bin (Optional — if not present, testing evaluation is gracefully skipped)

Example:

data/
├── eastpark_feats_train.bin
├── eastpark_feats_valid.bin
└── eastpark_feats_test.bin

---

🚀 Usage Guide

1. Training a Model

To start training with default settings (grid size = 8, hidden size = 24, geometric mode):

python train.py --dataset_path /path/to/data --basename eastpark_feats --logdir ./logs

2. Evaluating the KAN Model (PyTorch)

Evaluate the trained KAN checkpoint directly on validation and test datasets:

python test_kan.py \
  --dataset_path /path/to/data \
  --basename eastpark_feats \
  --mode geom \
  --logdir ./logs

3. Extracting Symbolic Formulas

Extract symbolic mathematical equations from the trained KAN checkpoint and export them into a standalone Python file (kanformula_03.py):

python produce_kan_formula.py \
  --dataset_path /path/to/data \
  --basename eastpark_feats \
  --mode geom \
  --logdir ./logs \
  --decimals 3

4. Evaluating Extracted Symbolic Formulas (NumPy)

Run fast evaluation of the exported symbolic formula using pure NumPy, finding the optimal threshold on validation data and testing performance:

python test_kan_formula.py \
  --dataset_path /path/to/data \
  --basename eastpark_feats \
  --mode geom \
  --logdir ./logs \
  --decimals 3

---

📋 Command-Line Arguments Reference

Argument	Type	Default	Description
--dataset_path	str	Required	Path to the directory containing binary dataset files.
--basename	str	eastpark_feats	Prefix for dataset files (e.g. eastpark_feats for eastpark_feats_train.bin).
--mode	str	geom	Feature selection mode: geom (17 features), geom+remission (29 features), or all (all features).
--grid, --grid_size	int	8	Initial B-spline grid resolution for KAN layers.
--hidden_size	int	24	Number of hidden units in KAN layer.
--logdir	str	./logs	Output directory for saving model checkpoints (.pth), logs, and formula files.
--decimals	int	3	Number of decimal places to round extracted symbolic formula coefficients.
--subsample	int	-1	Number of training samples to subsample (-1 to use full dataset).
--lr	float	0.01	Initial learning rate.
--weight_decay	float	1e-5	Weight decay coefficient.
--batch_size	int	50000	DataLoader batch size.
--k	int	8	B-spline polynomial order.
--threshold	float	None	Custom evaluation threshold (default: automatically finds optimal threshold on validation set).

---

📈 Model Checkpointing & Formula Files

• Model checkpoints are automatically named based on the selected mode:
  • Mode geom $\rightarrow$ logs/best_model_geom.pth
  • Mode geom+remission $\rightarrow$ logs/best_model_geom_remission.pth
  • Mode all $\rightarrow$ logs/best_model_all.pth
• Extracted formula files are saved as:
  • logs/kanformula_03.py (for --decimals 3)