EXPERIMENT_GUIDE.md

Spiral Autoencoder Experiment Script

A configurable CLI tool for training autoencoders on spiral data and visualizing the latent space.

Usage

Basic usage (with defaults):

python3 scripts/spiral_autoencoder.py

With custom parameters:

python3 scripts/spiral_autoencoder.py \
  --hidden-dim 32 \
  --latent-dim 3 \
  --sample-fraction 0.2 \
  --noise-sigma 0.2 \
  --epochs 50 \
  --output-dir ./results

Available Options

Option	Type	Default	Description
--theta-max	float	6π	Maximum angle for spiral generation (radians)
--spiral-points	int	10000	Total number of spiral points to generate
--sample-fraction	float	0.1	Fraction of spiral points to sample for training (0-1)
--noise-sigma	float	0.1	Standard deviation of Gaussian noise added to samples
--hidden-dim	int	16	Hidden layer dimension in encoder/decoder
--latent-dim	int	2	Latent space dimension
--batch-size	int	128	Training batch size
--epochs	int	40	Number of training epochs
--learning-rate	float	0.001	Adam optimizer learning rate
--output-dir	str	.	Directory to save output plots
--seed	int	42	Random seed for reproducibility

Output Files

Each run generates the following plots in output-dir:

• training_history.png — Training and validation loss curves
• latent_space_2d.png — 2D visualization of latent space (if latent_dim >= 2)
• latent_space_3d.png — 3D visualization of latent space (if latent_dim >= 3)
• reconstructions.png — Comparison of input data vs reconstructions

Running Multiple Experiments

Use the provided bash script to run a series of experiments:

bash scripts/run_experiments.sh

This runs 5 different configurations and saves results to ./experiments/exp1_baseline, ./experiments/exp2_latent4, etc.

Logging

The script logs all important events (data generation, splitting, training, visualization) to the console. Log level can be controlled by modifying the logging configuration in the script.

Example Experiments

Varying latent dimension:

for latent_dim in 1 2 3 4 5; do
  python3 scripts/spiral_autoencoder.py \
    --latent-dim $latent_dim \
    --output-dir "./results/latent_dim_$latent_dim"
done

Varying noise levels:

for sigma in 0.01 0.05 0.1 0.25 0.5; do
  python3 scripts/spiral_autoencoder.py \
    --noise-sigma $sigma \
    --output-dir "./results/noise_$sigma"
done

Varying sample sizes:

for frac in 0.01 0.05 0.1 0.25 0.5; do
  python3 scripts/spiral_autoencoder.py \
    --sample-fraction $frac \
    --output-dir "./results/fraction_$frac"
done