# NonLinear Programming with CasADi
**C**a**s**ADi-**NLP** (**csnlp**, for short) is a library that provides classes
and utilities to model, solve and analyse nonlinear (but not only) programmes (NLPs) for
optimization purposes.
> | | |
> |---|---|
> | **Documentation** | <https://casadi-nlp.readthedocs.io/en/stable/> |
> | **Download** | <https://pypi.python.org/pypi/csnlp/> |
> | **Source code** | <https://github.com/FilippoAiraldi/casadi-nlp/> |
> | **Report issues** | <https://github.com/FilippoAiraldi/casadi-nlp/issues/> |
[](https://badge.fury.io/py/csnlp)
[](https://github.com/FilippoAiraldi/casadi-nlp/blob/main/LICENSE)
[](https://github.com/FilippoAiraldi/casadi-nlp/actions/workflows/tests.yml)
[](https://casadi-nlp.readthedocs.io/en/stable/?badge=stable)
[](https://www.pepy.tech/projects/csnlp)
[](https://codeclimate.com/github/FilippoAiraldi/casadi-nlp/maintainability)
[](https://codeclimate.com/github/FilippoAiraldi/casadi-nlp/test_coverage)
[](https://github.com/psf/black)
---
## Features
**csnlp** builds on top of the [CasADi](https://web.casadi.org/)
framework [[1]](#1) to model the optimization problems and perform symbolic
differentiation, and heavily relies on the [IPOPT](https://github.com/coin-or/Ipopt)
solver [[2]](#2) (though the package allows the user to seamlessly switch to other
solvers supported by CasADi). While it is similar in functionality (and was inspired by)
the CasADi's
[Opti Stack](https://web.casadi.org/api/html/dd/dc6/classcasadi_1_1Opti.html) (see
[this blog post](https://web.casadi.org/blog/opti/) for example), it is more tailored to
research as
1. it is more flexible, since it is written in Python and allows the user to easily
access all the constituents of the optimization problem (e.g. the objective function,
constraints, dual variables, bounds, etc.)
2. it is more modular, since it allows the base `csnlp.Nlp` class to be wrapped with
additional functionality (e.g. sensitivity, Model Predictive Control, etc.), and it
provides parallel implementations in case of multistarting in the `csnlp.multistart`
module.
The package offers also tools for the sensitivity analysis of NLPs, solving them with
multiple initial conditions, as well as for building MPC controllers. The library is not
meant to be a faster alternative to `casadi.Opti`, but rather a more flexible and
modular one for research purposes.
---
## Installation
### Using `pip`
You can use `pip` to install **csnlp** with the command
```bash
pip install csnlp
```
**csnlp** has the following dependencies
- Python 3.9 or higher
- [NumPy](https://pypi.org/project/numpy/)
- [CasADi](https://pypi.org/project/casadi/)
- [Joblib](https://joblib.readthedocs.io/)
### Using source code
If you'd like to play around with the source code instead, run
```bash
git clone https://github.com/FilippoAiraldi/casadi-nlp.git
```
The `main` branch contains the main releases of the packages (and the occasional post
release). The `experimental` branch is reserved for the implementation and test of new
features and hosts the release candidates. You can then install the package to edit it
as you wish as
```bash
pip install -e /path/to/casadi-nlp
```
---
## Getting started
Here we provide a compact example on how **csnlp** can be employed to build and solve
an optimization problem. Similar to
[Opti](https://web.casadi.org/api/html/dd/dc6/classcasadi_1_1Opti.html), we instantiate
a class which represents the NLP and allows us to create its variables and parameters
and model its constraints and objective. For example, suppose we'd like to solve the
problem
$$
\min_{x,y}{ (1 - x)^2 + 0.2(y - x^2)^2 \text{ s.t. } (p/2)^2 \le (x + 0.5)^2 + y^2 \le p^2 }
$$
We can do so with the following code:
```python
from csnlp import Nlp
nlp = Nlp()
x = nlp.variable("x")[0] # create primal variable x
y = nlp.variable("y")[0] # create primal variable y
p = nlp.parameter("p") # create parameter p
# define the objective and constraints
nlp.minimize((1 - x) ** 2 + 0.2 * (y - x**2) ** 2)
g = (x + 0.5) ** 2 + y**2
nlp.constraint("c1", (p / 2) ** 2, "<=", g)
nlp.constraint("c2", g, "<=", p**2)
nlp.init_solver() # initializes IPOPT under the hood
sol = nlp.solve(pars={"p": 1.25}) # solves the NLP for parameter p=1.25
x_opt = sol.vals["x"] # optimal values can be retrieved via the dict .vals
y_opt = sol.value(y) # or the .value method
```
However, the package also allows to seamlessly enhance the standard `csnlp.Nlp` with
different capabilities. For instance, when the problem is highly nonlinear and
necessitates to be solved with multiple initial conditions, the `csnlp.multistart`
module offers various solutions to parallelize the computations (see, e.g.,
`csnlp.multistart.ParallelMultistartNlp`). The `csnlp.wrappers` module offers instead a
set of wrappers that can be used to augment the NLP with additional capabilities without
modifying the original NLP instance: as of now, wrappers have been implemented for
The package also allows to enhance the NLP with different capabilities with, e.g.,
multistart (see `csnlp.MultistartNlp`) or by wrapping it. As of now, wrappers have been
implemented for
- sensitivity analysis (see `csnlp.wrappers.NlpSensitivity` [[3]](#3))
- Model Predictive Control (see `csnlp.wrappers.Mpc` [[4]](#4) and
`csnlp.wrappers.ScenarioBasedMpc` [[5]](#5))
- NLP scaling (see `csnlp.wrappers.NlpScaling` and `csnlp.core.scaling`).
For example, if we'd like to compute the sensitivity $\frac{\partial y}{\partial p}$ of
the optimal primal variable $y$ with respect to the parameter $p$, we just need to wrap
the `csnlp.Nlp` instance with the `csnlp.wrappers.NlpSensitivity` wrapper, which is
specialized in differentiating the optimization problem. This in turn allows us to
compute the first-order $\frac{\partial y}{\partial p}$ and second sensitivities
$\frac{\partial^2 y}{\partial p^2}$ (`dydp` and `d2ydp2`, respectively) as such:
```python
from csnlp import wrappers
nlp = wrappers.NlpSensitivity(nlp)
dydp, d2ydp2 = nlp.parametric_sensitivity()
```
In other words, these sensitivities provide the jacobian and hessian
that locally approximate the solution w.r.t. the parameter $p$. As
shown in the corresponding example but not in this quick demonstation, the sensitivity
can be also computed for any generic expression $z(x(p),\lambda(p),p)$ that is a
function of the primal $x$ and dual $\lambda$ variables, and the parameters
$p$. Moreover, the sensitivity computations can be carried out symbolically (more
demanding) or numerically (more stable and reliable).
Similarly, a `csnlp.Nlp` instance can be wrapped in a `csnlp.wrappers.Mpc` wrapper
that makes it easier to build such finite-horizon optimal controllers for model-based
control applications.
---
## Examples
Our [examples](https://github.com/FilippoAiraldi/casadi-nlp/tree/main/examples)
subdirectory contains example applications of this package in NLP optimization,
sensitivity analysis, scaling of NLPs, and optimal control.
---
## License
The repository is provided under the MIT License. See the LICENSE file included with
this repository.
---
## Author
[Filippo Airaldi](https://www.tudelft.nl/staff/f.airaldi/), PhD Candidate
[f.airaldi@tudelft.nl | filippoairaldi@gmail.com]
> [Delft Center for Systems and Control](https://www.tudelft.nl/en/me/about/departments/delft-center-for-systems-and-control/)
in [Delft University of Technology](https://www.tudelft.nl/en/)
Copyright (c) 2024 Filippo Airaldi.
Copyright notice: Technische Universiteit Delft hereby disclaims all copyright interest
in the program “csnlp” (Nonlinear Progamming with CasADi) written by the Author(s).
Prof. Dr. Ir. Fred van Keulen, Dean of ME.
---
## References
<a id="1">[1]</a>
Andersson, J.A.E., Gillis, J., Horn, G., Rawlings, J.B., and Diehl, M. (2019).
[CasADi: a software framework for nonlinear optimization and optimal control](https://link.springer.com/article/10.1007/s12532-018-0139-4).
Mathematical Programming Computation, 11(1), 1–36.
<a id="2">[2]</a>
Wachter, A. and Biegler, L.T. (2006).
[On the implementation of an interior-point filter line-search algorithm for large-scale nonlinear programming](https://link.springer.com/article/10.1007/s10107-004-0559-y).
Mathematical Programming, 106(1), 25–57.
<a id="3">[3]</a>
Büskens, C. and Maurer, H. (2001).
[Sensitivity analysis and real-time optimization of parametric nonlinear programming problems](https://link.springer.com/chapter/10.1007/978-3-662-04331-8_1).
In M. Grötschel, S.O. Krumke, and J. Rambau (eds.), Online Optimization of Large Scale Systems, 3–16. Springer, Berlin, Heidelberg
<a id="4">[4]</a>
Rawlings, J.B., Mayne, D.Q. and Diehl, M., 2017.
[Model Predictive Control: theory, computation, and design (Vol. 2)](https://sites.engineering.ucsb.edu/~jbraw/mpc/).
Madison, WI: Nob Hill Publishing.
<a id="5">[5]</a>
Schildbach, G., Fagiano, L., Frei, C. and Morari, M., 2014.
[The Scenario Approach for stochastic Model Predictive Control with bounds on closed-loop constraint violations](https://www.sciencedirect.com/science/article/pii/S0005109814004166).
Automatica, 50(12), pp.3009-3018.
Raw data
{
"_id": null,
"home_page": null,
"name": "csnlp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "nonlinear-optimization, casadi, sensitivity-analysis",
"author": null,
"author_email": "Filippo Airaldi <filippoairaldi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/18/90/14716578db816e7a127b4b285780c6b429bb3eb7f602ff1053b7b5043ec6/csnlp-1.6.4.tar.gz",
"platform": null,
"description": "# NonLinear Programming with CasADi\r\n\r\n**C**a**s**ADi-**NLP** (**csnlp**, for short) is a library that provides classes\r\nand utilities to model, solve and analyse nonlinear (but not only) programmes (NLPs) for\r\noptimization purposes.\r\n\r\n> | | |\r\n> |---|---|\r\n> | **Documentation** | <https://casadi-nlp.readthedocs.io/en/stable/> |\r\n> | **Download** | <https://pypi.python.org/pypi/csnlp/> |\r\n> | **Source code** | <https://github.com/FilippoAiraldi/casadi-nlp/> |\r\n> | **Report issues** | <https://github.com/FilippoAiraldi/casadi-nlp/issues/> |\r\n\r\n[](https://badge.fury.io/py/csnlp)\r\n[](https://github.com/FilippoAiraldi/casadi-nlp/blob/main/LICENSE)\r\n\r\n\r\n[](https://github.com/FilippoAiraldi/casadi-nlp/actions/workflows/tests.yml)\r\n[](https://casadi-nlp.readthedocs.io/en/stable/?badge=stable)\r\n[](https://www.pepy.tech/projects/csnlp)\r\n[](https://codeclimate.com/github/FilippoAiraldi/casadi-nlp/maintainability)\r\n[](https://codeclimate.com/github/FilippoAiraldi/casadi-nlp/test_coverage)\r\n[](https://github.com/psf/black)\r\n\r\n---\r\n\r\n## Features\r\n\r\n**csnlp** builds on top of the [CasADi](https://web.casadi.org/)\r\nframework [[1]](#1) to model the optimization problems and perform symbolic\r\ndifferentiation, and heavily relies on the [IPOPT](https://github.com/coin-or/Ipopt)\r\nsolver [[2]](#2) (though the package allows the user to seamlessly switch to other\r\nsolvers supported by CasADi). While it is similar in functionality (and was inspired by)\r\nthe CasADi's\r\n[Opti Stack](https://web.casadi.org/api/html/dd/dc6/classcasadi_1_1Opti.html) (see\r\n[this blog post](https://web.casadi.org/blog/opti/) for example), it is more tailored to\r\nresearch as\r\n\r\n1. it is more flexible, since it is written in Python and allows the user to easily\r\n access all the constituents of the optimization problem (e.g. the objective function,\r\n constraints, dual variables, bounds, etc.)\r\n\r\n2. it is more modular, since it allows the base `csnlp.Nlp` class to be wrapped with\r\n additional functionality (e.g. sensitivity, Model Predictive Control, etc.), and it\r\n provides parallel implementations in case of multistarting in the `csnlp.multistart`\r\n module.\r\n\r\nThe package offers also tools for the sensitivity analysis of NLPs, solving them with\r\nmultiple initial conditions, as well as for building MPC controllers. The library is not\r\nmeant to be a faster alternative to `casadi.Opti`, but rather a more flexible and\r\nmodular one for research purposes.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n### Using `pip`\r\n\r\nYou can use `pip` to install **csnlp** with the command\r\n\r\n```bash\r\npip install csnlp\r\n```\r\n\r\n**csnlp** has the following dependencies\r\n\r\n- Python 3.9 or higher\r\n- [NumPy](https://pypi.org/project/numpy/)\r\n- [CasADi](https://pypi.org/project/casadi/)\r\n- [Joblib](https://joblib.readthedocs.io/)\r\n\r\n### Using source code\r\n\r\nIf you'd like to play around with the source code instead, run\r\n\r\n```bash\r\ngit clone https://github.com/FilippoAiraldi/casadi-nlp.git\r\n```\r\n\r\nThe `main` branch contains the main releases of the packages (and the occasional post\r\nrelease). The `experimental` branch is reserved for the implementation and test of new\r\nfeatures and hosts the release candidates. You can then install the package to edit it\r\nas you wish as\r\n\r\n```bash\r\npip install -e /path/to/casadi-nlp\r\n```\r\n\r\n---\r\n\r\n## Getting started\r\n\r\nHere we provide a compact example on how **csnlp** can be employed to build and solve\r\nan optimization problem. Similar to\r\n[Opti](https://web.casadi.org/api/html/dd/dc6/classcasadi_1_1Opti.html), we instantiate\r\na class which represents the NLP and allows us to create its variables and parameters\r\nand model its constraints and objective. For example, suppose we'd like to solve the\r\nproblem\r\n\r\n$$\r\n\\min_{x,y}{ (1 - x)^2 + 0.2(y - x^2)^2 \\text{ s.t. } (p/2)^2 \\le (x + 0.5)^2 + y^2 \\le p^2 }\r\n$$\r\n\r\nWe can do so with the following code:\r\n\r\n```python\r\nfrom csnlp import Nlp\r\n\r\nnlp = Nlp()\r\nx = nlp.variable(\"x\")[0] # create primal variable x\r\ny = nlp.variable(\"y\")[0] # create primal variable y\r\np = nlp.parameter(\"p\") # create parameter p\r\n\r\n# define the objective and constraints\r\nnlp.minimize((1 - x) ** 2 + 0.2 * (y - x**2) ** 2)\r\ng = (x + 0.5) ** 2 + y**2\r\nnlp.constraint(\"c1\", (p / 2) ** 2, \"<=\", g)\r\nnlp.constraint(\"c2\", g, \"<=\", p**2)\r\n\r\nnlp.init_solver() # initializes IPOPT under the hood\r\nsol = nlp.solve(pars={\"p\": 1.25}) # solves the NLP for parameter p=1.25\r\n\r\nx_opt = sol.vals[\"x\"] # optimal values can be retrieved via the dict .vals\r\ny_opt = sol.value(y) # or the .value method\r\n```\r\n\r\nHowever, the package also allows to seamlessly enhance the standard `csnlp.Nlp` with\r\ndifferent capabilities. For instance, when the problem is highly nonlinear and\r\nnecessitates to be solved with multiple initial conditions, the `csnlp.multistart`\r\nmodule offers various solutions to parallelize the computations (see, e.g.,\r\n`csnlp.multistart.ParallelMultistartNlp`). The `csnlp.wrappers` module offers instead a\r\nset of wrappers that can be used to augment the NLP with additional capabilities without\r\nmodifying the original NLP instance: as of now, wrappers have been implemented for\r\n\r\nThe package also allows to enhance the NLP with different capabilities with, e.g.,\r\nmultistart (see `csnlp.MultistartNlp`) or by wrapping it. As of now, wrappers have been\r\nimplemented for\r\n\r\n- sensitivity analysis (see `csnlp.wrappers.NlpSensitivity` [[3]](#3))\r\n- Model Predictive Control (see `csnlp.wrappers.Mpc` [[4]](#4) and\r\n `csnlp.wrappers.ScenarioBasedMpc` [[5]](#5))\r\n- NLP scaling (see `csnlp.wrappers.NlpScaling` and `csnlp.core.scaling`).\r\n\r\nFor example, if we'd like to compute the sensitivity $\\frac{\\partial y}{\\partial p}$ of\r\nthe optimal primal variable $y$ with respect to the parameter $p$, we just need to wrap\r\nthe `csnlp.Nlp` instance with the `csnlp.wrappers.NlpSensitivity` wrapper, which is\r\nspecialized in differentiating the optimization problem. This in turn allows us to\r\ncompute the first-order $\\frac{\\partial y}{\\partial p}$ and second sensitivities\r\n$\\frac{\\partial^2 y}{\\partial p^2}$ (`dydp` and `d2ydp2`, respectively) as such:\r\n\r\n```python\r\nfrom csnlp import wrappers\r\n\r\nnlp = wrappers.NlpSensitivity(nlp)\r\ndydp, d2ydp2 = nlp.parametric_sensitivity()\r\n```\r\n\r\nIn other words, these sensitivities provide the jacobian and hessian\r\nthat locally approximate the solution w.r.t. the parameter $p$. As\r\nshown in the corresponding example but not in this quick demonstation, the sensitivity\r\ncan be also computed for any generic expression $z(x(p),\\lambda(p),p)$ that is a\r\nfunction of the primal $x$ and dual $\\lambda$ variables, and the parameters\r\n$p$. Moreover, the sensitivity computations can be carried out symbolically (more\r\ndemanding) or numerically (more stable and reliable).\r\n\r\nSimilarly, a `csnlp.Nlp` instance can be wrapped in a `csnlp.wrappers.Mpc` wrapper\r\nthat makes it easier to build such finite-horizon optimal controllers for model-based\r\ncontrol applications.\r\n\r\n---\r\n\r\n## Examples\r\n\r\nOur [examples](https://github.com/FilippoAiraldi/casadi-nlp/tree/main/examples)\r\nsubdirectory contains example applications of this package in NLP optimization,\r\nsensitivity analysis, scaling of NLPs, and optimal control.\r\n\r\n---\r\n\r\n## License\r\n\r\nThe repository is provided under the MIT License. See the LICENSE file included with\r\nthis repository.\r\n\r\n---\r\n\r\n## Author\r\n\r\n[Filippo Airaldi](https://www.tudelft.nl/staff/f.airaldi/), PhD Candidate\r\n[f.airaldi@tudelft.nl | filippoairaldi@gmail.com]\r\n\r\n> [Delft Center for Systems and Control](https://www.tudelft.nl/en/me/about/departments/delft-center-for-systems-and-control/)\r\nin [Delft University of Technology](https://www.tudelft.nl/en/)\r\n\r\nCopyright (c) 2024 Filippo Airaldi.\r\n\r\nCopyright notice: Technische Universiteit Delft hereby disclaims all copyright interest\r\nin the program \u201ccsnlp\u201d (Nonlinear Progamming with CasADi) written by the Author(s).\r\nProf. Dr. Ir. Fred van Keulen, Dean of ME.\r\n\r\n---\r\n\r\n## References\r\n\r\n<a id=\"1\">[1]</a>\r\nAndersson, J.A.E., Gillis, J., Horn, G., Rawlings, J.B., and Diehl, M. (2019).\r\n[CasADi: a software framework for nonlinear optimization and optimal control](https://link.springer.com/article/10.1007/s12532-018-0139-4).\r\nMathematical Programming Computation, 11(1), 1\u201336.\r\n\r\n<a id=\"2\">[2]</a>\r\nWachter, A. and Biegler, L.T. (2006).\r\n[On the implementation of an interior-point filter line-search algorithm for large-scale nonlinear programming](https://link.springer.com/article/10.1007/s10107-004-0559-y).\r\nMathematical Programming, 106(1), 25\u201357.\r\n\r\n<a id=\"3\">[3]</a>\r\nB\u00fcskens, C. and Maurer, H. (2001).\r\n[Sensitivity analysis and real-time optimization of parametric nonlinear programming problems](https://link.springer.com/chapter/10.1007/978-3-662-04331-8_1).\r\nIn M. Gr\u00f6tschel, S.O. Krumke, and J. Rambau (eds.), Online Optimization of Large Scale Systems, 3\u201316. Springer, Berlin, Heidelberg\r\n\r\n<a id=\"4\">[4]</a>\r\nRawlings, J.B., Mayne, D.Q. and Diehl, M., 2017.\r\n[Model Predictive Control: theory, computation, and design (Vol. 2)](https://sites.engineering.ucsb.edu/~jbraw/mpc/).\r\nMadison, WI: Nob Hill Publishing.\r\n\r\n<a id=\"5\">[5]</a>\r\nSchildbach, G., Fagiano, L., Frei, C. and Morari, M., 2014.\r\n[The Scenario Approach for stochastic Model Predictive Control with bounds on closed-loop constraint violations](https://www.sciencedirect.com/science/article/pii/S0005109814004166).\r\nAutomatica, 50(12), pp.3009-3018.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Nonlinear Progamming with CasADi",
"version": "1.6.4",
"project_urls": {
"Bug Tracker": "https://github.com/FilippoAiraldi/casadi-nlp/issues",
"Homepage": "https://github.com/FilippoAiraldi/casadi-nlp"
},
"split_keywords": [
"nonlinear-optimization",
" casadi",
" sensitivity-analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f3056741ba95b21eab783c687da575381d84170dce042dcd13b3dda9b4c34264",
"md5": "d8efab954e9f3ad9d9465ab8705be494",
"sha256": "c1a4a91ce21585c2e2169b28086ba276a26917ab7489ac35b2fbd15d127dd2c6"
},
"downloads": -1,
"filename": "csnlp-1.6.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8efab954e9f3ad9d9465ab8705be494",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 82918,
"upload_time": "2025-01-15T12:41:26",
"upload_time_iso_8601": "2025-01-15T12:41:26.665880Z",
"url": "https://files.pythonhosted.org/packages/f3/05/6741ba95b21eab783c687da575381d84170dce042dcd13b3dda9b4c34264/csnlp-1.6.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "189014716578db816e7a127b4b285780c6b429bb3eb7f602ff1053b7b5043ec6",
"md5": "78347b89e4f023f0c539ba2ab34c5f05",
"sha256": "95493bacdca28bf41c68420fa566da902e5e8a13bbdd389b0678183e76d9ecd7"
},
"downloads": -1,
"filename": "csnlp-1.6.4.tar.gz",
"has_sig": false,
"md5_digest": "78347b89e4f023f0c539ba2ab34c5f05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 102105,
"upload_time": "2025-01-15T12:41:29",
"upload_time_iso_8601": "2025-01-15T12:41:29.147785Z",
"url": "https://files.pythonhosted.org/packages/18/90/14716578db816e7a127b4b285780c6b429bb3eb7f602ff1053b7b5043ec6/csnlp-1.6.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 12:41:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FilippoAiraldi",
"github_project": "casadi-nlp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.6"
],
[
"<",
"2.0.0"
]
]
},
{
"name": "casadi",
"specs": [
[
">=",
"3.6.0"
]
]
},
{
"name": "joblib",
"specs": [
[
">=",
"1.4.0"
]
]
}
],
"lcname": "csnlp"
}
JSON
