Welcome to our NCM python package for real-time robust nonlinear estimation and control via convex optimization. Here is a brief summary of what you can achieve with this repository.

• optimal, provably-stable, robust, and real-time state estimation and control policies of a given nonlinear dynamical system
• Neural Contraction Metrics (NCMs)

• nonlinear dynamical system : f of dx/dt = f(x)+g(x)u
• measurement equation (for state estimation) : h of y = h(x)
• actuation matrix (for feedback control) : g of dx/dt = f(x)+g(x)u
• state space of your interest

This repository contains the NCM class file which automatically constructs an NCM of a given nonlinear dynamical system, and Jupyter Notebook examples for estimation and control of perturbed nonlinear dynamical systems using an NCM introduced in this paper. Here are some important facts about the NCM.

1. The NCM is a global neural network-based approximation of an optimal contraction metric.
2. The existence of a contraction metric is a necessary and sufficient condition for exponential stability of nonlinear systems.
3. The optimality of NCMs stems from the fact that the contraction metrics sampled offline are the solutions of a convex optimization problem (see CV-STEM for more details) to minimize an upper bound of the steady-state Euclidean distance between perturbed and unperturbed system trajectories.
4. Due to the differential formulation of contraction analysis, there exists a nonlinear version of estimation and control duality, analogous to the one of the Kalman filter and LQR duality in linear systems (see the NCM paper for more).
5. Note that the NCM class file assumes input affine autonomous nonlinear systems, but you can always convert input non-affine non-autonomous systems into an input affine autonomous form by treating t as a state variable and du/dt as a control input.

MIT License

Copyright (c) 2020 Hiroyasu Tsukamoto

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

• NCMestimation.ipynb : Jupyter Notebook that illustrates how to use classncm.py for nonlinear optimal state estimation
• NCMcontrol.ipynb : Jupyter Notebook that illustrates how to use classncm.py for nonlinear optimal feedback control
• classncm.py : class file that contains functions required for constructing an NCM of a given nonlinear dynamical system

In addition to standard python packages like numpy, you need several other packages and software. The NCM class file classncm.py has been verified to work with CVXPY 1.1.1, Mosek 9.2.11, TensorFlow 2.2.0, and Keras 2.3.1.

• Jupyter Notebook to see and edit codes
• CVXPY and Mosek to solve convex optimization problems
• Keras and TensorFlow to construct neural networks (Keras comes packaged with TensorFlow 2.0 as tensorflow.keras)

• nonlinear dynamical system : f of dx/dt = f(x)+g(x)u
• measurement equation (for state estimation) : h of y = h(x)
• actuation matrix (for feedback control) : g of dx/dt = f(x)+g(x)u
• your guess of contraction rate : just put a small number if not sure

The detailed explanation on its methods and objects are given in the documentation. Here we introduce some useful methods for the NCM design. The trade-off between larger feedback gains (larger nu) and smaller steady-state tracking error (smaller chi) discussed in the NCM paper can be handled by changing the values d1_over and d2_over in the NCM class.

• ncm : Returns a trained NCM with respect to a given state.
• train : Trains a neural network to be used for designing an NCM and returns a Keras neural network model.
• cvstem : Samples optimal contraction metrics of a given dynamical system in a given state space by the CV-STEM method. These metrics will be used for the neural network training in the train method.
• linesearch : Finds the optimal contraction rate by line search.
• simulation : Performs NCM-based estimation or control of a given nonlinear dynamical systems and returns simulation results.

The convex optimization problem in the cvstem method could become infeasible for some nonlinear dynamical systems under certain choices of parameters. Here are some tips in avoiding such infeasibility in practice.

• Start from smaller value of alpha : Since the stability constraint becomes tighter as alpha (contraction rate) becomes larger, set alims[0] (minimum alpha) smaller.
• Select smaller state space : Since larger state space could lead to stricter stability constraints, set xlims to represent smaller state space.
• Use larger CV-STEM sampling period : It is better to use a smaller CV-STEM sampling period dt when computing dW/dt (W: normalized inverse of a contraction metric) from a theoretical point of view, but it could cause some numerical issues. You can relax dt to some larger values.
• Write your dynamics in state-dependend coefficient form : The NCM class uses Jacobian of f(x) and h(x) for parameters Afun and Cfun by default. Instead you could use extended linearization, i.e. use A(x) and C(x) s.t. f(x) = A(x)x and h(x) = C(x)x for Cfun and Afun. See the CV-STEM paper for more.
• Pre-compute xd and ud : For some systems, a feedback control law u = -K(x)x is not sufficient to stabilize them in practice. You could try u = -K(x)(x-xd)+ud instead using a pre-computed desired trajectory and input xd and ud.
• Change d1_over and d2_over from their default values : Although this will not affect the infeasibility theoretically, it may solve some numerical issues.
• Try different solvers : The default solver for the NCM class is Mosek. You can change "solver=cp.MOSEK" in the class file to something different such as cp.CVXOPT.
• Solve CV-STEM problems along pre-computed trajectories : The NCM class computes dW/dt (W: normalized inverse of a contraction metric) using a lower bound of the induced 2-norm of a contraction metric. You could run the CV-STEM along given trajectories as was done in the NCM paper seeking for a less tight stability condition. The source codes of this paper will give you some ideas.
• Set epsilon to some positive value : There is a parameter called epsilon in the NCM class, and if you select epsilon > 0 then the stability condition can be relaxed. You could also use epsilon as a decision variable and minimize it to have tightest relaxation but stability in a sense described in the NCM paper is no longer guaranteed.
• Try CVX if you have MATLAB : The CVX can sometimes obtain optimal solutions even when the solvers in CVXPY fail. We have a matlab version of the NCM class although it is under development.
• If all of these approaches do not work or you have any questions, please contact us.