Metadata-Version: 2.4
Name: ddmsoft
Version: 0.1.0
Summary: Native desktop tools for differential dynamic microscopy
Author: DDMSoft contributors
License-Expression: GPL-3.0-or-later
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: opencv-python
Requires-Dist: PySide6
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-qt; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# DDMSoft

<p align="center">
  <img src="https://raw.githubusercontent.com/duxfrederic/ddmsoft/main/logo/logo.png" alt="DDMSoft logo" width="180">
</p>

DDMSoft is a native desktop application for differential dynamic microscopy
(DDM): it reads microscopy videos, computes DDM matrices, fits relaxation
models, and provides interactive plots and exports.

DDMSoft was originally developed during a 2019 internship at RWTH Aachen,
organized by Jerome J. Crassous and funded by a BioSoft scholarship. The
original project page includes an introduction and examples:
<https://duxfrederic.github.io/ddmsoft/>.

## Features

- Fast conversion of microscopy videos to DDM matrices.
- Exploration and selection of matrices for further analysis.
- Wavenumber-dependent correlation-function plots for checking measurement
  quality.
- Multi-wavenumber fitting with single and double exponentials, stretched
  exponentials, cumulants, exponential-plus-flow models, and CONTIN.
- Tools for combining, averaging, exporting, and batch-fitting the large data
  sets produced by DDM analysis.

## Install and launch

DDMSoft supports Windows and Linux with Python 3.12, 3.13, or 3.14. A
standalone installer is not required.

```bash
python -m pip install ddmsoft
ddmsoft
```

To install a source checkout or release archive instead:

```bash
python -m pip install .
ddmsoft
```

Using a virtual environment is recommended. `pip` installs the Qt, NumPy,
SciPy, Matplotlib, and OpenCV dependencies.

## Input directory

Open a directory containing AVI videos and UTF-8 acquisition metadata. Use one
shared `.txt` file for all videos, or one stem-matched file per video. Required
values are frame rate in frames per second and pixel size in metres per pixel:

```text
framerate: 30
pixelsize: 1e-6
```

Existing legacy matrix sets in `ddm_matrices/` load without conversion when all
three files are present: `*_DDM_matrix.npy`, `*_deltaTs.npy`, and `*_QS.npy`.

## Primary workflow

1. Open the acquisition directory and review or edit frame rate and pixel size
   in the video table.
2. Choose whether to keep existing matrices or explicitly recompute them, then
   select lag sampling, frame-pair, and direction settings and click `Process`.
3. Select a matrix and inspect its DDM/correlation plot. Use the q and time
   sliders to choose the fit region.
4. Select a model, edit initial guesses or fixed parameters if needed, and run
   the fit.
5. Inspect matrix, correlation, fitted-parameter, amplitude, noise, diffusion,
   and optional hydrodynamic-radius plots; export the required data.

The q-min, q-max, time-min, and time-max slider values are **inclusive**. The
samples at both selected endpoints participate in fitting and plot markers.

The cumulant models fit the DLS field-correlation function directly. They use
`Gamma = D*q^2` with `D` in `m^2/s`, `mu2` as the second decay-rate cumulant in
`s^-2`, and `mu3` as the third decay-rate cumulant in `s^-3`. The dimensionless
cumulant PDI at a given q is `mu2 / Gamma^2`.

## Advanced workflows

- Set more than one direction part to compute legacy opposite-direction sectors
  over 180 degrees. Each sector is saved and selected as a normal matrix.
- Use `Tools` to split videos into time-dependent matrices. Every source frame
  is assigned to exactly one partition.
- Merge compatible lag ranges, average compatible lag-time groups, or batch-fit
  selected matrices from the `DDM matrix fitting` and `Batch, export` actions.
- Use `More Fitting > CONTIN` to scan one q value, inspect every alpha candidate,
  and export the selected candidate or the complete scan.
- Use `Tools > Concatenate videos` for optional ffmpeg-backed concatenation.

## Video codecs and ffmpeg

Video decoding uses OpenCV. Codec availability depends on the OpenCV build and
operating system, so an `.avi` extension does not guarantee that a stream can be
decoded. DDMSoft reports videos that cannot be opened, have no decodable frames,
or change frame shape. The current DDM calculation accepts square frames only;
crop or transcode rectangular video before processing.

Concatenation requires an external `ffmpeg` executable on `PATH`; it is not a
Python dependency. The operation uses stream copy rather than re-encoding, so
the selected videos must have compatible streams and container parameters.
Missing executables and ffmpeg failures are reported without committing a
partial output.

## Demo and benchmark

Generate a small synthetic demonstration dataset:

```bash
ddmsoft-demo ./ddmsoft-demo-data
```

Run the representative synthetic benchmark:

```bash
ddmsoft-benchmark --output ./ddmsoft-benchmark.json
```

These console scripts are included in the release tooling. The current release
qualification measurements are recorded in
[`docs/benchmark-results.json`](docs/benchmark-results.json).

## Release notes

- [Intentional scientific and compatibility changes](docs/scientific-changes.md)
- [Release qualification and manual checklist](docs/release-checklist.md)
- [Legacy parity inventory](docs/parity-checklist.md)
