diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..b1c27fc3d6 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: doc/source/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - method: pip + path: . + - requirements: doc/requirements.txt + - requirements: requirements.txt \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 0e0f73c5e7..717ce4477e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -256,8 +256,13 @@ def __getattr__(self, name): # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_css_files = ['css/styling.css'] - +html_css_files = [ + 'css/styling.css', + 'https://cdn.datatables.net/2.1.8/css/dataTables.dataTables.css', +] +html_js_files = [ + 'https://cdn.datatables.net/2.1.8/js/dataTables.js', +] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' diff --git a/doc/source/functions/functions_table.rst b/doc/source/functions/functions_table.rst new file mode 100644 index 0000000000..b4d0303278 --- /dev/null +++ b/doc/source/functions/functions_table.rst @@ -0,0 +1,1095 @@ +.. |_| unicode:: 0xA0 + :trim: + +.. list-table:: + :class: atomic-functions + :header-rows: 1 + + * - Function + - Meaning + - Domain + - DCP Properties + - Curvature |_| + + * - :ref:`dotsort(X,W) ` + + constant :math:`W \in \mathbf{R}^{o \times p}` + - :math:`\text{dot product of}` + :math:`\operatorname{sort}\operatorname{vec}(X) \text{ and}` + :math:`\operatorname{sort}\operatorname{vec}(W)` + - :math:`X \in \mathbf{R}^{m \times n}` + - sign depends on :math:`X`, :math:`W` + + |incr| for :math:`\min(W) \geq 0` + - |convex| convex + + * - :ref:`geo_mean(x) ` + + :ref:`geo_mean(x, p) ` + + :math:`p \in \mathbf{R}^n_{+}` + + :math:`p \neq 0` + - :math:`x_1^{1/n} \cdots x_n^{1/n}` + - :math:`x \in \mathbf{R}^n_{+}` + - |positive| positive + + |incr| incr. + - |concave| concave + + * - :ref:`harmonic_mean(x) ` + - :math:`\frac{n}{\frac{1}{x_1} + \cdots + \frac{1}{x_n}}` + - :math:`x \in \mathbf{R}^n_{+}` + - |positive| positive + + |incr| incr. + - |concave| concave + + * - :ref:`inv_prod(x) ` + - :math:`(x_1\cdots x_n)^{-1}` + - :math:`x \in \mathbf{R}^n_+` + - |positive| positive + + |decr| decr. + - |convex| convex + + * - :ref:`lambda_max(X) ` + - :math:`\lambda_{\max}(X)` + - :math:`X \in \mathbf{S}^n` + - |unknown| unknown sign + - |convex| convex + + * - :ref:`lambda_min(X) ` + - :math:`\lambda_{\min}(X)` + - :math:`X \in \mathbf{S}^n` + - |unknown| unknown sign + - |concave| concave + + * - :ref:`lambda_sum_largest(X,k) ` + + :math:`k = 1,\ldots, n` + - :math:`\text{sum of $k$ largest}` + :math:`\text{eigenvalues of $X$}` + - :math:`X \in\mathbf{S}^{n}` + - |unknown| unknown sign + - |convex| convex + + * - :ref:`lambda_sum_smallest(X,k) ` + + :math:`k = 1,\ldots, n` + - :math:`\text{sum of $k$ smallest}` + :math:`\text{eigenvalues of $X$}` + - :math:`X \in\mathbf{S}^{n}` + - |unknown| unknown sign + - |concave| concave + + * - :ref:`log_det(X) ` + + - :math:`\log \left(\det (X)\right)` + - :math:`X \in \mathbf{S}^n_+` + - |unknown| unknown sign + - |concave| concave + + * - :ref:`log_sum_exp(X) ` + + - :math:`\log \left(\sum_{ij}e^{X_{ij}}\right)` + - :math:`X \in\mathbf{R}^{m \times n}` + - |unknown| unknown sign + + |incr| incr. + - |convex| convex + + * - :ref:`matrix_frac(x, P) ` + + - :math:`x^T P^{-1} x` + - :math:`x \in \mathbf{R}^n` + - |positive| positive + - |convex| convex + + * - :ref:`max(X) ` + + - :math:`\max_{ij}\left\{ X_{ij}\right\}` + - :math:`X \in\mathbf{R}^{m \times n}` + - same sign as X + + |incr| incr. + - |convex| convex + + * - :ref:`mean(X) ` + + - :math:`\frac{1}{m n}\sum_{ij}\left\{ X_{ij}\right\}` + - :math:`X \in\mathbf{R}^{m \times n}` + - same sign as X + + |incr| incr. + - |affine| affine + + * - :ref:`min(X) ` + + - :math:`\min_{ij}\left\{ X_{ij}\right\}` + - :math:`X \in\mathbf{R}^{m \times n}` + - same sign as X + + |incr| incr. + - |concave| concave + + * - :ref:`mixed_norm(X, p, q) ` + + - :math:`\left(\sum_k\left(\sum_l\lvert x_{k,l}\rvert^p\right)^{q/p}\right)^{1/q}` + - :math:`X \in\mathbf{R}^{n \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`norm(x) ` + + norm(x, 2) + - :math:`\sqrt{\sum_{i} \lvert x_{i} \rvert^2 }` + - :math:`X \in\mathbf{R}^{n}` + - |positive| positive + + |incr| for :math:`x_{i} \geq 0` + - |convex| convex + + * - :ref:`norm(x, 1) ` + - :math:`\sum_{i}\lvert x_{i} \rvert` + - :math:`x \in\mathbf{R}^{n}` + - |positive| positive + + |incr| for :math:`x_{i} \geq 0` + - |convex| convex + + * - :ref:`norm(x, "inf") ` + - :math:`\max_{i} \{\lvert x_{i} \rvert\}` + - :math:`x \in\mathbf{R}^{n}` + - |positive| positive + + |incr| for :math:`x_{i} \geq 0` + - |convex| convex + + * - :ref:`norm(X, "fro") ` + - :math:`\sqrt{\sum_{ij}X_{ij}^2 }` + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + + |incr| for :math:`X_{ij} \geq 0` + - |convex| convex + + * - :ref:`norm(X, 1) ` + - :math:`\max_{j} \|X_{:,j}\|_1` + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + + |incr| for :math:`X_{ij} \geq 0` + - |convex| convex + + * - :ref:`norm(X, "inf") ` + - :math:`\max_{i} \|X_{i,:}\|_1` + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + + |incr| for :math:`X_{ij} \geq 0` + - |convex| convex + + * - :ref:`norm(X, "nuc") ` + - :math:`\mathrm{tr}\left(\left(X^T X\right)^{1/2}\right)` + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`norm(X) ` + norm(X, 2) + - :math:`\sqrt{\lambda_{\max}\left(X^T X\right)}` + - :math:`X in\mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`perspective(f(x),s) ` + + - :math:`sf(x/s)` + - :math:`x \in \mathop{\bf dom} f` + :math:`s \geq 0` + - same sign as f + - |convex| / |concave| + same as :math:`f` + + * - :ref:`pnorm(X, p) ` + + :math:`p \geq 1` + or ``p = 'inf'`` + - :math:`\left(\sum_{ij} |X_{ij}|^p \right)^{1/p}` + - :math:`X \in \mathbf{R}^{m \times n}` + - |positive| positive + + |incr| for :math:`X_{ij} \geq 0` + - |convex| convex + + * - :ref:`pnorm(X, p) ` + + :math:`p < 1`, :math:`p \neq 0` + - :math:`\left(\sum_{ij} X_{ij}^p \right)^{1/p}` + - :math:`X \in \mathbf{R}^{m \times n}_+` + - |positive| positive + + |incr| incr. + - |concave| concave + + * - :ref:`ptp(X) ` + + - :math:`\max_{ij} X_{ij} - \min_{ij} X_{ij}` + - :math:`X \in \mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`quad_form(x, P) ` + + constant :math:`P \in \mathbf{S}^n_+` + - :math:`x^T P x` + - :math:`x \in \mathbf{R}^n` + - |positive| positive + + |incr| for :math:`x_i \geq 0` + - |convex| convex + + * - :ref:`quad_form(x, P) ` + + constant :math:`P \in \mathbf{S}^n_-` + - :math:`x^T P x` + - :math:`x \in \mathbf{R}^n` + - |negative| negative + + |decr| for :math:`x_i \geq 0` + - |concave| concave + + * - :ref:`quad_form(c, X) ` + + constant :math:`c \in \mathbf{R}^n` + - :math:`c^T X c` + - :math:`X \in\mathbf{R}^{n \times n}` + - sign depends |_| on |_| c, |_| X + + monotonicity depends |_| on |_| c + - |affine| affine + + * - :ref:`quad_over_lin(X, y) ` + + - :math:`\left(\sum_{ij}X_{ij}^2\right)/y` + - :math:`x \in \mathbf{R}^n` + :math:`y > 0` + - |positive| positive + + |incr| for :math:`X_{ij} \geq 0` + |decr| for :math:`X_{ij} \leq 0` + |decr| decr. in :math:`y` + - |convex| convex + + * - :ref:`std(X) ` + + - analog to `numpy.std `_ + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`sum(X) ` + + - :math:`\sum_{ij}X_{ij}` + - :math:`X \in\mathbf{R}^{m \times n}` + - same sign as X + + |incr| incr. + - |affine| affine + + * - :ref:`sum_largest(X, k) ` + + :math:`k = 1,2,\ldots` + - :math:`\text{sum of } k` + + :math:`\text{largest }X_{ij}` + - :math:`X \in\mathbf{R}^{m \times n}` + - same sign as X + + |incr| incr. + - |convex| convex + + * - :ref:`sum_smallest(X, k) ` + + :math:`k = 1,2,\ldots` + - :math:`\text{sum of } k` + + :math:`\text{smallest }X_{ij}` + - :math:`X \in\mathbf{R}^{m \times n}` + - same sign as X + + |incr| incr. + - |concave| concave + + * - :ref:`sum_squares(X) ` + + - :math:`\sum_{ij}X_{ij}^2` + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + + |incr| for :math:`X_{ij} \geq 0` + |decr| for :math:`X_{ij} \leq 0` + - |convex| convex + + * - :ref:`trace(X) ` + + - :math:`\mathrm{tr}\left(X \right)` + - :math:`X \in\mathbf{R}^{n \times n}` + - same sign as X + + |incr| incr. + - |affine| affine + + * - :ref:`tr_inv(X) ` + + - :math:`\mathrm{tr}\left(X^{-1} \right)` + - :math:`X \in\mathbf{S}^n_{++}` + - |positive| positive + - |convex| convex + + * - :ref:`tv(x) ` + + - :math:`\sum_{i}|x_{i+1} - x_i|` + - :math:`x \in \mathbf{R}^n` + - |positive| positive + - |convex| convex + + * - :ref:`tv(X) ` + :math:`Y = \left[\begin{matrix} X_{i+1,j} - X_{ij} \\ X_{i,j+1} -X_{ij} \end{matrix}\right]` + - :math:`\sum_{ij}\left\| Y \right\|_2` + - :math:`X \in \mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`tv([X1,...,Xk]) ` + :math:`Y = \left[\begin{matrix} X_{i+1,j}^{(1)} - X_{ij}^{(1)} \\ X_{i,j+1}^{(1)} -X_{ij}^{(1)} \\ \vdots \\ X_{i+1,j}^{(k)} - X_{ij}^{(k)} \\ X_{i,j+1}^{(k)} -X_{ij}^{(k)} \end{matrix}\right]` + - :math:`\sum_{ij}\left\| Y \right\|_2` + - :math:`X^{(i)} \in\mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`var(X) ` + + - analog to `numpy.var `_ + - :math:`X \in\mathbf{R}^{m \times n}` + - |positive| positive + - |convex| convex + + * - :ref:`abs(x) ` + + - :math:`\lvert x \rvert` + - :math:`x \in \mathbf{C}` + - |positive| positive + + |incr| for :math:`x \geq 0` + - |convex| convex + + * - :ref:`conj(x) ` + + - complex conjugate + - :math:`x \in \mathbf{C}` + - |unknown| unknown sign + - |affine| affine + + * - :ref:`entr(x) ` + + - :math:`-x \log (x)` + - :math:`x > 0` + - |unknown| unknown sign + - |concave| concave + + * - :ref:`exp(x) ` + + - :math:`e^x` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| incr. + - |convex| convex + + * - :ref:`huber(x, M=1) ` + + :math:`M \geq 0` + - :math:`\begin{aligned} & \text{if } |x| \leq M\colon \\& x^2 \end{aligned}` + + :math:`\begin{aligned} & \text{if } |x| > M\colon \\& 2M|x| - M^2 \end{aligned}` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| for :math:`x \geq 0` + + |decr| for :math:`x \leq 0` + - |convex| convex + + * - :ref:`imag(x) ` + + - imaginary part + + of a complex number + - :math:`x \in \mathbf{C}` + - |unknown| unknown sign + - |affine| affine + + * - :ref:`inv_pos(x) ` + + - :math:`1/x` + - :math:`x > 0` + - |positive| positive + + |decr| decr. + - |convex| convex + + * - :ref:`kl_div(x, y) ` + + - :math:`x \log(x/y) - x + y` + - :math:`x > 0` + + :math:`y > 0` + - |positive| positive + - |convex| convex + + * - :ref:`log(x) ` + + - :math:`\log(x)` + - :math:`x > 0` + - |unknown| unknown sign + + |incr| incr. + - |concave| concave + + * - :ref:`log_normcdf(x) ` + + - :ref:`approximate ` log of the standard normal CDF + - :math:`x \in \mathbf{R}` + - |negative| negative + + |incr| incr. + - |concave| concave + + * - :ref:`log1p(x) ` + + - :math:`\log(x+1)` + - :math:`x > -1` + - same sign as x + + |incr| incr. + - |concave| concave + + * - :ref:`loggamma(x) ` + + - :ref:`approximate ` `log of the Gamma function `_ + - :math:`x > 0` + - |unknown| unknown sign + - |convex| convex + + * - :ref:`logistic(x) ` + + - :math:`\log(1 + e^{x})` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| incr. + - |convex| convex + + * - :ref:`maximum(x, y) ` + + - :math:`\max \left\{x, y\right\}` + - :math:`x,y \in \mathbf{R}` + - sign depends on x,y + + |incr| incr. + - |convex| convex + + * - :ref:`minimum(x, y) ` + - :math:`\min \left\{x, y\right\}` + - :math:`x, y \in \mathbf{R}` + - sign depends |_| on |_| x,y + + |incr| incr. + - |concave| concave + + * - :ref:`multiply(c, x) ` + + :math:`c \in \mathbf{R}` + - c*x + - :math:`x \in\mathbf{R}` + - :math:`\mathrm{sign}(cx)` + + monotonicity depends |_| on |_| c + - |affine| affine + + * - :ref:`neg(x) ` + - :math:`\max \left\{-x, 0 \right\}` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |decr| decr. + - |convex| convex + + * - :ref:`pos(x) ` + - :math:`\max \left\{x, 0 \right\}` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| incr. + - |convex| convex + + * - :ref:`power(x, 0) ` + - :math:`1` + - :math:`x \in \mathbf{R}` + - |positive| positive + - constant + + * - :ref:`power(x, 1) ` + - :math:`x` + - :math:`x \in \mathbf{R}` + - same sign as x + + |incr| incr. + - |affine| affine + + * - :ref:`power(x, p) ` + + :math:`p = 2, 4, 8, \ldots` + - :math:`x^p` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| for :math:`x \geq 0` + |decr| for :math:`x \leq 0` + - |convex| convex + + * - :ref:`power(x, p) ` + + :math:`p < 0` + - :math:`x^p` + - :math:`x > 0` + - |positive| positive + + |decr| decr. + - |convex| convex + + * - :ref:`power(x, p) ` + + :math:`0 < p < 1` + - :math:`x^p` + - :math:`x \geq 0` + - |positive| positive + + |incr| incr. + - |concave| concave + + * - :ref:`power(x, p) ` + + :math:`p > 1,\ p \neq 2, 4, 8, \ldots` + + - :math:`x^p` + - :math:`x \geq 0` + - |positive| positive + + |incr| incr. + - |convex| convex + + * - :ref:`real(x) ` + + - real part of a complex number + - :math:`x \in \mathbf{C}` + - |unknown| unknown sign + + |incr| incr. + - |affine| affine + + * - :ref:`rel_entr(x, y) ` + + - :math:`x \log(x/y)` + - :math:`x > 0` + + :math:`y > 0` + - |unknown| unknown sign + + |decr| in :math:`y` + - |convex| convex + + * - :ref:`scalene(x, alpha, beta) ` + + :math:`\text{alpha} \geq 0` + + :math:`\text{beta} \geq 0` + - :math:`\alpha\mathrm{pos}(x)+ \beta\mathrm{neg}(x)` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| for :math:`x \geq 0` + + |decr| for :math:`x \leq 0` + - |convex| convex + + * - :ref:`sqrt(x) ` + + - :math:`\sqrt x` + - :math:`x \geq 0` + - |positive| positive + + |incr| incr. + - |concave| concave + + * - :ref:`square(x) ` + + - :math:`x^2` + - :math:`x \in \mathbf{R}` + - |positive| positive + + |incr| for :math:`x \geq 0` + + |decr| for :math:`x \leq 0` + - |convex| convex + + * - :ref:`xexp(x) ` + + - :math:`x e^x` + - :math:`x \geq 0` + - |positive| positive + + |incr| incr. + - |convex| convex + + * - :ref:`bmat() ` + + - :math:`\left[\begin{matrix} X^{(1,1)} & .. & X^{(1,q)} \\ \vdots & & \vdots \\ X^{(p,1)} & .. & X^{(p,q)} \end{matrix}\right]` + - :math:`X^{(i,j)} \in\mathbf{R}^{m_i \times n_j}` + - |incr| incr. + - |affine| affine + + * - :ref:`convolve(c, x) ` + + :math:`c\in\mathbf{R}^m` + - :math:`c*x` + - :math:`x\in \mathbf{R}^n` + - monotonicity depends |_| on |_| c + - |affine| affine + + * - :ref:`cumsum(X, axis=0) ` + + - cumulative sum along given axis. + - :math:`X \in \mathbf{R}^{m \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`diag(x) ` + + - :math:`\left[\begin{matrix}x_1 & & \\& \ddots & \\& & x_n\end{matrix}\right]` + - :math:`x \in\mathbf{R}^{n}` + - |incr| incr. + - |affine| affine + + * - :ref:`diag(X) ` + - :math:`\left[\begin{matrix}X_{11} \\\vdots \\X_{nn}\end{matrix}\right]` + - :math:`X \in\mathbf{R}^{n \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`diff(X, k=1, axis=0) ` + + :math:`k \in 0,1,2,\ldots` + - kth order differences along given axis + - :math:`X \in\mathbf{R}^{m \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`hstack([X1, ..., Xk]) ` + + - :math:`\left[\begin{matrix}X^{(1)} \cdots X^{(k)}\end{matrix}\right]` + - :math:`X^{(i)} \in\mathbf{R}^{m \times n_i}` + - |incr| incr. + - |affine| affine + + * - :ref:`kron(X, Y) ` + + constant :math:`X\in\mathbf{R}^{p \times q}` + - :math:`\left[\begin{matrix}X_{11}Y & .. & X_{1q}Y \\ \vdots & & \vdots \\ X_{p1}Y & .. & X_{pq}Y \end{matrix}\right]` + - :math:`Y \in \mathbf{R}^{m \times n}` + - monotonicity depends on :math:`X` + - |affine| affine + + * - :ref:`kron(X, Y) ` + + constant :math:`Y\in\mathbf{R}^{m \times n}` + - :math:`\left[\begin{matrix}X_{11}Y & .. & X_{1q}Y \\ \vdots & & \vdots \\ X_{p1}Y & .. & X_{pq}Y \end{matrix}\right]` + - :math:`X \in \mathbf{R}^{p \times q}` + - monotonicity depends on :math:`Y` + - |affine| affine + + * - :ref:`outer(x, y) ` + + constant :math:`y \in \mathbf{R}^m` + - :math:`x y^T` + - :math:`x \in \mathbf{R}^n` + - monotonicity depends on :math:`Y` + - |affine| affine + + * - :ref:`partial_trace(X, dims, axis=0) ` + + - partial trace + - :math:`X \in\mathbf{R}^{n \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`partial_transpose(X, dims, axis=0) ` + + - partial transpose + - :math:`X \in\mathbf{R}^{n \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`reshape(X, (m', n'), order='F') ` + + - :math:`X' \in\mathbf{R}^{m' \times n'}` + - :math:`X \in\mathbf{R}^{m \times n}` + + :math:`m'n' = mn` + - |incr| incr. + - |affine| affine + + * - :ref:`upper_tri(X) ` + + - flatten the strictly upper-triangular part of :math:`X` + - :math:`X \in \mathbf{R}^{n \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`vec(X) ` + + - :math:`x' \in\mathbf{R}^{mn}` + - :math:`X \in\mathbf{R}^{m \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`vec_to_upper_tri(X, strict=False) ` + + - :math:`x' \in\mathbf{R}^{n(n-1)/2}` for ``strict=True`` + + :math:`x' \in\mathbf{R}^{n(n+1)/2}` for ``strict=False`` + - :math:`X \in\mathbf{R}^{n \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`vstack([X1, ..., Xk]) ` + - :math:`\left[\begin{matrix}X^{(1)} \\ \vdots \\X^{(k)}\end{matrix}\right]` + - :math:`X^{(i)} \in\mathbf{R}^{m_i \times n}` + - |incr| incr. + - |affine| affine + + * - :ref:`geo_mean(x) ` + + :ref:`geo_mean(x, p) ` + + :math:`p \in \mathbf{R}^n_{+}` + + :math:`p \neq 0` + - :math:`x_1^{1/n} \cdots x_n^{1/n}` + + :math:`\left(x_1^{p_1} \cdots x_n^{p_n}\right)^{\frac{1}{\mathbf{1}^T p}}` + - :math:`x \in \mathbf{R}^n_{+}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`harmonic_mean(x) ` + - :math:`\frac{n}{\frac{1}{x_1} + \cdots + \frac{1}{x_n}}` + - :math:`x \in \mathbf{R}^n_{+}` + - |incr| incr. + - |concave| log-log concave + + * - :ref:`max(X) ` + - :math:`\max_{ij}\left\{ X_{ij}\right\}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`min(X) ` + - :math:`\min_{ij}\left\{ X_{ij}\right\}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |concave| log-log concave + + * - :ref:`norm(x) ` + + :ref:`norm(x, 2) ` + + - :math:`\sqrt{\sum_{i} \lvert x_{i} \rvert^2 }` + - :math:`X \in\mathbf{R}^{n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`norm(X, "fro") ` + - :math:`\sqrt{\sum_{ij}X_{ij}^2 }` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`norm(X, 1) ` + - :math:`\sum_{ij}\lvert X_{ij} \rvert` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`norm(X, "inf") ` + - :math:`\max_{ij} \{\lvert X_{ij} \rvert\}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`pnorm(X, p) ` + + :math:`p \geq 1` + + or ``p = 'inf'`` + - :math:`\left(\sum_{ij} |X_{ij}|^p \right)^{1/p}` + - :math:`X \in \mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`pnorm(X, p) ` + :math:`0 < p < 1` + - :math:`\left(\sum_{ij} X_{ij}^p \right)^{1/p}` + - :math:`X \in \mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`prod(X) ` + - :math:`\prod_{ij}X_{ij}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`quad_form(x, P) ` + - :math:`x^T P x` + - :math:`x \in \mathbf{R}^n`, :math:`P \in \mathbf{R}^{n \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`quad_over_lin(X, y) ` + - :math:`\left(\sum_{ij}X_{ij}^2\right)/y` + - :math:`x \in \mathbf{R}^n_{++}` + + :math:`y > 0` + - |incr| in :math:`X_{ij}` + + |decr| decr. in :math:`y` + - |convex| log-log convex + + * - :ref:`sum(X) ` + - :math:`\sum_{ij}X_{ij}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`sum_squares(X) ` + - :math:`\sum_{ij}X_{ij}^2` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`trace(X) ` + - :math:`\mathrm{tr}\left(X \right)` + - :math:`X \in\mathbf{R}^{n \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`pf_eigenvalue(X) ` + - spectral radius of :math:`X` + - :math:`X \in\mathbf{R}^{n \times n}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`diff_pos(x, y) ` + - :math:`x - y` + - :math:`0 < y < x` + - |incr| incr. in :math:`x` + + |decr| decr. in :math:`y` + - |concave| log-log concave + + * - :ref:`entr(x) ` + - :math:`-x \log (x)` + - :math:`0 < x < 1` + - None + - |concave| log-log concave + + * - :ref:`exp(x) ` + - :math:`e^x` + - :math:`x > 0` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`log(x) ` + - :math:`\log(x)` + - :math:`x > 1` + - |incr| incr. + - |concave| log-log concave + + * - :ref:`maximum(x, y) ` + - :math:`\max \left\{x, y\right\}` + - :math:`x,y > 0` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`minimum(x, y) ` + - :math:`\min \left\{x, y\right\}` + - :math:`x, y > 0` + - |incr| incr. + - |concave| log-log concave + + * - :ref:`multiply(x, y) ` + - :math:`x*y` + - :math:`x, y > 0` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`one_minus_pos(x) ` + - :math:`1 - x` + - :math:`0 < x < 1` + - |decr| decr. + - |concave| log-log concave + + * - :ref:`power(x, 0) ` + - :math:`1` + - :math:`x > 0` + - constant + - constant + + * - :ref:`power(x, p) ` + - :math:`x` + - :math:`x > 0` + - |incr| for :math:`p > 0` + + |decr| for :math:`p < 0` + - |affine| log-log affine + + * - :ref:`sqrt(x) ` + - :math:`\sqrt x` + - :math:`x > 0` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`square(x) ` + - :math:`x^2` + - :math:`x > 0` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`xexp(x) ` + - :math:`x e^x` + - :math:`x > 0` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`bmat() ` + - :math:`\left[\begin{matrix} X^{(1,1)} & .. & X^{(1,q)} \\ \vdots & & \vdots \\ X^{(p,1)} & .. & X^{(p,q)} \end{matrix}\right]` + - :math:`X^{(i,j)} \in\mathbf{R}^{m_i \times n_j}_{++}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`diag(x) ` + - :math:`\left[\begin{matrix}x_1 & & \\& \ddots & \\& & x_n\end{matrix}\right]` + - :math:`x \in\mathbf{R}^{n}_{++}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`diag(X) ` + - :math:`\left[\begin{matrix}X_{11} \\\vdots \\X_{nn}\end{matrix}\right]` + - :math:`X \in\mathbf{R}^{n \times n}_{++}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`eye_minus_inv(X) ` + - :math:`(I - X)^{-1}` + - :math:`X \in\mathbf{R}^{n \times n}_{++}`, + + :math:`\lambda_{\text{pf}}(X) < 1` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`gmatmul(A, x) ` + + :math:`A \in \mathbf{R}^{m \times n}` + - :math:`\left[\begin{matrix}\prod_{j=1}^n x_j^{A_{1j}} \\\vdots \\\prod_{j=1}^n x_j^{A_{mj}}\end{matrix}\right]` + - :math:`x \in \mathbf{R}^n_{++}` + - |incr| for :math:`A_{ij} \geq 0` + + |decr| for :math:`A_{ij} \leq 0` + - |affine| log-log affine + + * - :ref:`hstack([X1, ..., Xk]) ` + - :math:`\left[\begin{matrix}X^{(1)} \cdots X^{(k)}\end{matrix}\right]` + - :math:`X^{(i)} \in\mathbf{R}^{m \times n_i}_{++}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`matmul(X, Y) ` + - :math:`XY` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + + :math:`Y \in\mathbf{R}^{n \times p}_{++}` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`resolvent(X) ` + - :math:`(sI - X)^{-1}` + - :math:`X \in\mathbf{R}^{n \times n}_{++}` + + :math:`\lambda_{\text{pf}}(X) < s` + - |incr| incr. + - |convex| log-log convex + + * - :ref:`reshape(X, (m', n')) ` + - :math:`X' \in\mathbf{R}^{m' \times n'}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + + :math:`m'n' = mn` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`vec(X) ` + - :math:`x' \in\mathbf{R}^{mn}` + - :math:`X \in\mathbf{R}^{m \times n}_{++}` + - |incr| incr. + - |affine| log-log affine + + * - :ref:`vstack([X1, ..., Xk]) ` + - :math:`\left[\begin{matrix}X^{(1)} \\ \vdots \\X^{(k)}\end{matrix}\right]` + - :math:`X^{(i)} \in\mathbf{R}^{m_i \times n}_{++}` + - |incr| incr. + - |affine| log-log affine + +.. |positive| image:: /tutorial/functions/functions_files/positive.svg + :width: 15px + :height: 15px + +.. |negative| image:: /tutorial/functions/functions_files/negative.svg + :width: 15px + :height: 15px + +.. |unknown| image:: /tutorial/functions/functions_files/unknown.svg + :width: 15px + :height: 15px + +.. |convex| image:: /tutorial/functions/functions_files/convex.svg + :width: 15px + :height: 15px + +.. |concave| image:: /tutorial/functions/functions_files/concave.svg + :width: 15px + :height: 15px + +.. |affine| image:: /tutorial/functions/functions_files/affine.svg + :width: 15px + :height: 15px + +.. |incr| image:: /tutorial/functions/functions_files/increasing.svg + :width: 15px + :height: 15px + +.. |decr| image:: /tutorial/functions/functions_files/decreasing.svg + :width: 15px + :height: 15px \ No newline at end of file diff --git a/doc/source/functions/index.rst b/doc/source/functions/index.rst new file mode 100644 index 0000000000..e21358c2b2 --- /dev/null +++ b/doc/source/functions/index.rst @@ -0,0 +1,108 @@ +.. _functions: + +Functions +========= +The table below lists all the atomic functions available in CVXPY. + +.. raw:: html + +
+
+
Curvature
+
+
+ + + + +
+ + + +
+
+
DCP Property
+
+
+ + + + + +
+
+
+ +Atoms table +----------- +.. include:: functions_table.rst + +.. raw:: html + + + + + diff --git a/doc/source/index.rst b/doc/source/index.rst index f75b3b3b60..ba3c13fc4f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -126,6 +126,11 @@ website to use a modern theme based on Sphinx Immaterial. User Guide +.. toctree:: + :hidden: + + functions/index + .. toctree:: :hidden: