NeuroMANCER v1.5.6

Neural Modules with Adaptive Nonlinear Constraints and Efficient Regularizations (NeuroMANCER) is an open-source differentiable programming (DP) library for solving parametric constrained optimization problems, physics-informed system identification, and parametric model-based optimal control. NeuroMANCER is written in PyTorch and allows for systematic integration of machine learning with scientific computing for creating end-to-end differentiable models and algorithms embedded with prior knowledge and physics.

---

Table of Contents

1. Overview
2. Key Features
3. What's New in v1.5.3
4. Installation
5. Getting Started
6. Tutorials
7. Documentation and User Guides

---

Key Features

• Learn To Model, Learn To Control, Learn To Optimize: Our library is built to provide end users a multitude of tools to solve Learning To Optimize (L2O), Learning To Model (L2M), and Learning To Control (L2C) tasks. Tackle advanced constrained parametric optimization, model fluid dynamics using physics-informed neural networks, or learn how to control indoor air temperature in buildings to maximize building efficiency.
• Symbolic programming interface makes it very easy to define and embed physics equations, domain knowledge, and constraints into those learning paradigms.
• Comprehensive Learning Tools: Access a wide array of tutorials and example applications—from basic system identification to advanced predictive control—making it easy for users to learn and apply NeuroMANCER to real-world problems.
• State-of-the-art methods: NeuroMANCER is up-to-date with SOTA methods such as Function Encoders (FE) and Kolgomorov-Arnold Networks (KANs) for function approximation, neural ordinary differential equations (NODEs) and neural Koopman Operator (KO) and sparse identification of non-linear dynamics (SINDy) for learning to model dynamical systems, differentiable convex optimization layers for safety constraints in learning to optimize, and Differentiable Predictive Control (DPC) for learning to control nonlinear systems.
• The NeuroMANCER-GPT Assistant: We provide easy-to-use scripts to convert the contents of the NeuroMANCER library in a way that is suitable for ingestion in RAG-based "LLM-assistant" pipelines. Please see Assistant to read more about how one can quickly spin up an LLM model to help understand and code in NeuroMANCER.

What's New in v1.5.6

New Examples:

• Neural DAEs via operator splitting method
• Mixed-Integer DPC for thermal system
• Grid-responsive DPC for building energy systems
• DPC with preview horizon

New Features

• New class SystemPreview that acts as drop-in replacement for System class enabling preview horizon functionality
• Unit tests brought up-to-date.

Fixed bug

• Fixed bug with mlflow dependency creating conflicts in Google Colab

Installation

Simply run

pip install neuromancer

For manual installation, please refer to Installation Instructions

Getting Started

An extensive set of tutorials can be found in the examples folder and the Tutorials below. Interactive notebook versions of examples are available on Google Colab! Test out NeuroMANCER functionality before cloning the repository and setting up an environment.

The notebooks below introduce the core abstractions of the NeuroMANCER library, in particular, our symbolic programming interface and Node classes.

Symbolic Variables, Nodes, Constraints, Objectives, and Systems Classes

• Part 1: Linear regression in PyTorch vs NeuroMANCER.

• Part 2: NeuroMANCER syntax tutorial: variables, constraints, and objectives.

• Part 3: NeuroMANCER syntax tutorial: modules, Node, and System class.

Example

Quick example for how to solve parametric constrained optimization problem using NeuroMANCER, leveraging our symbolic programming interface, Node and Variable, Blocks, SLiM library, and PenaltyLoss classes.

# Neuromancer syntax example for constrained optimization
import neuromancer as nm
import torch 

# define neural architecture 
func = nm.modules.blocks.MLP(insize=1, outsize=2, 
                             linear_map=nm.slim.maps['linear'], 
                             nonlin=torch.nn.ReLU, hsizes=[80] * 4)
# wrap neural net into symbolic representation via the Node class: map(p) -> x
map = nm.system.Node(func, ['p'], ['x'], name='map')
    
# define decision variables
x = nm.constraint.variable("x")[:, [0]]
y = nm.constraint.variable("x")[:, [1]]
# problem parameters sampled in the dataset
p = nm.constraint.variable('p')

# define objective function
f = (1-x)**2 + (y-x**2)**2
obj = f.minimize(weight=1.0)

