NeuroMANCER v1.3.2

Neural Modules with Adaptive Nonlinear Constraints and Efficient Regularizations.

Authors: Aaron Tuor, Jan Drgona, Mia Skomski, Stefan Dernbach, James Koch, Zhao Chen, Christian Møldrup Legaard, Draguna Vrabie, Madelyn Shapiro

Colab tutorials

Parametric programming
- Rosenbrook

+ Himmelblau

System Identification

Double Integrator

Control

Version 1.3.2 Release Notes

Merged Structured Linear Maps and Pyton Systems Library into Neuromancer
- The code in neuromancer was closely tied to psl and slim. A decision was made to integrate the packages as submodules of neuromancer. This also solves the issue of the package names "psl" and "slim" already being taken on PyPI.

Import changes for psl and slim

# before
import psl
import slim

# now
from neuromancer import psl
from neuromancer import slim

Documentation

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

# Neuromancer syntax example for differentiable parametric programming
import neuromancer as nm

# primal solution map to be trained
func = nm.blocks.MLP(insize=2, outsize=2, hsizes=[80] * 4)
sol_map = nm.maps.Map(func,
        input_keys=["a", "p"],
        output_keys=["x"],
        name='primal_map')

# problem primal variables
x = nm.constraint.variable("x")[:, [0]]
y = nm.constraint.variable("x")[:, [1]]

# sampled problem parameters
p = nm.constraint.variable('p')
a = nm.constraint.variable('a')

# nonlinear objective function
f = (1-x)**2 + a*(y-x**2)**2
obj = f.minimize(weight=1., name='obj')

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

# create constrained optimization loss
objectives = [obj]
constraints = [con_1, con_2, con_3]
loss = nm.loss.PenaltyLoss(objectives, constraints)
# construct constrained optimization problem
components = [sol_map]
problem = nm.problem.Problem(components, loss)

UML diagram of NeuroMANCER classes.

Installation

For either pip or conda installation, 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

Conda install

Conda install is recommended for GPU acceleration. In many cases the following simple install should work for the specified OS

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

conda env create -f osxarm64_env.yml
conda activate neuromancer

Other operating system

!!! 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 matplotlib scikit-learn pandas dill mlflow pydot=1.4.2 pyts numba
conda install networkx=3.0 plum-dispatch 
conda install -c anaconda pytest hypothesis
conda install cvxpy cvxopt casadi seaborn imageio
conda install tqdm torchdiffeq toml
## (for Windows): conda install -c defaults intel-openmp -f

PIP Install

Pip installation is broken up into required dependencies for core Neuromancer and dependencies associated with the examples, tests, and generating the documentation. Below we give instructions to install all dependencies in a conda virtual enviroment via pip.

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]

See the pyproject.toml file for reference.

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

Test NeuroMANCER install

Run pytest on the test 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.

Examples

For detailed examples of NeuroMANCER usage for control, system identification, and parametric programming as well as tutorials for basic usage, see the scripts in the examples folder.

New in 1.3.1: Interactive notebook versions of examples are available on Google Colab! Test out NeuroMANCER functionality before cloning the repository and setting up an environment. We currently have three interactive notebook examples:

examples/control/double_integrator_DPC_interactive.ipynb
examples/parametric_programming/Himmelblau_interactive.ipynb
examples/duffing_parameter_interactive.ipynb

Community

Contributing examples

If you have an example of using NeuroMANCER to solve an interesting problem, or of using NeuroMANCER in a unique way, we would love to see it incorporated into our current library of examples. To submit an example, create a folder for your example/s in the example folder if there isn't currently an applicable folder and place either your executable python file or notebook file there. Push your code back to github and then submit a pull request. Please make sure to note in a comment at the top of your code if there are additional dependencies to run your example and how to install those dependencies.

Contributing code

We welcome contributions to NeuroMANCER. Please accompany contributions with some lightweight unit tests via pytest (see test/ folder for some examples of easy to compose unit tests using pytest). In addition to unit tests a script utilizing introduced new classes or modules should be placed in the examples folder. To contribute a new feature please submit a pull request.

Reporting issues or bugs

If you find a bug in the code or want to request a new feature, please open an issue.

NeuroMANCER development plan

Here are some upcoming features we plan to develop. Please let us know if you would like to get involved and contribute so we may be able to coordinate on development. If there is a feature that you think would be highly valuable but not included below, please open an issue and let us know your thoughts.

Faster dynamics modeling via Torchscript
Control and modelling for networked systems
Easy to implement modeling and control with uncertainty quantification
Online learning examples
Benchmark examples of DPC compared to deep RL
Conda and pip package distribution
CVXPY-like interface for optimization via Problem.solve method
More versatile and simplified time series dataloading
Pytorch Lightning trainer compatibility
Discovery of governing equations from learned RHS via NODEs and SINDy

Publications

Cite as

@article{Neuromancer2022,
  title={{NeuroMANCER: Neural Modules with Adaptive Nonlinear Constraints and Efficient Regularizations}},
  author={Tuor, Aaron and Drgona, Jan and Skomski, Mia and Koch, James and Chen, Zhao and Dernbach, Stefan and Legaard, Christian Møldrup and Vrabie, Draguna},
  Url= {https://github.com/pnnl/neuromancer}, 
  year={2022}
}

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.

Prior release notes

Version 1.3.1 release notes

New example scripts and notebooks
- Interactive Colab notebooks for testing Neuromancer functionality without setting up an environment
  - See Examples for links to Colab
- RC-Network modeling using Graph Neural Time-steppers example:
  - See neuromancer/examples/graph_timesteppers/
- Baseline NODE dynamics modeling results for all nonautonomous systems in Python Systems Library
  - See neuromancer/examples/benchmarks/node/
- Updated install instructions for Linux, Windows, and MAC operating systems
  - New linux_env.yml, windows_env.yml, osxarm64_env.yml files for installation of dependencies across OS
Corresponding releases of SLiM and PSL packages
- Make sure to update these packages if updating Neuromancer
- Release 1.4 will roll SLiM and PSL into core Neuromancer for ease of installation and development

Version 1.3 release notes

Tutorial YouTube videos to accompany tutorial scripts in examples folder:
- examples/system_identification/duffing_parameter.py
Closed loop control policy learning examples with Neural Ordinary Differential Equations
- examples/control/
  - vdpo_DPC_cl_fixed_ref.py
  - two_tank_sysID_DPC_cl_var_ref.py
  - two_tank_DPC_cl_var_ref.py
  - two_tank_DPC_cl_fixed_ref.py
Closed loop control policy learning example with Linear State Space Models.
- examples/control/
  - double_integrator_dpc_ol_fixed_ref.py
  - vtol_dpc_ol_fixed_ref.py
New class for Linear State Space Models (LSSM)
- LinearSSM in dynamics.py
Refactored closed loop control policy simulations
- simulator.py
Interfaces for open and closed loop simulation (evaluation after training) for several classes
- Dynamics
- Estimator
- Policy
- Constraint
- PSL Emulator classes
New class for closed-loop policy learning of non-autonomous ODE systems
- ControlODE class in ode.py
Added support for NODE systems
- Torchdiffeq integration with fast adjoint method for NODE optimization

pnnl/neuromancer

pnnl

Reviews

Repository Details