API Reference#

Welcome to the official API reference for Pyxu. This API documentation is intended to serve as a comprehensive guide to the library’s various modules, classes, functions, and interfaces. It provides detailed descriptions of each component’s role, relations, assumptions, and behavior.

Please note that this API reference is not designed to be a tutorial; it’s a technical resource aimed at users who are already familiar with the library’s basics and wish to dive deeper into its functionalities.

Pyxu is broken down into the following top-level namespaces:

  • pyxu.abc: abstract base types and logic used throughout Pyxu.

  • pyxu.info.deps: array backend tools.

  • pyxu.info.ptype: type aliases for Python type checkers.

  • pyxu.info.warning: internal warnings.

  • pyxu.operator: operator collection.

  • pyxu.operator.interop: helpers to interface with external packages such as JAX, PyTorch, etc.

  • pyxu.opt.solver: solver collection.

  • pyxu.opt.stop: common stopping criteria.

  • pyxu.runtime: compute precision tools.

  • pyxu.math: math helpers.

  • pyxu.util: utility functions.

  • pyxu.experimental: experimental packages. These may change in the future without warning. Each sub-module under experimental must be imported individually:

    from pyxu.experimental.sampler import ULA

Individual Pyxu components should be imported from these top-level modules. Some low-level routines are not exposed from the former and must be imported explicitly:

from pyxu.operator import Sum  # top-level import
from pyxu.util.misc import peaks  # low-level import

The import path of each object can be inferred by looking at its canonical path in the alphabetical listings below.

pyxu.abc#

Arithmetic Rules (low-level)#

pyxu.abc.arithmetic.AddRule(lhs, rhs)

Arithmetic rules for operator addition: \(C(x) = A(x) + B(x)\).

pyxu.abc.arithmetic.ArgScaleRule(op, cst)

Arithmetic rules for element-wise parameter scaling: \(B(x) = A(\alpha x)\).

pyxu.abc.arithmetic.ArgShiftRule(op, cst)

Arithmetic rules for parameter shifting: \(B(x) = A(x + c)\).

pyxu.abc.arithmetic.ChainRule(lhs, rhs)

Arithmetic rules for operator composition: \(C(x) = (A \circ B)(x)\).

pyxu.abc.arithmetic.Rule()

General arithmetic rule.

pyxu.abc.arithmetic.ScaleRule(op, cst)

Arithmetic rules for element-wise scaling: \(B(x) = \alpha A(x)\).

pyxu.abc.arithmetic.TransposeRule(op)

Arithmetic rules for LinOp transposition: \(B(x) = A^{T}(x)\).

pyxu.experimental#

Sampling Tools#

MYULA([f, g, gamma, lamb])

Moreau-Yosida unajusted Langevin algorithm (MYULA).

OnlineCenteredMoment([order])

Pointwise online centered moment.

OnlineKurtosis()

Pointwise online kurtosis.

OnlineMoment([order])

Pointwise online moment.

OnlineSkewness()

Pointwise online skewness.

OnlineStd()

Pointwise online standard deviation.

OnlineVariance()

Pointwise online variance.

ULA(f[, gamma])

Unajusted Langevin algorithm (ULA).

pyxu.info.deps#

CUPY_ENABLED

Show if CuPy-based backends are available.

NDArrayInfo(value[, names, module, ...])

Supported dense array backends.

SparseArrayInfo(value[, names, module, ...])

Supported sparse array backends.

supported_array_modules()

List of all supported dense array modules in current Pyxu install.

supported_array_types()

List of all supported dense array types in current Pyxu install.

supported_sparse_modules()

List of all supported sparse array modules in current Pyxu install.

supported_sparse_types()

List of all supported sparse array types in current Pyxu install.

pyxu.info.ptype#

ArrayModule

Supported dense array modules.

DType

NDArray dtype specifier.

Integer

alias of Integral

NDArray

Supported dense array types.

NDArrayAxis

Axis/Axes specifier.

NDArrayShape

NDArray shape specifier.

OpC

Operator hierarchy class type.

OpT

Top-level abstract Operator interface exposed to users.

Path

Path-like object.

Property

Mathematical properties attached to Operator objects.

Real()

To Complex, Real adds the operations that work on real numbers.

SolverC

Solver hierarchy class type.

SolverM

Solver run-modes.

SolverT

Top-level abstract Solver interface exposed to users.

SparseArray

Type variable.

SparseModule

Type variable.

VarName

Variable name(s).

pyxu.info.warning#

AutoInferenceWarning

