Learnable SDE for Movement Prediction

An object-oriented research framework for training, evaluating, and running learnable stochastic differential equation models.

The repository separates domain objects, model capabilities, estimators, inference engines, evaluation rules, application services, and infrastructure adapters. It includes a deterministic synthetic workflow, so installation and the public test suite do not require the private trajectory dataset.

Project status: research software. The segment-constant model, EM estimator, exact Gaussian inference, split-step inference, CRN inference, checkpoint round trip, and synthetic CLI workflow are implemented and tested. Components explicitly described as experimental or incomplete fail fast instead of silently falling back to another algorithm.

Python 3.10 or newer is required.

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[test]"

Train a small model on deterministic synthetic data:

learnable-sde train --config config.yaml --smoke \
  --checkpoint .local/checkpoints/smoke.pt

Generate a forecast from that checkpoint:

learnable-sde predict --config config.yaml \
  --checkpoint .local/checkpoints/smoke.pt \
  --x0 0 0 --horizons 60 120 --samples 100 --regime 0 \
  --output .local/outputs/forecast.json

The module form is equivalent when the console script is not installed:

python -m cli train --config config.yaml --smoke
python -m cli ablate --matrix
python -m cli ablate --verify

No research data, derived trajectory samples, or trained checkpoints are included. Configure local paths with environment variables:

LEARNABLE_SDE_DATA_ROOT=/path/to/trajectory-data
LEARNABLE_SDE_COND_ROOT=/path/to/condition-data
LEARNABLE_SDE_CHECKPOINT=/path/to/checkpoint-directory

On PowerShell:

$env:LEARNABLE_SDE_DATA_ROOT = "D:\datasets\trajectory-data"

When no environment variable is set, local-only paths under .local/ are used. That directory is ignored by Git. See DATA.md for the expected schema, split contract, and data-release boundary.

The public execution path is:

CLI -> ExperimentApplication -> registry -> model / estimator / inference
                          |      -> checkpoint and artifact adapters
                          +-> EvaluationPipeline -> inference / conditioning
                                                -> Evaluator -> scoring rules

Core interfaces:

• SDEModel: a standard torch.nn.Module with explicit model context.
• Estimator.fit(model, data, context) -> FitResult.
• InferenceEngine.forecast(model, request, context) -> Forecast.
• Evaluator: applies one canonical scoring-rule implementation.
• ExperimentApplication: owns component assembly and the compatible train/predict/evidence/evaluate, legacy forecast, and checkpoint use cases.
• AtomicRunStore: stages one run's artifacts and RunRecord, then publishes the non-overwriting run directory with a same-filesystem atomic rename.

See OOP_ARCHITECTURE.md for the code-anchored component map, object relationships, call sequence, I/O boundaries, and truthful implemented-versus-planned status. DESIGN.md records the wider target design and scientific constraints.

application/      use-case orchestration and runtime ownership
cli/              train, predict, and ablate commands
data/             data-source interfaces, loaders, paths, and validation
domain/           shared types, results, requests, and errors
estimation/       estimator interface and implementations
evaluation/       evaluators and scoring rules
inference/        inference interface and implementations
infrastructure/   checkpoint and artifact adapters
models/           SDE model interface and implementations
tests/            unit, characterization, and integration tests

python -m pytest -q
python -m experiments.smoke_test

Contribution workflow, commit message format, and pull-request requirements are documented in CONTRIBUTING.md. Known numerical and migration limitations are tracked in KNOWN_ISSUES.md.

For the purpose, checks, triggers, and release assets of GitHub Actions, see CI_CD.md.

The Lean proofs are maintained in learnable-sde-theory-to-predict-movement. Keeping the formal development separate gives it an independent toolchain, CI workflow, and release history.

Citation metadata is provided in CITATION.cff. No software license has been granted yet. Until the rights holder adds a LICENSE file, the source is available for inspection but no permission to copy, modify, or redistribute it is implied. See RELEASE_CHECKLIST.md.