CONTROL-CORE: Integrated Development Environment for Closed-loop Neuromodulation Control Systems.

CONTROL-CORE is a design and simulation framework, functioning as a visual Integrated Development Environment (IDE) for Closed-loop Neuromodulation Control Systems. At its center is concore, a lightweight protocol to simulate neuromodulation control systems. This repository consists of the implementation of concore protocol and sample (demo and neuromodulation control systems) studies. In addition to its default standard Python implementation, concore also supports developing studies in Matlab/Octave, Verilog, and C++. concore also aims to support more language programs in the future.

The CONTROL-CORE Framework

The CONTROL-CORE framework consists of the below projects.

• concore: The CONTROL-CORE protocol, known as concore, allows modular simulation of controller and PM nodes to run on different operating systems, computing platforms, and programming languages. This repository consists of concore source code. The concore documentation can be found here. A concore study can be developed from programs written in different languages. That means, concore facilitates a seamless communication across codes developed in different languages that it supports, through its simple file-based data sharing between the programs.

• concore Editor: This is the front-end for CONTROL-CORE. We forked DHGWorkflow, a sibling project we developed, and extend it as the concore Editor.

• Mediator: The Mediator allows the CONTROL-CORE studies to be distributed and run, rather than having all the programs that construct a study to be run just from a centralized location.

• concore-lite: The concore-lite repository consists of a simple example version of a concore study. Please check out and run this, if you like to learn the concore protocol without having to clone this large concore repository.

• documentation: The source code repository of the ReadTheDocs documentation of CONTROL-CORE.

The concore Protocol

concore enables composing studies from programs developed in different languages. Currently supported languages are, Python, Matlab/Octave, Verilog, and C++. The studies are designed through the visual concore Editor (DHGWorkflow) and interpreted into concore through its parser. Neural control systems consist of loops (dicycles). Therefore, they cannot be represented by classic workflow standards (such as CWL or WDL). Therefore, concore addresses a significant research gap to model closed-loop neuromodulation control systems. The concore protocol shares data between the programs through file sharing, with no centralized entity (a broker or an orchestrator) to arbitrate communications between the programs. (In the distributed executions, the CONTROL-CORE Mediator enables connecting the disjoint pieces of the study through REST APIs).

Wire Format

Concore payloads follow Python literal syntax compatible with ast.literal_eval(). The Python, C++, and Java implementations parse this shared format; the MATLAB and Verilog implementations currently support only flat numeric arrays derived from it. Supported value types include:

• Numbers — integers and floats, including scientific notation (e.g., 1e3, -2.5)
• Booleans — True / False (converted to 1.0 / 0.0 in numeric contexts)
• Strings — single- or double-quoted (e.g., "start", 'label')
• Nested arrays — [1, [2, 3]]
• Tuples — (1.0, 2.0) (treated identically to arrays)

Installation and Getting Started Guide

Please follow the ReadTheDocs documentation and the concore-lite repository to get started quick.

Installation instructions for concore can be found here. Usage instructions can be found here.

Command-Line Interface (CLI)

concore now includes a command-line interface for easier workflow management. Install it with:

pip install -e .

Quick start with the CLI:

# Create a new project
concore init my-project

# Validate your workflow
concore validate workflow.graphml

# Compile your workflow
concore build workflow.graphml --auto-build

# Monitor running processes
concore status

# Stop all processes
concore stop

For detailed CLI documentation, see concore_cli/README.md.

Configuration

concore supports customization through configuration files in the CONCOREPATH directory (defaults to the concore installation directory):

• concore.tools - Override tool paths (one per line, KEY=value format):

  CPPEXE=/usr/local/bin/g++-12
  PYTHONEXE=/usr/bin/python3.11
  VEXE=/opt/iverilog/bin/iverilog
  OCTAVEEXE=/snap/bin/octave
  

  Supported keys: CPPWIN, CPPEXE, VWIN, VEXE, PYTHONEXE, PYTHONWIN, MATLABEXE, MATLABWIN, OCTAVEEXE, OCTAVEWIN