# define constraints
con_1 = 100.*(x >= y)
con_2 = 100.*(x**2+y**2 <= p**2)

# create penalty method-based loss function
loss = nm.loss.PenaltyLoss(objectives=[obj], constraints=[con_1, con_2])
# construct differentiable constrained optimization problem
problem = nm.problem.Problem(nodes=[map], loss=loss)

Domain Examples

NeuroMANCER is built to tackle a variety of domain-specific modeling and control problems using its array of methods. Here we show how to model and control building energy systems, as well as apply load forecasting techniques.

For more in-depth coverage of our methods, please see our general Tutorials section below.

Energy Systems

• Learning Building Thermal Dynamics using Neural ODEs
• Multi-zone Building Thermal Dynamics Resistance-Capacitance network with Neural ODEs
• Learning Swing Equation Dynamics using Neural ODEs
• Learning to Control Indoor Air Temperature in Buildings
• Energy Load Forecasting for Building with MLP and CNN Models
• Energy Load Forecasting for Building with Transformers Model
• Learning to Control Pumped-storage Hyrdoelectricity System
• Learning to Control Building HVAC System With Safe RL and DPC

• Grid-responsive DPC for building energy systems

Tutorials on Methods for Modeling, Optimization, and Control

Learning to Optimize (L2O) for Parametric Programming

Neuromancer allows you to formulate and solve a broad class of parametric optimization problems, leveraging machine learning to learn the solutions to such problems. More information on Parametric programming

• Learning to solve a constrained optimization problem.

• Learning to solve a quadratically-constrained optimization problem.

• Learning to solve a set of 2D constrained optimization problems.

• Learning to solve a constrained optimization problem with the projected gradient.

• Using Cvxpylayers for differentiable projection onto the polytopic feasible set.

• Learning to optimize with metric learning for Operator Splitting layers.

Learning to Control (L2C) via Differentiable Predictive Control (DPC)

Neuromancer enables you to learn control policies for a full spectrum of differentiable white-box, grey-box, and black-box dynamical systems, subject to choice constraints and objective functions. More information on Differential Predictive Control

• Learning to stabilize a linear dynamical system.
• Learning to stabilize a nonlinear differential equation.
• Learning to control a nonlinear differential equation.
• Learning neural ODE model and control policy for an unknown dynamical system.
• Learning neural Lyapunov function for a nonlinear dynamical system.

• Mixed-Integer DPC

Function Approximation

Neuromancer is up-to-date with state-of-the-art methods. Here we showcase the powerful Kolgomorov-Arnold networks More information on Kolgomorov-Arnold Networks

• A comparison of KANs and FBKANs in learning a 1D multiscale function with noise
• A comparison of KANs and FBKANs in learning a 2D multiscale function with noise

Neuromancer contains an implementation of function encoders, an algorithm for learning basis functions as neural networks. See Function Encoders: A Principled Approach to Transfer Learning in Hilbert Spaces.

• An Introduction to Function Encoders

System Identification

Neuromancer allows one to use machine learning, prior physics, and domain knowledge to construct data-driven models of dynamical systems given the measured observations of the system behavior. More information on System ID via Neural State Space Models and ODEs

• Neural Ordinary Differential Equations (NODEs)
• Parameter estimation of an ODE system
• Universal Differential Equations (UDEs)
• NODEs with exogenous inputs
• Neural State Space Models (NSSMs) with exogenous inputs
• Data-driven modeling of resistance-capacitance (RC) network ODEs
• Deep Koopman operator
• control-oriented Deep Koopman operator
• Sparse Identification of Nonlinear Dynamics (SINDy)

• Function Encoders + Neural ODEs

• Neural Differential Algebraic Equations (DAEs) via operator splitting method

Physics-Informed Neural Networks (PINNs)

Neuromancer's symbolic programming design is perfectly suited for solving PINNs. More information on PINNs

• Diffusion Equation
• Burgers' Equation
• Burgers' Equation w/ Parameter Estimation (Inverse Problem)
• Laplace's Equation (steady-state)
• Damped Pendulum via stacked PINN
• Navier-Stokes equation (lid-driven cavity flow, steady-state, KAN)

Stochastic Differential Equations (SDEs)

