{"id":16693461,"url":"https://github.com/stephane-caron/qpmpc","last_synced_at":"2025-09-14T05:32:38.059Z","repository":{"id":37725389,"uuid":"475907332","full_name":"stephane-caron/qpmpc","owner":"stephane-caron","description":"Model predictive control in Python based on quadratic programming","archived":false,"fork":false,"pushed_at":"2025-03-11T11:13:30.000Z","size":345,"stargazers_count":37,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-15T03:38:04.546Z","etag":null,"topics":["linear-time-invariant","linear-time-variant","model-predictive-control","optimal-control","python","trajectory-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stephane-caron.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-30T14:06:55.000Z","updated_at":"2025-03-13T10:27:10.000Z","dependencies_parsed_at":"2023-11-14T11:31:44.768Z","dependency_job_id":"ef404ae4-3084-4792-9fb4-6bd4b63ee4cb","html_url":"https://github.com/stephane-caron/qpmpc","commit_stats":null,"previous_names":["tasts-robots/ltv-mpc","stephane-caron/qpmpc"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephane-caron%2Fqpmpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephane-caron%2Fqpmpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephane-caron%2Fqpmpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephane-caron%2Fqpmpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephane-caron","download_url":"https://codeload.github.com/stephane-caron/qpmpc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243835942,"owners_count":20355611,"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":["linear-time-invariant","linear-time-variant","model-predictive-control","optimal-control","python","trajectory-optimization"],"created_at":"2024-10-12T16:30:39.738Z","updated_at":"2025-03-17T00:33:23.020Z","avatar_url":"https://github.com/stephane-caron.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qpmpc\n\n[![CI](https://img.shields.io/github/actions/workflow/status/stephane-caron/qpmpc/ci.yml?branch=main)](https://github.com/stephane-caron/qpmpc/actions)\n[![Documentation](https://img.shields.io/badge/docs-online-brightgreen?style=flat)](https://scaron.info/doc/qpmpc/)\n[![Coverage](https://coveralls.io/repos/github/stephane-caron/qpmpc/badge.svg?branch=main)](https://coveralls.io/github/stephane-caron/qpmpc?branch=main)\n[![Conda version](https://img.shields.io/conda/vn/conda-forge/qpmpc.svg?color=blue)](https://anaconda.org/conda-forge/qpmpc)\n[![PyPI version](https://img.shields.io/pypi/v/qpmpc)](https://pypi.org/project/qpmpc/0.6.0/)\n\nModel predictive control (MPC) in Python for optimal-control problems that are quadratic programs (QP). This includes linear time-invariant (LTI) and time-variant (LTV) systems with linear constraints. The corresponding QP has the form:\n\n\u003e ![qpmpc](https://raw.githubusercontent.com/stephane-caron/qpmpc/main/doc/src/images/qpmpc.svg)\n\nThis module is designed for prototyping. If you need performance, check out the [alternatives](#alternatives) below.\n\n## Installation\n\n```sh\npip install qpmpc\n```\n\n## Usage\n\nThis module defines a one-stop shop function:\n\n```python\nsolve_mpc(problem: MPCProblem, solver: str) -\u003e Plan\n```\n\nThe [``MPCProblem``](https://scaron.info/doc/qpmpc/usage.html#qpmpc.mpc_problem.MPCProblem) defines the model predictive control problem (LTV system, LTV constraints, initial state and cost function to optimize) while the returned [``Plan``](https://scaron.info/doc/qpmpc/usage.html#qpmpc.plan.Plan) holds the state and input trajectories that result from optimizing the problem (if a solution exists). The ``solver`` string is used to select the backend [quadratic programming solver](https://github.com/stephane-caron/qpsolvers#solvers).\n\n## Example\n\nLet us define a triple integrator:\n\n```python\n    import numpy as np\n\n    horizon_duration = 1.0  # [s]\n    N = 16  # number of discretization steps\n    T = horizon_duration / N\n    A = np.array([[1.0, T, T ** 2 / 2.0], [0.0, 1.0, T], [0.0, 0.0, 1.0]])\n    B = np.array([T ** 3 / 6.0, T ** 2 / 2.0, T]).reshape((3, 1))\n```\n\nSuppose for the sake of example that acceleration is the main constraint acting on our system. We thus define an acceleration constraint ``|acceleration| \u003c= max_accel``:\n\n```python\n    max_accel = 3.0  # [m] / [s] / [s]\n    accel_from_state = np.array([0.0, 0.0, 1.0])\n    C = np.vstack([+accel_from_state, -accel_from_state])\n    e = np.array([+max_accel, +max_accel])\n```\n\nThis leads us to the following linear MPC problem:\n\n```python\n    from qpmpc import MPCProblem\n\n    x_init = np.array([0.0, 0.0, 0.0])\n    x_goal = np.array([1.0, 0.0, 0.0])\n    problem = MPCProblem(\n        transition_state_matrix=A,\n        transition_input_matrix=B,\n        ineq_state_matrix=C,\n        ineq_input_matrix=None,\n        ineq_vector=e,\n        initial_state=x_init,\n        goal_state=x_goal,\n        nb_timesteps=N,\n        terminal_cost_weight=1.0,\n        stage_state_cost_weight=None,\n        stage_input_cost_weight=1e-6,\n    )\n```\n\nWe can solve it with:\n\n```python\n    from qpmpc import solve_mpc\n\n    solution = solve_mpc(problem, solver=\"proxqp\")\n```\n\nThe solution holds complete state and input trajectories as stacked vectors. For instance, we can plot positions, velocities and accelerations as follows:\n\n```python\n    import pylab\n\n    t = np.linspace(0.0, horizon_duration, N + 1)\n    X = solution.states\n    positions, velocities, accelerations = X[:, 0], X[:, 1], X[:, 2]\n    pylab.ion()\n    pylab.plot(t, positions)\n    pylab.plot(t, velocities)\n    pylab.plot(t, accelerations)\n    pylab.grid(True)\n    pylab.legend((\"position\", \"velocity\", \"acceleration\"))\n```\n\nThis example produces the following trajectory:\n\n![2022-03-30-172206_1920x1080_scrot](https://user-images.githubusercontent.com/1189580/160871543-3734ec65-fe74-4a6f-8452-a877aa4050b1.png)\n\nThe behavior is a weighted compromise between reaching the goal state (weight ``1.0``) and keeping reasonable finite jerk inputs (weight ``1e-6``). The latter mitigate bang-bang accelerations but prevent fully reaching the goal within the horizon. See the [examples](examples/) folder for more examples.\n\n## Areas of improvement\n\nThis module is incomplete with regards to the following points:\n\n- Cost functions: can be extended to general linear stage cost functions\n- Documentation: there are some undocumented functions\n- Test coverage: only one end-to-end test\n\nCheck out the [contribution guidelines](CONTRIBUTING.md) if you are interested in lending a hand.\n\n## Alternatives\n\nYou can also check out the following open-source libraries:\n\n### Linear model predictive control\n\n| Name                                                       | Systems               | Languages   | License      |\n|------------------------------------------------------------|-----------------------|-------------|--------------|\n| [Copra (LTV fork)](https://github.com/ANYbotics/copra)     | Linear time-variant   | C++, Python | BSD-2-Clause |\n| [Copra (original)](https://github.com/jrl-umi3218/copra)   | Linear time-invariant | C++, Python | BSD-2-Clause |\n| [mpc-interface](https://github.com/Gepetto/mpc-interface)  | Linear time-variant   | C++, Python | BSD-2-Clause |\n| [pyMPC](https://github.com/forgi86/pyMPC)                  | Linear time-variant   | Python      | MIT          |\n\n### Nonlinear model predictive control\n\n| Name                                                       | Systems               | Languages           | License      |\n|------------------------------------------------------------|-----------------------|---------------------|--------------|\n| [acados](https://github.com/acados/acados)                 | Nonlinear             | C++, Matlab, Python | BSD-2-Clause |\n| [Aligator](https://github.com/Simple-Robotics/aligator/)   | Nonlinear             | C++, Python         | BSD-2-Clause |\n| [Crocoddyl](https://github.com/loco-3d/crocoddyl)          | Nonlinear             | C++, Python         | BSD-3-Clause |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephane-caron%2Fqpmpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephane-caron%2Fqpmpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephane-caron%2Fqpmpc/lists"}