Quick Start Guide to MDF

This is a quick guide to the various parts of the ModECI Model Description Format (MDF) specification, API and examples.

Specification of MDF language

The specification for the language, including the core types Graph, Node, Edge etc. is available here.

Installation of Python API

There is a prototype implementation of an API (Application Programming Interface) in Python which can be used to build models in the MDF format, as well as save (serialize) the models in JSON, YAML and other formats. It also has an Execution Engine which can be used to execute/evaluate the models.

Use pip to install the latest version of MDF (plus dependencies) from PyPI:

pip install modeci_mdf

More details, and importantly, how to set up a virtual environment for the package, can be found here.

Examples of MDF

Simple examples

Some basic examples of models in MDF format which illustrate how a model can be 1) created using the Python API, 2) saved to JSON and YAML, 3) exported to graphical form and 4) executed to evaluate all parameters, can be found here.

A step-by-step guide to using MDF

This Jupyter notebook provides a step-by-step guide to creating, saving and executing an MDF model in Python.

More complex examples

  • An example of a simple Spiking Neuronal Network (SNN) can be found here.

  • Multiple examples of Convolutional Neural Network (CNN) models can be found in the PyTorch to MDF documentation.

  • An example of a Recurrent Neural Network (RNN) in MDF can be found here.

Export/import formats

Serialization formats

Whenever a model is exchanged between different environments it will usually be a serialized form of the model which is exported/imported. Python scripts can be used to generate MDF models (e.g. this), but the models are saved in standardized format in either text based JSON or YAML formats or in binary BSON format.

Currently supported environments


Models can be created in PyTorch and exported into MDF format, or MDF models can be converted to code which executes natively in PyTorch. See here for more details.


ONNX (Open Neural Network Exchange) is an important format for exchanging models between machine learning environments. It is used in the MDF function ontology, and models in ONNX format can be exported to MDF. See here for more details. Converting MDF->ONNX is best enabled currently by converting the model to PyTorch and from there to ONNX.


Examples of converting MDF to/from NeuroML2/LEMS can be found here.

Planned environments to support


We have started some preliminary interactions between ACT-R and MDF. See here for more details.


The MDF format was first proposed following a meeting organised at Princeton in July 2019 by Russ Poldrack of the Center for Reproducible Neuroscience (CRN) at Stanford and the Brain Imaging Data Standard (BIDS) initiative. While the prototype Python API and MDF specification have been developed independently of the BIDS initiative (which focusses on exchange of neuroimaging data), there is interest in that community to allow MDF to be used as a way to encode models of neuronal activity, which can be embedded in BIDS datasets. The BIDS Extension Proposal Computational Models is a potential avenue for this.

Background to the ModECI Initiative

See here for details about the Model Exchange and Convergence Initiative (ModECI).