LaDyS (Latent Dynamical Systems) Package

PyTorch benchmark scaffolding for latent variable models of neural dynamics.

The first API pass standardizes model construction, training/reporting contracts, and a Lorenz synthetic dataset. Models accept (batch, time, neurons) tensors in forward.

Initial Examples

• ladys.models.cassm: thin adapter around the upstream sparse CASSM KalmanFilterSmoother implementation. Install the original cassm package or the local CASSM repository before constructing this model.
• ladys.models.gpfa: Gaussian-observation GPFA with FA initialization, EM updates, and RBF GP timescale learning. One full-dataset E/M update is treated as one benchmark epoch.

References Inspected

• Local planning note: /Users/jonathanhuml/Desktop/npdb.md
• CASSM Lorenz data source: jonathanhuml/cassm/src/cassm/datasets
• Local GPFA-MATLAB reference: /Users/jonathanhuml/Desktop/gpfa-matlab

Smoke Usage

PYTHONPATH=src python3 examples/smoke_compare.py

Public Experiment API

LaDyS is organized around three public pieces:

• ladys.models: model configs build PyTorch nn.Module instances and carry their optimization settings.
• ladys.data.DataModule: creates PyTorch train/validation datasets and dataloaders.
• ladys.Experiment: gathers data, model, training, evaluation metrics, and artifacts into one inspectable run folder.

Run the canonical CLI path with a dataset and model:

ladys run -d lorenz -m cassm

The run folder includes config.json, history.csv, metrics.json, predictions.npz, model.pt, and report.md. The CLI also accepts full YAML experiment configs:

ladys run -c configs/experiment/gpfa_lorenz.yaml
ladys list datasets
ladys list models

Scaling Benchmark

PYTHONPATH=src python3 scripts/benchmark_lorenz_scaling.py \
  --models cassm gpfa \
  --neurons 10 100 1000 \
  --seeds 1

The script writes lorenz_scaling_results.csv, lorenz_scaling_results.npy, and time_vs_neurons.png under artifacts/lorenz_scaling/.

Loss-Curve Benchmark

PYTHONPATH=src python3 scripts/benchmark_lorenz_loss_curves.py \
  --models cassm gpfa \
  --neurons 100 \
  --epochs 30

The script writes lorenz_loss_history.csv, test_rate_mse_curves.png, test_objective_curves.png, train_test_objective_curves.png, and per-model held-out rate trace plots/CSVs under artifacts/lorenz_loss_curves/.

Preprocessing

Experiment YAML files can include a preprocessing block. The benchmark scripts apply this to dataset observations before models see them, while leaving Lorenz ground-truth rates unchanged for MSE metrics.

preprocessing:
  observations:
    name: smooth_firing_rate
    sampling_precision: 20.0
    kern_sd_ms: 50.0

configs/experiment/cassm_lorenz.yaml enables this CASSM-style spike smoothing. configs/experiment/gpfa_lorenz.yaml leaves observations raw.

See docs/model_output_contract.md for the forward-output convention. See docs/optimizer_contract.md for the benchmark epoch definition.

Documentation Site

Docs source lives under docs/ and is configured by mkdocs.yml. Model pages under docs/models/ are generated from model class docstrings and config defaults. Images referenced from model docstrings should live under docs/assets/ and can be linked as assets/<filename>:

python scripts/generate_model_docs.py
python scripts/generate_model_docs.py --check

Install the docs extra and serve the site locally:

pip install -e ".[docs]"
mkdocs serve

The GitHub Pages workflow publishes the root homepage at https://zkunkworks.com/ from website/ and the generated documentation at https://zkunkworks.com/ladys/.