Infer "auto" arguments from data

[TomGeorge1234]

This PR define automatic values for speed_prior and kernel_bandwidth, inferring them from data. It allows the user to leave them undefined and they will take on "sensible" (pinch of salt) values most of the time.

IMPORTANTLY I tested it below on all datasets in simple_demo and found the auto parameters gave decent performance (all gave positive change in BPS close to our "tuned" parameters). Nonetheless tuned parameters always did better and documentation is updated to warn against blindly using the auto values.

Summary

• Default kernel_bandwidth and speed_prior to "auto", joining the existing automatic bin_size default.
• Store resolved values as kernel_bandwidth_, speed_prior_, and bin_size_, save them in result metadata, and label inferred values in the fit summary.
• Simplify fit output with clearer fit/decode terminology and aligned train/validation metrics.
• Document inference in the README, show the installed SIMPL version in the demo, and add focused regression tests.

Automatic inference

bin_size="auto" uses 1/25 of the largest environment span:

$$ \Delta x = \frac{\max_d (x_d^{\max} - x_d^{\min})}{25}. $$

kernel_bandwidth="auto" uses the isotropic multivariate Scott estimate:

$$ h = \left(\frac{4}{D+2}\right)^{\frac{1}{D+4}} n^{-\frac{1}{D+4}} \left(\prod_{d=1}^{D}\sigma_d\right)^{\frac{1}{D}}, $$

bounded below by the grid resolution: kernel_bandwidth_ = max(h, bin_size_).

speed_prior="auto" uses mean behavioral speed:

$$ v = \frac{1}{T-1}\sum_{t=1}^{T-1} \frac{\lVert X_{t+1}-X_t\rVert_2}{t_{t+1}-t_t}. $$

Angular displacements are wrapped to the shortest step before calculating speed. Explicit numeric values override inference, while speed_prior=None continues to disable temporal smoothing.

Motivation

Provide scale-aware defaults for minimal, out-of-the-box fitting without hiding modeling choices. Resolved values remain visible and reproducible, and users can set a larger speed prior when neural dynamics evolve faster than measured behavior.

Validation

• ruff check src tests README.md examples/simpl_demo.ipynb
• pytest

Demo comparison

scripts/compare_demo_auto_params.py reruns the 1D and 2D models from simpl_demo.ipynb with their explicit
parameters and with automatic inference. Net validation bits per spike is the final value minus iteration 0;
the final column is auto minus current. HDC keeps its deliberately high speed_prior=100. The 3D and 4D
hand-reaching models are omitted to avoid impractically large automatic grids.

Example	KB current	KB auto	bin current	bin auto	speed current	speed auto	net val BPS current	net val BPS auto	BPS difference
Synthetic grid cells	0.025	0.052	0.020	0.040	0.400	0.093	2.112	1.717	-0.396
Real place cells	0.100	0.178	0.020	0.140	0.600	0.197	0.186	0.111	-0.075
Head-direction cells	0.200	0.251	0.063	0.251	100.000	100.000	0.312	0.309	-0.003
Hand reaching |pos|	0.300	0.080	0.100	0.080	3.000	1.036	0.033	0.023	-0.010
Hand reaching |vel|	0.300	0.080	0.100	0.080	3.000	2.619	0.024	0.022	-0.001
Hand reaching |acc|	0.300	0.080	0.100	0.080	3.000	3.632	0.023	0.022	-0.002
Hand reaching [x, y]	0.100	0.080	0.020	0.080	2.000	0.921	0.022	0.004	-0.017
Hand reaching [vx, vy]	0.100	0.080	0.020	0.080	2.000	2.679	0.017	0.014	-0.003
Hand reaching [ax, ay]	0.100	0.080	0.020	0.080	2.000	4.148	0.020	0.016	-0.004