• concore.octave - Treat .m files as Octave instead of MATLAB (presence = enabled)

• concore.mcr - MATLAB Compiler Runtime path (single line)

• concore.sudo - Docker command override (e.g., docker instead of sudo docker)

• concore.repo - Docker repository override

Tool paths can also be set via environment variables (e.g., CONCORE_CPPEXE=/usr/bin/g++). Priority: config file > env var > defaults.

Docker Executable Configuration

The Docker executable used by generated scripts (build, run, stop, maxtime, params, unlock) is controlled by the DOCKEREXE variable. It defaults to docker and can be overridden in three ways (highest priority first):

1. Config file — Write the desired command into concore.sudo in your CONCOREPATH directory:

   docker
   

   This remains the highest-priority override, preserving backward compatibility.

2. Environment variable — Set DOCKEREXE before running mkconcore.py:

   # Rootless Docker / Docker Desktop (macOS, Windows)
   export DOCKEREXE="docker"
   
   # Podman
   export DOCKEREXE="podman"
   
   # Traditional Linux with sudo
   export DOCKEREXE="sudo docker"
   

3. Default — If neither the config file nor the environment variable is set, docker is used.

Note: Previous versions defaulted to sudo docker, which failed on Docker Desktop (macOS/Windows), rootless Docker, and Podman. The new default (docker) works out of the box on those platforms. If you still need sudo, set DOCKEREXE="sudo docker" via the environment variable or concore.sudo config file.

Security Configuration

Set a secure secret key for the Flask server before running in production:

export FLASK_SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")

Do NOT commit your secret key to version control. If FLASK_SECRET_KEY is not set, a temporary random key will be generated automatically (suitable for local development only).

For a detailed and more scientific documentation, please read our extensive open-access research paper on CONTROL-CORE. This paper has a complete discussion on the CONTROL-CORE architecture and deployment, together with the commands to execute the studies in different programming languages and programming environments (Ubuntu, Windows, MacOS, Docker, and distributed execution).

C++ ZMQ Transport

concore.hpp supports ZMQ-based communication as an opt-in transport alongside the default file-based I/O.

To enable it, compile with -DCONCORE_USE_ZMQ and link against cppzmq:

g++ -DCONCORE_USE_ZMQ my_node.cpp -lzmq -o my_node

In your C++ node, register a ZMQ port before reading or writing:

#include "concore.hpp"

Concore c;
c.init_zmq_port("in1", "bind", "tcp://*:5555", "REP");
c.init_zmq_port("out1", "connect", "tcp://localhost:5556", "REQ");

vector<double> val = c.read("in1", "", "0.0");
c.write("out1", "", val, 0);

Builds without -DCONCORE_USE_ZMQ are unaffected.

The concore Repository

concore contains programs (such as physiological models or more commonly called "PMs" and controllers) and studies (i.e., graphml files that represents the studies as workflows). The wrappers enable seamlessly extending a study into a distributed one with the CONTROL-CORE Mediator.

concore repository consists of several scripts at its root level. The demo folder consists of several sample programs and studies, mostly toy examples to learn the protocol. The ratc folder consists of the programs and studies of the rat cardiac experiments we developed with concore.

If you have a bug to report in one of the CONTROL-CORE projects, please report it through relevant Issue Tracker. Similarly, please feel free to contribute your studies and code enhancements using pull requests. Questions and discussions can be made through the relevant Discussions forum.

The concore Issues can be reported here.

The concore discussion forum can be found here.

Please make sure to send your concore pull requests to the dev branch.

Citing concore

If you use concore in your research, please cite the below papers:

• Kathiravelu, P., Arnold, M., Vijay, S., Jagwani, R., Goyal, P., Goel, A.K., Li, N., Horn, C., Pan, T., Kothare, M. V., and Mahmoudi, B. *