DecNefSimulator: A Modular, Interpretable Framework for Decoded Neurofeedback Simulation Using Generative Models
In compliance with FAIR practices, DecNefSimulator is registred in the NITRC public software registry, here
I am working on pip packaging. Stay tuned! 😺
Decoded Neurofeedback (DecNef) is a flourishing non-invasive approach to brain modulation with wide-ranging applications in neuromedicine and cognitive neuroscience. However, progress in DecNef research remains constrained by subject-dependent learning variability, reliance on indirect measures to quantify progress, and the high cost and time demands of experimentation.
We present DecNefSimulator, a modular and interpretable simulation framework that formalizes DecNef as a machine learning problem. Beyond providing a virtual laboratory, DecNefSimulator enables researchers to model, analyze and understand neurofeedback dynamics. Using latent variable generative models as simulated participants, DecNefSimulator allows direct observation of internal cognitive states and systematic evaluation of how different protocol designs and subject characteristics influence learning.
We demonstrate how this approach can (i) reproduce empirical phenomena of DecNef learning, (ii) identify conditions under which DecNef feedback fails to induce learning, and (iii) guide the design of more robust and reliable DecNef protocols in silico before human implementation.
In summary, DecNefSimulator bridges computational modeling and cognitive neuroscience, offering a principled foundation for methodological innovation, robust protocol design, and ultimately, a deeper understanding of DecNef-based brain modulation.
If this work has been useful to you, please include a citation in your publication 😊
@article{olza2026decnefsimulator,
title={DecNefSimulator: A Modular, Interpretable Framework for Decoded Neurofeedback Simulation Using Generative Models},
author={Olza, Alexander and Santana, Roberto and Soto, David},
eprint={2511.14555},
archivePrefix={arXiv},
year={2026},
url={https://arxiv.org/abs/2511.14555}
}In our paper, we model the human participant with a VAE and a simple learning behaviour, but other researchers can implement new custom models acording to their expert knowledge. DecNefSimulator is highly customizable, and we encourage users to implement their custom components.
Click here to learn the basic usage!
This project uses Python 3.10. We recommend using pip to manage dependencies. We make use of pytorch and have conducted our experiments on a NVIDIA GeForce RTX 2080 GPU; however, the code is prepared to run in CPU as well.
The auxiliary repository DecNefSimulator_install provides an installation script (install.sh), and is also be used to manage new dependencies during active development. Given that Python 3 and pip are available, DecNefSimulator is set up from scratch in a dedicated environment by running the installation script. We kindly advise you to follow that procedure.
You may click this dropdown for a summary of what will happen during the install.
1. External repos [MindSimulator](https://github.com/Noirebao/MindSimulator) and [MindEye2](https://github.com/MedARC-AI/MindEyeV2) will be cloned 2. Required packages will be installed via pip. This includes: - scikit-learn, pytorch and other Machine Learning libraries - nilearn and nibabel: neuroimaging libraries - matplotlib, seaborn and other plotting libraries 3. External repo [CLIP](https://github.com/openai/CLIP) (from openAI) and package `dalle2-pytorch` will be installed via git, without dependencies. This is required by MindSimulator. 4. Installed packages will be written to a `requirements.txt` file.Additionally, for experiments with synthetic fMRI, MindEye models and data must be downloaded from HuggingFace, specifically, files betas_all_subj0X_fp32_renorm.hdf5 (where X is the subject index), fileand file. For optional result visualization using neuroimaging libraries, we used the file brain_region_masks.hdf5.
To reproduce our results, you can run run_exp.sh. Bear in mind that this script runs all our experiments sequentially. We provide it as a reproducibility guide, but we suggest parallelizing as much as possible. We used naive parallelization to run the experiments in our available GPUs. The experimental analysis is conducted by running image_analysis.sh and fMRI_analysis.sh.
This repository is distributed under the AGPL 3.0 license. See the LICENSE file for more details, or visit the AGPL 3.0 homepage.