Machine Learning Library

Namespace: MLLIB · Source: src/libraries/ml The mne_ml library (MLLIB namespace) provides machine learning infrastructure for MNE-CPP: ONNX Runtime inference for pre-trained neural networks, tensor data structures, and a launcher for Python training scripts. Classical estimators (scalers, linear models, covariance shrinkage) come from the external skigen library. The primary use case is CMNE (Contextual Minimum-Norm Estimate) inference, where an LSTM network trained in Python is deployed via ONNX Runtime in C++.

target_link_libraries(my_app PRIVATE mne_ml)

Dependencies: mne_utils, mne_math, Qt6::Core, Eigen3. Optional: ONNX Runtime (enabled via USE_ONNXRUNTIME=ON).

Class Inventory

Class / Struct	Header	Description
`MlModel`	`ml/ml_model.h`	Abstract base class for all ML models
`MlOnnxModel`	`ml/ml_onnx_model.h`	ONNX Runtime backed model for neural network inference
`MlTensor`	`ml/ml_tensor.h`	N-dimensional row-major float32 tensor with zero-copy semantics
`MLTrainer`	`ml/ml_trainer.h`	Python training script launcher (not available in WASM builds)

Enumerations (`ml/ml_types.h`)

Enum	Values	Description
`MlBackend`	`OnnxRuntime`, `BuiltIn`	ML back-end engine
`MlDataType`	`Float32`, `Float64`, `Int64`	Tensor data types
`MlTaskType`	`Classification`, `Regression`, `FeatureExtraction`	ML task categories

MlModel (Abstract Base)

All ML models implement this interface:

#include <ml/ml_model.h>

class MlModel {
public:
    typedef QSharedPointer<MlModel> SPtr;

    virtual MlTensor predict(const MlTensor& input) const = 0;
    virtual bool save(const QString& path) const = 0;
    virtual bool load(const QString& path) = 0;
    virtual QString modelType() const = 0;
    virtual MlTaskType taskType() const = 0;
};

Method	Description
`predict(input)`	Run inference on the input tensor
`save(path)`	Save model to file
`load(path)`	Load model from file
`modelType()`	Return model type string (e.g., `"onnx"`)
`taskType()`	Return the task type (Classification, Regression, FeatureExtraction)

MlOnnxModel

ONNX Runtime backed model for deploying pre-trained neural networks (e.g., CMNE LSTM):

#include <ml/ml_onnx_model.h>

MLLIB::MlOnnxModel model;
if (model.load("cmne_lstm.onnx")) {
    qDebug() << "Model loaded, type:" << model.modelType();

    // Prepare input tensor: [batch, sequence_length, features]
    std::vector<float> data(1 * 20 * 204, 0.0f);
    MLLIB::MlTensor input(std::move(data), {1, 20, 204});

    // Run inference
    MLLIB::MlTensor output = model.predict(input);
    qDebug() << "Output shape:" << output.shape();
}

Method	Description
`predict(input)`	Run ONNX Runtime inference on the input tensor
`load(path)`	Load an `.onnx` model file and create an inference session
`save(path)`	Copy the model file to a new path
`isLoaded()`	Check if a session is loaded and ready
`modelType()`	Returns `"onnx"`
`taskType()`	Returns the configured task type

note

When built without USE_ONNXRUNTIME, all methods throw std::runtime_error. The ONNX Runtime shared library is automatically copied alongside mne_ml during the build for runtime discovery.

MlTensor

N-dimensional tensor with contiguous row-major (C-order) float32 storage. Data is held in a reference-counted buffer, making copy, reshape, and slice O(1). Storage layout is row-major to match ONNX Runtime, PyTorch, and NumPy conventions.

#include <ml/ml_tensor.h>

// From moved buffer
std::vector<float> buf(1 * 20 * 204, 0.0f);
MLLIB::MlTensor t1(std::move(buf), {1, 20, 204});

// From Eigen matrix (copied + transposed to row-major)
Eigen::MatrixXf mat(100, 50);
MLLIB::MlTensor t2(mat);

// From raw pointer
float* ptr = ...;
MLLIB::MlTensor t3(ptr, {10, 20});

// Access shape
std::vector<int64_t> shape = t1.shape();  // {1, 20, 204}

// Eigen interop (zero-copy map)
auto eigenMap = t2.matrix();  // RowMajorMatrixMap

Type Aliases

Alias	Type
`RowMajorMatrixXf`	`Eigen::Matrix<float, Dynamic, Dynamic, RowMajor>`
`RowMajorMatrixMap`	`Eigen::Map<RowMajorMatrixXf>`
`ConstRowMajorMatrixMap`	`Eigen::Map<const RowMajorMatrixXf>`

Constructors

Constructor	Description
`MlTensor()`	Empty 0-element tensor
`MlTensor(data&&, shape)`	From moved `std::vector<float>` buffer and shape
`MlTensor(ptr, shape)`	Copy from raw pointer and shape
`MlTensor(MatrixXf)`	From Eigen column-major matrix (copied to row-major)

MLTrainer

ML-specific convenience wrapper over UTILSLIB::PythonRunner for launching Python training scripts. Not available in WASM builds.

#include <ml/ml_trainer.h>

MLLIB::MLTrainer trainer;

// Check prerequisites
if (trainer.checkPackages({"torch", "mne", "numpy"})) {
    // Run training script
    auto result = trainer.run("scripts/ml/training/train_cmne.py",
                               {"--epochs", "100", "--lr", "0.001"});
    if (result.exitCode == 0) {
        qDebug() << "Training complete";
    }
}

Method	Description
`run(scriptPath, args)`	Run a Python training script
`checkPackages(packages)`	Verify that required Python packages are importable
`runner()`	Access the underlying `PythonRunner` for callback/config changes

CMNE Workflow

CMNE is implemented by INVLIB::InvCMNE in the inverse library: it z-scores the dSPM estimate and re-weights each time point with the prediction of an LSTM run in ONNX Runtime from the previous contextual estimates (Dinh et al. 2021); see the Inverse Estimation API. Use MlOnnxModel directly for other ONNX networks.

MNE-Python Cross-Reference

MNE-CPP (MLLIB)	Python Equivalent
`MlOnnxModel`	`onnxruntime.InferenceSession`
`MlTensor`	`numpy.ndarray` / `torch.Tensor`
`MLTrainer`	Direct Python execution (no equivalent needed)

Class Inventory​

Enumerations (ml/ml_types.h)​

MlModel (Abstract Base)​

MlOnnxModel​

MlTensor​

Type Aliases​

Constructors​

MLTrainer​

CMNE Workflow​

MNE-Python Cross-Reference​

See Also​