{"id":13473283,"url":"https://github.com/Shunichi09/PythonLinearNonlinearControl","last_synced_at":"2025-03-26T17:32:28.455Z","repository":{"id":44460051,"uuid":"161974754","full_name":"Shunichi09/PythonLinearNonlinearControl","owner":"Shunichi09","description":"PythonLinearNonLinearControl is a library implementing the linear and nonlinear control theories in python.","archived":false,"fork":false,"pushed_at":"2021-08-23T12:57:01.000Z","size":1014,"stargazers_count":899,"open_issues_count":2,"forks_count":179,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-03T20:15:33.632Z","etag":null,"topics":["cem","ddp","ilqr","linear-control","model-based-rl","model-predictive-control","mpc","mppi","nmpc","nonlinear-control","optimal-control","reinforcement-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shunichi09.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"licenses/GPL3+.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-16T06:35:25.000Z","updated_at":"2025-03-03T15:09:10.000Z","dependencies_parsed_at":"2022-08-21T23:40:49.271Z","dependency_job_id":null,"html_url":"https://github.com/Shunichi09/PythonLinearNonlinearControl","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shunichi09%2FPythonLinearNonlinearControl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shunichi09%2FPythonLinearNonlinearControl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shunichi09%2FPythonLinearNonlinearControl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shunichi09%2FPythonLinearNonlinearControl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shunichi09","download_url":"https://codeload.github.com/Shunichi09/PythonLinearNonlinearControl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245702565,"owners_count":20658634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cem","ddp","ilqr","linear-control","model-based-rl","model-predictive-control","mpc","mppi","nmpc","nonlinear-control","optimal-control","reinforcement-learning"],"created_at":"2024-07-31T16:01:02.368Z","updated_at":"2025-03-26T17:32:28.081Z","avatar_url":"https://github.com/Shunichi09.png","language":"Python","readme":"[![Coverage Status](https://coveralls.io/repos/github/Shunichi09/PythonLinearNonlinearControl/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/Shunichi09/PythonLinearNonlinearControl?branch=master\u0026service=github)\n[![GitHub issues open](https://img.shields.io/github/issues/Shunichi09/PythonLinearNonlinearControl.svg)]()\n[![Build Status](https://travis-ci.org/Shunichi09/PythonLinearNonlinearControl.svg?branch=master\u0026service=github)](https://travis-ci.org/Shunichi09/PythonLinearNonlinearControl)\n\n# PythonLinearNonlinearControl\n\nPythonLinearNonlinearControl is a library implementing the linear and nonlinear control theories in python.\nDue to use only basic libralies (scipy, numpy), this library is easy to extend for your own situations.\n\n\u003cdiv\u003e\u003cimg src=\"assets/concept.png\" width=\"500\"/\u003e\u003c/div\u003e\n\n\u003cimg src=\"assets/cartpole.gif\" width=\"350\"\u003e \u003cimg src=\"assets/twowheeledtrack.gif\" width=\"350\"\u003e\n\n# Algorithms\n\n| Algorithm | Use Linear Model | Use Nonlinear Model | Need Gradient (Hamiltonian) | Need Gradient (Model) | Need Hessian (Model) |\n|:----------|:---------------: |:----------------:|:----------------:|:----------------:|:----------------:|\n| Linear Model Predictive Control (MPC) | ✓ | x | x | x | x |\n| Cross Entropy Method (CEM) | ✓ | ✓ | x | x | x |\n| Model Predictive Path Integral Control of Nagabandi, A. (MPPI) | ✓ | ✓ | x | x | x |\n| Model Predictive Path Integral Control of Williams, G. (MPPIWilliams) | ✓ | ✓ | x | x | x |\n| Random Shooting Method (Random) | ✓ | ✓ | x | x | x |\n| Iterative LQR (iLQR) | x | ✓ | x | ✓ | x |\n| Differential Dynamic Programming (DDP) | x | ✓ | x | ✓ | ✓ |\n| Unconstrained Nonlinear Model Predictive Control (NMPC) | x | ✓ | ✓ | x | x |\n| Constrained Nonlinear Model Predictive Control CGMRES (NMPC-CGMRES) | x | ✓ | ✓ | x | x |\n| Constrained Nonlinear Model Predictive Control Newton (NMPC-Newton) | x | ✓ | x | x | x |\n\n\"Need Gradient\" means that you have to implement the gradient of the model or the gradient of hamiltonian.  \n\nFollowing algorithms are implemented in PythonLinearNonlinearControl\n\n- [Linear Model Predictive Control (MPC)](http://www2.eng.cam.ac.uk/~jmm1/mpcbook/mpcbook.html)\n  - Ref: Maciejowski, J. M. (2002). Predictive control: with constraints.\n    - [script](PythonLinearNonlinearControl/controllers/mpc.py)\n- [Cross Entropy Method (CEM)](https://arxiv.org/abs/1805.12114)\n  - Ref: Chua, K., Calandra, R., McAllister, R., \u0026 Levine, S. (2018). Deep reinforcement learning in a handful of trials using probabilistic dynamics models. In Advances in Neural Information Processing Systems (pp. 4754-4765)\n    - [script](PythonLinearNonlinearControl/controllers/cem.py)\n- [Model Predictive Path Integral Control of Nagabandi, A. (MPPI)](https://arxiv.org/abs/1909.11652)\n  - Ref: Nagabandi, A., Konoglie, K., Levine, S., \u0026 Kumar, V. (2019). Deep Dynamics Models for Learning Dexterous Manipulation. arXiv preprint arXiv:1909.11652.\n    - [script](PythonLinearNonlinearControl/controllers/mppi.py)\n- [Model Predictive Path Integral Control of Williams, G. (MPPIWilliams)](https://ieeexplore.ieee.org/abstract/document/7989202)\n  - Ref: Williams, G., Wagener, N., Goldfain, B., Drews, P., Rehg, J. M., Boots, B., \u0026 Theodorou, E. A. (2017, May). Information theoretic MPC for model-based reinforcement learning. In 2017 IEEE International Conference on Robotics and Automation (ICRA) (pp. 1714-1721). IEEE.\n    - [script](PythonLinearNonlinearControl/controllers/mppi_williams.py)\n- [Random Shooting Method (Random)](https://arxiv.org/abs/1805.12114)\n  - Ref: Chua, K., Calandra, R., McAllister, R., \u0026 Levine, S. (2018). Deep reinforcement learning in a handful of trials using probabilistic dynamics models. In Advances in Neural Information Processing Systems (pp. 4754-4765)\n    - [script](PythonLinearNonlinearControl/controllers/random.py)\n- [Iterative LQR (iLQR)](https://ieeexplore.ieee.org/document/6386025)\n  - Ref: Tassa, Y., Erez, T., \u0026 Todorov, E. (2012, October). Synthesis and stabilization of complex behaviors through online trajectory optimization. In 2012 IEEE/RSJ International Conference on Intelligent Robots and Systems (pp. 4906-4913). IEEE. and [Study Wolf](https://github.com/studywolf/control), https://github.com/anassinator/ilqr\n    - [script](PythonLinearNonlinearControl/controllers/ilqr.py)\n- [Dynamic Differential Programming (DDP)](https://ieeexplore.ieee.org/document/6386025)\n  - Ref: Tassa, Y., Erez, T., \u0026 Todorov, E. (2012, October). Synthesis and stabilization of complex behaviors through online trajectory optimization. In 2012 IEEE/RSJ International Conference on Intelligent Robots and Systems (pp. 4906-4913). IEEE. and [Study Wolf](https://github.com/studywolf/control), https://github.com/anassinator/ilqr\n    - [script](PythonLinearNonlinearControl/controllers/ddp.py)\n- [Unconstrained Nonlinear Model Predictive Control (NMPC)](https://www.sciencedirect.com/science/article/pii/S0005109897000058)\n  - Ref: Ohtsuka, T., \u0026 Fujii, H. A. (1997). Real-time optimization algorithm for nonlinear receding-horizon control. Automatica, 33(6), 1147-1154.\n    - [script](PythonLinearNonlinearControl/controllers/nmpc.py)\n- [Constrained Nonlinear Model Predictive Control -CGMRES- (NMPC-CGMRES)](https://www.sciencedirect.com/science/article/pii/S0005109897000058)\n  - Ref: Ohtsuka, T., \u0026 Fujii, H. A. (1997). Real-time optimization algorithm for nonlinear receding-horizon control. Automatica, 33(6), 1147-1154.\n    - [script](PythonLinearNonlinearControl/controllers/nmpc_cgmres.py)\n- [Constrained Nonlinear Model Predictive Control -Newton- (NMPC-Newton)](https://www.sciencedirect.com/science/article/pii/S0005109897000058)\n  - Ref: Ohtsuka, T., \u0026 Fujii, H. A. (1997). Real-time optimization algorithm for nonlinear receding-horizon control. Automatica, 33(6), 1147-1154.\n    - [script (Coming soon)]()\n\n# Environments\n\nThere are 4 example environments, \"FirstOrderLag\", \"TwoWheeledConst\", \"TwoWheeledTrack\" and \"Cartpole\".\n\n| Name | Linear | Nonlinear | State Size | Input size |\n|:----------|:---------------:|:----------------:|:----------------:|:----------------:|\n| First Order Lag System | ✓ | x | 4 | 2 | \n| Two wheeled System (Constant Goal) | x | ✓ | 3 | 2 | \n| Two wheeled System (Moving Goal) | x | ✓ | 3 | 2 | \n| Cartpole (Swing up) | x | ✓ | 4 | 1 | \n| Nonlinear Sample System Env | x | ✓ | 2 | 1 | \n\nAll states and inputs of environments are continuous.\n**It should be noted that the algorithms for linear model could be applied to nonlinear enviroments if you have linealized the model of nonlinear environments.**\n\nYou could know abount our environmets more in [Environments.md](Environments.md)\n\n# Installation\n\n## To install this package\n\n```\n$ pip install PythonLinearNonlinearControl\n```\n\n## When developing the package\n\n```\n$ python setup.py develop\n```\n\nor\n\n```\n$ pip install -e .\n```\n\n# Basic concepts\n\nWhen we design control systems, we should have **Model**, **Planner**, **Controller** and **Runner** as shown in the figure.\nIt should be noted that **Model** and **Environment** are different. As mentioned before, we the algorithms for linear model could be applied to nonlinear enviroments if you have linealized model of nonlinear environments. In addition, you can use Neural Network or any non-linear functions to the model, although this library can not deal with it now.\n\n\u003cimg src=\"assets/concept.png\" width=\"500\"\u003e\n\n## [Model](PythonLinearNonlinearControl/models/)\n\nSystem model. For an instance, in the case that a model is linear, this model should have a form, \"x[k+1] = Ax[k] + Bu[k]\".\n\nIf you use gradient based control method, you are preferred to implement the gradients of the model, other wise the controllers use numeric gradients.\n\n## [Planner](PythonLinearNonlinearControl/planners/)\n\nPlanner make the goal states.\n\n## [Controller](PythonLinearNonlinearControl/controllers/)\n\nController calculate the optimal inputs by using the model by using the algorithms.\n\n## [Runner](PythonLinearNonlinearControl/runners/)\n\nRunner runs the simulation.\n\nPlease, see more detail in each scripts.\n\n# Getting started\n\n## [QuickStart Guide](scripts/quickstart/quickstart.md)\n\nThis is a quickstart guide for users who just want to try PythonLinearNonlinearControl.\nIf you have not installed PythonLinearNonLinearControl, please see the section of \"how to setup\" in README.md\n\nWhen we design control systems, we should have Environment, Model, Planner, Controller and Runner.\nTherefore your script contains those Modules.\n\nFirst, import each Modules from PythonLinearNonlinearControl.\n\n```py\nfrom PythonLinearNonlinearControl import configs \nfrom PythonLinearNonlinearControl import envs\nfrom PythonLinearNonlinearControl import models\nfrom PythonLinearNonlinearControl import planners\nfrom PythonLinearNonlinearControl import controllers\nfrom PythonLinearNonlinearControl import runners\n```\n\nConfigs contains each modules configurations such as cost functions, prediction length, ...etc.\n\nThen you can make each module. (This is example about CEM and CartPole env)\n\n```py\nconfig = configs.CartPoleConfigModule()\nenv = envs.CartPoleEnv()\nmodel = models.CartPoleModel(config)\ncontroller = controllers.CEM(config, model)\nplanner = planners.ConstantPlanner(config)\nrunner = runners.ExpRunner()\n```\n\nThe preparation for experiment has done!\nPlease run the runner.\n\n```py\nhistory_x, history_u, history_g = runner.run(env, controller, planner) \n```\n\nYou can get the results of history of state, history of input and history of goal.\nUse that histories to visualize the Animation or Figures.\n(Note FirstOrderEnv does not support animation)\n\n```py\n# plot results\nplot_results(history_x, history_u, history_g=history_g)\nsave_plot_data(history_x, history_u, history_g=history_g)\n\n# create animation\nanimator = Animator(env)\nanimator.draw(history_x, history_g)\n```\n**It should be noted that the controller parameters like Q, R and Sf strongly affect the performence of the controller.\nPlease, check these parameters before you run the simulation.**\n\n## Run Example Script\n\nYou can run the example script as follows:\n\n```\npython scripts/simple_run.py --env CartPole --controller CEM --save_anim 1\n```\n\n**figures and animations are saved in the ./result folder.**\n\n# Old version\n\nIf you are interested in the old version of this library, that was not a library just examples, please see [v1.0](https://github.com/Shunichi09/PythonLinearNonlinearControl/tree/v1.0)\n\n# Documents\n\nComing soon !!\n\n# Requirements\n\n- numpy\n- scipy\n- matplotlib (for figures and animations)\n- ffmpeg (for animations)\n\n# License\n\nPythonLinearNonlinearControl is licensed under the MIT License. However, some scripts are available under different license terms. See below.\n\nThe following parts are licensed under GPL3+:\n\n- [ilqr](PythonLinearNonlinearControl/controllers/ilqr.py)\n- [ddp](PythonLinearNonlinearControl/controllers/ddp.py)\n\nSee the [licenses folder](./licenses) for the full text of the licenses.\n\n# Citation\n\n```\n@Misc{PythonLinearNonLinearControl,\nauthor = {Shunichi Sekiguchi},\ntitle = {PythonLinearNonlinearControl},\nnote = \"\\url{https://github.com/Shunichi09/PythonLinearNonlinearControl}\",\n}\n```\n","funding_links":[],"categories":["Python","\u003cspan id=\"head29\"\u003e3.3. Optimal Control\u003c/span\u003e"],"sub_categories":["3.2.5. First Order Methods"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShunichi09%2FPythonLinearNonlinearControl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShunichi09%2FPythonLinearNonlinearControl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShunichi09%2FPythonLinearNonlinearControl/lists"}