NeuralMPCX

What NeuralMPCX can do for you

NeuralMPCX is an open-source Python library for developing, simulating, and deploying Model Predictive Controllers (MPC) using linear, nonlinear, and neural network-based dynamic models. Built around CasADi and IPOPT, it provides a flexible framework for solving constrained optimal control problems, particularly in industrial process control and research applications.

With NeuralMPCX, you can:

• Develop different types of MPC controllers: Design linear, nonlinear, and neural Model Predictive Controllers within a unified Python framework.
• Integrate neural networks into predictive control: Incorporate trained recurrent neural networks (RNNs), particularly Long Short-Term Memory (LSTM) models, into CasADi-based optimization problems.
• Reduce the need for complex first-principles models: Use data-driven dynamic models identified from measured input-output sequences when deriving accurate physical models is difficult or time-consuming.
• Improve recurrent model initialization: Use historical measurements and a context-window warmup algorithm to initialize LSTM hidden states and maintain them efficiently between control steps.
• Handle practical control constraints and disturbances: Define input limits, state and output constraints, soft constraints, custom objective functions, and measured disturbances.
• Estimate unmeasured states and disturbances: Apply Kalman filtering, Extended Kalman filtering, augmented state estimation, and Moving Horizon Estimation (MHE) to support feedback control.
• Evaluate and compare control strategies: Use simulation utilities, industrial benchmark examples, and reproducible experiments to study closed-loop performance, robustness, and computational feasibility.

How NeuralMPCX works

NeuralMPCX combines mathematical optimization with physical and data-driven modeling.

For classical MPC, users define a system's dynamics, constraints, and objective function using CasADi. The resulting nonlinear optimization problems are solved with IPOPT.

For neural MPC, trained PyTorch LSTM models are converted into CasADi-compatible symbolic expressions, allowing neural predictions to be incorporated directly into the optimization process.

A dedicated warmup mechanism uses historical input-output measurements to initialize recurrent states. During subsequent control steps, these states can be updated incrementally, avoiding repeated processing of the complete historical window.

The library also provides state estimators and control-system utilities for applications where measurements are noisy, incomplete, or affected by disturbances.

Example applications

NeuralMPCX includes examples involving:

• Cascaded two-tank systems: Neural MPC using LSTM-based dynamics.
• Continuous Stirred Tank Reactors (CSTR): Nonlinear MPC and neural MPC with state estimation.
• Grinding circuits: Multivariable process control with linear MPC and augmented state estimation.
• Benchmark experiments: Evaluation of noise sensitivity, model mismatch, robustness, real-time feasibility, and closed-loop performance.

Installation and code examples

NeuralMPCX supports Python 3.9 and newer and can be installed directly from PyPI.

Standard installation:

pip install neuralmpcx

Installation with PyTorch support for neural MPC:

pip install "neuralmpcx[torch]"

Development installation:

git clone https://github.com/hzdr/neural-mpcx.git
cd neural-mpcx
pip install -e ".[dev]"

Basic MPC initialization

The following example illustrates how to initialize a controller and define its state and control variables.

from neuralmpcx import Nlp
from neuralmpcx.wrappers import Mpc

# Create a Model Predictive Controller
nlp = Nlp(sym_type="MX")

mpc = Mpc(
    nlp=nlp,
    prediction_horizon=10,
    control_horizon=5,
    tuning_parameters={}
)

# Define states and control inputs
x, _ = mpc.state("x", size=4)
u, _, _ = mpc.action(
    "u", size=2, lb=-1.0, ub=1.0
)

# Next: define dynamics, objectives and
# constraints before initializing the solver.

Complete working examples for classical and neural MPC are available in the repository.

Main components and capabilities

Component	Description	Main purpose
Linear MPC	Predictive control using linear state-space models	Classical process control
Nonlinear MPC	Optimization with nonlinear dynamic models	Control of nonlinear systems
Neural MPC	CasADi-compatible LSTM models	Data-driven predictive control
RNN warmup	Historical context initialization and recurrent-state updates	Consistent neural predictions
State estimation	Kalman filters, EKF, augmented estimators	Reconstruction of unmeasured states and biases
Moving Horizon Estimation	Optimization-based estimation with constraints	Constrained state and disturbance estimation
Benchmark utilities	Reproducible simulations and performance evaluations	Controller comparison and validation

Getting started checklist

• Install NeuralMPCX using pip.
• Choose a modeling approach: linear, nonlinear, or neural.
• Define the system dynamics or load a trained LSTM model.
• Configure the prediction horizon, control horizon, objective function, and constraints.
• Add state estimation or measured disturbance handling if required.
• Initialize the optimization solver and implement the control loop.
• Validate the controller using the available examples and benchmarks.

Links and resources

• GitHub repository and documentation
• Python package on PyPI
• Examples and benchmarks
• Report issues or request features
• Software publication and DOI
• Apache 2.0 License

Images

Development and citation

NeuralMPCX is developed at the Helmholtz-Zentrum Dresden-Rossendorf (HZDR) and is distributed under the Apache License 2.0. Portions of the software derive from casadi-nlp under the MIT License.

The project welcomes contributions, bug reports, and feature requests through GitHub.

If you use NeuralMPCX in scientific work, please cite the software using its DOI:

DOI: 10.14278/rodare.4567