Skip to content

Commit 66f80bc

Browse files
TransurgeonTransurgeon
committed
restore readme
1 parent bb47d39 commit 66f80bc

1 file changed

Lines changed: 61 additions & 143 deletions

File tree

‎README.md‎

Lines changed: 61 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,156 +1,74 @@
1-
CVXPY
2-
=====================
3-
[![Build Status](https://github.com/cvxpy/cvxpy/actions/workflows/build.yml/badge.svg?event=push)](https://github.com/cvxpy/cvxpy/actions/workflows/build.yml)
4-
![PyPI - downloads](https://img.shields.io/pypi/dm/cvxpy.svg?label=Pypi%20downloads)
5-
![Conda - downloads](https://img.shields.io/conda/dn/conda-forge/cvxpy.svg?label=Conda%20downloads)
6-
[![Discord](https://img.shields.io/badge/Chat-Discord-Blue?color=5865f2)](https://discord.gg/4urRQeGBCr)
7-
[![Benchmarks](http://img.shields.io/badge/benchmarked%20by-asv-blue.svg?style=flat)](https://cvxpy.github.io/benchmarks/)
8-
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/cvxpy/cvxpy/badge)](https://api.securityscorecards.dev/projects/github.com/cvxpy/cvxpy)
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).
95

10-
**The CVXPY documentation is at [cvxpy.org](https://www.cvxpy.org/).**
11-
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).*
13-
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)
22-
23-
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
29-
import cvxpy as cp
30-
import numpy
31-
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)
38-
39-
# Construct the problem.
40-
x = cp.Variable(n)
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.
6+
---
7+
## Installation
8+
The installation consists of two steps.
689

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
6915

70-
## Installation
71-
CVXPY is available on PyPI, and can be installed with
16+
# macOS
17+
brew install ipopt
7218
```
73-
pip install cvxpy
19+
Then install the Python interface:
20+
```bash
21+
pip install cyipopt
7422
```
7523

76-
CVXPY can also be installed with conda, using
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 .
7730
```
78-
conda install -c conda-forge cvxpy
79-
```
80-
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!
10731

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.
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
13438

135-
Before starting work on your contribution, please read the [contributing guide](https://github.com/cvxpy/cvxpy/blob/master/CONTRIBUTING.md).
39+
# problem data
40+
np.random.seed(0)
41+
n = 3
42+
A = np.random.randn(n, n)
43+
A = A.T @ A
13644

137-
## Team
138-
CVXPY is a community project, built from the contributions of many
139-
researchers and engineers.
45+
# formulate optimization problem
46+
x = cp.Variable(n)
47+
obj = cp.Maximize(cp.quad_form(x, A))
48+
constraints = [cp.sum_squares(x) == 1]
49+
50+
# initialize and solve
51+
x.value = np.ones(n)
52+
prob = cp.Problem(obj, constraints)
53+
prob.solve(nlp=True, verbose=True)
54+
print("Optimal value from DNLP: ", prob.value)
55+
56+
# the optimal value for this toy problem can also be found by computing the maximum eigenvalue of A
57+
eigenvalues = np.linalg.eigvalsh(A)
58+
print("Maximum eigenvalue: " , np.max(eigenvalues))
59+
```
14060

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.
61+
---
62+
## Supported Solvers
63+
| Solver | License | Installation |
64+
|--------|---------|--------------|
65+
| [IPOPT](https://github.com/coin-or/Ipopt) | EPL-2.0 | Install system IPOPT (see above), then `pip install cyipopt` |
66+
| [Knitro](https://www.artelys.com/solvers/knitro/) | Commercial | `pip install knitro` (requires license) |
67+
| [UNO](https://github.com/cvanaret/Uno) | MIT | See [Uno](https://github.com/cvanaret/Uno) |
68+
| [COPT](https://www.copt.de/) | Commercial | Requires license |
15269

153-
For more information about the team and our processes, see our [governance document](https://github.com/cvxpy/org/blob/main/governance.md).
70+
---
71+
## Differentiation Engine
72+
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.
15473

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.
74+
SparseDiffPy builds an expression tree from the CVXPY problem and computes exact sparse gradients, Jacobians, and Hessians required by the NLP solvers.

0 commit comments

Comments
 (0)