Metadata-Version: 2.4
Name: ddalab
Version: 2.2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
License-File: LICENSE
Summary: Delay differential analysis of neurophysiological recordings: the ddalab command-line tool
Keywords: dda,delay-differential,eeg,time-series
Home-Page: https://github.com/sdraeger/DDALAB/tree/main/packages/dda-rs
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://sdraeger.github.io/DDALAB/
Project-URL: Issues, https://github.com/sdraeger/DDALAB/issues
Project-URL: Repository, https://github.com/sdraeger/DDALAB

# dda-rs

Pure Rust Delay Differential Analysis (DDA) engine and the `ddalab` command-line tool. The same crate runs in the browser as WebAssembly in the [DDALAB web application](https://sdraeger.github.io/DDALAB/).

All analysis runs through the Rust engine directly; nothing shells out to a native DDA binary.

## Command-line tool

Install it as a Python tool (the wheel carries the `ddalab` executable only) or download an archive and its `.sha256` file from [GitHub Releases](https://github.com/sdraeger/DDALAB/releases):

```bash
uv tool install ddalab
ddalab inspect --file recording.edf
ddalab run --file recording.edf --variants ST --wl 1000 --ws 200 --delays 7 10 --bundle out
```

It reads EDF, BDF, BrainVision and delimited text. `ddalab --help` lists the other commands (`batch`, `variants`, `validate`, `samples`, `info`).

## Features

- Pure Rust execution for DDA variants and CCD extensions
- Typed request/response API with `serde`
- Built-in variant metadata and SELECT-mask helpers
- Configurable solver backend:
  - `RobustSvd` for the default numerically stable path
  - `NativeCompatSvd` for the native-compatible SVD path
- Optional batched CUDA acceleration for ST, CT, CD, DE, and SY

## Rust library

```toml
[dependencies]
dda-rs = "2.2.0"
```

## Quick Start

```rust
use dda_rs::{
    run_request_on_matrix, AlgorithmSelection, DDARequest, DelayParameters, PreprocessingOptions,
    TimeRange, WindowParameters,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request = DDARequest {
        file_path: "synthetic.csv".to_string(),
        channels: Some(vec![0, 1, 2]),
        time_range: TimeRange {
            start: 0.0,
            end: 511.0,
        },
        preprocessing_options: PreprocessingOptions {
            highpass: None,
            lowpass: None,
        },
        algorithm_selection: AlgorithmSelection {
            enabled_variants: vec!["ST".to_string(), "CD".to_string()],
            select_mask: None,
        },
        window_parameters: WindowParameters {
            window_length: 128,
            window_step: 64,
            ct_window_length: None,
            ct_window_step: None,
        },
        delay_parameters: DelayParameters { delays: vec![1, 2] },
        ct_channel_pairs: None,
        cd_channel_pairs: None,
        model_parameters: None,
        model_terms: None,
        variant_configs: None,
        sampling_rate: None,
    };

    let samples = (0..512)
        .map(|t| {
            let x = t as f64 * 0.03;
            vec![x.sin(), (1.7 * x).cos(), (0.5 * x).sin()]
        })
        .collect::<Vec<_>>();

    let result = run_request_on_matrix(&request, &samples, None)?;
    println!("analysis id: {}", result.id);
    Ok(())
}
```

## Solver Backends

The Rust engine exposes two SVD backends through `PureRustOptions::svd_backend`:

- `SvdBackend::RobustSvd`
  - default
  - uses nalgebra SVD
  - preferred for real analysis
- `SvdBackend::NativeCompatSvd`
  - uses the native-compatible SVD kernel ported into Rust
  - useful when comparing against historical native-binary behavior

## CUDA

CPU execution remains the default. Build the optional CUDA backend and select a device with:

```bash
cargo run --release --features cuda -- run --file data.csv --channels 0 1 --device cuda
```

`--device cuda:N` selects device `N`. The CUDA build dynamically loads the NVIDIA driver and cuBLAS. Compilation does not require a local CUDA toolkit; execution requires a working NVIDIA CUDA installation. The implementation batches same-shaped `f64` regressions and computes predictions and residual norms on the GPU. Rank-deficient regressions fall back to the CPU SVD solver. Rust-only CCD extensions continue to use their existing CPU implementations.

Library users configure the same backend through `PureRustOptions`:

```rust
use dda_rs::{ComputeDevice, PureRustOptions, PureRustRunner};

let runner = PureRustRunner::new(PureRustOptions {
    compute_device: ComputeDevice::Cuda(0),
    ..PureRustOptions::default()
});
```

## Modules

- `engine`: core DDA and CCD execution
- `types`: request/response structures
- `variants`: variant metadata and SELECT-mask utilities
- `network_motifs`: motif analysis helpers
- `profiling`: profiling helpers
- `error`: error types

## License

MIT

