Package: neuromancer
NeuroMANCER v1.4.2Neural 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 inPyTorchand 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.New in v1.4.2insert updates hereNew in v1.4.1We've made some backwards-compatible changes in order to simplify integration and support multiple symbolic inputs tonn.Modulesin ourblocksinterface.New Colab Examples:⭐Physics-Informed Neural Networks (PINNs) for solving partial differential equations (PDEs) in NeuroMANCER⭐System identification for ordinary differential equations (ODEs)Seev1.4.1 release notesfor more details.Features and ExamplesExtensive set of tutorials can be found in theexamplesfolder.
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 NeuroMANCERPart 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.Parametric ProgrammingPart 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 projected gradient method.Ordinary Differential Equations (ODEs)Part 1: Neural Ordinary Differential Equations (NODEs)Part 2: Parameter estimation of ODE systemPart 3: Universal Differential Equations (UDEs)Part 4: NODEs with exogenous inputsPart 5: Neural State Space Models (NSSMs) with exogenous inputsPart 6: Data-driven modeling of resistance-capacitance (RC) network ODEsPart 7: Deep Koopman operatorPart 8: control-oriented Deep Koopman operatorPhysics-Informed Neural Networks (PINNs) for Partial Differential Equations (PDEs)Part 1: Diffusion EquationPart 2: Burgers' EquationPart 3: Burgers' Equation w/ Parameter Estimation (Inverse Problem)ControlPart 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.DocumentationThe documentation for the library can be foundonline.
There is also anintroduction videocovering
core features of the library.# Neuromancer syntax example for constrained optimizationimportneuromancerasnmimporttorch# define neural architecturefunc=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) -> xmap=nm.system.Node(func,['p'],['x'],name='map')# define decision variablesx=nm.constraint.variable("x")[:,[0]]y=nm.constraint.variable("x")[:,[1]]# problem parameters sampled in the datasetp=nm.constraint.variable('p')# define objective functionf=(1-x)**2+(y-x**2)**2obj=f.minimize(weight=1.0)# define constraintscon_1=100.*(x>=y)con_2=100.*(x**2+y**2<=p**2)# create penalty method-based loss functionloss=nm.loss.PenaltyLoss(objectives=[obj],constraints=[con_1,con_2])# construct differentiable constrained optimization problemproblem=nm.problem.Problem(nodes=[map],loss=loss)UML diagram of NeuroMANCER classes.InstallationPIP Install (recommended)Consider using a dedicated virtual environment (conda or otherwise) with Python 3.9+ installed.pipinstallneuromancerExample usage:importtorch
fromneuromancer.systemimportNodefun_1=lambdax1,x2:2.*x1-x2**2node_3=Node(fun_1,['y1','y2'],['y3'],name='quadratic')# evaluate forward pass of the node with dictionary input datasetprint(node_3({'y1':torch.rand(2),'y2':torch.rand(2)}))Manual InstallFirst 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.gitclone-bmasterhttps://github.com/pnnl/neuromancer.git--single-branchCreate and activate virtual environmentcondacreate-nneuromancerpython=3.10.4
condaactivateneuromancerInstall neuromancer and all dependencies.From top level directory of cloned neuromancer run:pipinstall-e.[docs,tests,examples]OR, for zsh users:pipinstall-e.'[docs,tests,examples]'See thepyproject.tomlfile for reference.[project.optional-dependencies]tests=["pytest","hypothesis"]examples=["casadi","cvxpy","imageio"]docs=["sphinx","sphinx-rtd-theme"]Note on pip install withexampleson MacOS (Apple M1)Before CVXPY can be installed on Apple M1, you must installcmakevia Homebrew:brewinstallcmakeSeeCVXPY installation instructionsfor more details.Conda installConda install is recommended for GPU acceleration.
In many cases the following simple install should work for the specified OSCreate environment & install dependenciesUbuntucondaenvcreate-flinux_env.yml
condaactivateneuromancerWindowscondaenvcreate-fwindows_env.yml
condaactivateneuromancer
condainstall-cdefaultsintel-openmp-fMacOS (Apple M1)condaenvcreate-fosxarm64_env.yml
condaactivateneuromancerOther (manually install all dependencies)!!! Pay attention to comments for non-Linux OS !!!condacreate-nneuromancerpython=3.10.4
condaactivateneuromancer
condainstallpytorchpytorch-cuda=11.6-cpytorch-cnvidia## OR (for Mac): conda install pytorch -c pytorchcondaconfig--appendchannelsconda-forge
condainstallscipynumpy"<1.24.0"matplotlibscikit-learnpandasdillmlflowpydot=1.4.2pytsnumba
condainstallnetworkx=3.0plum-dispatch=1.7.3condainstall-canacondapytesthypothesis
condainstallcvxpycvxoptcasadiseabornimageio
condainstalltqdmtorchdiffeqtoml## (for Windows): conda install -c defaults intel-openmp -fInstall NeuroMANCER packageFrom the top level directory of cloned neuromancer
(in the activated environment where the dependencies have been installed):pipinstall-e.--no-depsTest NeuroMANCER installRun pytest on thetests 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 InformationWe welcome contributions and feedback from the open-source community!Contributions, Discussions, and IssuesPlease read theCommunity Development Guidelinesfor further information on contributions,discussions, andIssues.Release notesSee theRelease notesdocumenting new features.LicenseNeuroMANCER comes withBSD license.
See thelicensefor further details.PublicationsJames 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 2022Wenceslao 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 2022Ethan 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-92Drgona, 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, 2022Drgona, 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 Vrabie, Draguna},Url= {https://github.com/pnnl/neuromancer},year={2023}}Development teamLead developers: Jan Drgona, Aaron TuorActive core developers: James Koch, Madelyn ShapiroScientific advisors: Draguna VrabieNotable contributors: Seth Briney, Bo Tang, Ethan King, Shrirang Abhyankar,
Mia Skomski, Stefan Dernbach, Zhao Chen, Christian Møldrup LegaardOpen-source contributions made by:Made withcontrib.rocks.AcknowledgmentsThis 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.