Metadata-Version: 2.4
Name: ladys
Version: 0.1.0
Summary: PyTorch benchmark scaffolding for latent neural dynamics models.
Author: Jon Huml
License-Expression: MIT
Project-URL: Homepage, https://zkunkworks.com/
Project-URL: Documentation, https://zkunkworks.com/ladys/
Project-URL: Repository, https://github.com/jonathanhuml/ladys
Project-URL: Issues, https://github.com/jonathanhuml/ladys/issues
Keywords: latent-dynamics,neuroscience,pytorch,benchmarking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2
Requires-Dist: scipy>=1.10
Requires-Dist: torch>=2.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Dynamic: license-file

# 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

```bash
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:

```bash
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:

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

## Scaling Benchmark

```bash
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

```bash
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.

```yaml
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>`:

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

Install the docs extra and serve the site locally:

```bash
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/`.