Neuromancer has been integrated with TorchSDE to handle stochastic dynamical systems. More information on SDEs

• LatentSDEs: "System Identification" of Stochastic Processes using Neuromancer x TorchSDE

Scalability and Customization

PyTorch Lightning Integration

We have integrated PyTorch Lightning to streamline code, enable custom training logic, support GPU and multi-GPU setups, and handle large-scale, memory-intensive learning tasks.

• Lightning Integration Basics.
• Lightning Advanced Features and Automatic GPU Support.
• Defining Custom Training Logic via Lightning Modularized Code.

Documentation and User Guides

The documentation for the library can be found online. There is also an introduction video covering the core features of the library.

For more information, including that for developers, please go to our Developer and User Guide

Community Information

We welcome contributions and feedback from the open-source community!

Contributions, Discussions, and Issues

Please read the Community Development Guidelines for further information on contributions, discussions, and Issues.

Release notes

See the Release notes documenting new features.

License

NeuroMANCER comes with BSD license. See the license for further details.

Publications

• Ashish S. Nair, Bruno Jacob, Amanda A. Howard, Jan Drgona, Panos Stinis, E-PINNs: Epistemic Physics-Informed Neural Networks, arXiv:2503.19333
• Bo Tang, Elias B. Khalil, Ján Drgoňa, Learning to Optimize for Mixed-Integer Non-linear Programming, arXiv:2410.11061, 2024
• John Viljoen, Wenceslao Shaw Cortez, Jan Drgona, Sebastian East, Masayoshi Tomizuka, Draguna Vrabie, Differentiable Predictive Control for Robotics: A Data-Driven Predictive Safety Filter Approach, arXiv:2409.13817, 2024
• Jan Drgona, Aaron Tuor, Draguna Vrabie, Learning Constrained Parametric Differentiable Predictive Control Policies With Guarantees, IEEE Transactions on Systems, Man, and Cybernetics: Systems, 2024
• Renukanandan Tumu, Wenceslao Shaw Cortez, Ján Drgoňa, Draguna L. Vrabie, Sonja Glavaski, Differentiable Predictive Control for Large-Scale Urban Road Networks, arXiv:2406.10433, 2024
• Ethan King, James Kotary, Ferdinando Fioretto, Jan Drgona, Metric Learning to Accelerate Convergence of Operator Splitting Methods for Differentiable Parametric Programming, arXiv:2404.00882, 2024
• James Koch, Madelyn Shapiro, Himanshu Sharma, Draguna Vrabie, Jan Drgona, Neural Differential Algebraic Equations, arXiv:2403.12938, 2024
• Wenceslao Shaw Cortez, Jan Drgona, Draguna Vrabie, Mahantesh Halappanavar, A Robust, Efficient Predictive Safety Filter, arXiv:2311.08496, 2024
• Shrirang Abhyankar, Jan Drgona, Andrew August, Elliott Skomski, Aaron Tuor, Neuro-physical dynamic load modeling using differentiable parametric optimization, 2023 IEEE Power & Energy Society General Meeting (PESGM), 2023
• James Koch, Zhao Chen, Aaron Tuor, Jan Drgona, Draguna Vrabie, Structural Inference of Networked Dynamical Systems with Universal Differential Equations, arXiv:2207.04962, (2022)
• Ján Drgoňa, Sayak Mukherjee, Aaron Tuor, Mahantesh Halappanavar, Draguna Vrabie, Learning Stochastic Parametric Differentiable Predictive Control Policies, IFAC ROCOND conference (2022)
• Sayak Mukherjee, Ján Drgoňa, Aaron Tuor, Mahantesh Halappanavar, Draguna Vrabie, Neural Lyapunov Differentiable Predictive Control, IEEE Conference on Decision and Control Conference 2022
• Wenceslao Shaw Cortez, Jan Drgona, Aaron Tuor, Mahantesh Halappanavar, Draguna Vrabie, Differentiable Predictive Control with Safety Guarantees: A Control Barrier Function Approach, IEEE Conference on Decision and Control Conference 2022
• Ethan King, Jan Drgona, Aaron Tuor, Shrirang Abhyankar, Craig Bakker, Arnab Bhattacharya, Draguna Vrabie, Koopman-based Differentiable Predictive Control for the Dynamics-Aware Economic Dispatch Problem, 2022 American Control Conference (ACC)
• Drgoňa, J., Tuor, A. R., Chandan, V., & Vrabie, D. L., Physics-constrained deep learning of multi-zone building thermal dynamics. Energy and Buildings, 243, 110992, (2021)
• E. Skomski, S. Vasisht, C. Wight, A. Tuor, J. Drgoňa and D. Vrabie, "Constrained Block Nonlinear Neural Dynamical Models," 2021 American Control Conference (ACC), 2021, pp. 3993-4000, doi: 10.23919/ACC50511.2021.9482930.
• Skomski, E., Drgoňa, J., & Tuor, A. (2021, May). Automating Discovery of Physics-Informed Neural State Space Models via Learning and Evolution. In Learning for Dynamics and Control (pp. 980-991). PMLR.
• Drgoňa, J., Tuor, A., Skomski, E., Vasisht, S., & Vrabie, D. (2021). Deep Learning Explicit Differentiable Predictive Control Laws for Buildings. IFAC-PapersOnLine, 54(6), 14-19.
• Tuor, A., Drgona, J., & Vrabie, D. (2020). Constrained neural ordinary differential equations with stability guarantees. arXiv preprint arXiv:2004.10883.
• Drgona, Jan, et al. "Differentiable Predictive Control: An MPC Alternative for Unknown Nonlinear Systems using Constrained Deep Learning." Journal of Process Control Volume 116, August 2022, Pages 80-92
• Drgona, J., Skomski, E., Vasisht, S., Tuor, A., & Vrabie, D. (2020). Dissipative Deep Neural Dynamical Systems, in IEEE Open Journal of Control Systems, vol. 1, pp. 100-112, 2022
• Drgona, J., Tuor, A., & Vrabie, D., Learning Constrained Adaptive Differentiable Predictive Control Policies With Guarantees, arXiv preprint arXiv:2004.11184, (2020)