Use when a quantity was auto-inferenced with possible caveats.

BackendWarning

Inform user of a backend-specific problem to be aware of.

ContributionWarning

Use for warnings related to Pyxu plugins.

DenseWarning

Use for sparse-based algos which revert to dense arrays.

NonTransparentWarning

Inform test suite runner of (safe) non-transparent function call.

PerformanceWarning

Use for performance-related warnings.

PrecisionWarning

Use for precision-related warnings.

PyxuWarning

Parent class of all warnings raised in Pyxu.

pyxu.math#

backtracking_linesearch(f, x, direction[, ...])

Backtracking line search algorithm based on the Armijo-Goldstein condition.

hutchpp(op[, m, xp, dtype, seed])

Stochastic trace estimation of a linear operator based on the Hutch++ algorithm.

trace(op[, xp, dtype])

Exact trace of a linear operator based on multiple evaluation of the forward operator.

pyxu.operator.interop#

General#

from_source(cls, dim_shape, codim_shape[, ...])

Define an Operator from low-level constructs.

SciPy#

from_sciop(cls, sp_op)

Wrap a LinearOperator as a 2D LinOp (or sub-class thereof).

JAX#

_from_jax(x[, xp])

JAX -> NumPy/CuPy conversion.

_to_jax(x[, enable_warnings])

NumPy/CuPy -> JAX conversion.

from_jax(cls, dim_shape, codim_shape[, ...])

Define an Operator from JAX functions.

PyTorch#

_from_torch(tensor)

PyTorch -> NumPy/CuPy conversion.

_to_torch(arr[, requires_grad])

NumPy/CuPy -> PyTorch conversion.

from_torch(cls, dim_shape, codim_shape[, ...])

Define an Operator from PyTorch functions.

pyxu.operator#

Functionals#

Norms & Loss Functions#

KLDivergence(data)

Generalised Kullback-Leibler divergence \(D_{KL}(\mathbf{y}||\mathbf{x}) := \sum_{i} y_{i} \log(y_{i} / x_{i}) - y_{i} + x_{i}\).

L1Norm(dim_shape)

\(\ell_{1}\)-norm, \(\Vert\mathbf{x}\Vert_{1} := \sum_{i} |x_{i}|\).

L21Norm(dim_shape[, l2_axis])

Mixed \(\ell_{2}-\ell_{1}\) norm, \(\Vert\mathbf{x}\Vert_{2, 1} := \sum_{i} \sqrt{\sum_{j} x_{i, j}^{2}}\).

L2Norm(dim_shape)

\(\ell_{2}\)-norm, \(\Vert\mathbf{x}\Vert_{2} := \sqrt{\sum_{i} |x_{i}|^{2}}\).

LInfinityNorm(dim_shape)

\(\ell_{\infty}\)-norm, \(\Vert\mathbf{x}\Vert_{\infty} := \max_{i} |x_{i}|\).

PositiveL1Norm(dim_shape)

\(\ell_{1}\)-norm, with a positivity constraint.

SquaredL1Norm(dim_shape)

\(\ell^{2}_{1}\)-norm, \(\Vert\mathbf{x}\Vert^{2}_{1} := (\sum_{i} |x_{i}|)^{2}\).

SquaredL2Norm(dim_shape)

\(\ell^{2}_{2}\)-norm, \(\Vert\mathbf{x}\Vert^{2}_{2} := \sum_{i} |x_{i}|^{2}\).

Indicator Functions#

HyperSlab(a, lb, ub)

Indicator function of a hyperslab.

L1Ball(dim_shape[, radius])

Indicator function of the \(\ell_{1}\)-ball.

L2Ball(dim_shape[, radius])

Indicator function of the \(\ell_{2}\)-ball.

LInfinityBall(dim_shape[, radius])

Indicator function of the \(\ell_{\infty}\)-ball.

PositiveOrthant(dim_shape)

Indicator function of the positive orthant.

RangeSet(A)

Indicator function of a range set.

Linear Operators#

Basic Operators#

DiagonalOp(vec[, dim_shape, enable_warnings])

Element-wise scaling operator.

HomothetyOp(dim_shape, cst)

Constant scaling operator.

IdentityOp(dim_shape)

Identity operator.

NullFunc(dim_shape)

Null functional.

NullOp(dim_shape, codim_shape)

Null operator.

Pad(dim_shape, pad_width[, mode])

Multi-dimensional padding operator.

SubSample(dim_shape, *indices)

Multi-dimensional sub-sampling operator.

Sum(dim_shape[, axis])

