Skip to content

Commit 5bfe079

Browse files
haozhu10015haozhu10015
committed
update README.md
1 parent 9aed63f commit 5bfe079

File tree

1 file changed

+139
-7
lines changed

1 file changed

+139
-7
lines changed

‎README.md‎

Lines changed: 139 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,21 @@ The functions $f_0, \ldots, f_m$ are biconvex, meaning that for fixed $y$,
1616
the functions $f_i(\cdot, y)$ are convex,
1717
and for fixed $x$, the functions $f_i(x, \cdot)$ are convex.
1818
The functions $h_1, \ldots, h_p$ are biaffine in a similar sense.
19-
A more detailed discussion about biconvex optimization problems
20-
can be found in our accompanying paper.
19+
In the most general case, biconvex optimization problems are very hard
20+
to solve, but heuristic methods such as *alternating convex search* (ACS)
21+
can often find good solutions in practice.
22+
23+
More theoretical and technical aspects about
24+
biconvex optimization problems can be found in our [accompanying paper](https://haozhu10015.github.io/papers/dbcp.html).
2125

2226
## Installation
2327

28+
DBCP has the following dependencies:
29+
30+
- Python >= 3.12
31+
- [NumPy](https://numpy.org/doc/stable/index.html) >= 2.3.3
32+
- [CVXPY](https://www.cvxpy.org/) >= 1.7.3
33+
2434
### Using pip
2535

2636
You can install the package using pip:
@@ -55,19 +65,130 @@ This will:
5565

5666
## Usage
5767

68+
Here we provide a basic overview of how to use DBCP;
69+
for more details, please refer to our paper
70+
and the [examples](./examples).
71+
5872
### DBCP syntax rule for multiplications
5973

74+
DBCP is based on CVXPY and inherits its syntax rules,
75+
with the following extension for variable multiplications:
76+
77+
1. A valid DBCP convex product expression between
78+
variables should be one of the form:
79+
80+
- *affine* \* *affine*
81+
- *affine-nonneg* \* *convex*
82+
- *affine-nonpos* \* *concave*
83+
- *convex-nonneg* \* *convex-nonneg*
84+
- *concave-nonpos* \* *concave-nonpos*
85+
86+
2. There exists no loop in the variable interaction graph of
87+
the overall expression, where the edge between two variables
88+
indicates that they appear in different sides in a
89+
product expression as described in the above rule.
90+
6091
### Specifying biconvex problems
6192

62-
### Solving a biconvex problem
93+
DBCP provides the `BiconvexProblem` and `BiconvexRelaxProblem`
94+
classes to specify biconvex problems.
95+
Roughly speaking, the difference between these two classes is that
96+
`BiconvexProblem` implements a solver for directly solving
97+
the original biconvex problem, while
98+
`BiconvexRelaxProblem` is used for solving a relaxed version
99+
of the problem with additional slack variables added to the constraints,
100+
so the latter allows solving with infeasible starting points.
63101

64-
### Solving with infeasible starting points
102+
As an example, to create a `BiconvexProblem` instance,
103+
one can use the following syntax:
104+
105+
```python
106+
prob = BiconvexProblem(obj, [x_var, y_var], constraints)
107+
```
108+
109+
The argument `obj` is a DBCP-compliant biconvex expression
110+
representing the objective function, `x_var` and `y_var`
111+
are lists of the biconvex optimization variables,
112+
and `constraints` is a list of DBCP-compliant biconvex constraints.
113+
The arguments `x_var` and `y_var` define the variable partition
114+
for the biconvex problem, such that each group will be fixed
115+
when optimizing over the other group during the ACS procedure.
65116

66117
### Verification of biconvexity
67118

119+
After creating a `BiconvexProblem` or `BiconvexRelaxProblem` instance,
120+
one can call its `is_dbcp` method to verify whether the problem
121+
is DBCP-compliant:
122+
123+
```python
124+
prob.is_dbcp()
125+
```
126+
127+
which returns `True` if the problem is DBCP-compliant, and `False` otherwise.
128+
129+
### Solving a biconvex problem
130+
131+
After creating a `BiconvexProblem` instance,
132+
one can call its `solve` method to solve the problem:
133+
134+
```python
135+
prob.solve()
136+
```
137+
138+
The most important optional arguments of the
139+
`BiconvexProblem.solve` method are as follows:
140+
141+
- `lbd`: The regularization parameter of the proximal term.
142+
- `max_iters`: The maximum number of ACS iterations.
143+
- `gap_tolerance`: The tolerance for the gap between the subproblems
144+
when stopping the ACS procedure.
145+
146+
The `BiconvexRelaxProblem.solve` method has an additional
147+
optional argument `nu` to specify the penalty parameter
148+
for the total slackness, i.e.,
149+
violation of the biconvex constraints.
150+
68151
### Problem status
69152

70-
## Basic example
153+
After solving a biconvex problem using the `solve` method,
154+
one can check the problem status using the `status` attribute.
155+
156+
The possible status values for `BiconvexProblem` are as follows:
157+
158+
- `converge`: The ACS procedure converged successfully, i.e.,
159+
the final gap between the subproblems is within the specified tolerance.
160+
- `converge_inaccurate`: The maximum number of iterations was reached,
161+
but the final gap between the subproblems is still
162+
larger than the specified tolerance.
163+
164+
In the second case, one may want to call the `solve` method again.
165+
This will continue the ACS procedure from the last iteration, until
166+
either convergence is achieved or the maximum number of iterations
167+
is reached.
168+
169+
The possible status values for `BiconvexRelaxProblem` are as follows:
170+
171+
- `converge`: The ACS procedure converged successfully
172+
with a feasible solution (i.e., the total slackness is zero)
173+
to the original problem.
174+
- `converge_infeasible`: The ACS procedure converged successfully,
175+
but the final solution is still infeasible with nonzero total slackness.
176+
- `converge_inaccurate`: The maximum number of iterations was reached
177+
with a feasible final point,
178+
but the final gap between the subproblems is still
179+
larger than the specified tolerance.
180+
- `converge_inaccurate_infeasible`: The maximum number of iterations was reached,
181+
but the final gap between the subproblems is still
182+
larger than the specified tolerance,
183+
and the final solution is still infeasible with nonzero total slackness.
184+
185+
When 'infeasible' appears in the status,
186+
one may want to increase the penalty parameter `nu`
187+
and call the `solve` method again.
188+
189+
## Examples
190+
191+
### Basic example
71192

72193
Suppose we are given a matrix $A \in \mathbf{R}^{m \times n}$.
73194
Consider the following nonnegative matrix factorization problem:
@@ -86,7 +207,7 @@ with variables $X \in \mathbf{R}^{m \times k}$,
86207
$Y \in \mathbf{R}^{k \times n}$,
87208
and $Z \in \mathbf{R}^{m \times n}$.
88209

89-
To specify and solve this problem using `dbcp`,
210+
To specify and solve this problem using DBCP,
90211
one may use the following code:
91212

92213
```python
@@ -104,4 +225,15 @@ prob = dbcp.BiconvexProblem(obj, [[X], [Y]], constraints)
104225
prob.solve()
105226
```
106227

107-
## Citation
228+
### Other examples
229+
230+
We provide several other examples
231+
in the [examples](./examples) directory.
232+
To view and reproduce the examples, executing
233+
234+
```shell
235+
make marimo
236+
```
237+
238+
in the repository folder will install
239+
and start the [marimo](https://marimo.io/) environment.

0 commit comments

Comments
 (0)