Cite as

@article{Neuromancer2023,
  title={{NeuroMANCER: Neural Modules with Adaptive Nonlinear Constraints and Efficient Regularizations}},
  author={Drgona, Jan and Tuor, Aaron and Koch, James and Shapiro, Madelyn and Jacob, Bruno and Vrabie, Draguna},
  Url= {https://github.com/pnnl/neuromancer}, 
  year={2023}
}

Development team

Lead developers: Jan Drgona, Aaron Tuor
Notable contributors: Rahul Birmiwal, Bruno Jacob, Reilly Raab, Madelyn Shapiro, James Koch, Seth Briney, Bo Tang, Ethan King, Elliot Skomski, Zhao Chen, Christian Møldrup Legaard, Tyler Ingebrand, Alireza Daneshvar, Cary Faulkner
Scientific advisors: Draguna Vrabie, Panos Stinis

Open-source contributions made by:

Made with contrib.rocks.

Acknowledgments

This research was partially supported by the Mathematics for Artificial Reasoning in Science (MARS) and Data Model Convergence (DMC) initiatives via the Laboratory Directed Research and Development (LDRD) investments at Pacific Northwest National Laboratory (PNNL), by the U.S. Department of Energy, through the Office of Advanced Scientific Computing Research's “Data-Driven Decision Control for Complex Systems (DnC2S)” project, and through the Energy Efficiency and Renewable Energy, Building Technologies Office under the “Dynamic decarbonization through autonomous physics-centric deep learning and optimization of building operations” and the “Advancing Market-Ready Building Energy Management by Cost-Effective Differentiable Predictive Control” projects. This project was also supported by the U.S. Department of Energy (DOE), Office of Science, Advanced Scientific Computing Research (ASCR) program, under the Uncertainty Quantification for Multifidelity Operator Learning (MOLUcQ) project (Project No. 81739). PNNL is a multi-program national laboratory operated for the U.S. Department of Energy (DOE) by Battelle Memorial Institute under Contract No. DE-AC05-76RL0-1830. This research is also partially supported by the U.S. DOE, Office of Science, ASCR program under the Scientific Discovery through Advanced Computing (SciDAC) Institute “LEADS: LEarning-Accelerated Domain Science”. This research is also partially supported by the Ralph O’Connor Sustainable Energy Institute (ROSEI) at Johns Hopkins University.