|
1 | | -# DNLP — Disciplined Nonlinear Programming |
2 | | -The DNLP package is an extension of [CVXPY](https://www.cvxpy.org/) to general nonlinear programming (NLP). |
3 | | -DNLP allows smooth functions to be freely mixed with nonsmooth convex and concave functions, |
4 | | -with some rules governing how the nonsmooth functions can be used. For details, see our paper [Disciplined Nonlinear Programming](https://web.stanford.edu/~boyd/papers/dnlp.html). |
| 1 | +CVXPY |
| 2 | +===================== |
| 3 | +[](https://github.com/cvxpy/cvxpy/actions/workflows/build.yml) |
| 4 | + |
| 5 | + |
| 6 | +[](https://discord.gg/4urRQeGBCr) |
| 7 | +[](https://cvxpy.github.io/benchmarks/) |
| 8 | +[](https://api.securityscorecards.dev/projects/github.com/cvxpy/cvxpy) |
5 | 9 |
|
6 | | ---- |
7 | | -## Installation |
8 | | -The installation consists of two steps. |
| 10 | +**The CVXPY documentation is at [cvxpy.org](https://www.cvxpy.org/).** |
9 | 11 |
|
10 | | -#### Step 1: Install IPOPT |
11 | | -DNLP requires an NLP solver. The recommended solver is [Ipopt](https://coin-or.github.io/Ipopt/). First install the IPOPT system library, then install the Python interface [cyipopt](https://github.com/mechmotum/cyipopt): |
12 | | -```bash |
13 | | -# Ubuntu/Debian |
14 | | -sudo apt-get install coinor-libipopt-dev |
| 12 | +*We are building a CVXPY community on [Discord](https://discord.gg/4urRQeGBCr). Join the conversation! For issues and long-form discussions, use [Github Issues](https://github.com/cvxpy/cvxpy/issues) and [Github Discussions](https://github.com/cvxpy/cvxpy/discussions).* |
15 | 13 |
|
16 | | -# macOS |
17 | | -brew install ipopt |
18 | | -``` |
19 | | -Then install the Python interface: |
20 | | -```bash |
21 | | -pip install cyipopt |
22 | | -``` |
| 14 | +**Contents** |
| 15 | +- [Installation](#installation) |
| 16 | +- [Getting started](#getting-started) |
| 17 | +- [Issues](#issues) |
| 18 | +- [Community](#community) |
| 19 | +- [Contributing](#contributing) |
| 20 | +- [Team](#team) |
| 21 | +- [Citing](#citing) |
23 | 22 |
|
24 | | -#### Step 2: Install DNLP |
25 | | -DNLP is installed by cloning this repository and installing it locally: |
26 | | -```bash |
27 | | -git clone https://github.com/cvxgrp/DNLP.git |
28 | | -cd DNLP |
29 | | -pip install . |
30 | | -``` |
31 | 23 |
|
32 | | ---- |
33 | | -## Example |
34 | | -Below we give a toy example where we maximize a convex quadratic function subject to a nonlinear equality constraint. Many more examples, including the ones in the paper, can be found at [DNLP-examples](https://github.com/cvxgrp/dnlp-examples). |
35 | | -```python |
36 | | -import cvxpy as cp |
37 | | -import numpy as np |
| 24 | +CVXPY is a Python-embedded modeling language for convex optimization problems. It allows you to express your problem in a natural way that follows the math, rather than in the restrictive standard form required by solvers. |
| 25 | + |
| 26 | +For example, the following code solves a least-squares problem where the variable is constrained by lower and upper bounds: |
| 27 | + |
| 28 | +```python3 |
38 | 29 | import cvxpy as cp |
| 30 | +import numpy |
39 | 31 |
|
40 | | -# problem data |
41 | | -np.random.seed(0) |
42 | | -n = 3 |
43 | | -A = np.random.randn(n, n) |
44 | | -A = A.T @ A |
| 32 | +# Problem data. |
| 33 | +m = 30 |
| 34 | +n = 20 |
| 35 | +numpy.random.seed(1) |
| 36 | +A = numpy.random.randn(m, n) |
| 37 | +b = numpy.random.randn(m) |
45 | 38 |
|
46 | | -# formulate optimization problem |
| 39 | +# Construct the problem. |
47 | 40 | x = cp.Variable(n) |
48 | | -obj = cp.Maximize(cp.quad_form(x, A)) |
49 | | -constraints = [cp.sum_squares(x) == 1] |
50 | | - |
51 | | -# initialize and solve |
52 | | -x.value = np.ones(n) |
53 | | -prob = cp.Problem(obj, constraints) |
54 | | -prob.solve(nlp=True, verbose=True) |
55 | | -print("Optimal value from DNLP: ", prob.value) |
56 | | - |
57 | | -# the optimal value for this toy problem can also be found by computing the maximum eigenvalue of A |
58 | | -eigenvalues = np.linalg.eigvalsh(A) |
59 | | -print("Maximum eigenvalue: " , np.max(eigenvalues)) |
| 41 | +objective = cp.Minimize(cp.sum_squares(A @ x - b)) |
| 42 | +constraints = [0 <= x, x <= 1] |
| 43 | +prob = cp.Problem(objective, constraints) |
| 44 | + |
| 45 | +# The optimal objective is returned by prob.solve(). |
| 46 | +result = prob.solve() |
| 47 | +# The optimal value for x is stored in x.value. |
| 48 | +print(x.value) |
| 49 | +# The optimal Lagrange multiplier for a constraint |
| 50 | +# is stored in constraint.dual_value. |
| 51 | +print(constraints[0].dual_value) |
| 52 | +``` |
| 53 | + |
| 54 | +With CVXPY, you can model |
| 55 | +* convex optimization problems, |
| 56 | +* mixed-integer convex optimization problems, |
| 57 | +* geometric programs, and |
| 58 | +* quasiconvex programs. |
| 59 | + |
| 60 | +CVXPY is not a solver. It relies upon the open source solvers |
| 61 | +[Clarabel](https://github.com/oxfordcontrol/Clarabel.rs), [SCS](https://github.com/bodono/scs-python), |
| 62 | +[OSQP](https://github.com/oxfordcontrol/osqp) and [HiGHS](https://github.com/ERGO-Code/HiGHS). |
| 63 | +Additional solvers are [available](https://www.cvxpy.org/tutorial/solvers/index.html#choosing-a-solver), |
| 64 | +but must be installed separately. |
| 65 | + |
| 66 | +CVXPY began as a Stanford University research project. It is now developed by |
| 67 | +many people, across many institutions and countries. |
| 68 | + |
| 69 | + |
| 70 | +## Installation |
| 71 | +CVXPY is available on PyPI, and can be installed with |
| 72 | +``` |
| 73 | +pip install cvxpy |
| 74 | +``` |
| 75 | + |
| 76 | +CVXPY can also be installed with conda, using |
| 77 | +``` |
| 78 | +conda install -c conda-forge cvxpy |
60 | 79 | ``` |
61 | 80 |
|
62 | | ---- |
63 | | -## Supported Solvers |
64 | | -| Solver | License | Installation | |
65 | | -|--------|---------|--------------| |
66 | | -| [IPOPT](https://github.com/coin-or/Ipopt) | EPL-2.0 | Install system IPOPT (see above), then `pip install cyipopt` | |
67 | | -| [Knitro](https://www.artelys.com/solvers/knitro/) | Commercial | `pip install knitro` (requires license) | |
| 81 | +CVXPY has the following dependencies: |
| 82 | + |
| 83 | +- Python >= 3.11 |
| 84 | +- Clarabel >= 0.5.0 |
| 85 | +- OSQP >= 1.0.0 |
| 86 | +- SCS >= 3.2.4.post1 |
| 87 | +- NumPy >= 2.0.0 |
| 88 | +- SciPy >= 1.13.0 |
| 89 | +- highspy >= 1.11.0 |
| 90 | + |
| 91 | +For detailed instructions, see the [installation |
| 92 | +guide](https://www.cvxpy.org/install/index.html). |
| 93 | + |
| 94 | +## Getting started |
| 95 | +To get started with CVXPY, check out the following: |
| 96 | +* [official CVXPY tutorial](https://www.cvxpy.org/tutorial/index.html) |
| 97 | +* [example library](https://www.cvxpy.org/examples/index.html) |
| 98 | +* [API reference](https://www.cvxpy.org/api_reference/cvxpy.html) |
| 99 | + |
| 100 | +## Issues |
| 101 | +We encourage you to report issues using the [Github tracker](https://github.com/cvxpy/cvxpy/issues). We welcome all kinds of issues, especially those related to correctness, documentation, performance, and feature requests. |
| 102 | + |
| 103 | +For basic usage questions (e.g., "Why isn't my problem DCP?"), please use [StackOverflow](https://stackoverflow.com/questions/tagged/cvxpy) instead. |
| 104 | + |
| 105 | +## Community |
| 106 | +The CVXPY community consists of researchers, data scientists, software engineers, and students from all over the world. We welcome you to join us! |
| 107 | + |
| 108 | +* To chat with the CVXPY community in real-time, join us on [Discord](https://discord.gg/4urRQeGBCr). |
| 109 | +* To have longer, in-depth discussions with the CVXPY community, use [Github Discussions](https://github.com/cvxpy/cvxpy/discussions). |
| 110 | +* To share feature requests and bug reports, use [Github Issues](https://github.com/cvxpy/cvxpy/issues). |
| 111 | + |
| 112 | +Please be respectful in your communications with the CVXPY community, and make sure to abide by our [code of conduct](https://github.com/cvxpy/cvxpy/blob/master/CODE_OF_CONDUCT.md). |
| 113 | + |
| 114 | +## Contributing |
| 115 | +We appreciate all contributions. You don't need to be an expert in convex |
| 116 | +optimization to help out. |
| 117 | + |
| 118 | +You should first |
| 119 | +install [CVXPY from source](https://www.cvxpy.org/install/index.html#install-from-source). |
| 120 | +Here are some simple ways to start contributing immediately: |
| 121 | +* Read the CVXPY source code and improve the documentation, or address TODOs |
| 122 | +* Enhance the [website documentation](https://github.com/cvxpy/cvxpy/tree/master/doc) |
| 123 | +* Browse the [issue tracker](https://github.com/cvxpy/cvxpy/issues), and look for issues tagged as "help wanted" |
| 124 | +* Polish the [example library](https://github.com/cvxpy/examples) |
| 125 | +* Add a [benchmark](https://github.com/cvxpy/benchmarks) |
| 126 | + |
| 127 | +If you'd like to add a new example to our library, or implement a new feature, |
| 128 | +please get in touch with us first to make sure that your priorities align with |
| 129 | +ours. |
| 130 | + |
| 131 | +Contributions should be submitted as [pull requests](https://github.com/cvxpy/cvxpy/pulls). |
| 132 | +A member of the CVXPY development team will review the pull request and guide |
| 133 | +you through the contributing process. |
| 134 | + |
| 135 | +Before starting work on your contribution, please read the [contributing guide](https://github.com/cvxpy/cvxpy/blob/master/CONTRIBUTING.md). |
| 136 | + |
| 137 | +## Team |
| 138 | +CVXPY is a community project, built from the contributions of many |
| 139 | +researchers and engineers. |
| 140 | + |
| 141 | +CVXPY is developed and maintained by [Steven |
| 142 | +Diamond](https://stevendiamond.me/), [Akshay |
| 143 | +Agrawal](https://akshayagrawal.com), [Riley Murray](https://rileyjmurray.wordpress.com/), |
| 144 | +[Philipp Schiele](https://www.philippschiele.com/), |
| 145 | +[Bartolomeo Stellato](https://stellato.io/), |
| 146 | +and [Parth Nobel](https://ptnobel.github.io), with many others contributing |
| 147 | +significantly. |
| 148 | +A non-exhaustive list of people who have shaped CVXPY over the |
| 149 | +years includes Stephen Boyd, Eric Chu, Robin Verschueren, |
| 150 | +Jaehyun Park, Enzo Busseti, AJ Friend, Judson Wilson, Chris Dembia, and |
| 151 | +William Zhang. |
68 | 152 |
|
69 | | ---- |
70 | | -## Differentiation Engine |
71 | | -DNLP uses [SparseDiffPy](https://github.com/SparseDifferentiation/SparseDiffPy) as its differentiation engine. SparseDiffPy is a Python wrapper around the [SparseDiffEngine](https://github.com/SparseDifferentiation/SparseDiffEngine) C library, and is installed automatically as a dependency of DNLP. |
| 153 | +For more information about the team and our processes, see our [governance document](https://github.com/cvxpy/org/blob/main/governance.md). |
72 | 154 |
|
73 | | -SparseDiffPy builds an expression tree from the CVXPY problem and computes exact sparse gradients, Jacobians, and Hessians required by the NLP solvers. |
| 155 | +## Citing |
| 156 | +If you use CVXPY for academic work, we encourage you to [cite our papers](https://www.cvxpy.org/resources/citing/index.html). If you use CVXPY in industry, we'd love to hear from you as well, on Discord or over email. |
0 commit comments