pyxu.operator.map

Element-wise Operators

class Abs(dim_shape)

Bases: Map

Absolute value, element-wise.

Notes

• \(f(x) = \vert x \vert\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

class ArcCos(dim_shape)

Bases: DiffMap

Inverse cosine, element-wise.

Notes

• \(f(x) = \arccos(x)\)

• \(f'(x) = -(1 - x^{2})^{-\frac{1}{2}}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = [-1, 1]\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = [-1, 1]\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class ArcCosh(dim_shape)

Bases: DiffMap

Inverse hyperbolic cosine, element-wise.

Notes

• \(f(x) = \cosh^{-1}(x) = \ln(x + \sqrt{x^{2} - 1})\)

• \(f'(x) = (x^{2} - 1)^{-\frac{1}{2}}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = [1, \infty[\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = [1, \infty[\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class ArcSin(dim_shape)

Bases: DiffMap

Inverse sine, element-wise.

Notes

• \(f(x) = \arcsin(x)\)

• \(f'(x) = (1 - x^{2})^{-\frac{1}{2}}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = [-1, 1]\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = [-1, 1]\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class ArcSinh(dim_shape)

Bases: DiffMap

Inverse hyperbolic sine, element-wise.

Notes

• \(f(x) = \sinh^{-1}(x) = \ln(x + \sqrt{x^{2} + 1})\)

• \(f'(x) = (x^{2} + 1)^{-\frac{1}{2}}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = 0\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \frac{2}{3 \sqrt{3}}\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = \pm \frac{1}{\sqrt{2}}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class ArcTan(dim_shape)

Bases: DiffMap

Inverse tangent, element-wise.

Notes

• \(f(x) = \arctan(x)\)

• \(f'(x) = (1 + x^{2})^{-1}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = 0\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 3 \sqrt{3} / 8\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = \pm \frac{1}{\sqrt{3}}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class ArcTanh(dim_shape)

Bases: DiffMap

Inverse hyperbolic tangent, element-wise.

Notes

• \(f(x) = \tanh^{-1}(x) = \frac{1}{2}\ln\left(\frac{1+x}{1-x}\right)\)

• \(f'(x) = (1 - x^{2})^{-1}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = [-1, 1]\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = [-1, 1]\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Cbrt(dim_shape)

Bases: DiffMap

Cube-root, element-wise.

Notes

• \(f(x) = \sqrt[3]{x}\)

• \(f'(x) = 1 / 3 \sqrt[3]{x^{2}}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Clip(dim_shape, a_min=None, a_max=None)

Bases: Map

Clip (limit) values in an array, element-wise.

Notes

• \[\begin{split}f_{[a,b]}(x) = \begin{cases} a, & \text{if} \ x \leq a, \\ x, & a < x < b, \\ b, & \text{if} \ x \geq b. \end{cases}\end{split}\]

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• a_min (Real)

• a_max (Real)

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

class Cos(dim_shape)

Bases: DiffMap

Trigonometric cosine, element-wise.

Notes

• \(f(x) = \cos(x)\)

• \(f'(x) = -\sin(x)\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = (2k + 1) \frac{\pi}{2}, \, k \in \mathbb{Z}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 1\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = k \pi, \, k \in \mathbb{Z}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Cosh(dim_shape)

Bases: DiffMap

Hyperbolic cosine, element-wise.

Notes

• \(f(x) = \cosh(x)\)

• \(f'(x) = \sinh(x)\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Exp(dim_shape, base=None)

Bases: DiffMap

Exponential, element-wise. (Default: base-E exponential.)

Notes

• \(f_{b}(x) = b^{x}\)

• \(f_{b}'(x) = b^{x} \ln(b)\)

• \(\vert f_{b}(x) - f_{b}(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f_{b}'(x)\) is unbounded on \(\text{dom}(f_{b}) = \mathbb{R}\).)

• \(\vert f_{b}'(x) - f_{b}'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f_{b}''(x)\) is unbounded on \(\text{dom}(f_{b}) = \mathbb{R}\).)

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• base (Real)

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Gaussian(dim_shape)

Bases: DiffMap

Gaussian, element-wise.

Notes

• \(f(x) = \exp(-x^{2})\)

• \(f'(x) = -2 x \exp(-x^{2})\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \sqrt{2 / e}\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = \pm 1 / \sqrt{2}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 2\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = 0\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class LeakyReLU(dim_shape, alpha)

Bases: Map

Leaky rectified linear unit, element-wise.

Notes

• \(f(x) = x \left[\mathbb{1}_{\ge 0}(x) + \alpha \mathbb{1}_{< 0}(x)\right], \quad \alpha \ge 0\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \max(1, \alpha)\).

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• alpha (Real)

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

class Log(dim_shape, base=None)

Bases: DiffMap

Logarithm, element-wise. (Default: base-E logarithm.)

Notes

• \(f_{b}(x) = \log_{b}(x)\)

• \(f_{b}'(x) = x^{-1} / \ln(b)\)

• \(\vert f_{b}(x) - f_{b}(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f_{b}'(x)\) is unbounded on \(\text{dom}(f_{b}) = \mathbb{R}_{+}\).)

• \(\vert f_{b}'(x) - f_{b}'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f_{b}''(x)\) is unbounded on \(\text{dom}(f_{b}) = \mathbb{R}_{+}\).)

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• base (Real)

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class ReLU(dim_shape)

Bases: LeakyReLU

Rectified linear unit, element-wise.

Notes

• \(f(x) = \lfloor x \rfloor_{+}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

Parameters:

dim_shape (Integral | tuple[Integral, ...])

class Sigmoid(dim_shape)

Bases: DiffMap

Sigmoid, element-wise.

Notes

• \(f(x) = (1 + e^{-x})^{-1}\)

• \(f'(x) = f(x) [ f(x) - 1 ]\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1 / 4\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = 0\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 1 / 6 \sqrt{3}\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = \ln(2 \pm \sqrt{3})\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Sign(dim_shape)

Bases: Map

Number sign indicator, element-wise.

Notes

• \(f(x) = x / \vert x \vert\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 2\).

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

class SiLU(dim_shape)

Bases: DiffMap

Sigmoid linear unit, element-wise.

Notes

• \(f(x) = x / (1 + e^{-x})\)

• \(f'(x) = (1 + e^{-x} + x e^{-x}) / (1 + e^{-x})^{2}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1.1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x \approx 2.4\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 1 / 2\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = 0\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Sin(dim_shape)

Bases: DiffMap

Trigonometric sine, element-wise.

Notes

• \(f(x) = \sin(x)\)

• \(f'(x) = \cos(x)\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = k \pi, \, k \in \mathbb{Z}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 1\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = (2k + 1) \frac{\pi}{2}, \, k \in \mathbb{Z}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Sinh(dim_shape)

Bases: DiffMap

Hyperbolic sine, element-wise.

Notes

• \(f(x) = \sinh(x)\)

• \(f'(x) = \cosh(x)\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class SoftPlus(dim_shape)

Bases: DiffMap

Softplus operator.

Notes

• \(f(x) = \ln(1 + e^{x})\)

• \(f'(x) = (1 + e^{-x})^{-1}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) on \(\text{dom}(f) = \mathbb{R}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 1 / 4\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = 0\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Sqrt(dim_shape)

Bases: DiffMap

Non-negative square-root, element-wise.

Notes

• \(f(x) = \sqrt{x}\)

• \(f'(x) = 1 / 2 \sqrt{x}\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}_{+}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}_{+}\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Square(dim_shape)

Bases: DiffMap

Square, element-wise.

Notes

• \(f(x) = x^{2}\)

• \(f'(x) = 2 x\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = \mathbb{R}\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 2\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) everywhere.)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Tan(dim_shape)

Bases: DiffMap

Trigonometric tangent, element-wise.

Notes

• \(f(x) = \tan(x)\)

• \(f'(x) = \cos^{-2}(x)\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = \infty\).

  (Reason: \(f'(x)\) is unbounded on \(\text{dom}(f) = [-\pi, \pi]\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = \infty\).

  (Reason: \(f''(x)\) is unbounded on \(\text{dom}(f) = [-\pi, \pi]\).)

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

class Tanh(dim_shape)

Bases: DiffMap

Hyperbolic tangent, element-wise.

Notes

• \(f(x) = \tanh(x)\)

• \(f'(x) = 1 - \tanh^{2}(x)\)

• \(\vert f(x) - f(y) \vert \le L \vert x - y \vert\), with Lipschitz constant \(L = 1\).

  (Reason: \(\vert f'(x) \vert\) is bounded by \(L\) at \(x = 0\).)

• \(\vert f'(x) - f'(y) \vert \le \partial L \vert x - y \vert\), with diff-Lipschitz constant \(\partial L = 4 / 3 \sqrt{3}\).

  (Reason: \(\vert f''(x) \vert\) is bounded by \(\partial L\) at \(x = \frac{1}{2} \ln(2 \pm \sqrt{3})\).

Parameters:

dim_shape (Integral | tuple[Integral, ...])

apply(arr)

Evaluate operator at specified point(s).

Parameters:

arr (NDArray) – (…, M1,…,MD) input points.

Returns:

out – (…, N1,…,NK) output points.

Return type:

NDArray

jacobian(arr)

Evaluate the Jacobian of \(\mathbf{f}\) at the specified point.

Parameters:

arr (NDArray) – (M1,…,MD) evaluation point.

Returns:

op – Jacobian operator at point arr.

Return type:

OpT

Notes

Let \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) be a differentiable multi-dimensional map. The Jacobian (or differential) of \(\mathbf{f}\) at \(\mathbf{z} \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) is defined as the best linear approximator of \(\mathbf{f}\) near \(\mathbf{z}\), in the following sense:

\[\mathbf{f}(\mathbf{x}) - \mathbf{f}(\mathbf{z}) = \mathbf{J}_{\mathbf{f}}(\mathbf{z}) (\mathbf{x} - \mathbf{z}) + o(\| \mathbf{x} - \mathbf{z} \|) \quad \text{as} \quad \mathbf{x} \to \mathbf{z}.\]

The Jacobian admits the following matrix representation:

\[[\mathbf{J}_{\mathbf{f}}(\mathbf{x})]_{ij} := \frac{\partial f_{i}}{\partial x_{j}}(\mathbf{x}), \qquad \forall (i,j) \in \{1,\ldots,N_{1}\cdots N_{K}\} \times \{1,\ldots,M_{1}\cdots M_{D}\}.\]

Misc

ConstantValued(dim_shape, codim_shape, cst)

Constant-valued operator \(C: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\).

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• codim_shape (Integral | tuple[Integral, ...])

• cst (Real)

Return type:

OpT

class TransposeAxes(dim_shape, axes=None)

Bases: UnitOp

Reverse or permute the axes of an array.

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• axes (Integral | tuple[Integral, ...])

__init__(dim_shape, axes=None)

Parameters:

• axes (NDArrayAxis) –

  New axis order.

  If specified, must be a tuple or list which contains a permutation of [0,1,…,D-1]. All axes are reversed if unspecified. (Default)

• dim_shape (Integral | tuple[Integral, ...])

class SqueezeAxes(dim_shape, axes=None)

Bases: UnitOp

Remove axes of length one.

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• axes (Integral | tuple[Integral, ...])

__init__(dim_shape, axes=None)

Parameters:

• axes (NDArrayAxis) –

  Axes to drop.

  If unspecified, all axes of shape 1 will be dropped. If an axis is selected with shape greater than 1, an error is raised.

• dim_shape (Integral | tuple[Integral, ...])

Notes

• 1D arrays cannot be squeezed.

• Given a D-dimensional input, at most D-1 dimensions may be dropped.

RechunkAxes(dim_shape, chunks)

Re-chunk core dimensions to new chunk size.

Parameters:

• dim_shape (NDArrayShape)

• chunks (dict) –

  (ax -> chunk_size) mapping, where chunk_size can be:

  • int (non-negative)

  • tuple[int]

  The following special values per axis can also be used:

  • None: do not change chunks.

  • -1: do not chunk.

  • ”auto”: select a good chunk size.

Returns:

op

Return type:

OpT

Notes

• apply() is a no-op if inputs are not DASK arrays.

• adjoint() is always a no-op.

• Chunk sizes along stacking dimensions are not modified.

class ReshapeAxes(dim_shape, codim_shape)

Bases: UnitOp

Reshape an array.

Notes

• If an integer, then the result will be a 1D array of that length. One co-dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions.

• Reshaping DASK inputs may be sub-optimal based on the array’s chunk structure: use at your own risk.

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• codim_shape (Integral | tuple[Integral, ...])

cogram()

Co-Gram operator \(\mathbf{A}\mathbf{A}^{\ast}:\mathbb{R}^{N_{1} \times\cdots\times N_{K}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\).

Returns:

op – Co-Gram operator.

Return type:

OpT

Note

By default the co-Gram is computed by the composition self * self.T. This may not be the fastest way to compute the co-Gram operator. If the co-Gram can be computed more efficiently (e.g. with a convolution), the user should re-define this method.

class BroadcastAxes(dim_shape, codim_shape)

Bases: LinOp

Broadcast an array.

Parameters:

• dim_shape (Integral | tuple[Integral, ...])

• codim_shape (Integral | tuple[Integral, ...])

estimate_lipschitz(**kwargs)

Compute a Lipschitz constant of the operator.

Parameters:

• method ("svd" | "trace") –

  • If svd, compute the optimal Lipschitz constant.

  • If trace, compute an upper bound. (Default)

• kwargs –

  Optional kwargs passed on to:

  • svd: svdvals()

  • trace: hutchpp()

Return type:

Real

Notes

• The tightest Lipschitz constant is given by the spectral norm of the operator \(\mathbf{A}\): \(\|\mathbf{A}\|_{2}\). It can be computed via the SVD, which is compute-intensive task for large operators. In this setting, it may be advantageous to overestimate the Lipschitz constant with the Frobenius norm of \(\mathbf{A}\) since \(\|\mathbf{A}\|_{F} \geq \|\mathbf{A}\|_{2}\).

  \(\|\mathbf{A}\|_{F}\) can be efficiently approximated by computing the trace of \(\mathbf{A}^{\ast} \mathbf{A}\) (or \(\mathbf{A}\mathbf{A}^{\ast}\)) via the Hutch++ stochastic algorithm.

• \(\|\mathbf{A}\|_{F}\) is upper-bounded by \(\|\mathbf{A}\|_{F} \leq \sqrt{n} \|\mathbf{A}\|_{2}\), where the equality is reached (worst-case scenario) when the eigenspectrum of the linear operator is flat.

svdvals(**kwargs)

Compute leading singular values of the linear operator.

Parameters:

• k (Integer) – Number of singular values to compute.

• gpu (bool) – If True the singular value decomposition is performed on the GPU.

• dtype (DType) – Working precision of the linear operator.

• kwargs (Mapping) – Additional kwargs accepted by svds().

Returns:

D – (k,) singular values in ascending order.

Return type:

NDArray

gram()

Gram operator \(\mathbf{A}^{\ast} \mathbf{A}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\).

Returns:

op – Gram operator.

Return type:

OpT

Note

By default the Gram is computed by the composition self.T * self. This may not be the fastest way to compute the Gram operator. If the Gram can be computed more efficiently (e.g. with a convolution), the user should re-define this method.

pinv(arr, damp, **kwargs)

Evaluate the Moore-Penrose pseudo-inverse \(\mathbf{A}^{\dagger}\) at specified point(s).

Parameters:

• arr (NDArray) – (…, N1,…,NK) input points.

• damp (Real) – Positive dampening factor regularizing the pseudo-inverse.

• kwargs_init (Mapping) – Optional kwargs to be passed to CG()’s __init__() method.

• kwargs_fit (Mapping) – Optional kwargs to be passed to CG()’s fit() method.

Returns:

out – (…, M1,…,MD) pseudo-inverse(s).

Return type:

NDArray

Notes

The Moore-Penrose pseudo-inverse of an operator \(\mathbf{A}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) is defined as the operator \(\mathbf{A}^{\dagger}: \mathbb{R}^{N_{1} \times\cdots\times N_{K}} \to \mathbb{R}^{M_{1} \times\cdots\times M_{D}}\) verifying the Moore-Penrose conditions:

1. \(\mathbf{A} \mathbf{A}^{\dagger} \mathbf{A} = \mathbf{A}\),

2. \(\mathbf{A}^{\dagger} \mathbf{A} \mathbf{A}^{\dagger} = \mathbf{A}^{\dagger}\),

3. \((\mathbf{A}^{\dagger} \mathbf{A})^{\ast} = \mathbf{A}^{\dagger} \mathbf{A}\),

4. \((\mathbf{A} \mathbf{A}^{\dagger})^{\ast} = \mathbf{A} \mathbf{A}^{\dagger}\).

This operator exists and is unique for any finite-dimensional linear operator. The action of the pseudo-inverse \(\mathbf{A}^{\dagger} \mathbf{y}\) for every \(\mathbf{y} \in \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) can be computed in matrix-free fashion by solving the normal equations:

\[\mathbf{A}^{\ast} \mathbf{A} \mathbf{x} = \mathbf{A}^{\ast} \mathbf{y} \quad\Leftrightarrow\quad \mathbf{x} = \mathbf{A}^{\dagger} \mathbf{y}, \quad \forall (\mathbf{x}, \mathbf{y}) \in \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \times \mathbb{R}^{N_{1} \times\cdots\times N_{K}}.\]

In the case of severe ill-conditioning, it is possible to consider the dampened normal equations for a numerically-stabler approximation of \(\mathbf{A}^{\dagger} \mathbf{y}\):

\[(\mathbf{A}^{\ast} \mathbf{A} + \tau I) \mathbf{x} = \mathbf{A}^{\ast} \mathbf{y},\]

where \(\tau > 0\) corresponds to the damp parameter.

dagger(damp, **kwargs)

Return the Moore-Penrose pseudo-inverse operator \(\mathbf{A}^\dagger\).

Parameters:

• damp (Real) – Positive dampening factor regularizing the pseudo-inverse.

• kwargs_init (Mapping) – Optional kwargs to be passed to CG()’s __init__() method.

• kwargs_fit (Mapping) – Optional kwargs to be passed to CG()’s fit() method.

Returns:

op – Moore-Penrose pseudo-inverse operator.

Return type:

OpT