Multi-dimensional sum reduction \(\mathbf{A}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{D}}\).

Trim(dim_shape, trim_width)

Multi-dimensional trimming operator.

Transforms#

FFT(dim_shape[, axes])

Multi-dimensional Discrete Fourier Transform (DFT) \(A: \mathbb{C}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{C}^{M_{1} \times\cdots\times M_{D}}\).

CZT(dim_shape, axes, M, A, W, **kwargs)

Multi-dimensional Chirp Z-Transform (CZT) \(C: \mathbb{C}^{N_{1} \times\cdots\times N_{D}} \to \mathbb{C}^{M_{1} \times\cdots\times M_{D}}\).

Stencils & Convolutions#

Convolve(dim_shape, kernel, center[, mode, ...])

Multi-dimensional JIT-compiled convolution.

Correlate

alias of Stencil

FFTConvolve(dim_shape, kernel, center[, ...])

Multi-dimensional FFT-based convolution.

FFTCorrelate(dim_shape, kernel, center[, ...])

Multi-dimensional FFT-based correlation.

Stencil(dim_shape, kernel, center[, mode, ...])

Multi-dimensional JIT-compiled stencil.

_Stencil(kernel, center)

Multi-dimensional JIT-compiled stencil.

Filters#

DifferenceOfGaussians(dim_shape[, ...])

Multi-dimensional Difference of Gaussians filter.

DoG(dim_shape[, low_sigma, high_sigma, ...])

Alias of DifferenceOfGaussians().

Gaussian(dim_shape)

Gaussian, element-wise.

Laplace(dim_shape[, mode, sampling, gpu, dtype])

Multi-dimensional Laplace filter.

MovingAverage(dim_shape, size[, center, ...])

Multi-dimensional moving average or uniform filter.

Prewitt(dim_shape[, axis, mode, sampling, ...])

Multi-dimensional Prewitt filter.

Scharr(dim_shape[, axis, mode, sampling, ...])

Multi-dimensional Scharr filter.

Sobel(dim_shape[, axis, mode, sampling, ...])

Multi-dimensional Sobel filter.

StructureTensor(dim_shape[, diff_method, ...])

Structure tensor operator.

Derivatives#

DirectionalDerivative(dim_shape, order, ...)

Directional derivative operator.

DirectionalGradient(dim_shape, directions[, ...])

Directional gradient operator.

DirectionalHessian(dim_shape, directions[, ...])

Directional Hessian operator.

DirectionalLaplacian(dim_shape, directions)

Directional Laplacian operator.

Divergence(dim_shape[, directions, ...])

Divergence operator.

Gradient(dim_shape[, directions, ...])

Gradient operator.

Hessian(dim_shape[, directions, ...])

Hessian operator.

Jacobian(dim_shape[, directions, ...])

Jacobian operator.

Laplacian(dim_shape[, directions, ...])

Laplacian operator.

PartialDerivative()

Partial derivative operator based on Numba stencils.

Tensor Products#

khatri_rao(A, B)

Column-wise Khatri-Rao product \(A \circ B\) between two linear operators.

kron(A, B)

Kronecker product \(A \otimes B\) between two linear operators.

Misc#

BroadcastAxes(dim_shape, codim_shape)

Broadcast an array.

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}}\).

RechunkAxes(dim_shape, chunks)

Re-chunk core dimensions to new chunk size.

ReshapeAxes(dim_shape, codim_shape)

Reshape an array.

SqueezeAxes(dim_shape[, axes])

Remove axes of length one.

TransposeAxes(dim_shape[, axes])

Reverse or permute the axes of an array.

Block-defined Operators#

block_diag(ops)

Zip operators over parallel inputs.

stack(ops)

Map operators over the same input.

Element-wise Operators#

Abs(dim_shape)

Absolute value, element-wise.

ArcCos(dim_shape)

Inverse cosine, element-wise.

ArcCosh(dim_shape)

Inverse hyperbolic cosine, element-wise.

ArcSin(dim_shape)

Inverse sine, element-wise.

ArcSinh(dim_shape)

Inverse hyperbolic sine, element-wise.

ArcTan(dim_shape)

Inverse tangent, element-wise.

ArcTanh(dim_shape)

Inverse hyperbolic tangent, element-wise.

Cbrt(dim_shape)

Cube-root, element-wise.

Clip(dim_shape[, a_min, a_max])

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

Cos(dim_shape)

Trigonometric cosine, element-wise.

Cosh(dim_shape)

Hyperbolic cosine, element-wise.

