BioFoundation

Copyright (C) 2025-2026 ETH Zurich, Switzerland. SPDX-License-Identifier: Apache-2.0. See LICENSE for details.

Authors: Thorir Mar Ingolfsson, Anna Tegon, Berkay Döner, Xiaying Wang, Matteo Fasulo, Danaé Broustail, Marija Zelic, Yawei Li, and Luca Benini.

TL;DR: Choose a model from the table below, install the training dependencies, set DATA_PATH and CHECKPOINT_DIR, then run python -u run_train.py +experiment=<MODEL>_pretrain or the matching fine-tuning experiment. Each model page links its Hugging Face weights and exact checkpoint command. ARES is separate and only needed for embedded deployment.

BioFoundation is a research and onboarding codebase for foundation models across EEG, sEMG, ECG, and PPG. It collects the model implementations, Hydra experiments, preprocessing tools, and pretrained releases behind five model families.

The training stack is built on PyTorch Lightning and Hydra. Embedded deployment through ARES is maintained as a separate toolchain inside the repository.

Model Zoo

Model	Signals	Architecture	Resources
FEMBA	EEG	Bidirectional Mamba	Paper / Hugging Face
LUNA	EEG	Query-unified Transformer	Paper / Hugging Face
TinyMyo	sEMG	Rotary Transformer	Paper / Hugging Face
LuMamba	EEG	Query-unified Mamba	Paper / Hugging Face
PanLUNA	EEG, ECG, PPG	Multimodal query-unified Transformer	Paper / Hugging Face

The machine-readable model_registry.py records the experiment names, papers, Hugging Face repositories, modalities, and batch metadata requirements for these families.

Quick Start

BioFoundation requires Python 3.11 or newer. Create an isolated environment and install the training dependencies:

git clone https://github.com/pulp-bio/BioFoundation.git
cd BioFoundation
conda create -n biofoundation python=3.11
conda activate biofoundation
pip install -r requirements.txt

With uv, the equivalent setup is:

uv venv --python 3.11
source .venv/bin/activate
uv pip install -r pyproject.toml --torch-backend=auto

Set the prepared data and experiment-output roots:

export DATA_PATH=/absolute/path/to/data
export CHECKPOINT_DIR=/absolute/path/to/experiments

Start a pre-training experiment:

python -u run_train.py +experiment=FEMBA_pretrain

Or fine-tune a downloaded checkpoint:

python -u run_train.py +experiment=LUNA_finetune /model=LUNA_base \
  pretrained_safetensors_path=/absolute/path/to/LUNA_base.safetensors

Choose another +experiment from the model registry. Before a long run, review the selected file in config/experiment and resolve its #CHANGEME values.

Repository Map

Path	Responsibility
biofoundation	Shared batch, environment, and model metadata contracts.
models	Foundation model implementations.
tasks	Lightning pre-training, classification, and regression tasks.
datasets	Dataset readers and sample contracts.
data_module	Lightning data modules and loader composition.
config	Hydra defaults, modules, and reproducible experiments.
make_datasets	Raw-data preprocessing and HDF5 conversion.
criterion	Training objectives.
tests	Fast repository and refactoring contracts.
ARES	Independent GAP9 and Siracusa deployment toolchain.

Documentation

• Documentation index
• Training and batch contracts
• Hydra configuration guide
• Dataset preparation
• Contribution guide
• Citations
• ARES deployment

Each model page linked from the model zoo contains its input assumptions, architecture, results, Hugging Face download, and fine-tuning example.

Development Checks

The fast suite checks model metadata, Hydra composition and targets, batch adapters, environment handling, documentation links, and Apache headers:

python -m unittest discover -s tests -p 'test_*.py' -v
python -m compileall -q biofoundation run_train.py models tasks datasets data_module \
  criterion schedulers util make_datasets tests

Numerical changes to models, losses, or datasets should also be tested with representative CPU or GPU batches.

Licensing and Support

The source code is licensed under Apache 2.0. Pretrained weights in the five PulpBio Hugging Face repositories are licensed under CC BY-ND 4.0; see the model cards for terms and checkpoint-specific details.

For questions and support, open an issue. For changes, start with CONTRIBUTING.md.