neuromancer

# 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](https://pytorch.org/) 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](#overview) 2. [Key Features](#key-features) 3. [What's New in v1.5.3](#whats-new-in-v153) 4. [Installation](#installation) 5. [Getting Started](#getting-started) 6. [Tutorials](#domain-examples) 6. [Documentation and User Guides](#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](https://github.com/pnnl/neuromancer/blob/develop/assistant/README.md) 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](INSTALLATION.md) ## Getting Started An extensive set of tutorials can be found in the [examples](https://github.com/pnnl/neuromancer/tree/master/examples) folder and the [Tutorials](#domain-examples) 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. ``` … ``` ## 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](#tutorials-on-methods-for-modeling-optimization-and-control) 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](https://github.com/pnnl/neuromancer/tree/develop/examples/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](https://github.com/pnnl/neuromancer/tree/develop/examples/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](https://github.com/pnnl/neuromancer/tree/develop/examples/KANs) + 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