Exp(dim_shape[, base])

Exponential, element-wise.

Gaussian(dim_shape)

Gaussian, element-wise.

LeakyReLU(dim_shape, alpha)

Leaky rectified linear unit, element-wise.

Log(dim_shape[, base])

Logarithm, element-wise.

ReLU(dim_shape)

Rectified linear unit, element-wise.

Sigmoid(dim_shape)

Sigmoid, element-wise.

Sign(dim_shape)

Number sign indicator, element-wise.

SiLU(dim_shape)

Sigmoid linear unit, element-wise.

Sin(dim_shape)

Trigonometric sine, element-wise.

Sinh(dim_shape)

Hyperbolic sine, element-wise.

SoftPlus(dim_shape)

Softplus operator.

Sqrt(dim_shape)

Non-negative square-root, element-wise.

Square(dim_shape)

Square, element-wise.

Tan(dim_shape)

Trigonometric tangent, element-wise.

Tanh(dim_shape)

Hyperbolic tangent, element-wise.

pyxu.opt.solver#

Adam(f, **kwargs)

Adam solver [ProxAdam].

ADMM([f, h, K, solver, solver_kwargs])

Alternating Direction Method of Multipliers.

CG(A, **kwargs)

Conjugate Gradient Method.

ChambollePock([g, h, K, base])

Chambolle-Pock primal-dual splitting method.

CondatVu([f, g, h, K])

Condat-Vu primal-dual splitting algorithm.

CP([g, h, K, base])

Alias of ChambollePock().

CV

alias of CondatVu

DavisYin(f[, g, h])

Davis-Yin primal-dual splitting method.

DouglasRachford([g, h, base])

Douglas-Rachford splitting algorithm.

DR([g, h, base])

Alias of DouglasRachford().

DY

alias of DavisYin

FB

alias of ForwardBackward

ForwardBackward([f, g])

Forward-backward splitting algorithm.

LorisVerhoeven([f, h, K])

Loris-Verhoeven splitting algorithm.

LV

alias of LorisVerhoeven

NLCG(f, **kwargs)

Nonlinear Conjugate Gradient Method (NLCG).

PD3O([f, g, h, K])

Primal-Dual Three-Operator Splitting (PD3O) algorithm.

PGD([f, g])

Proximal Gradient Descent (PGD) solver.

PP([g, base])

Alias of ProximalPoint().

ProximalPoint([g, base])

Proximal-point method.

pyxu.opt.stop#

AbsError(eps[, var, rank, f, norm, satisfy_all])

Stop iterative solver after absolute norm of a variable (or function thereof) reaches threshold.

ManualStop()

Continue-forever criterion.

MaxDuration(t)

Stop iterative solver after a specified duration has elapsed.

MaxIter(n)

Stop iterative solver after a fixed number of iterations.

Memorize(var)

Memorize a variable.

RelError(eps[, var, rank, f, norm, satisfy_all])

Stop iterative solver after relative norm change of a variable (or function thereof) reaches threshold.

pyxu.runtime#

CWidth(value[, names, module, qualname, ...])

Machine-dependent complex-valued floating-point types.

Width(value[, names, module, qualname, ...])

Machine-dependent floating-point types.

pyxu.util#

Complex Number Handling#

as_real_op(A[, dim_rank])

View complex-valued linear operator as its real-valued equivalent.

require_viewable(x)

Copy array if required to do real/complex view manipulations.

view_as_complex(x)

View real-valued array as its complex-valued bijection.

view_as_real(x)

View complex-valued array as its real-valued bijection.

Operator-Related#

as_canonical_axes(axes, rank)

Transform NDarray axes into tuple-form with positive indices.

as_canonical_shape(x)

Transform a lone integer into a valid tuple-based shape specifier.

vectorize(i, dim_shape, codim_shape)

Decorator to auto-vectorize a function \(\mathbf{f}: \mathbb{R}^{M_{1} \times\cdots\times M_{D}} \to \mathbb{R}^{N_{1} \times\cdots\times N_{K}}\) to accept stacking dimensions.

Misc#

copy_if_unsafe(x)

Copy array if it is unsafe to do in-place updates on it.

import_module(name[, fail_on_error])

Load a Python module dynamically.

parse_params(func, *args, **kwargs)

Get function parameterization.

read_only(x)

Make an array read-only.

Low-lever Helpers

pyxu.util.misc.peaks(x, y)

Matlab 2D peaks function.

pyxu.util.misc.star_like_sample(N, w, s, po, x0)

Star-like test image.