NeuroMANCER v1.5.1

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.

⭐ Now available on PyPi! ⭐

New in v1.5.1

Lightning Enhancements

Further integration enhancements with PyTorch Lightning (https://lightning.ai/docs/pytorch/stable/). We now support all Lightning hooks, which are modular logic blocks that make defining custom training/validation/etc logic very easy and user-friendly.

We have also released a Lightning Studio course on Differentiable Predictive Control: !

Lightning Studios are powerful, AI development platforms. They essentially act as extremely user-friendly virtual machines, but accessible through your browser! Please see https://lightning.ai/studios for more information.

TorchSDE Integration

• We have begun integration with the TorchSDE library (https://github.com/google-research/torchsde/tree/master) TorchSDE provides stochastic differential equation solvers with GPU spport and efficient backpropagation.
• Neuromancer already has robust and extensive library for Neural ODEs and ODE solvers. We extend that functionality to the stochastic case by incorporating TorchSDE solvers. To motivate and teach the user how one progresses from neural ODEs to "neural SDEs" we have written a lengthy notebook -- sde_walkthrough.ipynb

Stacked Physics-Informed Neural Networks

• Neuromancer now supports Stacked Physics-Informed Neural Networks. This architecture, based on the work of Howard et al. (2023), consists of stacking multifidelity networks via composition, allowing a progressive improvement of learned solutions. This formulation is especially useful for highly oscillatory problems. We illustrate an example of its usage with the solution of a damped harmonic oscillator using PINN: Part_5_Pendulum_Stacked.ipynb

SINDy

• Sparse Identification of Nonlinear Dynamics (SINDy) is a powerful method which uses sparse regression to identify a small number of active terms in dynamic systems, allowing for interpretable and efficient modeling of complex, nonlinear dynamics. We now enable users to leverage this technique for sparse physics-informed system identification. Checkout the notebook here Part_9_SINDy.ipynb

New Colab Examples:

⭐ Custom Training Via Lightning Hooks

⭐ Latent Stochastic Differential Equations

⭐ Stacked Physics-Informed Neural Networks

⭐ Part 9: Sparse Identification of Nonlinear Dynamics (SINDy)

Features and Examples

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

Intro to NeuroMANCER

• 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.

Learning to Optimize (L2O) for Parametric Programming

• Part 1: Learning to solve a constrained optimization problem.

• Part 2: Learning to solve a quadratically-constrained optimization problem.

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

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

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

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

System Identification of Ordinary Differential Equations (ODEs)

• Part 1: Neural Ordinary Differential Equations (NODEs)
• Part 2: Parameter estimation of ODE system
• Part 3: Universal Differential Equations (UDEs)
• Part 4: NODEs with exogenous inputs
• Part 5: Neural State Space Models (NSSMs) with exogenous inputs
• Part 6: Data-driven modeling of resistance-capacitance (RC) network ODEs
• Part 7: Deep Koopman operator
• Part 8: control-oriented Deep Koopman operator
• Part 9: Sparse Identification of Nonlinear Dynamics (SINDy)

Physics-Informed Neural Networks (PINNs) for Partial Differential Equations (PDEs) and Ordinary Differential Equations (ODEs)

• Part 1: Diffusion Equation
• Part 2: Burgers' Equation
• Part 3: Burgers' Equation w/ Parameter Estimation (Inverse Problem)
• Part 4: Laplace's Equation (steady-state)
• Part 5: Damped Pendulum (stacked PINN)
• Part 6: Navier-Stokes equation (lid-driven cavity flow, steady-state, KAN)

Learning to Control (L2C) with Differentiable Models

• Part 1: Learning to stabilize a linear dynamical system.
• Part 2: Learning to stabilize a nonlinear differential equation.
• Part 3: Learning to control a nonlinear differential equation.
• Part 4: Learning neural ODE model and control policy for an unknown dynamical system.
• Part 5: Learning neural Lyapunov function for a nonlinear dynamical system.

Domain Examples

• Part 1: Learning to Control Indoor Air Temperature in Buildings.
• Part 2: Learning to Control an Pumped-Hydroelectricity Energy Storage System.
• Part 3: Learning Building Thermal Dynamics using Neural ODEs.
• Part 4: Data-driven modeling of a Resistance-Capacitance network with Neural ODEs.
• Part 5: Learning Swing Equation Dynamics using Neural ODEs.
• Part 6: Learning Building Thermal Dynamics using Neural State Space Models.

Lightning Integration Examples

• Part 1: Lightning Integration Basics.
• Part 2: Lightning Advanced Features and Automatic GPU Support.
• Part 3: Hyperparameter Tuning With Lightning & WandB
• Part 4: Defining Custom Training Logic via Lightning Modularized Code.

Stochastic Differential Equations (SDEs)

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

Documentation

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

# 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)

UML diagram of NeuroMANCER classes.

Installation

PIP Install (recommended)

Consider using a dedicated virtual environment (conda or otherwise) with Python 3.9+ installed.

pip install neuromancer

Example usage:

import torch
from neuromancer.system import Node

fun_1 = lambda x1, x2: 2.*x1 - x2**2
node_3 = Node(fun_1, ['y1', 'y2'], ['y3'], name='quadratic')
# evaluate forward pass of the node with dictionary input dataset
print(node_3({'y1': torch.rand(2), 'y2': torch.rand(2)}))

Manual Install

First clone the neuromancer package. A dedicated virtual environment (conda or otherwise) is recommended.

Note: If you have a previous neuromancer env it would be best at this point to create a new environment given the following instructions.

git clone -b master https://github.com/pnnl/neuromancer.git --single-branch

Create and activate virtual environment

conda create -n neuromancer python=3.10.4
conda activate neuromancer

Install neuromancer and all dependencies.

From top level directory of cloned neuromancer run:

pip install -e.[docs,tests,examples]

OR, for zsh users:

pip install -e.'[docs,tests,examples]'

See the pyproject.toml file for reference.

[project.optional-dependencies]
tests = ["pytest", "hypothesis"]
examples = ["casadi", "cvxpy", "imageio", "cvxpylayers"]
docs = ["sphinx", "sphinx-rtd-theme"]

Note on pip install with examples on MacOS (Apple M1)

Before CVXPY can be installed on Apple M1, you must install cmake via Homebrew:

brew install cmake

See CVXPY installation instructions for more details.

Conda install

Conda install is recommended for GPU acceleration.

❗️Warning: linux_env.yml, windows_env.yml, and osxarm64_env.yml are out of date. Manual installation of dependencies is recommended for conda.

Create environment & install dependencies

Ubuntu

conda env create -f linux_env.yml
conda activate neuromancer

Windows

conda env create -f windows_env.yml
conda activate neuromancer
conda install -c defaults intel-openmp -f

MacOS (Apple Silicon)

conda env create -f osxarm64_env.yml
conda activate neuromancer

Other (manually install all dependencies)

!!! Pay attention to comments for non-Linux OS !!!

conda create -n neuromancer python=3.10.4
conda activate neuromancer
conda install pytorch pytorch-cuda=11.6 -c pytorch -c nvidia
## OR (for Mac): conda install pytorch -c pytorch
conda config --append channels conda-forge
conda install scipy numpy"<1.24.0" matplotlib scikit-learn pandas dill mlflow pydot=1.4.2 pyts numba
conda install networkx=3.0 plum-dispatch=1.7.3 
conda install -c anaconda pytest hypothesis
conda install cvxpy cvxopt casadi seaborn imageio
conda install tqdm torchdiffeq toml
conda install lightning wandb -c conda-forge
## (for Windows): conda install -c defaults intel-openmp -f

Install NeuroMANCER package

From the top level directory of cloned neuromancer (in the activated environment where the dependencies have been installed):

pip install -e . --no-deps

Install Graphviz (optional)

In order to use the Problem graph plots, we recommend installing Graphviz system-wide. Note that this feature is optional.

For Windows:

Package must be installed manually: Graphviz website

For Linux (Debian, Ubuntu)

sudo apt install graphviz

For MacOS

brew install graphviz

Test NeuroMANCER install

Run pytest on the tests folder. It should take about 2 minutes to run the tests on CPU. There will be a lot of warnings that you can safely ignore. These warnings will be cleaned up in a future release.

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

• 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

Active core developers: Jan Drgona, Rahul Birmiwal, Bruno Jacob
Notable contributors: Aaron Tuor, Madelyn Shapiro, James Koch, Seth Briney, Bo Tang, Ethan King, Elliot Skomski, Zhao Chen, Christian Møldrup Legaard
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. 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.