mdadash

Latest release
Status
Community

Dashboard for tracking and analyzing live MD simulations with streaming.

mdadash is bound by a Code of Conduct.

Installation

To build mdadash from source, we highly recommend using virtual environments. If possible, we strongly recommend that you use Anaconda as your package manager. Below we provide instructions both for conda and for pip.

With conda

Ensure that you have conda installed.

Create a virtual environment and activate it:

conda create --name mdadash
conda activate mdadash

Install the development, testing and documentation dependencies:

conda env update --name mdadash --file devtools/conda-envs/dev_env.yaml
conda env update --name mdadash --file devtools/conda-envs/test_env.yaml
conda env update --name mdadash --file docs/requirements.yaml

Build this package from source:

pip install -e .

If you want to update your dependencies (which can be risky!), run:

conda update --all

And when you are finished, you can exit the virtual environment with:

conda deactivate

With pip

To build the package from source, run:

pip install .

If you want to create a development environment, install the dependencies required for tests and docs with:

pip install ".[dev,test,doc]"

Run

The frontend code needs to be built before running the backend server. This can be done as follows:

cd mdadash/frontend
npm install
npm run build

To run the dashboard server:

mdadash

To see the options available:

mdadash --help

Development

Frontend

Developer instruction for frontend code can be found here.

Backend

• Use the editable installation above (pip install -e .)

Tests

Frontend

npm run test:unit --prefix mdadash/frontend -- --run

Backend

pytest -v

Code Coverage

Frontend

cd mdadash/frontend
npx vitest --run --coverage

The coverage details will be shown on the console. Open coverage/index.html to view the interactive coverage report in the browser.

Backend

To see coverage output on the console:

pytest -v --cov=mdadash

To write coverage output to html file:

pytest -v --cov=mdadash --cov-report=html

Open htmlcov/index.html to view the coverage report in the browser.

Build

To build this package:

rm -rf mdadash.egg-info dist && python -m build

To verify the created wheel:

uv run --refresh --with path.to.whl mdadash

To check the created distribution:

twine check dist/*

Verify GitHub actions locally

GitHub actions can be verified locally using act.

Note that this requires Docker. Running on Mac needs an additional param --container-architecture linux/arm64. To bypass the repo name check, you can pass --env GITHUB_REPOSITORY=MDAnalysis/mdadash. Both these can be set in ~/.actrc as well.

To list the jobs:

act -l

To run a job (eg: pylint_check):

act -j pylint_check

To run all jobs:

act

Docs

Setting up the docs environment:

conda env update --name mdadash --file docs/requirements.yaml

Building docs locally:

cd docs
make clean && make html

Open docs/_build/html/index.html to view the docs in the browser.

Copyright

The mdadash source code is hosted at https://github.com/MDAnalysis/mdadash and is available under the MIT License (see the file LICENSE).

Copyright (c) 2026, MDAnalysis

Acknowledgements

Project based on the MDAnalysis Cookiecutter version 0.1. Please cite MDAnalysis when using mdadash in published work.