Package: modeci-mdf
ModECI Model Description Format (MDF)Click here for the full MDF documentationNote: MDF is still in development! See theopen issues related to the specificationor gohereto get in contact regarding MDF.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 theBrain Imaging Data Standard (BIDS)initiative. For more on the previous work in this area, seehere.OverviewMDF is an open source, community-supported standard and associated library of tools for expressing computational models in a form that allows them to be exchanged between diverse programming languages and execution environments. The overarching aim is to provide a common format for models acrosscomputational neuroscience,cognitive scienceandmachine learning.It consists of a specification for expressing models in serialized formats (currentlyJSON,YAMLandBSONrepresentations are supported, though others such asHDF5are planned) and a set of Python tools for implementing a model described using MDF. The serialized formats can be used when importing a model into a supported target environment to execute it; and, conversely, when exporting a model built in a supported environment so that it can be re-used in other environments.The MDF Python API can be used to create or load an MDF model for inspection and validation. It also includes a basicexecution enginefor simulating models in the format. However, this is not intended to provide a efficient, general-purpose simulation environment, nor is MDF intended as a programming language. Rather, the primary purpose of the Python API is to facilitate and validate the exchange of models between existing environments that serve different communities. Accordingly, these Python tools include bi-directional support for importing to and exporting from widely-used programming environments in a range of disciplines, and for easily extending these to other environments.DevelopmentThe implementation and dissemination of the MDF language and associated tools is being carried out by theModel Exchange and Convergence Initiative (ModECI), which has been supported by theNSF Convergence Accelerator Program(Track D: AI-Driven Innovation via Data and Model Sharing), as a publicly accessibleopen-source project. The initial design has been informed by aseries of workshopsinvolving developers of key software environments and other stakeholders in machine learning, cognitive science and neuroscience. Future workshops will address broadening of support to other domains in basic and applied science and technology development (e.g., population biology, medical informatics, structural and environmental monitoring, and complex systems control). Environments for which support is currently being developed includePyTorch,ONNX,WebGME,NeuroML,PsyNeuLink, andACT-R.Fig 1:Some of the current and planned formats which MDF will interact with. Click on the image for more information.Successful interfacing of MDF to existing disciplinary standards (such asONNXin machine learning, andNeuroMLin neuroscience) as well as general-purpose simulation environments (such asWebGME) will permit bridging between these environments, and translation to the broader set of environments supported by those standards (such asTensorflow&Kerasin the case of ONNX, andThe Virtual BrainandSONATAin the case of NeuroML). Initial investigations have also taken place, in collaboration with projects in the NSF Accelerator Track C (Quantum Technology), to use MDF for facilitating the implementation of computational models onquantum hardware.The core elements of the MDF standardModelsThe highest level construct in MDF is a model that consists of one or moregraphsand model attributes. The former describe the operational features of the model (its structure and execution), while the latter provide additional information (metadata) useful for executing, evaluating, testing or visualizing it.GraphsA graph specifies the structure and process flow of amodel. The most fundamental element of a graph is anode, which specifies some unit of computation in terms of itsparametersandfunctions. Nodes are connected to other nodes via directededges, which, in the absence of additionalconditions, define the computational flow of the model.NodesThese define the core elements of computation in agraph, that receive and transmit information via theirinput and output ports. In general, ports represent points of contact between anodeand theedgesthat connect it to other nodes.Output PortsAn output port is the starting point of the data transmission process. After processing the information in anode, an output port is used to begin the transmission of information to the nextnodethroughedges.EdgesThese transmit information from theoutput portof onenodeto theinput portof another, collectively defining agraph’stopography. Edges may contain weights that can operate on the information they carry.Input PortsAn input port is the endpoint of the data transmission process. It receives the information transmitted through anedgeand inputs it to the nextnodefor further processing.ConditionsThese are a core and distinctive element of the MDF specification, that complement other computational graph-based formats by providing a high-level set of descriptors for specifying conditional execution ofnodes. This allows models with relatively complex execution requirements (e.g., containing cycles, branches, and/or temporal dependencies) to be expressed asgraphsin a sufficiently abstract form that facilities exchange among high-level modeling environments without requiring that they be “lowered” to and then recovered from more elaborated procedural descriptions.ParametersAttributes that determine the configuration and operation ofnodesandedges, can be defined in the MDF using parameters. In the case of parameters specifying large data structures (e.g., weight-matrices), arrays in widely used formats (e.g. numpy arrays, TensorFlow tensors) can be used, and serialisation in portable binary formats (e.g. BSON) is supported. Parameters can either be fixed values, which don't change when thenodeis executed, or can change over time (stateful parameters).FunctionsA single value which is evaluated as a function of values oninput portsand other functions andparameters. A key distinction withparametersis that a function is always stateless.Model metadataThere is the ability to add “metadata” to themodel,graph,nodesand many of their sub elements which provide additional information about that element. While the metadata should not be essential to the mathematical description of the behavior/structure of the element, it could be useful for human interpretability of its function/purpose, or used when it is mapped to a specific application for simulation/visualization. Metadata can be added to the top level model to specify contact information, citations, acknowledgements, pointers to sample data and benchmark results, and environments in which the specified model was originally implemented and any that have been validated to support its execution.Fig 2:A simple graph with 3 nodes and 2 edges expressed in MDF.Fig 3:This graph illustrates the ability to specify behavior that extends beyond the directed flow through the graph. Here, Node 1 generates a random number and transmits that number to Node 2. Node 2 will only run if the number it receives from Node 1 is greater than 10.InstallationRequirementsRequires Python >= 3.7Quick startpip install modeci-mdfFor more detailed installation instructions seehere.For guidelines on contributing to the development of MDF, seehere.ExamplesTo get started, follow the simple example in a Jupyter notebookhereMultiple examples of serialized MDF files, the Python scripts used to generate them, as well as mappings to target environments can be foundhere.