diff --git a/WARNINGS.log b/WARNINGS.log index f5145c5a..5023df83 100644 --- a/WARNINGS.log +++ b/WARNINGS.log @@ -1,4 +1,64 @@ -/Users/mmjasime/Documents/Github/pyxu/doc/guide/lipschitz.ipynb:286: WARNING: invalid syntax (, line 24) in document 'guide/lipschitz' +/home/sep/Documents/Repositories/pyxu/doc/fair/howto.rst:2: WARNING: Duplicate explicit target name: "catalogue website". +/home/sep/Documents/Repositories/pyxu/doc/fair/howto.rst:33: WARNING: invalid syntax (, line 2) in document 'fair/howto' +Parsed source in `python` block: +concatenations: from pyxu.opt.solver import GradientDescent +block source: ModuleNotFoundError: No module named 'pyxu.opt.solver.GradientDescent' +/home/sep/Documents/Repositories/pyxu/doc/fair/plugins/pyxu-eigh.rst:164: ERROR: Content block expected for the "raw" directive; none found. +/home/sep/Documents/Repositories/pyxu/doc/fair/plugins/pyxu-gradient-descent.rst:164: ERROR: Content block expected for the "raw" directive; none found. +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:129: WARNING: Title underline too short. + +Implicit Functionals: The Undercover Agents 🕵️‍♀️ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:129: WARNING: Title underline too short. + +Implicit Functionals: The Undercover Agents 🕵️‍♀️ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:27: WARNING: File not found: 'api/operator.interop.html#general' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:27: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.apply' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:27: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffFunc.grad' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:27: WARNING: File not found: 'api/abc.html#pyxu.abc.ProxFunc.prox' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:34: WARNING: File not found: 'api/abc.html#pyxu.abc.Func' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:61: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffFunc' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:76: WARNING: File not found: 'api/operator.interop.html#pyxu.operator.interop.from_torch' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:76: WARNING: File not found: 'api/operator.interop.html#pyxu.operator.interop.from_jax' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:81: WARNING: File not found: 'api/abc.html#pyxu.abc.ProxFunc' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:97: WARNING: File not found: 'api/abc.html#pyxu.abc.ProxFunc.moreau_envelope' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:124: WARNING: File not found: 'api/abc.html#pyxu.abc.ProxDiffFunc' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:124: WARNING: File not found: 'api/abc.html#pyxu.abc.LinFunc' +/home/sep/Documents/Repositories/pyxu/doc/guide/funcs.ipynb:124: WARNING: File not found: 'api/abc.html#pyxu.abc.QuadraticFunc' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:11: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:17: WARNING: File not found: 'api/operator.interop.html#general' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:17: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.apply' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:17: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp.adjoint' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:17: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap.jacobian' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:46: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:55: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.apply' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:66: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp.adjoint' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:100: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:102: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.lipschitz' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:102: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.estimate_lipschitz' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:108: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp.svdvals' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:110: WARNING: File not found: 'api/abc.html#pyxu.abc.SquareOp.trace' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:112: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp.pinv' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:118: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:118: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp.from_array' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:124: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:129: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:134: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.apply' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:134: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:136: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap.jacobian' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:146: WARNING: File not found: 'api/operator.interop.html#pyxu.operator.interop.from_torch' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:146: WARNING: File not found: 'api/operator.interop.html#pyxu.operator.interop.from_jax' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:148: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:153: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp' +/home/sep/Documents/Repositories/pyxu/doc/guide/fwdops.ipynb:153: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap' +/home/sep/Documents/Repositories/pyxu/doc/guide/hpc.ipynb:219: WARNING: File not found: 'api/runtime.html#pyxu.runtime.Precision' +/home/sep/Documents/Repositories/pyxu/doc/guide/lipschitz.ipynb:30: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.lipschitz' +/home/sep/Documents/Repositories/pyxu/doc/guide/lipschitz.ipynb:30: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap.diff_lipschitz' +/home/sep/Documents/Repositories/pyxu/doc/guide/lipschitz.ipynb:40: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.estimate_lipschitz' +/home/sep/Documents/Repositories/pyxu/doc/guide/lipschitz.ipynb:298: WARNING: File not found: 'api/index.html' +/home/sep/Documents/Repositories/pyxu/doc/guide/lipschitz.ipynb:298: WARNING: File not found: 'api/abc/arithmetic.html#' +/home/sep/Documents/Repositories/pyxu/doc/guide/lipschitz.ipynb:286: WARNING: invalid syntax (, line 24) in document 'guide/lipschitz' Parsed source in `python` block: concatenations: # Access Lipschitz constant of an operator 'op' lip_const = op.lipschitz @@ -32,21 +92,95 @@ block source: >> op1 = difffunc * linop; >> op2.diff_lipschitz == linop.lipschitz * diffmap.diff_lipschitz True ... -/Users/mmjasime/Documents/Github/pyxu/doc/fair/howto.rst:2: WARNING: Duplicate explicit target name: "catalogue website". -/Users/mmjasime/Documents/Github/pyxu/doc/fair/howto.rst:33: WARNING: invalid syntax (, line 2) in document 'fair/howto' +/home/sep/Documents/Repositories/pyxu/doc/examples/contributing.ipynb:42: WARNING: invalid syntax (, line 5) in document 'examples/contributing' Parsed source in `python` block: -concatenations: import pyxu.opt.solver.GradientDescent -block source: ModuleNotFoundError: No module named 'pyxu.opt.solver.GradientDescent' -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:640: ERROR: Unexpected indentation. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:638: WARNING: Inline interpreted text or phrase reference start-string without end-string. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:644: WARNING: Block quote ends without a blank line; unexpected unindent. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:653: WARNING: Inline interpreted text or phrase reference start-string without end-string. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:655: WARNING: Definition list ends without a blank line; unexpected unindent. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:765: ERROR: Unexpected indentation. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:763: WARNING: Inline interpreted text or phrase reference start-string without end-string. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:768: WARNING: Block quote ends without a blank line; unexpected unindent. -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:109: WARNING: File not found: 'examples/TODO' -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:156: WARNING: expected ':' (, line 29) in document 'examples/DifferentialOperators' +concatenations: try: + from pyxu.opt.solver import GradientDescent +except ImportError as e: + print(e) +block source: !pip install pyxu-gradient-descent +/home/sep/Documents/Repositories/pyxu/doc/fair/score.rst:29: WARNING: Bullet list ends without a blank line; unexpected unindent. +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:33: WARNING: File not found: 'api/abc.html#pyxu.abc.Map.apply' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:33: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap.jacobian' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:33: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffFunc.grad' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:33: WARNING: File not found: 'api/abc.html#pyxu.abc.ProxFunc.prox' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:33: WARNING: File not found: 'api/abc.html#pyxu.abc.LinOp.adjoint' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:39: WARNING: File not found: 'api/abc/arithmetic.html' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:41: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.Rule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:42: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.ScaleRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:43: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.ArgScaleRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:44: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.ArgShiftRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:45: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.AddRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:46: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.ChainRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:47: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.PowerRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:48: WARNING: File not found: 'api/abc.html#pyxu.abc.arithmetic.TransposeRule' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:53: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffFunc' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:53: WARNING: File not found: 'api/abc.html#pyxu.abc.DiffMap' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:95: WARNING: File not found: 'api/operator/blocks.html#pyxu.operator.coo_block' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:95: WARNING: File not found: 'api/operator/blocks.html#pyxu.operator.block' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:95: WARNING: File not found: 'api/operator/blocks.html#pyxu.operator.block_diag' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:95: WARNING: File not found: 'api/operator/blocks.html#pyxu.operator.stack' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:95: WARNING: File not found: 'api/operator/blocks.html#pyxu.operator.vstack' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:95: WARNING: File not found: 'api/operator/blocks.html#pyxu.operator.hstack' +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:18: WARNING: invalid syntax (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: >> op1 + op2 # Addition of two operators + >> op1 * op2 # Composition of two operators + >> op ** 3 # Exponentiation of an operator + >> op.argscale(c) # Dilation by a scalar 'c' + >> op.argshift(x) # Shifting by a vector 'x' + >> 4 * op # Scaling by a scalar + >> op.T # Transposing +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:55: WARNING: invalid syntax (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: >> h = f * L + >> h.grad(x) = L.jacobian(x).adjoint(f.grad(L(x))) +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:64: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: op.apply(arr) = lhs.apply(rhs.apply(arr)) + op.lipschitz = lhs.lipschitz * rhs.lipschitz +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:71: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: op.prox(arr, tau) = rhs.adjoint(lhs.prox(rhs.apply(arr), tau)) +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:77: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: op.jacobian(arr) = lhs.jacobian(rhs.apply(arr)) * rhs.jacobian(arr) + op.diff_lipschitz = + linear * linear => 0 + linear * diff => lhs.lipschitz * rhs.diff_lipschitz + diff * linear => lhs.diff_lipschitz * (rhs.lipschitz ** 2) + diff * diff => infty +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:88: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: op.grad(arr) = lhs.grad(rhs.apply(arr)) @ rhs.jacobian(arr).asarray() +/home/sep/Documents/Repositories/pyxu/doc/guide/algebra.ipynb:100: WARNING: invalid syntax (, line 1) in document 'guide/algebra' +Parsed source in `python` block: +block source: >> coo_block(([A(500,1000), B(1,1000), C(500,500), D(1,3)], # data + ... [[0, 1, 0, 2], # i + ... [0, 0, 2, 1], # j + ]),grid_shape=(3, 3)) +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:17: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.CG' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:29: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.PGD' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:58: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.CondatVu' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:58: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.PD3O' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:58: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.ADMM' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:58: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.ChambollePock' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:74: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.DouglasRachford' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:76: WARNING: File not found: 'api/opt.solver.html#pyxu.opt.solver.Adam' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:127: WARNING: File not found: 'api/opt.stop.html' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:144: WARNING: File not found: 'api/abc.html#pyxu.abc.Solver' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:144: WARNING: File not found: 'api/abc.html#pyxu.abc.Solver.m_init' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:144: WARNING: File not found: 'api/abc.html#pyxu.abc.Solver.m_step' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:148: WARNING: File not found: 'api/abc.html#pyxu.abc.Solver.fit' +/home/sep/Documents/Repositories/pyxu/doc/guide/algorithms.ipynb:66: WARNING: invalid syntax (, line 1) in document 'guide/algorithms' +Parsed source in `python` block: +block source: >> K = vstack([K_1, ..., K_J]) + >> H = hstack([h_1, ..., h_J]) +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:11: WARNING: File not found: 'api/operator/linop.html#derivatives' +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:18: WARNING: File not found: 'api/operator/linop.html#pyxu.operator.PartialDerivative' +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:535: WARNING: File not found: 'api/operator/linop.html#pyxu.operator.Gradient' +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:545: WARNING: File not found: 'api/operator/linop.html#pyxu.operator.Hessian' +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:93: WARNING: expected an indented block after function definition on line 20 (, line 29) in document 'guide/diff_ops' Parsed source in `python` block: concatenations: def D(f): """ @@ -76,8 +210,8 @@ block source: def finite_difference( gpu: bool = False, dtype: typ.Optional[pyct.DType] = None, sampling: typ.Union[pyct.Real, cabc.Sequence[pyct.Real, ...]] = 1, - ) -> pyct.OpT -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:171: WARNING: expected ':' (, line 29) in document 'examples/DifferentialOperators' + ) -> pyct.OpT: +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:107: WARNING: expected an indented block after function definition on line 20 (, line 29) in document 'guide/diff_ops' Parsed source in `python` block: concatenations: def D(f): """ @@ -107,8 +241,8 @@ block source: def gaussian_derivative( gpu: bool = False, dtype: typ.Optional[pyct.DType] = None, sampling: typ.Union[pyct.Real, cabc.Sequence[pyct.Real, ...]] = 1, - ) -> pyct.OpT -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:680: WARNING: expected an indented block after function definition on line 139 (, line 148) in document 'examples/DifferentialOperators' + ) -> pyct.OpT: +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:579: WARNING: expected an indented block after function definition on line 139 (, line 148) in document 'guide/diff_ops' Parsed source in `python` block: concatenations: def D(f): """ @@ -258,7 +392,7 @@ block source: def Gradient( parallel: bool = False, **diff_kwargs, ) -> pyct.OpT: -/Users/mmjasime/Documents/Github/pyxu/doc/examples/DifferentialOperators.ipynb:694: WARNING: expected an indented block after function definition on line 139 (, line 152) in document 'examples/DifferentialOperators' +/home/sep/Documents/Repositories/pyxu/doc/guide/diff_ops.ipynb:593: WARNING: expected an indented block after function definition on line 139 (, line 152) in document 'guide/diff_ops' Parsed source in `python` block: concatenations: def D(f): """ @@ -412,63 +546,19 @@ block source: def Hessian( parallel: bool = False, **diff_kwargs, ) -> pyct.OpT: -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:18: WARNING: invalid syntax (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: >> op1 + op2 # Addition of two operators - >> op1 * op2 # Composition of two operators - >> op ** 3 # Exponentiation of an operator - >> op.argscale(c) # Dilation by a scalar 'c' - >> op.argshift(x) # Shifting by a vector 'x' - >> 4 * op # Scaling by a scalar - >> op.T # Transposing -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:54: WARNING: invalid syntax (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: >> h = f * L - >> h.grad(x) = L.jacobian(x).adjoint(f.grad(L(x))) -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:63: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: op.apply(arr) = lhs.apply(rhs.apply(arr)) - op.lipschitz = lhs.lipschitz * rhs.lipschitz -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:70: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: op.prox(arr, tau) = rhs.adjoint(lhs.prox(rhs.apply(arr), tau)) -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:76: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: op.jacobian(arr) = lhs.jacobian(rhs.apply(arr)) * rhs.jacobian(arr) - op.diff_lipschitz = - linear * linear => 0 - linear * diff => lhs.lipschitz * rhs.diff_lipschitz - diff * linear => lhs.diff_lipschitz * (rhs.lipschitz ** 2) - diff * diff => infty -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:87: WARNING: cannot assign to function call here. Maybe you meant '==' instead of '='? (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: op.grad(arr) = lhs.grad(rhs.apply(arr)) @ rhs.jacobian(arr).asarray() -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algebra.ipynb:98: WARNING: invalid syntax (, line 1) in document 'guide/algebra' -Parsed source in `python` block: -block source: >> coo_block(([A(500,1000), B(1,1000), C(500,500), D(1,3)], # data - ... [[0, 1, 0, 2], # i - ... [0, 0, 2, 1], # j - ]),grid_shape=(3, 3)) -/Users/mmjasime/Documents/Github/pyxu/doc/guide/algorithms.ipynb:66: WARNING: invalid syntax (, line 1) in document 'guide/algorithms' -Parsed source in `python` block: -block source: >> K = vstack([K_1, ..., K_J]) - >> H = hstack([h_1, ..., h_J]) -/Users/mmjasime/Documents/Github/pyxu/doc/guide/funcs.ipynb:129: WARNING: Title underline too short. - -Implicit Functionals: The Undercover Agents 🕵️‍♀️ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -/Users/mmjasime/Documents/Github/pyxu/doc/guide/funcs.ipynb:129: WARNING: Title underline too short. - -Implicit Functionals: The Undercover Agents 🕵️‍♀️ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/interop/jax.py:docstring of pyxu.operator.interop.jax._from_jax:: WARNING: py:class reference target not found: pyxu.operator.interop.jax.JaxArray -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/interop/jax.py:docstring of pyxu.operator.interop.jax._to_jax:: WARNING: py:class reference target not found: pyxu.operator.interop.jax.JaxArray -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/blocks.py:docstring of pyxu.operator.blocks.coo_block:33: WARNING: py:mod reference target not found: pyxu.operator.blocks -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/pad.py:docstring of pyxu.operator.linop.pad.Pad.__init__:10: WARNING: py:class reference target not found: pyxu.operator.linop.pad.Pad.WidthSpec -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/filter.py:docstring of pyxu.operator.linop.filter.MovingAverage:30: WARNING: py:class reference target not found: pyxu.operator.linop.filter.IndexSpec -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: (Integer -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: Integer) -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: ((Integer -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: Integer) -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: (Integer -/Users/mmjasime/Documents/Github/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: Integer)) +/home/sep/Documents/Repositories/pyxu/doc/references.rst:5: WARNING: Citation [ProxAlg] is not referenced. +/home/sep/Documents/Repositories/pyxu/doc/references.rst:8: WARNING: Citation [ProxSplit] is not referenced. +/home/sep/Documents/Repositories/pyxu/doc/references.rst:19: WARNING: Citation [P2] is not referenced. +/home/sep/Documents/Repositories/pyxu/doc/references.rst:20: WARNING: Citation [GaussProcesses] is not referenced. +/home/sep/Documents/Repositories/pyxu/doc/references.rst:21: WARNING: Citation [SubGauss] is not referenced. +/home/sep/Documents/Repositories/pyxu/doc/references.rst:29: WARNING: Citation [UQ_MCMC] is not referenced. +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/blocks.py:docstring of pyxu.operator.blocks.coo_block:33: WARNING: py:mod reference target not found: pyxu.operator.blocks +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/pad.py:docstring of pyxu.operator.linop.pad.Pad.__init__:10: WARNING: py:class reference target not found: pyxu.operator.linop.pad.Pad.WidthSpec +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/filter.py:docstring of pyxu.operator.linop.filter.MovingAverage:30: WARNING: py:class reference target not found: pyxu.operator.linop.filter.IndexSpec +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: (Integer +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: Integer) +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: ((Integer +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: Integer) +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: (Integer +/home/sep/Documents/Repositories/pyxu/src/pyxu/operator/linop/diff.py:docstring of pyxu.operator.linop.diff.Hessian:65: WARNING: py:class reference target not found: Integer)) +/home/sep/Documents/Repositories/pyxu/doc/examples/contributing.ipynb:42: WARNING: Lexing literal_block '!pip install pyxu-gradient-descent' as "python" resulted in an error at token: '!'. Retrying in relaxed mode. diff --git a/_downloads/.DS_Store b/_downloads/.DS_Store deleted file mode 100644 index 9677c7d8..00000000 Binary files a/_downloads/.DS_Store and /dev/null differ diff --git a/_downloads/001882fa6559d942c582faa9cb948f03/operator-16.png b/_downloads/001882fa6559d942c582faa9cb948f03/operator-16.png deleted file mode 100644 index 0a0e3de5..00000000 Binary files a/_downloads/001882fa6559d942c582faa9cb948f03/operator-16.png and /dev/null differ diff --git a/_downloads/00a03ca7daa38b33580314c7f5f51dcb/operator-12_00.hires.png b/_downloads/00a03ca7daa38b33580314c7f5f51dcb/operator-12_00.hires.png deleted file mode 100644 index 4775db44..00000000 Binary files a/_downloads/00a03ca7daa38b33580314c7f5f51dcb/operator-12_00.hires.png and /dev/null differ diff --git a/_downloads/01d31b53f3906f9c7594bb738943953e/linop-4_01.pdf b/_downloads/01d31b53f3906f9c7594bb738943953e/linop-4_01.pdf deleted file mode 100644 index dfec4ce2..00000000 Binary files a/_downloads/01d31b53f3906f9c7594bb738943953e/linop-4_01.pdf and /dev/null differ diff --git a/_downloads/027b1d95119170b929f57668d02810ce/operator-10.png b/_downloads/027b1d95119170b929f57668d02810ce/operator-10.png deleted file mode 100644 index 9df02f1e..00000000 Binary files a/_downloads/027b1d95119170b929f57668d02810ce/operator-10.png and /dev/null differ diff --git a/_downloads/056a52abc2bba483fc2b1a564d9714ff/linop-13_00.hires.png b/_downloads/056a52abc2bba483fc2b1a564d9714ff/linop-13_00.hires.png deleted file mode 100644 index 4d5d2c76..00000000 Binary files a/_downloads/056a52abc2bba483fc2b1a564d9714ff/linop-13_00.hires.png and /dev/null differ diff --git a/_downloads/070f6a163480e1040e23b47cc06445ff/experimental-1_00_00.hires.png b/_downloads/070f6a163480e1040e23b47cc06445ff/experimental-1_00_00.hires.png deleted file mode 100644 index 846e1b51..00000000 Binary files a/_downloads/070f6a163480e1040e23b47cc06445ff/experimental-1_00_00.hires.png and /dev/null differ diff --git a/_downloads/08c11a4f54d6a5f6b338299631747747/operator-17.hires.png b/_downloads/08c11a4f54d6a5f6b338299631747747/operator-17.hires.png deleted file mode 100644 index 6156a608..00000000 Binary files a/_downloads/08c11a4f54d6a5f6b338299631747747/operator-17.hires.png and /dev/null differ diff --git a/_downloads/09786f40eba03e70a1bcdf11579b8e69/linop-20.hires.png b/_downloads/09786f40eba03e70a1bcdf11579b8e69/linop-20.hires.png deleted file mode 100644 index fe395c67..00000000 Binary files a/_downloads/09786f40eba03e70a1bcdf11579b8e69/linop-20.hires.png and /dev/null differ diff --git a/_downloads/09b83b84e67dd3bf3bfa9889ef5464d2/linop-5.pdf b/_downloads/09b83b84e67dd3bf3bfa9889ef5464d2/linop-5.pdf index 2e60c859..f17bc305 100644 Binary files a/_downloads/09b83b84e67dd3bf3bfa9889ef5464d2/linop-5.pdf and b/_downloads/09b83b84e67dd3bf3bfa9889ef5464d2/linop-5.pdf differ diff --git a/_downloads/0c27d2285c5e9a51cef246afff3163ad/operator-4_00.hires.png b/_downloads/0c27d2285c5e9a51cef246afff3163ad/operator-4_00.hires.png deleted file mode 100644 index e0f5bc76..00000000 Binary files a/_downloads/0c27d2285c5e9a51cef246afff3163ad/operator-4_00.hires.png and /dev/null differ diff --git a/_downloads/0e4825835a3d6d1b8ed46f992d78d573/linop-3_00.pdf b/_downloads/0e4825835a3d6d1b8ed46f992d78d573/linop-3_00.pdf deleted file mode 100644 index 28c9817f..00000000 Binary files a/_downloads/0e4825835a3d6d1b8ed46f992d78d573/linop-3_00.pdf and /dev/null differ diff --git a/_downloads/0f251ac595e8816e9c76523c2acfad07/linop-13_01.png b/_downloads/0f251ac595e8816e9c76523c2acfad07/linop-13_01.png deleted file mode 100644 index df404bc2..00000000 Binary files a/_downloads/0f251ac595e8816e9c76523c2acfad07/linop-13_01.png and /dev/null differ diff --git a/_downloads/0f65a5f8726612599305eeb053b028a0/linop-13_01.pdf b/_downloads/0f65a5f8726612599305eeb053b028a0/linop-13_01.pdf deleted file mode 100644 index de9d8df4..00000000 Binary files a/_downloads/0f65a5f8726612599305eeb053b028a0/linop-13_01.pdf and /dev/null differ diff --git a/_downloads/129c00df1a520657bba17d5d67553f10/operator-21_01.pdf b/_downloads/129c00df1a520657bba17d5d67553f10/operator-21_01.pdf deleted file mode 100644 index 93bf5e58..00000000 Binary files a/_downloads/129c00df1a520657bba17d5d67553f10/operator-21_01.pdf and /dev/null differ diff --git a/_downloads/157c6163c0348ead39d6ceb2a1fd7fbe/linop-11_02.hires.png b/_downloads/157c6163c0348ead39d6ceb2a1fd7fbe/linop-11_02.hires.png deleted file mode 100644 index c6b1db43..00000000 Binary files a/_downloads/157c6163c0348ead39d6ceb2a1fd7fbe/linop-11_02.hires.png and /dev/null differ diff --git a/_downloads/1702b305e1cb9e54e7738ebc64606e50/linop-11_01.hires.png b/_downloads/1702b305e1cb9e54e7738ebc64606e50/linop-11_01.hires.png index fb6eebf1..d5b90890 100644 Binary files a/_downloads/1702b305e1cb9e54e7738ebc64606e50/linop-11_01.hires.png and b/_downloads/1702b305e1cb9e54e7738ebc64606e50/linop-11_01.hires.png differ diff --git a/_downloads/176694d4afd8c703e2f166119010b4a5/operator-12.py b/_downloads/176694d4afd8c703e2f166119010b4a5/operator-12.py deleted file mode 100644 index 8a895bdc..00000000 --- a/_downloads/176694d4afd8c703e2f166119010b4a5/operator-12.py +++ /dev/null @@ -1,27 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import DirectionalLaplacian -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -z = peaks(xx, yy) -directions1 = np.zeros(shape=(2, z.size)) -directions1[0, :z.size // 2] = 1 -directions1[1, z.size // 2:] = 1 -directions2 = np.zeros(shape=(2, z.size)) -directions2[1, :z.size // 2] = -1 -directions2[0, z.size // 2:] = -1 -arg_shape = z.shape -dop = DirectionalLaplacian(arg_shape=arg_shape, directions=[directions1, directions2]) -out = dop.unravel(dop(z.ravel())) -plt.figure() -h = plt.pcolormesh(xx, yy, z, shading='auto') -plt.quiver(x, x, directions1[1].reshape(arg_shape), directions1[0].reshape(xx.shape)) -plt.quiver(x, x, directions2[1].reshape(arg_shape), directions2[0].reshape(xx.shape), color='red') -plt.colorbar(h) -plt.title('Signal and directions of derivatives') -plt.figure() -h = plt.pcolormesh(xx, yy, out.squeeze(), shading='auto') -plt.colorbar(h) -plt.title('Directional Laplacian') \ No newline at end of file diff --git a/_downloads/17ea64344184b13eb3942803c2022ec7/linop-9.pdf b/_downloads/17ea64344184b13eb3942803c2022ec7/linop-9.pdf index ce8e9671..f154ca06 100644 Binary files a/_downloads/17ea64344184b13eb3942803c2022ec7/linop-9.pdf and b/_downloads/17ea64344184b13eb3942803c2022ec7/linop-9.pdf differ diff --git a/_downloads/191962a7e06446281208e5b3542ba6d8/operator-13_02.png b/_downloads/191962a7e06446281208e5b3542ba6d8/operator-13_02.png deleted file mode 100644 index d66751f8..00000000 Binary files a/_downloads/191962a7e06446281208e5b3542ba6d8/operator-13_02.png and /dev/null differ diff --git a/_downloads/1afb1ff7f88d33f9d3bf15c2560c74ef/linop-11_01.png b/_downloads/1afb1ff7f88d33f9d3bf15c2560c74ef/linop-11_01.png index 23895dd6..1e266f6f 100644 Binary files a/_downloads/1afb1ff7f88d33f9d3bf15c2560c74ef/linop-11_01.png and b/_downloads/1afb1ff7f88d33f9d3bf15c2560c74ef/linop-11_01.png differ diff --git a/_downloads/1b73e81f624aaa2edc92c239025b33b2/operator-2.pdf b/_downloads/1b73e81f624aaa2edc92c239025b33b2/operator-2.pdf deleted file mode 100644 index abea4912..00000000 Binary files a/_downloads/1b73e81f624aaa2edc92c239025b33b2/operator-2.pdf and /dev/null differ diff --git a/_downloads/1cd8e614728fc68270743fa172a043f0/linop-11_00.pdf b/_downloads/1cd8e614728fc68270743fa172a043f0/linop-11_00.pdf index b3e56e61..79b548cb 100644 Binary files a/_downloads/1cd8e614728fc68270743fa172a043f0/linop-11_00.pdf and b/_downloads/1cd8e614728fc68270743fa172a043f0/linop-11_00.pdf differ diff --git a/_downloads/1e56b08165a1aaab1d61109119a49a7f/opt-2.py b/_downloads/1e56b08165a1aaab1d61109119a49a7f/opt-2.py deleted file mode 100644 index 50219928..00000000 --- a/_downloads/1e56b08165a1aaab1d61109119a49a7f/opt-2.py +++ /dev/null @@ -1,31 +0,0 @@ -import matplotlib.pyplot as plt -import numpy as np -import pyxu.operator as pxo -from pyxu.experimental._dev import DownSampling, FirstDerivative -from pyxu.opt.solver import PD3O - -x = np.repeat(np.asarray([0, 2, 1, 3, 0, 2, 0]), 10) -N = x.size - -D = FirstDerivative(size=N, kind="forward") -D.lipschitz = D.estimate_lipschitz() - -downsample = DownSampling(size=N, downsampling_factor=3) -y = downsample(x) -loss = (1 / 2) * pxo.SquaredL2Norm(y.size).argshift(-y) -F = loss * downsample -F.diff_lipschitz = F.estimate_diff_lipschitz() - -pd3o = PD3O(f=F, g=0.01 * pxo.L1Norm(N), h=0.1 * pxo.L1Norm(N), K=D) -x0, z0 = np.zeros((2, N)) -pd3o.fit(x0=x0, z0=z0) -x_recons = pd3o.solution()[0] - -plt.figure() -plt.stem(x, linefmt="C0-", markerfmt="C0o") -mask_ids = np.where(downsample.downsampling_mask)[0] -markerline, stemlines, baseline = plt.stem(mask_ids, y, linefmt="C3-", markerfmt="C3o") -markerline.set_markerfacecolor("none") -plt.stem(x_recons, linefmt="C1--", markerfmt="C1s") -plt.legend(["Ground truth", "Observation", "PD3O Estimate"]) -plt.show() \ No newline at end of file diff --git a/_downloads/1f117a6a28d0313d35ba2f9b8f29caee/linop-8.pdf b/_downloads/1f117a6a28d0313d35ba2f9b8f29caee/linop-8.pdf index 3240fe4c..1ac6e885 100644 Binary files a/_downloads/1f117a6a28d0313d35ba2f9b8f29caee/linop-8.pdf and b/_downloads/1f117a6a28d0313d35ba2f9b8f29caee/linop-8.pdf differ diff --git a/_downloads/210cb0deb2ac8363471ad2f714bf5985/operator-18.hires.png b/_downloads/210cb0deb2ac8363471ad2f714bf5985/operator-18.hires.png deleted file mode 100644 index 304a30db..00000000 Binary files a/_downloads/210cb0deb2ac8363471ad2f714bf5985/operator-18.hires.png and /dev/null differ diff --git a/_downloads/21d149a39c58daf587fccda553930dfa/linop-21.png b/_downloads/21d149a39c58daf587fccda553930dfa/linop-21.png deleted file mode 100644 index 707cde96..00000000 Binary files a/_downloads/21d149a39c58daf587fccda553930dfa/linop-21.png and /dev/null differ diff --git a/_downloads/224d8e48ea022f3ad8e02331df42dace/operator-14.hires.png b/_downloads/224d8e48ea022f3ad8e02331df42dace/operator-14.hires.png deleted file mode 100644 index 69769eda..00000000 Binary files a/_downloads/224d8e48ea022f3ad8e02331df42dace/operator-14.hires.png and /dev/null differ diff --git a/_downloads/23893637b3327ac8e6693fb7ff55df1e/linop-21_01.pdf b/_downloads/23893637b3327ac8e6693fb7ff55df1e/linop-21_01.pdf index f0970baa..88491b07 100644 Binary files a/_downloads/23893637b3327ac8e6693fb7ff55df1e/linop-21_01.pdf and b/_downloads/23893637b3327ac8e6693fb7ff55df1e/linop-21_01.pdf differ diff --git a/_downloads/2567cfd1b90b151e14d7b845b313e372/operator-13_03.png b/_downloads/2567cfd1b90b151e14d7b845b313e372/operator-13_03.png deleted file mode 100644 index 77f49770..00000000 Binary files a/_downloads/2567cfd1b90b151e14d7b845b313e372/operator-13_03.png and /dev/null differ diff --git a/_downloads/298e89895fe824420ba2e49aeb0c3fea/operator-8.hires.png b/_downloads/298e89895fe824420ba2e49aeb0c3fea/operator-8.hires.png deleted file mode 100644 index b0ad33fd..00000000 Binary files a/_downloads/298e89895fe824420ba2e49aeb0c3fea/operator-8.hires.png and /dev/null differ diff --git a/_downloads/29a19a1fb21ffd45345b62d68053b614/operator-13_03.hires.png b/_downloads/29a19a1fb21ffd45345b62d68053b614/operator-13_03.hires.png deleted file mode 100644 index 79c9d498..00000000 Binary files a/_downloads/29a19a1fb21ffd45345b62d68053b614/operator-13_03.hires.png and /dev/null differ diff --git a/_downloads/2a27831b457a8e11354eed9aa36db333/operator-13_03.pdf b/_downloads/2a27831b457a8e11354eed9aa36db333/operator-13_03.pdf deleted file mode 100644 index 00f1a911..00000000 Binary files a/_downloads/2a27831b457a8e11354eed9aa36db333/operator-13_03.pdf and /dev/null differ diff --git a/_downloads/2b553e753c10e27428470a2afb36677c/opt-3.pdf b/_downloads/2b553e753c10e27428470a2afb36677c/opt-3.pdf deleted file mode 100644 index db139356..00000000 Binary files a/_downloads/2b553e753c10e27428470a2afb36677c/opt-3.pdf and /dev/null differ diff --git a/_downloads/2df7baa26b1216d90e237608efc19755/operator-3_01.hires.png b/_downloads/2df7baa26b1216d90e237608efc19755/operator-3_01.hires.png deleted file mode 100644 index fb6eebf1..00000000 Binary files a/_downloads/2df7baa26b1216d90e237608efc19755/operator-3_01.hires.png and /dev/null differ diff --git a/_downloads/2dfedee52a994ad94fb7bd9b94482b47/linop-19.hires.png b/_downloads/2dfedee52a994ad94fb7bd9b94482b47/linop-19.hires.png deleted file mode 100644 index 304a30db..00000000 Binary files a/_downloads/2dfedee52a994ad94fb7bd9b94482b47/linop-19.hires.png and /dev/null differ diff --git a/_downloads/2e608f839a2dd0470c1ea869e20bccde/operator-4_00.pdf b/_downloads/2e608f839a2dd0470c1ea869e20bccde/operator-4_00.pdf deleted file mode 100644 index b19ad1ad..00000000 Binary files a/_downloads/2e608f839a2dd0470c1ea869e20bccde/operator-4_00.pdf and /dev/null differ diff --git a/_downloads/2e7add4265c7fc537212f569e3f61c7f/misc-2.pdf b/_downloads/2e7add4265c7fc537212f569e3f61c7f/misc-2.pdf index 3b444152..715ea42a 100644 Binary files a/_downloads/2e7add4265c7fc537212f569e3f61c7f/misc-2.pdf and b/_downloads/2e7add4265c7fc537212f569e3f61c7f/misc-2.pdf differ diff --git a/_downloads/2fc8c1957a4c7f9f2fe757e5469a31e4/operator-18.pdf b/_downloads/2fc8c1957a4c7f9f2fe757e5469a31e4/operator-18.pdf deleted file mode 100644 index dd1be07b..00000000 Binary files a/_downloads/2fc8c1957a4c7f9f2fe757e5469a31e4/operator-18.pdf and /dev/null differ diff --git a/_downloads/32a76fb4fe0570a9a6b22a68761ff535/experimental-sampler-1_00_00.pdf b/_downloads/32a76fb4fe0570a9a6b22a68761ff535/experimental-sampler-1_00_00.pdf index ca3af06c..04d30543 100644 Binary files a/_downloads/32a76fb4fe0570a9a6b22a68761ff535/experimental-sampler-1_00_00.pdf and b/_downloads/32a76fb4fe0570a9a6b22a68761ff535/experimental-sampler-1_00_00.pdf differ diff --git a/_downloads/3350197cf4a2d8503d4a5460eee1fd3b/operator-16.pdf b/_downloads/3350197cf4a2d8503d4a5460eee1fd3b/operator-16.pdf deleted file mode 100644 index 46f5b645..00000000 Binary files a/_downloads/3350197cf4a2d8503d4a5460eee1fd3b/operator-16.pdf and /dev/null differ diff --git a/_downloads/346e1717be7da8fa867cbbe2294f196a/operator-21_02.pdf b/_downloads/346e1717be7da8fa867cbbe2294f196a/operator-21_02.pdf deleted file mode 100644 index bb5327d9..00000000 Binary files a/_downloads/346e1717be7da8fa867cbbe2294f196a/operator-21_02.pdf and /dev/null differ diff --git a/_downloads/3566084b06716c19cd096b504dd5245c/linop-10.png b/_downloads/3566084b06716c19cd096b504dd5245c/linop-10.png deleted file mode 100644 index 9df02f1e..00000000 Binary files a/_downloads/3566084b06716c19cd096b504dd5245c/linop-10.png and /dev/null differ diff --git a/_downloads/36fe774d4b9531a9b7471cccf5df7552/operator-5.png b/_downloads/36fe774d4b9531a9b7471cccf5df7552/operator-5.png deleted file mode 100644 index 3caac993..00000000 Binary files a/_downloads/36fe774d4b9531a9b7471cccf5df7552/operator-5.png and /dev/null differ diff --git a/_downloads/390b0bd8774742dfe7b58970af28e8c4/operator-12_00.png b/_downloads/390b0bd8774742dfe7b58970af28e8c4/operator-12_00.png deleted file mode 100644 index c28866bc..00000000 Binary files a/_downloads/390b0bd8774742dfe7b58970af28e8c4/operator-12_00.png and /dev/null differ diff --git a/_downloads/398290731e77c5555d2871cb9b024a36/linop-4_01.hires.png b/_downloads/398290731e77c5555d2871cb9b024a36/linop-4_01.hires.png deleted file mode 100644 index b50b6dfb..00000000 Binary files a/_downloads/398290731e77c5555d2871cb9b024a36/linop-4_01.hires.png and /dev/null differ diff --git a/_downloads/3a7603daabb4101f49f7a9dd513ab803/operator-6.hires.png b/_downloads/3a7603daabb4101f49f7a9dd513ab803/operator-6.hires.png deleted file mode 100644 index 2e97dd48..00000000 Binary files a/_downloads/3a7603daabb4101f49f7a9dd513ab803/operator-6.hires.png and /dev/null differ diff --git a/_downloads/3b75210a4ac872e658bfc6fd21a99402/linop-18.pdf b/_downloads/3b75210a4ac872e658bfc6fd21a99402/linop-18.pdf index cc85125c..5cf17098 100644 Binary files a/_downloads/3b75210a4ac872e658bfc6fd21a99402/linop-18.pdf and b/_downloads/3b75210a4ac872e658bfc6fd21a99402/linop-18.pdf differ diff --git a/_downloads/3d5a83560b1cd58d557e6254a9784261/operator-19.png b/_downloads/3d5a83560b1cd58d557e6254a9784261/operator-19.png deleted file mode 100644 index cf0cf366..00000000 Binary files a/_downloads/3d5a83560b1cd58d557e6254a9784261/operator-19.png and /dev/null differ diff --git a/_downloads/3e00ef9813368e3b18ae614801b6914c/opt-1.png b/_downloads/3e00ef9813368e3b18ae614801b6914c/opt-1.png deleted file mode 100644 index 5b1ae4f0..00000000 Binary files a/_downloads/3e00ef9813368e3b18ae614801b6914c/opt-1.png and /dev/null differ diff --git a/_downloads/40fedab1780635b89af691e5c4ea11fb/operator-18.py b/_downloads/40fedab1780635b89af691e5c4ea11fb/operator-18.py deleted file mode 100644 index c6cfdede..00000000 --- a/_downloads/40fedab1780635b89af691e5c4ea11fb/operator-18.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import Sobel - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -sobel = Sobel(arg_shape) -out = sobel(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_downloads/427c29d9fe06f23074682a0c3cb7f952/operator-15.png b/_downloads/427c29d9fe06f23074682a0c3cb7f952/operator-15.png deleted file mode 100644 index 26a935f1..00000000 Binary files a/_downloads/427c29d9fe06f23074682a0c3cb7f952/operator-15.png and /dev/null differ diff --git a/_downloads/43864c0e1201a6ed908d58fc3d598b00/operator-12_01.hires.png b/_downloads/43864c0e1201a6ed908d58fc3d598b00/operator-12_01.hires.png deleted file mode 100644 index 34e902e5..00000000 Binary files a/_downloads/43864c0e1201a6ed908d58fc3d598b00/operator-12_01.hires.png and /dev/null differ diff --git a/_downloads/4617a7e816843b4107fe1d29530b7702/operator-6.pdf b/_downloads/4617a7e816843b4107fe1d29530b7702/operator-6.pdf deleted file mode 100644 index afcd5a93..00000000 Binary files a/_downloads/4617a7e816843b4107fe1d29530b7702/operator-6.pdf and /dev/null differ diff --git a/_downloads/468910fa079d504203df7361bc14fe4f/operator-1_01.pdf b/_downloads/468910fa079d504203df7361bc14fe4f/operator-1_01.pdf index 77e1513b..31cffbd8 100644 Binary files a/_downloads/468910fa079d504203df7361bc14fe4f/operator-1_01.pdf and b/_downloads/468910fa079d504203df7361bc14fe4f/operator-1_01.pdf differ diff --git a/_downloads/46ba4351fee97ccd2e3d0aba89e7413d/linop-14.pdf b/_downloads/46ba4351fee97ccd2e3d0aba89e7413d/linop-14.pdf index 17baa0ae..ab53dfa2 100644 Binary files a/_downloads/46ba4351fee97ccd2e3d0aba89e7413d/linop-14.pdf and b/_downloads/46ba4351fee97ccd2e3d0aba89e7413d/linop-14.pdf differ diff --git a/_downloads/4769d18f8e2c0bf193e34be59a343ebb/opt-3.py b/_downloads/4769d18f8e2c0bf193e34be59a343ebb/opt-3.py deleted file mode 100644 index 2b58eeeb..00000000 --- a/_downloads/4769d18f8e2c0bf193e34be59a343ebb/opt-3.py +++ /dev/null @@ -1,58 +0,0 @@ -import matplotlib.pyplot as plt -import numpy as np -import pyxu.abc as pxa -import pyxu.operator as pxo -import scipy as sp -from pyxu.opt.solver import ADMM - -N = 100 # Dimension of the problem - -# Generate piecewise-linear ground truth -x_gt = np.array([10, 25, 60, 90]) # Knot locations -a_gt = np.array([2, -4, 3, -2]) # Amplitudes of the knots -gt = np.zeros(N) # Ground-truth signal -for n in range(len(x_gt)): - gt[x_gt[n] :] += a_gt[n] * np.arange(N - x_gt[n]) / N - -# Generate data (noisy samples at random locations) -M = 20 # Number of data points -rng = np.random.default_rng(seed=0) -x_samp = rng.choice(np.arange(N // M), size=M) + np.arange(N, step=N // M) # sampling locations -sigma = 2 * 1e-2 # noise variance -y = gt[x_samp] + sigma * rng.standard_normal(size=M) # noisy data points - -# Data-fidelity term -subsamp_mat = sp.sparse.lil_matrix((M, N)) -for i in range(M): - subsamp_mat[i, x_samp[i]] = 1 -G = pxa.LinOp.from_array(subsamp_mat.tocsr()) -F = 1 / 2 * pxo.SquaredL2Norm(dim=y.size).argshift(-y) * G -F.diff_lipschitz = F.estimate_diff_lipschitz(method="svd") - -# Regularization term (promotes sparse second derivatives) -deriv_mat = sp.sparse.diags(diagonals=[1, -2, 1], offsets=[0, 1, 2], shape=(N - 2, N)) -D = pxa.LinOp.from_array(deriv_mat) -_lambda = 1e-1 # regularization parameter -H = _lambda * pxo.L1Norm(dim=D.codim) - -# Solver for ADMM -tau = 1 / _lambda # internal ADMM parameter -# Inverse operator to solve the linear system -A_inv = sp.linalg.inv(G.gram().asarray() + (1 / tau) * D.gram().asarray()) - -def solver_ADMM(arr, tau): - b = (1 / tau) * D.adjoint(arr) + G.adjoint(y) - return A_inv @ b.squeeze() - - -# Solve optimization problem -admm = ADMM(f=F, h=H, K=D, solver=solver_ADMM,show_progress=False) # with solver -admm.fit(x0=np.zeros(N), tau=tau) -x_opt = admm.solution() # reconstructed signal - -# Plots -plt.figure() -plt.plot(np.arange(N), gt, label="Ground truth") -plt.plot(x_samp, y, "kx", label="Noisy data points") -plt.plot(np.arange(N), x_opt, label="Reconstructed signal") -plt.legend() \ No newline at end of file diff --git a/_downloads/4835132393171dc4fee6fa57fd1d6c6a/experimental-1_01_00.hires.png b/_downloads/4835132393171dc4fee6fa57fd1d6c6a/experimental-1_01_00.hires.png deleted file mode 100644 index aa5b1c63..00000000 Binary files a/_downloads/4835132393171dc4fee6fa57fd1d6c6a/experimental-1_01_00.hires.png and /dev/null differ diff --git a/_downloads/4b255f3f357b804c1d553a554aa9a10e/operator-9.hires.png b/_downloads/4b255f3f357b804c1d553a554aa9a10e/operator-9.hires.png deleted file mode 100644 index c455c5d4..00000000 Binary files a/_downloads/4b255f3f357b804c1d553a554aa9a10e/operator-9.hires.png and /dev/null differ diff --git a/_downloads/4ba5c9eaac728e0995605bd6a8c46c0b/operator-21_02.hires.png b/_downloads/4ba5c9eaac728e0995605bd6a8c46c0b/operator-21_02.hires.png deleted file mode 100644 index f93b073e..00000000 Binary files a/_downloads/4ba5c9eaac728e0995605bd6a8c46c0b/operator-21_02.hires.png and /dev/null differ diff --git a/_downloads/4cc16af0bb9cf504a115b5d05f3dbec2/linop-4_02.png b/_downloads/4cc16af0bb9cf504a115b5d05f3dbec2/linop-4_02.png deleted file mode 100644 index e557225d..00000000 Binary files a/_downloads/4cc16af0bb9cf504a115b5d05f3dbec2/linop-4_02.png and /dev/null differ diff --git a/_downloads/501c0d344ad2b1378a6ffc9e3b3f1ab0/operator-19.pdf b/_downloads/501c0d344ad2b1378a6ffc9e3b3f1ab0/operator-19.pdf deleted file mode 100644 index aa89b022..00000000 Binary files a/_downloads/501c0d344ad2b1378a6ffc9e3b3f1ab0/operator-19.pdf and /dev/null differ diff --git a/_downloads/507c4e7f83f78bf820d3fcff11186a24/operator-11_00.png b/_downloads/507c4e7f83f78bf820d3fcff11186a24/operator-11_00.png deleted file mode 100644 index 29997314..00000000 Binary files a/_downloads/507c4e7f83f78bf820d3fcff11186a24/operator-11_00.png and /dev/null differ diff --git a/_downloads/51314ba6ee1ae39115d8e0d37bb6ae91/operator-6.png b/_downloads/51314ba6ee1ae39115d8e0d37bb6ae91/operator-6.png deleted file mode 100644 index 60d90a67..00000000 Binary files a/_downloads/51314ba6ee1ae39115d8e0d37bb6ae91/operator-6.png and /dev/null differ diff --git a/_downloads/524c1e2c0e80a155bd2bc9ca41e01180/operator-9.pdf b/_downloads/524c1e2c0e80a155bd2bc9ca41e01180/operator-9.pdf deleted file mode 100644 index 63adde5a..00000000 Binary files a/_downloads/524c1e2c0e80a155bd2bc9ca41e01180/operator-9.pdf and /dev/null differ diff --git a/_downloads/53d0049ee495e879d6713207dec87fb4/opt-solver-3.png b/_downloads/53d0049ee495e879d6713207dec87fb4/opt-solver-3.png index b769785d..d652c5bf 100644 Binary files a/_downloads/53d0049ee495e879d6713207dec87fb4/opt-solver-3.png and b/_downloads/53d0049ee495e879d6713207dec87fb4/opt-solver-3.png differ diff --git a/_downloads/5420c90dcdf9b097dbed8ebf47bc7a03/util-2.pdf b/_downloads/5420c90dcdf9b097dbed8ebf47bc7a03/util-2.pdf index 0c6a330b..a4a41f07 100644 Binary files a/_downloads/5420c90dcdf9b097dbed8ebf47bc7a03/util-2.pdf and b/_downloads/5420c90dcdf9b097dbed8ebf47bc7a03/util-2.pdf differ diff --git a/_downloads/557f177f4b474935fc904081afacebf3/operator-3.py b/_downloads/557f177f4b474935fc904081afacebf3/operator-3.py deleted file mode 100644 index 725e0ddf..00000000 --- a/_downloads/557f177f4b474935fc904081afacebf3/operator-3.py +++ /dev/null @@ -1,40 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import PartialDerivative -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) -arg_shape = image.shape # Shape of our image -# Specify derivative order at each direction -df_dx = (1, 0) # Compute derivative of order 1 in first dimension -d2f_dy2 = (0, 2) # Compute derivative of order 2 in second dimension -d3f_dxdy2 = (1, 2) # Compute derivative of order 1 in first dimension and der. of order 2 in second dimension -# Instantiate derivative operators -sigma = 2.0 -diff1 = PartialDerivative.gaussian_derivative(order=df_dx, arg_shape=arg_shape, sigma=sigma / np.sqrt(2)) -diff2 = PartialDerivative.gaussian_derivative(order=d2f_dy2, arg_shape=arg_shape, sigma=sigma / np.sqrt(2)) -diff = PartialDerivative.gaussian_derivative(order=d3f_dxdy2, arg_shape=arg_shape, sigma=sigma) -# Compute derivatives -out1 = (diff1 * diff2)(image.ravel()).reshape(arg_shape) -out2 = diff(image.ravel()).reshape(arg_shape) -# Plot derivatives -fig, axs = plt.subplots(1, 3, figsize=(15, 4)) -im = axs[0].imshow(image) -axs[0].axis("off") -axs[0].set_title("f(x,y)") -plt.colorbar(im, ax=axs[0]) -axs[1].imshow(out1) -axs[1].axis("off") -axs[1].set_title(r"$\frac{\partial^{3} f(x,y)}{\partial x\partial y^{2}}$") -plt.colorbar(im, ax=axs[1]) - -axs[2].imshow(out2) -axs[2].axis("off") -axs[2].set_title(r"$\frac{\partial^{3} f(x,y)}{\partial x\partial y^{2}}$") -plt.colorbar(im, ax=axs[2]) - -# Test approximation error -plt.figure() -plt.imshow(abs(out1 - out2) / abs(out2)), plt.colorbar() \ No newline at end of file diff --git a/_downloads/55854ad41c5a3d5cbee9b24ef1577582/operator-15.hires.png b/_downloads/55854ad41c5a3d5cbee9b24ef1577582/operator-15.hires.png deleted file mode 100644 index 5e23f460..00000000 Binary files a/_downloads/55854ad41c5a3d5cbee9b24ef1577582/operator-15.hires.png and /dev/null differ diff --git a/_downloads/55d371222ffd54cabbfd4963a3d08463/linop-13_03.png b/_downloads/55d371222ffd54cabbfd4963a3d08463/linop-13_03.png deleted file mode 100644 index 77f49770..00000000 Binary files a/_downloads/55d371222ffd54cabbfd4963a3d08463/linop-13_03.png and /dev/null differ diff --git a/_downloads/57fe8e40f534fdcff0e15bffe502c8fe/operator-14.pdf b/_downloads/57fe8e40f534fdcff0e15bffe502c8fe/operator-14.pdf deleted file mode 100644 index 59edca89..00000000 Binary files a/_downloads/57fe8e40f534fdcff0e15bffe502c8fe/operator-14.pdf and /dev/null differ diff --git a/_downloads/5822ec21ae4dcb79a8910f34bb426b2a/operator-15.py b/_downloads/5822ec21ae4dcb79a8910f34bb426b2a/operator-15.py deleted file mode 100644 index 6af655cf..00000000 --- a/_downloads/5822ec21ae4dcb79a8910f34bb426b2a/operator-15.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import Gaussian - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -gaussian = Gaussian(arg_shape, sigma=3) -out = gaussian(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_downloads/59794358488e15e2bf1ca40d5f99cb9e/operator-12_01.pdf b/_downloads/59794358488e15e2bf1ca40d5f99cb9e/operator-12_01.pdf deleted file mode 100644 index ed4f05f3..00000000 Binary files a/_downloads/59794358488e15e2bf1ca40d5f99cb9e/operator-12_01.pdf and /dev/null differ diff --git a/_downloads/59deb88b8c72373ae195592f25d7ee24/operator-7.pdf b/_downloads/59deb88b8c72373ae195592f25d7ee24/operator-7.pdf deleted file mode 100644 index 120c0519..00000000 Binary files a/_downloads/59deb88b8c72373ae195592f25d7ee24/operator-7.pdf and /dev/null differ diff --git a/_downloads/5a9ba501121acc4e444b2d68b182a34f/linop-11_02.pdf b/_downloads/5a9ba501121acc4e444b2d68b182a34f/linop-11_02.pdf deleted file mode 100644 index de235727..00000000 Binary files a/_downloads/5a9ba501121acc4e444b2d68b182a34f/linop-11_02.pdf and /dev/null differ diff --git a/_downloads/5acb9b748c14cdfa52f2de300f4722e9/operator-11_02.hires.png b/_downloads/5acb9b748c14cdfa52f2de300f4722e9/operator-11_02.hires.png deleted file mode 100644 index c6b1db43..00000000 Binary files a/_downloads/5acb9b748c14cdfa52f2de300f4722e9/operator-11_02.hires.png and /dev/null differ diff --git a/_downloads/5aff9c364459ff6030f38559ad70a41d/operator-20.pdf b/_downloads/5aff9c364459ff6030f38559ad70a41d/operator-20.pdf deleted file mode 100644 index c3711b80..00000000 Binary files a/_downloads/5aff9c364459ff6030f38559ad70a41d/operator-20.pdf and /dev/null differ diff --git a/_downloads/5bc77603e37ab6857e35a64c763b0285/operator-13.py b/_downloads/5bc77603e37ab6857e35a64c763b0285/operator-13.py deleted file mode 100644 index ddc93cd0..00000000 --- a/_downloads/5bc77603e37ab6857e35a64c763b0285/operator-13.py +++ /dev/null @@ -1,35 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import DirectionalHessian -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -z = peaks(xx, yy) -directions1 = np.zeros(shape=(2, z.size)) -directions1[0, :z.size // 2] = 1 -directions1[1, z.size // 2:] = 1 -directions2 = np.zeros(shape=(2, z.size)) -directions2[1, :z.size // 2] = -1 -directions2[0, z.size // 2:] = -1 -arg_shape = z.shape -d_hess = DirectionalHessian(arg_shape=arg_shape, directions=[directions1, directions2]) -out = d_hess.unravel(d_hess(z.ravel())) -plt.figure() -h = plt.pcolormesh(xx, yy, z, shading='auto') -plt.quiver(x, x, directions1[1].reshape(arg_shape), directions1[0].reshape(xx.shape)) -plt.quiver(x, x, directions2[1].reshape(arg_shape), directions2[0].reshape(xx.shape), color='red') -plt.colorbar(h) -plt.title(r'Signal $\mathbf{f}$ and directions of derivatives') -plt.figure() -h = plt.pcolormesh(xx, yy, out[0], shading='auto') -plt.colorbar(h) -plt.title(r'$\nabla^2_{\mathbf{v}_0} \mathbf{f}$') -plt.figure() -h = plt.pcolormesh(xx, yy, out[1], shading='auto') -plt.colorbar(h) -plt.title(r'$\nabla_{\mathbf{v}_0} \nabla_{\mathbf{v}_{1}} \mathbf{f}$') -plt.figure() -h = plt.pcolormesh(xx, yy, out[2], shading='auto') -plt.colorbar(h) -plt.title(r'$\nabla^2_{\mathbf{v}_1} \mathbf{f}$') \ No newline at end of file diff --git a/_downloads/5be70851f96b004b61b84e14faba6d02/util-1.pdf b/_downloads/5be70851f96b004b61b84e14faba6d02/util-1.pdf index 94a15e57..8e452f2d 100644 Binary files a/_downloads/5be70851f96b004b61b84e14faba6d02/util-1.pdf and b/_downloads/5be70851f96b004b61b84e14faba6d02/util-1.pdf differ diff --git a/_downloads/5c238fb268b33a8da224f181740013f5/operator-3_00.hires.png b/_downloads/5c238fb268b33a8da224f181740013f5/operator-3_00.hires.png deleted file mode 100644 index 2cd6cbd3..00000000 Binary files a/_downloads/5c238fb268b33a8da224f181740013f5/operator-3_00.hires.png and /dev/null differ diff --git a/_downloads/5d831190e971237b56d4c6f5001a1497/linop-1.pdf b/_downloads/5d831190e971237b56d4c6f5001a1497/linop-1.pdf index 49c74c60..a846ba25 100644 Binary files a/_downloads/5d831190e971237b56d4c6f5001a1497/linop-1.pdf and b/_downloads/5d831190e971237b56d4c6f5001a1497/linop-1.pdf differ diff --git a/_downloads/5dae74c59590de9941fc8e69d39c3f0c/linop-21.hires.png b/_downloads/5dae74c59590de9941fc8e69d39c3f0c/linop-21.hires.png deleted file mode 100644 index a16df524..00000000 Binary files a/_downloads/5dae74c59590de9941fc8e69d39c3f0c/linop-21.hires.png and /dev/null differ diff --git a/_downloads/5e5b9b1c67e25e4482d76496b68f3b68/experimental-1.py b/_downloads/5e5b9b1c67e25e4482d76496b68f3b68/experimental-1.py deleted file mode 100644 index d5ab99f6..00000000 --- a/_downloads/5e5b9b1c67e25e4482d76496b68f3b68/experimental-1.py +++ /dev/null @@ -1,70 +0,0 @@ -import matplotlib.pyplot as plt -import numpy as np -import pyxu.experimental.sampler as pxe_sampler -import pyxu.operator as pxo -import scipy as sp - -f = pxo.SquaredL2Norm(dim=1) / 2 # To sample 1D normal distribution (mean 0, variance 1) -ula = pxe_sampler.ULA(f=f) # Sampler with maximum step size -ula_lb = pxe_sampler.ULA(f=f, gamma=1e-1) # Sampler with small step size - -gen_ula = ula.samples(x0=np.zeros(1)) -gen_ula_lb = ula_lb.samples(x0=np.zeros(1)) -n_burn_in = int(1e3) # Number of burn-in iterations -for i in range(n_burn_in): - next(gen_ula) - next(gen_ula_lb) - -# Online statistics objects -mean_ula = pxe_sampler.OnlineMoment(order=1) -mean_ula_lb = pxe_sampler.OnlineMoment(order=1) -var_ula = pxe_sampler.OnlineVariance() -var_ula_lb = pxe_sampler.OnlineVariance() - -n = int(1e4) # Number of samples -samples_ula = np.zeros(n) -samples_ula_lb = np.zeros(n) -for i in range(n): - sample = next(gen_ula) - sample_lb = next(gen_ula_lb) - samples_ula[i] = sample - samples_ula_lb[i] = sample_lb - mean = float(mean_ula.update(sample)) - var = float(var_ula.update(sample)) - mean_lb = float(mean_ula_lb.update(sample_lb)) - var_lb = float(var_ula_lb.update(sample_lb)) - -# Theoretical variances of biased stationary distributions of ULA -biased_var = 1 / (1 - ula._gamma / 2) -biased_var_lb = 1 / (1 - ula_lb._gamma / 2) - -# Quantify goodness of fit of empirical distribution with theoretical distribution (Cramér-von Mises test) -cvm = sp.stats.cramervonmises(samples_ula, "norm", args=(0, np.sqrt(biased_var))) -cvm_lb = sp.stats.cramervonmises(samples_ula_lb, "norm", args=(0, np.sqrt(biased_var_lb))) - -# Plots -grid = np.linspace(-4, 4, 1000) - -plt.figure() -plt.title( - f"ULA samples (large step size) \n Empirical mean: {mean:.3f} (theoretical: 0) \n " - f"Empirical variance: {var:.3f} (theoretical: {biased_var:.3f}) \n" - f"Cramér-von Mises goodness of fit: {cvm.statistic:.3f}" -) -plt.hist(samples_ula, range=(min(grid), max(grid)), bins=100, density=True) -plt.plot(grid, sp.stats.norm.pdf(grid), label=r"$p(x)$") -plt.plot(grid, sp.stats.norm.pdf(grid, scale=np.sqrt(biased_var)), label=r"$p_{\gamma_1}(x)$") -plt.legend() -plt.show() - -plt.figure() -plt.title( - f"ULA samples (small step size) \n Empirical mean: {mean_lb:.3f} (theoretical: 0) \n " - f"Empirical variance: {var_lb:.3f} (theoretical: {biased_var_lb:.3f}) \n" - f"Cramér-von Mises goodness of fit: {cvm_lb.statistic:.3f}" -) -plt.hist(samples_ula_lb, range=(min(grid), max(grid)), bins=100, density=True) -plt.plot(grid, sp.stats.norm.pdf(grid), label=r"$p(x)$") -plt.plot(grid, sp.stats.norm.pdf(grid, scale=np.sqrt(biased_var_lb)), label=r"$p_{\gamma_2}(x)$") -plt.legend() -plt.show() \ No newline at end of file diff --git a/_downloads/5ebda40b456c165df2ad890040597b6f/linop-15.pdf b/_downloads/5ebda40b456c165df2ad890040597b6f/linop-15.pdf index 935f6243..97673b8e 100644 Binary files a/_downloads/5ebda40b456c165df2ad890040597b6f/linop-15.pdf and b/_downloads/5ebda40b456c165df2ad890040597b6f/linop-15.pdf differ diff --git a/_downloads/5f62c6bb5301ff3e2502fc8625ddc3e8/linop-19.pdf b/_downloads/5f62c6bb5301ff3e2502fc8625ddc3e8/linop-19.pdf deleted file mode 100644 index 8c3b181b..00000000 Binary files a/_downloads/5f62c6bb5301ff3e2502fc8625ddc3e8/linop-19.pdf and /dev/null differ diff --git a/_downloads/5f6fc21c910212a2ec51fbd06ff28311/opt-2.png b/_downloads/5f6fc21c910212a2ec51fbd06ff28311/opt-2.png deleted file mode 100644 index 4a24cdae..00000000 Binary files a/_downloads/5f6fc21c910212a2ec51fbd06ff28311/opt-2.png and /dev/null differ diff --git a/_downloads/609e087aab0132654c29d1c90c1481a0/operator-20.hires.png b/_downloads/609e087aab0132654c29d1c90c1481a0/operator-20.hires.png deleted file mode 100644 index a16df524..00000000 Binary files a/_downloads/609e087aab0132654c29d1c90c1481a0/operator-20.hires.png and /dev/null differ diff --git a/_downloads/64198f23c5f65d9a6e63da1e1c3364d8/operator-3_01.png b/_downloads/64198f23c5f65d9a6e63da1e1c3364d8/operator-3_01.png deleted file mode 100644 index 23895dd6..00000000 Binary files a/_downloads/64198f23c5f65d9a6e63da1e1c3364d8/operator-3_01.png and /dev/null differ diff --git a/_downloads/6456824f0a6ba3b0c63ce20c17d96e7d/operator-2.hires.png b/_downloads/6456824f0a6ba3b0c63ce20c17d96e7d/operator-2.hires.png deleted file mode 100644 index 8c88a1d8..00000000 Binary files a/_downloads/6456824f0a6ba3b0c63ce20c17d96e7d/operator-2.hires.png and /dev/null differ diff --git a/_downloads/651d2605be213b23cdea0892fe1385fd/linop-10_03.pdf b/_downloads/651d2605be213b23cdea0892fe1385fd/linop-10_03.pdf index b784160f..cab15943 100644 Binary files a/_downloads/651d2605be213b23cdea0892fe1385fd/linop-10_03.pdf and b/_downloads/651d2605be213b23cdea0892fe1385fd/linop-10_03.pdf differ diff --git a/_downloads/65a0f0ae34645fbd8fc9c45aa8707cb6/linop-4_01.png b/_downloads/65a0f0ae34645fbd8fc9c45aa8707cb6/linop-4_01.png deleted file mode 100644 index ea2aefc5..00000000 Binary files a/_downloads/65a0f0ae34645fbd8fc9c45aa8707cb6/linop-4_01.png and /dev/null differ diff --git a/_downloads/67094c89382ad81380a52906901bb725/operator-17.py b/_downloads/67094c89382ad81380a52906901bb725/operator-17.py deleted file mode 100644 index 74ffad5c..00000000 --- a/_downloads/67094c89382ad81380a52906901bb725/operator-17.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import Laplace - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -laplace = Laplace(arg_shape) -out = laplace(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_downloads/673d72fb29625abae78650b04ff992cf/operator-21_00.pdf b/_downloads/673d72fb29625abae78650b04ff992cf/operator-21_00.pdf deleted file mode 100644 index f60243ed..00000000 Binary files a/_downloads/673d72fb29625abae78650b04ff992cf/operator-21_00.pdf and /dev/null differ diff --git a/_downloads/6902f0f4b2fd599de9c794c345b38a48/linop-12_01.pdf b/_downloads/6902f0f4b2fd599de9c794c345b38a48/linop-12_01.pdf index 26b0b901..267a546f 100644 Binary files a/_downloads/6902f0f4b2fd599de9c794c345b38a48/linop-12_01.pdf and b/_downloads/6902f0f4b2fd599de9c794c345b38a48/linop-12_01.pdf differ diff --git a/_downloads/6d6eb2e18628afcd80afb9b1f46a86c9/operator-1_00.pdf b/_downloads/6d6eb2e18628afcd80afb9b1f46a86c9/operator-1_00.pdf index 14e8fad8..3cf18f98 100644 Binary files a/_downloads/6d6eb2e18628afcd80afb9b1f46a86c9/operator-1_00.pdf and b/_downloads/6d6eb2e18628afcd80afb9b1f46a86c9/operator-1_00.pdf differ diff --git a/_downloads/6e540c944bfd9490bda771e3a4d2d051/linop-13_02.hires.png b/_downloads/6e540c944bfd9490bda771e3a4d2d051/linop-13_02.hires.png deleted file mode 100644 index 17cbf1bf..00000000 Binary files a/_downloads/6e540c944bfd9490bda771e3a4d2d051/linop-13_02.hires.png and /dev/null differ diff --git a/_downloads/727cebf6c294705854011009653ef8e1/opt-solver-3.pdf b/_downloads/727cebf6c294705854011009653ef8e1/opt-solver-3.pdf index 7f6968b9..46984fa4 100644 Binary files a/_downloads/727cebf6c294705854011009653ef8e1/opt-solver-3.pdf and b/_downloads/727cebf6c294705854011009653ef8e1/opt-solver-3.pdf differ diff --git a/_downloads/73bedc7b7248ca036824dc8463b36828/operator-17.pdf b/_downloads/73bedc7b7248ca036824dc8463b36828/operator-17.pdf deleted file mode 100644 index b63f9b3c..00000000 Binary files a/_downloads/73bedc7b7248ca036824dc8463b36828/operator-17.pdf and /dev/null differ diff --git a/_downloads/745f48dcf87b63655f3a16dcef7b2961/operator-4_02.png b/_downloads/745f48dcf87b63655f3a16dcef7b2961/operator-4_02.png deleted file mode 100644 index e557225d..00000000 Binary files a/_downloads/745f48dcf87b63655f3a16dcef7b2961/operator-4_02.png and /dev/null differ diff --git a/_downloads/74d1d3b6135054cbe9fd1fe59d6f8bad/operator-13_02.hires.png b/_downloads/74d1d3b6135054cbe9fd1fe59d6f8bad/operator-13_02.hires.png deleted file mode 100644 index 17cbf1bf..00000000 Binary files a/_downloads/74d1d3b6135054cbe9fd1fe59d6f8bad/operator-13_02.hires.png and /dev/null differ diff --git a/_downloads/758c43883775bf96c999d8249824235e/operator-5.pdf b/_downloads/758c43883775bf96c999d8249824235e/operator-5.pdf deleted file mode 100644 index c2ec0b65..00000000 Binary files a/_downloads/758c43883775bf96c999d8249824235e/operator-5.pdf and /dev/null differ diff --git a/_downloads/7a311f51d351b440032a25d77b6b0f15/operator-21.py b/_downloads/7a311f51d351b440032a25d77b6b0f15/operator-21.py deleted file mode 100644 index 9ef935ea..00000000 --- a/_downloads/7a311f51d351b440032a25d77b6b0f15/operator-21.py +++ /dev/null @@ -1,45 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import StructureTensor -from pyxu.util.misc import peaks - -# Define input image -n = 1000 -x = np.linspace(-3, 3, n) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) -nsamples = 2 -arg_shape = image.shape # (1000, 1000) -images = np.tile(image, (nsamples, 1, 1)).reshape(nsamples, -1) -print(images.shape) # (2, 1000000) -# Instantiate structure tensor operator -structure_tensor = StructureTensor(arg_shape=arg_shape) - -outputs = structure_tensor(images) -print(outputs.shape) # (2, 3000000) -# Plot -outputs = structure_tensor.unravel(outputs) -print(outputs.shape) # (2, 3, 1000, 1000) -plt.figure() -plt.imshow(images[0].reshape(arg_shape)) -plt.colorbar() -plt.title("Image") -plt.axis("off") - -plt.figure() -plt.imshow(outputs[0][0].reshape(arg_shape)) -plt.colorbar() -plt.title(r"$\hat{S}_{xx}$") -plt.axis("off") - -plt.figure() -plt.imshow(outputs[0][1].reshape(arg_shape)) -plt.colorbar() -plt.title(r"$\hat{S}_{xy}$") -plt.axis("off") - -plt.figure() -plt.imshow(outputs[0][2].reshape(arg_shape)) -plt.colorbar() -plt.title(r"$\hat{S}_{yy}$") -plt.axis("off") \ No newline at end of file diff --git a/_downloads/7a45a92466c43f54218138bd4c5bfb33/opt-1.pdf b/_downloads/7a45a92466c43f54218138bd4c5bfb33/opt-1.pdf deleted file mode 100644 index 8c3fe559..00000000 Binary files a/_downloads/7a45a92466c43f54218138bd4c5bfb33/opt-1.pdf and /dev/null differ diff --git a/_downloads/7acbb4c520fb3c12fd8bb79d870c930d/opt-2.hires.png b/_downloads/7acbb4c520fb3c12fd8bb79d870c930d/opt-2.hires.png deleted file mode 100644 index 05fc0b01..00000000 Binary files a/_downloads/7acbb4c520fb3c12fd8bb79d870c930d/opt-2.hires.png and /dev/null differ diff --git a/_downloads/7b093b841c4187795b2b3e7fe37a35fb/linop-21_03.pdf b/_downloads/7b093b841c4187795b2b3e7fe37a35fb/linop-21_03.pdf index 41bb5ead..52382b7d 100644 Binary files a/_downloads/7b093b841c4187795b2b3e7fe37a35fb/linop-21_03.pdf and b/_downloads/7b093b841c4187795b2b3e7fe37a35fb/linop-21_03.pdf differ diff --git a/_downloads/7bf4f564a15100201d0a1e7baafafa52/opt-solver-2.pdf b/_downloads/7bf4f564a15100201d0a1e7baafafa52/opt-solver-2.pdf index 87e6c096..ab401ccb 100644 Binary files a/_downloads/7bf4f564a15100201d0a1e7baafafa52/opt-solver-2.pdf and b/_downloads/7bf4f564a15100201d0a1e7baafafa52/opt-solver-2.pdf differ diff --git a/_downloads/7c525dffe55156065be00ab7ed0fdbc9/linop-4_00.hires.png b/_downloads/7c525dffe55156065be00ab7ed0fdbc9/linop-4_00.hires.png deleted file mode 100644 index e0f5bc76..00000000 Binary files a/_downloads/7c525dffe55156065be00ab7ed0fdbc9/linop-4_00.hires.png and /dev/null differ diff --git a/_downloads/7e7493ef5be8fe7afc5d4591de150cb7/operator-8.pdf b/_downloads/7e7493ef5be8fe7afc5d4591de150cb7/operator-8.pdf deleted file mode 100644 index 840ccddd..00000000 Binary files a/_downloads/7e7493ef5be8fe7afc5d4591de150cb7/operator-8.pdf and /dev/null differ diff --git a/_downloads/7f7cb23a315a631d79c8a7353eb5e5ea/linop-3_01.hires.png b/_downloads/7f7cb23a315a631d79c8a7353eb5e5ea/linop-3_01.hires.png deleted file mode 100644 index fb6eebf1..00000000 Binary files a/_downloads/7f7cb23a315a631d79c8a7353eb5e5ea/linop-3_01.hires.png and /dev/null differ diff --git a/_downloads/7fade2ac152b694790a10dace2a8fb9d/operator-21_01.hires.png b/_downloads/7fade2ac152b694790a10dace2a8fb9d/operator-21_01.hires.png deleted file mode 100644 index ec6b317a..00000000 Binary files a/_downloads/7fade2ac152b694790a10dace2a8fb9d/operator-21_01.hires.png and /dev/null differ diff --git a/_downloads/80a3b5b858569587ccf5e93587163d10/operator-20.png b/_downloads/80a3b5b858569587ccf5e93587163d10/operator-20.png deleted file mode 100644 index 707cde96..00000000 Binary files a/_downloads/80a3b5b858569587ccf5e93587163d10/operator-20.png and /dev/null differ diff --git a/_downloads/80addee3e5ddf78f60a7c11d664bee28/linop-3_00.hires.png b/_downloads/80addee3e5ddf78f60a7c11d664bee28/linop-3_00.hires.png deleted file mode 100644 index 2cd6cbd3..00000000 Binary files a/_downloads/80addee3e5ddf78f60a7c11d664bee28/linop-3_00.hires.png and /dev/null differ diff --git a/_downloads/80e8d2262c83f8aa3286c318c355a06b/operator-11_00.pdf b/_downloads/80e8d2262c83f8aa3286c318c355a06b/operator-11_00.pdf deleted file mode 100644 index 4a5514a4..00000000 Binary files a/_downloads/80e8d2262c83f8aa3286c318c355a06b/operator-11_00.pdf and /dev/null differ diff --git a/_downloads/821591bde9f2c4bb83a1dbdf85716dce/operator-19.py b/_downloads/821591bde9f2c4bb83a1dbdf85716dce/operator-19.py deleted file mode 100644 index 4e36ae88..00000000 --- a/_downloads/821591bde9f2c4bb83a1dbdf85716dce/operator-19.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import Prewitt - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -prewitt = Prewitt(arg_shape) -out = prewitt(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_downloads/830c6cf1ca9ddce08ef358693dbce351/operator-15.pdf b/_downloads/830c6cf1ca9ddce08ef358693dbce351/operator-15.pdf deleted file mode 100644 index c525fab3..00000000 Binary files a/_downloads/830c6cf1ca9ddce08ef358693dbce351/operator-15.pdf and /dev/null differ diff --git a/_downloads/84355f586daab57f0013b1d59aea0d7c/operator-7.png b/_downloads/84355f586daab57f0013b1d59aea0d7c/operator-7.png deleted file mode 100644 index 39e58e55..00000000 Binary files a/_downloads/84355f586daab57f0013b1d59aea0d7c/operator-7.png and /dev/null differ diff --git a/_downloads/84c84a6dd5058dc024f4c28e976c67be/operator-4_00.png b/_downloads/84c84a6dd5058dc024f4c28e976c67be/operator-4_00.png deleted file mode 100644 index fccd452c..00000000 Binary files a/_downloads/84c84a6dd5058dc024f4c28e976c67be/operator-4_00.png and /dev/null differ diff --git a/_downloads/852396df1c2a68b4ab13ea440094a13b/linop-2.pdf b/_downloads/852396df1c2a68b4ab13ea440094a13b/linop-2.pdf index 5c3063f8..5cb391a1 100644 Binary files a/_downloads/852396df1c2a68b4ab13ea440094a13b/linop-2.pdf and b/_downloads/852396df1c2a68b4ab13ea440094a13b/linop-2.pdf differ diff --git a/_downloads/86e69c2455bde978da9d846de7a188a9/operator-10.hires.png b/_downloads/86e69c2455bde978da9d846de7a188a9/operator-10.hires.png deleted file mode 100644 index fae722c2..00000000 Binary files a/_downloads/86e69c2455bde978da9d846de7a188a9/operator-10.hires.png and /dev/null differ diff --git a/_downloads/8860ae0fe6ee3c63137f67234c7ff9a8/experimental-1_01_00.pdf b/_downloads/8860ae0fe6ee3c63137f67234c7ff9a8/experimental-1_01_00.pdf deleted file mode 100644 index 0a4f5b1d..00000000 Binary files a/_downloads/8860ae0fe6ee3c63137f67234c7ff9a8/experimental-1_01_00.pdf and /dev/null differ diff --git a/_downloads/89cf7e77837a5c3249511293b70d7aa2/linop-13_00.pdf b/_downloads/89cf7e77837a5c3249511293b70d7aa2/linop-13_00.pdf deleted file mode 100644 index 7a50f81e..00000000 Binary files a/_downloads/89cf7e77837a5c3249511293b70d7aa2/linop-13_00.pdf and /dev/null differ diff --git a/_downloads/8aaa0ff216ce48a45f853f1ad1ff4869/operator-19.hires.png b/_downloads/8aaa0ff216ce48a45f853f1ad1ff4869/operator-19.hires.png deleted file mode 100644 index fe395c67..00000000 Binary files a/_downloads/8aaa0ff216ce48a45f853f1ad1ff4869/operator-19.hires.png and /dev/null differ diff --git a/_downloads/8b1f3ad99310d672760460d94ff5ae53/linop-3_01.png b/_downloads/8b1f3ad99310d672760460d94ff5ae53/linop-3_01.png deleted file mode 100644 index 23895dd6..00000000 Binary files a/_downloads/8b1f3ad99310d672760460d94ff5ae53/linop-3_01.png and /dev/null differ diff --git a/_downloads/8b695d494c85f1c4793c328b97cbc021/operator-1.png b/_downloads/8b695d494c85f1c4793c328b97cbc021/operator-1.png deleted file mode 100644 index 65459407..00000000 Binary files a/_downloads/8b695d494c85f1c4793c328b97cbc021/operator-1.png and /dev/null differ diff --git a/_downloads/8b725cf748f1669bc44a24d333409c47/linop-12_02.pdf b/_downloads/8b725cf748f1669bc44a24d333409c47/linop-12_02.pdf index 094c3258..afba84cf 100644 Binary files a/_downloads/8b725cf748f1669bc44a24d333409c47/linop-12_02.pdf and b/_downloads/8b725cf748f1669bc44a24d333409c47/linop-12_02.pdf differ diff --git a/_downloads/8b75e17542eb060a859009378ccf739e/operator-6.py b/_downloads/8b75e17542eb060a859009378ccf739e/operator-6.py deleted file mode 100644 index 088a74fe..00000000 --- a/_downloads/8b75e17542eb060a859009378ccf739e/operator-6.py +++ /dev/null @@ -1,16 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import Jacobian -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -image = np.tile(peaks(xx, yy), (3, 1, 1)) -jac = Jacobian(arg_shape=image.shape[1:], n_channels=image.shape[0]) -out = jac.unravel(jac(image.ravel())) -fig, axes = plt.subplots(3, 2, figsize=(10, 15)) -for i in range(3): - for j in range(2): - axes[i, j].imshow(out[i, j].T, cmap=["Reds", "Greens", "Blues"][j]) - axes[i, j].set_title(f"$\partial I_{{{['R', 'G', 'B'][j]}}}/\partial{{{['x', 'y'][j]}}}$") -plt.suptitle("Jacobian") \ No newline at end of file diff --git a/_downloads/8f59a997c178a3e2bb89f1f4ce7dc2b0/operator-4_01.png b/_downloads/8f59a997c178a3e2bb89f1f4ce7dc2b0/operator-4_01.png deleted file mode 100644 index ea2aefc5..00000000 Binary files a/_downloads/8f59a997c178a3e2bb89f1f4ce7dc2b0/operator-4_01.png and /dev/null differ diff --git a/_downloads/9029f349dcba6220309b295a9140982b/operator-2.py b/_downloads/9029f349dcba6220309b295a9140982b/operator-2.py deleted file mode 100644 index fb8d4844..00000000 --- a/_downloads/9029f349dcba6220309b295a9140982b/operator-2.py +++ /dev/null @@ -1,43 +0,0 @@ -import numpy as np -import pyxu.operator as pxo - -rng = np.random.default_rng(2) -D, M, N = 2, 500, 200 -rnd_points = lambda _: rng.normal(scale=rng.uniform(0.25, 0.5, size=(D,)), size=(_, D)) -rnd_offset = lambda: rng.uniform(-1, 1, size=(D,)) -scale = 20 -x = np.concatenate( - [ - rnd_points(M) + rnd_offset() * scale, - rnd_points(M) + rnd_offset() * scale, - rnd_points(M) + rnd_offset() * scale, - rnd_points(M) + rnd_offset() * scale, - rnd_points(M) + rnd_offset() * scale, - ], - axis=0, -) -z = np.concatenate( - [ - rnd_points(N) + rnd_offset() * scale, - rnd_points(N) + rnd_offset() * scale, - rnd_points(N) + rnd_offset() * scale, - rnd_points(N) + rnd_offset() * scale, - rnd_points(N) + rnd_offset() * scale, - ], - axis=0, -) - -kwargs = dict( - x=x, - z=z, - isign=-1, - eps=1e-3, -) -A = pxo.NUFFT.type3(**kwargs, chunked=True) -x_chunks, z_chunks = A.auto_chunk( - max_mem=.1, - max_anisotropy=1, -) -A.allocate(x_chunks, z_chunks) -fig = A.diagnostic_plot('x') -fig.show() \ No newline at end of file diff --git a/_downloads/90b6ede7cd0b624bf04b02a069518152/operator-13_00.pdf b/_downloads/90b6ede7cd0b624bf04b02a069518152/operator-13_00.pdf deleted file mode 100644 index 4f9d0109..00000000 Binary files a/_downloads/90b6ede7cd0b624bf04b02a069518152/operator-13_00.pdf and /dev/null differ diff --git a/_downloads/91bc70ed73eba97c728b782748cb547d/experimental-sampler-1_01_00.pdf b/_downloads/91bc70ed73eba97c728b782748cb547d/experimental-sampler-1_01_00.pdf index fb1a5c0c..e27083a8 100644 Binary files a/_downloads/91bc70ed73eba97c728b782748cb547d/experimental-sampler-1_01_00.pdf and b/_downloads/91bc70ed73eba97c728b782748cb547d/experimental-sampler-1_01_00.pdf differ diff --git a/_downloads/92c55fbba0661a785247389e08ad5597/operator-16.hires.png b/_downloads/92c55fbba0661a785247389e08ad5597/operator-16.hires.png deleted file mode 100644 index a8185a39..00000000 Binary files a/_downloads/92c55fbba0661a785247389e08ad5597/operator-16.hires.png and /dev/null differ diff --git a/_downloads/939913c4d6f629c9f874b65940808e69/linop-13_03.hires.png b/_downloads/939913c4d6f629c9f874b65940808e69/linop-13_03.hires.png deleted file mode 100644 index 79c9d498..00000000 Binary files a/_downloads/939913c4d6f629c9f874b65940808e69/linop-13_03.hires.png and /dev/null differ diff --git a/_downloads/93fb12da52772af95edddbe745a3718e/experimental-sampler-1_00_00.hires.png b/_downloads/93fb12da52772af95edddbe745a3718e/experimental-sampler-1_00_00.hires.png index 9b6309b8..d144350f 100644 Binary files a/_downloads/93fb12da52772af95edddbe745a3718e/experimental-sampler-1_00_00.hires.png and b/_downloads/93fb12da52772af95edddbe745a3718e/experimental-sampler-1_00_00.hires.png differ diff --git a/_downloads/980507e47f5840458f13ac6f6b9c23a7/operator-4_02.hires.png b/_downloads/980507e47f5840458f13ac6f6b9c23a7/operator-4_02.hires.png deleted file mode 100644 index afc1e2cf..00000000 Binary files a/_downloads/980507e47f5840458f13ac6f6b9c23a7/operator-4_02.hires.png and /dev/null differ diff --git a/_downloads/9c8347663ec88378aaae5057c1ae3264/operator-1.py b/_downloads/9c8347663ec88378aaae5057c1ae3264/operator-1.py deleted file mode 100644 index 2fb312ed..00000000 --- a/_downloads/9c8347663ec88378aaae5057c1ae3264/operator-1.py +++ /dev/null @@ -1,14 +0,0 @@ -import numpy as np -import pyxu.operator as pxo -import matplotlib.pyplot as plt - -rng = np.random.default_rng(0) -D, M, N = 1, 2, 3 # D denotes the dimension of the data -x = np.fmod(rng.normal(size=(M, D)), 2 * np.pi) -A = pxo.NUFFT.type1( - x, N, - isign=-1, - eps=1e-9 -) -A.plot_kernel() -plt.show() \ No newline at end of file diff --git a/_downloads/9db61dbdbb51645a825c3d21408069d0/opt-1.hires.png b/_downloads/9db61dbdbb51645a825c3d21408069d0/opt-1.hires.png deleted file mode 100644 index 5c9726a6..00000000 Binary files a/_downloads/9db61dbdbb51645a825c3d21408069d0/opt-1.hires.png and /dev/null differ diff --git a/_downloads/9e57502a9a3a00032c71b730aca92025/linop-7.pdf b/_downloads/9e57502a9a3a00032c71b730aca92025/linop-7.pdf index 62ff0549..4f989b73 100644 Binary files a/_downloads/9e57502a9a3a00032c71b730aca92025/linop-7.pdf and b/_downloads/9e57502a9a3a00032c71b730aca92025/linop-7.pdf differ diff --git a/_downloads/9ef5b55562f46c73423fa8bff428227e/linop-13_01.hires.png b/_downloads/9ef5b55562f46c73423fa8bff428227e/linop-13_01.hires.png deleted file mode 100644 index 9ccc6d00..00000000 Binary files a/_downloads/9ef5b55562f46c73423fa8bff428227e/linop-13_01.hires.png and /dev/null differ diff --git a/_downloads/9fb2ea53b64737bdcfba96217fef5782/operator-21_00.hires.png b/_downloads/9fb2ea53b64737bdcfba96217fef5782/operator-21_00.hires.png deleted file mode 100644 index 9fa3fcde..00000000 Binary files a/_downloads/9fb2ea53b64737bdcfba96217fef5782/operator-21_00.hires.png and /dev/null differ diff --git a/_downloads/a21657746c05addd5a96533facc10684/experimental-sampler-1_01_00.png b/_downloads/a21657746c05addd5a96533facc10684/experimental-sampler-1_01_00.png index c8779884..8abb07d6 100644 Binary files a/_downloads/a21657746c05addd5a96533facc10684/experimental-sampler-1_01_00.png and b/_downloads/a21657746c05addd5a96533facc10684/experimental-sampler-1_01_00.png differ diff --git a/_downloads/a262dbc83116c51f87f485930377e9fa/abc-1_00.pdf b/_downloads/a262dbc83116c51f87f485930377e9fa/abc-1_00.pdf index 68a92a3f..5511e171 100644 Binary files a/_downloads/a262dbc83116c51f87f485930377e9fa/abc-1_00.pdf and b/_downloads/a262dbc83116c51f87f485930377e9fa/abc-1_00.pdf differ diff --git a/_downloads/a2750b0cb155e149ee1e828df83ae363/linop-21_00.pdf b/_downloads/a2750b0cb155e149ee1e828df83ae363/linop-21_00.pdf index a004cacf..fda9661e 100644 Binary files a/_downloads/a2750b0cb155e149ee1e828df83ae363/linop-21_00.pdf and b/_downloads/a2750b0cb155e149ee1e828df83ae363/linop-21_00.pdf differ diff --git a/_downloads/a30e3ded8c1066a4592a760dd92364c9/operator-7.py b/_downloads/a30e3ded8c1066a4592a760dd92364c9/operator-7.py deleted file mode 100644 index df749166..00000000 --- a/_downloads/a30e3ded8c1066a4592a760dd92364c9/operator-7.py +++ /dev/null @@ -1,25 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import Gradient, Divergence, Laplacian -from pyxu.util.misc import peaks - -n = 100 -x = np.linspace(-3, 3, n) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) -arg_shape = image.shape # (1000, 1000) -grad = Gradient(arg_shape=arg_shape) -div = Divergence(arg_shape=arg_shape) -# Construct Laplacian via composition -laplacian1 = div * grad -# Compare to default Laplacian -laplacian2 = Laplacian(arg_shape=arg_shape) -output1 = laplacian1(image.ravel()) -output2 = laplacian2(image.ravel()) -fig, axes = plt.subplots(1, 2, figsize=(10, 5)) -im = axes[0].imshow(np.log(abs(output1)).reshape(*arg_shape)) -axes[0].set_title("Laplacian via composition") -plt.colorbar(im, ax=axes[0]) -im = axes[1].imshow(np.log(abs(output1)).reshape(*arg_shape)) -axes[1].set_title("Default Laplacian") -plt.colorbar(im, ax=axes[1]) \ No newline at end of file diff --git a/_downloads/a38dda46342bca2d4b49ded8ed4e9096/operator-7.hires.png b/_downloads/a38dda46342bca2d4b49ded8ed4e9096/operator-7.hires.png deleted file mode 100644 index ae2eedda..00000000 Binary files a/_downloads/a38dda46342bca2d4b49ded8ed4e9096/operator-7.hires.png and /dev/null differ diff --git a/_downloads/a55a7abe3d36074d183a6c2f04c216f0/operator-11_00.hires.png b/_downloads/a55a7abe3d36074d183a6c2f04c216f0/operator-11_00.hires.png deleted file mode 100644 index 4d5d2c76..00000000 Binary files a/_downloads/a55a7abe3d36074d183a6c2f04c216f0/operator-11_00.hires.png and /dev/null differ diff --git a/_downloads/a65f90bcbe154b20bfa66b70ccf8657f/linop-3_00.png b/_downloads/a65f90bcbe154b20bfa66b70ccf8657f/linop-3_00.png deleted file mode 100644 index fe4dbf22..00000000 Binary files a/_downloads/a65f90bcbe154b20bfa66b70ccf8657f/linop-3_00.png and /dev/null differ diff --git a/_downloads/a787a4de8a26371e9e6db60996ebc82f/linop-20.png b/_downloads/a787a4de8a26371e9e6db60996ebc82f/linop-20.png deleted file mode 100644 index cf0cf366..00000000 Binary files a/_downloads/a787a4de8a26371e9e6db60996ebc82f/linop-20.png and /dev/null differ diff --git a/_downloads/a7fbcf236aa04c1f2f0fe84dd0beb567/linop-17.pdf b/_downloads/a7fbcf236aa04c1f2f0fe84dd0beb567/linop-17.pdf index 2d02bb88..feac0625 100644 Binary files a/_downloads/a7fbcf236aa04c1f2f0fe84dd0beb567/linop-17.pdf and b/_downloads/a7fbcf236aa04c1f2f0fe84dd0beb567/linop-17.pdf differ diff --git a/_downloads/a8991112e97556caf0e2fd5883613b0a/operator-21_02.png b/_downloads/a8991112e97556caf0e2fd5883613b0a/operator-21_02.png deleted file mode 100644 index 202a34b9..00000000 Binary files a/_downloads/a8991112e97556caf0e2fd5883613b0a/operator-21_02.png and /dev/null differ diff --git a/_downloads/a91dd135849d728226e425b0ff0e1bd6/operator-12_01.png b/_downloads/a91dd135849d728226e425b0ff0e1bd6/operator-12_01.png deleted file mode 100644 index 07432f15..00000000 Binary files a/_downloads/a91dd135849d728226e425b0ff0e1bd6/operator-12_01.png and /dev/null differ diff --git a/_downloads/a9f1d15500139a62d3908b04a52bc416/linop-10_00.pdf b/_downloads/a9f1d15500139a62d3908b04a52bc416/linop-10_00.pdf index a839ce52..665448b8 100644 Binary files a/_downloads/a9f1d15500139a62d3908b04a52bc416/linop-10_00.pdf and b/_downloads/a9f1d15500139a62d3908b04a52bc416/linop-10_00.pdf differ diff --git a/_downloads/aa08cf4e2cef61b518aa64b10c1817a9/abc-1_01.pdf b/_downloads/aa08cf4e2cef61b518aa64b10c1817a9/abc-1_01.pdf index 46a33053..4f600ce0 100644 Binary files a/_downloads/aa08cf4e2cef61b518aa64b10c1817a9/abc-1_01.pdf and b/_downloads/aa08cf4e2cef61b518aa64b10c1817a9/abc-1_01.pdf differ diff --git a/_downloads/ac2d8e4fa5ab3cfce5066292ea2e5ee4/operator-13_00.png b/_downloads/ac2d8e4fa5ab3cfce5066292ea2e5ee4/operator-13_00.png deleted file mode 100644 index 29997314..00000000 Binary files a/_downloads/ac2d8e4fa5ab3cfce5066292ea2e5ee4/operator-13_00.png and /dev/null differ diff --git a/_downloads/ad2f7e24bddbd17a6cfa96e6423ca673/experimental-1_00_00.pdf b/_downloads/ad2f7e24bddbd17a6cfa96e6423ca673/experimental-1_00_00.pdf deleted file mode 100644 index 834d2478..00000000 Binary files a/_downloads/ad2f7e24bddbd17a6cfa96e6423ca673/experimental-1_00_00.pdf and /dev/null differ diff --git a/_downloads/aef880f23607764f0dad2e327f5d24fd/opt-3.hires.png b/_downloads/aef880f23607764f0dad2e327f5d24fd/opt-3.hires.png deleted file mode 100644 index 8040355b..00000000 Binary files a/_downloads/aef880f23607764f0dad2e327f5d24fd/opt-3.hires.png and /dev/null differ diff --git a/_downloads/b0e4014986a0f5921e51c57c3f1d2893/operator-4_02.pdf b/_downloads/b0e4014986a0f5921e51c57c3f1d2893/operator-4_02.pdf deleted file mode 100644 index f59b3f2a..00000000 Binary files a/_downloads/b0e4014986a0f5921e51c57c3f1d2893/operator-4_02.pdf and /dev/null differ diff --git a/_downloads/b1cab852cc8994069d3eb7349822e126/linop-13_02.pdf b/_downloads/b1cab852cc8994069d3eb7349822e126/linop-13_02.pdf deleted file mode 100644 index 6f4f5460..00000000 Binary files a/_downloads/b1cab852cc8994069d3eb7349822e126/linop-13_02.pdf and /dev/null differ diff --git a/_downloads/b2643be9761ce6a5244d11d98408529f/linop-13.pdf b/_downloads/b2643be9761ce6a5244d11d98408529f/linop-13.pdf index 0ce8ee28..a6ff73fc 100644 Binary files a/_downloads/b2643be9761ce6a5244d11d98408529f/linop-13.pdf and b/_downloads/b2643be9761ce6a5244d11d98408529f/linop-13.pdf differ diff --git a/_downloads/b36aa4a64f4a3c14b29c9ba6aa0773dd/experimental-1_01_00.png b/_downloads/b36aa4a64f4a3c14b29c9ba6aa0773dd/experimental-1_01_00.png deleted file mode 100644 index 5c33d91e..00000000 Binary files a/_downloads/b36aa4a64f4a3c14b29c9ba6aa0773dd/experimental-1_01_00.png and /dev/null differ diff --git a/_downloads/b5b8151ee0b479d40092a5e2c7ba8055/operator-11_02.pdf b/_downloads/b5b8151ee0b479d40092a5e2c7ba8055/operator-11_02.pdf deleted file mode 100644 index 9207566e..00000000 Binary files a/_downloads/b5b8151ee0b479d40092a5e2c7ba8055/operator-11_02.pdf and /dev/null differ diff --git a/_downloads/b720f3f70e5d870af630b0311b862bdc/operator-16.py b/_downloads/b720f3f70e5d870af630b0311b862bdc/operator-16.py deleted file mode 100644 index 7650f6fb..00000000 --- a/_downloads/b720f3f70e5d870af630b0311b862bdc/operator-16.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import DoG - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -dog = DoG(arg_shape, low_sigma=3) -out = dog(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_downloads/b793257364ec7e73fe09d6ac0cf897bb/linop-3.pdf b/_downloads/b793257364ec7e73fe09d6ac0cf897bb/linop-3.pdf index 8062c6e6..f0fb7c0d 100644 Binary files a/_downloads/b793257364ec7e73fe09d6ac0cf897bb/linop-3.pdf and b/_downloads/b793257364ec7e73fe09d6ac0cf897bb/linop-3.pdf differ diff --git a/_downloads/b9ab671fb0a7f18372db2008f8f175b3/operator-2.png b/_downloads/b9ab671fb0a7f18372db2008f8f175b3/operator-2.png deleted file mode 100644 index c4e9be08..00000000 Binary files a/_downloads/b9ab671fb0a7f18372db2008f8f175b3/operator-2.png and /dev/null differ diff --git a/_downloads/bb645b33928b6e51d2976522ee8f3806/experimental-sampler-1_01_00.hires.png b/_downloads/bb645b33928b6e51d2976522ee8f3806/experimental-sampler-1_01_00.hires.png index 0d12f76f..c0aa3e34 100644 Binary files a/_downloads/bb645b33928b6e51d2976522ee8f3806/experimental-sampler-1_01_00.hires.png and b/_downloads/bb645b33928b6e51d2976522ee8f3806/experimental-sampler-1_01_00.hires.png differ diff --git a/_downloads/beadf23da07c5206cde021558c7f49fa/linop-3_01.pdf b/_downloads/beadf23da07c5206cde021558c7f49fa/linop-3_01.pdf deleted file mode 100644 index 10cb5062..00000000 Binary files a/_downloads/beadf23da07c5206cde021558c7f49fa/linop-3_01.pdf and /dev/null differ diff --git a/_downloads/bf001791fa8cc4ac5b9c6369e6c26d9b/linop-4_00.pdf b/_downloads/bf001791fa8cc4ac5b9c6369e6c26d9b/linop-4_00.pdf deleted file mode 100644 index 763a4552..00000000 Binary files a/_downloads/bf001791fa8cc4ac5b9c6369e6c26d9b/linop-4_00.pdf and /dev/null differ diff --git a/_downloads/c0190b5d57d3d151adb5651d8b8a1ee5/linop-10.pdf b/_downloads/c0190b5d57d3d151adb5651d8b8a1ee5/linop-10.pdf deleted file mode 100644 index 3f17e6f3..00000000 Binary files a/_downloads/c0190b5d57d3d151adb5651d8b8a1ee5/linop-10.pdf and /dev/null differ diff --git a/_downloads/c287d657992e4ff9fb0cd17bed7a0b5b/operator-4_01.pdf b/_downloads/c287d657992e4ff9fb0cd17bed7a0b5b/operator-4_01.pdf deleted file mode 100644 index 1aeb73ca..00000000 Binary files a/_downloads/c287d657992e4ff9fb0cd17bed7a0b5b/operator-4_01.pdf and /dev/null differ diff --git a/_downloads/c391db68b8dc3c5e9af1e480d97b4c31/operator-14.png b/_downloads/c391db68b8dc3c5e9af1e480d97b4c31/operator-14.png deleted file mode 100644 index c28982cb..00000000 Binary files a/_downloads/c391db68b8dc3c5e9af1e480d97b4c31/operator-14.png and /dev/null differ diff --git a/_downloads/c4dc0f0fa9d2ce5348b916d5ee685aba/operator-21_03.hires.png b/_downloads/c4dc0f0fa9d2ce5348b916d5ee685aba/operator-21_03.hires.png deleted file mode 100644 index 1ad6d173..00000000 Binary files a/_downloads/c4dc0f0fa9d2ce5348b916d5ee685aba/operator-21_03.hires.png and /dev/null differ diff --git a/_downloads/c5a9926c064600f986df1e9b30229987/operator-13_00.hires.png b/_downloads/c5a9926c064600f986df1e9b30229987/operator-13_00.hires.png deleted file mode 100644 index 4d5d2c76..00000000 Binary files a/_downloads/c5a9926c064600f986df1e9b30229987/operator-13_00.hires.png and /dev/null differ diff --git a/_downloads/c6700c20988494320e4fca76fe07c2f7/linop-16.pdf b/_downloads/c6700c20988494320e4fca76fe07c2f7/linop-16.pdf index 1c5b816a..e1d0d7f1 100644 Binary files a/_downloads/c6700c20988494320e4fca76fe07c2f7/linop-16.pdf and b/_downloads/c6700c20988494320e4fca76fe07c2f7/linop-16.pdf differ diff --git a/_downloads/c69c5719c815b1c976384c957f6e9777/operator-11_02.png b/_downloads/c69c5719c815b1c976384c957f6e9777/operator-11_02.png deleted file mode 100644 index 785b9e79..00000000 Binary files a/_downloads/c69c5719c815b1c976384c957f6e9777/operator-11_02.png and /dev/null differ diff --git a/_downloads/c6b0f3c315acd2b5a9a28ec22e1ea553/linop-13_00.png b/_downloads/c6b0f3c315acd2b5a9a28ec22e1ea553/linop-13_00.png deleted file mode 100644 index 29997314..00000000 Binary files a/_downloads/c6b0f3c315acd2b5a9a28ec22e1ea553/linop-13_00.png and /dev/null differ diff --git a/_downloads/c6b377da5d37f9a1a7bd869cb238734f/operator-4.py b/_downloads/c6b377da5d37f9a1a7bd869cb238734f/operator-4.py deleted file mode 100644 index bfe7ebc3..00000000 --- a/_downloads/c6b377da5d37f9a1a7bd869cb238734f/operator-4.py +++ /dev/null @@ -1,33 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import PartialDerivative -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) -arg_shape = image.shape # Shape of our image -# Specify derivative order at each direction -df_dx = (1, 0) # Compute derivative of order 1 in first dimension -d2f_dy2 = (0, 2) # Compute derivative of order 2 in second dimension -d3f_dxdy2 = (1, 2) # Compute derivative of order 1 in first dimension and der. of order 2 in second dimension -# Instantiate derivative operators -diff1 = PartialDerivative.gaussian_derivative(order=df_dx, arg_shape=arg_shape, sigma=2.0) -diff2 = PartialDerivative.gaussian_derivative(order=d2f_dy2, arg_shape=arg_shape, sigma=2.0) -diff = PartialDerivative.gaussian_derivative(order=d3f_dxdy2, arg_shape=arg_shape, sigma=2.0) -# Compute derivatives -out1 = (diff1 * diff2)(image.ravel()).reshape(arg_shape) -out2 = diff(image.ravel()).reshape(arg_shape) -plt.figure() -plt.imshow(image), -plt.axis('off') -plt.colorbar() -plt.title('f(x,y)') -plt.figure() -plt.imshow(out1.T) -plt.axis('off') -plt.title(r'$\frac{\partial^{3} f(x,y)}{\partial x\partial y^{2}}$') -plt.figure() -plt.imshow(out2.T) -plt.axis('off') -plt.title(r'$\frac{\partial^{3} f(x,y)}{\partial x\partial y^{2}}$') \ No newline at end of file diff --git a/_downloads/c6cc146e09111e224dd32387b5f48af9/operator-11_01.hires.png b/_downloads/c6cc146e09111e224dd32387b5f48af9/operator-11_01.hires.png deleted file mode 100644 index 9dfd8018..00000000 Binary files a/_downloads/c6cc146e09111e224dd32387b5f48af9/operator-11_01.hires.png and /dev/null differ diff --git a/_downloads/c722cabc6093f717e47975d57ffbc907/operator-5.py b/_downloads/c722cabc6093f717e47975d57ffbc907/operator-5.py deleted file mode 100644 index caacd6b1..00000000 --- a/_downloads/c722cabc6093f717e47975d57ffbc907/operator-5.py +++ /dev/null @@ -1,34 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import Gradient -from pyxu.util.misc import peaks - -# Define input image -n = 100 -x = np.linspace(-3, 3, n) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) -arg_shape = image.shape # (1000, 1000) -# Instantiate gradient operator -grad = Gradient(arg_shape=arg_shape) - -# Compute gradients -output = grad(image.ravel()) # shape = (2000000, ) -df_dx, df_dy = grad.unravel(output) # shape = (2, 1000, 1000) - -# Plot image -fig, axs = plt.subplots(1, 3, figsize=(15, 4)) -im = axs[0].imshow(image) -axs[0].set_title("Image") -axs[0].axis("off") -plt.colorbar(im, ax=axs[0]) - -# Plot gradient -im = axs[1].imshow(df_dx) -axs[1].set_title(r"$\partial f/ \partial x$") -axs[1].axis("off") -plt.colorbar(im, ax=axs[1]) -im = axs[2].imshow(df_dy) -axs[2].set_title(r"$\partial f/ \partial y$") -axs[2].axis("off") -plt.colorbar(im, ax=axs[2]) \ No newline at end of file diff --git a/_downloads/c8a864597bcad6d39da2ef420e9ea684/linop-19_00.pdf b/_downloads/c8a864597bcad6d39da2ef420e9ea684/linop-19_00.pdf index 35c0d02f..5160218f 100644 Binary files a/_downloads/c8a864597bcad6d39da2ef420e9ea684/linop-19_00.pdf and b/_downloads/c8a864597bcad6d39da2ef420e9ea684/linop-19_00.pdf differ diff --git a/_downloads/c935bd338de06e762ff0060037d2bdbf/linop-4_00.png b/_downloads/c935bd338de06e762ff0060037d2bdbf/linop-4_00.png deleted file mode 100644 index fccd452c..00000000 Binary files a/_downloads/c935bd338de06e762ff0060037d2bdbf/linop-4_00.png and /dev/null differ diff --git a/_downloads/ca2090d31fc0a86e6382087c1b5955b0/operator-1.hires.png b/_downloads/ca2090d31fc0a86e6382087c1b5955b0/operator-1.hires.png deleted file mode 100644 index 1eda77c6..00000000 Binary files a/_downloads/ca2090d31fc0a86e6382087c1b5955b0/operator-1.hires.png and /dev/null differ diff --git a/_downloads/cac3dcf5082691d7fec7aafb5a70b646/operator-8.py b/_downloads/cac3dcf5082691d7fec7aafb5a70b646/operator-8.py deleted file mode 100644 index a64c708c..00000000 --- a/_downloads/cac3dcf5082691d7fec7aafb5a70b646/operator-8.py +++ /dev/null @@ -1,38 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import Hessian, PartialDerivative -from pyxu.util.misc import peaks - -n = 100 -x = np.linspace(-3, 3, n) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) -arg_shape = image.shape # (1000, 1000) - -# Instantiate Hessian operator -hessian = Hessian(arg_shape=arg_shape, directions="all") -# Compute Hessian -output = hessian(image.ravel()) # shape = (300000,) -d2f_dx2, d2f_dxdy, d2f_dy2 = hessian.unravel(output) - -# Plot -fig, axs = plt.subplots(1, 4, figsize=(20, 4)) -im = axs[0].imshow(image) -plt.colorbar(im, ax=axs[0]) -axs[0].set_title("Image") -axs[0].axis("off") - -im = axs[1].imshow(d2f_dx2) -plt.colorbar(im, ax=axs[1]) -axs[1].set_title(r"$\partial^{2} f/ \partial x^{2}$") -axs[1].axis("off") - -im = axs[2].imshow(d2f_dxdy) -plt.colorbar(im, ax=axs[2]) -axs[2].set_title(r"$\partial^{2} f/ \partial x\partial y$") -axs[2].axis("off") - -im = axs[3].imshow(d2f_dy2) -plt.colorbar(im, ax=axs[3]) -axs[3].set_title(r"$\partial^{2} f/ \partial y^{2}$") -axs[3].axis("off") \ No newline at end of file diff --git a/_downloads/cb592e426f343abde6179a6c6c588c24/operator-8.png b/_downloads/cb592e426f343abde6179a6c6c588c24/operator-8.png deleted file mode 100644 index d6d0749e..00000000 Binary files a/_downloads/cb592e426f343abde6179a6c6c588c24/operator-8.png and /dev/null differ diff --git a/_downloads/cde91f0a039a2f1ff6788278b2648951/operator-18.png b/_downloads/cde91f0a039a2f1ff6788278b2648951/operator-18.png deleted file mode 100644 index 7abd9e38..00000000 Binary files a/_downloads/cde91f0a039a2f1ff6788278b2648951/operator-18.png and /dev/null differ diff --git a/_downloads/ce73cbbc77dfb793bac0675acf730767/linop-19_02.pdf b/_downloads/ce73cbbc77dfb793bac0675acf730767/linop-19_02.pdf index 3fd24a4c..e5ff4774 100644 Binary files a/_downloads/ce73cbbc77dfb793bac0675acf730767/linop-19_02.pdf and b/_downloads/ce73cbbc77dfb793bac0675acf730767/linop-19_02.pdf differ diff --git a/_downloads/d0179760969d96a450497e7728d72b0c/operator-13_02.pdf b/_downloads/d0179760969d96a450497e7728d72b0c/operator-13_02.pdf deleted file mode 100644 index c6c48cef..00000000 Binary files a/_downloads/d0179760969d96a450497e7728d72b0c/operator-13_02.pdf and /dev/null differ diff --git a/_downloads/d033201855f1ac9d7e8eb509601ad103/operator-20.py b/_downloads/d033201855f1ac9d7e8eb509601ad103/operator-20.py deleted file mode 100644 index e2a1b717..00000000 --- a/_downloads/d033201855f1ac9d7e8eb509601ad103/operator-20.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import Scharr - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -scharr = Scharr(arg_shape) -out = scharr(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_downloads/d1d43d473b0f4368b7c6e91e21b490e0/operator-5.hires.png b/_downloads/d1d43d473b0f4368b7c6e91e21b490e0/operator-5.hires.png deleted file mode 100644 index c1509f28..00000000 Binary files a/_downloads/d1d43d473b0f4368b7c6e91e21b490e0/operator-5.hires.png and /dev/null differ diff --git a/_downloads/d334da298262f6838cd851168625d306/operator-11_01.png b/_downloads/d334da298262f6838cd851168625d306/operator-11_01.png deleted file mode 100644 index 26f76494..00000000 Binary files a/_downloads/d334da298262f6838cd851168625d306/operator-11_01.png and /dev/null differ diff --git a/_downloads/d94d98623f466a362f24485e332111fc/linop-13_02.png b/_downloads/d94d98623f466a362f24485e332111fc/linop-13_02.png deleted file mode 100644 index d66751f8..00000000 Binary files a/_downloads/d94d98623f466a362f24485e332111fc/linop-13_02.png and /dev/null differ diff --git a/_downloads/d95682f2902576513757e8747a4f94d8/operator-9.py b/_downloads/d95682f2902576513757e8747a4f94d8/operator-9.py deleted file mode 100644 index ccb1eef9..00000000 --- a/_downloads/d95682f2902576513757e8747a4f94d8/operator-9.py +++ /dev/null @@ -1,29 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import Laplacian -from pyxu.util.misc import peaks - -# Define input image -n = 100 -x = np.linspace(-3, 3, n) -xx, yy = np.meshgrid(x, x) -image = peaks(xx, yy) - -arg_shape = image.shape # (1000, 1000) -# Compute Laplacian -laplacian = Laplacian(arg_shape=arg_shape) -output = laplacian(image.ravel()) -output = laplacian.unravel(output) # shape = (1, 1000, 1000) -# Plot -fig, axs = plt.subplots(1, 2, figsize=(10, 4)) -im = axs[0].imshow(image) -plt.colorbar(im, ax=axs[0]) -axs[0].set_title("Image") -axs[0].axis("off") - -im = axs[1].imshow(output.squeeze()) -plt.colorbar(im, ax=axs[1]) -axs[1].set_title(r"$\partial^{2} f/ \partial x^{2}+\partial^{2} f/ \partial y^{2}$") -axs[1].axis("off") - -fig.show() \ No newline at end of file diff --git a/_downloads/db9ac5fbbfe21a45f644cc919f758da2/opt-solver-1.pdf b/_downloads/db9ac5fbbfe21a45f644cc919f758da2/opt-solver-1.pdf index e1684d5b..bcf0b987 100644 Binary files a/_downloads/db9ac5fbbfe21a45f644cc919f758da2/opt-solver-1.pdf and b/_downloads/db9ac5fbbfe21a45f644cc919f758da2/opt-solver-1.pdf differ diff --git a/_downloads/dbc53e64d0cae8e637f47735d895aafa/linop-20_00.pdf b/_downloads/dbc53e64d0cae8e637f47735d895aafa/linop-20_00.pdf index 647f707e..c4832cfc 100644 Binary files a/_downloads/dbc53e64d0cae8e637f47735d895aafa/linop-20_00.pdf and b/_downloads/dbc53e64d0cae8e637f47735d895aafa/linop-20_00.pdf differ diff --git a/_downloads/dbc64e26ca6edbd26084bb910e4ff9f7/linop-4_02.hires.png b/_downloads/dbc64e26ca6edbd26084bb910e4ff9f7/linop-4_02.hires.png deleted file mode 100644 index afc1e2cf..00000000 Binary files a/_downloads/dbc64e26ca6edbd26084bb910e4ff9f7/linop-4_02.hires.png and /dev/null differ diff --git a/_downloads/dbd13b2660ccf8ff01353b1a063aaa1c/operator-21_01.png b/_downloads/dbd13b2660ccf8ff01353b1a063aaa1c/operator-21_01.png deleted file mode 100644 index 987409c8..00000000 Binary files a/_downloads/dbd13b2660ccf8ff01353b1a063aaa1c/operator-21_01.png and /dev/null differ diff --git a/_downloads/dc98e14e812e6f847c4fbabc802e630d/linop-4_02.pdf b/_downloads/dc98e14e812e6f847c4fbabc802e630d/linop-4_02.pdf deleted file mode 100644 index 2e7585c5..00000000 Binary files a/_downloads/dc98e14e812e6f847c4fbabc802e630d/linop-4_02.pdf and /dev/null differ diff --git a/_downloads/ddb65118b9c2654fdc8b8c39e75cc610/operator-12_00.pdf b/_downloads/ddb65118b9c2654fdc8b8c39e75cc610/operator-12_00.pdf deleted file mode 100644 index 22296cd6..00000000 Binary files a/_downloads/ddb65118b9c2654fdc8b8c39e75cc610/operator-12_00.pdf and /dev/null differ diff --git a/_downloads/de67bbc9a9bee54b9f36845451ed1c4e/linop-10_01.pdf b/_downloads/de67bbc9a9bee54b9f36845451ed1c4e/linop-10_01.pdf index 09f435ab..534c0c96 100644 Binary files a/_downloads/de67bbc9a9bee54b9f36845451ed1c4e/linop-10_01.pdf and b/_downloads/de67bbc9a9bee54b9f36845451ed1c4e/linop-10_01.pdf differ diff --git a/_downloads/e0edab28ffa8a7b21d2c5383d9cb8c12/operator-3_00.png b/_downloads/e0edab28ffa8a7b21d2c5383d9cb8c12/operator-3_00.png deleted file mode 100644 index fe4dbf22..00000000 Binary files a/_downloads/e0edab28ffa8a7b21d2c5383d9cb8c12/operator-3_00.png and /dev/null differ diff --git a/_downloads/e0eefa74af9eff0db39630aafbdd32db/linop-11_01.pdf b/_downloads/e0eefa74af9eff0db39630aafbdd32db/linop-11_01.pdf index 67830bce..1d1092f9 100644 Binary files a/_downloads/e0eefa74af9eff0db39630aafbdd32db/linop-11_01.pdf and b/_downloads/e0eefa74af9eff0db39630aafbdd32db/linop-11_01.pdf differ diff --git a/_downloads/e1a75dcc78d38d076dc2ecbd8c33f9ad/linop-11.py b/_downloads/e1a75dcc78d38d076dc2ecbd8c33f9ad/linop-11.py index 725e0ddf..9b92fec1 100644 --- a/_downloads/e1a75dcc78d38d076dc2ecbd8c33f9ad/linop-11.py +++ b/_downloads/e1a75dcc78d38d076dc2ecbd8c33f9ad/linop-11.py @@ -35,6 +35,6 @@ axs[2].set_title(r"$\frac{\partial^{3} f(x,y)}{\partial x\partial y^{2}}$") plt.colorbar(im, ax=axs[2]) -# Test approximation error +# Check approximation error plt.figure() -plt.imshow(abs(out1 - out2) / abs(out2)), plt.colorbar() \ No newline at end of file +plt.imshow(abs(out1 - out2)), plt.colorbar() \ No newline at end of file diff --git a/_downloads/e1c2f45952876293feb161611e3c2d06/linop-19.png b/_downloads/e1c2f45952876293feb161611e3c2d06/linop-19.png deleted file mode 100644 index 7abd9e38..00000000 Binary files a/_downloads/e1c2f45952876293feb161611e3c2d06/linop-19.png and /dev/null differ diff --git a/_downloads/e52263af1a66ae9a23ee58f7c56f3a6f/linop-13_03.pdf b/_downloads/e52263af1a66ae9a23ee58f7c56f3a6f/linop-13_03.pdf deleted file mode 100644 index 00bf9f22..00000000 Binary files a/_downloads/e52263af1a66ae9a23ee58f7c56f3a6f/linop-13_03.pdf and /dev/null differ diff --git a/_downloads/e6d7379beda9ef38f71609f23015c745/opt-2.pdf b/_downloads/e6d7379beda9ef38f71609f23015c745/opt-2.pdf deleted file mode 100644 index 6e9c13ad..00000000 Binary files a/_downloads/e6d7379beda9ef38f71609f23015c745/opt-2.pdf and /dev/null differ diff --git a/_downloads/e739c7c86eb1e91d889c2ba6a4a6af52/operator-21_03.png b/_downloads/e739c7c86eb1e91d889c2ba6a4a6af52/operator-21_03.png deleted file mode 100644 index 825b173b..00000000 Binary files a/_downloads/e739c7c86eb1e91d889c2ba6a4a6af52/operator-21_03.png and /dev/null differ diff --git a/_downloads/e86ae7ff57577dab32fe27b228573552/misc-1.pdf b/_downloads/e86ae7ff57577dab32fe27b228573552/misc-1.pdf index 4acc0453..a046374d 100644 Binary files a/_downloads/e86ae7ff57577dab32fe27b228573552/misc-1.pdf and b/_downloads/e86ae7ff57577dab32fe27b228573552/misc-1.pdf differ diff --git a/_downloads/e8cf3ce50f34b6ff0831d06aeebabca8/linop-6.pdf b/_downloads/e8cf3ce50f34b6ff0831d06aeebabca8/linop-6.pdf index cbf1aceb..8f37ba7f 100644 Binary files a/_downloads/e8cf3ce50f34b6ff0831d06aeebabca8/linop-6.pdf and b/_downloads/e8cf3ce50f34b6ff0831d06aeebabca8/linop-6.pdf differ diff --git a/_downloads/e8d0761a439aeaea00dcf73a4a90445e/experimental-1_00_00.png b/_downloads/e8d0761a439aeaea00dcf73a4a90445e/experimental-1_00_00.png deleted file mode 100644 index ce654ae3..00000000 Binary files a/_downloads/e8d0761a439aeaea00dcf73a4a90445e/experimental-1_00_00.png and /dev/null differ diff --git a/_downloads/e8ddacc83821817f83af535a3fdc0c3d/operator-10.pdf b/_downloads/e8ddacc83821817f83af535a3fdc0c3d/operator-10.pdf deleted file mode 100644 index 3226d41a..00000000 Binary files a/_downloads/e8ddacc83821817f83af535a3fdc0c3d/operator-10.pdf and /dev/null differ diff --git a/_downloads/e92a40fb9538516e44ee3d2080a0bba4/opt-3.png b/_downloads/e92a40fb9538516e44ee3d2080a0bba4/opt-3.png deleted file mode 100644 index b769785d..00000000 Binary files a/_downloads/e92a40fb9538516e44ee3d2080a0bba4/opt-3.png and /dev/null differ diff --git a/_downloads/e9c0199593213119a01b24588af34368/linop-20.pdf b/_downloads/e9c0199593213119a01b24588af34368/linop-20.pdf deleted file mode 100644 index c74274cd..00000000 Binary files a/_downloads/e9c0199593213119a01b24588af34368/linop-20.pdf and /dev/null differ diff --git a/_downloads/ea065ef29eb66de1c45bbe0702cc77be/operator-17.png b/_downloads/ea065ef29eb66de1c45bbe0702cc77be/operator-17.png deleted file mode 100644 index 46f5ec1b..00000000 Binary files a/_downloads/ea065ef29eb66de1c45bbe0702cc77be/operator-17.png and /dev/null differ diff --git a/_downloads/ebb87a8c84008c9385f6e91393987384/linop-11_02.png b/_downloads/ebb87a8c84008c9385f6e91393987384/linop-11_02.png deleted file mode 100644 index 785b9e79..00000000 Binary files a/_downloads/ebb87a8c84008c9385f6e91393987384/linop-11_02.png and /dev/null differ diff --git a/_downloads/ebca942ca6e14d7ba2eabcfc752dc3ce/linop-20_01.pdf b/_downloads/ebca942ca6e14d7ba2eabcfc752dc3ce/linop-20_01.pdf index fb57006c..3c955e12 100644 Binary files a/_downloads/ebca942ca6e14d7ba2eabcfc752dc3ce/linop-20_01.pdf and b/_downloads/ebca942ca6e14d7ba2eabcfc752dc3ce/linop-20_01.pdf differ diff --git a/_downloads/ebd30b8cac6ffa23638f86e7e0cbfcf8/operator-4_01.hires.png b/_downloads/ebd30b8cac6ffa23638f86e7e0cbfcf8/operator-4_01.hires.png deleted file mode 100644 index b50b6dfb..00000000 Binary files a/_downloads/ebd30b8cac6ffa23638f86e7e0cbfcf8/operator-4_01.hires.png and /dev/null differ diff --git a/_downloads/ebda9c8427d0061add5c36d23ac72518/operator-21_03.pdf b/_downloads/ebda9c8427d0061add5c36d23ac72518/operator-21_03.pdf deleted file mode 100644 index eab1a645..00000000 Binary files a/_downloads/ebda9c8427d0061add5c36d23ac72518/operator-21_03.pdf and /dev/null differ diff --git a/_downloads/ec62b0e358ee5c0b4fe48a7f14c93a09/operator-3_00.pdf b/_downloads/ec62b0e358ee5c0b4fe48a7f14c93a09/operator-3_00.pdf deleted file mode 100644 index 54c761a2..00000000 Binary files a/_downloads/ec62b0e358ee5c0b4fe48a7f14c93a09/operator-3_00.pdf and /dev/null differ diff --git a/_downloads/ecac7b967e6cb984424af14d8b946bce/operator-13_01.hires.png b/_downloads/ecac7b967e6cb984424af14d8b946bce/operator-13_01.hires.png deleted file mode 100644 index 9ccc6d00..00000000 Binary files a/_downloads/ecac7b967e6cb984424af14d8b946bce/operator-13_01.hires.png and /dev/null differ diff --git a/_downloads/ecb8cc6e01fafd628c1f3f5476756590/operator-21_00.png b/_downloads/ecb8cc6e01fafd628c1f3f5476756590/operator-21_00.png deleted file mode 100644 index 5fa0c071..00000000 Binary files a/_downloads/ecb8cc6e01fafd628c1f3f5476756590/operator-21_00.png and /dev/null differ diff --git a/_downloads/edea08851573d4f271df708dfee884d4/linop-21.pdf b/_downloads/edea08851573d4f271df708dfee884d4/linop-21.pdf deleted file mode 100644 index 57f1ad19..00000000 Binary files a/_downloads/edea08851573d4f271df708dfee884d4/linop-21.pdf and /dev/null differ diff --git a/_downloads/ee22dc0a66baaeda24d579f4dd50f185/operator-13_01.pdf b/_downloads/ee22dc0a66baaeda24d579f4dd50f185/operator-13_01.pdf deleted file mode 100644 index 8fc34204..00000000 Binary files a/_downloads/ee22dc0a66baaeda24d579f4dd50f185/operator-13_01.pdf and /dev/null differ diff --git a/_downloads/ee39cd6f03890e23e667a22fcfb0878d/operator-13_01.png b/_downloads/ee39cd6f03890e23e667a22fcfb0878d/operator-13_01.png deleted file mode 100644 index df404bc2..00000000 Binary files a/_downloads/ee39cd6f03890e23e667a22fcfb0878d/operator-13_01.png and /dev/null differ diff --git a/_downloads/ee7aa894b3da122692fdf69beafcbe37/operator-1.pdf b/_downloads/ee7aa894b3da122692fdf69beafcbe37/operator-1.pdf deleted file mode 100644 index 1acc3bfe..00000000 Binary files a/_downloads/ee7aa894b3da122692fdf69beafcbe37/operator-1.pdf and /dev/null differ diff --git a/_downloads/ef2ed6b8376eb7464b1d4b22cdf87266/linop-10_02.pdf b/_downloads/ef2ed6b8376eb7464b1d4b22cdf87266/linop-10_02.pdf index 7249c5fd..10a3b6dc 100644 Binary files a/_downloads/ef2ed6b8376eb7464b1d4b22cdf87266/linop-10_02.pdf and b/_downloads/ef2ed6b8376eb7464b1d4b22cdf87266/linop-10_02.pdf differ diff --git a/_downloads/ef375de8a555744bde8d66d2be4d2ecd/linop-4.pdf b/_downloads/ef375de8a555744bde8d66d2be4d2ecd/linop-4.pdf index 02b28ac9..deb42a0f 100644 Binary files a/_downloads/ef375de8a555744bde8d66d2be4d2ecd/linop-4.pdf and b/_downloads/ef375de8a555744bde8d66d2be4d2ecd/linop-4.pdf differ diff --git a/_downloads/eff18b5fef44d9c0d77331121a291e8f/operator-11.py b/_downloads/eff18b5fef44d9c0d77331121a291e8f/operator-11.py deleted file mode 100644 index 06c3a954..00000000 --- a/_downloads/eff18b5fef44d9c0d77331121a291e8f/operator-11.py +++ /dev/null @@ -1,31 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import DirectionalGradient -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -z = peaks(xx, yy) -directions1 = np.zeros(shape=(2, z.size)) -directions1[0, :z.size // 2] = 1 -directions1[1, z.size // 2:] = 1 -directions2 = np.zeros(shape=(2, z.size)) -directions2[1, :z.size // 2] = -1 -directions2[0, z.size // 2:] = -1 -arg_shape = z.shape -dop = DirectionalGradient(arg_shape=arg_shape, directions=[directions1, directions2]) -out = dop.unravel(dop(z.ravel())) -plt.figure() -h = plt.pcolormesh(xx, yy, z, shading='auto') -plt.quiver(x, x, directions1[1].reshape(arg_shape), directions1[0].reshape(xx.shape)) -plt.quiver(x, x, directions2[1].reshape(arg_shape), directions2[0].reshape(xx.shape), color='red') -plt.colorbar(h) -plt.title(r'Signal $\mathbf{f}$ and directions of derivatives') -plt.figure() -h = plt.pcolormesh(xx, yy, out[0], shading='auto') -plt.colorbar(h) -plt.title(r'$\nabla_{\mathbf{v}_0} \mathbf{f}$') -plt.figure() -h = plt.pcolormesh(xx, yy, out[1], shading='auto') -plt.colorbar(h) -plt.title(r'$\nabla_{\mathbf{v}_1} \mathbf{f}$') \ No newline at end of file diff --git a/_downloads/f2dd49c204e444011bf0c8ee51349779/opt-1.py b/_downloads/f2dd49c204e444011bf0c8ee51349779/opt-1.py deleted file mode 100644 index 982b2492..00000000 --- a/_downloads/f2dd49c204e444011bf0c8ee51349779/opt-1.py +++ /dev/null @@ -1,31 +0,0 @@ -import matplotlib.pyplot as plt -import numpy as np -import pyxu.operator as pxo -from pyxu.experimental._dev import DownSampling, FirstDerivative -from pyxu.opt.solver import CV - -x = np.repeat(np.asarray([0, 2, 1, 3, 0, 2, 0]), 10) -N = x.size - -D = FirstDerivative(size=N, kind="forward") -D.lipschitz = D.estimate_lipschitz() - -downsample = DownSampling(size=N, downsampling_factor=3) -y = downsample(x) -loss = (1 / 2) * pxo.SquaredL2Norm(y.size).argshift(-y) -F = loss * downsample -F.diff_lipschitz = F.estimate_diff_lipschitz() - -cv = CV(f=F, g=0.01 * pxo.L1Norm(N), h=0.1 * pxo.L1Norm(N), K=D) -x0, z0 = np.zeros((2, N)) -cv.fit(x0=x0, z0=z0) -x_recons = cv.solution()[0] - -plt.figure() -plt.stem(x, linefmt="C0-", markerfmt="C0o") -mask_ids = np.where(downsample.downsampling_mask)[0] -markerline, stemlines, baseline = plt.stem(mask_ids, y, linefmt="C3-", markerfmt="C3o") -markerline.set_markerfacecolor("none") -plt.stem(x_recons, linefmt="C1--", markerfmt="C1s") -plt.legend(["Ground truth", "Observation", "CV Estimate"]) -plt.show() \ No newline at end of file diff --git a/_downloads/f32070409f4c8c535a15508855b9e463/linop-21_02.pdf b/_downloads/f32070409f4c8c535a15508855b9e463/linop-21_02.pdf index 9a068ceb..b65f4c88 100644 Binary files a/_downloads/f32070409f4c8c535a15508855b9e463/linop-21_02.pdf and b/_downloads/f32070409f4c8c535a15508855b9e463/linop-21_02.pdf differ diff --git a/_downloads/f363b074be57f30d62e32feccedb67e8/experimental-sampler-1_00_00.png b/_downloads/f363b074be57f30d62e32feccedb67e8/experimental-sampler-1_00_00.png index c147aa54..684c09e3 100644 Binary files a/_downloads/f363b074be57f30d62e32feccedb67e8/experimental-sampler-1_00_00.png and b/_downloads/f363b074be57f30d62e32feccedb67e8/experimental-sampler-1_00_00.png differ diff --git a/_downloads/f54ac688c85e54a5c4e01ac51d047db1/operator-10.py b/_downloads/f54ac688c85e54a5c4e01ac51d047db1/operator-10.py deleted file mode 100644 index 1f191681..00000000 --- a/_downloads/f54ac688c85e54a5c4e01ac51d047db1/operator-10.py +++ /dev/null @@ -1,29 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt -from pyxu.operator import DirectionalDerivative -from pyxu.util.misc import peaks - -x = np.linspace(-2.5, 2.5, 25) -xx, yy = np.meshgrid(x, x) -z = peaks(xx, yy) -directions = np.zeros(shape=(2, z.size)) -directions[0, : z.size // 2] = 1 -directions[1, z.size // 2:] = 1 -dop = DirectionalDerivative(arg_shape=z.shape, order=1, directions=directions) -out = dop.unravel(dop(z.ravel())) -dop2 = DirectionalDerivative(arg_shape=z.shape, order=2, directions=directions) -out2 = dop2.unravel(dop2(z.ravel())) -fig, axs = plt.subplots(1, 3, figsize=(15, 5)) -axs = np.ravel(axs) -h = axs[0].pcolormesh(xx, yy, z, shading="auto") -axs[0].quiver(x, x, directions[1].reshape(xx.shape), directions[0].reshape(xx.shape)) -plt.colorbar(h, ax=axs[0]) -axs[0].set_title("Signal and directions of first derivatives") - -h = axs[1].pcolormesh(xx, yy, out.squeeze(), shading="auto") -plt.colorbar(h, ax=axs[1]) -axs[1].set_title("First-order directional derivatives") - -h = axs[2].pcolormesh(xx, yy, out2.squeeze(), shading="auto") -plt.colorbar(h, ax=axs[2]) -axs[2].set_title("Second-order directional derivative") \ No newline at end of file diff --git a/_downloads/f6fdcb1dac293e403daf6b44a63a0a98/linop-19_01.pdf b/_downloads/f6fdcb1dac293e403daf6b44a63a0a98/linop-19_01.pdf index 7ed446be..fa468629 100644 Binary files a/_downloads/f6fdcb1dac293e403daf6b44a63a0a98/linop-19_01.pdf and b/_downloads/f6fdcb1dac293e403daf6b44a63a0a98/linop-19_01.pdf differ diff --git a/_downloads/f9ba4343980bdb8f37da0283f3a6d97e/linop-10.hires.png b/_downloads/f9ba4343980bdb8f37da0283f3a6d97e/linop-10.hires.png deleted file mode 100644 index fae722c2..00000000 Binary files a/_downloads/f9ba4343980bdb8f37da0283f3a6d97e/linop-10.hires.png and /dev/null differ diff --git a/_downloads/fa1e9c492a3642cd6b2e4edb05885d27/operator-11_01.pdf b/_downloads/fa1e9c492a3642cd6b2e4edb05885d27/operator-11_01.pdf deleted file mode 100644 index 1017a0fd..00000000 Binary files a/_downloads/fa1e9c492a3642cd6b2e4edb05885d27/operator-11_01.pdf and /dev/null differ diff --git a/_downloads/fb2a08c73290a1f099ce4f662f384ba8/operator-3_01.pdf b/_downloads/fb2a08c73290a1f099ce4f662f384ba8/operator-3_01.pdf deleted file mode 100644 index eb3df032..00000000 Binary files a/_downloads/fb2a08c73290a1f099ce4f662f384ba8/operator-3_01.pdf and /dev/null differ diff --git a/_downloads/fd4ec1dae59f3f8ce46dd8ad9d29ad84/linop-12_00.pdf b/_downloads/fd4ec1dae59f3f8ce46dd8ad9d29ad84/linop-12_00.pdf index de0a3e38..02838a25 100644 Binary files a/_downloads/fd4ec1dae59f3f8ce46dd8ad9d29ad84/linop-12_00.pdf and b/_downloads/fd4ec1dae59f3f8ce46dd8ad9d29ad84/linop-12_00.pdf differ diff --git a/_downloads/fe6968ec011cf22e38035319bd778af2/operator-9.png b/_downloads/fe6968ec011cf22e38035319bd778af2/operator-9.png deleted file mode 100644 index 458adf0d..00000000 Binary files a/_downloads/fe6968ec011cf22e38035319bd778af2/operator-9.png and /dev/null differ diff --git a/_downloads/feb0d965c7c0bb35ac098ec3ef67df61/operator-14.py b/_downloads/feb0d965c7c0bb35ac098ec3ef67df61/operator-14.py deleted file mode 100644 index d7c5085f..00000000 --- a/_downloads/feb0d965c7c0bb35ac098ec3ef67df61/operator-14.py +++ /dev/null @@ -1,16 +0,0 @@ -import matplotlib.pyplot as plt -from pyxu.operator import MovingAverage - -arg_shape = (11, 11) -image = np.zeros(arg_shape) -image[5, 5] = 1. - -ma = MovingAverage(arg_shape, size=5) -out = ma(image.ravel()) -plt.figure(figsize=(10, 5)) -plt.subplot(121) -plt.imshow(image) -plt.colorbar() -plt.subplot(122) -plt.imshow(out.reshape(*arg_shape)) -plt.colorbar() \ No newline at end of file diff --git a/_images/examples_Stencils_29_0.png b/_images/examples_Stencils_29_0.png deleted file mode 100644 index 881b65da..00000000 Binary files a/_images/examples_Stencils_29_0.png and /dev/null differ diff --git a/_images/examples_Stencils_26_0.png b/_images/examples_stencils_26_0.png similarity index 100% rename from _images/examples_Stencils_26_0.png rename to _images/examples_stencils_26_0.png diff --git a/_images/examples_Stencils_28_0.png b/_images/examples_stencils_28_0.png similarity index 100% rename from _images/examples_Stencils_28_0.png rename to _images/examples_stencils_28_0.png diff --git a/_images/examples_Stencils_9_0.png b/_images/examples_stencils_9_0.png similarity index 100% rename from _images/examples_Stencils_9_0.png rename to _images/examples_stencils_9_0.png diff --git a/_images/experimental-1_00_00.png b/_images/experimental-1_00_00.png deleted file mode 100644 index ce654ae3..00000000 Binary files a/_images/experimental-1_00_00.png and /dev/null differ diff --git a/_images/experimental-1_01_00.png b/_images/experimental-1_01_00.png deleted file mode 100644 index 5c33d91e..00000000 Binary files a/_images/experimental-1_01_00.png and /dev/null differ diff --git a/_images/experimental-sampler-1_00_00.png b/_images/experimental-sampler-1_00_00.png index c147aa54..684c09e3 100644 Binary files a/_images/experimental-sampler-1_00_00.png and b/_images/experimental-sampler-1_00_00.png differ diff --git a/_images/experimental-sampler-1_01_00.png b/_images/experimental-sampler-1_01_00.png index c8779884..8abb07d6 100644 Binary files a/_images/experimental-sampler-1_01_00.png and b/_images/experimental-sampler-1_01_00.png differ diff --git a/_images/examples_DifferentialOperators_20_0.png b/_images/guide_diff_ops_10_0.png similarity index 100% rename from _images/examples_DifferentialOperators_20_0.png rename to _images/guide_diff_ops_10_0.png diff --git a/_images/examples_DifferentialOperators_31_0.png b/_images/guide_diff_ops_21_0.png similarity index 100% rename from _images/examples_DifferentialOperators_31_0.png rename to _images/guide_diff_ops_21_0.png diff --git a/_images/examples_DifferentialOperators_34_0.png b/_images/guide_diff_ops_24_0.png similarity index 100% rename from _images/examples_DifferentialOperators_34_0.png rename to _images/guide_diff_ops_24_0.png diff --git a/_images/examples_DifferentialOperators_13_1.png b/_images/guide_diff_ops_3_1.png similarity index 100% rename from _images/examples_DifferentialOperators_13_1.png rename to _images/guide_diff_ops_3_1.png diff --git a/_images/examples_DifferentialOperators_19_0.png b/_images/guide_diff_ops_9_0.png similarity index 100% rename from _images/examples_DifferentialOperators_19_0.png rename to _images/guide_diff_ops_9_0.png diff --git a/_images/guide_hpc_10_0.png b/_images/guide_hpc_10_0.png deleted file mode 100644 index b4d72807..00000000 Binary files a/_images/guide_hpc_10_0.png and /dev/null differ diff --git a/_images/linop-10.png b/_images/linop-10.png deleted file mode 100644 index 9df02f1e..00000000 Binary files a/_images/linop-10.png and /dev/null differ diff --git a/_images/linop-11_01.png b/_images/linop-11_01.png index 23895dd6..1e266f6f 100644 Binary files a/_images/linop-11_01.png and b/_images/linop-11_01.png differ diff --git a/_images/linop-11_02.png b/_images/linop-11_02.png deleted file mode 100644 index 785b9e79..00000000 Binary files a/_images/linop-11_02.png and /dev/null differ diff --git a/_images/linop-13_00.png b/_images/linop-13_00.png deleted file mode 100644 index 29997314..00000000 Binary files a/_images/linop-13_00.png and /dev/null differ diff --git a/_images/linop-13_01.png b/_images/linop-13_01.png deleted file mode 100644 index df404bc2..00000000 Binary files a/_images/linop-13_01.png and /dev/null differ diff --git a/_images/linop-13_02.png b/_images/linop-13_02.png deleted file mode 100644 index d66751f8..00000000 Binary files a/_images/linop-13_02.png and /dev/null differ diff --git a/_images/linop-13_03.png b/_images/linop-13_03.png deleted file mode 100644 index 77f49770..00000000 Binary files a/_images/linop-13_03.png and /dev/null differ diff --git a/_images/linop-19.png b/_images/linop-19.png deleted file mode 100644 index 7abd9e38..00000000 Binary files a/_images/linop-19.png and /dev/null differ diff --git a/_images/linop-20.png b/_images/linop-20.png deleted file mode 100644 index cf0cf366..00000000 Binary files a/_images/linop-20.png and /dev/null differ diff --git a/_images/linop-21.png b/_images/linop-21.png deleted file mode 100644 index 707cde96..00000000 Binary files a/_images/linop-21.png and /dev/null differ diff --git a/_images/linop-3_00.png b/_images/linop-3_00.png deleted file mode 100644 index fe4dbf22..00000000 Binary files a/_images/linop-3_00.png and /dev/null differ diff --git a/_images/linop-3_01.png b/_images/linop-3_01.png deleted file mode 100644 index 23895dd6..00000000 Binary files a/_images/linop-3_01.png and /dev/null differ diff --git a/_images/linop-4_00.png b/_images/linop-4_00.png deleted file mode 100644 index fccd452c..00000000 Binary files a/_images/linop-4_00.png and /dev/null differ diff --git a/_images/linop-4_01.png b/_images/linop-4_01.png deleted file mode 100644 index ea2aefc5..00000000 Binary files a/_images/linop-4_01.png and /dev/null differ diff --git a/_images/linop-4_02.png b/_images/linop-4_02.png deleted file mode 100644 index e557225d..00000000 Binary files a/_images/linop-4_02.png and /dev/null differ diff --git a/_images/operator-1.png b/_images/operator-1.png deleted file mode 100644 index 65459407..00000000 Binary files a/_images/operator-1.png and /dev/null differ diff --git a/_images/operator-10.png b/_images/operator-10.png deleted file mode 100644 index 9df02f1e..00000000 Binary files a/_images/operator-10.png and /dev/null differ diff --git a/_images/operator-11_00.png b/_images/operator-11_00.png deleted file mode 100644 index 29997314..00000000 Binary files a/_images/operator-11_00.png and /dev/null differ diff --git a/_images/operator-11_01.png b/_images/operator-11_01.png deleted file mode 100644 index 26f76494..00000000 Binary files a/_images/operator-11_01.png and /dev/null differ diff --git a/_images/operator-11_02.png b/_images/operator-11_02.png deleted file mode 100644 index 785b9e79..00000000 Binary files a/_images/operator-11_02.png and /dev/null differ diff --git a/_images/operator-12_00.png b/_images/operator-12_00.png deleted file mode 100644 index c28866bc..00000000 Binary files a/_images/operator-12_00.png and /dev/null differ diff --git a/_images/operator-12_01.png b/_images/operator-12_01.png deleted file mode 100644 index 07432f15..00000000 Binary files a/_images/operator-12_01.png and /dev/null differ diff --git a/_images/operator-13_00.png b/_images/operator-13_00.png deleted file mode 100644 index 29997314..00000000 Binary files a/_images/operator-13_00.png and /dev/null differ diff --git a/_images/operator-13_01.png b/_images/operator-13_01.png deleted file mode 100644 index df404bc2..00000000 Binary files a/_images/operator-13_01.png and /dev/null differ diff --git a/_images/operator-13_02.png b/_images/operator-13_02.png deleted file mode 100644 index d66751f8..00000000 Binary files a/_images/operator-13_02.png and /dev/null differ diff --git a/_images/operator-13_03.png b/_images/operator-13_03.png deleted file mode 100644 index 77f49770..00000000 Binary files a/_images/operator-13_03.png and /dev/null differ diff --git a/_images/operator-14.png b/_images/operator-14.png deleted file mode 100644 index c28982cb..00000000 Binary files a/_images/operator-14.png and /dev/null differ diff --git a/_images/operator-15.png b/_images/operator-15.png deleted file mode 100644 index 26a935f1..00000000 Binary files a/_images/operator-15.png and /dev/null differ diff --git a/_images/operator-16.png b/_images/operator-16.png deleted file mode 100644 index 0a0e3de5..00000000 Binary files a/_images/operator-16.png and /dev/null differ diff --git a/_images/operator-17.png b/_images/operator-17.png deleted file mode 100644 index 46f5ec1b..00000000 Binary files a/_images/operator-17.png and /dev/null differ diff --git a/_images/operator-18.png b/_images/operator-18.png deleted file mode 100644 index 7abd9e38..00000000 Binary files a/_images/operator-18.png and /dev/null differ diff --git a/_images/operator-19.png b/_images/operator-19.png deleted file mode 100644 index cf0cf366..00000000 Binary files a/_images/operator-19.png and /dev/null differ diff --git a/_images/operator-2.png b/_images/operator-2.png deleted file mode 100644 index c4e9be08..00000000 Binary files a/_images/operator-2.png and /dev/null differ diff --git a/_images/operator-20.png b/_images/operator-20.png deleted file mode 100644 index 707cde96..00000000 Binary files a/_images/operator-20.png and /dev/null differ diff --git a/_images/operator-21_00.png b/_images/operator-21_00.png deleted file mode 100644 index 5fa0c071..00000000 Binary files a/_images/operator-21_00.png and /dev/null differ diff --git a/_images/operator-21_01.png b/_images/operator-21_01.png deleted file mode 100644 index 987409c8..00000000 Binary files a/_images/operator-21_01.png and /dev/null differ diff --git a/_images/operator-21_02.png b/_images/operator-21_02.png deleted file mode 100644 index 202a34b9..00000000 Binary files a/_images/operator-21_02.png and /dev/null differ diff --git a/_images/operator-21_03.png b/_images/operator-21_03.png deleted file mode 100644 index 825b173b..00000000 Binary files a/_images/operator-21_03.png and /dev/null differ diff --git a/_images/operator-3_00.png b/_images/operator-3_00.png deleted file mode 100644 index fe4dbf22..00000000 Binary files a/_images/operator-3_00.png and /dev/null differ diff --git a/_images/operator-3_01.png b/_images/operator-3_01.png deleted file mode 100644 index 23895dd6..00000000 Binary files a/_images/operator-3_01.png and /dev/null differ diff --git a/_images/operator-4_00.png b/_images/operator-4_00.png deleted file mode 100644 index fccd452c..00000000 Binary files a/_images/operator-4_00.png and /dev/null differ diff --git a/_images/operator-4_01.png b/_images/operator-4_01.png deleted file mode 100644 index ea2aefc5..00000000 Binary files a/_images/operator-4_01.png and /dev/null differ diff --git a/_images/operator-4_02.png b/_images/operator-4_02.png deleted file mode 100644 index e557225d..00000000 Binary files a/_images/operator-4_02.png and /dev/null differ diff --git a/_images/operator-5.png b/_images/operator-5.png deleted file mode 100644 index 3caac993..00000000 Binary files a/_images/operator-5.png and /dev/null differ diff --git a/_images/operator-6.png b/_images/operator-6.png deleted file mode 100644 index 60d90a67..00000000 Binary files a/_images/operator-6.png and /dev/null differ diff --git a/_images/operator-7.png b/_images/operator-7.png deleted file mode 100644 index 39e58e55..00000000 Binary files a/_images/operator-7.png and /dev/null differ diff --git a/_images/operator-8.png b/_images/operator-8.png deleted file mode 100644 index d6d0749e..00000000 Binary files a/_images/operator-8.png and /dev/null differ diff --git a/_images/operator-9.png b/_images/operator-9.png deleted file mode 100644 index 458adf0d..00000000 Binary files a/_images/operator-9.png and /dev/null differ diff --git a/_images/opt-1.png b/_images/opt-1.png deleted file mode 100644 index 5b1ae4f0..00000000 Binary files a/_images/opt-1.png and /dev/null differ diff --git a/_images/opt-2.png b/_images/opt-2.png deleted file mode 100644 index 4a24cdae..00000000 Binary files a/_images/opt-2.png and /dev/null differ diff --git a/_images/opt-3.png b/_images/opt-3.png deleted file mode 100644 index b769785d..00000000 Binary files a/_images/opt-3.png and /dev/null differ diff --git a/_images/opt-solver-3.png b/_images/opt-solver-3.png index b769785d..d652c5bf 100644 Binary files a/_images/opt-solver-3.png and b/_images/opt-solver-3.png differ diff --git a/_modules/.DS_Store b/_modules/.DS_Store deleted file mode 100644 index 772eae70..00000000 Binary files a/_modules/.DS_Store and /dev/null differ diff --git a/_modules/collections/abc.html b/_modules/collections/abc.html index 4eb3fab4..793a945f 100644 --- a/_modules/collections/abc.html +++ b/_modules/collections/abc.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -199,7 +199,7 @@ -
v1.0.x
+
Pyxu v1.0.1
    @@ -236,7 +236,7 @@ - +
  • @@ -341,7 +341,7 @@
    -
    v1.0.x
    +
    Pyxu v1.0.1
      @@ -378,7 +378,7 @@ - +
    • @@ -513,15 +513,11 @@

      Source code for collections.abc

             
         
      
   
      
-    Created using Sphinx 7.2.5.
+     Created with Sphinx 7.2.5, with some help from  ChatGPT (GPT 4).
     
      
   
      
 
      
       
-        
      
-  Built with the PyData Sphinx Theme 0.13.3.
-
      
-
      diff --git a/_modules/index.html b/_modules/index.html index 59c8e23d..ec426312 100644 --- a/_modules/index.html +++ b/_modules/index.html @@ -27,7 +27,7 @@ - + @@ -37,13 +37,13 @@ - + - + diff --git a/_modules/numbers.html b/_modules/numbers.html index 284917c5..f1a2519e 100644 --- a/_modules/numbers.html +++ b/_modules/numbers.html @@ -27,7 +27,7 @@ - + @@ -37,13 +37,13 @@ - + - + @@ -199,7 +199,7 @@
    -
    v1.0.x
    +
    Pyxu v1.0.1
      @@ -236,7 +236,7 @@ - +
    • @@ -341,7 +341,7 @@
      -
      v1.0.x
      +
      Pyxu v1.0.1
        @@ -378,7 +378,7 @@ - +
      • @@ -598,7 +598,7 @@

        Source code for numbers

         145
 146
 
        
-[docs]
+[docs]
 147class Real(Complex):
 148    """To Complex, Real adds the operations that work on real numbers.
 149
@@ -713,7 +713,7 @@ 
        Source code for numbers
         258        return 0
 259
 
        
-[docs]
+[docs]
 260    def conjugate(self):
 261        """Conjugate is a no-op for Reals."""
 262        return +self
        
@@ -909,15 +909,11 @@ 
        Source code for numbers
               
         
        
   
        
-    Created using Sphinx 7.2.5.
+     Created with Sphinx 7.2.5, with some help from  ChatGPT (GPT 4).
     
        
   
        
 
        
       
-        
        
-  Built with the PyData Sphinx Theme 0.13.3.
-
        
-      
     
        
   
   
diff --git a/_modules/pyxu/.DS_Store b/_modules/pyxu/.DS_Store
deleted file mode 100644
index 9a01400a..00000000
Binary files a/_modules/pyxu/.DS_Store and /dev/null differ
diff --git a/_modules/pyxu/abc/arithmetic.html b/_modules/pyxu/abc/arithmetic.html
index f0a1273d..470a8063 100644
--- a/_modules/pyxu/abc/arithmetic.html
+++ b/_modules/pyxu/abc/arithmetic.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
      • @@ -378,7 +378,7 @@ - +
      • @@ -468,7 +468,7 @@

        Source code for pyxu.abc.arithmetic

           15
   16
 
        
-[docs]
+[docs]
   17class Rule:
   18    """
   19    General arithmetic rule.
@@ -477,7 +477,7 @@ 
        Source code for pyxu.abc.arithmetic
           22    """
   23
 
        
-[docs]
+[docs]
   24    def op(self) -> pxt.OpT:
   25        """
   26        Returns
@@ -526,7 +526,7 @@ 
        Source code for pyxu.abc.arithmetic
           67
   68
 
        
-[docs]
+[docs]
   69class ScaleRule(Rule):
   70    r"""
   71    Arithmetic rules for element-wise scaling: :math:`B(x) = \alpha A(x)`.
@@ -727,7 +727,7 @@ 
        Source code for pyxu.abc.arithmetic
          265
  266
 
        
-[docs]
+[docs]
  267class ArgScaleRule(Rule):
  268    r"""
  269    Arithmetic rules for element-wise parameter scaling: :math:`B(x) = A(\alpha x)`.
@@ -950,7 +950,7 @@ 
        Source code for pyxu.abc.arithmetic
          485
  486
 
        
-[docs]
+[docs]
  487class ArgShiftRule(Rule):
  488    r"""
  489    Arithmetic rules for parameter shifting: :math:`B(x) = A(x - c)`.
@@ -1143,7 +1143,7 @@ 
        Source code for pyxu.abc.arithmetic
          675
  676
 
        
-[docs]
+[docs]
  677class AddRule(Rule):
  678    r"""
  679    Arithmetic rules for operator addition: :math:`C(x) = A(x) + B(x)`.
@@ -1515,7 +1515,7 @@ 
        Source code for pyxu.abc.arithmetic
         1044
 1045
 
        
-[docs]
+[docs]
 1046class ChainRule(Rule):
 1047    r"""
 1048    Arithmetic rules for operator composition: :math:`C(x) = (A \circ B)(x)`.
@@ -1837,7 +1837,7 @@ 
        Source code for pyxu.abc.arithmetic
         1363
 1364
 
        
-[docs]
+[docs]
 1365class PowerRule(Rule):
 1366    r"""
 1367    Arithmetic rules for operator exponentiation: :math:`B(x) = A^{k}(x)`.
@@ -1882,7 +1882,7 @@ 
        Source code for pyxu.abc.arithmetic
         1405
 1406
 
        
-[docs]
+[docs]
 1407class TransposeRule(Rule):
 1408    # Not strictly-speaking an arithmetic method, but the logic behind constructing transposed
 1409    # operators is identical to arithmetic methods.
diff --git a/_modules/pyxu/abc/operator.html b/_modules/pyxu/abc/operator.html
index 142b14ff..052ec986 100644
--- a/_modules/pyxu/abc/operator.html
+++ b/_modules/pyxu/abc/operator.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
      • @@ -378,7 +378,7 @@ - +
      • @@ -471,7 +471,7 @@

        Source code for pyxu.abc.operator

           18
   19
 
        
-[docs]
+[docs]
   20class Property(enum.Enum):
   21    """
   22    Mathematical property.
@@ -496,7 +496,7 @@ 
        Source code for pyxu.abc.operator
           41    QUADRATIC = enum.auto()
   42
 
        
-[docs]
+[docs]
   43    def arithmetic_methods(self) -> cabc.Set[str]:
   44        "Instance methods affected by arithmetic operations."
   45        data = collections.defaultdict(list)
@@ -537,7 +537,7 @@ 
        Source code for pyxu.abc.operator
           78
   79
 
        
-[docs]
+[docs]
   80class Operator:
   81    """
   82    Abstract Base Class for Pyxu operators.
@@ -556,7 +556,7 @@ 
        Source code for pyxu.abc.operator
           95    __array_priority__ = np.inf
   96
 
        
-[docs]
+[docs]
   97    def __init__(self, shape: pxt.OpShape):
   98        r"""
   99        Parameters
@@ -594,7 +594,7 @@ 
        Source code for pyxu.abc.operator
          130        return self.shape[0]
  131
 
        
-[docs]
+[docs]
  132    @classmethod
  133    def properties(cls) -> cabc.Set[Property]:
  134        "Mathematical properties of the operator."
@@ -602,7 +602,7 @@ 
        Source code for pyxu.abc.operator
         
  136
 
        
-[docs]
+[docs]
  137    @classmethod
  138    def has(cls, prop: typ.Union[Property, cabc.Collection[Property]]) -> bool:
  139        """
@@ -614,7 +614,7 @@ 
        Source code for pyxu.abc.operator
         
  145
 
        
-[docs]
+[docs]
  146    def asop(self, cast_to: pxt.OpC) -> pxt.OpT:
  147        r"""
  148        Recast an :py:class:`~pyxu.abc.Operator` (or subclass thereof) to another :py:class:`~pyxu.abc.Operator`.
@@ -677,7 +677,7 @@ 
        Source code for pyxu.abc.operator
          204
  205    # Operator Arithmetic -----------------------------------------------------
 
        
-[docs]
+[docs]
  206    def __add__(self, other: pxt.OpT) -> pxt.OpT:
  207        """
  208        Add two operators.
@@ -714,7 +714,7 @@ 
        Source code for pyxu.abc.operator
         
  239
 
        
-[docs]
+[docs]
  240    def __sub__(self, other: pxt.OpT) -> pxt.OpT:
  241        """
  242        Subtract two operators.
@@ -740,7 +740,7 @@ 
        Source code for pyxu.abc.operator
         
  262
 
        
-[docs]
+[docs]
  263    def __neg__(self) -> pxt.OpT:
  264        """
  265        Negate an operator.
@@ -756,7 +756,7 @@ 
        Source code for pyxu.abc.operator
         
  275
 
        
-[docs]
+[docs]
  276    def __mul__(self, other: typ.Union[pxt.Real, pxt.OpT]) -> pxt.OpT:
  277        """
  278        Compose two operators, or scale an operator by a constant.
@@ -811,7 +811,7 @@ 
        Source code for pyxu.abc.operator
          326            return NotImplemented
  327
 
        
-[docs]
+[docs]
  328    def __pow__(self, k: pxt.Integer) -> pxt.OpT:
  329        """
  330        Exponentiate an operator, i.e. compose it with itself.
@@ -851,7 +851,7 @@ 
        Source code for pyxu.abc.operator
          363        return NotImplemented
  364
 
        
-[docs]
+[docs]
  365    def argscale(self, scalar: pxt.Real) -> pxt.OpT:
  366        """
  367        Scale operator's domain.
@@ -876,7 +876,7 @@ 
        Source code for pyxu.abc.operator
         
  386
 
        
-[docs]
+[docs]
  387    def argshift(self, shift: typ.Union[pxt.Real, pxt.NDArray]) -> pxt.OpT:
  388        """
  389        Shift operator's domain.
@@ -913,7 +913,7 @@ 
        Source code for pyxu.abc.operator
          419            raise ValueError(f"No operator found with properties {prop}.")
  420
 
        
-[docs]
+[docs]
  421    def squeeze(self) -> pxt.OpT:
  422        r"""
  423        Cast an :py:class:`~pyxu.abc.Operator` to the right core operator sub-type given codomain dimension.
@@ -953,7 +953,7 @@ 
        Source code for pyxu.abc.operator
          456        return (self,)
  457
 
        
-[docs]
+[docs]
  458    def expr(self, level: int = 0, strip: bool = True) -> str:
  459        """
  460        Pretty-Print the expression representation of the operator.
@@ -1014,7 +1014,7 @@ 
        Source code for pyxu.abc.operator
          513
  514
 
        
-[docs]
+[docs]
  515class Map(Operator):
  516    r"""
  517    Base class for real-valued maps :math:`\mathbf{f}: \mathbb{R}^{M} \to \mathbb{R}^{N}`.
@@ -1026,7 +1026,7 @@ 
        Source code for pyxu.abc.operator
          523    """
  524
 
        
-[docs]
+[docs]
  525    @classmethod
  526    def properties(cls) -> cabc.Set[Property]:
  527        p = set(super().properties())
@@ -1039,7 +1039,7 @@ 
        Source code for pyxu.abc.operator
          533        self.lipschitz = np.inf
  534
 
        
-[docs]
+[docs]
  535    def apply(self, arr: pxt.NDArray) -> pxt.NDArray:
  536        """
  537        Evaluate operator at specified point(s).
@@ -1058,7 +1058,7 @@ 
        Source code for pyxu.abc.operator
         
  550
 
        
-[docs]
+[docs]
  551    def __call__(self, arr: pxt.NDArray) -> pxt.NDArray:
  552        """
  553        Alias for :py:meth:`~pyxu.abc.Map.apply`.
@@ -1126,7 +1126,7 @@ 
        Source code for pyxu.abc.operator
          614            self.estimate_lipschitz = types.MethodType(op_estimate_lipschitz, self)
  615
 
        
-[docs]
+[docs]
  616    def estimate_lipschitz(self, **kwargs) -> pxt.Real:
  617        r"""
  618        Compute a Lipschitz constant of the operator.
@@ -1162,7 +1162,7 @@ 
        Source code for pyxu.abc.operator
          646
  647
 
        
-[docs]
+[docs]
  648class Func(Map):
  649    r"""
  650    Base class for real-valued functionals :math:`f: \mathbb{R}^{M} \to \mathbb{R}\cup\{+\infty\}`.
@@ -1184,7 +1184,7 @@ 
        Source code for pyxu.abc.operator
          666        assert self.codim == 1, f"shape: expected (1, n), got {shape}."
  667
 
        
-[docs]
+[docs]
  668    def asloss(self, data: pxt.NDArray = None) -> pxt.OpT:
  669        """
  670        Transform a functional into a loss functional.
@@ -1209,7 +1209,7 @@ 
        Source code for pyxu.abc.operator
          687
  688
 
        
-[docs]
+[docs]
  689class DiffMap(Map):
  690    r"""
  691    Base class for real-valued differentiable maps :math:`\mathbf{f}: \mathbb{R}^{M} \to \mathbb{R}^{N}`.
@@ -1234,7 +1234,7 @@ 
        Source code for pyxu.abc.operator
          710        self.diff_lipschitz = np.inf
  711
 
        
-[docs]
+[docs]
  712    def jacobian(self, arr: pxt.NDArray) -> pxt.OpT:
  713        r"""
  714        Evaluate the Jacobian of :math:`\mathbf{f}` at the specified point.
@@ -1339,7 +1339,7 @@ 
        Source code for pyxu.abc.operator
          812            self.estimate_diff_lipschitz = types.MethodType(op_estimate_diff_lipschitz, self)
  813
 
        
-[docs]
+[docs]
  814    def estimate_diff_lipschitz(self, **kwargs) -> pxt.Real:
  815        r"""
  816        Compute a Lipschitz constant of :py:meth:`~pyxu.abc.DiffMap.jacobian`.
@@ -1375,7 +1375,7 @@ 
        Source code for pyxu.abc.operator
          844
  845
 
        
-[docs]
+[docs]
  846class ProxFunc(Func):
  847    r"""
  848    Base class for real-valued proximable functionals :math:`f: \mathbb{R}^{M} \to \mathbb{R} \cup \{+\infty\}`.
@@ -1400,7 +1400,7 @@ 
        Source code for pyxu.abc.operator
          867        super().__init__(shape=shape)
  868
 
        
-[docs]
+[docs]
  869    def prox(self, arr: pxt.NDArray, tau: pxt.Real) -> pxt.NDArray:
  870        r"""
  871        Evaluate proximity operator of :math:`\tau f` at specified point(s).
@@ -1434,7 +1434,7 @@ 
        Source code for pyxu.abc.operator
         
  899
 
        
-[docs]
+[docs]
  900    @pxrt.enforce_precision(i=("arr", "sigma"))
  901    def fenchel_prox(self, arr: pxt.NDArray, sigma: pxt.Real) -> pxt.NDArray:
  902        r"""
@@ -1479,7 +1479,7 @@ 
        Source code for pyxu.abc.operator
         
  941
 
        
-[docs]
+[docs]
  942    def moreau_envelope(self, mu: pxt.Real) -> pxt.OpT:
  943        r"""
  944        Approximate proximable functional :math:`f` by its *Moreau envelope* :math:`f^{\mu}`.
@@ -1609,7 +1609,7 @@ 
        Source code for pyxu.abc.operator
         1066
 1067
 
        
-[docs]
+[docs]
 1068class DiffFunc(DiffMap, Func):
 1069    r"""
 1070    Base class for real-valued differentiable functionals :math:`f: \mathbb{R}^{M} \to \mathbb{R}`.
@@ -1638,7 +1638,7 @@ 
        Source code for pyxu.abc.operator
         1093        return LinFunc.from_array(self.grad(arr))
 1094
 
        
-[docs]
+[docs]
 1095    def grad(self, arr: pxt.NDArray) -> pxt.NDArray:
 1096        r"""
 1097        Evaluate operator gradient at specified point(s).
@@ -1674,7 +1674,7 @@ 
        Source code for pyxu.abc.operator
         1125
 1126
 
        
-[docs]
+[docs]
 1127class ProxDiffFunc(ProxFunc, DiffFunc):
 1128    r"""
 1129    Base class for real-valued differentiable *and* proximable functionals :math:`f:\mathbb{R}^{M} \to \mathbb{R}`.
@@ -1701,7 +1701,7 @@ 
        Source code for pyxu.abc.operator
         1149
 1150
 
        
-[docs]
+[docs]
 1151class QuadraticFunc(ProxDiffFunc):
 1152    # This is a special abstract base class with more __init__ parameters than `shape`.
 1153    r"""
@@ -1755,7 +1755,7 @@ 
        Source code for pyxu.abc.operator
         1201        return frozenset(p)
 1202
 
        
-[docs]
+[docs]
 1203    def __init__(
 1204        self,
 1205        shape: pxt.OpShape,
@@ -1839,7 +1839,7 @@ 
        Source code for pyxu.abc.operator
         1282        return dL
 1283
 
        
-[docs]
+[docs]
 1284    def _quad_spec(self):
 1285        """
 1286        Canonical quadratic parameterization.
@@ -1852,7 +1852,7 @@ 
        Source code for pyxu.abc.operator
         1291
 1292
 
        
-[docs]
+[docs]
 1293class LinOp(DiffMap):
 1294    r"""
 1295    Base class for real-valued linear operators :math:`\mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{N}`.
@@ -1889,7 +1889,7 @@ 
        Source code for pyxu.abc.operator
         1326        self.diff_lipschitz = 0
 1327
 
        
-[docs]
+[docs]
 1328    def adjoint(self, arr: pxt.NDArray) -> pxt.NDArray:
 1329        r"""
 1330        Evaluate operator adjoint at specified point(s).
@@ -1933,7 +1933,7 @@ 
        Source code for pyxu.abc.operator
         1367        return arithmetic.TransposeRule(op=self).op()
 1368
 
        
-[docs]
+[docs]
 1369    def to_sciop(
 1370        self,
 1371        dtype: pxt.DType = None,
@@ -1983,7 +1983,7 @@ 
        Source code for pyxu.abc.operator
         
 1415
 
        
-[docs]
+[docs]
 1416    def estimate_lipschitz(self, **kwargs) -> pxt.Real:
 1417        r"""
 1418        Compute a Lipschitz constant of the operator.
@@ -2055,7 +2055,7 @@ 
        Source code for pyxu.abc.operator
         
 1484
 
        
-[docs]
+[docs]
 1485    @pxrt.enforce_precision()
 1486    def svdvals(
 1487        self,
@@ -2130,7 +2130,7 @@ 
        Source code for pyxu.abc.operator
         
 1556
 
        
-[docs]
+[docs]
 1557    def asarray(
 1558        self,
 1559        xp: pxt.ArrayModule = None,
@@ -2168,7 +2168,7 @@ 
        Source code for pyxu.abc.operator
         
 1591
 
        
-[docs]
+[docs]
 1592    def gram(self) -> pxt.OpT:
 1593        r"""
 1594        Gram operator :math:`\mathbf{A}^{\ast} \mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{M}`.
@@ -2194,7 +2194,7 @@ 
        Source code for pyxu.abc.operator
         
 1614
 
        
-[docs]
+[docs]
 1615    def cogram(self) -> pxt.OpT:
 1616        r"""
 1617        Co-Gram operator :math:`\mathbf{A}\mathbf{A}^{\ast}:\mathbb{R}^{N} \to \mathbb{R}^{N}`.
@@ -2220,7 +2220,7 @@ 
        Source code for pyxu.abc.operator
         
 1637
 
        
-[docs]
+[docs]
 1638    @pxrt.enforce_precision(i=("arr", "damp"))
 1639    def pinv(
 1640        self,
@@ -2306,7 +2306,7 @@ 
        Source code for pyxu.abc.operator
         
 1720
 
        
-[docs]
+[docs]
 1721    def dagger(
 1722        self,
 1723        damp: pxt.Real,
@@ -2368,7 +2368,7 @@ 
        Source code for pyxu.abc.operator
         
 1779
 
        
-[docs]
+[docs]
 1780    @classmethod
 1781    def from_array(
 1782        cls,
@@ -2398,7 +2398,7 @@ 
        Source code for pyxu.abc.operator
         1804
 1805
 
        
-[docs]
+[docs]
 1806class SquareOp(LinOp):
 1807    r"""
 1808    Base class for *square* linear operators, i.e. :math:`\mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{M}`
@@ -2416,7 +2416,7 @@ 
        Source code for pyxu.abc.operator
         1820        assert self.dim == self.codim, f"shape: expected (M, M), got {self.shape}."
 1821
 
        
-[docs]
+[docs]
 1822    @pxrt.enforce_precision()
 1823    def trace(self, **kwargs) -> pxt.Real:
 1824        """
@@ -2464,7 +2464,7 @@ 
        Source code for pyxu.abc.operator
         1864
 1865
 
        
-[docs]
+[docs]
 1866class NormalOp(SquareOp):
 1867    r"""
 1868    Base class for *normal* operators.
@@ -2486,7 +2486,7 @@ 
        Source code for pyxu.abc.operator
         1883
 1884
 
        
-[docs]
+[docs]
 1885class SelfAdjointOp(NormalOp):
 1886    r"""
 1887    Base class for *self-adjoint* operators.
@@ -2506,7 +2506,7 @@ 
        Source code for pyxu.abc.operator
         1900
 1901
 
        
-[docs]
+[docs]
 1902class UnitOp(NormalOp):
 1903    r"""
 1904    Base class for *unitary* operators.
@@ -2555,7 +2555,7 @@ 
        Source code for pyxu.abc.operator
         1946
 1947
 
        
-[docs]
+[docs]
 1948class ProjOp(SquareOp):
 1949    r"""
 1950    Base class for *projection* operators.
@@ -2572,7 +2572,7 @@ 
        Source code for pyxu.abc.operator
         1960
 1961
 
        
-[docs]
+[docs]
 1962class OrthProjOp(ProjOp, SelfAdjointOp):
 1963    r"""
 1964    Base class for *orthogonal projection* operators.
@@ -2616,7 +2616,7 @@ 
        Source code for pyxu.abc.operator
         2001
 2002
 
        
-[docs]
+[docs]
 2003class PosDefOp(SelfAdjointOp):
 2004    r"""
 2005    Base class for *positive-definite* operators.
@@ -2631,7 +2631,7 @@ 
        Source code for pyxu.abc.operator
         2013
 2014
 
        
-[docs]
+[docs]
 2015class LinFunc(ProxDiffFunc, LinOp):
 2016    r"""
 2017    Base class for real-valued linear functionals :math:`f: \mathbb{R}^{M} \to \mathbb{R}`.
diff --git a/_modules/pyxu/abc/solver.html b/_modules/pyxu/abc/solver.html
index 68fb9ae7..dd9b39d6 100644
--- a/_modules/pyxu/abc/solver.html
+++ b/_modules/pyxu/abc/solver.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
diff --git a/_modules/pyxu/experimental/sampler/_sampler.html b/_modules/pyxu/experimental/sampler/_sampler.html
index a706a264..516bd0b3 100644
--- a/_modules/pyxu/experimental/sampler/_sampler.html
+++ b/_modules/pyxu/experimental/sampler/_sampler.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
diff --git a/_modules/pyxu/experimental/sampler/statistics.html b/_modules/pyxu/experimental/sampler/statistics.html
index 6d1e2675..76bb0274 100644
--- a/_modules/pyxu/experimental/sampler/statistics.html
+++ b/_modules/pyxu/experimental/sampler/statistics.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
      • @@ -378,7 +378,7 @@ - +
      • diff --git a/_modules/pyxu/info/deps.html b/_modules/pyxu/info/deps.html index a9eceb5b..0d517e92 100644 --- a/_modules/pyxu/info/deps.html +++ b/_modules/pyxu/info/deps.html @@ -27,7 +27,7 @@ - + @@ -37,13 +37,13 @@ - + - + @@ -199,7 +199,7 @@
      -
      v1.0.x
      +
      Pyxu v1.0.1
        @@ -236,7 +236,7 @@ - +
      • @@ -341,7 +341,7 @@
        -
        v1.0.x
        +
        Pyxu v1.0.1
          @@ -378,7 +378,7 @@ - +
        • @@ -475,7 +475,7 @@

          Source code for pyxu.info.deps

            22
  23
 
          
-[docs]
+[docs]
  24@enum.unique
  25class NDArrayInfo(enum.Enum):
  26    """
@@ -487,7 +487,7 @@ 
          Source code for pyxu.info.deps
            32    CUPY = enum.auto()
  33
 
          
-[docs]
+[docs]
  34    @classmethod
  35    def default(cls) -> "NDArrayInfo":
  36        """Default array backend to use."""
@@ -495,7 +495,7 @@ 
          Source code for pyxu.info.deps
           
  38
 
          
-[docs]
+[docs]
  39    def type(self) -> type:
  40        """Array type associated to a backend."""
  41        if self.name == "NUMPY":
@@ -509,7 +509,7 @@ 
          Source code for pyxu.info.deps
           
  49
 
          
-[docs]
+[docs]
  50    @classmethod
  51    def from_obj(cls, obj) -> "NDArrayInfo":
  52        """Find array backend associated to `obj`."""
@@ -521,7 +521,7 @@ 
          Source code for pyxu.info.deps
           
  58
 
          
-[docs]
+[docs]
  59    @classmethod
  60    def from_flag(cls, gpu: bool) -> "NDArrayInfo":
  61        """Find array backend suitable for in-memory CPU/GPU computing."""
@@ -532,7 +532,7 @@ 
          Source code for pyxu.info.deps
           
  66
 
          
-[docs]
+[docs]
  67    def module(self, linalg: bool = False) -> types.ModuleType:
  68        """
  69        Python module associated to an array backend.
@@ -559,7 +559,7 @@ 
          Source code for pyxu.info.deps
            88
  89
 
          
-[docs]
+[docs]
  90@enum.unique
  91class SparseArrayInfo(enum.Enum):
  92    """
@@ -571,7 +571,7 @@ 
          Source code for pyxu.info.deps
            98    CUPY_SPARSE = enum.auto()
  99
 
          
-[docs]
+[docs]
 100    @classmethod
 101    def default(cls) -> "SparseArrayInfo":
 102        """Default array backend to use."""
@@ -579,7 +579,7 @@ 
          Source code for pyxu.info.deps
           
 104
 
          
-[docs]
+[docs]
 105    def type(self) -> type:
 106        """Array type associated to a backend."""
 107        if self.name == "SCIPY_SPARSE":
@@ -594,7 +594,7 @@ 
          Source code for pyxu.info.deps
           
 116
 
          
-[docs]
+[docs]
 117    @classmethod
 118    def from_obj(cls, obj) -> "SparseArrayInfo":
 119        """Find array backend associated to `obj`."""
@@ -606,7 +606,7 @@ 
          Source code for pyxu.info.deps
           
 125
 
          
-[docs]
+[docs]
 126    def module(self, linalg: bool = False) -> types.ModuleType:
 127        """
 128        Python module associated to an array backend.
@@ -633,7 +633,7 @@ 
          Source code for pyxu.info.deps
           147
 148
 
          
-[docs]
+[docs]
 149def supported_array_types() -> cabc.Collection[type]:
 150    """List of all supported dense array types in current Pyxu install."""
 151    data = set()
@@ -645,7 +645,7 @@ 
          Source code for pyxu.info.deps
           156
 157
 
          
-[docs]
+[docs]
 158def supported_array_modules() -> cabc.Collection[types.ModuleType]:
 159    """List of all supported dense array modules in current Pyxu install."""
 160    data = set()
@@ -657,7 +657,7 @@ 
          Source code for pyxu.info.deps
           165
 166
 
          
-[docs]
+[docs]
 167def supported_sparse_types() -> cabc.Collection[type]:
 168    """List of all supported sparse array types in current Pyxu install."""
 169    data = set()
@@ -669,7 +669,7 @@ 
          Source code for pyxu.info.deps
           174
 175
 
          
-[docs]
+[docs]
 176def supported_sparse_modules() -> cabc.Collection[types.ModuleType]:
 177    """List of all supported sparse array modules in current Pyxu install."""
 178    data = set()
@@ -759,15 +759,11 @@ 
          Source code for pyxu.info.deps
                 
         
          
   
          
-    Created using Sphinx 7.2.5.
+     Created with Sphinx 7.2.5, with some help from  ChatGPT (GPT 4).
     
          
   
          
 
          
       
-        
          
-  Built with the PyData Sphinx Theme 0.13.3.
-
          
-      
     
          
   
   
diff --git a/_modules/pyxu/info/ptype.html b/_modules/pyxu/info/ptype.html
index 45538f56..8488a2b8 100644
--- a/_modules/pyxu/info/ptype.html
+++ b/_modules/pyxu/info/ptype.html
@@ -27,7 +27,7 @@
 
 
 
-    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
        • @@ -378,7 +378,7 @@ - +
        • diff --git a/_modules/pyxu/info/warning.html b/_modules/pyxu/info/warning.html index a3ff5a99..9a8b972f 100644 --- a/_modules/pyxu/info/warning.html +++ b/_modules/pyxu/info/warning.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + diff --git a/_modules/pyxu/math/linalg.html b/_modules/pyxu/math/linalg.html index 391a279f..595aa69b 100644 --- a/_modules/pyxu/math/linalg.html +++ b/_modules/pyxu/math/linalg.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
        • @@ -378,7 +378,7 @@ - +
        • diff --git a/_modules/pyxu/math/linesearch.html b/_modules/pyxu/math/linesearch.html index 1919681d..ff22b80d 100644 --- a/_modules/pyxu/math/linesearch.html +++ b/_modules/pyxu/math/linesearch.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
        • @@ -378,7 +378,7 @@ - +
        • diff --git a/_modules/pyxu/operator/blocks.html b/_modules/pyxu/operator/blocks.html index ee3f59d0..9c892e5d 100644 --- a/_modules/pyxu/operator/blocks.html +++ b/_modules/pyxu/operator/blocks.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
        • @@ -378,7 +378,7 @@ - +
        • @@ -464,1014 +464,1017 @@

          Source code for pyxu.operator.blocks

             11import pyxu.info.ptype as pxt
   12import pyxu.runtime as pxrt
   13import pyxu.util as pxu
-  14
-  15__all__ = [
-  16    "stack",
-  17    "vstack",
-  18    "hstack",
-  19    "block_diag",
-  20    "block",
-  21    "coo_block",
-  22]
-  23
-  24# Arithmetic methods/attributes of [hstack, vstack, block_diag, coo_block]() are very similar. To avoid excessive
-  25# copy/paste-ing the same implementation everywhere, these functions piggy-back on _COOBlock() for most computations.
-  26# When a more efficient implementation is known however, it is overridden in [hstack, vstack, block_diag]() as needed.
-  27
-  28
+  14from pyxu.info.plugin import _load_entry_points
+  15
+  16__all__ = [
+  17    "stack",
+  18    "vstack",
+  19    "hstack",
+  20    "block_diag",
+  21    "block",
+  22    "coo_block",
+  23]
+  24
+  25__all__ = _load_entry_points(globals(), group="pyxu.opt.blocks", names=__all__)
+  26
+  27# Arithmetic methods/attributes of [hstack, vstack, block_diag, coo_block]() are very similar. To avoid excessive
+  28# copy/paste-ing the same implementation everywhere, these functions piggy-back on _COOBlock() for most computations.
+  29# When a more efficient implementation is known however, it is overridden in [hstack, vstack, block_diag]() as needed.
+  30
+  31
 
          
-[docs]
-  29def stack(
-  30    ops: cabc.Sequence[pxt.OpT],
-  31    axis: pxt.Integer,
-  32    **kwargs,
-  33) -> pxt.OpT:
-  34    r"""
-  35    Construct a stacked operator.
-  36
-  37    A stacked-operator :math:`V: \mathbb{R}^{d} \to \mathbb{R}^{c}` is an operator containing (vertically or
-  38    horizontally) blocks of smaller operators :math:`\{O_{1}, \ldots, O_{N}\}`.
+[docs]
+  32def stack(
+  33    ops: cabc.Sequence[pxt.OpT],
+  34    axis: pxt.Integer,
+  35    **kwargs,
+  36) -> pxt.OpT:
+  37    r"""
+  38    Construct a stacked operator.
   39
-  40    This is a convenience function around :py:func:`~pyxu.operator.hstack` and :py:func:`~pyxu.operator.vstack`.
-  41
-  42    Parameters
-  43    ----------
-  44    ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` )
-  45        [op1(c1, d1), ..., opN(cN, dN)] operators to join.
-  46    axis: Integer
-  47        The axis along which operators will be joined, i.e.
-  48
-  49        * 0: stack vertically (row-wise)
-  50        * 1: stack horizontally (column-wise)
-  51    kwargs
-  52        Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`.
-  53
-  54    Returns
-  55    -------
-  56    op: OpT
-  57        Stacked operator.
-  58
-  59    See Also
-  60    --------
-  61    :py:func:`~pyxu.operator.hstack`,
-  62    :py:func:`~pyxu.operator.vstack`.
-  63    """
-  64    axis = int(axis)
-  65    assert axis in {0, 1}, f"axis: out-of-bounds axis '{axis}'."
-  66
-  67    f = {0: vstack, 1: hstack}[axis]
-  68    op = f(ops, **kwargs)
-  69    return op
          
+  40    A stacked-operator :math:`V: \mathbb{R}^{d} \to \mathbb{R}^{c}` is an operator containing (vertically or
+  41    horizontally) blocks of smaller operators :math:`\{O_{1}, \ldots, O_{N}\}`.
+  42
+  43    This is a convenience function around :py:func:`~pyxu.operator.hstack` and :py:func:`~pyxu.operator.vstack`.
+  44
+  45    Parameters
+  46    ----------
+  47    ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` )
+  48        [op1(c1, d1), ..., opN(cN, dN)] operators to join.
+  49    axis: Integer
+  50        The axis along which operators will be joined, i.e.
+  51
+  52        * 0: stack vertically (row-wise)
+  53        * 1: stack horizontally (column-wise)
+  54    kwargs
+  55        Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`.
+  56
+  57    Returns
+  58    -------
+  59    op: OpT
+  60        Stacked operator.
+  61
+  62    See Also
+  63    --------
+  64    :py:func:`~pyxu.operator.hstack`,
+  65    :py:func:`~pyxu.operator.vstack`.
+  66    """
+  67    axis = int(axis)
+  68    assert axis in {0, 1}, f"axis: out-of-bounds axis '{axis}'."
+  69
+  70    f = {0: vstack, 1: hstack}[axis]
+  71    op = f(ops, **kwargs)
+  72    return op
          - 70 - 71 + 73 + 74
          -[docs] - 72def vstack( - 73 ops: cabc.Sequence[pxt.OpT], - 74 **kwargs, - 75) -> pxt.OpT: - 76 r""" - 77 Construct a vertically-stacked operator. - 78 - 79 A vstacked-operator :math:`V: \mathbb{R}^{d} \to \mathbb{R}^{c_{1} + \cdots + c_{N}}` is an operator containing - 80 (vertically) blocks of smaller operators :math:`\{O_{1}: \mathbb{R}^{d} \to \mathbb{R}^{c_{1}}, \ldots, O_{N}: - 81 \mathbb{R}^{d} \to \mathbb{R}^{c_{N}}\}`, i.e. - 82 - 83 .. math:: - 84 - 85 V - 86 = - 87 \left[ - 88 \begin{array}{c} - 89 O_{1} \\ - 90 \vdots \\ - 91 O_{N} \\ - 92 \end{array} - 93 \right] - 94 - 95 Parameters - 96 ---------- - 97 ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) - 98 [op1(c1, d), ..., opN(cN, d)] operators to concatenate. - 99 kwargs - 100 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. - 101 - 102 Returns - 103 ------- - 104 op: OpT - 105 Vertically-stacked (c1+...+cN, d) operator. - 106 - 107 Notes - 108 ----- - 109 * All sub-operator domains must have compatible shapes, i.e. all integer-valued ``dim`` s must be identical. - 110 - 111 See Also - 112 -------- - 113 :py:func:`~pyxu.operator.hstack`, - 114 :py:func:`~pyxu.operator.stack`. - 115 """ - 116 - 117 def op_expr(_) -> tuple: - 118 N_row = _._grid_shape[0] - 119 ops = [_._block[(r, 0)] for r in range(N_row)] - 120 return ("vstack", *ops) - 121 - 122 N_data = len(ops) - 123 op = _COOBlock( - 124 ops=( - 125 ops, # data - 126 ( - 127 tuple(range(N_data)), # i - 128 [0] * N_data, # j - 129 ), - 130 ), - 131 grid_shape=(N_data, 1), - 132 parallel=kwargs.get("parallel", False), - 133 ).op() - 134 op._expr = types.MethodType(op_expr, op) - 135 return op
          +[docs] + 75def vstack( + 76 ops: cabc.Sequence[pxt.OpT], + 77 **kwargs, + 78) -> pxt.OpT: + 79 r""" + 80 Construct a vertically-stacked operator. + 81 + 82 A vstacked-operator :math:`V: \mathbb{R}^{d} \to \mathbb{R}^{c_{1} + \cdots + c_{N}}` is an operator containing + 83 (vertically) blocks of smaller operators :math:`\{O_{1}: \mathbb{R}^{d} \to \mathbb{R}^{c_{1}}, \ldots, O_{N}: + 84 \mathbb{R}^{d} \to \mathbb{R}^{c_{N}}\}`, i.e. + 85 + 86 .. math:: + 87 + 88 V + 89 = + 90 \left[ + 91 \begin{array}{c} + 92 O_{1} \\ + 93 \vdots \\ + 94 O_{N} \\ + 95 \end{array} + 96 \right] + 97 + 98 Parameters + 99 ---------- + 100 ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) + 101 [op1(c1, d), ..., opN(cN, d)] operators to concatenate. + 102 kwargs + 103 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. + 104 + 105 Returns + 106 ------- + 107 op: OpT + 108 Vertically-stacked (c1+...+cN, d) operator. + 109 + 110 Notes + 111 ----- + 112 * All sub-operator domains must have compatible shapes, i.e. all integer-valued ``dim`` s must be identical. + 113 + 114 See Also + 115 -------- + 116 :py:func:`~pyxu.operator.hstack`, + 117 :py:func:`~pyxu.operator.stack`. + 118 """ + 119 + 120 def op_expr(_) -> tuple: + 121 N_row = _._grid_shape[0] + 122 ops = [_._block[(r, 0)] for r in range(N_row)] + 123 return ("vstack", *ops) + 124 + 125 N_data = len(ops) + 126 op = _COOBlock( + 127 ops=( + 128 ops, # data + 129 ( + 130 tuple(range(N_data)), # i + 131 [0] * N_data, # j + 132 ), + 133 ), + 134 grid_shape=(N_data, 1), + 135 parallel=kwargs.get("parallel", False), + 136 ).op() + 137 op._expr = types.MethodType(op_expr, op) + 138 return op
        - 136 - 137 + 139 + 140
        -[docs] - 138def hstack( - 139 ops: cabc.Sequence[pxt.OpT], - 140 **kwargs, - 141) -> pxt.OpT: - 142 r""" - 143 Construct a horizontally-stacked operator. - 144 - 145 A hstacked-operator :math:`H: \mathbb{R}^{d_{1} + \cdots + d_{N}} \to \mathbb{R}^{c}` is an operator containing - 146 (horizontally) blocks of smaller operators :math:`\{O_{1}: \mathbb{R}^{d_{1}} \to \mathbb{R}^{c}, \ldots, O_{N}: - 147 \mathbb{R}^{d_{N}} \to \mathbb{R}^{c}\}`, i.e. - 148 - 149 .. math:: - 150 - 151 H - 152 = - 153 \left[ - 154 \begin{array}{ccc} - 155 O_{1} & \cdots & O_{N} - 156 \end{array} - 157 \right] - 158 - 159 Parameters - 160 ---------- - 161 ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) - 162 [op1(c, d1), ..., opN(c, dN)] operators to concatenate. - 163 kwargs - 164 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. - 165 - 166 Returns - 167 ------- - 168 op: OpT - 169 Horizontally-stacked (c, d1+....+dN) operator. - 170 - 171 Notes - 172 ----- - 173 * All sub-operator domains must have compatible shapes, i.e. all ``codim`` s must be identical. - 174 - 175 See Also - 176 -------- - 177 :py:func:`~pyxu.operator.vstack`, - 178 :py:func:`~pyxu.operator.stack`. - 179 """ - 180 - 181 def op_expr(_) -> tuple: - 182 N_col = _._grid_shape[1] - 183 ops = [_._block[(0, c)] for c in range(N_col)] - 184 return ("hstack", *ops) - 185 - 186 N_data = len(ops) - 187 op = _COOBlock( - 188 ops=( - 189 ops, # data - 190 ( - 191 [0] * N_data, # i - 192 tuple(range(N_data)), # j - 193 ), - 194 ), - 195 grid_shape=(1, N_data), - 196 parallel=kwargs.get("parallel", False), - 197 ).op() - 198 op._expr = types.MethodType(op_expr, op) - 199 return op
        +[docs] + 141def hstack( + 142 ops: cabc.Sequence[pxt.OpT], + 143 **kwargs, + 144) -> pxt.OpT: + 145 r""" + 146 Construct a horizontally-stacked operator. + 147 + 148 A hstacked-operator :math:`H: \mathbb{R}^{d_{1} + \cdots + d_{N}} \to \mathbb{R}^{c}` is an operator containing + 149 (horizontally) blocks of smaller operators :math:`\{O_{1}: \mathbb{R}^{d_{1}} \to \mathbb{R}^{c}, \ldots, O_{N}: + 150 \mathbb{R}^{d_{N}} \to \mathbb{R}^{c}\}`, i.e. + 151 + 152 .. math:: + 153 + 154 H + 155 = + 156 \left[ + 157 \begin{array}{ccc} + 158 O_{1} & \cdots & O_{N} + 159 \end{array} + 160 \right] + 161 + 162 Parameters + 163 ---------- + 164 ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) + 165 [op1(c, d1), ..., opN(c, dN)] operators to concatenate. + 166 kwargs + 167 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. + 168 + 169 Returns + 170 ------- + 171 op: OpT + 172 Horizontally-stacked (c, d1+....+dN) operator. + 173 + 174 Notes + 175 ----- + 176 * All sub-operator domains must have compatible shapes, i.e. all ``codim`` s must be identical. + 177 + 178 See Also + 179 -------- + 180 :py:func:`~pyxu.operator.vstack`, + 181 :py:func:`~pyxu.operator.stack`. + 182 """ + 183 + 184 def op_expr(_) -> tuple: + 185 N_col = _._grid_shape[1] + 186 ops = [_._block[(0, c)] for c in range(N_col)] + 187 return ("hstack", *ops) + 188 + 189 N_data = len(ops) + 190 op = _COOBlock( + 191 ops=( + 192 ops, # data + 193 ( + 194 [0] * N_data, # i + 195 tuple(range(N_data)), # j + 196 ), + 197 ), + 198 grid_shape=(1, N_data), + 199 parallel=kwargs.get("parallel", False), + 200 ).op() + 201 op._expr = types.MethodType(op_expr, op) + 202 return op
        - 200 - 201 + 203 + 204
        -[docs] - 202def block_diag( - 203 ops: cabc.Sequence[pxt.OpT], - 204 **kwargs, - 205) -> pxt.OpT: - 206 r""" - 207 Construct a block-diagonal operator. - 208 - 209 A block-diagonal operator :math:`D: \mathbb{R}^{d_{1} + \cdots + d_{N}} \to \mathbb{R}^{c_{1} + \cdots + c_{N}}` is - 210 an operator containing (diagonally) blocks of smaller operators :math:`\{O_{1}: \mathbb{R}^{d_{1}} \to - 211 \mathbb{R}^{c_{1}}, \ldots, O_{N}: \mathbb{R}^{d_{N}} \to \mathbb{R}^{c_{N}}\}`, i.e. - 212 - 213 .. math:: - 214 - 215 D - 216 = - 217 \left[ - 218 \begin{array}{ccc} - 219 O_{1} & & \\ - 220 & \ddots & \\ - 221 & & O_{N} \\ - 222 \end{array} - 223 \right] - 224 - 225 Parameters - 226 ---------- - 227 ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) - 228 [op1(c1, d1), ..., opN(cN, dN)] operators to concatenate. - 229 kwargs - 230 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. - 231 - 232 Returns - 233 ------- - 234 op: OpT - 235 Block-diagonal (c1+...+cN, d1+...+dN) operator. - 236 - 237 See Also - 238 -------- - 239 :py:func:`~pyxu.operator.block`, - 240 :py:func:`~pyxu.operator.coo_block`. - 241 """ - 242 - 243 def op_svdvals(_, **kwargs) -> pxt.NDArray: - 244 # op.svdvals(**kwargs) = [top|bottom-k]([op1.svdvals(**kwargs), ..., opN.svdvals(**kwargs)]) - 245 if not _.has(pxa.Property.LINEAR): - 246 raise NotImplementedError - 247 - 248 k = kwargs.get("k", 1) - 249 which = kwargs.get("which", "LM") - 250 if which.upper() == "SM": - 251 D = _.__class__.svdvals(_, **kwargs) - 252 else: - 253 parts = [op.svdvals(**kwargs) for op in _._block.values()] - 254 xp = pxu.get_array_module(parts[0]) - 255 D = xp.sort(xp.concatenate(parts, axis=0), axis=None)[-k:] - 256 return D - 257 - 258 @pxrt.enforce_precision(i=("arr", "damp")) - 259 def op_pinv(_, arr: pxt.NDArray, damp: pxt.Real, **kwargs) -> pxt.NDArray: - 260 # op.pinv(y, damp) = concatenate([op1.pinv(y1, damp), ..., opN.pinv(yN, damp)], axis=-1) - 261 if not _.has(pxa.Property.LINEAR): - 262 raise NotImplementedError - 263 - 264 parts = dict() - 265 for idx, op in _._block.items(): - 266 offset = _._block_offset[idx][0] - 267 p = op.pinv(arr[..., offset : offset + op.codim], damp, **kwargs) - 268 parts[idx] = p - 269 - 270 xp = pxu.get_array_module(arr) - 271 parts = [parts[k] for k in sorted(parts.keys())] - 272 out = xp.concatenate(parts, axis=-1) - 273 return out - 274 - 275 @pxrt.enforce_precision() - 276 def op_trace(_, **kwargs) -> pxt.Real: - 277 # op.trace(**kwargs) = if [op1,...,opN] square - 278 # sum([op1.trace(**kwargs), ..., opN.trace(**kwargs)]) - 279 # else - 280 # SquareOp.trace(**kwargs) - 281 if not _.has(pxa.Property.LINEAR_SQUARE): - 282 raise NotImplementedError - 283 - 284 if all(op.has(pxa.Property.LINEAR_SQUARE) for op in _._block.values()): - 285 parts = [op.trace(**kwargs) for op in _._block.values()] - 286 tr = sum(parts) - 287 else: # default fallback - 288 tr = pxa.SquareOp.trace(_, **kwargs) - 289 return tr - 290 - 291 def op_expr(_) -> tuple: - 292 ops = [_._block[k] for k in sorted(_._block.keys())] - 293 return ("block_diag", *ops) - 294 - 295 N_data = len(ops) - 296 op = _COOBlock( - 297 ops=( - 298 ops, # data - 299 ( - 300 tuple(range(N_data)), # i - 301 tuple(range(N_data)), # j - 302 ), - 303 ), - 304 grid_shape=(N_data, N_data), - 305 parallel=kwargs.get("parallel", False), - 306 ).op() - 307 op.svdvals = types.MethodType(op_svdvals, op) - 308 op.pinv = types.MethodType(op_pinv, op) - 309 op.trace = types.MethodType(op_trace, op) - 310 op._expr = types.MethodType(op_expr, op) - 311 return op
        +[docs] + 205def block_diag( + 206 ops: cabc.Sequence[pxt.OpT], + 207 **kwargs, + 208) -> pxt.OpT: + 209 r""" + 210 Construct a block-diagonal operator. + 211 + 212 A block-diagonal operator :math:`D: \mathbb{R}^{d_{1} + \cdots + d_{N}} \to \mathbb{R}^{c_{1} + \cdots + c_{N}}` is + 213 an operator containing (diagonally) blocks of smaller operators :math:`\{O_{1}: \mathbb{R}^{d_{1}} \to + 214 \mathbb{R}^{c_{1}}, \ldots, O_{N}: \mathbb{R}^{d_{N}} \to \mathbb{R}^{c_{N}}\}`, i.e. + 215 + 216 .. math:: + 217 + 218 D + 219 = + 220 \left[ + 221 \begin{array}{ccc} + 222 O_{1} & & \\ + 223 & \ddots & \\ + 224 & & O_{N} \\ + 225 \end{array} + 226 \right] + 227 + 228 Parameters + 229 ---------- + 230 ops: :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) + 231 [op1(c1, d1), ..., opN(cN, dN)] operators to concatenate. + 232 kwargs + 233 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. + 234 + 235 Returns + 236 ------- + 237 op: OpT + 238 Block-diagonal (c1+...+cN, d1+...+dN) operator. + 239 + 240 See Also + 241 -------- + 242 :py:func:`~pyxu.operator.block`, + 243 :py:func:`~pyxu.operator.coo_block`. + 244 """ + 245 + 246 def op_svdvals(_, **kwargs) -> pxt.NDArray: + 247 # op.svdvals(**kwargs) = [top|bottom-k]([op1.svdvals(**kwargs), ..., opN.svdvals(**kwargs)]) + 248 if not _.has(pxa.Property.LINEAR): + 249 raise NotImplementedError + 250 + 251 k = kwargs.get("k", 1) + 252 which = kwargs.get("which", "LM") + 253 if which.upper() == "SM": + 254 D = _.__class__.svdvals(_, **kwargs) + 255 else: + 256 parts = [op.svdvals(**kwargs) for op in _._block.values()] + 257 xp = pxu.get_array_module(parts[0]) + 258 D = xp.sort(xp.concatenate(parts, axis=0), axis=None)[-k:] + 259 return D + 260 + 261 @pxrt.enforce_precision(i=("arr", "damp")) + 262 def op_pinv(_, arr: pxt.NDArray, damp: pxt.Real, **kwargs) -> pxt.NDArray: + 263 # op.pinv(y, damp) = concatenate([op1.pinv(y1, damp), ..., opN.pinv(yN, damp)], axis=-1) + 264 if not _.has(pxa.Property.LINEAR): + 265 raise NotImplementedError + 266 + 267 parts = dict() + 268 for idx, op in _._block.items(): + 269 offset = _._block_offset[idx][0] + 270 p = op.pinv(arr[..., offset : offset + op.codim], damp, **kwargs) + 271 parts[idx] = p + 272 + 273 xp = pxu.get_array_module(arr) + 274 parts = [parts[k] for k in sorted(parts.keys())] + 275 out = xp.concatenate(parts, axis=-1) + 276 return out + 277 + 278 @pxrt.enforce_precision() + 279 def op_trace(_, **kwargs) -> pxt.Real: + 280 # op.trace(**kwargs) = if [op1,...,opN] square + 281 # sum([op1.trace(**kwargs), ..., opN.trace(**kwargs)]) + 282 # else + 283 # SquareOp.trace(**kwargs) + 284 if not _.has(pxa.Property.LINEAR_SQUARE): + 285 raise NotImplementedError + 286 + 287 if all(op.has(pxa.Property.LINEAR_SQUARE) for op in _._block.values()): + 288 parts = [op.trace(**kwargs) for op in _._block.values()] + 289 tr = sum(parts) + 290 else: # default fallback + 291 tr = pxa.SquareOp.trace(_, **kwargs) + 292 return tr + 293 + 294 def op_expr(_) -> tuple: + 295 ops = [_._block[k] for k in sorted(_._block.keys())] + 296 return ("block_diag", *ops) + 297 + 298 N_data = len(ops) + 299 op = _COOBlock( + 300 ops=( + 301 ops, # data + 302 ( + 303 tuple(range(N_data)), # i + 304 tuple(range(N_data)), # j + 305 ), + 306 ), + 307 grid_shape=(N_data, N_data), + 308 parallel=kwargs.get("parallel", False), + 309 ).op() + 310 op.svdvals = types.MethodType(op_svdvals, op) + 311 op.pinv = types.MethodType(op_pinv, op) + 312 op.trace = types.MethodType(op_trace, op) + 313 op._expr = types.MethodType(op_expr, op) + 314 return op
      - 312 - 313 + 315 + 316
      -[docs] - 314def block( - 315 ops: cabc.Sequence[cabc.Sequence[pxt.OpT]], - 316 order: pxt.Integer, - 317 **kwargs, - 318) -> pxt.OpT: - 319 r""" - 320 Construct a (dense) block-defined operator. - 321 - 322 A block-defined operator is an operator containing blocks of smaller operators. Blocks are stacked - 323 horizontally/vertically in a user-specified order to obtain the final shape. +[docs] + 317def block( + 318 ops: cabc.Sequence[cabc.Sequence[pxt.OpT]], + 319 order: pxt.Integer, + 320 **kwargs, + 321) -> pxt.OpT: + 322 r""" + 323 Construct a (dense) block-defined operator. 324 - 325 Parameters - 326 ---------- - 327 ops: :py:class:`~collections.abc.Sequence` ( :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) ) - 328 2D nested sequence of (ck, dk)-shaped operators. - 329 order: 0, 1 - 330 Order in which the nested operators are specified/concatenated: - 331 - 332 * 0: concatenate inner-most blocks via :py:func:`~pyxu.operator.vstack`, then :py:func:`~pyxu.operator.hstack`. - 333 * 1: concatenate inner-most blocks via :py:func:`~pyxu.operator.hstack`, then :py:func:`~pyxu.operator.vstack`. - 334 kwargs - 335 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. - 336 - 337 Returns - 338 ------- - 339 op: OpT - 340 Block-defined operator. (See below for examples.) - 341 - 342 Notes - 343 ----- - 344 * Each row/column may contain a different number of operators. - 345 - 346 Examples - 347 -------- + 325 A block-defined operator is an operator containing blocks of smaller operators. Blocks are stacked + 326 horizontally/vertically in a user-specified order to obtain the final shape. + 327 + 328 Parameters + 329 ---------- + 330 ops: :py:class:`~collections.abc.Sequence` ( :py:class:`~collections.abc.Sequence` ( :py:attr:`~pyxu.info.ptype.OpT` ) ) + 331 2D nested sequence of (ck, dk)-shaped operators. + 332 order: 0, 1 + 333 Order in which the nested operators are specified/concatenated: + 334 + 335 * 0: concatenate inner-most blocks via :py:func:`~pyxu.operator.vstack`, then :py:func:`~pyxu.operator.hstack`. + 336 * 1: concatenate inner-most blocks via :py:func:`~pyxu.operator.hstack`, then :py:func:`~pyxu.operator.vstack`. + 337 kwargs + 338 Extra keyword-arguments forwarded to :py:class:`~pyxu.operator.blocks._COOBlock`. + 339 + 340 Returns + 341 ------- + 342 op: OpT + 343 Block-defined operator. (See below for examples.) + 344 + 345 Notes + 346 ----- + 347 * Each row/column may contain a different number of operators. 348 - 349 .. code:: - 350 - 351 >>> block( - 352 ... [ - 353 ... [A], # ABEEGGG - 354 ... [B, C, D], # ACEEHHH - 355 ... [E, F], # ADFFHHH - 356 ... [G, H], - 357 ... ], - 358 ... order=0, - 359 ... ) - 360 - 361 >>> block( - 362 ... [ - 363 ... [A, B, C, D], # ABBCD - 364 ... [E], # EEEEE - 365 ... [F, G], # FFGGG - 366 ... ], - 367 ... order=1, - 368 ... ) - 369 - 370 See Also - 371 -------- - 372 :py:func:`~pyxu.operator.block_diag`, - 373 :py:func:`~pyxu.operator.coo_block`. - 374 """ - 375 order = int(order) - 376 assert order in {0, 1}, f"order: out-of-bounds order '{order}'." - 377 - 378 inner = {0: vstack, 1: hstack}[order] - 379 outer = {0: hstack, 1: vstack}[order] + 349 Examples + 350 -------- + 351 + 352 .. code:: + 353 + 354 >>> block( + 355 ... [ + 356 ... [A], # ABEEGGG + 357 ... [B, C, D], # ACEEHHH + 358 ... [E, F], # ADFFHHH + 359 ... [G, H], + 360 ... ], + 361 ... order=0, + 362 ... ) + 363 + 364 >>> block( + 365 ... [ + 366 ... [A, B, C, D], # ABBCD + 367 ... [E], # EEEEE + 368 ... [F, G], # FFGGG + 369 ... ], + 370 ... order=1, + 371 ... ) + 372 + 373 See Also + 374 -------- + 375 :py:func:`~pyxu.operator.block_diag`, + 376 :py:func:`~pyxu.operator.coo_block`. + 377 """ + 378 order = int(order) + 379 assert order in {0, 1}, f"order: out-of-bounds order '{order}'." 380 - 381 op = outer([inner(row, **kwargs) for row in ops], **kwargs) - 382 return op
      - + 381 inner = {0: vstack, 1: hstack}[order] + 382 outer = {0: hstack, 1: vstack}[order] 383 - 384 + 384 op = outer([inner(row, **kwargs) for row in ops], **kwargs) + 385 return op
      + + 386 + 387
      -[docs] - 385def coo_block( - 386 ops: tuple[ - 387 cabc.Sequence[pxt.OpT], - 388 tuple[ - 389 cabc.Sequence[pxt.Integer], - 390 cabc.Sequence[pxt.Integer], - 391 ], - 392 ], - 393 grid_shape: pxt.OpShape, - 394 *, - 395 parallel: bool = False, - 396) -> pxt.OpT: - 397 r""" - 398 Constuct a (possibly-sparse) block-defined operator in COOrdinate format. - 399 - 400 A block-defined operator is an operator containing blocks of smaller operators. Blocks must align on a coarse grid, - 401 akin to the COO format used to define sparse arrays. +[docs] + 388def coo_block( + 389 ops: tuple[ + 390 cabc.Sequence[pxt.OpT], + 391 tuple[ + 392 cabc.Sequence[pxt.Integer], + 393 cabc.Sequence[pxt.Integer], + 394 ], + 395 ], + 396 grid_shape: pxt.OpShape, + 397 *, + 398 parallel: bool = False, + 399) -> pxt.OpT: + 400 r""" + 401 Constuct a (possibly-sparse) block-defined operator in COOrdinate format. 402 - 403 Parameters - 404 ---------- - 405 ops - 406 (data, (i, j)) sequences defining block placement, i.e. - 407 - 408 * `data[:]` are :py:attr:`~pyxu.info.ptype.OpT` instances, in any order. - 409 * `i[:]` are the row indices of the block entries on the coarse grid. - 410 * `j[:]` are the column indices of the block entries on the coarse grid. - 411 - 412 grid_shape: OpShape - 413 (M, N) shape of the coarse grid. + 403 A block-defined operator is an operator containing blocks of smaller operators. Blocks must align on a coarse grid, + 404 akin to the COO format used to define sparse arrays. + 405 + 406 Parameters + 407 ---------- + 408 ops + 409 (data, (i, j)) sequences defining block placement, i.e. + 410 + 411 * `data[:]` are :py:attr:`~pyxu.info.ptype.OpT` instances, in any order. + 412 * `i[:]` are the row indices of the block entries on the coarse grid. + 413 * `j[:]` are the column indices of the block entries on the coarse grid. 414 - 415 parallel: bool - 416 If ``true`` , use Dask to evaluate the following methods: + 415 grid_shape: OpShape + 416 (M, N) shape of the coarse grid. 417 - 418 * ``.apply()`` - 419 * ``.prox()`` - 420 * ``.grad()`` - 421 * ``.adjoint()`` - 422 * ``.[co]gram().[apply,adjoint]()`` - 423 - 424 Returns - 425 ------- - 426 op: OpT - 427 Block-defined operator. (See below for examples.) - 428 - 429 Notes - 430 ----- - 431 * Blocks on the same row/column must have the same ``codim`` / ``dim`` s. - 432 * Each row/column of the coarse grid **must** contain at least one entry. - 433 * ``parallel=True`` only parallelizes execution when inputs to listed methods are NUMPY arrays. - 434 - 435 .. Warning:: - 436 - 437 When processing Dask inputs, or when ``parallel=True``, operators which are not thread-safe may produce incorrect - 438 results. There is no easy way to ensure thread-safety at the level of :py:mod:`~pyxu.operator.blocks` without - 439 impacting performance of all operators involved. Users are thus responsible for executing block-defined - 440 operators correctly, i.e., if thread-unsafe operators are involved, stick to NumPy/CuPy inputs. - 441 - 442 Examples - 443 -------- + 418 parallel: bool + 419 If ``true`` , use Dask to evaluate the following methods: + 420 + 421 * ``.apply()`` + 422 * ``.prox()`` + 423 * ``.grad()`` + 424 * ``.adjoint()`` + 425 * ``.[co]gram().[apply,adjoint]()`` + 426 + 427 Returns + 428 ------- + 429 op: OpT + 430 Block-defined operator. (See below for examples.) + 431 + 432 Notes + 433 ----- + 434 * Blocks on the same row/column must have the same ``codim`` / ``dim`` s. + 435 * Each row/column of the coarse grid **must** contain at least one entry. + 436 * ``parallel=True`` only parallelizes execution when inputs to listed methods are NUMPY arrays. + 437 + 438 .. Warning:: + 439 + 440 When processing Dask inputs, or when ``parallel=True``, operators which are not thread-safe may produce incorrect + 441 results. There is no easy way to ensure thread-safety at the level of :py:mod:`~pyxu.operator.blocks` without + 442 impacting performance of all operators involved. Users are thus responsible for executing block-defined + 443 operators correctly, i.e., if thread-unsafe operators are involved, stick to NumPy/CuPy inputs. 444 - 445 .. code:: - 446 - 447 >>> coo_block( - 448 ... ([A(500,1000), B(1,1000), C(500,500), D(1,3)], # data - 449 ... [ - 450 ... [0, 1, 0, 2], # i - 451 ... [0, 0, 2, 1], # j - 452 ... ]), - 453 ... grid_shape=(3, 3), - 454 ... ) - 455 - 456 | coarse_idx | 0 | 1 | 2 | - 457 |------------|--------------|---------|-------------| - 458 | 0 | A(500, 1000) | | C(500, 500) | - 459 | 1 | B(1, 1000) | | | - 460 | 2 | | D(1, 3) | | - 461 """ - 462 op = _COOBlock( - 463 ops=ops, - 464 grid_shape=grid_shape, - 465 parallel=parallel, - 466 ).op() - 467 return op
      + 445 Examples + 446 -------- + 447 + 448 .. code:: + 449 + 450 >>> coo_block( + 451 ... ([A(500,1000), B(1,1000), C(500,500), D(1,3)], # data + 452 ... [ + 453 ... [0, 1, 0, 2], # i + 454 ... [0, 0, 2, 1], # j + 455 ... ]), + 456 ... grid_shape=(3, 3), + 457 ... ) + 458 + 459 | coarse_idx | 0 | 1 | 2 | + 460 |------------|--------------|---------|-------------| + 461 | 0 | A(500, 1000) | | C(500, 500) | + 462 | 1 | B(1, 1000) | | | + 463 | 2 | | D(1, 3) | | + 464 """ + 465 op = _COOBlock( + 466 ops=ops, + 467 grid_shape=grid_shape, + 468 parallel=parallel, + 469 ).op() + 470 return op
    - 468 - 469 - 470def _parallelize(func: cabc.Callable) -> cabc.Callable: - 471 # Parallelize execution of func() under conditions. - 472 # - 473 # * func() must be one of the arithmetic methods [apply,prox,grad,adjoint,pinv]() - 474 # * the `_parallel` attribute must be attached to the instance for it to parallelize execution - 475 # over NUMPY inputs. - 476 - 477 @functools.wraps(func) - 478 def wrapper(*ARGS, **KWARGS): - 479 func_args = pxu.parse_params(func, *ARGS, **KWARGS) - 480 - 481 arr = func_args.get("arr", None) - 482 N = pxd.NDArrayInfo - 483 parallelize = ARGS[0]._parallel and (N.from_obj(arr) == N.NUMPY) - 484 - 485 # [2022.09.26] Sepand Kashani - 486 # Q: Why do we parallelize only for NUMPY inputs and not CUPY? - 487 # A: Given an arithmetic method `f`, there is no obligation (for DASK inputs) to satisfy the - 488 # relation `f(arr).chunk_type == arr.chunk_type`. - 489 # In particular the relationship does not hold for LinFunc.[grad, adjoint]() unless the - 490 # user provides a special implementation for DASK inputs. - 491 # Consequence: the sum() / xp.concatenate() instructions in _COOBlock() may: - 492 # * fail due to array-type mismatch; or - 493 # * induce unnecessary CPU<>GPU transfers. - 494 - 495 if parallelize: - 496 xp = N.DASK.module() - 497 func_args.update(arr=xp.array(arr, dtype=arr.dtype)) - 498 else: - 499 pass - 500 - 501 out = func(**func_args) - 502 f = {True: pxu.compute, False: lambda _: _}[parallelize] - 503 return f(out) - 504 - 505 return wrapper - 506 + 471 + 472 + 473def _parallelize(func: cabc.Callable) -> cabc.Callable: + 474 # Parallelize execution of func() under conditions. + 475 # + 476 # * func() must be one of the arithmetic methods [apply,prox,grad,adjoint,pinv]() + 477 # * the `_parallel` attribute must be attached to the instance for it to parallelize execution + 478 # over NUMPY inputs. + 479 + 480 @functools.wraps(func) + 481 def wrapper(*ARGS, **KWARGS): + 482 func_args = pxu.parse_params(func, *ARGS, **KWARGS) + 483 + 484 arr = func_args.get("arr", None) + 485 N = pxd.NDArrayInfo + 486 parallelize = ARGS[0]._parallel and (N.from_obj(arr) == N.NUMPY) + 487 + 488 # [2022.09.26] Sepand Kashani + 489 # Q: Why do we parallelize only for NUMPY inputs and not CUPY? + 490 # A: Given an arithmetic method `f`, there is no obligation (for DASK inputs) to satisfy the + 491 # relation `f(arr).chunk_type == arr.chunk_type`. + 492 # In particular the relationship does not hold for LinFunc.[grad, adjoint]() unless the + 493 # user provides a special implementation for DASK inputs. + 494 # Consequence: the sum() / xp.concatenate() instructions in _COOBlock() may: + 495 # * fail due to array-type mismatch; or + 496 # * induce unnecessary CPU<>GPU transfers. + 497 + 498 if parallelize: + 499 xp = N.DASK.module() + 500 func_args.update(arr=xp.array(arr, dtype=arr.dtype)) + 501 else: + 502 pass + 503 + 504 out = func(**func_args) + 505 f = {True: pxu.compute, False: lambda _: _}[parallelize] + 506 return f(out) 507 - 508class _COOBlock: # See coo_block() for a detailed description. - 509 def __init__( - 510 self, - 511 ops: tuple[ - 512 cabc.Sequence[pxt.OpT], - 513 tuple[ - 514 cabc.Sequence[pxt.Integer], - 515 cabc.Sequence[pxt.Integer], - 516 ], - 517 ], - 518 grid_shape: pxt.OpShape, - 519 parallel: bool, - 520 ): - 521 self._grid_shape = tuple(grid_shape) - 522 self._init_spec(ops) - 523 self._parallel = bool(parallel) - 524 - 525 def op(self) -> pxt.OpT: - 526 """ - 527 Returns - 528 ------- - 529 op: pxt.OpT - 530 Synthesized operator given inputs to :py:meth:`~pyxu.operator.blocks._COOBlock.__init__`. - 531 """ - 532 blk = self._block - 533 if len(blk) == 1: - 534 _, op = blk.popitem() - 535 else: - 536 import pyxu.abc.arithmetic as arithmetic - 537 - 538 op = self._infer_op() - 539 op._block = self._block # embed for introspection - 540 op._block_offset = self._block_offset # embed for introspection - 541 op._grid_shape = self._grid_shape # embed for introspection - 542 op._parallel = self._parallel # embed for introspection - 543 for p in op.properties(): - 544 for name in p.arithmetic_methods(): - 545 func = getattr(self.__class__, name) - 546 setattr(op, name, types.MethodType(func, op)) - 547 arithmetic.Rule._propagate_constants(op) - 548 return op - 549 - 550 def _init_spec(self, ops): - 551 """ - 552 Transform input into standardized form. - 553 - 554 Returns - 555 ------- - 556 block: (int, int) -> pxt.OpT - 557 coarse_grid index -> Operator at that location. - 558 block_offset: (int, int) -> (int, int) - 559 coarse_grid index -> (top-left) fine_grid index. - 560 """ - 561 data, (i, j) = ops - 562 N_row, N_col, N_block = *self._grid_shape, len(data) - 563 msg = "Incorrect COO parametrization" - 564 assert N_block == len(i) == len(j), msg - 565 assert 0 < N_block <= N_row * N_col, msg - 566 assert 0 <= min(i) <= max(i) < N_row, msg - 567 assert 0 <= min(j) <= max(j) < N_col, msg - 568 - 569 # block dimensions are compatible. - 570 row = collections.defaultdict(list) # row_idx -> [block] - 571 col = collections.defaultdict(list) # col_idx -> [block] - 572 for d, _i, _j in zip(data, i, j): - 573 row[_i].append(d) - 574 col[_j].append(d) - 575 msg = lambda dim, idx, dom: f"All sub-operators on {dim} {idx} must have same {dom} size." - 576 for k, v in row.items(): - 577 assert len({_.codim for _ in v}) == 1, msg("row", k, "codomain") - 578 for k, v in col.items(): - 579 assert len({_.dim for _ in v}) == 1, msg("column", k, "domain") - 580 - 581 # no empty lines/columns in coarse grid. - 582 msg = lambda _: f"Coarse grid contains empty {_}: cannot infer fine-grid dimensions." - 583 assert len(row) == N_row, msg("rows") - 584 assert len(col) == N_col, msg("columns") - 585 - 586 # --------------------------------------------------------------------- - 587 # create block - 588 block = dict() # coarse_grid(int, int) -> pxt.OpT - 589 for d, _i, _j in zip(data, i, j): - 590 block[(_i, _j)] = d.squeeze() - 591 self._block = block - 592 - 593 # create block_offset - 594 block_offset = dict() # coarse_grid(int, int) -> fine_grid(int, int) - 595 row_offset = np.cumsum([row[k][0].codim for k in range(N_row)]) - 596 col_offset = np.cumsum([col[k][0].dim for k in range(N_col)]) - 597 for i in range(N_row): - 598 for j in range(N_col): - 599 _i = 0 if (i == 0) else row_offset[i - 1] - 600 _j = 0 if (j == 0) else col_offset[j - 1] - 601 block_offset[(i, j)] = _i, _j - 602 self._block_offset = block_offset - 603 - 604 def _infer_op(self) -> pxt.OpT: - 605 # Create the abstract COO-operator to which methods will be assigned. - 606 blk = self._block # shorthand - 607 - 608 row = collections.defaultdict(list) - 609 col = collections.defaultdict(list) - 610 for (r, c), op in blk.items(): - 611 row[r].append(op) - 612 col[c].append(op) - 613 N_row, N_col = len(row), len(col) - 614 op_codim = sum(ops[0].codim for ops in row.values()) - 615 op_dim = sum(ops[0].dim for ops in col.values()) - 616 - 617 P = pxa.Property - 618 properties = set.intersection(*[set(op.properties()) for op in blk.values()]) - 619 if op_codim > 1: - 620 properties -= { - 621 P.FUNCTIONAL, - 622 P.PROXIMABLE, - 623 P.DIFFERENTIABLE_FUNCTION, - 624 P.QUADRATIC, - 625 } - 626 - 627 if all( # block_diag case - 628 [ - 629 N_row == N_col == len(blk), - 630 all((r, r) in blk for r in range(N_row)), - 631 ] - 632 ): - 633 pass - 634 elif op_codim == 1: # hstack case: special treatment of quadratics - 635 if all(op.has(P.QUADRATIC) for op in blk.values()): - 636 properties.add(P.QUADRATIC) - 637 elif any(op.has(P.QUADRATIC) for op in blk.values()): - 638 # possible quadratic if all other terms are linear. - 639 non_quad = [op for op in blk.values() if not op.has(P.QUADRATIC)] - 640 if all(op.has(P.LINEAR) for op in non_quad): - 641 properties.add(P.QUADRATIC) - 642 else: # (1) vstack case or (2) arbitrary fill-in case => non-functionals - 643 properties &= { - 644 P.CAN_EVAL, - 645 P.DIFFERENTIABLE, - 646 P.LINEAR, - 647 } - 648 if (op_codim == op_dim) and (P.LINEAR in properties): - 649 properties.add(P.LINEAR_SQUARE) - 650 - 651 klass = pxa.Operator._infer_operator_type(properties) - 652 op = klass(shape=(op_codim, op_dim)) - 653 return op - 654 - 655 @_parallelize - 656 @pxrt.enforce_precision(i="arr") - 657 def apply(self, arr: pxt.NDArray) -> pxt.NDArray: - 658 # compute blocks - 659 parts = dict() - 660 for idx, op in self._block.items(): - 661 offset = self._block_offset[idx][1] - 662 p = op.apply(arr[..., offset : offset + op.dim]) - 663 parts[idx] = p - 664 - 665 # row-oriented reduction (via +) - 666 rows = collections.defaultdict(list) - 667 for (r, c), p in parts.items(): - 668 rows[r].append(p) - 669 cols = [sum(rows[r]) for r in range(len(rows))] - 670 - 671 # concatenate to super-column - 672 xp = pxu.get_array_module(arr) - 673 out = xp.concatenate(cols, axis=-1) - 674 return out - 675 - 676 def __call__(self, arr: pxt.NDArray) -> pxt.NDArray: - 677 return self.apply(arr) + 508 return wrapper + 509 + 510 + 511class _COOBlock: # See coo_block() for a detailed description. + 512 def __init__( + 513 self, + 514 ops: tuple[ + 515 cabc.Sequence[pxt.OpT], + 516 tuple[ + 517 cabc.Sequence[pxt.Integer], + 518 cabc.Sequence[pxt.Integer], + 519 ], + 520 ], + 521 grid_shape: pxt.OpShape, + 522 parallel: bool, + 523 ): + 524 self._grid_shape = tuple(grid_shape) + 525 self._init_spec(ops) + 526 self._parallel = bool(parallel) + 527 + 528 def op(self) -> pxt.OpT: + 529 """ + 530 Returns + 531 ------- + 532 op: pxt.OpT + 533 Synthesized operator given inputs to :py:meth:`~pyxu.operator.blocks._COOBlock.__init__`. + 534 """ + 535 blk = self._block + 536 if len(blk) == 1: + 537 _, op = blk.popitem() + 538 else: + 539 import pyxu.abc.arithmetic as arithmetic + 540 + 541 op = self._infer_op() + 542 op._block = self._block # embed for introspection + 543 op._block_offset = self._block_offset # embed for introspection + 544 op._grid_shape = self._grid_shape # embed for introspection + 545 op._parallel = self._parallel # embed for introspection + 546 for p in op.properties(): + 547 for name in p.arithmetic_methods(): + 548 func = getattr(self.__class__, name) + 549 setattr(op, name, types.MethodType(func, op)) + 550 arithmetic.Rule._propagate_constants(op) + 551 return op + 552 + 553 def _init_spec(self, ops): + 554 """ + 555 Transform input into standardized form. + 556 + 557 Returns + 558 ------- + 559 block: (int, int) -> pxt.OpT + 560 coarse_grid index -> Operator at that location. + 561 block_offset: (int, int) -> (int, int) + 562 coarse_grid index -> (top-left) fine_grid index. + 563 """ + 564 data, (i, j) = ops + 565 N_row, N_col, N_block = *self._grid_shape, len(data) + 566 msg = "Incorrect COO parametrization" + 567 assert N_block == len(i) == len(j), msg + 568 assert 0 < N_block <= N_row * N_col, msg + 569 assert 0 <= min(i) <= max(i) < N_row, msg + 570 assert 0 <= min(j) <= max(j) < N_col, msg + 571 + 572 # block dimensions are compatible. + 573 row = collections.defaultdict(list) # row_idx -> [block] + 574 col = collections.defaultdict(list) # col_idx -> [block] + 575 for d, _i, _j in zip(data, i, j): + 576 row[_i].append(d) + 577 col[_j].append(d) + 578 msg = lambda dim, idx, dom: f"All sub-operators on {dim} {idx} must have same {dom} size." + 579 for k, v in row.items(): + 580 assert len({_.codim for _ in v}) == 1, msg("row", k, "codomain") + 581 for k, v in col.items(): + 582 assert len({_.dim for _ in v}) == 1, msg("column", k, "domain") + 583 + 584 # no empty lines/columns in coarse grid. + 585 msg = lambda _: f"Coarse grid contains empty {_}: cannot infer fine-grid dimensions." + 586 assert len(row) == N_row, msg("rows") + 587 assert len(col) == N_col, msg("columns") + 588 + 589 # --------------------------------------------------------------------- + 590 # create block + 591 block = dict() # coarse_grid(int, int) -> pxt.OpT + 592 for d, _i, _j in zip(data, i, j): + 593 block[(_i, _j)] = d.squeeze() + 594 self._block = block + 595 + 596 # create block_offset + 597 block_offset = dict() # coarse_grid(int, int) -> fine_grid(int, int) + 598 row_offset = np.cumsum([row[k][0].codim for k in range(N_row)]) + 599 col_offset = np.cumsum([col[k][0].dim for k in range(N_col)]) + 600 for i in range(N_row): + 601 for j in range(N_col): + 602 _i = 0 if (i == 0) else row_offset[i - 1] + 603 _j = 0 if (j == 0) else col_offset[j - 1] + 604 block_offset[(i, j)] = _i, _j + 605 self._block_offset = block_offset + 606 + 607 def _infer_op(self) -> pxt.OpT: + 608 # Create the abstract COO-operator to which methods will be assigned. + 609 blk = self._block # shorthand + 610 + 611 row = collections.defaultdict(list) + 612 col = collections.defaultdict(list) + 613 for (r, c), op in blk.items(): + 614 row[r].append(op) + 615 col[c].append(op) + 616 N_row, N_col = len(row), len(col) + 617 op_codim = sum(ops[0].codim for ops in row.values()) + 618 op_dim = sum(ops[0].dim for ops in col.values()) + 619 + 620 P = pxa.Property + 621 properties = set.intersection(*[set(op.properties()) for op in blk.values()]) + 622 if op_codim > 1: + 623 properties -= { + 624 P.FUNCTIONAL, + 625 P.PROXIMABLE, + 626 P.DIFFERENTIABLE_FUNCTION, + 627 P.QUADRATIC, + 628 } + 629 + 630 if all( # block_diag case + 631 [ + 632 N_row == N_col == len(blk), + 633 all((r, r) in blk for r in range(N_row)), + 634 ] + 635 ): + 636 pass + 637 elif op_codim == 1: # hstack case: special treatment of quadratics + 638 if all(op.has(P.QUADRATIC) for op in blk.values()): + 639 properties.add(P.QUADRATIC) + 640 elif any(op.has(P.QUADRATIC) for op in blk.values()): + 641 # possible quadratic if all other terms are linear. + 642 non_quad = [op for op in blk.values() if not op.has(P.QUADRATIC)] + 643 if all(op.has(P.LINEAR) for op in non_quad): + 644 properties.add(P.QUADRATIC) + 645 else: # (1) vstack case or (2) arbitrary fill-in case => non-functionals + 646 properties &= { + 647 P.CAN_EVAL, + 648 P.DIFFERENTIABLE, + 649 P.LINEAR, + 650 } + 651 if (op_codim == op_dim) and (P.LINEAR in properties): + 652 properties.add(P.LINEAR_SQUARE) + 653 + 654 klass = pxa.Operator._infer_operator_type(properties) + 655 op = klass(shape=(op_codim, op_dim)) + 656 return op + 657 + 658 @_parallelize + 659 @pxrt.enforce_precision(i="arr") + 660 def apply(self, arr: pxt.NDArray) -> pxt.NDArray: + 661 # compute blocks + 662 parts = dict() + 663 for idx, op in self._block.items(): + 664 offset = self._block_offset[idx][1] + 665 p = op.apply(arr[..., offset : offset + op.dim]) + 666 parts[idx] = p + 667 + 668 # row-oriented reduction (via +) + 669 rows = collections.defaultdict(list) + 670 for (r, c), p in parts.items(): + 671 rows[r].append(p) + 672 cols = [sum(rows[r]) for r in range(len(rows))] + 673 + 674 # concatenate to super-column + 675 xp = pxu.get_array_module(arr) + 676 out = xp.concatenate(cols, axis=-1) + 677 return out 678 - 679 def estimate_lipschitz(self, **kwargs) -> pxt.Real: - 680 Ls_all = np.zeros(self._grid_shape) # squared Lipschitz constant of each block. + 679 def __call__(self, arr: pxt.NDArray) -> pxt.NDArray: + 680 return self.apply(arr) 681 - 682 no_eval = "__rule" in kwargs - 683 if no_eval: - 684 for (r, c), op in self._block.items(): - 685 Ls_all[r, c] = op.lipschitz**2 - 686 elif self.has(pxa.Property.LINEAR): - 687 L = self.__class__.estimate_lipschitz(self, **kwargs) - 688 return L - 689 else: - 690 for (r, c), op in self._block.items(): - 691 Ls_all[r, c] = op.estimate_lipschitz(**kwargs) ** 2 - 692 - 693 # [non-linear case] Various upper bounds apply depending on how the blocks are organized: - 694 # * vertical alignment: L**2 = sum(L_k**2) - 695 # * horizontal alignment: L**2 = sum(L_k**2) - 696 # * block-diagonal alignment: L**2 = max(L_k**2) - 697 # * arbitrary 2D alignment: L**2 = sum(L_k**2) - 698 # [obtained via vertical+horizontal composition (or vice-versa)] - 699 if np.allclose(Ls_all.sum(), Ls_all.diagonal().sum()): # block-diag case - 700 L = np.sqrt(Ls_all.max()) - 701 else: - 702 L = np.sqrt(Ls_all.sum()) - 703 return L - 704 - 705 def _expr(self) -> tuple: - 706 class _Block(pxa.Operator): - 707 def __init__(self, idx: tuple[int, int], op: pxt.OpT): - 708 super().__init__(shape=op.shape) - 709 self._name = op._name - 710 self._idx = tuple(idx) - 711 self._op = op - 712 - 713 def _expr(self) -> tuple: - 714 head = "block[" + ", ".join(map(str, self._idx)) + "]" - 715 return (head, self._op) - 716 - 717 # head = coo_block[grid_shape] - 718 head = "coo_block[" + ", ".join(map(str, self._grid_shape)) + "]" + 682 def estimate_lipschitz(self, **kwargs) -> pxt.Real: + 683 Ls_all = np.zeros(self._grid_shape) # squared Lipschitz constant of each block. + 684 + 685 no_eval = "__rule" in kwargs + 686 if no_eval: + 687 for (r, c), op in self._block.items(): + 688 Ls_all[r, c] = op.lipschitz**2 + 689 elif self.has(pxa.Property.LINEAR): + 690 L = self.__class__.estimate_lipschitz(self, **kwargs) + 691 return L + 692 else: + 693 for (r, c), op in self._block.items(): + 694 Ls_all[r, c] = op.estimate_lipschitz(**kwargs) ** 2 + 695 + 696 # [non-linear case] Various upper bounds apply depending on how the blocks are organized: + 697 # * vertical alignment: L**2 = sum(L_k**2) + 698 # * horizontal alignment: L**2 = sum(L_k**2) + 699 # * block-diagonal alignment: L**2 = max(L_k**2) + 700 # * arbitrary 2D alignment: L**2 = sum(L_k**2) + 701 # [obtained via vertical+horizontal composition (or vice-versa)] + 702 if np.allclose(Ls_all.sum(), Ls_all.diagonal().sum()): # block-diag case + 703 L = np.sqrt(Ls_all.max()) + 704 else: + 705 L = np.sqrt(Ls_all.sum()) + 706 return L + 707 + 708 def _expr(self) -> tuple: + 709 class _Block(pxa.Operator): + 710 def __init__(self, idx: tuple[int, int], op: pxt.OpT): + 711 super().__init__(shape=op.shape) + 712 self._name = op._name + 713 self._idx = tuple(idx) + 714 self._op = op + 715 + 716 def _expr(self) -> tuple: + 717 head = "block[" + ", ".join(map(str, self._idx)) + "]" + 718 return (head, self._op) 719 - 720 # tail = sequence of sub-blocks, encapsulated in _Block to obtain hierarchical view. - 721 tail = [_Block(idx=k, op=op) for (k, op) in self._block.items()] - 722 return (head, *tail) - 723 - 724 @_parallelize - 725 @pxrt.enforce_precision(i=("arr", "tau")) - 726 def prox(self, arr: pxt.NDArray, tau: pxt.Real) -> pxt.NDArray: - 727 if not self.has(pxa.Property.PROXIMABLE): - 728 raise NotImplementedError - 729 - 730 parts = dict() - 731 for idx, op in self._block.items(): - 732 offset = self._block_offset[idx][1] - 733 p = op.prox(arr=arr[..., offset : offset + op.dim], tau=tau) - 734 parts[idx] = p - 735 - 736 xp = pxu.get_array_module(arr) - 737 parts = [parts[(0, c)] for c in range(len(parts))] # re-ordering - 738 out = xp.concatenate(parts, axis=-1) - 739 return out - 740 - 741 def _quad_spec(self): - 742 if not self.has(pxa.Property.QUADRATIC): - 743 raise NotImplementedError - 744 - 745 parts = dict() - 746 for idx, op in self._block.items(): - 747 if op.has(pxa.Property.QUADRATIC): - 748 _Q, _c, _t = op._quad_spec() - 749 else: # op is necessarily LINEAR - 750 from pyxu.operator import NullOp - 751 - 752 _Q = NullOp(shape=(op.dim, op.dim)).asop(pxa.PosDefOp) - 753 _c = op - 754 _t = 0 - 755 parts[idx] = _Q, _c, _t - 756 - 757 parts = [parts[k] for k in sorted(parts.keys())] # re-ordering - 758 Q, c, t = zip(*parts) - 759 return (block_diag(Q), hstack(c), sum(t)) - 760 - 761 def jacobian(self, arr: pxt.NDArray) -> pxt.OpT: - 762 if not self.has(pxa.Property.DIFFERENTIABLE): - 763 raise NotImplementedError - 764 - 765 if self.has(pxa.Property.LINEAR): - 766 out = self - 767 else: - 768 data, i, j = [], [], [] - 769 for (r, c), op in self._block.items(): - 770 offset = self._block_offset[(r, c)][1] - 771 opJ = op.jacobian(arr[offset : offset + op.dim]) - 772 - 773 i.append(r) - 774 j.append(c) - 775 data.append(opJ) - 776 - 777 out = _COOBlock( - 778 ops=(data, (i, j)), - 779 grid_shape=self._grid_shape, - 780 parallel=self._parallel, - 781 ).op() - 782 return out - 783 - 784 def estimate_diff_lipschitz(self, **kwargs) -> pxt.Real: - 785 if not self.has(pxa.Property.DIFFERENTIABLE): - 786 raise NotImplementedError - 787 - 788 dLs_all = np.zeros(self._grid_shape) # squared diff-Lipschitz constant of each block. - 789 - 790 no_eval = "__rule" in kwargs - 791 if no_eval: - 792 for (r, c), op in self._block.items(): - 793 dLs_all[r, c] = op.diff_lipschitz**2 - 794 elif self.has(pxa.Property.QUADRATIC): - 795 dL = pxa.QuadraticFunc.estimate_diff_lipschitz(self, **kwargs) - 796 return dL - 797 elif self.has(pxa.Property.LINEAR): - 798 dL = 0 + 720 # head = coo_block[grid_shape] + 721 head = "coo_block[" + ", ".join(map(str, self._grid_shape)) + "]" + 722 + 723 # tail = sequence of sub-blocks, encapsulated in _Block to obtain hierarchical view. + 724 tail = [_Block(idx=k, op=op) for (k, op) in self._block.items()] + 725 return (head, *tail) + 726 + 727 @_parallelize + 728 @pxrt.enforce_precision(i=("arr", "tau")) + 729 def prox(self, arr: pxt.NDArray, tau: pxt.Real) -> pxt.NDArray: + 730 if not self.has(pxa.Property.PROXIMABLE): + 731 raise NotImplementedError + 732 + 733 parts = dict() + 734 for idx, op in self._block.items(): + 735 offset = self._block_offset[idx][1] + 736 p = op.prox(arr=arr[..., offset : offset + op.dim], tau=tau) + 737 parts[idx] = p + 738 + 739 xp = pxu.get_array_module(arr) + 740 parts = [parts[(0, c)] for c in range(len(parts))] # re-ordering + 741 out = xp.concatenate(parts, axis=-1) + 742 return out + 743 + 744 def _quad_spec(self): + 745 if not self.has(pxa.Property.QUADRATIC): + 746 raise NotImplementedError + 747 + 748 parts = dict() + 749 for idx, op in self._block.items(): + 750 if op.has(pxa.Property.QUADRATIC): + 751 _Q, _c, _t = op._quad_spec() + 752 else: # op is necessarily LINEAR + 753 from pyxu.operator import NullOp + 754 + 755 _Q = NullOp(shape=(op.dim, op.dim)).asop(pxa.PosDefOp) + 756 _c = op + 757 _t = 0 + 758 parts[idx] = _Q, _c, _t + 759 + 760 parts = [parts[k] for k in sorted(parts.keys())] # re-ordering + 761 Q, c, t = zip(*parts) + 762 return (block_diag(Q), hstack(c), sum(t)) + 763 + 764 def jacobian(self, arr: pxt.NDArray) -> pxt.OpT: + 765 if not self.has(pxa.Property.DIFFERENTIABLE): + 766 raise NotImplementedError + 767 + 768 if self.has(pxa.Property.LINEAR): + 769 out = self + 770 else: + 771 data, i, j = [], [], [] + 772 for (r, c), op in self._block.items(): + 773 offset = self._block_offset[(r, c)][1] + 774 opJ = op.jacobian(arr[offset : offset + op.dim]) + 775 + 776 i.append(r) + 777 j.append(c) + 778 data.append(opJ) + 779 + 780 out = _COOBlock( + 781 ops=(data, (i, j)), + 782 grid_shape=self._grid_shape, + 783 parallel=self._parallel, + 784 ).op() + 785 return out + 786 + 787 def estimate_diff_lipschitz(self, **kwargs) -> pxt.Real: + 788 if not self.has(pxa.Property.DIFFERENTIABLE): + 789 raise NotImplementedError + 790 + 791 dLs_all = np.zeros(self._grid_shape) # squared diff-Lipschitz constant of each block. + 792 + 793 no_eval = "__rule" in kwargs + 794 if no_eval: + 795 for (r, c), op in self._block.items(): + 796 dLs_all[r, c] = op.diff_lipschitz**2 + 797 elif self.has(pxa.Property.QUADRATIC): + 798 dL = pxa.QuadraticFunc.estimate_diff_lipschitz(self, **kwargs) 799 return dL - 800 else: - 801 for (r, c), op in self._block.items(): - 802 dLs_all[r, c] = op.estimate_diff_lipschitz(**kwargs) ** 2 - 803 - 804 # Various upper bounds apply depending on how the blocks are organized: - 805 # * vertical alignment: dL**2 = sum(dL_k**2) - 806 # * horizontal alignment: dL**2 = sum(dL_k**2) - 807 # * block-diagonal alignment: dL**2 = max(dL_k**2) - 808 # * arbitrary 2D alignment: dL**2 = sum(dL_k**2) - 809 # [obtained via vertical+horizontal composition (or vice-versa)] - 810 if np.allclose(dLs_all.sum(), dLs_all.diagonal().sum()): # block-diag case - 811 dL = np.sqrt(dLs_all.max()) - 812 else: - 813 dL = np.sqrt(dLs_all.sum()) - 814 return dL - 815 - 816 @_parallelize - 817 @pxrt.enforce_precision(i="arr") - 818 def grad(self, arr: pxt.NDArray) -> pxt.NDArray: - 819 if not self.has(pxa.Property.DIFFERENTIABLE_FUNCTION): - 820 raise NotImplementedError - 821 - 822 parts = dict() - 823 for idx, op in self._block.items(): - 824 offset = self._block_offset[idx][1] - 825 p = op.grad(arr[..., offset : offset + op.dim]) - 826 parts[idx] = p - 827 - 828 xp = pxu.get_array_module(arr) - 829 parts = [parts[(0, c)] for c in range(len(parts))] # re-ordering - 830 out = xp.concatenate(parts, axis=-1) - 831 return out - 832 - 833 @_parallelize - 834 @pxrt.enforce_precision(i="arr") - 835 def adjoint(self, arr: pxt.NDArray) -> pxt.NDArray: - 836 if not self.has(pxa.Property.LINEAR): - 837 raise NotImplementedError - 838 - 839 # compute blocks - 840 parts = dict() - 841 for idx, op in self._block.items(): - 842 offset = self._block_offset[idx][0] - 843 p = op.adjoint(arr[..., offset : offset + op.codim]) - 844 parts[idx[::-1]] = p - 845 - 846 # row-oriented reduction (via +) - 847 rows = collections.defaultdict(list) - 848 for (r, c), p in parts.items(): - 849 rows[r].append(p) - 850 cols = [sum(rows[r]) for r in range(len(rows))] - 851 - 852 # concatenate to super-column - 853 xp = pxu.get_array_module(arr) - 854 out = xp.concatenate(cols, axis=-1) - 855 return out - 856 - 857 def asarray(self, **kwargs) -> pxt.NDArray: - 858 if not self.has(pxa.Property.LINEAR): - 859 raise NotImplementedError - 860 - 861 parts = dict() - 862 for idx, op in self._block.items(): - 863 p = op.asarray(**kwargs) - 864 parts[idx] = p - 865 - 866 xp = kwargs.get("xp", pxd.NDArrayInfo.default().module()) - 867 dtype = kwargs.get("dtype", pxrt.getPrecision().value) - 868 A = xp.zeros(self.shape, dtype=dtype) - 869 for idx, p in parts.items(): - 870 r_o, c_o = self._block_offset[idx] # offsets - 871 r_s, c_s = self._block[idx].shape # spans - 872 A[r_o : r_o + r_s, c_o : c_o + c_s] = p - 873 return A - 874 - 875 def svdvals(self, **kwargs) -> pxt.NDArray: - 876 D = self.__class__.svdvals(self, **kwargs) - 877 return D - 878 - 879 @pxrt.enforce_precision(i=("arr", "damp")) - 880 def pinv(self, arr: pxt.NDArray, damp: pxt.Real, **kwargs) -> pxt.NDArray: - 881 out = self.__class__.pinv(self, arr=arr, damp=damp, **kwargs) - 882 return out - 883 - 884 def gram(self) -> pxt.OpT: - 885 if not self.has(pxa.Property.LINEAR): - 886 raise NotImplementedError - 887 - 888 blk = self._block # shorthand - 889 N_row, N_col = self._grid_shape + 800 elif self.has(pxa.Property.LINEAR): + 801 dL = 0 + 802 return dL + 803 else: + 804 for (r, c), op in self._block.items(): + 805 dLs_all[r, c] = op.estimate_diff_lipschitz(**kwargs) ** 2 + 806 + 807 # Various upper bounds apply depending on how the blocks are organized: + 808 # * vertical alignment: dL**2 = sum(dL_k**2) + 809 # * horizontal alignment: dL**2 = sum(dL_k**2) + 810 # * block-diagonal alignment: dL**2 = max(dL_k**2) + 811 # * arbitrary 2D alignment: dL**2 = sum(dL_k**2) + 812 # [obtained via vertical+horizontal composition (or vice-versa)] + 813 if np.allclose(dLs_all.sum(), dLs_all.diagonal().sum()): # block-diag case + 814 dL = np.sqrt(dLs_all.max()) + 815 else: + 816 dL = np.sqrt(dLs_all.sum()) + 817 return dL + 818 + 819 @_parallelize + 820 @pxrt.enforce_precision(i="arr") + 821 def grad(self, arr: pxt.NDArray) -> pxt.NDArray: + 822 if not self.has(pxa.Property.DIFFERENTIABLE_FUNCTION): + 823 raise NotImplementedError + 824 + 825 parts = dict() + 826 for idx, op in self._block.items(): + 827 offset = self._block_offset[idx][1] + 828 p = op.grad(arr[..., offset : offset + op.dim]) + 829 parts[idx] = p + 830 + 831 xp = pxu.get_array_module(arr) + 832 parts = [parts[(0, c)] for c in range(len(parts))] # re-ordering + 833 out = xp.concatenate(parts, axis=-1) + 834 return out + 835 + 836 @_parallelize + 837 @pxrt.enforce_precision(i="arr") + 838 def adjoint(self, arr: pxt.NDArray) -> pxt.NDArray: + 839 if not self.has(pxa.Property.LINEAR): + 840 raise NotImplementedError + 841 + 842 # compute blocks + 843 parts = dict() + 844 for idx, op in self._block.items(): + 845 offset = self._block_offset[idx][0] + 846 p = op.adjoint(arr[..., offset : offset + op.codim]) + 847 parts[idx[::-1]] = p + 848 + 849 # row-oriented reduction (via +) + 850 rows = collections.defaultdict(list) + 851 for (r, c), p in parts.items(): + 852 rows[r].append(p) + 853 cols = [sum(rows[r]) for r in range(len(rows))] + 854 + 855 # concatenate to super-column + 856 xp = pxu.get_array_module(arr) + 857 out = xp.concatenate(cols, axis=-1) + 858 return out + 859 + 860 def asarray(self, **kwargs) -> pxt.NDArray: + 861 if not self.has(pxa.Property.LINEAR): + 862 raise NotImplementedError + 863 + 864 parts = dict() + 865 for idx, op in self._block.items(): + 866 p = op.asarray(**kwargs) + 867 parts[idx] = p + 868 + 869 xp = kwargs.get("xp", pxd.NDArrayInfo.default().module()) + 870 dtype = kwargs.get("dtype", pxrt.getPrecision().value) + 871 A = xp.zeros(self.shape, dtype=dtype) + 872 for idx, p in parts.items(): + 873 r_o, c_o = self._block_offset[idx] # offsets + 874 r_s, c_s = self._block[idx].shape # spans + 875 A[r_o : r_o + r_s, c_o : c_o + c_s] = p + 876 return A + 877 + 878 def svdvals(self, **kwargs) -> pxt.NDArray: + 879 D = self.__class__.svdvals(self, **kwargs) + 880 return D + 881 + 882 @pxrt.enforce_precision(i=("arr", "damp")) + 883 def pinv(self, arr: pxt.NDArray, damp: pxt.Real, **kwargs) -> pxt.NDArray: + 884 out = self.__class__.pinv(self, arr=arr, damp=damp, **kwargs) + 885 return out + 886 + 887 def gram(self) -> pxt.OpT: + 888 if not self.has(pxa.Property.LINEAR): + 889 raise NotImplementedError 890 - 891 # Determine operator(s) which will occupy position (r,c) on coarse grid. - 892 ops = collections.defaultdict(list) # coarse_grid(int, int) -> [pxt.OpT] - 893 for r, c in itertools.product(range(N_col), repeat=2): - 894 for k in range(N_row): - 895 if ((k, r) in blk) and ((k, c) in blk): - 896 if r == c: - 897 _op = blk[(k, r)].gram() - 898 else: - 899 _op = blk[(k, r)].T * blk[(k, c)] - 900 ops[(r, c)].append(_op) - 901 - 902 # ops[(r,c)] should be reduced (via +) to form a single operator per (r,c)-entry. - 903 # It is inefficient however to chain so many operators together via AddRule(). - 904 # G.[apply,adjoint]() are thus redefined to improve performance. - 905 data, i, j = [], [], [] - 906 for (r, c), _ops in ops.items(): - 907 klass = pxa.SelfAdjointOp if (r == c) else pxa.LinOp - 908 _op = klass(shape=_ops[0].shape) # .[apply|adjoint]() overridden below. - 909 _op._ops = _ops # embed for introspection - 910 - 911 @pxrt.enforce_precision(i="arr") - 912 def op_apply(_, arr: pxt.NDArray) -> pxt.NDArray: - 913 parts = [op.apply(arr) for op in _._ops] - 914 out = sum(parts) - 915 return out - 916 - 917 @pxrt.enforce_precision(i="arr") - 918 def op_adjoint(_, arr: pxt.NDArray) -> pxt.NDArray: - 919 parts = [op.adjoint(arr) for op in _._ops] - 920 out = sum(parts) - 921 return out - 922 - 923 _op.apply = types.MethodType(op_apply, _op) - 924 _op.adjoint = types.MethodType(op_adjoint, _op) + 891 blk = self._block # shorthand + 892 N_row, N_col = self._grid_shape + 893 + 894 # Determine operator(s) which will occupy position (r,c) on coarse grid. + 895 ops = collections.defaultdict(list) # coarse_grid(int, int) -> [pxt.OpT] + 896 for r, c in itertools.product(range(N_col), repeat=2): + 897 for k in range(N_row): + 898 if ((k, r) in blk) and ((k, c) in blk): + 899 if r == c: + 900 _op = blk[(k, r)].gram() + 901 else: + 902 _op = blk[(k, r)].T * blk[(k, c)] + 903 ops[(r, c)].append(_op) + 904 + 905 # ops[(r,c)] should be reduced (via +) to form a single operator per (r,c)-entry. + 906 # It is inefficient however to chain so many operators together via AddRule(). + 907 # G.[apply,adjoint]() are thus redefined to improve performance. + 908 data, i, j = [], [], [] + 909 for (r, c), _ops in ops.items(): + 910 klass = pxa.SelfAdjointOp if (r == c) else pxa.LinOp + 911 _op = klass(shape=_ops[0].shape) # .[apply|adjoint]() overridden below. + 912 _op._ops = _ops # embed for introspection + 913 + 914 @pxrt.enforce_precision(i="arr") + 915 def op_apply(_, arr: pxt.NDArray) -> pxt.NDArray: + 916 parts = [op.apply(arr) for op in _._ops] + 917 out = sum(parts) + 918 return out + 919 + 920 @pxrt.enforce_precision(i="arr") + 921 def op_adjoint(_, arr: pxt.NDArray) -> pxt.NDArray: + 922 parts = [op.adjoint(arr) for op in _._ops] + 923 out = sum(parts) + 924 return out 925 - 926 data.append(_op) - 927 i.append(r) - 928 j.append(c) - 929 G = ( - 930 _COOBlock( - 931 ops=(data, (i, j)), - 932 grid_shape=(N_col, N_col), - 933 parallel=self._parallel, - 934 ) - 935 .op() - 936 .asop(pxa.SelfAdjointOp) - 937 ) - 938 return G.squeeze() - 939 - 940 def cogram(self) -> pxt.OpT: - 941 if not self.has(pxa.Property.LINEAR): - 942 raise NotImplementedError - 943 - 944 blk = self._block # shorthand - 945 N_row, N_col = self._grid_shape + 926 _op.apply = types.MethodType(op_apply, _op) + 927 _op.adjoint = types.MethodType(op_adjoint, _op) + 928 + 929 data.append(_op) + 930 i.append(r) + 931 j.append(c) + 932 G = ( + 933 _COOBlock( + 934 ops=(data, (i, j)), + 935 grid_shape=(N_col, N_col), + 936 parallel=self._parallel, + 937 ) + 938 .op() + 939 .asop(pxa.SelfAdjointOp) + 940 ) + 941 return G.squeeze() + 942 + 943 def cogram(self) -> pxt.OpT: + 944 if not self.has(pxa.Property.LINEAR): + 945 raise NotImplementedError 946 - 947 # Determine operator(s) which will occupy position (r,c) on coarse grid. - 948 ops = collections.defaultdict(list) # coarse_grid(int, int) -> [pxt.OpT] - 949 for r, c in itertools.product(range(N_row), repeat=2): - 950 for k in range(N_col): - 951 if ((r, k) in blk) and ((c, k) in blk): - 952 if r == c: - 953 _op = blk[(r, k)].cogram() - 954 else: - 955 _op = blk[(r, k)] * blk[(c, k)].T - 956 ops[(r, c)].append(_op) - 957 - 958 # ops[(r,c)] should be reduced (via +) to form a single operator per (r,c)-entry. - 959 # It is inefficient however to chain so many operators together via AddRule(). - 960 # CG.[apply,adjoint]() are thus redefined to improve performance. - 961 data, i, j = [], [], [] - 962 for (r, c), _ops in ops.items(): - 963 klass = pxa.SelfAdjointOp if (r == c) else pxa.LinOp - 964 _op = klass(shape=_ops[0].shape) # .[apply|adjoint]() overridden below. - 965 _op._ops = _ops # embed for introspection - 966 - 967 @pxrt.enforce_precision(i="arr") - 968 def op_apply(_, arr: pxt.NDArray) -> pxt.NDArray: - 969 parts = [op.apply(arr) for op in _._ops] - 970 out = sum(parts) - 971 return out - 972 - 973 @pxrt.enforce_precision(i="arr") - 974 def op_adjoint(_, arr: pxt.NDArray) -> pxt.NDArray: - 975 parts = [op.adjoint(arr) for op in _._ops] - 976 out = sum(parts) - 977 return out - 978 - 979 _op.apply = types.MethodType(op_apply, _op) - 980 _op.adjoint = types.MethodType(op_adjoint, _op) + 947 blk = self._block # shorthand + 948 N_row, N_col = self._grid_shape + 949 + 950 # Determine operator(s) which will occupy position (r,c) on coarse grid. + 951 ops = collections.defaultdict(list) # coarse_grid(int, int) -> [pxt.OpT] + 952 for r, c in itertools.product(range(N_row), repeat=2): + 953 for k in range(N_col): + 954 if ((r, k) in blk) and ((c, k) in blk): + 955 if r == c: + 956 _op = blk[(r, k)].cogram() + 957 else: + 958 _op = blk[(r, k)] * blk[(c, k)].T + 959 ops[(r, c)].append(_op) + 960 + 961 # ops[(r,c)] should be reduced (via +) to form a single operator per (r,c)-entry. + 962 # It is inefficient however to chain so many operators together via AddRule(). + 963 # CG.[apply,adjoint]() are thus redefined to improve performance. + 964 data, i, j = [], [], [] + 965 for (r, c), _ops in ops.items(): + 966 klass = pxa.SelfAdjointOp if (r == c) else pxa.LinOp + 967 _op = klass(shape=_ops[0].shape) # .[apply|adjoint]() overridden below. + 968 _op._ops = _ops # embed for introspection + 969 + 970 @pxrt.enforce_precision(i="arr") + 971 def op_apply(_, arr: pxt.NDArray) -> pxt.NDArray: + 972 parts = [op.apply(arr) for op in _._ops] + 973 out = sum(parts) + 974 return out + 975 + 976 @pxrt.enforce_precision(i="arr") + 977 def op_adjoint(_, arr: pxt.NDArray) -> pxt.NDArray: + 978 parts = [op.adjoint(arr) for op in _._ops] + 979 out = sum(parts) + 980 return out 981 - 982 data.append(_op) - 983 i.append(r) - 984 j.append(c) - 985 CG = ( - 986 _COOBlock( - 987 ops=(data, (i, j)), - 988 grid_shape=(N_row, N_row), - 989 parallel=self._parallel, - 990 ) - 991 .op() - 992 .asop(pxa.SelfAdjointOp) - 993 ) - 994 return CG.squeeze() - 995 - 996 @pxrt.enforce_precision() - 997 def trace(self, **kwargs) -> pxt.Real: - 998 tr = self.__class__.trace(self, **kwargs) - 999 return tr -1000 -1001 def asloss(self, data: pxt.NDArray = None) -> pxt.OpT: -1002 msg = "asloss() is ambiguous for block-defined operators." -1003 raise NotImplementedError(msg) + 982 _op.apply = types.MethodType(op_apply, _op) + 983 _op.adjoint = types.MethodType(op_adjoint, _op) + 984 + 985 data.append(_op) + 986 i.append(r) + 987 j.append(c) + 988 CG = ( + 989 _COOBlock( + 990 ops=(data, (i, j)), + 991 grid_shape=(N_row, N_row), + 992 parallel=self._parallel, + 993 ) + 994 .op() + 995 .asop(pxa.SelfAdjointOp) + 996 ) + 997 return CG.squeeze() + 998 + 999 @pxrt.enforce_precision() +1000 def trace(self, **kwargs) -> pxt.Real: +1001 tr = self.__class__.trace(self, **kwargs) +1002 return tr +1003 +1004 def asloss(self, data: pxt.NDArray = None) -> pxt.OpT: +1005 msg = "asloss() is ambiguous for block-defined operators." +1006 raise NotImplementedError(msg)
    diff --git a/_modules/pyxu/operator/func/indicator.html b/_modules/pyxu/operator/func/indicator.html index e2bc2b76..fcc73a47 100644 --- a/_modules/pyxu/operator/func/indicator.html +++ b/_modules/pyxu/operator/func/indicator.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
  • @@ -378,7 +378,7 @@ - +
  • @@ -523,7 +523,7 @@

    Source code for pyxu.operator.func.indicator

     70
  71
 
    
-[docs]
+[docs]
  72def L1Ball(dim: pxt.Integer, radius: pxt.Real = 1) -> pxt.OpT:
  73    r"""
  74    Indicator function of the :math:`\ell_{1}`-ball.
@@ -560,7 +560,7 @@ 
    Source code for pyxu.operator.func.indicator
    104
 105
 
    
-[docs]
+[docs]
 106def L2Ball(dim: pxt.Integer, radius: pxt.Real = 1) -> pxt.OpT:
 107    r"""
 108    Indicator function of the :math:`\ell_{2}`-ball.
@@ -597,7 +597,7 @@ 
    Source code for pyxu.operator.func.indicator
    138
 139
 
    
-[docs]
+[docs]
 140def LInfinityBall(dim: pxt.Integer, radius: pxt.Real = 1) -> pxt.OpT:
 141    r"""
 142    Indicator function of the :math:`\ell_{\infty}`-ball.
@@ -634,7 +634,7 @@ 
    Source code for pyxu.operator.func.indicator
    172
 173
 
    
-[docs]
+[docs]
 174class PositiveOrthant(_IndicatorFunction):
 175    r"""
 176    Indicator function of the positive orthant.
@@ -672,7 +672,7 @@ 
    Source code for pyxu.operator.func.indicator
    207
 208
 
    
-[docs]
+[docs]
 209class HyperSlab(_IndicatorFunction):
 210    r"""
 211    Indicator function of a hyperslab.
@@ -698,7 +698,7 @@ 
    Source code for pyxu.operator.func.indicator
    231    """
 232
 
    
-[docs]
+[docs]
 233    @pxrt.enforce_precision(i=("lb", "ub"))
 234    def __init__(self, a: pxa.LinFunc, lb: pxt.Real, ub: pxt.Real):
 235        """
@@ -749,7 +749,7 @@ 
    Source code for pyxu.operator.func.indicator
    278
 279
 
    
-[docs]
+[docs]
 280class RangeSet(_IndicatorFunction):
 281    r"""
 282    Indicator function of a range set.
@@ -771,7 +771,7 @@ 
    Source code for pyxu.operator.func.indicator
    298    """
 299
 
    
-[docs]
+[docs]
 300    def __init__(self, A: pxa.LinOp):
 301        """
 302        Parameters
@@ -811,7 +811,7 @@ 
    Source code for pyxu.operator.func.indicator
    334
 335
 
    
-[docs]
+[docs]
 336class AffineSet(_IndicatorFunction):
 337    r"""
 338    Indicator function of an affine set.
@@ -843,7 +843,7 @@ 
    Source code for pyxu.operator.func.indicator
    364    """
 365
 
    
-[docs]
+[docs]
 366    @pxrt.enforce_precision(i="b")
 367    def __init__(self, A: pxa.LinOp, b: pxt.NDArray):
 368        """
@@ -883,7 +883,7 @@ 
    Source code for pyxu.operator.func.indicator
    400
 401
 
    
-[docs]
+[docs]
 402class ConvexSetIntersection(_IndicatorFunction):
 403    r"""
 404    Indicator function of an intersection of convex domains :math:`\mathcal{C}_{1} \cap \cdots \cap \mathcal{C}_{K}`.
@@ -924,7 +924,7 @@ 
    Source code for pyxu.operator.func.indicator
    439    """
 440
 
    
-[docs]
+[docs]
 441    def __init__(self, *args: cabc.Sequence[pxa.ProxFunc]):
 442        """
 443        Parameters
@@ -959,7 +959,7 @@ 
    Source code for pyxu.operator.func.indicator
    471        return out
 472
 
    
-[docs]
+[docs]
 473    @pxrt.enforce_precision(i=("arr", "tau"))
 474    def prox(self, arr: pxt.NDArray, tau: pxt.Real) -> pxt.NDArray:
 475        if len(self._f) == 1:
diff --git a/_modules/pyxu/operator/func/loss.html b/_modules/pyxu/operator/func/loss.html
index 42f33837..a6a0c91f 100644
--- a/_modules/pyxu/operator/func/loss.html
+++ b/_modules/pyxu/operator/func/loss.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -463,7 +463,7 @@

    Source code for pyxu.operator.func.loss

      10
  11
 
    
-[docs]
+[docs]
  12def shift_loss(
  13    op: pxt.OpT,
  14    data: pxt.NDArray = None,
@@ -493,7 +493,7 @@ 
    Source code for pyxu.operator.func.loss
      37
  38
 
    
-[docs]
+[docs]
  39class KLDivergence(pxa.ProxFunc):
  40    r"""
  41    Generalised Kullback-Leibler divergence :math:`D_{KL}(\mathbf{y}||\mathbf{x}):=\sum_{i=1}^N y_i\log(y_i/x_i) -y_i
@@ -501,7 +501,7 @@ 
    Source code for pyxu.operator.func.loss
      43    """
  44
 
    
-[docs]
+[docs]
  45    def __init__(
  46        self,
  47        dim: pxt.Integer,
diff --git a/_modules/pyxu/operator/func/norm.html b/_modules/pyxu/operator/func/norm.html
index 3ce1d57e..491a85a0 100644
--- a/_modules/pyxu/operator/func/norm.html
+++ b/_modules/pyxu/operator/func/norm.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -484,7 +484,7 @@

    Source code for pyxu.operator.func.norm

      31
  32
 
    
-[docs]
+[docs]
  33class L1Norm(_ShiftLossMixin, pxa.ProxFunc):
  34    r"""
  35    :math:`\ell_{1}`-norm, :math:`\Vert\mathbf{x}\Vert_{1} := \sum_{i=1}^{N} |x_{i}|`.
@@ -509,7 +509,7 @@ 
    Source code for pyxu.operator.func.norm
      53
  54
 
    
-[docs]
+[docs]
  55class L2Norm(_ShiftLossMixin, pxa.ProxFunc):
  56    r"""
  57    :math:`\ell_{2}`-norm, :math:`\Vert\mathbf{x}\Vert_{2} := \sqrt{\sum_{i=1}^{N} |x_{i}|^{2}}`.
@@ -537,7 +537,7 @@ 
    Source code for pyxu.operator.func.norm
      78
  79
 
    
-[docs]
+[docs]
  80class SquaredL2Norm(pxa.QuadraticFunc):
  81    r"""
  82    :math:`\ell^{2}_{2}`-norm, :math:`\Vert\mathbf{x}\Vert^{2}_{2} := \sum_{i=1}^{N} |x_{i}|^{2}`.
@@ -575,14 +575,14 @@ 
    Source code for pyxu.operator.func.norm
     113
 114
 
    
-[docs]
+[docs]
 115class SquaredL1Norm(_ShiftLossMixin, pxa.ProxFunc):
 116    r"""
 117    :math:`\ell^{2}_{1}`-norm, :math:`\Vert\mathbf{x}\Vert^{2}_{1} := (\sum_{i=1}^{N} |x_{i}|)^{2}`.
 118    """
 119
 
    
-[docs]
+[docs]
 120    def __init__(self, dim: pxt.Integer, prox_algo: str = "sort"):
 121        r"""
 122        Parameters
@@ -678,7 +678,7 @@ 
    Source code for pyxu.operator.func.norm
     211        return out
 212
 
    
-[docs]
+[docs]
 213    @pxrt.enforce_precision(i=("arr", "tau"))
 214    def prox(self, arr: pxt.NDArray, tau: pxt.Real) -> pxt.NDArray:
 215        N = pxd.NDArrayInfo
@@ -709,7 +709,7 @@ 
    Source code for pyxu.operator.func.norm
     238
 239
 
    
-[docs]
+[docs]
 240class LInfinityNorm(_ShiftLossMixin, pxa.ProxFunc):
 241    r"""
 242    :math:`\ell_{\infty}`-norm, :math:`\Vert\mathbf{x}\Vert_{\infty} := \max_{i=1,\ldots,N} |x_{i}|`.
@@ -767,7 +767,7 @@ 
    Source code for pyxu.operator.func.norm
     293
 294
 
    
-[docs]
+[docs]
 295class L21Norm(_ShiftLossMixin, pxa.ProxFunc):
 296    r"""
 297    Mixed :math:`\ell_{2}-\ell_{1}` norm, :math:`\Vert\mathbf{x}\Vert_{2, 1} := \sum_{i=1}^{N} \sqrt{\sum_{j=1}^{M}
@@ -780,7 +780,7 @@ 
    Source code for pyxu.operator.func.norm
     304    """
 305
 
    
-[docs]
+[docs]
 306    def __init__(
 307        self,
 308        arg_shape: pxt.NDArrayShape,
@@ -842,7 +842,7 @@ 
    Source code for pyxu.operator.func.norm
     362
 363
 
    
-[docs]
+[docs]
 364class PositiveL1Norm(_ShiftLossMixin, pxa.ProxFunc):
 365    r"""
 366    :math:`\ell_{1}`-norm, with a positivity constraint.
diff --git a/_modules/pyxu/operator/interop/jax.html b/_modules/pyxu/operator/interop/jax.html
index 98e28b3f..647aed3f 100644
--- a/_modules/pyxu/operator/interop/jax.html
+++ b/_modules/pyxu/operator/interop/jax.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • diff --git a/_modules/pyxu/operator/interop/sciop.html b/_modules/pyxu/operator/interop/sciop.html index f09713cf..a5b43f2d 100644 --- a/_modules/pyxu/operator/interop/sciop.html +++ b/_modules/pyxu/operator/interop/sciop.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
  • @@ -378,7 +378,7 @@ - +
  • diff --git a/_modules/pyxu/operator/interop/source.html b/_modules/pyxu/operator/interop/source.html index 4ca83b72..05675977 100644 --- a/_modules/pyxu/operator/interop/source.html +++ b/_modules/pyxu/operator/interop/source.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
  • @@ -378,7 +378,7 @@ - +
  • diff --git a/_modules/pyxu/operator/interop/torch.html b/_modules/pyxu/operator/interop/torch.html index be71ddd2..eb79d55a 100644 --- a/_modules/pyxu/operator/interop/torch.html +++ b/_modules/pyxu/operator/interop/torch.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
  • @@ -378,7 +378,7 @@ - +
  • diff --git a/_modules/pyxu/operator/linop/base.html b/_modules/pyxu/operator/linop/base.html index 47c0c2ff..eadc85c4 100644 --- a/_modules/pyxu/operator/linop/base.html +++ b/_modules/pyxu/operator/linop/base.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + diff --git a/_modules/pyxu/operator/linop/diff.html b/_modules/pyxu/operator/linop/diff.html index cdcbe812..4551b566 100644 --- a/_modules/pyxu/operator/linop/diff.html +++ b/_modules/pyxu/operator/linop/diff.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
  • @@ -378,7 +378,7 @@ - +
  • @@ -896,7 +896,7 @@

    Source code for pyxu.operator.linop.diff

      443
  444
 
    
-[docs]
+[docs]
  445class PartialDerivative:
  446    r"""
  447    Partial derivative operator based on `Numba stencils
@@ -953,7 +953,7 @@ 
    Source code for pyxu.operator.linop.diff
      498    """
  499
 
    
-[docs]
+[docs]
  500    @staticmethod
  501    def finite_difference(
  502        arg_shape: pxt.NDArrayShape,
@@ -1151,9 +1151,9 @@ 
    Source code for pyxu.operator.linop.diff
      694           axs[2].set_title(r"$\frac{\partial^{3} f(x,y)}{\partial x\partial y^{2}}$")
  695           plt.colorbar(im, ax=axs[2])
  696
- 697           # Test approximation error
+ 697           # Check approximation error
  698           plt.figure()
- 699           plt.imshow(abs(out1 - out2) / abs(out2)), plt.colorbar()
+ 699           plt.imshow(abs(out1 - out2)), plt.colorbar()
  700
  701        """
  702        assert isinstance(order, cabc.Sequence), "`order` should be a tuple / list"
@@ -1197,7 +1197,7 @@ 
    Source code for pyxu.operator.linop.diff
     
  740
 
    
-[docs]
+[docs]
  741    @staticmethod
  742    def gaussian_derivative(
  743        arg_shape: pxt.NDArrayShape,
@@ -1573,7 +1573,7 @@ 
    Source code for pyxu.operator.linop.diff
     1111
 1112
 
    
-[docs]
+[docs]
 1113def Gradient(
 1114    arg_shape: pxt.NDArrayShape,
 1115    directions: typ.Optional[pxt.NDArrayAxis] = None,
@@ -1731,7 +1731,7 @@ 
    Source code for pyxu.operator.linop.diff
     1266
 1267
 
    
-[docs]
+[docs]
 1268def Jacobian(
 1269    arg_shape: pxt.NDArrayShape,
 1270    n_channels: pxt.Integer,
@@ -1884,7 +1884,7 @@ 
    Source code for pyxu.operator.linop.diff
     1416
 1417
 
    
-[docs]
+[docs]
 1418def Divergence(
 1419    arg_shape: pxt.NDArrayShape,
 1420    directions: typ.Optional[pxt.NDArrayAxis] = None,
@@ -2060,7 +2060,7 @@ 
    Source code for pyxu.operator.linop.diff
     1589
 1590
 
    
-[docs]
+[docs]
 1591def Hessian(
 1592    arg_shape: pxt.NDArrayShape,
 1593    directions: typ.Union[
@@ -2271,7 +2271,7 @@ 
    Source code for pyxu.operator.linop.diff
     1797
 1798
 
    
-[docs]
+[docs]
 1799def Laplacian(
 1800    arg_shape: pxt.NDArrayShape,
 1801    directions: typ.Optional[pxt.NDArrayAxis] = None,
@@ -2413,7 +2413,7 @@ 
    Source code for pyxu.operator.linop.diff
     1936
 1937
 
    
-[docs]
+[docs]
 1938def DirectionalDerivative(
 1939    arg_shape: pxt.NDArrayShape,
 1940    order: pxt.Integer,
@@ -2664,7 +2664,7 @@ 
    Source code for pyxu.operator.linop.diff
     2184
 2185
 
    
-[docs]
+[docs]
 2186def DirectionalGradient(
 2187    arg_shape: pxt.NDArrayShape,
 2188    directions: cabc.Sequence[pxt.NDArray],
@@ -2839,7 +2839,7 @@ 
    Source code for pyxu.operator.linop.diff
     2356
 2357
 
    
-[docs]
+[docs]
 2358def DirectionalLaplacian(
 2359    arg_shape: pxt.NDArrayShape,
 2360    directions: cabc.Sequence[pxt.NDArray],
@@ -3030,7 +3030,7 @@ 
    Source code for pyxu.operator.linop.diff
     2544
 2545
 
    
-[docs]
+[docs]
 2546def DirectionalHessian(
 2547    arg_shape: pxt.NDArrayShape,
 2548    directions: cabc.Sequence[pxt.NDArray],
diff --git a/_modules/pyxu/operator/linop/fft/fft.html b/_modules/pyxu/operator/linop/fft/fft.html
index de72a3bc..0f320b66 100644
--- a/_modules/pyxu/operator/linop/fft/fft.html
+++ b/_modules/pyxu/operator/linop/fft/fft.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -468,7 +468,7 @@

    Source code for pyxu.operator.linop.fft.fft

      15
  16
 
    
-[docs]
+[docs]
  17class FFT(pxa.LinOp):  # Inherits from LinOp instead of NormalOp since operator not square if `real=True`.
  18    r"""
  19    Multi-dimensional Discrete Fourier Transform (DFT) :math:`A: \mathbb{C}^{N_{1} \times \cdots \times N_{D}} \to
@@ -611,7 +611,7 @@ 
    Source code for pyxu.operator.linop.fft.fft
     156    """
 157
 
    
-[docs]
+[docs]
 158    def __init__(
 159        self,
 160        arg_shape: pxt.NDArrayShape,
@@ -760,7 +760,7 @@ 
    Source code for pyxu.operator.linop.fft.fft
     302        return out
 303
 
    
-[docs]
+[docs]
 304    @pxrt.enforce_precision(i="arr")
 305    def apply(self, arr: pxt.NDArray) -> pxt.NDArray:
 306        r"""
@@ -803,7 +803,7 @@ 
    Source code for pyxu.operator.linop.fft.fft
     
 343
 
    
-[docs]
+[docs]
 344    @pxrt.enforce_precision(i="arr")
 345    def adjoint(self, arr: pxt.NDArray) -> pxt.NDArray:
 346        r"""
diff --git a/_modules/pyxu/operator/linop/fft/nufft.html b/_modules/pyxu/operator/linop/fft/nufft.html
index c6b018fa..9e7fc16b 100644
--- a/_modules/pyxu/operator/linop/fft/nufft.html
+++ b/_modules/pyxu/operator/linop/fft/nufft.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
diff --git a/_modules/pyxu/operator/linop/filter.html b/_modules/pyxu/operator/linop/filter.html
index 188338ed..80e57caa 100644
--- a/_modules/pyxu/operator/linop/filter.html
+++ b/_modules/pyxu/operator/linop/filter.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -525,7 +525,7 @@

    Source code for pyxu.operator.linop.filter

       72
   73
 
    
-[docs]
+[docs]
   74def MovingAverage(
   75    arg_shape: pxt.NDArrayShape,
   76    size: typ.Union[typ.Tuple, pxt.Integer],
@@ -640,7 +640,7 @@ 
    Source code for pyxu.operator.linop.filter
      184
  185
 
    
-[docs]
+[docs]
  186def Gaussian(
  187    arg_shape: pxt.NDArrayShape,
  188    sigma: typ.Union[typ.Tuple[pxt.Real], pxt.Real] = 1.0,
@@ -770,7 +770,7 @@ 
    Source code for pyxu.operator.linop.filter
      311
  312
 
    
-[docs]
+[docs]
  313def DifferenceOfGaussians(
  314    arg_shape: pxt.NDArrayShape,
  315    low_sigma=1.0,
@@ -902,7 +902,7 @@ 
    Source code for pyxu.operator.linop.filter
      440
  441
 
    
-[docs]
+[docs]
  442def Laplace(
  443    arg_shape: pxt.NDArrayShape,
  444    mode: ModeSpec = "constant",
@@ -998,7 +998,7 @@ 
    Source code for pyxu.operator.linop.filter
      533
  534
 
    
-[docs]
+[docs]
  535def Sobel(
  536    arg_shape: pxt.NDArrayShape,
  537    axis: typ.Optional[typ.Tuple] = None,
@@ -1099,7 +1099,7 @@ 
    Source code for pyxu.operator.linop.filter
      631
  632
 
    
-[docs]
+[docs]
  633def Prewitt(
  634    arg_shape: pxt.NDArrayShape,
  635    axis: typ.Optional[typ.Tuple] = None,
@@ -1200,7 +1200,7 @@ 
    Source code for pyxu.operator.linop.filter
      729
  730
 
    
-[docs]
+[docs]
  731def Scharr(
  732    arg_shape: pxt.NDArrayShape,
  733    axis: typ.Optional[typ.Tuple] = None,
@@ -1342,7 +1342,7 @@ 
    Source code for pyxu.operator.linop.filter
      868
  869
 
    
-[docs]
+[docs]
  870class StructureTensor(pxa.DiffMap):
  871    r"""
  872    Structure tensor operator.
@@ -1492,19 +1492,19 @@ 
    Source code for pyxu.operator.linop.filter
     1016            self.smooth = pxlb.IdentityOp(dim=np.prod(arg_shape).item())
 1017
 
    
-[docs]
+[docs]
 1018    def unravel(self, arr):
 1019        return arr.reshape(*arr.shape[:-1], -1, *self.arg_shape)
    
 
 1020
 
    
-[docs]
+[docs]
 1021    def ravel(self, arr):
 1022        return arr.reshape(*arr.shape[: -1 - len(self.arg_shape)], -1)
    
 
 1023
 
    
-[docs]
+[docs]
 1024    def apply(self, arr):
 1025        xp = pxu.get_array_module(arr)
 1026        sh = arr.shape[:-1]
diff --git a/_modules/pyxu/operator/linop/kron.html b/_modules/pyxu/operator/linop/kron.html
index 39af0e49..9c3ec1cf 100644
--- a/_modules/pyxu/operator/linop/kron.html
+++ b/_modules/pyxu/operator/linop/kron.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -467,7 +467,7 @@

    Source code for pyxu.operator.linop.kron

      14
  15
 
    
-[docs]
+[docs]
  16def kron(A: pxt.OpT, B: pxt.OpT) -> pxt.OpT:
  17    r"""
  18    `Kronecker product <https://en.wikipedia.org/wiki/Kronecker_product#Definition>`_ :math:`A \otimes B` between two
@@ -694,7 +694,7 @@ 
    Source code for pyxu.operator.linop.kron
     238
 239
 
    
-[docs]
+[docs]
 240def khatri_rao(A: pxt.OpT, B: pxt.OpT) -> pxt.OpT:
 241    r"""
 242    `Column-wise Khatri-Rao product
diff --git a/_modules/pyxu/operator/linop/pad.html b/_modules/pyxu/operator/linop/pad.html
index bf36f12c..21798428 100644
--- a/_modules/pyxu/operator/linop/pad.html
+++ b/_modules/pyxu/operator/linop/pad.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -467,7 +467,7 @@

    Source code for pyxu.operator.linop.pad

      14
  15
 
    
-[docs]
+[docs]
  16class Pad(pxa.LinOp):
  17    r"""
  18    Multi-dimensional padding operator.
@@ -592,7 +592,7 @@ 
    Source code for pyxu.operator.linop.pad
     137    ModeSpec = typ.Union[str, cabc.Sequence[str]]
 138
 
    
-[docs]
+[docs]
 139    def __init__(
 140        self,
 141        arg_shape: pxt.NDArrayShape,
diff --git a/_modules/pyxu/operator/linop/reduce.html b/_modules/pyxu/operator/linop/reduce.html
index e2e1ae01..21278343 100644
--- a/_modules/pyxu/operator/linop/reduce.html
+++ b/_modules/pyxu/operator/linop/reduce.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -467,7 +467,7 @@

    Source code for pyxu.operator.linop.reduce

      14
  15
 
    
-[docs]
+[docs]
  16def Sum(
  17    arg_shape: pxt.NDArrayShape,
  18    axis: pxt.NDArrayAxis = None,
diff --git a/_modules/pyxu/operator/linop/select.html b/_modules/pyxu/operator/linop/select.html
index a4a4bb04..89920bd1 100644
--- a/_modules/pyxu/operator/linop/select.html
+++ b/_modules/pyxu/operator/linop/select.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -469,7 +469,7 @@

    Source code for pyxu.operator.linop.select

      16
  17
 
    
-[docs]
+[docs]
  18class SubSample(pxa.LinOp):
  19    r"""
  20    Multi-dimensional sub-sampling operator.
@@ -534,7 +534,7 @@ 
    Source code for pyxu.operator.linop.select
      79    ]
  80
 
    
-[docs]
+[docs]
  81    def __init__(
  82        self,
  83        arg_shape: pxt.NDArrayShape,
@@ -575,7 +575,7 @@ 
    Source code for pyxu.operator.linop.select
     
 118
 
    
-[docs]
+[docs]
 119    @pxrt.enforce_precision(i="arr")
 120    def apply(self, arr: pxt.NDArray) -> pxt.NDArray:
 121        """
@@ -602,7 +602,7 @@ 
    Source code for pyxu.operator.linop.select
     
 142
 
    
-[docs]
+[docs]
 143    @pxrt.enforce_precision(i="arr")
 144    def adjoint(self, arr: pxt.NDArray) -> pxt.NDArray:
 145        """
@@ -668,7 +668,7 @@ 
    Source code for pyxu.operator.linop.select
     203
 204
 
    
-[docs]
+[docs]
 205def Trim(
 206    arg_shape: pxt.NDArrayShape,
 207    trim_width: SubSample.TrimSpec,
diff --git a/_modules/pyxu/operator/linop/stencil/_stencil.html b/_modules/pyxu/operator/linop/stencil/_stencil.html
index 63c6fcec..ff51ac14 100644
--- a/_modules/pyxu/operator/linop/stencil/_stencil.html
+++ b/_modules/pyxu/operator/linop/stencil/_stencil.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
  • @@ -378,7 +378,7 @@ - +
  • @@ -513,7 +513,7 @@

    Source code for pyxu.operator.linop.stencil._stencil

    60 61
    -[docs] +[docs] 62class _Stencil: 63 """ 64 Multi-dimensional JIT-compiled stencil. (Low-level function.) @@ -552,7 +552,7 @@

    Source code for pyxu.operator.linop.stencil._stencil

    97 IndexSpec = cabc.Sequence[pxt.Integer] 98
    -[docs] +[docs] 99 @staticmethod 100 def init( 101 kernel: pxt.NDArray, @@ -595,7 +595,7 @@

    Source code for pyxu.operator.linop.stencil._stencil

    138
    -[docs] +[docs] 139 def apply( 140 self, 141 arr: pxt.NDArray, diff --git a/_modules/pyxu/operator/linop/stencil/stencil.html b/_modules/pyxu/operator/linop/stencil/stencil.html index 1ec844a8..19a9d3b0 100644 --- a/_modules/pyxu/operator/linop/stencil/stencil.html +++ b/_modules/pyxu/operator/linop/stencil/stencil.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
  • @@ -378,7 +378,7 @@ - +
  • @@ -477,7 +477,7 @@

    Source code for pyxu.operator.linop.stencil.stencil

    24 25
    -[docs] +[docs] 26class Stencil(pxa.SquareOp): 27 r""" 28 Multi-dimensional JIT-compiled stencil. @@ -801,7 +801,7 @@

    Source code for pyxu.operator.linop.stencil.stencil

    346 ] 347
    -[docs] +[docs] 348 def __init__( 349 self, 350 arg_shape: pxt.NDArrayShape, @@ -909,7 +909,7 @@

    Source code for pyxu.operator.linop.stencil.stencil

    451 return out 452
    -[docs] +[docs] 453 def configure_dispatcher(self, **kwargs): 454 """ 455 (Only applies if `kernel` is a CuPy array.) @@ -1206,7 +1206,7 @@

    Source code for pyxu.operator.linop.stencil.stencil

    745 return r_idx 746
    -[docs] +[docs] 747 def visualize(self) -> str: 748 r""" 749 Show the :math:`D`-dimensional stencil kernel. @@ -1247,7 +1247,7 @@

    Source code for pyxu.operator.linop.stencil.stencil

    782 783
    -[docs] +[docs] 784class Convolve(Stencil): 785 r""" 786 Multi-dimensional JIT-compiled convolution. diff --git a/_modules/pyxu/operator/map/base.html b/_modules/pyxu/operator/map/base.html index bf4f3d9d..1cf3c0f4 100644 --- a/_modules/pyxu/operator/map/base.html +++ b/_modules/pyxu/operator/map/base.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -199,7 +199,7 @@
    -
    v1.0.x
    +
    Pyxu v1.0.1
      @@ -236,7 +236,7 @@ - +
    • @@ -341,7 +341,7 @@
      -
      v1.0.x
      +
      Pyxu v1.0.1
        @@ -378,7 +378,7 @@ - +
      • @@ -465,7 +465,7 @@

        Source code for pyxu.operator.map.base

         12
 13
 
        
-[docs]
+[docs]
 14def ConstantValued(
 15    shape: pxt.OpShape,
 16    cst: pxt.Real,
@@ -578,15 +578,11 @@ 
        Source code for pyxu.operator.map.base
               
         
        
   
        
-    Created using Sphinx 7.2.5.
+     Created with Sphinx 7.2.5, with some help from  ChatGPT (GPT 4).
     
        
   
        
 
        
       
-        
        
-  Built with the PyData Sphinx Theme 0.13.3.
-
        
-      
     
        
   
   
diff --git a/_modules/pyxu/operator/map/ufunc.html b/_modules/pyxu/operator/map/ufunc.html
index 8755f342..06a1f4a9 100644
--- a/_modules/pyxu/operator/map/ufunc.html
+++ b/_modules/pyxu/operator/map/ufunc.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
      • @@ -378,7 +378,7 @@ - +
      • @@ -534,7 +534,7 @@

        Source code for pyxu.operator.map.ufunc

           81
   82
 
        
-[docs]
+[docs]
   83def sin(op: pxt.OpT) -> pxt.OpT:
   84    r"""
   85    Trigonometric sine, element-wise.
@@ -574,7 +574,7 @@ 
        Source code for pyxu.operator.map.ufunc
          118
  119
 
        
-[docs]
+[docs]
  120def cos(op: pxt.OpT) -> pxt.OpT:
  121    r"""
  122    Trigonometric cosine, element-wise.
@@ -616,7 +616,7 @@ 
        Source code for pyxu.operator.map.ufunc
          157
  158
 
        
-[docs]
+[docs]
  159def tan(op: pxt.OpT) -> pxt.OpT:
  160    r"""
  161    Trigonometric tangent, element-wise.
@@ -659,7 +659,7 @@ 
        Source code for pyxu.operator.map.ufunc
          197
  198
 
        
-[docs]
+[docs]
  199def arcsin(op: pxt.OpT) -> pxt.OpT:
  200    r"""
  201    Inverse sine, element-wise.
@@ -700,7 +700,7 @@ 
        Source code for pyxu.operator.map.ufunc
          235
  236
 
        
-[docs]
+[docs]
  237def arccos(op: pxt.OpT) -> pxt.OpT:
  238    r"""
  239    Inverse cosine, element-wise.
@@ -743,7 +743,7 @@ 
        Source code for pyxu.operator.map.ufunc
          275
  276
 
        
-[docs]
+[docs]
  277def arctan(op: pxt.OpT) -> pxt.OpT:
  278    r"""
  279    Inverse tangent, element-wise.
@@ -783,7 +783,7 @@ 
        Source code for pyxu.operator.map.ufunc
          312
  313
 
        
-[docs]
+[docs]
  314def sinh(op: pxt.OpT) -> pxt.OpT:
  315    r"""
  316    Hyperbolic sine, element-wise.
@@ -822,7 +822,7 @@ 
        Source code for pyxu.operator.map.ufunc
          348
  349
 
        
-[docs]
+[docs]
  350def cosh(op: pxt.OpT) -> pxt.OpT:
  351    r"""
  352    Hyperbolic cosine, element-wise.
@@ -867,7 +867,7 @@ 
        Source code for pyxu.operator.map.ufunc
          390
  391
 
        
-[docs]
+[docs]
  392def tanh(op: pxt.OpT) -> pxt.OpT:
  393    r"""
  394    Hyperbolic tangent, element-wise.
@@ -913,7 +913,7 @@ 
        Source code for pyxu.operator.map.ufunc
          433
  434
 
        
-[docs]
+[docs]
  435def arcsinh(op: pxt.OpT) -> pxt.OpT:
  436    r"""
  437    Inverse hyperbolic sine, element-wise.
@@ -955,7 +955,7 @@ 
        Source code for pyxu.operator.map.ufunc
          472
  473
 
        
-[docs]
+[docs]
  474def arccosh(op: pxt.OpT) -> pxt.OpT:
  475    r"""
  476    Inverse hyperbolic cosine, element-wise.
@@ -996,7 +996,7 @@ 
        Source code for pyxu.operator.map.ufunc
          510
  511
 
        
-[docs]
+[docs]
  512def arctanh(op: pxt.OpT) -> pxt.OpT:
  513    r"""
  514    Inverse hyperbolic tangent, element-wise.
@@ -1044,7 +1044,7 @@ 
        Source code for pyxu.operator.map.ufunc
          555
  556
 
        
-[docs]
+[docs]
  557def exp(op: pxt.OpT, base: pxt.Real = None) -> pxt.OpT:
  558    r"""
  559    Exponential, element-wise. (Default: base-E exponential.)
@@ -1089,7 +1089,7 @@ 
        Source code for pyxu.operator.map.ufunc
          597
  598
 
        
-[docs]
+[docs]
  599def log(op: pxt.OpT, base: pxt.Real = None) -> pxt.OpT:
  600    r"""
  601    Logarithm, element-wise. (Default: base-E logarithm.)
@@ -1134,7 +1134,7 @@ 
        Source code for pyxu.operator.map.ufunc
          639
  640
 
        
-[docs]
+[docs]
  641def clip(op: pxt.OpT, a_min: pxt.Real = None, a_max: pxt.Real = None):
  642    r"""
  643    Clip (limit) values in an array, element-wise.
@@ -1174,7 +1174,7 @@ 
        Source code for pyxu.operator.map.ufunc
          676
  677
 
        
-[docs]
+[docs]
  678def sqrt(op: pxt.OpT) -> pxt.OpT:
  679    r"""
  680    Non-negative square-root, element-wise.
@@ -1215,7 +1215,7 @@ 
        Source code for pyxu.operator.map.ufunc
          714
  715
 
        
-[docs]
+[docs]
  716def cbrt(op: pxt.OpT) -> pxt.OpT:
  717    r"""
  718    Cube-root, element-wise.
@@ -1256,7 +1256,7 @@ 
        Source code for pyxu.operator.map.ufunc
          752
  753
 
        
-[docs]
+[docs]
  754def square(op: pxt.OpT) -> pxt.OpT:
  755    r"""
  756    Square, element-wise.
@@ -1289,7 +1289,7 @@ 
        Source code for pyxu.operator.map.ufunc
          782
  783
 
        
-[docs]
+[docs]
  784def abs(op: pxt.OpT) -> pxt.OpT:
  785    r"""
  786    Absolute value, element-wise.
@@ -1315,7 +1315,7 @@ 
        Source code for pyxu.operator.map.ufunc
          805
  806
 
        
-[docs]
+[docs]
  807def sign(op: pxt.OpT) -> pxt.OpT:
  808    r"""
  809    Number sign indicator, element-wise.
@@ -1354,7 +1354,7 @@ 
        Source code for pyxu.operator.map.ufunc
          841
  842
 
        
-[docs]
+[docs]
  843def gaussian(op: pxt.OpT) -> pxt.OpT:
  844    r"""
  845    Gaussian, element-wise.
@@ -1399,7 +1399,7 @@ 
        Source code for pyxu.operator.map.ufunc
          883
  884
 
        
-[docs]
+[docs]
  885def sigmoid(op: pxt.OpT) -> pxt.OpT:
  886    r"""
  887    Sigmoid, element-wise.
@@ -1439,7 +1439,7 @@ 
        Source code for pyxu.operator.map.ufunc
          920
  921
 
        
-[docs]
+[docs]
  922def softplus(op: pxt.OpT) -> pxt.OpT:
  923    r"""
  924    Softplus operator.
@@ -1474,7 +1474,7 @@ 
        Source code for pyxu.operator.map.ufunc
          952
  953
 
        
-[docs]
+[docs]
  954def leakyrelu(op: pxt.OpT, alpha: pxt.Real) -> pxt.OpT:
  955    r"""
  956    Leaky rectified linear unit, element-wise.
@@ -1494,7 +1494,7 @@ 
        Source code for pyxu.operator.map.ufunc
          969
  970
 
        
-[docs]
+[docs]
  971def relu(op: pxt.OpT) -> pxt.OpT:
  972    r"""
  973    Rectified linear unit, element-wise.
@@ -1534,7 +1534,7 @@ 
        Source code for pyxu.operator.map.ufunc
         1006
 1007
 
        
-[docs]
+[docs]
 1008def silu(op: pxt.OpT) -> pxt.OpT:
 1009    r"""
 1010    Sigmoid linear unit, element-wise.
@@ -1578,7 +1578,7 @@ 
        Source code for pyxu.operator.map.ufunc
         1047
 1048
 
        
-[docs]
+[docs]
 1049def softmax(op: pxt.OpT) -> pxt.OpT:
 1050    r"""
 1051    Softmax operator.
diff --git a/_modules/pyxu/opt/solver/adam.html b/_modules/pyxu/opt/solver/adam.html
index cbfa40cd..157de997 100644
--- a/_modules/pyxu/opt/solver/adam.html
+++ b/_modules/pyxu/opt/solver/adam.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -236,7 +236,7 @@
           
           
           
-          
+
      • @@ -378,7 +378,7 @@ - +
      • diff --git a/_modules/pyxu/opt/solver/cg.html b/_modules/pyxu/opt/solver/cg.html index 9e2625b4..32e2b633 100644 --- a/_modules/pyxu/opt/solver/cg.html +++ b/_modules/pyxu/opt/solver/cg.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
      • @@ -378,7 +378,7 @@ - +
      • diff --git a/_modules/pyxu/opt/solver/nlcg.html b/_modules/pyxu/opt/solver/nlcg.html index 30f9d432..d78ae824 100644 --- a/_modules/pyxu/opt/solver/nlcg.html +++ b/_modules/pyxu/opt/solver/nlcg.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
      • @@ -378,7 +378,7 @@ - +
      • diff --git a/_modules/pyxu/opt/solver/pds.html b/_modules/pyxu/opt/solver/pds.html index 68f75492..85d5a70a 100644 --- a/_modules/pyxu/opt/solver/pds.html +++ b/_modules/pyxu/opt/solver/pds.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + diff --git a/_modules/pyxu/opt/solver/pgd.html b/_modules/pyxu/opt/solver/pgd.html index e3b5ebf8..9ce62c60 100644 --- a/_modules/pyxu/opt/solver/pgd.html +++ b/_modules/pyxu/opt/solver/pgd.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
      • @@ -378,7 +378,7 @@ - +
      • diff --git a/_modules/pyxu/opt/solver/prox_adam.html b/_modules/pyxu/opt/solver/prox_adam.html deleted file mode 100644 index 208a4a98..00000000 --- a/_modules/pyxu/opt/solver/prox_adam.html +++ /dev/null @@ -1,1018 +0,0 @@ - - - - - - - - - - pyxu.opt.solver.prox_adam — Pyxu Documentation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        -
        -
        -
        - - - Ctrl+K -
        -
        - - - -
        -
        - -
        - - - -
        - - -
        - -
        - -
        - - - -
        - -
        v1.0.x
        - -
        - -
        - -
        - - -
        -
        - - - - -
        - -
        - - -
        -
        - -
        -
        - -
        - -
        - - - - -
        - -
        - - -
        -
        - - - - - -
        - -

        Source code for pyxu.opt.solver.prox_adam

        -  1import math
-  2import warnings
-  3
-  4import pyxu.abc as pxa
-  5import pyxu.info.ptype as pxt
-  6import pyxu.info.warning as pxw
-  7import pyxu.operator.func as pxf
-  8import pyxu.operator.linop as pxl
-  9import pyxu.opt.solver as pxs
- 10import pyxu.runtime as pxrt
- 11import pyxu.util as pxu
- 12
- 13__all__ = [
- 14    "ProxAdam",
- 15]
- 16
- 17
-
        
-[docs]
- 18class ProxAdam(pxa.Solver):
- 19    r"""
- 20    Proximal Adam solver [ProxAdam]_.
- 21
- 22    ProxAdam minimizes
- 23
- 24    .. math::
- 25
- 26       {\min_{\mathbf{x}\in\mathbb{R}^N} \;\mathcal{F}(\mathbf{x})\;\;+\;\;\mathcal{G}(\mathbf{x})},
- 27
- 28    where:
- 29
- 30    * :math:`\mathcal{F}:\mathbb{R}^N\rightarrow \mathbb{R}` is *convex* and *differentiable*, with
- 31      :math:`\beta`-*Lipschitz continuous* gradient, for some :math:`\beta\in[0,+\infty[`.
- 32    * :math:`\mathcal{G}:\mathbb{R}^N\rightarrow \mathbb{R}\cup\{+\infty\}` is a *proper*, *lower
- 33      semicontinuous* and *convex function* with a *simple proximal operator*.
- 34
- 35    ProxAdam is a suitable alternative to Proximal Gradient Descent
- 36    (:py:class:`~pyxu.opt.solver.pgd.PGD`) when:
- 37
- 38    * computing :math:`\beta` to optimally choose the step size is infeasible, and
- 39    * line-search methods to estimate step sizes are too expensive.
- 40
- 41    Compared to PGD, ProxAdam:
- 42
- 43    * auto-tunes gradient updates based on stochastic estimates of
- 44      :math:`\phi_{t} = \mathbb{E}[\nabla\mathcal{F}]` and :math:`\psi_{t} =
- 45      \mathbb{E}[\nabla\mathcal{F}^{2}]` respectively;
- 46    * uses a modified proximity operator at each iteration to update coordinates at varying scales:
- 47
- 48      .. math::
- 49
- 50         \text{prox}_{\alpha\mathcal{G}}(\mathbf{x}_{t})
- 51         =
- 52         \min_{\mathbf{z}\in\mathbb{R}^N} \;\mathcal{G}(\mathbf{z})\;\;+\;\;\frac{1}{2\alpha}||\mathbf{z}-\mathbf{x}_t||_H^2,
- 53
- 54      where :math:`H=\text{diag}(\psi_t)`.
- 55      The modified proximity operator is computed by solving a PGD sub-problem.
- 56
- 57    ProxAdam has many named variants for particular choices of :math:`\phi` and :math:`\psi`:
- 58
- 59    * Adam:
- 60
- 61      .. math::
- 62
- 63         \phi_t
- 64         =
- 65         \frac{
- 66           \mathbf{m}_t
- 67         }{
- 68           1-\beta_1^t
- 69         }
- 70         \qquad
- 71         \psi_t
- 72         =
- 73         \sqrt{
- 74           \frac{
- 75             \mathbf{v}_t
- 76           }{
- 77             1-\beta_2^t
- 78           }
- 79         } + \epsilon,
- 80
- 81    * AMSGrad:
- 82
- 83      .. math::
- 84
- 85         \phi_t = \mathbf{m}_t
- 86         \qquad
- 87         \psi_t = \sqrt{\hat{\mathbf{v}}_t},
- 88
- 89    * PAdam:
- 90
- 91      .. math::
- 92
- 93         \phi_t = \mathbf{m}_t
- 94         \qquad
- 95         \psi_t = \hat{\mathbf{v}}_t^p,
- 96
- 97    where in all cases:
- 98
- 99    .. math::
-100
-101       \mathbf{m}_t
-102       =
-103       \beta_1\mathbf{m}_{t-1}
-104       +
-105       (1-\beta_1)\mathbf{g}_t \\
-106       \mathbf{v}_t
-107       =
-108       \beta_2\mathbf{v}_{t-1}
-109       +
-110       (1-\beta_2)\mathbf{g}_t^2\\
-111       \hat{\mathbf{v}}_t
-112       =
-113       \max(\hat{\mathbf{v}}_{t-1}, \mathbf{v}_t),
-114
-115    with :math:`\mathbf{m}_0 = \mathbf{v}_0 = \mathbf{0}`.
-116
-117    Remarks
-118    -------
-119    * The algorithm is still valid if :math:`\mathcal{G}` is zero.
-120
-121    * The convergence is guaranteed for step sizes :math:`\alpha\leq 2/\beta`.
-122
-123    * The default stopping criterion is the relative norm change of the primal variable.
-124      By default, the algorithm stops when the norm of the difference between two consecutive iterates
-125      :math:`\{\mathbf{x}_n\}_{n\in\mathbb{N}}` is smaller than 1e-4.
-126      Different stopping criteria can be used.
-127      It is recommended to change the stopping criterion when using the PAdam and AMSGrad variants to
-128      avoid premature stops.
-129      By default, the same stopping criterion is used for the proximal sub-problem.
-130
-131    Parameters (``__init__()``)
-132    ---------------------------
-133    * **f** (:py:class:`~pyxu.abc.operator.DiffFunc`)
-134      --
-135      Differentiable function :math:`\mathcal{F}`.
-136    * **g** (:py:class:`~pyxu.abc.operator.ProxFunc`, :py:obj:`None`)
-137      --
-138      Proximable function :math:`\mathcal{G}`.
-139    * **\*\*kwargs** (:py:class:`~collections.abc.Mapping`)
-140      --
-141      Other keyword parameters passed on to :py:meth:`pyxu.abc.solver.Solver.__init__`.
-142
-143    Parameters (``fit()``)
-144    ----------------------
-145    * **x0** (:py:attr:`~pyxu.info.ptype.NDArray`)
-146      --
-147      (..., N) initial point(s).
-148    * **variant** ("adam", "amsgrad", "padam")
-149      --
-150      Name of the ProxAdam variant to use.
-151      Defaults to "adam".
-152    * **a** (:py:attr:`~pyxu.info.ptype.Real`, :py:obj:`None`)
-153      --
-154      Max normalized gradient step size.
-155      Defaults to :math:`1 / \beta` if unspecified.
-156    * **b1** (:py:attr:`~pyxu.info.ptype.Real`)
-157      --
-158      1st-order gradient exponential decay :math:`\beta_{1} \in [0, 1)`.
-159    * **b2** (:py:attr:`~pyxu.info.ptype.Real`)
-160      --
-161      2nd-order gradient exponential decay :math:`\beta_{2} \in [0, 1)`.
-162    * **m0** (:py:attr:`~pyxu.info.ptype.NDArray`, :py:obj:`None`)
-163      --
-164      (..., N) initial 1st-order gradient estimate corresponding to each initial point.
-165      Defaults to the null vector if unspecified.
-166    * **v0** (:py:attr:`~pyxu.info.ptype.NDArray`, :py:obj:`None`)
-167      --
-168      (..., N) initial 2nd-order gradient estimate corresponding to each initial point.
-169      Defaults to the null vector if unspecified.
-170    * **kwargs_sub** (:py:class:`~collections.abc.Mapping`, :py:obj:`None`)
-171      --
-172      Keyword parameters used to initialize :py:meth:`~pyxu.opt.solver.pgd.PGD`'s ``__init__()`` in
-173      sub-problems.
-174      This is an advanced option: use it with care.
-175    * **stop_crit_sub** (:py:class:`~pyxu.abc.solver.StoppingCriterion`, :py:obj:`None`)
-176      --
-177      Sub-problem stopping criterion.
-178      Default: use same stopping criterion as main problem.
-179    * **p** (:py:attr:`~pyxu.info.ptype.Real`)
-180      --
-181      PAdam power parameter :math:`p \in (0, 0.5]`.
-182      Must be specified for PAdam, unused otherwise.
-183    * **eps_adam** (:py:attr:`~pyxu.info.ptype.Real`)
-184      --
-185      Adam noise parameter :math:`\epsilon`.
-186      This term is used exclusively if `variant="adam"`.
-187      Defaults to 1e-6.
-188    * **eps_var** (:py:attr:`~pyxu.info.ptype.Real`)
-189      --
-190      Avoids division by zero if estimated gradient variance is too small.
-191      Defaults to 1e-6.
-192    * **\*\*kwargs** (:py:class:`~collections.abc.Mapping`)
-193      --
-194      Other keyword parameters passed on to :py:meth:`pyxu.abc.solver.Solver.fit`.
-195
-196    Note
-197    ----
-198    If provided, `m0` and `v0` must be broadcastable with `x0`.
-199
-200    Example
-201    -------
-202    Consider the following optimization problem:
-203
-204    .. math::
-205
-206       \min_{\mathbf{x}\in\mathbb{R}^N} \Vert{\mathbf{x}-\mathbf{1}}\Vert_2^2 + \Vert{\mathbf{x}-\mathbf{1}}\Vert_1
-207
-208    .. code-block:: python3
-209
-210       import numpy as np
-211
-212       from pyxu.operator.func import L1Norm, SquaredL2Norm
-213       from pyxu.opt.solver import ProxAdam
-214
-215       N = 3
-216       f = SquaredL2Norm(dim=N).asloss(1)
-217       g = L1Norm(dim=N).asloss(1)
-218
-219       prox_adam = ProxAdam(f, g)
-220       prox_adam.fit(
-221           x0=np.zeros((N,)),
-222           variant="padam",
-223           p=0.25,
-224       )
-225       x_opt = prox_adam.solution()
-226       np.allclose(x_opt, 1)  # True
-227    """
-228
-229    def __init__(
-230        self,
-231        f: pxa.DiffFunc,
-232        g: pxa.ProxFunc = None,
-233        **kwargs,
-234    ):
-235        kwargs.update(
-236            log_var=kwargs.get("log_var", ("x",)),
-237        )
-238        super().__init__(**kwargs)
-239
-240        self._f = f
-241        # If f is domain-agnostic and g is unspecified, cannot auto-infer NullFunc dimension.
-242        # Solution: delay initialization of g to m_init(), where x0's shape can be used.
-243        self._prox_required = g is not None
-244        self._g = g
-245
-246    @pxrt.enforce_precision(i=("x0", "a", "b1", "b2", "m0", "v0", "p", "eps_adam", "eps_var"))
-247    def m_init(  # default values from https://github.com/pmelchior/proxmin/blob/master/proxmin/algorithms.py
-248        self,
-249        x0: pxt.NDArray,
-250        variant: str = "adam",
-251        a: pxt.Real = None,
-252        b1: pxt.Real = 0.9,
-253        b2: pxt.Real = 0.999,
-254        m0: pxt.NDArray = None,
-255        v0: pxt.NDArray = None,
-256        kwargs_sub: dict = None,
-257        stop_crit_sub: pxa.solver.StoppingCriterion = None,
-258        p: pxt.Real = 0.5,
-259        eps_adam: pxt.Real = 1e-6,
-260        eps_var: pxt.Real = 1e-6,
-261    ):
-262        mst = self._mstate  # shorthand
-263        mst["x"] = x0
-264
-265        if self._g is None:
-266            self._g = pxf.NullFunc(dim=x0.shape[-1])
-267
-268        if a is None:
-269            mst["a"] = pxrt.coerce(1 / self._f.diff_lipschitz)
-270            if math.isinf(mst["a"]):
-271                # _f is constant-valued: a is a free parameter.
-272                mst["a"] = pxrt.coerce(1)
-273                msg = "\n".join(
-274                    [
-275                        rf"The gradient step size `a` is auto-set to {mst['a']}.",
-276                        r"Choosing a manually may lead to faster convergence.",
-277                    ]
-278                )
-279                warnings.warn(msg, pxw.AutoInferenceWarning)
-280        else:
-281            try:
-282                assert a > 0
-283                mst["a"] = a
-284            except Exception:
-285                raise ValueError(f"`a` must be positive, got {a}.")
-286
-287        mst["variant"] = self.__parse_variant(variant)
-288
-289        assert 0 < p <= 0.5, f"p: expected value in (0, 0.5], got {p}."
-290        mst["padam_p"] = p
-291
-292        assert eps_adam > 0, f"eps_adam: expected positive value, got {eps_adam}."
-293        mst["eps_adam"] = eps_adam
-294
-295        xp = pxu.get_array_module(x0)
-296
-297        if m0 is None:
-298            mst["mean"] = xp.zeros_like(x0)
-299        elif m0.shape == x0.shape:
-300            # No broadcasting involved
-301            mst["mean"] = m0
-302        else:
-303            x0, m0 = xp.broadcast_arrays(x0, m0)
-304            mst["mean"] = m0.copy()
-305
-306        if v0 is None:
-307            mst["variance"] = xp.zeros_like(x0)
-308        elif v0.shape == x0.shape:
-309            # No broadcasting involved
-310            mst["variance"] = v0
-311        else:
-312            x0, v0 = xp.broadcast_arrays(x0, v0)
-313            mst["variance"] = v0.copy()
-314        mst["variance_hat"] = mst["variance"]
-315
-316        if kwargs_sub is None:
-317            kwargs_sub = dict()
-318        mst["subproblem_init_kwargs"] = kwargs_sub
-319        if stop_crit_sub is None:
-320            stop_crit_sub = self.default_stop_crit()
-321        mst["subproblem_stop_crit"] = stop_crit_sub
-322
-323        assert 0 <= b1 < 1, f"b1: expected value in [0, 1), got {b1}."
-324        mst["b1"] = b1
-325
-326        assert 0 <= b2 < 1, f"b2: expected value in [0, 1), got {b2}."
-327        mst["b2"] = b2
-328
-329        assert eps_var > 0, f"eps_var: expected positive value, got {eps_var}."
-330        mst["eps_variance"] = eps_var
-331
-332    def m_step(self):
-333        mst = self._mstate  # shorthand
-334
-335        x, a = mst["x"], mst["a"]
-336        xp = pxu.get_array_module(x)
-337        gm = pxu.copy_if_unsafe(self._f.grad(x))
-338        gv = gm.copy()
-339
-340        ## Part 1: evaluate phi/psi ============================
-341        m, b1 = mst["mean"], mst["b1"]
-342        # In-place implementation of -----------------
-343        #   m = b1 * m + (1 - b1) * g
-344        m *= b1
-345        gm *= 1 - b1
-346        m += gm
-347        # --------------------------------------------
-348        mst["mean"] = m
-349
-350        v, b2 = mst["variance"], mst["b2"]
-351        # In-place implementation of -----------------
-352        #   v = b2 * v + (1 - b2) * (g ** 2)
-353        v *= b2
-354        gv **= 2
-355        gv *= 1 - b2
-356        v += gv
-357        # --------------------------------------------
-358        mst["variance"] = v.clip(mst["eps_variance"], None)  # avoid division-by-zero
-359        mst["variance_hat"] = xp.maximum(mst["variance_hat"], mst["variance"])
-360
-361        phi = self.__phi(t=self._astate["idx"])
-362        psi = self.__psi(t=self._astate["idx"])
-363        ## =====================================================
-364
-365        ## Part 2: take a step in the gradient's direction =====
-366        # In-place implementation of -----------------
-367        #   x = x - a * (phi / psi)
-368        phi /= psi
-369        phi *= a
-370        x -= phi
-371        ## =====================================================
-372
-373        ## Part 3: eval PGD sub-problems =======================
-374        if self._prox_required:
-375            # Assume N initial points were provided in fit().
-376            # We need to solve a PGD sub-problem for each of them.
-377            #
-378            # Option 1: solve one large PGD(f, g) sub-problem, with
-379            #    f = hstack(f1, ..., fN)
-380            #    g = hstack(g, ..., g)
-381            # Option 2: solve N small PGD(f, g) sub-problems, with
-382            #    f = fn
-383            #    g = g
-384            #
-385            # The former (1) is more convenient since all sub-problems are solved in parallel, but:
-386            # * convergence will be slower since diff-Lipschitz constant of hstack(f1, ..., fN) is
-387            #   larger than those of fn. (Moreover the diff-Lipschitz constants of the fn may be
-388            #   spread out.)
-389            # * in the event `stop_crit_sub` is provided, we cannot always intercept/adapt it to
-390            #   apply block-wise on `_mstate`.
-391            #
-392            # Each sub-problem in the latter (2) converges fast, but sub-problems may execute in
-393            # sequence depending on the array backend used.
-394            #
-395            # In light of the above, we opt for Option 2.
-396            *x_sh, N = x.shape
-397            x_sub = []  # sub-problem solutions
-398            scale = pxrt.coerce(0.5 / a)
-399            for _x, _psi in zip(x.reshape(-1, N), psi.reshape(-1, N)):
-400                gamma = pxrt.coerce(a / xp.max(_psi))
-401                h_half = pxl.DiagonalOp(xp.sqrt(_psi))
-402
-403                f1 = pxf.SquaredL2Norm(dim=N).asloss(h_half.apply(_x)) * h_half
-404                f = f1 * scale
-405
-406                kwargs = mst["subproblem_init_kwargs"].copy()
-407                kwargs.update(show_progress=False)
-408                slvr = pxs.PGD(f=f, g=self._g, **kwargs)
-409
-410                slvr.fit(
-411                    x0=_x,
-412                    tau=gamma,
-413                    stop_crit=mst["subproblem_stop_crit"],
-414                )
-415                x_sub.append(slvr.solution())
-416            x = xp.stack(x_sub, axis=0).reshape(*x_sh, N)  # (..., N) original shape
-417        ## =====================================================
-418
-419        mst["x"] = x
-420
-421    def default_stop_crit(self) -> pxa.StoppingCriterion:
-422        from pyxu.opt.stop import RelError
-423
-424        # Described in [ProxAdam]_ and used in their implementation:
-425        # https://github.com/pmelchior/proxmin/blob/master/proxmin/algorithms.py
-426        rel_error = RelError(
-427            eps=1e-4,
-428            var="x",
-429            f=None,
-430            norm=2,
-431            satisfy_all=True,
-432        )
-433        return rel_error
-434
-435    def objective_func(self) -> pxt.NDArray:
-436        func = lambda x: self._f.apply(x) + self._g.apply(x)
-437        y = func(self._mstate["x"])
-438        return y
-439
-440    def solution(self) -> pxt.NDArray:
-441        """
-442        Returns
-443        -------
-444        x: NDArray
-445            (..., N) solution.
-446        """
-447        data, _ = self.stats()
-448        return data.get("x")
-449
-450    def __phi(self, t: int):
-451        mst = self._mstate
-452        var = mst["variant"]
-453        if var == "adam":
-454            out = mst["mean"].copy()
-455            out /= 1 - (mst["b1"] ** t)
-456        elif var in ["amsgrad", "padam"]:
-457            out = mst["mean"].copy()  # to allow in-place updates outside __compute_phi()
-458        return out
-459
-460    def __psi(self, t: int):
-461        mst = self._mstate
-462        xp = pxu.get_array_module(mst["x"])
-463        var = mst["variant"]
-464        if var == "adam":
-465            out = xp.sqrt(mst["variance"])
-466            out /= xp.sqrt(1 - mst["b2"] ** t)
-467            out += mst["eps_adam"]
-468        elif var == "amsgrad":
-469            out = xp.sqrt(mst["variance_hat"])
-470        elif var == "padam":
-471            out = mst["variance_hat"] ** mst["padam_p"]
-472        return out
-473
-474    def __parse_variant(self, variant: str) -> str:
-475        supported_variants = {"adam", "amsgrad", "padam"}
-476        if (v := variant.lower().strip()) not in supported_variants:
-477            raise ValueError(f"Unsupported variant '{variant}'.")
-478        return v
        
-
-
        - -
        - - - -
        - -
        - -
        -
        -
        - -
        - -
        - -
        - - - -
        - -
        -
        - -
        - - -
        -
        - -
        - -
        -
        -
        - - - - - -
        -
        - -
        - -
        -

        - - © Copyright 2023, M. Simeoni, S. Kashani, J. Rué-Queralt & Pyxu Developers. -
        - -

        -
        - -
        -

        - Created using Sphinx 7.2.5. -
        -

        -
        - -

        - Built with the PyData Sphinx Theme 0.13.3. -

        - -
        - - -
        - -

        - Built with the PyData Sphinx Theme 0.13.3. -

        - -
        - -
        - -
        - - \ No newline at end of file diff --git a/_modules/pyxu/opt/stop.html b/_modules/pyxu/opt/stop.html index fd171b25..95aab75f 100644 --- a/_modules/pyxu/opt/stop.html +++ b/_modules/pyxu/opt/stop.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + diff --git a/_modules/pyxu/runtime/_runtime.html b/_modules/pyxu/runtime/_runtime.html index b993ecf4..db14b792 100644 --- a/_modules/pyxu/runtime/_runtime.html +++ b/_modules/pyxu/runtime/_runtime.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
      • @@ -378,7 +378,7 @@ - +
      • diff --git a/_modules/pyxu/util/array_module.html b/_modules/pyxu/util/array_module.html index 9f27061e..40108d46 100644 --- a/_modules/pyxu/util/array_module.html +++ b/_modules/pyxu/util/array_module.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -454,124 +454,197 @@

        Source code for pyxu.util.array_module

           1import collections.abc as cabc
   2import functools
   3
-  4import pyxu.info.deps as pxd
-  5import pyxu.info.ptype as pxt
-  6import pyxu.util.misc as pxm
-  7
-  8__all__ = [
-  9    "get_array_module",
- 10    "redirect",
- 11]
- 12
- 13
+  4import dask
+  5
+  6import pyxu.info.deps as pxd
+  7import pyxu.info.ptype as pxt
+  8import pyxu.util.misc as pxm
+  9
+ 10__all__ = [
+ 11    "compute",
+ 12    "get_array_module",
+ 13    "redirect",
+ 14    "to_NUMPY",
+ 15]
+ 16
+ 17
 
        
 [docs]
- 14def get_array_module(x, fallback: pxt.ArrayModule = None) -> pxt.ArrayModule:
- 15    """
- 16    Get the array namespace corresponding to a given object.
- 17
- 18    Parameters
- 19    ----------
- 20    x: object
- 21        Any object compatible with the interface of NumPy arrays.
- 22    fallback: ArrayModule
- 23        Fallback module if `x` is not a NumPy-like array.  Default behaviour: raise error if fallback used.
- 24
- 25    Returns
- 26    -------
- 27    namespace: ArrayModule
- 28        The namespace to use to manipulate `x`, or `fallback` if provided.
- 29    """
- 30
- 31    def infer_api(y):
- 32        try:
- 33            return pxd.NDArrayInfo.from_obj(y).module()
- 34        except ValueError:
- 35            return None
- 36
- 37    if (xp := infer_api(x)) is not None:
- 38        return xp
- 39    elif fallback is not None:
- 40        return fallback
- 41    else:
- 42        raise ValueError(f"Could not infer array module for {type(x)}.")
        
-
- 43
- 44
+ 18def get_array_module(x, fallback: pxt.ArrayModule = None) -> pxt.ArrayModule:
+ 19    """
+ 20    Get the array namespace corresponding to a given object.
+ 21
+ 22    Parameters
+ 23    ----------
+ 24    x: object
+ 25        Any object compatible with the interface of NumPy arrays.
+ 26    fallback: ArrayModule
+ 27        Fallback module if `x` is not a NumPy-like array.  Default behaviour: raise error if fallback used.
+ 28
+ 29    Returns
+ 30    -------
+ 31    namespace: ArrayModule
+ 32        The namespace to use to manipulate `x`, or `fallback` if provided.
+ 33    """
+ 34
+ 35    def infer_api(y):
+ 36        try:
+ 37            return pxd.NDArrayInfo.from_obj(y).module()
+ 38        except ValueError:
+ 39            return None
+ 40
+ 41    if (xp := infer_api(x)) is not None:
+ 42        return xp
+ 43    elif fallback is not None:
+ 44        return fallback
+ 45    else:
+ 46        raise ValueError(f"Could not infer array module for {type(x)}.")
        + + 47 + 48
        [docs] - 45def redirect( - 46 i: pxt.VarName, - 47 **kwargs: cabc.Mapping[str, cabc.Callable], - 48) -> cabc.Callable: - 49 """ - 50 Change codepath for supplied array backends. - 51 - 52 Some functions/methods cannot be written in module-agnostic fashion. The action of this decorator is summarized - 53 below: - 54 - 55 * Analyze an array-valued parameter (`x`) of the wrapped function/method (`f`). - 56 * If `x` lies in one of the supplied array namespaces: re-route execution to the specified function. - 57 * If `x` lies in none of the supplied array namespaces: execute `f`. + 49def redirect( + 50 i: pxt.VarName, + 51 **kwargs: cabc.Mapping[str, cabc.Callable], + 52) -> cabc.Callable: + 53 """ + 54 Change codepath for supplied array backends. + 55 + 56 Some functions/methods cannot be written in module-agnostic fashion. The action of this decorator is summarized + 57 below: 58 - 59 Parameters - 60 ---------- - 61 i: VarName - 62 name of the array-like variable in `f` to base dispatch on. - 63 kwargs: ~collections.abc.Mapping - 64 - 65 * key[:py:class:`str`]: array backend short-name as defined in :py:class:`~pyxu.info.deps.NDArrayInfo`. - 66 * value[:py:class:`collections.abc.Callable`]: function/method to dispatch to. - 67 - 68 Notes - 69 ----- - 70 Auto-dispatch via :py:func:`redirect` assumes the dispatcher/dispatchee have the same parameterization, i.e.: + 59 * Analyze an array-valued parameter (`x`) of the wrapped function/method (`f`). + 60 * If `x` lies in one of the supplied array namespaces: re-route execution to the specified function. + 61 * If `x` lies in none of the supplied array namespaces: execute `f`. + 62 + 63 Parameters + 64 ---------- + 65 i: VarName + 66 name of the array-like variable in `f` to base dispatch on. + 67 kwargs: ~collections.abc.Mapping + 68 + 69 * key[:py:class:`str`]: array backend short-name as defined in :py:class:`~pyxu.info.deps.NDArrayInfo`. + 70 * value[:py:class:`collections.abc.Callable`]: function/method to dispatch to. 71 - 72 * if `f` is a function -> dispatch possible to another callable with identical signature (i.e., function or - 73 staticmethod) - 74 * if `f` is a staticmethod -> dispatch possible to another callable with identical signature (i.e., function or - 75 staticmethod) - 76 * if `f` is an instance-method -> dispatch to another instance-method of the class with identical signature. - 77 - 78 Example - 79 ------- - 80 .. code-block:: python3 + 72 Notes + 73 ----- + 74 Auto-dispatch via :py:func:`redirect` assumes the dispatcher/dispatchee have the same parameterization, i.e.: + 75 + 76 * if `f` is a function -> dispatch possible to another callable with identical signature (i.e., function or + 77 staticmethod) + 78 * if `f` is a staticmethod -> dispatch possible to another callable with identical signature (i.e., function or + 79 staticmethod) + 80 * if `f` is an instance-method -> dispatch to another instance-method of the class with identical signature. 81 - 82 def f(x, y): return "f" - 83 - 84 @redirect('x', NUMPY=f) # if 'x' is of type NDArrayInfo.NUMPY, i.e. has - 85 def g(x, y): return "g" # short-name 'NUMPY' -> reroute execution to `f` - 86 - 87 x1 = np.arange(5) - 88 x2 = da.array(x1) - 89 y = 1 - 90 g(x1, y), g(x2, y) # 'f', 'g' - 91 """ - 92 - 93 def decorator(func: cabc.Callable) -> cabc.Callable: - 94 @functools.wraps(func) - 95 def wrapper(*ARGS, **KWARGS): - 96 try: - 97 func_args = pxm.parse_params(func, *ARGS, **KWARGS) - 98 except Exception as e: - 99 error_msg = f"Could not parameterize {func}()." -100 raise ValueError(error_msg) from e -101 -102 if i not in func_args: -103 error_msg = f"Parameter[{i}] not part of {func.__qualname__}() parameter list." -104 raise ValueError(error_msg) + 82 Example + 83 ------- + 84 .. code-block:: python3 + 85 + 86 def f(x, y): return "f" + 87 + 88 @redirect('x', NUMPY=f) # if 'x' is of type NDArrayInfo.NUMPY, i.e. has + 89 def g(x, y): return "g" # short-name 'NUMPY' -> reroute execution to `f` + 90 + 91 x1 = np.arange(5) + 92 x2 = da.array(x1) + 93 y = 1 + 94 g(x1, y), g(x2, y) # 'f', 'g' + 95 """ + 96 + 97 def decorator(func: cabc.Callable) -> cabc.Callable: + 98 @functools.wraps(func) + 99 def wrapper(*ARGS, **KWARGS): +100 try: +101 func_args = pxm.parse_params(func, *ARGS, **KWARGS) +102 except Exception as e: +103 error_msg = f"Could not parameterize {func}()." +104 raise ValueError(error_msg) from e 105 -106 ndi = pxd.NDArrayInfo.from_obj(func_args[i]) -107 if (alt_func := kwargs.get(ndi.name)) is not None: -108 out = alt_func(**func_args) -109 else: -110 out = func(**func_args) -111 -112 return out -113 -114 return wrapper +106 if i not in func_args: +107 error_msg = f"Parameter[{i}] not part of {func.__qualname__}() parameter list." +108 raise ValueError(error_msg) +109 +110 ndi = pxd.NDArrayInfo.from_obj(func_args[i]) +111 if (alt_func := kwargs.get(ndi.name)) is not None: +112 out = alt_func(**func_args) +113 else: +114 out = func(**func_args) 115 -116 return decorator
        +116 return out +117 +118 return wrapper +119 +120 return decorator
      + +121 +122 +
      +[docs] +123def compute(*args, mode: str = "compute", **kwargs): +124 r""" +125 Force computation of Dask collections. +126 +127 Parameters +128 ---------- +129 \*args: object, list +130 Any number of objects. If it is a dask object, it is evaluated and the result is returned. Non-dask arguments +131 are passed through unchanged. Python collections are traversed to find/evaluate dask objects within. (Use +132 `traverse` =False to disable this behavior.) +133 mode: str +134 Dask evaluation strategy: compute or persist. +135 \*\*kwargs: dict +136 Extra keyword parameters forwarded to :py:func:`dask.compute` or :py:func:`dask.persist`. +137 +138 Returns +139 ------- +140 \*cargs: object, list +141 Evaluated objects. Non-dask arguments are passed through unchanged. +142 """ +143 try: +144 func = dict(compute=dask.compute, persist=dask.persist)[mode.lower()] +145 except Exception: +146 raise ValueError(f"mode: expected compute/persist, got {mode}.") +147 +148 cargs = func(*args, **kwargs) +149 if len(args) == 1: +150 cargs = cargs[0] +151 return cargs
      + +152 +153 +
      +[docs] +154def to_NUMPY(x: pxt.NDArray) -> pxt.NDArray: +155 """ +156 Convert an array from a specific backend to NUMPY. +157 +158 Parameters +159 ---------- +160 x: NDArray +161 Array to be converted. +162 +163 Returns +164 ------- +165 y: NDArray +166 Array with NumPy backend. +167 +168 Notes +169 ----- +170 This function is a no-op if the array is already a NumPy array. +171 """ +172 N = pxd.NDArrayInfo +173 ndi = N.from_obj(x) +174 if ndi == N.NUMPY: +175 y = x +176 elif ndi == N.DASK: +177 y = compute(x) +178 elif ndi == N.CUPY: +179 y = x.get() +180 else: +181 msg = f"Dev-action required: define behaviour for {ndi}." +182 raise ValueError(msg) +183 return y
      diff --git a/_modules/pyxu/util/complex.html b/_modules/pyxu/util/complex.html index da7bee8c..776e4064 100644 --- a/_modules/pyxu/util/complex.html +++ b/_modules/pyxu/util/complex.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -236,7 +236,7 @@ - +
    • @@ -378,7 +378,7 @@ - +
    • @@ -464,7 +464,7 @@

      Source code for pyxu.util.complex

        11
  12
 
      
-[docs]
+[docs]
  13def view_as_complex(x: pxt.NDArray) -> pxt.NDArray:
  14    r"""
  15    View real-valued array as its complex-valued bijection.  (Inverse of :py:func:`~pyxu.util.view_as_real`.)
@@ -521,7 +521,7 @@ 
      Source code for pyxu.util.complex
        65
  66
 
      
-[docs]
+[docs]
  67def view_as_real(x: pxt.NDArray) -> pxt.NDArray:
  68    r"""
  69    View complex-valued array as its real-valued bijection.  (Inverse of :py:func:`~pyxu.util.view_as_complex`.)
@@ -596,7 +596,7 @@ 
      Source code for pyxu.util.complex
       137
 138
 
      
-[docs]
+[docs]
 139def view_as_real_mat(
 140    cmat: pxt.NDArray,
 141    real_input: bool = False,
@@ -688,7 +688,7 @@ 
      Source code for pyxu.util.complex
       226
 227
 
      
-[docs]
+[docs]
 228def view_as_complex_mat(
 229    rmat: pxt.NDArray,
 230    real_input: bool = False,
diff --git a/_modules/pyxu/util/inspect.html b/_modules/pyxu/util/inspect.html
deleted file mode 100644
index b7da4e99..00000000
--- a/_modules/pyxu/util/inspect.html
+++ /dev/null
@@ -1,586 +0,0 @@
-
-
-
-
-
-
-  
-    
-    
-    pyxu.util.inspect — Pyxu Documentation
-  
-  
-  
-  
-  
-  
-  
-
-
-
-  
-  
-  
-
-
-
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-  
-  
-  
-
-
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    
-  
-  
-  
-  
-  
-  
-
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
      
-    
      
-    
      
-
      
-  
-  
-  Ctrl+K
-
      
-  
      
-  
-    
-  
-  
      
-    
      
-      
-      
      
-        
-
-  
-  
      
-    
-    
-      
      
-        
-          
      
-        
-      
      
-    
-    
-    
-      
      
-        
-          
       v1.0.x 
      
-        
-          
      
-        
-      
      
-    
-  
      
-  
-  
-  
      
-  
      
-  
-  
-
-
-      
      
-      
-      
      
-        
-        
-          
      
-            
      
-              
-              
      
-
      
-  
-    
      
-      
-        
      
-
-
-
-
-
      
-      
-    
      
-  
-  
-
      
-
      
-              
-              
-              
-                
-
-                
      
-                  
-  
      Source code for pyxu.util.inspect
      - 1import collections.abc as cabc
- 2import importlib
- 3import inspect
- 4import types
- 5
- 6__all__ = [
- 7    "import_module",
- 8    "parse_params",
- 9]
-10
-11
-
      
-[docs]
-12def parse_params(func, *args, **kwargs) -> cabc.Mapping:
-13    """
-14    Get function parameterization.
-15
-16    Returns
-17    -------
-18    params: ~collections.abc.Mapping
-19        (key, value) params as seen in body of `func` when called via `func(*args, **kwargs)`.
-20    """
-21    sig = inspect.Signature.from_callable(func)
-22    f_args = sig.bind(*args, **kwargs)
-23    f_args.apply_defaults()
-24
-25    params = dict(
-26        zip(f_args.arguments.keys(), f_args.args),  # positional arguments
-27        **f_args.kwargs,
-28    )
-29    return params
      
-
-30
-31
-
      
-[docs]
-32def import_module(name: str, fail_on_error: bool = True) -> types.ModuleType:
-33    """
-34    Load a Python module dynamically.
-35    """
-36    try:
-37        pkg = importlib.import_module(name)
-38    except ModuleNotFoundError:
-39        if fail_on_error:
-40            raise
-41        else:
-42            pkg = None
-43    return pkg
      
-
-
      
-
-                
      
-              
-              
-              
-                
      
-                  
-
      
-  
-    
      
-
      
-
      
-  
-
      
-
-                
      
-              
-            
      
-            
-            
-              
-                
      
-
-  
      
-
      
-
-
      
-              
-            
-          
      
-          
      
-            
-          
      
-        
-      
      
-    
      
-  
      
-  
-  
-  
-
-
-  
      
-
      
-  
-    
      
-      
-        
      
-  
      
-    
-      © Copyright 2023, M. Simeoni, S. Kashani, J. Rué-Queralt & Pyxu Developers.
-      
      
-    
-  
      
-
      
-      
-        
      
-  
      
-    Created using Sphinx 7.2.5.
-    
      
-  
      
-
      
-      
-        
      
-  Built with the PyData Sphinx Theme 0.13.3.
-
      
-      
-    
      
-  
-  
-    
      
-      
-        
      
-  Built with the PyData Sphinx Theme 0.13.3.
-
      
-      
-    
      
-  
-
      
-
-  
      
-  
-
\ No newline at end of file
diff --git a/_modules/pyxu/util/misc.html b/_modules/pyxu/util/misc.html
index 15d56129..0f4eb4bf 100644
--- a/_modules/pyxu/util/misc.html
+++ b/_modules/pyxu/util/misc.html
@@ -27,8 +27,8 @@
 
 
 
-    
-    
+    
+    
     
     
     
@@ -37,13 +37,13 @@
     
     
     
-    
+    
   
   
   
 
 
-    
+    
     
     
     
@@ -456,366 +456,294 @@ 
      Source code for pyxu.util.misc
         3import inspect
   4import types
   5
-  6import dask
-  7import numpy as np
-  8
-  9import pyxu.info.deps as pxd
- 10import pyxu.info.ptype as pxt
- 11
- 12__all__ = [
- 13    "compute",
- 14    "copy_if_unsafe",
- 15    "import_module",
- 16    "infer_composition_shape",
- 17    "infer_sum_shape",
- 18    "next_fast_len",
- 19    "parse_params",
- 20    "read_only",
- 21    "to_NUMPY",
- 22]
- 23
- 24
+  6import numpy as np
+  7
+  8import pyxu.info.deps as pxd
+  9import pyxu.info.ptype as pxt
+ 10
+ 11__all__ = [
+ 12    "copy_if_unsafe",
+ 13    "import_module",
+ 14    "infer_composition_shape",
+ 15    "infer_sum_shape",
+ 16    "next_fast_len",
+ 17    "parse_params",
+ 18    "read_only",
+ 19]
+ 20
+ 21
 
      
 [docs]
- 25def next_fast_len(N: pxt.Integer, even: bool = False) -> pxt.Integer:
- 26    """
- 27    Compute the next `5-smooth number <https://en.wikipedia.org/wiki/Smooth_number>`_ greater-or-equal to `N`.
- 28
- 29    If `even=True`, then ensure the next 5-smooth number is even-valued.
- 30    """
- 31    # warning: scipy.fftpack.next_fast_len() != scipy.fft.next_fast_len()
- 32    from scipy.fftpack import next_fast_len
- 33
- 34    N5 = next_fast_len(int(N))
- 35
- 36    is_even = lambda n: n % 2 == 0
- 37    if (not is_even(N5)) and even:
- 38        while not is_even(N5 := next_fast_len(N5)):
- 39            N5 += 1
+ 22def next_fast_len(N: pxt.Integer, even: bool = False) -> pxt.Integer:
+ 23    """
+ 24    Compute the next `5-smooth number <https://en.wikipedia.org/wiki/Smooth_number>`_ greater-or-equal to `N`.
+ 25
+ 26    If `even=True`, then ensure the next 5-smooth number is even-valued.
+ 27    """
+ 28    # warning: scipy.fftpack.next_fast_len() != scipy.fft.next_fast_len()
+ 29    from scipy.fftpack import next_fast_len
+ 30
+ 31    N5 = next_fast_len(int(N))
+ 32
+ 33    is_even = lambda n: n % 2 == 0
+ 34    if (not is_even(N5)) and even:
+ 35        while not is_even(N5 := next_fast_len(N5)):
+ 36            N5 += 1
+ 37
+ 38    return N5
      
+
+ 39
  40
- 41    return N5
      
-
- 42
- 43
 
      
 [docs]
- 44def peaks(x: pxt.NDArray, y: pxt.NDArray) -> pxt.NDArray:
- 45    r"""
- 46    Matlab 2D peaks function.
+ 41def peaks(x: pxt.NDArray, y: pxt.NDArray) -> pxt.NDArray:
+ 42    r"""
+ 43    Matlab 2D peaks function.
+ 44
+ 45    Peaks is a function of two variables, obtained by translating and scaling Gaussian distributions.  (See `Matlab's
+ 46    peaks function <https://www.mathworks.com/help/matlab/ref/peaks.html>`_.)
  47
- 48    Peaks is a function of two variables, obtained by translating and scaling Gaussian distributions.  (See `Matlab's
- 49    peaks function <https://www.mathworks.com/help/matlab/ref/peaks.html>`_.)
- 50
- 51    This function is useful for testing purposes.
- 52
- 53    Parameters
- 54    ----------
- 55    x: NDArray
- 56        X coordinates.
- 57    y: NDArray
- 58        Y coordinates.
- 59
- 60    Returns
- 61    -------
- 62    z: NDArray
- 63        Values of the 2D function ``peaks`` at the points specified by the entries of `x` and `y`.
+ 48    This function is useful for testing purposes.
+ 49
+ 50    Parameters
+ 51    ----------
+ 52    x: NDArray
+ 53        X coordinates.
+ 54    y: NDArray
+ 55        Y coordinates.
+ 56
+ 57    Returns
+ 58    -------
+ 59    z: NDArray
+ 60        Values of the 2D function ``peaks`` at the points specified by the entries of `x` and `y`.
+ 61
+ 62    Examples
+ 63    --------
  64
- 65    Examples
- 66    --------
- 67
- 68    .. plot::
- 69
- 70       import numpy as np
- 71       import matplotlib.pyplot as plt
- 72       from pyxu.util.misc import peaks
- 73
- 74       x = np.linspace(-3, 3, 1000)
- 75       xx, yy = np.meshgrid(x, x)
- 76       z = peaks(xx, yy)
- 77       plt.figure()
- 78       plt.imshow(z)
- 79    """
- 80    ndi = pxd.NDArrayInfo.from_obj(x)
- 81    xp = ndi.module()
- 82
- 83    a = 3 * ((1 - x) ** 2) * xp.exp(-(x**2) - (y + 1) ** 2)
- 84    b = -10 * ((x / 5) - x**3 - y**5) * xp.exp(-(x**2) - (y**2))
- 85    c = -xp.exp(-((x + 1) ** 2) - (y**2)) / 3
- 86    z = a + b + c
- 87    return z
      
-
- 88
- 89
+ 65    .. plot::
+ 66
+ 67       import numpy as np
+ 68       import matplotlib.pyplot as plt
+ 69       from pyxu.util.misc import peaks
+ 70
+ 71       x = np.linspace(-3, 3, 1000)
+ 72       xx, yy = np.meshgrid(x, x)
+ 73       z = peaks(xx, yy)
+ 74       plt.figure()
+ 75       plt.imshow(z)
+ 76    """
+ 77    ndi = pxd.NDArrayInfo.from_obj(x)
+ 78    xp = ndi.module()
+ 79
+ 80    a = 3 * ((1 - x) ** 2) * xp.exp(-(x**2) - (y + 1) ** 2)
+ 81    b = -10 * ((x / 5) - x**3 - y**5) * xp.exp(-(x**2) - (y**2))
+ 82    c = -xp.exp(-((x + 1) ** 2) - (y**2)) / 3
+ 83    z = a + b + c
+ 84    return z
      
+
+ 85
+ 86
 
      
 [docs]
- 90def star_like_sample(
- 91    N: pxt.Integer,
- 92    w: pxt.Integer,
- 93    s: pxt.Real,
- 94    po: pxt.Integer,
- 95    x0: pxt.Real,
- 96    ndi: pxd.NDArrayInfo = pxd.NDArrayInfo.NUMPY,
- 97) -> pxt.NDArray:
- 98    r"""
- 99    Star-like test image.
-100
-101    Generates a (N, N) square image of a star-like object normalized between 0 and 1.  Based on `GlobalBioIm's
-102    StarLikeSample function
-103    <https://github.com/Biomedical-Imaging-Group/GlobalBioIm/blob/master/Util/StarLikeSample.m>`_.  This function is
-104    useful for testing purposes as it contains high-frequency information.
-105
-106    Parameters
-107    ----------
-108    N: Integer
-109        Size of the image (must be an even number).
-110    w: Integer
-111        The number of branches of the sample will be 4*w.
-112    s: Real
-113        Slope of the sigmoid function :math:`\frac1{1+\exp[s (x-x_{0})]}` attenuating the boundaries.
-114    po: Integer
-115        Power-raising factor for the final image (to have smoother edges).
-116    x0: Real
-117        Radial shift of the sigmoid function :math:`\frac1{1+\exp[s (x-x_{0})]}`.
-118    ndi: NDArrayInfo
-119        Desired array module for the output.
-120
-121    Returns
-122    -------
-123    image: NDArray
-124        (N, N) image of star-like sample.
-125
-126    Examples
-127    --------
-128    .. plot::
-129
-130       import numpy as np
-131       import matplotlib.pyplot as plt
-132       from pyxu.util.misc import star_like_sample
-133
-134       star = star_like_sample(N=256, w=8, s=20, po=3, x0=0.7)
-135       plt.figure()
-136       plt.imshow(star)
-137    """
-138    assert N % 2 == 0
-139    xp = ndi.module()
-140
-141    grid = xp.linspace(-1, 1, N)
-142    x, y = xp.meshgrid(grid, grid)
-143    theta = xp.arctan2(y, x)
-144    image = 1 + xp.cos(4 * w * theta)
-145    image /= 1 + xp.exp(s * (xp.sqrt(x**2 + y**2) - x0))
-146    image = xp.maximum(image, 0) / 2
-147    image **= po
-148    image /= xp.amax(image)
-149    return image
      
-
-150
-151
+ 87def star_like_sample(
+ 88    N: pxt.Integer,
+ 89    w: pxt.Integer,
+ 90    s: pxt.Real,
+ 91    po: pxt.Integer,
+ 92    x0: pxt.Real,
+ 93    ndi: pxd.NDArrayInfo = pxd.NDArrayInfo.NUMPY,
+ 94) -> pxt.NDArray:
+ 95    r"""
+ 96    Star-like test image.
+ 97
+ 98    Generates a (N, N) square image of a star-like object normalized between 0 and 1.  Based on `GlobalBioIm's
+ 99    StarLikeSample function
+100    <https://github.com/Biomedical-Imaging-Group/GlobalBioIm/blob/master/Util/StarLikeSample.m>`_.  This function is
+101    useful for testing purposes as it contains high-frequency information.
+102
+103    Parameters
+104    ----------
+105    N: Integer
+106        Size of the image (must be an even number).
+107    w: Integer
+108        The number of branches of the sample will be 4*w.
+109    s: Real
+110        Slope of the sigmoid function :math:`\frac1{1+\exp[s (x-x_{0})]}` attenuating the boundaries.
+111    po: Integer
+112        Power-raising factor for the final image (to have smoother edges).
+113    x0: Real
+114        Radial shift of the sigmoid function :math:`\frac1{1+\exp[s (x-x_{0})]}`.
+115    ndi: NDArrayInfo
+116        Desired array module for the output.
+117
+118    Returns
+119    -------
+120    image: NDArray
+121        (N, N) image of star-like sample.
+122
+123    Examples
+124    --------
+125    .. plot::
+126
+127       import numpy as np
+128       import matplotlib.pyplot as plt
+129       from pyxu.util.misc import star_like_sample
+130
+131       star = star_like_sample(N=256, w=8, s=20, po=3, x0=0.7)
+132       plt.figure()
+133       plt.imshow(star)
+134    """
+135    assert N % 2 == 0
+136    xp = ndi.module()
+137
+138    grid = xp.linspace(-1, 1, N)
+139    x, y = xp.meshgrid(grid, grid)
+140    theta = xp.arctan2(y, x)
+141    image = 1 + xp.cos(4 * w * theta)
+142    image /= 1 + xp.exp(s * (xp.sqrt(x**2 + y**2) - x0))
+143    image = xp.maximum(image, 0) / 2
+144    image **= po
+145    image /= xp.amax(image)
+146    return image
      
+
+147
+148
 
      
 [docs]
-152def parse_params(func, *args, **kwargs) -> cabc.Mapping:
-153    """
-154    Get function parameterization.
-155
-156    Returns
-157    -------
-158    params: ~collections.abc.Mapping
-159        (key, value) params as seen in body of `func` when called via `func(*args, **kwargs)`.
-160    """
-161    sig = inspect.Signature.from_callable(func)
-162    f_args = sig.bind(*args, **kwargs)
-163    f_args.apply_defaults()
-164
-165    params = dict(
-166        zip(f_args.arguments.keys(), f_args.args),  # positional arguments
-167        **f_args.kwargs,
-168    )
-169    return params
      
-
-170
-171
+149def parse_params(func, *args, **kwargs) -> cabc.Mapping:
+150    """
+151    Get function parameterization.
+152
+153    Returns
+154    -------
+155    params: ~collections.abc.Mapping
+156        (key, value) params as seen in body of `func` when called via `func(*args, **kwargs)`.
+157    """
+158    sig = inspect.Signature.from_callable(func)
+159    f_args = sig.bind(*args, **kwargs)
+160    f_args.apply_defaults()
+161
+162    params = dict(
+163        zip(f_args.arguments.keys(), f_args.args),  # positional arguments
+164        **f_args.kwargs,
+165    )
+166    return params
      
+
+167
+168
 
      
 [docs]
-172def import_module(name: str, fail_on_error: bool = True) -> types.ModuleType:
-173    """
-174    Load a Python module dynamically.
-175    """
-176    try:
-177        pkg = importlib.import_module(name)
-178    except ModuleNotFoundError:
-179        if fail_on_error:
-180            raise
-181        else:
-182            pkg = None
-183    return pkg
      
-
-184
-185
-
      
-[docs]
-186def compute(*args, mode: str = "compute", **kwargs):
-187    r"""
-188    Force computation of Dask collections.
-189
-190    Parameters
-191    ----------
-192    \*args: object, list
-193        Any number of objects.  If it is a dask object, it is evaluated and the result is returned.  Non-dask arguments
-194        are passed through unchanged.  Python collections are traversed to find/evaluate dask objects within.  (Use
-195        `traverse` =False to disable this behavior.)
-196    mode: str
-197        Dask evaluation strategy: compute or persist.
-198    \*\*kwargs: dict
-199        Extra keyword parameters forwarded to :py:func:`dask.compute` or :py:func:`dask.persist`.
-200
-201    Returns
-202    -------
-203    \*cargs: object, list
-204        Evaluated objects. Non-dask arguments are passed through unchanged.
-205    """
-206    try:
-207        func = dict(compute=dask.compute, persist=dask.persist)[mode.lower()]
-208    except Exception:
-209        raise ValueError(f"mode: expected compute/persist, got {mode}.")
-210
-211    cargs = func(*args, **kwargs)
-212    if len(args) == 1:
-213        cargs = cargs[0]
-214    return cargs
      
-
-215
-216
-
      
-[docs]
-217def to_NUMPY(x: pxt.NDArray) -> pxt.NDArray:
-218    """
-219    Convert an array from a specific backend to NUMPY.
-220
-221    Parameters
-222    ----------
-223    x: NDArray
-224        Array to be converted.
-225
-226    Returns
-227    -------
-228    y: NDArray
-229        Array with NumPy backend.
-230
-231    Notes
-232    -----
-233    This function is a no-op if the array is already a NumPy array.
-234    """
-235    N = pxd.NDArrayInfo
-236    ndi = N.from_obj(x)
-237    if ndi == N.NUMPY:
-238        y = x
-239    elif ndi == N.DASK:
-240        y = compute(x)
-241    elif ndi == N.CUPY:
-242        y = x.get()
-243    else:
-244        msg = f"Dev-action required: define behaviour for {ndi}."
-245        raise ValueError(msg)
-246    return y
      
-
-247
-248
+169def import_module(name: str, fail_on_error: bool = True) -> types.ModuleType:
+170    """
+171    Load a Python module dynamically.
+172    """
+173    try:
+174        pkg = importlib.import_module(name)
+175    except ModuleNotFoundError:
+176        if fail_on_error:
+177            raise
+178        else:
+179            pkg = None
+180    return pkg
      
+
+181
+182
 
      
 [docs]
-249def copy_if_unsafe(x: pxt.NDArray) -> pxt.NDArray:
-250    """
-251    Copy array if it is unsafe to do in-place updates on it.
-252
-253    In-place updates are unsafe if:
-254
-255    * the array is read-only, OR
-256    * the array is a view onto another array.
-257
-258    Parameters
-259    ----------
-260    x: NDArray
-261
-262    Returns
-263    -------
-264    y: NDArray
-265    """
-266    N = pxd.NDArrayInfo
-267    ndi = N.from_obj(x)
-268    if ndi == N.DASK:
-269        # Dask operations span a graph -> always safe.
-270        y = x
-271    elif ndi == N.NUMPY:
-272        read_only = not x.flags.writeable
-273        reference = not x.flags.owndata
-274        y = x.copy() if (read_only or reference) else x
-275    elif ndi == N.CUPY:
-276        read_only = False  # https://github.com/cupy/cupy/issues/2616
-277        reference = not x.flags.owndata
-278        y = x.copy() if (read_only or reference) else x
-279    else:
-280        msg = f"copy_if_unsafe() not yet defined for {ndi}."
-281        raise NotImplementedError(msg)
-282    return y
      
-
-283
-284
+183def copy_if_unsafe(x: pxt.NDArray) -> pxt.NDArray:
+184    """
+185    Copy array if it is unsafe to do in-place updates on it.
+186
+187    In-place updates are unsafe if:
+188
+189    * the array is read-only, OR
+190    * the array is a view onto another array.
+191
+192    Parameters
+193    ----------
+194    x: NDArray
+195
+196    Returns
+197    -------
+198    y: NDArray
+199    """
+200    N = pxd.NDArrayInfo
+201    ndi = N.from_obj(x)
+202    if ndi == N.DASK:
+203        # Dask operations span a graph -> always safe.
+204        y = x
+205    elif ndi == N.NUMPY:
+206        read_only = not x.flags.writeable
+207        reference = not x.flags.owndata
+208        y = x.copy() if (read_only or reference) else x
+209    elif ndi == N.CUPY:
+210        read_only = False  # https://github.com/cupy/cupy/issues/2616
+211        reference = not x.flags.owndata
+212        y = x.copy() if (read_only or reference) else x
+213    else:
+214        msg = f"copy_if_unsafe() not yet defined for {ndi}."
+215        raise NotImplementedError(msg)
+216    return y
      
+
+217
+218
 
      
 [docs]
-285def read_only(x: pxt.NDArray) -> pxt.NDArray:
-286    """
-287    Make an array read-only.
-288
-289    Parameters
-290    ----------
-291    x: NDArray
-292
-293    Returns
-294    -------
-295    y: NDArray
-296    """
-297    N = pxd.NDArrayInfo
-298    ndi = N.from_obj(x)
-299    if ndi == N.DASK:
-300        # Dask operations are read-only since graph-backed.
-301        y = x
-302    elif ndi == N.NUMPY:
-303        y = x.view()
-304        y.flags.writeable = False
-305    elif ndi == N.CUPY:
-306        y = x.view()
-307        # y.flags.writeable = False  # https://github.com/cupy/cupy/issues/2616
-308    else:
-309        msg = f"read_only() not yet defined for {ndi}."
-310        raise NotImplementedError(msg)
-311    return y
      
-
-312
-313
+219def read_only(x: pxt.NDArray) -> pxt.NDArray:
+220    """
+221    Make an array read-only.
+222
+223    Parameters
+224    ----------
+225    x: NDArray
+226
+227    Returns
+228    -------
+229    y: NDArray
+230    """
+231    N = pxd.NDArrayInfo
+232    ndi = N.from_obj(x)
+233    if ndi == N.DASK:
+234        # Dask operations are read-only since graph-backed.
+235        y = x
+236    elif ndi == N.NUMPY:
+237        y = x.view()
+238        y.flags.writeable = False
+239    elif ndi == N.CUPY:
+240        y = x.view()
+241        # y.flags.writeable = False  # https://github.com/cupy/cupy/issues/2616
+242    else:
+243        msg = f"read_only() not yet defined for {ndi}."
+244        raise NotImplementedError(msg)
+245    return y
      
+
+246
+247
 
      
 [docs]
-314def infer_sum_shape(sh1: pxt.OpShape, sh2: pxt.OpShape) -> pxt.OpShape:
-315    r"""
-316    Infer shape of arithmetic operation :math:`A + B`.
-317    """
-318    A, B, C, D = *sh1, *sh2
-319    if B == D:
-320        return np.broadcast_shapes((A,), (C,)) + (B,)
-321    else:
-322        raise ValueError(f"Addition of {sh1} and {sh2} operators forbidden.")
      
-
-323
-324
+248def infer_sum_shape(sh1: pxt.OpShape, sh2: pxt.OpShape) -> pxt.OpShape:
+249    r"""
+250    Infer shape of arithmetic operation :math:`A + B`.
+251    """
+252    A, B, C, D = *sh1, *sh2
+253    if B == D:
+254        return np.broadcast_shapes((A,), (C,)) + (B,)
+255    else:
+256        raise ValueError(f"Addition of {sh1} and {sh2} operators forbidden.")
      
+
+257
+258
 
      
 [docs]
-325def infer_composition_shape(sh1: pxt.OpShape, sh2: pxt.OpShape) -> pxt.OpShape:
-326    r"""
-327    Infer shape of arithmetic operation :math:`A \circ B`.
-328    """
-329    A, B, C, D = *sh1, *sh2
-330    if B == C:
-331        return (A, D)
-332    else:
-333        raise ValueError(f"Composition of {sh1} and {sh2} operators forbidden.")
      
+259def infer_composition_shape(sh1: pxt.OpShape, sh2: pxt.OpShape) -> pxt.OpShape:
+260    r"""
+261    Infer shape of arithmetic operation :math:`A \circ B`.
+262    """
+263    A, B, C, D = *sh1, *sh2
+264    if B == C:
+265        return (A, D)
+266    else:
+267        raise ValueError(f"Composition of {sh1} and {sh2} operators forbidden.")
    diff --git a/_modules/pyxu/util/operator.html b/_modules/pyxu/util/operator.html index eaba3e1c..dc860b89 100644 --- a/_modules/pyxu/util/operator.html +++ b/_modules/pyxu/util/operator.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + diff --git a/_modules/typing.html b/_modules/typing.html index 567dcf51..6d453d4d 100644 --- a/_modules/typing.html +++ b/_modules/typing.html @@ -27,8 +27,8 @@ - - + + @@ -37,13 +37,13 @@ - + - + @@ -199,7 +199,7 @@
    -
    v1.0.x
    +
    Pyxu v1.0.1
      @@ -236,7 +236,7 @@ - +
    • @@ -341,7 +341,7 @@
      -
      v1.0.x
      +
      Pyxu v1.0.1
        @@ -378,7 +378,7 @@ - +
      • @@ -454,22 +454,22 @@

        Source code for typing

            1"""
    2The typing module: Support for gradual typing as defined by PEP 484 and subsequent PEPs.
    3
-   4Among other things, the module includes the following:
-   5* Generic, Protocol, and internal machinery to support generic aliases.
-   6  All subscripted types like X[int], Union[int, str] are generic aliases.
-   7* Various "special forms" that have unique meanings in type annotations:
-   8  NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others.
-   9* Classes whose instances can be type arguments to generic classes and functions:
-  10  TypeVar, ParamSpec, TypeVarTuple.
-  11* Public helper functions: get_type_hints, overload, cast, final, and others.
-  12* Several protocols to support duck-typing:
-  13  SupportsFloat, SupportsIndex, SupportsAbs, and others.
-  14* Special types: NewType, NamedTuple, TypedDict.
-  15* Deprecated wrapper submodules for re and io related types.
-  16* Deprecated aliases for builtin types and collections.abc ABCs.
-  17
-  18Any name not present in __all__ is an implementation detail
-  19that may be changed without notice. Use at your own risk!
+   4Any name not present in __all__ is an implementation detail
+   5that may be changed without notice. Use at your own risk!
+   6
+   7Among other things, the module includes the following:
+   8* Generic, Protocol, and internal machinery to support generic aliases.
+   9  All subscripted types like X[int], Union[int, str] are generic aliases.
+  10* Various "special forms" that have unique meanings in type annotations:
+  11  NoReturn, Never, ClassVar, Self, Concatenate, Unpack, and others.
+  12* Classes whose instances can be type arguments to generic classes and functions:
+  13  TypeVar, ParamSpec, TypeVarTuple.
+  14* Public helper functions: get_type_hints, overload, cast, final, and others.
+  15* Several protocols to support duck-typing:
+  16  SupportsFloat, SupportsIndex, SupportsAbs, and others.
+  17* Special types: NewType, NamedTuple, TypedDict.
+  18* Deprecated wrapper submodules for re and io related types.
+  19* Deprecated aliases for builtin types and collections.abc ABCs.
   20"""
   21
   22from abc import abstractmethod, ABCMeta
@@ -660,3284 +660,3264 @@ 
        Source code for typing
          207    """Internal helper for munging collections.abc.Callable's __args__.
  208
  209    The canonical representation for a Callable's __args__ flattens the
- 210    argument types, see https://github.com/python/cpython/issues/86361.
+ 210    argument types, see https://bugs.python.org/issue42195. For example::
  211
- 212    For example::
- 213
- 214        assert collections.abc.Callable[[int, int], str].__args__ == (int, int, str)
- 215        assert collections.abc.Callable[ParamSpec, str].__args__ == (ParamSpec, str)
- 216
- 217    As a result, if we need to reconstruct the Callable from its __args__,
- 218    we need to unflatten it.
- 219    """
- 220    return (
- 221        typ.__origin__ is collections.abc.Callable
- 222        and not (len(args) == 2 and _is_param_expr(args[0]))
- 223    )
- 224
- 225
- 226def _type_repr(obj):
- 227    """Return the repr() of an object, special-casing types (internal helper).
- 228
- 229    If obj is a type, we return a shorter version than the default
- 230    type.__repr__, based on the module and qualified name, which is
- 231    typically enough to uniquely identify a type.  For everything
- 232    else, we fall back on repr(obj).
- 233    """
- 234    if isinstance(obj, types.GenericAlias):
- 235        return repr(obj)
- 236    if isinstance(obj, type):
- 237        if obj.__module__ == 'builtins':
- 238            return obj.__qualname__
- 239        return f'{obj.__module__}.{obj.__qualname__}'
- 240    if obj is ...:
- 241        return('...')
- 242    if isinstance(obj, types.FunctionType):
- 243        return obj.__name__
- 244    return repr(obj)
- 245
- 246
- 247def _collect_parameters(args):
- 248    """Collect all type variables and parameter specifications in args
- 249    in order of first appearance (lexicographic order).
+ 212        collections.abc.Callable[[int, int], str].__args__ == (int, int, str)
+ 213        collections.abc.Callable[ParamSpec, str].__args__ == (ParamSpec, str)
+ 214
+ 215    As a result, if we need to reconstruct the Callable from its __args__,
+ 216    we need to unflatten it.
+ 217    """
+ 218    return (
+ 219        typ.__origin__ is collections.abc.Callable
+ 220        and not (len(args) == 2 and _is_param_expr(args[0]))
+ 221    )
+ 222
+ 223
+ 224def _type_repr(obj):
+ 225    """Return the repr() of an object, special-casing types (internal helper).
+ 226
+ 227    If obj is a type, we return a shorter version than the default
+ 228    type.__repr__, based on the module and qualified name, which is
+ 229    typically enough to uniquely identify a type.  For everything
+ 230    else, we fall back on repr(obj).
+ 231    """
+ 232    if isinstance(obj, types.GenericAlias):
+ 233        return repr(obj)
+ 234    if isinstance(obj, type):
+ 235        if obj.__module__ == 'builtins':
+ 236            return obj.__qualname__
+ 237        return f'{obj.__module__}.{obj.__qualname__}'
+ 238    if obj is ...:
+ 239        return('...')
+ 240    if isinstance(obj, types.FunctionType):
+ 241        return obj.__name__
+ 242    return repr(obj)
+ 243
+ 244
+ 245def _collect_parameters(args):
+ 246    """Collect all type variables and parameter specifications in args
+ 247    in order of first appearance (lexicographic order).
+ 248
+ 249    For example::
  250
- 251    For example::
- 252
- 253        assert _collect_parameters((T, Callable[P, T])) == (T, P)
- 254    """
- 255    parameters = []
- 256    for t in args:
- 257        if isinstance(t, type):
- 258            # We don't want __parameters__ descriptor of a bare Python class.
- 259            pass
- 260        elif isinstance(t, tuple):
- 261            # `t` might be a tuple, when `ParamSpec` is substituted with
- 262            # `[T, int]`, or `[int, *Ts]`, etc.
- 263            for x in t:
- 264                for collected in _collect_parameters([x]):
- 265                    if collected not in parameters:
- 266                        parameters.append(collected)
- 267        elif hasattr(t, '__typing_subst__'):
- 268            if t not in parameters:
- 269                parameters.append(t)
- 270        else:
- 271            for x in getattr(t, '__parameters__', ()):
- 272                if x not in parameters:
- 273                    parameters.append(x)
- 274    return tuple(parameters)
- 275
- 276
- 277def _check_generic(cls, parameters, elen):
- 278    """Check correct count for parameters of a generic cls (internal helper).
- 279
- 280    This gives a nice error message in case of count mismatch.
- 281    """
- 282    if not elen:
- 283        raise TypeError(f"{cls} is not a generic class")
- 284    alen = len(parameters)
- 285    if alen != elen:
- 286        raise TypeError(f"Too {'many' if alen > elen else 'few'} arguments for {cls};"
- 287                        f" actual {alen}, expected {elen}")
- 288
- 289def _unpack_args(args):
- 290    newargs = []
- 291    for arg in args:
- 292        subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
- 293        if subargs is not None and not (subargs and subargs[-1] is ...):
- 294            newargs.extend(subargs)
- 295        else:
- 296            newargs.append(arg)
- 297    return newargs
- 298
- 299def _deduplicate(params):
- 300    # Weed out strict duplicates, preserving the first of each occurrence.
- 301    all_params = set(params)
- 302    if len(all_params) < len(params):
- 303        new_params = []
- 304        for t in params:
- 305            if t in all_params:
- 306                new_params.append(t)
- 307                all_params.remove(t)
- 308        params = new_params
- 309        assert not all_params, all_params
- 310    return params
- 311
- 312
- 313def _remove_dups_flatten(parameters):
- 314    """Internal helper for Union creation and substitution.
- 315
- 316    Flatten Unions among parameters, then remove duplicates.
- 317    """
- 318    # Flatten out Union[Union[...], ...].
- 319    params = []
- 320    for p in parameters:
- 321        if isinstance(p, (_UnionGenericAlias, types.UnionType)):
- 322            params.extend(p.__args__)
- 323        else:
- 324            params.append(p)
+ 251        assert _collect_parameters((T, Callable[P, T])) == (T, P)
+ 252    """
+ 253    parameters = []
+ 254    for t in args:
+ 255        if isinstance(t, type):
+ 256            # We don't want __parameters__ descriptor of a bare Python class.
+ 257            pass
+ 258        elif isinstance(t, tuple):
+ 259            # `t` might be a tuple, when `ParamSpec` is substituted with
+ 260            # `[T, int]`, or `[int, *Ts]`, etc.
+ 261            for x in t:
+ 262                for collected in _collect_parameters([x]):
+ 263                    if collected not in parameters:
+ 264                        parameters.append(collected)
+ 265        elif hasattr(t, '__typing_subst__'):
+ 266            if t not in parameters:
+ 267                parameters.append(t)
+ 268        else:
+ 269            for x in getattr(t, '__parameters__', ()):
+ 270                if x not in parameters:
+ 271                    parameters.append(x)
+ 272    return tuple(parameters)
+ 273
+ 274
+ 275def _check_generic(cls, parameters, elen):
+ 276    """Check correct count for parameters of a generic cls (internal helper).
+ 277
+ 278    This gives a nice error message in case of count mismatch.
+ 279    """
+ 280    if not elen:
+ 281        raise TypeError(f"{cls} is not a generic class")
+ 282    alen = len(parameters)
+ 283    if alen != elen:
+ 284        raise TypeError(f"Too {'many' if alen > elen else 'few'} arguments for {cls};"
+ 285                        f" actual {alen}, expected {elen}")
+ 286
+ 287def _unpack_args(args):
+ 288    newargs = []
+ 289    for arg in args:
+ 290        subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
+ 291        if subargs is not None and not (subargs and subargs[-1] is ...):
+ 292            newargs.extend(subargs)
+ 293        else:
+ 294            newargs.append(arg)
+ 295    return newargs
+ 296
+ 297def _deduplicate(params):
+ 298    # Weed out strict duplicates, preserving the first of each occurrence.
+ 299    all_params = set(params)
+ 300    if len(all_params) < len(params):
+ 301        new_params = []
+ 302        for t in params:
+ 303            if t in all_params:
+ 304                new_params.append(t)
+ 305                all_params.remove(t)
+ 306        params = new_params
+ 307        assert not all_params, all_params
+ 308    return params
+ 309
+ 310
+ 311def _remove_dups_flatten(parameters):
+ 312    """Internal helper for Union creation and substitution.
+ 313
+ 314    Flatten Unions among parameters, then remove duplicates.
+ 315    """
+ 316    # Flatten out Union[Union[...], ...].
+ 317    params = []
+ 318    for p in parameters:
+ 319        if isinstance(p, (_UnionGenericAlias, types.UnionType)):
+ 320            params.extend(p.__args__)
+ 321        else:
+ 322            params.append(p)
+ 323
+ 324    return tuple(_deduplicate(params))
  325
- 326    return tuple(_deduplicate(params))
- 327
- 328
- 329def _flatten_literal_params(parameters):
- 330    """Internal helper for Literal creation: flatten Literals among parameters."""
- 331    params = []
- 332    for p in parameters:
- 333        if isinstance(p, _LiteralGenericAlias):
- 334            params.extend(p.__args__)
- 335        else:
- 336            params.append(p)
- 337    return tuple(params)
- 338
+ 326
+ 327def _flatten_literal_params(parameters):
+ 328    """Internal helper for Literal creation: flatten Literals among parameters."""
+ 329    params = []
+ 330    for p in parameters:
+ 331        if isinstance(p, _LiteralGenericAlias):
+ 332            params.extend(p.__args__)
+ 333        else:
+ 334            params.append(p)
+ 335    return tuple(params)
+ 336
+ 337
+ 338_cleanups = []
  339
- 340_cleanups = []
- 341
- 342
- 343def _tp_cache(func=None, /, *, typed=False):
- 344    """Internal wrapper caching __getitem__ of generic types.
- 345
- 346    For non-hashable arguments, the original function is used as a fallback.
- 347    """
- 348    def decorator(func):
- 349        cached = functools.lru_cache(typed=typed)(func)
- 350        _cleanups.append(cached.cache_clear)
- 351
- 352        @functools.wraps(func)
- 353        def inner(*args, **kwds):
- 354            try:
- 355                return cached(*args, **kwds)
- 356            except TypeError:
- 357                pass  # All real errors (not unhashable args) are raised below.
- 358            return func(*args, **kwds)
- 359        return inner
+ 340
+ 341def _tp_cache(func=None, /, *, typed=False):
+ 342    """Internal wrapper caching __getitem__ of generic types with a fallback to
+ 343    original function for non-hashable arguments.
+ 344    """
+ 345    def decorator(func):
+ 346        cached = functools.lru_cache(typed=typed)(func)
+ 347        _cleanups.append(cached.cache_clear)
+ 348
+ 349        @functools.wraps(func)
+ 350        def inner(*args, **kwds):
+ 351            try:
+ 352                return cached(*args, **kwds)
+ 353            except TypeError:
+ 354                pass  # All real errors (not unhashable args) are raised below.
+ 355            return func(*args, **kwds)
+ 356        return inner
+ 357
+ 358    if func is not None:
+ 359        return decorator(func)
  360
- 361    if func is not None:
- 362        return decorator(func)
- 363
- 364    return decorator
+ 361    return decorator
+ 362
+ 363def _eval_type(t, globalns, localns, recursive_guard=frozenset()):
+ 364    """Evaluate all forward references in the given type t.
  365
- 366def _eval_type(t, globalns, localns, recursive_guard=frozenset()):
- 367    """Evaluate all forward references in the given type t.
- 368
- 369    For use of globalns and localns see the docstring for get_type_hints().
- 370    recursive_guard is used to prevent infinite recursion with a recursive
- 371    ForwardRef.
- 372    """
- 373    if isinstance(t, ForwardRef):
- 374        return t._evaluate(globalns, localns, recursive_guard)
- 375    if isinstance(t, (_GenericAlias, GenericAlias, types.UnionType)):
- 376        if isinstance(t, GenericAlias):
- 377            args = tuple(
- 378                ForwardRef(arg) if isinstance(arg, str) else arg
- 379                for arg in t.__args__
- 380            )
- 381            is_unpacked = t.__unpacked__
- 382            if _should_unflatten_callable_args(t, args):
- 383                t = t.__origin__[(args[:-1], args[-1])]
- 384            else:
- 385                t = t.__origin__[args]
- 386            if is_unpacked:
- 387                t = Unpack[t]
- 388        ev_args = tuple(_eval_type(a, globalns, localns, recursive_guard) for a in t.__args__)
- 389        if ev_args == t.__args__:
- 390            return t
- 391        if isinstance(t, GenericAlias):
- 392            return GenericAlias(t.__origin__, ev_args)
- 393        if isinstance(t, types.UnionType):
- 394            return functools.reduce(operator.or_, ev_args)
- 395        else:
- 396            return t.copy_with(ev_args)
- 397    return t
- 398
+ 366    For use of globalns and localns see the docstring for get_type_hints().
+ 367    recursive_guard is used to prevent infinite recursion with a recursive
+ 368    ForwardRef.
+ 369    """
+ 370    if isinstance(t, ForwardRef):
+ 371        return t._evaluate(globalns, localns, recursive_guard)
+ 372    if isinstance(t, (_GenericAlias, GenericAlias, types.UnionType)):
+ 373        if isinstance(t, GenericAlias):
+ 374            args = tuple(
+ 375                ForwardRef(arg) if isinstance(arg, str) else arg
+ 376                for arg in t.__args__
+ 377            )
+ 378            is_unpacked = t.__unpacked__
+ 379            if _should_unflatten_callable_args(t, args):
+ 380                t = t.__origin__[(args[:-1], args[-1])]
+ 381            else:
+ 382                t = t.__origin__[args]
+ 383            if is_unpacked:
+ 384                t = Unpack[t]
+ 385        ev_args = tuple(_eval_type(a, globalns, localns, recursive_guard) for a in t.__args__)
+ 386        if ev_args == t.__args__:
+ 387            return t
+ 388        if isinstance(t, GenericAlias):
+ 389            return GenericAlias(t.__origin__, ev_args)
+ 390        if isinstance(t, types.UnionType):
+ 391            return functools.reduce(operator.or_, ev_args)
+ 392        else:
+ 393            return t.copy_with(ev_args)
+ 394    return t
+ 395
+ 396
+ 397class _Final:
+ 398    """Mixin to prohibit subclassing."""
  399
- 400class _Final:
- 401    """Mixin to prohibit subclassing."""
- 402
- 403    __slots__ = ('__weakref__',)
- 404
- 405    def __init_subclass__(cls, /, *args, **kwds):
- 406        if '_root' not in kwds:
- 407            raise TypeError("Cannot subclass special typing classes")
+ 400    __slots__ = ('__weakref__',)
+ 401
+ 402    def __init_subclass__(cls, /, *args, **kwds):
+ 403        if '_root' not in kwds:
+ 404            raise TypeError("Cannot subclass special typing classes")
+ 405
+ 406class _Immutable:
+ 407    """Mixin to indicate that object should not be copied."""
  408
- 409class _Immutable:
- 410    """Mixin to indicate that object should not be copied."""
- 411
- 412    __slots__ = ()
+ 409    __slots__ = ()
+ 410
+ 411    def __copy__(self):
+ 412        return self
  413
- 414    def __copy__(self):
+ 414    def __deepcopy__(self, memo):
  415        return self
  416
- 417    def __deepcopy__(self, memo):
- 418        return self
- 419
+ 417
+ 418class _NotIterable:
+ 419    """Mixin to prevent iteration, without being compatible with Iterable.
  420
- 421class _NotIterable:
- 422    """Mixin to prevent iteration, without being compatible with Iterable.
- 423
- 424    That is, we could do::
- 425
- 426        def __iter__(self): raise TypeError()
+ 421    That is, we could do::
+ 422
+ 423        def __iter__(self): raise TypeError()
+ 424
+ 425    But this would make users of this mixin duck type-compatible with
+ 426    collections.abc.Iterable - isinstance(foo, Iterable) would be True.
  427
- 428    But this would make users of this mixin duck type-compatible with
- 429    collections.abc.Iterable - isinstance(foo, Iterable) would be True.
- 430
- 431    Luckily, we can instead prevent iteration by setting __iter__ to None, which
- 432    is treated specially.
- 433    """
+ 428    Luckily, we can instead prevent iteration by setting __iter__ to None, which
+ 429    is treated specially.
+ 430    """
+ 431
+ 432    __slots__ = ()
+ 433    __iter__ = None
  434
- 435    __slots__ = ()
- 436    __iter__ = None
- 437
- 438
- 439# Internal indicator of special typing constructs.
- 440# See __doc__ instance attribute for specific docs.
- 441class _SpecialForm(_Final, _NotIterable, _root=True):
- 442    __slots__ = ('_name', '__doc__', '_getitem')
- 443
- 444    def __init__(self, getitem):
- 445        self._getitem = getitem
- 446        self._name = getitem.__name__
- 447        self.__doc__ = getitem.__doc__
- 448
- 449    def __getattr__(self, item):
- 450        if item in {'__name__', '__qualname__'}:
- 451            return self._name
- 452
- 453        raise AttributeError(item)
+ 435
+ 436# Internal indicator of special typing constructs.
+ 437# See __doc__ instance attribute for specific docs.
+ 438class _SpecialForm(_Final, _NotIterable, _root=True):
+ 439    __slots__ = ('_name', '__doc__', '_getitem')
+ 440
+ 441    def __init__(self, getitem):
+ 442        self._getitem = getitem
+ 443        self._name = getitem.__name__
+ 444        self.__doc__ = getitem.__doc__
+ 445
+ 446    def __getattr__(self, item):
+ 447        if item in {'__name__', '__qualname__'}:
+ 448            return self._name
+ 449
+ 450        raise AttributeError(item)
+ 451
+ 452    def __mro_entries__(self, bases):
+ 453        raise TypeError(f"Cannot subclass {self!r}")
  454
- 455    def __mro_entries__(self, bases):
- 456        raise TypeError(f"Cannot subclass {self!r}")
+ 455    def __repr__(self):
+ 456        return 'typing.' + self._name
  457
- 458    def __repr__(self):
- 459        return 'typing.' + self._name
+ 458    def __reduce__(self):
+ 459        return self._name
  460
- 461    def __reduce__(self):
- 462        return self._name
+ 461    def __call__(self, *args, **kwds):
+ 462        raise TypeError(f"Cannot instantiate {self!r}")
  463
- 464    def __call__(self, *args, **kwds):
- 465        raise TypeError(f"Cannot instantiate {self!r}")
+ 464    def __or__(self, other):
+ 465        return Union[self, other]
  466
- 467    def __or__(self, other):
- 468        return Union[self, other]
+ 467    def __ror__(self, other):
+ 468        return Union[other, self]
  469
- 470    def __ror__(self, other):
- 471        return Union[other, self]
+ 470    def __instancecheck__(self, obj):
+ 471        raise TypeError(f"{self} cannot be used with isinstance()")
  472
- 473    def __instancecheck__(self, obj):
- 474        raise TypeError(f"{self} cannot be used with isinstance()")
+ 473    def __subclasscheck__(self, cls):
+ 474        raise TypeError(f"{self} cannot be used with issubclass()")
  475
- 476    def __subclasscheck__(self, cls):
- 477        raise TypeError(f"{self} cannot be used with issubclass()")
- 478
- 479    @_tp_cache
- 480    def __getitem__(self, parameters):
- 481        return self._getitem(self, parameters)
- 482
- 483
- 484class _LiteralSpecialForm(_SpecialForm, _root=True):
- 485    def __getitem__(self, parameters):
- 486        if not isinstance(parameters, tuple):
- 487            parameters = (parameters,)
- 488        return self._getitem(self, *parameters)
- 489
- 490
- 491class _AnyMeta(type):
- 492    def __instancecheck__(self, obj):
- 493        if self is Any:
- 494            raise TypeError("typing.Any cannot be used with isinstance()")
- 495        return super().__instancecheck__(obj)
- 496
- 497    def __repr__(self):
- 498        if self is Any:
- 499            return "typing.Any"
- 500        return super().__repr__()  # respect to subclasses
- 501
+ 476    @_tp_cache
+ 477    def __getitem__(self, parameters):
+ 478        return self._getitem(self, parameters)
+ 479
+ 480
+ 481class _LiteralSpecialForm(_SpecialForm, _root=True):
+ 482    def __getitem__(self, parameters):
+ 483        if not isinstance(parameters, tuple):
+ 484            parameters = (parameters,)
+ 485        return self._getitem(self, *parameters)
+ 486
+ 487
+ 488class _AnyMeta(type):
+ 489    def __instancecheck__(self, obj):
+ 490        if self is Any:
+ 491            raise TypeError("typing.Any cannot be used with isinstance()")
+ 492        return super().__instancecheck__(obj)
+ 493
+ 494    def __repr__(self):
+ 495        if self is Any:
+ 496            return "typing.Any"
+ 497        return super().__repr__()  # respect to subclasses
+ 498
+ 499
+ 500class Any(metaclass=_AnyMeta):
+ 501    """Special type indicating an unconstrained type.
  502
- 503class Any(metaclass=_AnyMeta):
- 504    """Special type indicating an unconstrained type.
- 505
- 506    - Any is compatible with every type.
- 507    - Any assumed to have all methods.
- 508    - All values assumed to be instances of Any.
- 509
- 510    Note that all the above statements are true from the point of view of
- 511    static type checkers. At runtime, Any should not be used with instance
- 512    checks.
- 513    """
- 514
- 515    def __new__(cls, *args, **kwargs):
- 516        if cls is Any:
- 517            raise TypeError("Any cannot be instantiated")
- 518        return super().__new__(cls, *args, **kwargs)
- 519
- 520
- 521@_SpecialForm
- 522def NoReturn(self, parameters):
- 523    """Special type indicating functions that never return.
- 524
- 525    Example::
- 526
- 527        from typing import NoReturn
+ 503    - Any is compatible with every type.
+ 504    - Any assumed to have all methods.
+ 505    - All values assumed to be instances of Any.
+ 506
+ 507    Note that all the above statements are true from the point of view of
+ 508    static type checkers. At runtime, Any should not be used with instance
+ 509    checks.
+ 510    """
+ 511
+ 512    def __new__(cls, *args, **kwargs):
+ 513        if cls is Any:
+ 514            raise TypeError("Any cannot be instantiated")
+ 515        return super().__new__(cls, *args, **kwargs)
+ 516
+ 517
+ 518@_SpecialForm
+ 519def NoReturn(self, parameters):
+ 520    """Special type indicating functions that never return.
+ 521
+ 522    Example::
+ 523
+ 524        from typing import NoReturn
+ 525
+ 526        def stop() -> NoReturn:
+ 527            raise Exception('no way')
  528
- 529        def stop() -> NoReturn:
- 530            raise Exception('no way')
- 531
- 532    NoReturn can also be used as a bottom type, a type that
- 533    has no values. Starting in Python 3.11, the Never type should
- 534    be used for this concept instead. Type checkers should treat the two
- 535    equivalently.
- 536    """
- 537    raise TypeError(f"{self} is not subscriptable")
- 538
- 539# This is semantically identical to NoReturn, but it is implemented
- 540# separately so that type checkers can distinguish between the two
- 541# if they want.
- 542@_SpecialForm
- 543def Never(self, parameters):
- 544    """The bottom type, a type that has no members.
+ 529    NoReturn can also be used as a bottom type, a type that
+ 530    has no values. Starting in Python 3.11, the Never type should
+ 531    be used for this concept instead. Type checkers should treat the two
+ 532    equivalently.
+ 533    """
+ 534    raise TypeError(f"{self} is not subscriptable")
+ 535
+ 536# This is semantically identical to NoReturn, but it is implemented
+ 537# separately so that type checkers can distinguish between the two
+ 538# if they want.
+ 539@_SpecialForm
+ 540def Never(self, parameters):
+ 541    """The bottom type, a type that has no members.
+ 542
+ 543    This can be used to define a function that should never be
+ 544    called, or a function that never returns::
  545
- 546    This can be used to define a function that should never be
- 547    called, or a function that never returns::
- 548
- 549        from typing import Never
+ 546        from typing import Never
+ 547
+ 548        def never_call_me(arg: Never) -> None:
+ 549            pass
  550
- 551        def never_call_me(arg: Never) -> None:
- 552            pass
- 553
- 554        def int_or_str(arg: int | str) -> None:
- 555            never_call_me(arg)  # type checker error
- 556            match arg:
- 557                case int():
- 558                    print("It's an int")
- 559                case str():
- 560                    print("It's a str")
- 561                case _:
- 562                    never_call_me(arg)  # OK, arg is of type Never
- 563    """
- 564    raise TypeError(f"{self} is not subscriptable")
- 565
- 566
- 567@_SpecialForm
- 568def Self(self, parameters):
- 569    """Used to spell the type of "self" in classes.
- 570
- 571    Example::
- 572
- 573        from typing import Self
- 574
- 575        class Foo:
- 576            def return_self(self) -> Self:
- 577                ...
- 578                return self
- 579
- 580    This is especially useful for:
- 581        - classmethods that are used as alternative constructors
- 582        - annotating an `__enter__` method which returns self
- 583    """
- 584    raise TypeError(f"{self} is not subscriptable")
- 585
- 586
- 587@_SpecialForm
- 588def LiteralString(self, parameters):
- 589    """Represents an arbitrary literal string.
- 590
- 591    Example::
- 592
- 593        from typing import LiteralString
+ 551        def int_or_str(arg: int | str) -> None:
+ 552            never_call_me(arg)  # type checker error
+ 553            match arg:
+ 554                case int():
+ 555                    print("It's an int")
+ 556                case str():
+ 557                    print("It's a str")
+ 558                case _:
+ 559                    never_call_me(arg)  # ok, arg is of type Never
+ 560    """
+ 561    raise TypeError(f"{self} is not subscriptable")
+ 562
+ 563
+ 564@_SpecialForm
+ 565def Self(self, parameters):
+ 566    """Used to spell the type of "self" in classes.
+ 567
+ 568    Example::
+ 569
+ 570        from typing import Self
+ 571
+ 572        class Foo:
+ 573            def return_self(self) -> Self:
+ 574                ...
+ 575                return self
+ 576
+ 577    This is especially useful for:
+ 578        - classmethods that are used as alternative constructors
+ 579        - annotating an `__enter__` method which returns self
+ 580    """
+ 581    raise TypeError(f"{self} is not subscriptable")
+ 582
+ 583
+ 584@_SpecialForm
+ 585def LiteralString(self, parameters):
+ 586    """Represents an arbitrary literal string.
+ 587
+ 588    Example::
+ 589
+ 590        from typing import LiteralString
+ 591
+ 592        def run_query(sql: LiteralString) -> ...
+ 593            ...
  594
- 595        def run_query(sql: LiteralString) -> None:
- 596            ...
- 597
- 598        def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
- 599            run_query("SELECT * FROM students")  # OK
- 600            run_query(literal_string)  # OK
- 601            run_query("SELECT * FROM " + literal_string)  # OK
- 602            run_query(arbitrary_string)  # type checker error
- 603            run_query(  # type checker error
- 604                f"SELECT * FROM students WHERE name = {arbitrary_string}"
- 605            )
- 606
- 607    Only string literals and other LiteralStrings are compatible
- 608    with LiteralString. This provides a tool to help prevent
- 609    security issues such as SQL injection.
- 610    """
- 611    raise TypeError(f"{self} is not subscriptable")
- 612
- 613
- 614@_SpecialForm
- 615def ClassVar(self, parameters):
- 616    """Special type construct to mark class variables.
- 617
- 618    An annotation wrapped in ClassVar indicates that a given
- 619    attribute is intended to be used as a class variable and
- 620    should not be set on instances of that class.
- 621
- 622    Usage::
- 623
- 624        class Starship:
- 625            stats: ClassVar[dict[str, int]] = {} # class variable
- 626            damage: int = 10                     # instance variable
- 627
- 628    ClassVar accepts only types and cannot be further subscribed.
- 629
- 630    Note that ClassVar is not a class itself, and should not
- 631    be used with isinstance() or issubclass().
- 632    """
- 633    item = _type_check(parameters, f'{self} accepts only single type.')
- 634    return _GenericAlias(self, (item,))
- 635
- 636@_SpecialForm
- 637def Final(self, parameters):
- 638    """Special typing construct to indicate final names to type checkers.
- 639
- 640    A final name cannot be re-assigned or overridden in a subclass.
+ 595        def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
+ 596            run_query("SELECT * FROM students")  # ok
+ 597            run_query(literal_string)  # ok
+ 598            run_query("SELECT * FROM " + literal_string)  # ok
+ 599            run_query(arbitrary_string)  # type checker error
+ 600            run_query(  # type checker error
+ 601                f"SELECT * FROM students WHERE name = {arbitrary_string}"
+ 602            )
+ 603
+ 604    Only string literals and other LiteralStrings are compatible
+ 605    with LiteralString. This provides a tool to help prevent
+ 606    security issues such as SQL injection.
+ 607    """
+ 608    raise TypeError(f"{self} is not subscriptable")
+ 609
+ 610
+ 611@_SpecialForm
+ 612def ClassVar(self, parameters):
+ 613    """Special type construct to mark class variables.
+ 614
+ 615    An annotation wrapped in ClassVar indicates that a given
+ 616    attribute is intended to be used as a class variable and
+ 617    should not be set on instances of that class. Usage::
+ 618
+ 619        class Starship:
+ 620            stats: ClassVar[Dict[str, int]] = {} # class variable
+ 621            damage: int = 10                     # instance variable
+ 622
+ 623    ClassVar accepts only types and cannot be further subscribed.
+ 624
+ 625    Note that ClassVar is not a class itself, and should not
+ 626    be used with isinstance() or issubclass().
+ 627    """
+ 628    item = _type_check(parameters, f'{self} accepts only single type.')
+ 629    return _GenericAlias(self, (item,))
+ 630
+ 631@_SpecialForm
+ 632def Final(self, parameters):
+ 633    """Special typing construct to indicate final names to type checkers.
+ 634
+ 635    A final name cannot be re-assigned or overridden in a subclass.
+ 636
+ 637    For example::
+ 638
+ 639        MAX_SIZE: Final = 9000
+ 640        MAX_SIZE += 1  # Error reported by type checker
  641
- 642    For example::
- 643
- 644        MAX_SIZE: Final = 9000
- 645        MAX_SIZE += 1  # Error reported by type checker
- 646
- 647        class Connection:
- 648            TIMEOUT: Final[int] = 10
- 649
- 650        class FastConnector(Connection):
- 651            TIMEOUT = 1  # Error reported by type checker
+ 642        class Connection:
+ 643            TIMEOUT: Final[int] = 10
+ 644
+ 645        class FastConnector(Connection):
+ 646            TIMEOUT = 1  # Error reported by type checker
+ 647
+ 648    There is no runtime checking of these properties.
+ 649    """
+ 650    item = _type_check(parameters, f'{self} accepts only single type.')
+ 651    return _GenericAlias(self, (item,))
  652
- 653    There is no runtime checking of these properties.
- 654    """
- 655    item = _type_check(parameters, f'{self} accepts only single type.')
- 656    return _GenericAlias(self, (item,))
- 657
- 658@_SpecialForm
- 659def Union(self, parameters):
- 660    """Union type; Union[X, Y] means either X or Y.
- 661
- 662    On Python 3.10 and higher, the | operator
- 663    can also be used to denote unions;
- 664    X | Y means the same thing to the type checker as Union[X, Y].
- 665
- 666    To define a union, use e.g. Union[int, str]. Details:
- 667    - The arguments must be types and there must be at least one.
- 668    - None as an argument is a special case and is replaced by
- 669      type(None).
- 670    - Unions of unions are flattened, e.g.::
- 671
- 672        assert Union[Union[int, str], float] == Union[int, str, float]
- 673
- 674    - Unions of a single argument vanish, e.g.::
- 675
- 676        assert Union[int] == int  # The constructor actually returns int
- 677
- 678    - Redundant arguments are skipped, e.g.::
- 679
- 680        assert Union[int, str, int] == Union[int, str]
- 681
- 682    - When comparing unions, the argument order is ignored, e.g.::
- 683
- 684        assert Union[int, str] == Union[str, int]
- 685
- 686    - You cannot subclass or instantiate a union.
- 687    - You can use Optional[X] as a shorthand for Union[X, None].
- 688    """
- 689    if parameters == ():
- 690        raise TypeError("Cannot take a Union of no types.")
- 691    if not isinstance(parameters, tuple):
- 692        parameters = (parameters,)
- 693    msg = "Union[arg, ...]: each arg must be a type."
- 694    parameters = tuple(_type_check(p, msg) for p in parameters)
- 695    parameters = _remove_dups_flatten(parameters)
- 696    if len(parameters) == 1:
- 697        return parameters[0]
- 698    if len(parameters) == 2 and type(None) in parameters:
- 699        return _UnionGenericAlias(self, parameters, name="Optional")
- 700    return _UnionGenericAlias(self, parameters)
- 701
- 702@_SpecialForm
- 703def Optional(self, parameters):
- 704    """Optional[X] is equivalent to Union[X, None]."""
- 705    arg = _type_check(parameters, f"{self} requires a single type.")
- 706    return Union[arg, type(None)]
+ 653@_SpecialForm
+ 654def Union(self, parameters):
+ 655    """Union type; Union[X, Y] means either X or Y.
+ 656
+ 657    On Python 3.10 and higher, the | operator
+ 658    can also be used to denote unions;
+ 659    X | Y means the same thing to the type checker as Union[X, Y].
+ 660
+ 661    To define a union, use e.g. Union[int, str]. Details:
+ 662    - The arguments must be types and there must be at least one.
+ 663    - None as an argument is a special case and is replaced by
+ 664      type(None).
+ 665    - Unions of unions are flattened, e.g.::
+ 666
+ 667        assert Union[Union[int, str], float] == Union[int, str, float]
+ 668
+ 669    - Unions of a single argument vanish, e.g.::
+ 670
+ 671        assert Union[int] == int  # The constructor actually returns int
+ 672
+ 673    - Redundant arguments are skipped, e.g.::
+ 674
+ 675        assert Union[int, str, int] == Union[int, str]
+ 676
+ 677    - When comparing unions, the argument order is ignored, e.g.::
+ 678
+ 679        assert Union[int, str] == Union[str, int]
+ 680
+ 681    - You cannot subclass or instantiate a union.
+ 682    - You can use Optional[X] as a shorthand for Union[X, None].
+ 683    """
+ 684    if parameters == ():
+ 685        raise TypeError("Cannot take a Union of no types.")
+ 686    if not isinstance(parameters, tuple):
+ 687        parameters = (parameters,)
+ 688    msg = "Union[arg, ...]: each arg must be a type."
+ 689    parameters = tuple(_type_check(p, msg) for p in parameters)
+ 690    parameters = _remove_dups_flatten(parameters)
+ 691    if len(parameters) == 1:
+ 692        return parameters[0]
+ 693    if len(parameters) == 2 and type(None) in parameters:
+ 694        return _UnionGenericAlias(self, parameters, name="Optional")
+ 695    return _UnionGenericAlias(self, parameters)
+ 696
+ 697@_SpecialForm
+ 698def Optional(self, parameters):
+ 699    """Optional[X] is equivalent to Union[X, None]."""
+ 700    arg = _type_check(parameters, f"{self} requires a single type.")
+ 701    return Union[arg, type(None)]
+ 702
+ 703@_LiteralSpecialForm
+ 704@_tp_cache(typed=True)
+ 705def Literal(self, *parameters):
+ 706    """Special typing form to define literal types (a.k.a. value types).
  707
- 708@_LiteralSpecialForm
- 709@_tp_cache(typed=True)
- 710def Literal(self, *parameters):
- 711    """Special typing form to define literal types (a.k.a. value types).
- 712
- 713    This form can be used to indicate to type checkers that the corresponding
- 714    variable or function parameter has a value equivalent to the provided
- 715    literal (or one of several literals)::
- 716
- 717        def validate_simple(data: Any) -> Literal[True]:  # always returns True
- 718            ...
- 719
- 720        MODE = Literal['r', 'rb', 'w', 'wb']
- 721        def open_helper(file: str, mode: MODE) -> str:
- 722            ...
- 723
- 724        open_helper('/some/path', 'r')  # Passes type check
- 725        open_helper('/other/path', 'typo')  # Error in type checker
- 726
- 727    Literal[...] cannot be subclassed. At runtime, an arbitrary value
- 728    is allowed as type argument to Literal[...], but type checkers may
- 729    impose restrictions.
- 730    """
- 731    # There is no '_type_check' call because arguments to Literal[...] are
- 732    # values, not types.
- 733    parameters = _flatten_literal_params(parameters)
+ 708    This form can be used to indicate to type checkers that the corresponding
+ 709    variable or function parameter has a value equivalent to the provided
+ 710    literal (or one of several literals)::
+ 711
+ 712        def validate_simple(data: Any) -> Literal[True]:  # always returns True
+ 713            ...
+ 714
+ 715        MODE = Literal['r', 'rb', 'w', 'wb']
+ 716        def open_helper(file: str, mode: MODE) -> str:
+ 717            ...
+ 718
+ 719        open_helper('/some/path', 'r')  # Passes type check
+ 720        open_helper('/other/path', 'typo')  # Error in type checker
+ 721
+ 722    Literal[...] cannot be subclassed. At runtime, an arbitrary value
+ 723    is allowed as type argument to Literal[...], but type checkers may
+ 724    impose restrictions.
+ 725    """
+ 726    # There is no '_type_check' call because arguments to Literal[...] are
+ 727    # values, not types.
+ 728    parameters = _flatten_literal_params(parameters)
+ 729
+ 730    try:
+ 731        parameters = tuple(p for p, _ in _deduplicate(list(_value_and_type_iter(parameters))))
+ 732    except TypeError:  # unhashable parameters
+ 733        pass
  734
- 735    try:
- 736        parameters = tuple(p for p, _ in _deduplicate(list(_value_and_type_iter(parameters))))
- 737    except TypeError:  # unhashable parameters
- 738        pass
- 739
- 740    return _LiteralGenericAlias(self, parameters)
+ 735    return _LiteralGenericAlias(self, parameters)
+ 736
+ 737
+ 738@_SpecialForm
+ 739def TypeAlias(self, parameters):
+ 740    """Special form for marking type aliases.
  741
- 742
- 743@_SpecialForm
- 744def TypeAlias(self, parameters):
- 745    """Special form for marking type aliases.
- 746
- 747    Use TypeAlias to indicate that an assignment should
- 748    be recognized as a proper type alias definition by type
- 749    checkers.
- 750
- 751    For example::
+ 742    Use TypeAlias to indicate that an assignment should
+ 743    be recognized as a proper type alias definition by type
+ 744    checkers. For example::
+ 745
+ 746        Predicate: TypeAlias = Callable[..., bool]
+ 747
+ 748    It's invalid when used anywhere except as in the example above.
+ 749    """
+ 750    raise TypeError(f"{self} is not subscriptable")
+ 751
  752
- 753        Predicate: TypeAlias = Callable[..., bool]
- 754
- 755    It's invalid when used anywhere except as in the example above.
- 756    """
- 757    raise TypeError(f"{self} is not subscriptable")
- 758
- 759
- 760@_SpecialForm
- 761def Concatenate(self, parameters):
- 762    """Special form for annotating higher-order functions.
- 763
- 764    ``Concatenate`` can be used in conjunction with ``ParamSpec`` and
- 765    ``Callable`` to represent a higher-order function which adds, removes or
- 766    transforms the parameters of a callable.
- 767
- 768    For example::
- 769
- 770        Callable[Concatenate[int, P], int]
- 771
- 772    See PEP 612 for detailed information.
- 773    """
- 774    if parameters == ():
- 775        raise TypeError("Cannot take a Concatenate of no types.")
- 776    if not isinstance(parameters, tuple):
- 777        parameters = (parameters,)
- 778    if not (parameters[-1] is ... or isinstance(parameters[-1], ParamSpec)):
- 779        raise TypeError("The last parameter to Concatenate should be a "
- 780                        "ParamSpec variable or ellipsis.")
- 781    msg = "Concatenate[arg, ...]: each arg must be a type."
- 782    parameters = (*(_type_check(p, msg) for p in parameters[:-1]), parameters[-1])
- 783    return _ConcatenateGenericAlias(self, parameters,
- 784                                    _paramspec_tvars=True)
- 785
- 786
- 787@_SpecialForm
- 788def TypeGuard(self, parameters):
- 789    """Special typing construct for marking user-defined type guard functions.
- 790
- 791    ``TypeGuard`` can be used to annotate the return type of a user-defined
- 792    type guard function.  ``TypeGuard`` only accepts a single type argument.
- 793    At runtime, functions marked this way should return a boolean.
- 794
- 795    ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static
- 796    type checkers to determine a more precise type of an expression within a
- 797    program's code flow.  Usually type narrowing is done by analyzing
- 798    conditional code flow and applying the narrowing to a block of code.  The
- 799    conditional expression here is sometimes referred to as a "type guard".
+ 753@_SpecialForm
+ 754def Concatenate(self, parameters):
+ 755    """Special form for annotating higher-order functions.
+ 756
+ 757    ``Concatenate`` can be sed in conjunction with ``ParamSpec`` and
+ 758    ``Callable`` to represent a higher order function which adds, removes or
+ 759    transforms the parameters of a callable.
+ 760
+ 761    For example::
+ 762
+ 763        Callable[Concatenate[int, P], int]
+ 764
+ 765    See PEP 612 for detailed information.
+ 766    """
+ 767    if parameters == ():
+ 768        raise TypeError("Cannot take a Concatenate of no types.")
+ 769    if not isinstance(parameters, tuple):
+ 770        parameters = (parameters,)
+ 771    if not (parameters[-1] is ... or isinstance(parameters[-1], ParamSpec)):
+ 772        raise TypeError("The last parameter to Concatenate should be a "
+ 773                        "ParamSpec variable or ellipsis.")
+ 774    msg = "Concatenate[arg, ...]: each arg must be a type."
+ 775    parameters = (*(_type_check(p, msg) for p in parameters[:-1]), parameters[-1])
+ 776    return _ConcatenateGenericAlias(self, parameters,
+ 777                                    _paramspec_tvars=True)
+ 778
+ 779
+ 780@_SpecialForm
+ 781def TypeGuard(self, parameters):
+ 782    """Special typing construct for marking user-defined type guard functions.
+ 783
+ 784    ``TypeGuard`` can be used to annotate the return type of a user-defined
+ 785    type guard function.  ``TypeGuard`` only accepts a single type argument.
+ 786    At runtime, functions marked this way should return a boolean.
+ 787
+ 788    ``TypeGuard`` aims to benefit *type narrowing* -- a technique used by static
+ 789    type checkers to determine a more precise type of an expression within a
+ 790    program's code flow.  Usually type narrowing is done by analyzing
+ 791    conditional code flow and applying the narrowing to a block of code.  The
+ 792    conditional expression here is sometimes referred to as a "type guard".
+ 793
+ 794    Sometimes it would be convenient to use a user-defined boolean function
+ 795    as a type guard.  Such a function should use ``TypeGuard[...]`` as its
+ 796    return type to alert static type checkers to this intention.
+ 797
+ 798    Using  ``-> TypeGuard`` tells the static type checker that for a given
+ 799    function:
  800
- 801    Sometimes it would be convenient to use a user-defined boolean function
- 802    as a type guard.  Such a function should use ``TypeGuard[...]`` as its
- 803    return type to alert static type checkers to this intention.
+ 801    1. The return value is a boolean.
+ 802    2. If the return value is ``True``, the type of its argument
+ 803       is the type inside ``TypeGuard``.
  804
- 805    Using  ``-> TypeGuard`` tells the static type checker that for a given
- 806    function:
- 807
- 808    1. The return value is a boolean.
- 809    2. If the return value is ``True``, the type of its argument
- 810       is the type inside ``TypeGuard``.
- 811
- 812       For example::
- 813
- 814           def is_str(val: Union[str, float]):
- 815               # "isinstance" type guard
- 816               if isinstance(val, str):
- 817                   # Type of ``val`` is narrowed to ``str``
- 818                   ...
- 819               else:
- 820                   # Else, type of ``val`` is narrowed to ``float``.
- 821                   ...
+ 805       For example::
+ 806
+ 807           def is_str(val: Union[str, float]):
+ 808               # "isinstance" type guard
+ 809               if isinstance(val, str):
+ 810                   # Type of ``val`` is narrowed to ``str``
+ 811                   ...
+ 812               else:
+ 813                   # Else, type of ``val`` is narrowed to ``float``.
+ 814                   ...
+ 815
+ 816    Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower
+ 817    form of ``TypeA`` (it can even be a wider form) and this may lead to
+ 818    type-unsafe results.  The main reason is to allow for things like
+ 819    narrowing ``List[object]`` to ``List[str]`` even though the latter is not
+ 820    a subtype of the former, since ``List`` is invariant.  The responsibility of
+ 821    writing type-safe type guards is left to the user.
  822
- 823    Strict type narrowing is not enforced -- ``TypeB`` need not be a narrower
- 824    form of ``TypeA`` (it can even be a wider form) and this may lead to
- 825    type-unsafe results.  The main reason is to allow for things like
- 826    narrowing ``List[object]`` to ``List[str]`` even though the latter is not
- 827    a subtype of the former, since ``List`` is invariant.  The responsibility of
- 828    writing type-safe type guards is left to the user.
+ 823    ``TypeGuard`` also works with type variables.  For more information, see
+ 824    PEP 647 (User-Defined Type Guards).
+ 825    """
+ 826    item = _type_check(parameters, f'{self} accepts only single type.')
+ 827    return _GenericAlias(self, (item,))
+ 828
  829
- 830    ``TypeGuard`` also works with type variables.  For more information, see
- 831    PEP 647 (User-Defined Type Guards).
- 832    """
- 833    item = _type_check(parameters, f'{self} accepts only single type.')
- 834    return _GenericAlias(self, (item,))
- 835
- 836
- 837class ForwardRef(_Final, _root=True):
- 838    """Internal wrapper to hold a forward reference."""
- 839
- 840    __slots__ = ('__forward_arg__', '__forward_code__',
- 841                 '__forward_evaluated__', '__forward_value__',
- 842                 '__forward_is_argument__', '__forward_is_class__',
- 843                 '__forward_module__')
- 844
- 845    def __init__(self, arg, is_argument=True, module=None, *, is_class=False):
- 846        if not isinstance(arg, str):
- 847            raise TypeError(f"Forward reference must be a string -- got {arg!r}")
- 848
- 849        # If we do `def f(*args: *Ts)`, then we'll have `arg = '*Ts'`.
- 850        # Unfortunately, this isn't a valid expression on its own, so we
- 851        # do the unpacking manually.
- 852        if arg[0] == '*':
- 853            arg_to_compile = f'({arg},)[0]'  # E.g. (*Ts,)[0] or (*tuple[int, int],)[0]
- 854        else:
- 855            arg_to_compile = arg
- 856        try:
- 857            code = compile(arg_to_compile, '<string>', 'eval')
- 858        except SyntaxError:
- 859            raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}")
- 860
- 861        self.__forward_arg__ = arg
- 862        self.__forward_code__ = code
- 863        self.__forward_evaluated__ = False
- 864        self.__forward_value__ = None
- 865        self.__forward_is_argument__ = is_argument
- 866        self.__forward_is_class__ = is_class
- 867        self.__forward_module__ = module
- 868
- 869    def _evaluate(self, globalns, localns, recursive_guard):
- 870        if self.__forward_arg__ in recursive_guard:
- 871            return self
- 872        if not self.__forward_evaluated__ or localns is not globalns:
- 873            if globalns is None and localns is None:
- 874                globalns = localns = {}
- 875            elif globalns is None:
- 876                globalns = localns
- 877            elif localns is None:
- 878                localns = globalns
- 879            if self.__forward_module__ is not None:
- 880                globalns = getattr(
- 881                    sys.modules.get(self.__forward_module__, None), '__dict__', globalns
- 882                )
- 883            type_ = _type_check(
- 884                eval(self.__forward_code__, globalns, localns),
- 885                "Forward references must evaluate to types.",
- 886                is_argument=self.__forward_is_argument__,
- 887                allow_special_forms=self.__forward_is_class__,
- 888            )
- 889            self.__forward_value__ = _eval_type(
- 890                type_, globalns, localns, recursive_guard | {self.__forward_arg__}
- 891            )
- 892            self.__forward_evaluated__ = True
- 893        return self.__forward_value__
- 894
- 895    def __eq__(self, other):
- 896        if not isinstance(other, ForwardRef):
- 897            return NotImplemented
- 898        if self.__forward_evaluated__ and other.__forward_evaluated__:
- 899            return (self.__forward_arg__ == other.__forward_arg__ and
- 900                    self.__forward_value__ == other.__forward_value__)
- 901        return (self.__forward_arg__ == other.__forward_arg__ and
- 902                self.__forward_module__ == other.__forward_module__)
- 903
- 904    def __hash__(self):
- 905        return hash((self.__forward_arg__, self.__forward_module__))
- 906
- 907    def __or__(self, other):
- 908        return Union[self, other]
- 909
- 910    def __ror__(self, other):
- 911        return Union[other, self]
+ 830class ForwardRef(_Final, _root=True):
+ 831    """Internal wrapper to hold a forward reference."""
+ 832
+ 833    __slots__ = ('__forward_arg__', '__forward_code__',
+ 834                 '__forward_evaluated__', '__forward_value__',
+ 835                 '__forward_is_argument__', '__forward_is_class__',
+ 836                 '__forward_module__')
+ 837
+ 838    def __init__(self, arg, is_argument=True, module=None, *, is_class=False):
+ 839        if not isinstance(arg, str):
+ 840            raise TypeError(f"Forward reference must be a string -- got {arg!r}")
+ 841
+ 842        # If we do `def f(*args: *Ts)`, then we'll have `arg = '*Ts'`.
+ 843        # Unfortunately, this isn't a valid expression on its own, so we
+ 844        # do the unpacking manually.
+ 845        if arg[0] == '*':
+ 846            arg_to_compile = f'({arg},)[0]'  # E.g. (*Ts,)[0] or (*tuple[int, int],)[0]
+ 847        else:
+ 848            arg_to_compile = arg
+ 849        try:
+ 850            code = compile(arg_to_compile, '<string>', 'eval')
+ 851        except SyntaxError:
+ 852            raise SyntaxError(f"Forward reference must be an expression -- got {arg!r}")
+ 853
+ 854        self.__forward_arg__ = arg
+ 855        self.__forward_code__ = code
+ 856        self.__forward_evaluated__ = False
+ 857        self.__forward_value__ = None
+ 858        self.__forward_is_argument__ = is_argument
+ 859        self.__forward_is_class__ = is_class
+ 860        self.__forward_module__ = module
+ 861
+ 862    def _evaluate(self, globalns, localns, recursive_guard):
+ 863        if self.__forward_arg__ in recursive_guard:
+ 864            return self
+ 865        if not self.__forward_evaluated__ or localns is not globalns:
+ 866            if globalns is None and localns is None:
+ 867                globalns = localns = {}
+ 868            elif globalns is None:
+ 869                globalns = localns
+ 870            elif localns is None:
+ 871                localns = globalns
+ 872            if self.__forward_module__ is not None:
+ 873                globalns = getattr(
+ 874                    sys.modules.get(self.__forward_module__, None), '__dict__', globalns
+ 875                )
+ 876            type_ = _type_check(
+ 877                eval(self.__forward_code__, globalns, localns),
+ 878                "Forward references must evaluate to types.",
+ 879                is_argument=self.__forward_is_argument__,
+ 880                allow_special_forms=self.__forward_is_class__,
+ 881            )
+ 882            self.__forward_value__ = _eval_type(
+ 883                type_, globalns, localns, recursive_guard | {self.__forward_arg__}
+ 884            )
+ 885            self.__forward_evaluated__ = True
+ 886        return self.__forward_value__
+ 887
+ 888    def __eq__(self, other):
+ 889        if not isinstance(other, ForwardRef):
+ 890            return NotImplemented
+ 891        if self.__forward_evaluated__ and other.__forward_evaluated__:
+ 892            return (self.__forward_arg__ == other.__forward_arg__ and
+ 893                    self.__forward_value__ == other.__forward_value__)
+ 894        return (self.__forward_arg__ == other.__forward_arg__ and
+ 895                self.__forward_module__ == other.__forward_module__)
+ 896
+ 897    def __hash__(self):
+ 898        return hash((self.__forward_arg__, self.__forward_module__))
+ 899
+ 900    def __or__(self, other):
+ 901        return Union[self, other]
+ 902
+ 903    def __ror__(self, other):
+ 904        return Union[other, self]
+ 905
+ 906    def __repr__(self):
+ 907        if self.__forward_module__ is None:
+ 908            module_repr = ''
+ 909        else:
+ 910            module_repr = f', module={self.__forward_module__!r}'
+ 911        return f'ForwardRef({self.__forward_arg__!r}{module_repr})'
  912
- 913    def __repr__(self):
- 914        if self.__forward_module__ is None:
- 915            module_repr = ''
- 916        else:
- 917            module_repr = f', module={self.__forward_module__!r}'
- 918        return f'ForwardRef({self.__forward_arg__!r}{module_repr})'
- 919
- 920
- 921def _is_unpacked_typevartuple(x: Any) -> bool:
- 922    return ((not isinstance(x, type)) and
- 923            getattr(x, '__typing_is_unpacked_typevartuple__', False))
- 924
+ 913
+ 914def _is_unpacked_typevartuple(x: Any) -> bool:
+ 915    return ((not isinstance(x, type)) and
+ 916            getattr(x, '__typing_is_unpacked_typevartuple__', False))
+ 917
+ 918
+ 919def _is_typevar_like(x: Any) -> bool:
+ 920    return isinstance(x, (TypeVar, ParamSpec)) or _is_unpacked_typevartuple(x)
+ 921
+ 922
+ 923class _PickleUsingNameMixin:
+ 924    """Mixin enabling pickling based on self.__name__."""
  925
- 926def _is_typevar_like(x: Any) -> bool:
- 927    return isinstance(x, (TypeVar, ParamSpec)) or _is_unpacked_typevartuple(x)
+ 926    def __reduce__(self):
+ 927        return self.__name__
  928
  929
- 930class _PickleUsingNameMixin:
- 931    """Mixin enabling pickling based on self.__name__."""
+ 930class _BoundVarianceMixin:
+ 931    """Mixin giving __init__ bound and variance arguments.
  932
- 933    def __reduce__(self):
- 934        return self.__name__
- 935
- 936
- 937class _BoundVarianceMixin:
- 938    """Mixin giving __init__ bound and variance arguments.
- 939
- 940    This is used by TypeVar and ParamSpec, which both employ the notions of
- 941    a type 'bound' (restricting type arguments to be a subtype of some
- 942    specified type) and type 'variance' (determining subtype relations between
- 943    generic types).
- 944    """
- 945    def __init__(self, bound, covariant, contravariant):
- 946        """Used to setup TypeVars and ParamSpec's bound, covariant and
- 947        contravariant attributes.
- 948        """
- 949        if covariant and contravariant:
- 950            raise ValueError("Bivariant types are not supported.")
- 951        self.__covariant__ = bool(covariant)
- 952        self.__contravariant__ = bool(contravariant)
- 953        if bound:
- 954            self.__bound__ = _type_check(bound, "Bound must be a type.")
- 955        else:
- 956            self.__bound__ = None
- 957
- 958    def __or__(self, right):
- 959        return Union[self, right]
- 960
- 961    def __ror__(self, left):
- 962        return Union[left, self]
- 963
- 964    def __repr__(self):
- 965        if self.__covariant__:
- 966            prefix = '+'
- 967        elif self.__contravariant__:
- 968            prefix = '-'
- 969        else:
- 970            prefix = '~'
- 971        return prefix + self.__name__
+ 933    This is used by TypeVar and ParamSpec, which both employ the notions of
+ 934    a type 'bound' (restricting type arguments to be a subtype of some
+ 935    specified type) and type 'variance' (determining subtype relations between
+ 936    generic types).
+ 937    """
+ 938    def __init__(self, bound, covariant, contravariant):
+ 939        """Used to setup TypeVars and ParamSpec's bound, covariant and
+ 940        contravariant attributes.
+ 941        """
+ 942        if covariant and contravariant:
+ 943            raise ValueError("Bivariant types are not supported.")
+ 944        self.__covariant__ = bool(covariant)
+ 945        self.__contravariant__ = bool(contravariant)
+ 946        if bound:
+ 947            self.__bound__ = _type_check(bound, "Bound must be a type.")
+ 948        else:
+ 949            self.__bound__ = None
+ 950
+ 951    def __or__(self, right):
+ 952        return Union[self, right]
+ 953
+ 954    def __ror__(self, left):
+ 955        return Union[left, self]
+ 956
+ 957    def __repr__(self):
+ 958        if self.__covariant__:
+ 959            prefix = '+'
+ 960        elif self.__contravariant__:
+ 961            prefix = '-'
+ 962        else:
+ 963            prefix = '~'
+ 964        return prefix + self.__name__
+ 965
+ 966
+ 967class TypeVar(_Final, _Immutable, _BoundVarianceMixin, _PickleUsingNameMixin,
+ 968              _root=True):
+ 969    """Type variable.
+ 970
+ 971    Usage::
  972
- 973
- 974class TypeVar(_Final, _Immutable, _BoundVarianceMixin, _PickleUsingNameMixin,
- 975              _root=True):
- 976    """Type variable.
- 977
- 978    Usage::
- 979
- 980      T = TypeVar('T')  # Can be anything
- 981      A = TypeVar('A', str, bytes)  # Must be str or bytes
- 982
- 983    Type variables exist primarily for the benefit of static type
- 984    checkers.  They serve as the parameters for generic types as well
- 985    as for generic function definitions.  See class Generic for more
- 986    information on generic types.  Generic functions work as follows:
- 987
- 988      def repeat(x: T, n: int) -> List[T]:
- 989          '''Return a list containing n references to x.'''
- 990          return [x]*n
- 991
- 992      def longest(x: A, y: A) -> A:
- 993          '''Return the longest of two strings.'''
- 994          return x if len(x) >= len(y) else y
+ 973      T = TypeVar('T')  # Can be anything
+ 974      A = TypeVar('A', str, bytes)  # Must be str or bytes
+ 975
+ 976    Type variables exist primarily for the benefit of static type
+ 977    checkers.  They serve as the parameters for generic types as well
+ 978    as for generic function definitions.  See class Generic for more
+ 979    information on generic types.  Generic functions work as follows:
+ 980
+ 981      def repeat(x: T, n: int) -> List[T]:
+ 982          '''Return a list containing n references to x.'''
+ 983          return [x]*n
+ 984
+ 985      def longest(x: A, y: A) -> A:
+ 986          '''Return the longest of two strings.'''
+ 987          return x if len(x) >= len(y) else y
+ 988
+ 989    The latter example's signature is essentially the overloading
+ 990    of (str, str) -> str and (bytes, bytes) -> bytes.  Also note
+ 991    that if the arguments are instances of some subclass of str,
+ 992    the return type is still plain str.
+ 993
+ 994    At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
  995
- 996    The latter example's signature is essentially the overloading
- 997    of (str, str) -> str and (bytes, bytes) -> bytes.  Also note
- 998    that if the arguments are instances of some subclass of str,
- 999    the return type is still plain str.
+ 996    Type variables defined with covariant=True or contravariant=True
+ 997    can be used to declare covariant or contravariant generic types.
+ 998    See PEP 484 for more details. By default generic types are invariant
+ 999    in all type variables.
 1000
-1001    At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
+1001    Type variables can be introspected. e.g.:
 1002
-1003    Type variables defined with covariant=True or contravariant=True
-1004    can be used to declare covariant or contravariant generic types.
-1005    See PEP 484 for more details. By default generic types are invariant
-1006    in all type variables.
-1007
-1008    Type variables can be introspected. e.g.:
-1009
-1010      T.__name__ == 'T'
-1011      T.__constraints__ == ()
-1012      T.__covariant__ == False
-1013      T.__contravariant__ = False
-1014      A.__constraints__ == (str, bytes)
-1015
-1016    Note that only type variables defined in global scope can be pickled.
-1017    """
-1018
-1019    def __init__(self, name, *constraints, bound=None,
-1020                 covariant=False, contravariant=False):
-1021        self.__name__ = name
-1022        super().__init__(bound, covariant, contravariant)
-1023        if constraints and bound is not None:
-1024            raise TypeError("Constraints cannot be combined with bound=...")
-1025        if constraints and len(constraints) == 1:
-1026            raise TypeError("A single constraint is not allowed")
-1027        msg = "TypeVar(name, constraint, ...): constraints must be types."
-1028        self.__constraints__ = tuple(_type_check(t, msg) for t in constraints)
-1029        def_mod = _caller()
-1030        if def_mod != 'typing':
-1031            self.__module__ = def_mod
-1032
-1033    def __typing_subst__(self, arg):
-1034        msg = "Parameters to generic types must be types."
-1035        arg = _type_check(arg, msg, is_argument=True)
-1036        if ((isinstance(arg, _GenericAlias) and arg.__origin__ is Unpack) or
-1037            (isinstance(arg, GenericAlias) and getattr(arg, '__unpacked__', False))):
-1038            raise TypeError(f"{arg} is not valid as type argument")
-1039        return arg
-1040
+1003      T.__name__ == 'T'
+1004      T.__constraints__ == ()
+1005      T.__covariant__ == False
+1006      T.__contravariant__ = False
+1007      A.__constraints__ == (str, bytes)
+1008
+1009    Note that only type variables defined in global scope can be pickled.
+1010    """
+1011
+1012    def __init__(self, name, *constraints, bound=None,
+1013                 covariant=False, contravariant=False):
+1014        self.__name__ = name
+1015        super().__init__(bound, covariant, contravariant)
+1016        if constraints and bound is not None:
+1017            raise TypeError("Constraints cannot be combined with bound=...")
+1018        if constraints and len(constraints) == 1:
+1019            raise TypeError("A single constraint is not allowed")
+1020        msg = "TypeVar(name, constraint, ...): constraints must be types."
+1021        self.__constraints__ = tuple(_type_check(t, msg) for t in constraints)
+1022        def_mod = _caller()
+1023        if def_mod != 'typing':
+1024            self.__module__ = def_mod
+1025
+1026    def __typing_subst__(self, arg):
+1027        msg = "Parameters to generic types must be types."
+1028        arg = _type_check(arg, msg, is_argument=True)
+1029        if ((isinstance(arg, _GenericAlias) and arg.__origin__ is Unpack) or
+1030            (isinstance(arg, GenericAlias) and getattr(arg, '__unpacked__', False))):
+1031            raise TypeError(f"{arg} is not valid as type argument")
+1032        return arg
+1033
+1034
+1035class TypeVarTuple(_Final, _Immutable, _PickleUsingNameMixin, _root=True):
+1036    """Type variable tuple.
+1037
+1038    Usage:
+1039
+1040      Ts = TypeVarTuple('Ts')  # Can be given any name
 1041
-1042class TypeVarTuple(_Final, _Immutable, _PickleUsingNameMixin, _root=True):
-1043    """Type variable tuple.
-1044
-1045    Usage:
-1046
-1047      Ts = TypeVarTuple('Ts')  # Can be given any name
-1048
-1049    Just as a TypeVar (type variable) is a placeholder for a single type,
-1050    a TypeVarTuple is a placeholder for an *arbitrary* number of types. For
-1051    example, if we define a generic class using a TypeVarTuple:
-1052
-1053      class C(Generic[*Ts]): ...
+1042    Just as a TypeVar (type variable) is a placeholder for a single type,
+1043    a TypeVarTuple is a placeholder for an *arbitrary* number of types. For
+1044    example, if we define a generic class using a TypeVarTuple:
+1045
+1046      class C(Generic[*Ts]): ...
+1047
+1048    Then we can parameterize that class with an arbitrary number of type
+1049    arguments:
+1050
+1051      C[int]       # Fine
+1052      C[int, str]  # Also fine
+1053      C[()]        # Even this is fine
 1054
-1055    Then we can parameterize that class with an arbitrary number of type
-1056    arguments:
-1057
-1058      C[int]       # Fine
-1059      C[int, str]  # Also fine
-1060      C[()]        # Even this is fine
-1061
-1062    For more details, see PEP 646.
-1063
-1064    Note that only TypeVarTuples defined in global scope can be pickled.
-1065    """
-1066
-1067    def __init__(self, name):
-1068        self.__name__ = name
-1069
-1070        # Used for pickling.
-1071        def_mod = _caller()
-1072        if def_mod != 'typing':
-1073            self.__module__ = def_mod
-1074
-1075    def __iter__(self):
-1076        yield Unpack[self]
-1077
-1078    def __repr__(self):
-1079        return self.__name__
-1080
-1081    def __typing_subst__(self, arg):
-1082        raise TypeError("Substitution of bare TypeVarTuple is not supported")
+1055    For more details, see PEP 646.
+1056
+1057    Note that only TypeVarTuples defined in global scope can be pickled.
+1058    """
+1059
+1060    def __init__(self, name):
+1061        self.__name__ = name
+1062
+1063        # Used for pickling.
+1064        def_mod = _caller()
+1065        if def_mod != 'typing':
+1066            self.__module__ = def_mod
+1067
+1068    def __iter__(self):
+1069        yield Unpack[self]
+1070
+1071    def __repr__(self):
+1072        return self.__name__
+1073
+1074    def __typing_subst__(self, arg):
+1075        raise TypeError("Substitution of bare TypeVarTuple is not supported")
+1076
+1077    def __typing_prepare_subst__(self, alias, args):
+1078        params = alias.__parameters__
+1079        typevartuple_index = params.index(self)
+1080        for param in params[typevartuple_index + 1:]:
+1081            if isinstance(param, TypeVarTuple):
+1082                raise TypeError(f"More than one TypeVarTuple parameter in {alias}")
 1083
-1084    def __typing_prepare_subst__(self, alias, args):
-1085        params = alias.__parameters__
-1086        typevartuple_index = params.index(self)
-1087        for param in params[typevartuple_index + 1:]:
-1088            if isinstance(param, TypeVarTuple):
-1089                raise TypeError(f"More than one TypeVarTuple parameter in {alias}")
-1090
-1091        alen = len(args)
-1092        plen = len(params)
-1093        left = typevartuple_index
-1094        right = plen - typevartuple_index - 1
-1095        var_tuple_index = None
-1096        fillarg = None
-1097        for k, arg in enumerate(args):
-1098            if not isinstance(arg, type):
-1099                subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
-1100                if subargs and len(subargs) == 2 and subargs[-1] is ...:
-1101                    if var_tuple_index is not None:
-1102                        raise TypeError("More than one unpacked arbitrary-length tuple argument")
-1103                    var_tuple_index = k
-1104                    fillarg = subargs[0]
-1105        if var_tuple_index is not None:
-1106            left = min(left, var_tuple_index)
-1107            right = min(right, alen - var_tuple_index - 1)
-1108        elif left + right > alen:
-1109            raise TypeError(f"Too few arguments for {alias};"
-1110                            f" actual {alen}, expected at least {plen-1}")
-1111
-1112        return (
-1113            *args[:left],
-1114            *([fillarg]*(typevartuple_index - left)),
-1115            tuple(args[left: alen - right]),
-1116            *([fillarg]*(plen - right - left - typevartuple_index - 1)),
-1117            *args[alen - right:],
-1118        )
-1119
+1084        alen = len(args)
+1085        plen = len(params)
+1086        left = typevartuple_index
+1087        right = plen - typevartuple_index - 1
+1088        var_tuple_index = None
+1089        fillarg = None
+1090        for k, arg in enumerate(args):
+1091            if not isinstance(arg, type):
+1092                subargs = getattr(arg, '__typing_unpacked_tuple_args__', None)
+1093                if subargs and len(subargs) == 2 and subargs[-1] is ...:
+1094                    if var_tuple_index is not None:
+1095                        raise TypeError("More than one unpacked arbitrary-length tuple argument")
+1096                    var_tuple_index = k
+1097                    fillarg = subargs[0]
+1098        if var_tuple_index is not None:
+1099            left = min(left, var_tuple_index)
+1100            right = min(right, alen - var_tuple_index - 1)
+1101        elif left + right > alen:
+1102            raise TypeError(f"Too few arguments for {alias};"
+1103                            f" actual {alen}, expected at least {plen-1}")
+1104
+1105        return (
+1106            *args[:left],
+1107            *([fillarg]*(typevartuple_index - left)),
+1108            tuple(args[left: alen - right]),
+1109            *([fillarg]*(plen - right - left - typevartuple_index - 1)),
+1110            *args[alen - right:],
+1111        )
+1112
+1113
+1114class ParamSpecArgs(_Final, _Immutable, _root=True):
+1115    """The args for a ParamSpec object.
+1116
+1117    Given a ParamSpec object P, P.args is an instance of ParamSpecArgs.
+1118
+1119    ParamSpecArgs objects have a reference back to their ParamSpec:
 1120
-1121class ParamSpecArgs(_Final, _Immutable, _root=True):
-1122    """The args for a ParamSpec object.
-1123
-1124    Given a ParamSpec object P, P.args is an instance of ParamSpecArgs.
-1125
-1126    ParamSpecArgs objects have a reference back to their ParamSpec:
-1127
-1128       P.args.__origin__ is P
-1129
-1130    This type is meant for runtime introspection and has no special meaning to
-1131    static type checkers.
-1132    """
-1133    def __init__(self, origin):
-1134        self.__origin__ = origin
-1135
-1136    def __repr__(self):
-1137        return f"{self.__origin__.__name__}.args"
-1138
-1139    def __eq__(self, other):
-1140        if not isinstance(other, ParamSpecArgs):
-1141            return NotImplemented
-1142        return self.__origin__ == other.__origin__
-1143
+1121       P.args.__origin__ is P
+1122
+1123    This type is meant for runtime introspection and has no special meaning to
+1124    static type checkers.
+1125    """
+1126    def __init__(self, origin):
+1127        self.__origin__ = origin
+1128
+1129    def __repr__(self):
+1130        return f"{self.__origin__.__name__}.args"
+1131
+1132    def __eq__(self, other):
+1133        if not isinstance(other, ParamSpecArgs):
+1134            return NotImplemented
+1135        return self.__origin__ == other.__origin__
+1136
+1137
+1138class ParamSpecKwargs(_Final, _Immutable, _root=True):
+1139    """The kwargs for a ParamSpec object.
+1140
+1141    Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs.
+1142
+1143    ParamSpecKwargs objects have a reference back to their ParamSpec:
 1144
-1145class ParamSpecKwargs(_Final, _Immutable, _root=True):
-1146    """The kwargs for a ParamSpec object.
-1147
-1148    Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs.
-1149
-1150    ParamSpecKwargs objects have a reference back to their ParamSpec:
-1151
-1152       P.kwargs.__origin__ is P
-1153
-1154    This type is meant for runtime introspection and has no special meaning to
-1155    static type checkers.
-1156    """
-1157    def __init__(self, origin):
-1158        self.__origin__ = origin
-1159
-1160    def __repr__(self):
-1161        return f"{self.__origin__.__name__}.kwargs"
-1162
-1163    def __eq__(self, other):
-1164        if not isinstance(other, ParamSpecKwargs):
-1165            return NotImplemented
-1166        return self.__origin__ == other.__origin__
+1145       P.kwargs.__origin__ is P
+1146
+1147    This type is meant for runtime introspection and has no special meaning to
+1148    static type checkers.
+1149    """
+1150    def __init__(self, origin):
+1151        self.__origin__ = origin
+1152
+1153    def __repr__(self):
+1154        return f"{self.__origin__.__name__}.kwargs"
+1155
+1156    def __eq__(self, other):
+1157        if not isinstance(other, ParamSpecKwargs):
+1158            return NotImplemented
+1159        return self.__origin__ == other.__origin__
+1160
+1161
+1162class ParamSpec(_Final, _Immutable, _BoundVarianceMixin, _PickleUsingNameMixin,
+1163                _root=True):
+1164    """Parameter specification variable.
+1165
+1166    Usage::
 1167
-1168
-1169class ParamSpec(_Final, _Immutable, _BoundVarianceMixin, _PickleUsingNameMixin,
-1170                _root=True):
-1171    """Parameter specification variable.
-1172
-1173    Usage::
-1174
-1175       P = ParamSpec('P')
-1176
-1177    Parameter specification variables exist primarily for the benefit of static
-1178    type checkers.  They are used to forward the parameter types of one
-1179    callable to another callable, a pattern commonly found in higher order
-1180    functions and decorators.  They are only valid when used in ``Concatenate``,
-1181    or as the first argument to ``Callable``, or as parameters for user-defined
-1182    Generics.  See class Generic for more information on generic types.  An
-1183    example for annotating a decorator::
-1184
-1185       T = TypeVar('T')
-1186       P = ParamSpec('P')
+1168       P = ParamSpec('P')
+1169
+1170    Parameter specification variables exist primarily for the benefit of static
+1171    type checkers.  They are used to forward the parameter types of one
+1172    callable to another callable, a pattern commonly found in higher order
+1173    functions and decorators.  They are only valid when used in ``Concatenate``,
+1174    or as the first argument to ``Callable``, or as parameters for user-defined
+1175    Generics.  See class Generic for more information on generic types.  An
+1176    example for annotating a decorator::
+1177
+1178       T = TypeVar('T')
+1179       P = ParamSpec('P')
+1180
+1181       def add_logging(f: Callable[P, T]) -> Callable[P, T]:
+1182           '''A type-safe decorator to add logging to a function.'''
+1183           def inner(*args: P.args, **kwargs: P.kwargs) -> T:
+1184               logging.info(f'{f.__name__} was called')
+1185               return f(*args, **kwargs)
+1186           return inner
 1187
-1188       def add_logging(f: Callable[P, T]) -> Callable[P, T]:
-1189           '''A type-safe decorator to add logging to a function.'''
-1190           def inner(*args: P.args, **kwargs: P.kwargs) -> T:
-1191               logging.info(f'{f.__name__} was called')
-1192               return f(*args, **kwargs)
-1193           return inner
+1188       @add_logging
+1189       def add_two(x: float, y: float) -> float:
+1190           '''Add two numbers together.'''
+1191           return x + y
+1192
+1193    Parameter specification variables can be introspected. e.g.:
 1194
-1195       @add_logging
-1196       def add_two(x: float, y: float) -> float:
-1197           '''Add two numbers together.'''
-1198           return x + y
-1199
-1200    Parameter specification variables can be introspected. e.g.:
-1201
-1202       P.__name__ == 'P'
-1203
-1204    Note that only parameter specification variables defined in global scope can
-1205    be pickled.
-1206    """
-1207
-1208    @property
-1209    def args(self):
-1210        return ParamSpecArgs(self)
-1211
-1212    @property
-1213    def kwargs(self):
-1214        return ParamSpecKwargs(self)
+1195       P.__name__ == 'P'
+1196
+1197    Note that only parameter specification variables defined in global scope can
+1198    be pickled.
+1199    """
+1200
+1201    @property
+1202    def args(self):
+1203        return ParamSpecArgs(self)
+1204
+1205    @property
+1206    def kwargs(self):
+1207        return ParamSpecKwargs(self)
+1208
+1209    def __init__(self, name, *, bound=None, covariant=False, contravariant=False):
+1210        self.__name__ = name
+1211        super().__init__(bound, covariant, contravariant)
+1212        def_mod = _caller()
+1213        if def_mod != 'typing':
+1214            self.__module__ = def_mod
 1215
-1216    def __init__(self, name, *, bound=None, covariant=False, contravariant=False):
-1217        self.__name__ = name
-1218        super().__init__(bound, covariant, contravariant)
-1219        def_mod = _caller()
-1220        if def_mod != 'typing':
-1221            self.__module__ = def_mod
-1222
-1223    def __typing_subst__(self, arg):
-1224        if isinstance(arg, (list, tuple)):
-1225            arg = tuple(_type_check(a, "Expected a type.") for a in arg)
-1226        elif not _is_param_expr(arg):
-1227            raise TypeError(f"Expected a list of types, an ellipsis, "
-1228                            f"ParamSpec, or Concatenate. Got {arg}")
-1229        return arg
-1230
-1231    def __typing_prepare_subst__(self, alias, args):
-1232        params = alias.__parameters__
-1233        i = params.index(self)
-1234        if i >= len(args):
-1235            raise TypeError(f"Too few arguments for {alias}")
-1236        # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612.
-1237        if len(params) == 1 and not _is_param_expr(args[0]):
-1238            assert i == 0
-1239            args = (args,)
-1240        # Convert lists to tuples to help other libraries cache the results.
-1241        elif isinstance(args[i], list):
-1242            args = (*args[:i], tuple(args[i]), *args[i+1:])
-1243        return args
-1244
-1245def _is_dunder(attr):
-1246    return attr.startswith('__') and attr.endswith('__')
-1247
-1248class _BaseGenericAlias(_Final, _root=True):
-1249    """The central part of the internal API.
+1216    def __typing_subst__(self, arg):
+1217        if isinstance(arg, (list, tuple)):
+1218            arg = tuple(_type_check(a, "Expected a type.") for a in arg)
+1219        elif not _is_param_expr(arg):
+1220            raise TypeError(f"Expected a list of types, an ellipsis, "
+1221                            f"ParamSpec, or Concatenate. Got {arg}")
+1222        return arg
+1223
+1224    def __typing_prepare_subst__(self, alias, args):
+1225        params = alias.__parameters__
+1226        i = params.index(self)
+1227        if i >= len(args):
+1228            raise TypeError(f"Too few arguments for {alias}")
+1229        # Special case where Z[[int, str, bool]] == Z[int, str, bool] in PEP 612.
+1230        if len(params) == 1 and not _is_param_expr(args[0]):
+1231            assert i == 0
+1232            args = (args,)
+1233        # Convert lists to tuples to help other libraries cache the results.
+1234        elif isinstance(args[i], list):
+1235            args = (*args[:i], tuple(args[i]), *args[i+1:])
+1236        return args
+1237
+1238def _is_dunder(attr):
+1239    return attr.startswith('__') and attr.endswith('__')
+1240
+1241class _BaseGenericAlias(_Final, _root=True):
+1242    """The central part of the internal API.
+1243
+1244    This represents a generic version of type 'origin' with type arguments 'params'.
+1245    There are two kind of these aliases: user defined and special. The special ones
+1246    are wrappers around builtin collections and ABCs in collections.abc. These must
+1247    have 'name' always set. If 'inst' is False, then the alias can't be instantiated;
+1248    this is used by e.g. typing.List and typing.Dict.
+1249    """
 1250
-1251    This represents a generic version of type 'origin' with type arguments 'params'.
-1252    There are two kind of these aliases: user defined and special. The special ones
-1253    are wrappers around builtin collections and ABCs in collections.abc. These must
-1254    have 'name' always set. If 'inst' is False, then the alias can't be instantiated;
-1255    this is used by e.g. typing.List and typing.Dict.
-1256    """
-1257
-1258    def __init__(self, origin, *, inst=True, name=None):
-1259        self._inst = inst
-1260        self._name = name
-1261        self.__origin__ = origin
-1262        self.__slots__ = None  # This is not documented.
-1263
-1264    def __call__(self, *args, **kwargs):
-1265        if not self._inst:
-1266            raise TypeError(f"Type {self._name} cannot be instantiated; "
-1267                            f"use {self.__origin__.__name__}() instead")
-1268        result = self.__origin__(*args, **kwargs)
-1269        try:
-1270            result.__orig_class__ = self
-1271        except AttributeError:
-1272            pass
-1273        return result
-1274
-1275    def __mro_entries__(self, bases):
-1276        res = []
-1277        if self.__origin__ not in bases:
-1278            res.append(self.__origin__)
-1279        i = bases.index(self)
-1280        for b in bases[i+1:]:
-1281            if isinstance(b, _BaseGenericAlias) or issubclass(b, Generic):
-1282                break
-1283        else:
-1284            res.append(Generic)
-1285        return tuple(res)
-1286
-1287    def __getattr__(self, attr):
-1288        if attr in {'__name__', '__qualname__'}:
-1289            return self._name or self.__origin__.__name__
-1290
-1291        # We are careful for copy and pickle.
-1292        # Also for simplicity we don't relay any dunder names
-1293        if '__origin__' in self.__dict__ and not _is_dunder(attr):
-1294            return getattr(self.__origin__, attr)
-1295        raise AttributeError(attr)
+1251    def __init__(self, origin, *, inst=True, name=None):
+1252        self._inst = inst
+1253        self._name = name
+1254        self.__origin__ = origin
+1255        self.__slots__ = None  # This is not documented.
+1256
+1257    def __call__(self, *args, **kwargs):
+1258        if not self._inst:
+1259            raise TypeError(f"Type {self._name} cannot be instantiated; "
+1260                            f"use {self.__origin__.__name__}() instead")
+1261        result = self.__origin__(*args, **kwargs)
+1262        try:
+1263            result.__orig_class__ = self
+1264        except AttributeError:
+1265            pass
+1266        return result
+1267
+1268    def __mro_entries__(self, bases):
+1269        res = []
+1270        if self.__origin__ not in bases:
+1271            res.append(self.__origin__)
+1272        i = bases.index(self)
+1273        for b in bases[i+1:]:
+1274            if isinstance(b, _BaseGenericAlias) or issubclass(b, Generic):
+1275                break
+1276        else:
+1277            res.append(Generic)
+1278        return tuple(res)
+1279
+1280    def __getattr__(self, attr):
+1281        if attr in {'__name__', '__qualname__'}:
+1282            return self._name or self.__origin__.__name__
+1283
+1284        # We are careful for copy and pickle.
+1285        # Also for simplicity we don't relay any dunder names
+1286        if '__origin__' in self.__dict__ and not _is_dunder(attr):
+1287            return getattr(self.__origin__, attr)
+1288        raise AttributeError(attr)
+1289
+1290    def __setattr__(self, attr, val):
+1291        if _is_dunder(attr) or attr in {'_name', '_inst', '_nparams',
+1292                                        '_paramspec_tvars'}:
+1293            super().__setattr__(attr, val)
+1294        else:
+1295            setattr(self.__origin__, attr, val)
 1296
-1297    def __setattr__(self, attr, val):
-1298        if _is_dunder(attr) or attr in {'_name', '_inst', '_nparams',
-1299                                        '_paramspec_tvars'}:
-1300            super().__setattr__(attr, val)
-1301        else:
-1302            setattr(self.__origin__, attr, val)
+1297    def __instancecheck__(self, obj):
+1298        return self.__subclasscheck__(type(obj))
+1299
+1300    def __subclasscheck__(self, cls):
+1301        raise TypeError("Subscripted generics cannot be used with"
+1302                        " class and instance checks")
 1303
-1304    def __instancecheck__(self, obj):
-1305        return self.__subclasscheck__(type(obj))
-1306
-1307    def __subclasscheck__(self, cls):
-1308        raise TypeError("Subscripted generics cannot be used with"
-1309                        " class and instance checks")
-1310
-1311    def __dir__(self):
-1312        return list(set(super().__dir__()
-1313                + [attr for attr in dir(self.__origin__) if not _is_dunder(attr)]))
-1314
-1315
-1316# Special typing constructs Union, Optional, Generic, Callable and Tuple
-1317# use three special attributes for internal bookkeeping of generic types:
-1318# * __parameters__ is a tuple of unique free type parameters of a generic
-1319#   type, for example, Dict[T, T].__parameters__ == (T,);
-1320# * __origin__ keeps a reference to a type that was subscripted,
-1321#   e.g., Union[T, int].__origin__ == Union, or the non-generic version of
-1322#   the type.
-1323# * __args__ is a tuple of all arguments used in subscripting,
-1324#   e.g., Dict[T, int].__args__ == (T, int).
-1325
-1326
-1327class _GenericAlias(_BaseGenericAlias, _root=True):
-1328    # The type of parameterized generics.
-1329    #
-1330    # That is, for example, `type(List[int])` is `_GenericAlias`.
-1331    #
-1332    # Objects which are instances of this class include:
-1333    # * Parameterized container types, e.g. `Tuple[int]`, `List[int]`.
-1334    #  * Note that native container types, e.g. `tuple`, `list`, use
-1335    #    `types.GenericAlias` instead.
-1336    # * Parameterized classes:
-1337    #     T = TypeVar('T')
-1338    #     class C(Generic[T]): pass
-1339    #     # C[int] is a _GenericAlias
-1340    # * `Callable` aliases, generic `Callable` aliases, and
-1341    #   parameterized `Callable` aliases:
-1342    #     T = TypeVar('T')
-1343    #     # _CallableGenericAlias inherits from _GenericAlias.
-1344    #     A = Callable[[], None]  # _CallableGenericAlias
-1345    #     B = Callable[[T], None]  # _CallableGenericAlias
-1346    #     C = B[int]  # _CallableGenericAlias
-1347    # * Parameterized `Final`, `ClassVar` and `TypeGuard`:
-1348    #     # All _GenericAlias
-1349    #     Final[int]
-1350    #     ClassVar[float]
-1351    #     TypeVar[bool]
-1352
-1353    def __init__(self, origin, args, *, inst=True, name=None,
-1354                 _paramspec_tvars=False):
-1355        super().__init__(origin, inst=inst, name=name)
-1356        if not isinstance(args, tuple):
-1357            args = (args,)
-1358        self.__args__ = tuple(... if a is _TypingEllipsis else
-1359                              a for a in args)
-1360        self.__parameters__ = _collect_parameters(args)
-1361        self._paramspec_tvars = _paramspec_tvars
-1362        if not name:
-1363            self.__module__ = origin.__module__
-1364
-1365    def __eq__(self, other):
-1366        if not isinstance(other, _GenericAlias):
-1367            return NotImplemented
-1368        return (self.__origin__ == other.__origin__
-1369                and self.__args__ == other.__args__)
-1370
-1371    def __hash__(self):
-1372        return hash((self.__origin__, self.__args__))
-1373
-1374    def __or__(self, right):
-1375        return Union[self, right]
-1376
-1377    def __ror__(self, left):
-1378        return Union[left, self]
-1379
-1380    @_tp_cache
-1381    def __getitem__(self, args):
-1382        # Parameterizes an already-parameterized object.
-1383        #
-1384        # For example, we arrive here doing something like:
-1385        #   T1 = TypeVar('T1')
-1386        #   T2 = TypeVar('T2')
-1387        #   T3 = TypeVar('T3')
-1388        #   class A(Generic[T1]): pass
-1389        #   B = A[T2]  # B is a _GenericAlias
-1390        #   C = B[T3]  # Invokes _GenericAlias.__getitem__
-1391        #
-1392        # We also arrive here when parameterizing a generic `Callable` alias:
-1393        #   T = TypeVar('T')
-1394        #   C = Callable[[T], None]
-1395        #   C[int]  # Invokes _GenericAlias.__getitem__
-1396
-1397        if self.__origin__ in (Generic, Protocol):
-1398            # Can't subscript Generic[...] or Protocol[...].
-1399            raise TypeError(f"Cannot subscript already-subscripted {self}")
-1400        if not self.__parameters__:
-1401            raise TypeError(f"{self} is not a generic class")
-1402
-1403        # Preprocess `args`.
-1404        if not isinstance(args, tuple):
-1405            args = (args,)
-1406        args = tuple(_type_convert(p) for p in args)
-1407        args = _unpack_args(args)
-1408        new_args = self._determine_new_args(args)
-1409        r = self.copy_with(new_args)
-1410        return r
-1411
-1412    def _determine_new_args(self, args):
-1413        # Determines new __args__ for __getitem__.
-1414        #
-1415        # For example, suppose we had:
-1416        #   T1 = TypeVar('T1')
-1417        #   T2 = TypeVar('T2')
-1418        #   class A(Generic[T1, T2]): pass
-1419        #   T3 = TypeVar('T3')
-1420        #   B = A[int, T3]
-1421        #   C = B[str]
-1422        # `B.__args__` is `(int, T3)`, so `C.__args__` should be `(int, str)`.
-1423        # Unfortunately, this is harder than it looks, because if `T3` is
-1424        # anything more exotic than a plain `TypeVar`, we need to consider
-1425        # edge cases.
-1426
-1427        params = self.__parameters__
-1428        # In the example above, this would be {T3: str}
-1429        for param in params:
-1430            prepare = getattr(param, '__typing_prepare_subst__', None)
-1431            if prepare is not None:
-1432                args = prepare(self, args)
-1433        alen = len(args)
-1434        plen = len(params)
-1435        if alen != plen:
-1436            raise TypeError(f"Too {'many' if alen > plen else 'few'} arguments for {self};"
-1437                            f" actual {alen}, expected {plen}")
-1438        new_arg_by_param = dict(zip(params, args))
-1439        return tuple(self._make_substitution(self.__args__, new_arg_by_param))
-1440
-1441    def _make_substitution(self, args, new_arg_by_param):
-1442        """Create a list of new type arguments."""
-1443        new_args = []
-1444        for old_arg in args:
-1445            if isinstance(old_arg, type):
-1446                new_args.append(old_arg)
-1447                continue
-1448
-1449            substfunc = getattr(old_arg, '__typing_subst__', None)
-1450            if substfunc:
-1451                new_arg = substfunc(new_arg_by_param[old_arg])
-1452            else:
-1453                subparams = getattr(old_arg, '__parameters__', ())
-1454                if not subparams:
-1455                    new_arg = old_arg
-1456                else:
-1457                    subargs = []
-1458                    for x in subparams:
-1459                        if isinstance(x, TypeVarTuple):
-1460                            subargs.extend(new_arg_by_param[x])
-1461                        else:
-1462                            subargs.append(new_arg_by_param[x])
-1463                    new_arg = old_arg[tuple(subargs)]
-1464
-1465            if self.__origin__ == collections.abc.Callable and isinstance(new_arg, tuple):
-1466                # Consider the following `Callable`.
-1467                #   C = Callable[[int], str]
-1468                # Here, `C.__args__` should be (int, str) - NOT ([int], str).
-1469                # That means that if we had something like...
-1470                #   P = ParamSpec('P')
-1471                #   T = TypeVar('T')
-1472                #   C = Callable[P, T]
-1473                #   D = C[[int, str], float]
-1474                # ...we need to be careful; `new_args` should end up as
-1475                # `(int, str, float)` rather than `([int, str], float)`.
-1476                new_args.extend(new_arg)
-1477            elif _is_unpacked_typevartuple(old_arg):
-1478                # Consider the following `_GenericAlias`, `B`:
-1479                #   class A(Generic[*Ts]): ...
-1480                #   B = A[T, *Ts]
-1481                # If we then do:
-1482                #   B[float, int, str]
-1483                # The `new_arg` corresponding to `T` will be `float`, and the
-1484                # `new_arg` corresponding to `*Ts` will be `(int, str)`. We
-1485                # should join all these types together in a flat list
-1486                # `(float, int, str)` - so again, we should `extend`.
-1487                new_args.extend(new_arg)
-1488            elif isinstance(old_arg, tuple):
-1489                # Corner case:
-1490                #    P = ParamSpec('P')
-1491                #    T = TypeVar('T')
-1492                #    class Base(Generic[P]): ...
-1493                # Can be substituted like this:
-1494                #    X = Base[[int, T]]
-1495                # In this case, `old_arg` will be a tuple:
-1496                new_args.append(
-1497                    tuple(self._make_substitution(old_arg, new_arg_by_param)),
-1498                )
-1499            else:
-1500                new_args.append(new_arg)
-1501        return new_args
-1502
-1503    def copy_with(self, args):
-1504        return self.__class__(self.__origin__, args, name=self._name, inst=self._inst,
-1505                              _paramspec_tvars=self._paramspec_tvars)
-1506
-1507    def __repr__(self):
-1508        if self._name:
-1509            name = 'typing.' + self._name
-1510        else:
-1511            name = _type_repr(self.__origin__)
-1512        if self.__args__:
-1513            args = ", ".join([_type_repr(a) for a in self.__args__])
-1514        else:
-1515            # To ensure the repr is eval-able.
-1516            args = "()"
-1517        return f'{name}[{args}]'
-1518
-1519    def __reduce__(self):
-1520        if self._name:
-1521            origin = globals()[self._name]
-1522        else:
-1523            origin = self.__origin__
-1524        args = tuple(self.__args__)
-1525        if len(args) == 1 and not isinstance(args[0], tuple):
-1526            args, = args
-1527        return operator.getitem, (origin, args)
-1528
-1529    def __mro_entries__(self, bases):
-1530        if isinstance(self.__origin__, _SpecialForm):
-1531            raise TypeError(f"Cannot subclass {self!r}")
-1532
-1533        if self._name:  # generic version of an ABC or built-in class
-1534            return super().__mro_entries__(bases)
-1535        if self.__origin__ is Generic:
-1536            if Protocol in bases:
-1537                return ()
-1538            i = bases.index(self)
-1539            for b in bases[i+1:]:
-1540                if isinstance(b, _BaseGenericAlias) and b is not self:
-1541                    return ()
-1542        return (self.__origin__,)
-1543
-1544    def __iter__(self):
-1545        yield Unpack[self]
-1546
-1547
-1548# _nparams is the number of accepted parameters, e.g. 0 for Hashable,
-1549# 1 for List and 2 for Dict.  It may be -1 if variable number of
-1550# parameters are accepted (needs custom __getitem__).
-1551
-1552class _SpecialGenericAlias(_NotIterable, _BaseGenericAlias, _root=True):
-1553    def __init__(self, origin, nparams, *, inst=True, name=None):
-1554        if name is None:
-1555            name = origin.__name__
-1556        super().__init__(origin, inst=inst, name=name)
-1557        self._nparams = nparams
-1558        if origin.__module__ == 'builtins':
-1559            self.__doc__ = f'A generic version of {origin.__qualname__}.'
-1560        else:
-1561            self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}.'
-1562
-1563    @_tp_cache
-1564    def __getitem__(self, params):
-1565        if not isinstance(params, tuple):
-1566            params = (params,)
-1567        msg = "Parameters to generic types must be types."
-1568        params = tuple(_type_check(p, msg) for p in params)
-1569        _check_generic(self, params, self._nparams)
-1570        return self.copy_with(params)
+1304    def __dir__(self):
+1305        return list(set(super().__dir__()
+1306                + [attr for attr in dir(self.__origin__) if not _is_dunder(attr)]))
+1307
+1308
+1309# Special typing constructs Union, Optional, Generic, Callable and Tuple
+1310# use three special attributes for internal bookkeeping of generic types:
+1311# * __parameters__ is a tuple of unique free type parameters of a generic
+1312#   type, for example, Dict[T, T].__parameters__ == (T,);
+1313# * __origin__ keeps a reference to a type that was subscripted,
+1314#   e.g., Union[T, int].__origin__ == Union, or the non-generic version of
+1315#   the type.
+1316# * __args__ is a tuple of all arguments used in subscripting,
+1317#   e.g., Dict[T, int].__args__ == (T, int).
+1318
+1319
+1320class _GenericAlias(_BaseGenericAlias, _root=True):
+1321    # The type of parameterized generics.
+1322    #
+1323    # That is, for example, `type(List[int])` is `_GenericAlias`.
+1324    #
+1325    # Objects which are instances of this class include:
+1326    # * Parameterized container types, e.g. `Tuple[int]`, `List[int]`.
+1327    #  * Note that native container types, e.g. `tuple`, `list`, use
+1328    #    `types.GenericAlias` instead.
+1329    # * Parameterized classes:
+1330    #     T = TypeVar('T')
+1331    #     class C(Generic[T]): pass
+1332    #     # C[int] is a _GenericAlias
+1333    # * `Callable` aliases, generic `Callable` aliases, and
+1334    #   parameterized `Callable` aliases:
+1335    #     T = TypeVar('T')
+1336    #     # _CallableGenericAlias inherits from _GenericAlias.
+1337    #     A = Callable[[], None]  # _CallableGenericAlias
+1338    #     B = Callable[[T], None]  # _CallableGenericAlias
+1339    #     C = B[int]  # _CallableGenericAlias
+1340    # * Parameterized `Final`, `ClassVar` and `TypeGuard`:
+1341    #     # All _GenericAlias
+1342    #     Final[int]
+1343    #     ClassVar[float]
+1344    #     TypeVar[bool]
+1345
+1346    def __init__(self, origin, args, *, inst=True, name=None,
+1347                 _paramspec_tvars=False):
+1348        super().__init__(origin, inst=inst, name=name)
+1349        if not isinstance(args, tuple):
+1350            args = (args,)
+1351        self.__args__ = tuple(... if a is _TypingEllipsis else
+1352                              a for a in args)
+1353        self.__parameters__ = _collect_parameters(args)
+1354        self._paramspec_tvars = _paramspec_tvars
+1355        if not name:
+1356            self.__module__ = origin.__module__
+1357
+1358    def __eq__(self, other):
+1359        if not isinstance(other, _GenericAlias):
+1360            return NotImplemented
+1361        return (self.__origin__ == other.__origin__
+1362                and self.__args__ == other.__args__)
+1363
+1364    def __hash__(self):
+1365        return hash((self.__origin__, self.__args__))
+1366
+1367    def __or__(self, right):
+1368        return Union[self, right]
+1369
+1370    def __ror__(self, left):
+1371        return Union[left, self]
+1372
+1373    @_tp_cache
+1374    def __getitem__(self, args):
+1375        # Parameterizes an already-parameterized object.
+1376        #
+1377        # For example, we arrive here doing something like:
+1378        #   T1 = TypeVar('T1')
+1379        #   T2 = TypeVar('T2')
+1380        #   T3 = TypeVar('T3')
+1381        #   class A(Generic[T1]): pass
+1382        #   B = A[T2]  # B is a _GenericAlias
+1383        #   C = B[T3]  # Invokes _GenericAlias.__getitem__
+1384        #
+1385        # We also arrive here when parameterizing a generic `Callable` alias:
+1386        #   T = TypeVar('T')
+1387        #   C = Callable[[T], None]
+1388        #   C[int]  # Invokes _GenericAlias.__getitem__
+1389
+1390        if self.__origin__ in (Generic, Protocol):
+1391            # Can't subscript Generic[...] or Protocol[...].
+1392            raise TypeError(f"Cannot subscript already-subscripted {self}")
+1393        if not self.__parameters__:
+1394            raise TypeError(f"{self} is not a generic class")
+1395
+1396        # Preprocess `args`.
+1397        if not isinstance(args, tuple):
+1398            args = (args,)
+1399        args = tuple(_type_convert(p) for p in args)
+1400        args = _unpack_args(args)
+1401        new_args = self._determine_new_args(args)
+1402        r = self.copy_with(new_args)
+1403        return r
+1404
+1405    def _determine_new_args(self, args):
+1406        # Determines new __args__ for __getitem__.
+1407        #
+1408        # For example, suppose we had:
+1409        #   T1 = TypeVar('T1')
+1410        #   T2 = TypeVar('T2')
+1411        #   class A(Generic[T1, T2]): pass
+1412        #   T3 = TypeVar('T3')
+1413        #   B = A[int, T3]
+1414        #   C = B[str]
+1415        # `B.__args__` is `(int, T3)`, so `C.__args__` should be `(int, str)`.
+1416        # Unfortunately, this is harder than it looks, because if `T3` is
+1417        # anything more exotic than a plain `TypeVar`, we need to consider
+1418        # edge cases.
+1419
+1420        params = self.__parameters__
+1421        # In the example above, this would be {T3: str}
+1422        for param in params:
+1423            prepare = getattr(param, '__typing_prepare_subst__', None)
+1424            if prepare is not None:
+1425                args = prepare(self, args)
+1426        alen = len(args)
+1427        plen = len(params)
+1428        if alen != plen:
+1429            raise TypeError(f"Too {'many' if alen > plen else 'few'} arguments for {self};"
+1430                            f" actual {alen}, expected {plen}")
+1431        new_arg_by_param = dict(zip(params, args))
+1432        return tuple(self._make_substitution(self.__args__, new_arg_by_param))
+1433
+1434    def _make_substitution(self, args, new_arg_by_param):
+1435        """Create a list of new type arguments."""
+1436        new_args = []
+1437        for old_arg in args:
+1438            if isinstance(old_arg, type):
+1439                new_args.append(old_arg)
+1440                continue
+1441
+1442            substfunc = getattr(old_arg, '__typing_subst__', None)
+1443            if substfunc:
+1444                new_arg = substfunc(new_arg_by_param[old_arg])
+1445            else:
+1446                subparams = getattr(old_arg, '__parameters__', ())
+1447                if not subparams:
+1448                    new_arg = old_arg
+1449                else:
+1450                    subargs = []
+1451                    for x in subparams:
+1452                        if isinstance(x, TypeVarTuple):
+1453                            subargs.extend(new_arg_by_param[x])
+1454                        else:
+1455                            subargs.append(new_arg_by_param[x])
+1456                    new_arg = old_arg[tuple(subargs)]
+1457
+1458            if self.__origin__ == collections.abc.Callable and isinstance(new_arg, tuple):
+1459                # Consider the following `Callable`.
+1460                #   C = Callable[[int], str]
+1461                # Here, `C.__args__` should be (int, str) - NOT ([int], str).
+1462                # That means that if we had something like...
+1463                #   P = ParamSpec('P')
+1464                #   T = TypeVar('T')
+1465                #   C = Callable[P, T]
+1466                #   D = C[[int, str], float]
+1467                # ...we need to be careful; `new_args` should end up as
+1468                # `(int, str, float)` rather than `([int, str], float)`.
+1469                new_args.extend(new_arg)
+1470            elif _is_unpacked_typevartuple(old_arg):
+1471                # Consider the following `_GenericAlias`, `B`:
+1472                #   class A(Generic[*Ts]): ...
+1473                #   B = A[T, *Ts]
+1474                # If we then do:
+1475                #   B[float, int, str]
+1476                # The `new_arg` corresponding to `T` will be `float`, and the
+1477                # `new_arg` corresponding to `*Ts` will be `(int, str)`. We
+1478                # should join all these types together in a flat list
+1479                # `(float, int, str)` - so again, we should `extend`.
+1480                new_args.extend(new_arg)
+1481            elif isinstance(old_arg, tuple):
+1482                # Corner case:
+1483                #    P = ParamSpec('P')
+1484                #    T = TypeVar('T')
+1485                #    class Base(Generic[P]): ...
+1486                # Can be substituted like this:
+1487                #    X = Base[[int, T]]
+1488                # In this case, `old_arg` will be a tuple:
+1489                new_args.append(
+1490                    tuple(self._make_substitution(old_arg, new_arg_by_param)),
+1491                )
+1492            else:
+1493                new_args.append(new_arg)
+1494        return new_args
+1495
+1496    def copy_with(self, args):
+1497        return self.__class__(self.__origin__, args, name=self._name, inst=self._inst,
+1498                              _paramspec_tvars=self._paramspec_tvars)
+1499
+1500    def __repr__(self):
+1501        if self._name:
+1502            name = 'typing.' + self._name
+1503        else:
+1504            name = _type_repr(self.__origin__)
+1505        if self.__args__:
+1506            args = ", ".join([_type_repr(a) for a in self.__args__])
+1507        else:
+1508            # To ensure the repr is eval-able.
+1509            args = "()"
+1510        return f'{name}[{args}]'
+1511
+1512    def __reduce__(self):
+1513        if self._name:
+1514            origin = globals()[self._name]
+1515        else:
+1516            origin = self.__origin__
+1517        args = tuple(self.__args__)
+1518        if len(args) == 1 and not isinstance(args[0], tuple):
+1519            args, = args
+1520        return operator.getitem, (origin, args)
+1521
+1522    def __mro_entries__(self, bases):
+1523        if isinstance(self.__origin__, _SpecialForm):
+1524            raise TypeError(f"Cannot subclass {self!r}")
+1525
+1526        if self._name:  # generic version of an ABC or built-in class
+1527            return super().__mro_entries__(bases)
+1528        if self.__origin__ is Generic:
+1529            if Protocol in bases:
+1530                return ()
+1531            i = bases.index(self)
+1532            for b in bases[i+1:]:
+1533                if isinstance(b, _BaseGenericAlias) and b is not self:
+1534                    return ()
+1535        return (self.__origin__,)
+1536
+1537    def __iter__(self):
+1538        yield Unpack[self]
+1539
+1540
+1541# _nparams is the number of accepted parameters, e.g. 0 for Hashable,
+1542# 1 for List and 2 for Dict.  It may be -1 if variable number of
+1543# parameters are accepted (needs custom __getitem__).
+1544
+1545class _SpecialGenericAlias(_NotIterable, _BaseGenericAlias, _root=True):
+1546    def __init__(self, origin, nparams, *, inst=True, name=None):
+1547        if name is None:
+1548            name = origin.__name__
+1549        super().__init__(origin, inst=inst, name=name)
+1550        self._nparams = nparams
+1551        if origin.__module__ == 'builtins':
+1552            self.__doc__ = f'A generic version of {origin.__qualname__}.'
+1553        else:
+1554            self.__doc__ = f'A generic version of {origin.__module__}.{origin.__qualname__}.'
+1555
+1556    @_tp_cache
+1557    def __getitem__(self, params):
+1558        if not isinstance(params, tuple):
+1559            params = (params,)
+1560        msg = "Parameters to generic types must be types."
+1561        params = tuple(_type_check(p, msg) for p in params)
+1562        _check_generic(self, params, self._nparams)
+1563        return self.copy_with(params)
+1564
+1565    def copy_with(self, params):
+1566        return _GenericAlias(self.__origin__, params,
+1567                             name=self._name, inst=self._inst)
+1568
+1569    def __repr__(self):
+1570        return 'typing.' + self._name
 1571
-1572    def copy_with(self, params):
-1573        return _GenericAlias(self.__origin__, params,
-1574                             name=self._name, inst=self._inst)
-1575
-1576    def __repr__(self):
-1577        return 'typing.' + self._name
+1572    def __subclasscheck__(self, cls):
+1573        if isinstance(cls, _SpecialGenericAlias):
+1574            return issubclass(cls.__origin__, self.__origin__)
+1575        if not isinstance(cls, _GenericAlias):
+1576            return issubclass(cls, self.__origin__)
+1577        return super().__subclasscheck__(cls)
 1578
-1579    def __subclasscheck__(self, cls):
-1580        if isinstance(cls, _SpecialGenericAlias):
-1581            return issubclass(cls.__origin__, self.__origin__)
-1582        if not isinstance(cls, _GenericAlias):
-1583            return issubclass(cls, self.__origin__)
-1584        return super().__subclasscheck__(cls)
-1585
-1586    def __reduce__(self):
-1587        return self._name
-1588
-1589    def __or__(self, right):
-1590        return Union[self, right]
-1591
-1592    def __ror__(self, left):
-1593        return Union[left, self]
-1594
-1595class _CallableGenericAlias(_NotIterable, _GenericAlias, _root=True):
-1596    def __repr__(self):
-1597        assert self._name == 'Callable'
-1598        args = self.__args__
-1599        if len(args) == 2 and _is_param_expr(args[0]):
-1600            return super().__repr__()
-1601        return (f'typing.Callable'
-1602                f'[[{", ".join([_type_repr(a) for a in args[:-1]])}], '
-1603                f'{_type_repr(args[-1])}]')
+1579    def __reduce__(self):
+1580        return self._name
+1581
+1582    def __or__(self, right):
+1583        return Union[self, right]
+1584
+1585    def __ror__(self, left):
+1586        return Union[left, self]
+1587
+1588class _CallableGenericAlias(_NotIterable, _GenericAlias, _root=True):
+1589    def __repr__(self):
+1590        assert self._name == 'Callable'
+1591        args = self.__args__
+1592        if len(args) == 2 and _is_param_expr(args[0]):
+1593            return super().__repr__()
+1594        return (f'typing.Callable'
+1595                f'[[{", ".join([_type_repr(a) for a in args[:-1]])}], '
+1596                f'{_type_repr(args[-1])}]')
+1597
+1598    def __reduce__(self):
+1599        args = self.__args__
+1600        if not (len(args) == 2 and _is_param_expr(args[0])):
+1601            args = list(args[:-1]), args[-1]
+1602        return operator.getitem, (Callable, args)
+1603
 1604
-1605    def __reduce__(self):
-1606        args = self.__args__
-1607        if not (len(args) == 2 and _is_param_expr(args[0])):
-1608            args = list(args[:-1]), args[-1]
-1609        return operator.getitem, (Callable, args)
+1605class _CallableType(_SpecialGenericAlias, _root=True):
+1606    def copy_with(self, params):
+1607        return _CallableGenericAlias(self.__origin__, params,
+1608                                     name=self._name, inst=self._inst,
+1609                                     _paramspec_tvars=True)
 1610
-1611
-1612class _CallableType(_SpecialGenericAlias, _root=True):
-1613    def copy_with(self, params):
-1614        return _CallableGenericAlias(self.__origin__, params,
-1615                                     name=self._name, inst=self._inst,
-1616                                     _paramspec_tvars=True)
-1617
-1618    def __getitem__(self, params):
-1619        if not isinstance(params, tuple) or len(params) != 2:
-1620            raise TypeError("Callable must be used as "
-1621                            "Callable[[arg, ...], result].")
-1622        args, result = params
-1623        # This relaxes what args can be on purpose to allow things like
-1624        # PEP 612 ParamSpec.  Responsibility for whether a user is using
-1625        # Callable[...] properly is deferred to static type checkers.
-1626        if isinstance(args, list):
-1627            params = (tuple(args), result)
-1628        else:
-1629            params = (args, result)
-1630        return self.__getitem_inner__(params)
-1631
-1632    @_tp_cache
-1633    def __getitem_inner__(self, params):
-1634        args, result = params
-1635        msg = "Callable[args, result]: result must be a type."
-1636        result = _type_check(result, msg)
-1637        if args is Ellipsis:
-1638            return self.copy_with((_TypingEllipsis, result))
-1639        if not isinstance(args, tuple):
-1640            args = (args,)
-1641        args = tuple(_type_convert(arg) for arg in args)
-1642        params = args + (result,)
-1643        return self.copy_with(params)
-1644
-1645
-1646class _TupleType(_SpecialGenericAlias, _root=True):
-1647    @_tp_cache
-1648    def __getitem__(self, params):
-1649        if not isinstance(params, tuple):
-1650            params = (params,)
-1651        if len(params) >= 2 and params[-1] is ...:
-1652            msg = "Tuple[t, ...]: t must be a type."
-1653            params = tuple(_type_check(p, msg) for p in params[:-1])
-1654            return self.copy_with((*params, _TypingEllipsis))
-1655        msg = "Tuple[t0, t1, ...]: each t must be a type."
-1656        params = tuple(_type_check(p, msg) for p in params)
-1657        return self.copy_with(params)
-1658
-1659
-1660class _UnionGenericAlias(_NotIterable, _GenericAlias, _root=True):
-1661    def copy_with(self, params):
-1662        return Union[params]
-1663
-1664    def __eq__(self, other):
-1665        if not isinstance(other, (_UnionGenericAlias, types.UnionType)):
-1666            return NotImplemented
-1667        return set(self.__args__) == set(other.__args__)
-1668
-1669    def __hash__(self):
-1670        return hash(frozenset(self.__args__))
-1671
-1672    def __repr__(self):
-1673        args = self.__args__
-1674        if len(args) == 2:
-1675            if args[0] is type(None):
-1676                return f'typing.Optional[{_type_repr(args[1])}]'
-1677            elif args[1] is type(None):
-1678                return f'typing.Optional[{_type_repr(args[0])}]'
-1679        return super().__repr__()
-1680
-1681    def __instancecheck__(self, obj):
-1682        return self.__subclasscheck__(type(obj))
-1683
-1684    def __subclasscheck__(self, cls):
-1685        for arg in self.__args__:
-1686            if issubclass(cls, arg):
-1687                return True
-1688
-1689    def __reduce__(self):
-1690        func, (origin, args) = super().__reduce__()
-1691        return func, (Union, args)
-1692
-1693
-1694def _value_and_type_iter(parameters):
-1695    return ((p, type(p)) for p in parameters)
-1696
+1611    def __getitem__(self, params):
+1612        if not isinstance(params, tuple) or len(params) != 2:
+1613            raise TypeError("Callable must be used as "
+1614                            "Callable[[arg, ...], result].")
+1615        args, result = params
+1616        # This relaxes what args can be on purpose to allow things like
+1617        # PEP 612 ParamSpec.  Responsibility for whether a user is using
+1618        # Callable[...] properly is deferred to static type checkers.
+1619        if isinstance(args, list):
+1620            params = (tuple(args), result)
+1621        else:
+1622            params = (args, result)
+1623        return self.__getitem_inner__(params)
+1624
+1625    @_tp_cache
+1626    def __getitem_inner__(self, params):
+1627        args, result = params
+1628        msg = "Callable[args, result]: result must be a type."
+1629        result = _type_check(result, msg)
+1630        if args is Ellipsis:
+1631            return self.copy_with((_TypingEllipsis, result))
+1632        if not isinstance(args, tuple):
+1633            args = (args,)
+1634        args = tuple(_type_convert(arg) for arg in args)
+1635        params = args + (result,)
+1636        return self.copy_with(params)
+1637
+1638
+1639class _TupleType(_SpecialGenericAlias, _root=True):
+1640    @_tp_cache
+1641    def __getitem__(self, params):
+1642        if not isinstance(params, tuple):
+1643            params = (params,)
+1644        if len(params) >= 2 and params[-1] is ...:
+1645            msg = "Tuple[t, ...]: t must be a type."
+1646            params = tuple(_type_check(p, msg) for p in params[:-1])
+1647            return self.copy_with((*params, _TypingEllipsis))
+1648        msg = "Tuple[t0, t1, ...]: each t must be a type."
+1649        params = tuple(_type_check(p, msg) for p in params)
+1650        return self.copy_with(params)
+1651
+1652
+1653class _UnionGenericAlias(_NotIterable, _GenericAlias, _root=True):
+1654    def copy_with(self, params):
+1655        return Union[params]
+1656
+1657    def __eq__(self, other):
+1658        if not isinstance(other, (_UnionGenericAlias, types.UnionType)):
+1659            return NotImplemented
+1660        return set(self.__args__) == set(other.__args__)
+1661
+1662    def __hash__(self):
+1663        return hash(frozenset(self.__args__))
+1664
+1665    def __repr__(self):
+1666        args = self.__args__
+1667        if len(args) == 2:
+1668            if args[0] is type(None):
+1669                return f'typing.Optional[{_type_repr(args[1])}]'
+1670            elif args[1] is type(None):
+1671                return f'typing.Optional[{_type_repr(args[0])}]'
+1672        return super().__repr__()
+1673
+1674    def __instancecheck__(self, obj):
+1675        return self.__subclasscheck__(type(obj))
+1676
+1677    def __subclasscheck__(self, cls):
+1678        for arg in self.__args__:
+1679            if issubclass(cls, arg):
+1680                return True
+1681
+1682    def __reduce__(self):
+1683        func, (origin, args) = super().__reduce__()
+1684        return func, (Union, args)
+1685
+1686
+1687def _value_and_type_iter(parameters):
+1688    return ((p, type(p)) for p in parameters)
+1689
+1690
+1691class _LiteralGenericAlias(_GenericAlias, _root=True):
+1692    def __eq__(self, other):
+1693        if not isinstance(other, _LiteralGenericAlias):
+1694            return NotImplemented
+1695
+1696        return set(_value_and_type_iter(self.__args__)) == set(_value_and_type_iter(other.__args__))
 1697
-1698class _LiteralGenericAlias(_GenericAlias, _root=True):
-1699    def __eq__(self, other):
-1700        if not isinstance(other, _LiteralGenericAlias):
-1701            return NotImplemented
-1702
-1703        return set(_value_and_type_iter(self.__args__)) == set(_value_and_type_iter(other.__args__))
-1704
-1705    def __hash__(self):
-1706        return hash(frozenset(_value_and_type_iter(self.__args__)))
-1707
-1708
-1709class _ConcatenateGenericAlias(_GenericAlias, _root=True):
-1710    def copy_with(self, params):
-1711        if isinstance(params[-1], (list, tuple)):
-1712            return (*params[:-1], *params[-1])
-1713        if isinstance(params[-1], _ConcatenateGenericAlias):
-1714            params = (*params[:-1], *params[-1].__args__)
-1715        return super().copy_with(params)
-1716
-1717
-1718@_SpecialForm
-1719def Unpack(self, parameters):
-1720    """Type unpack operator.
+1698    def __hash__(self):
+1699        return hash(frozenset(_value_and_type_iter(self.__args__)))
+1700
+1701
+1702class _ConcatenateGenericAlias(_GenericAlias, _root=True):
+1703    def copy_with(self, params):
+1704        if isinstance(params[-1], (list, tuple)):
+1705            return (*params[:-1], *params[-1])
+1706        if isinstance(params[-1], _ConcatenateGenericAlias):
+1707            params = (*params[:-1], *params[-1].__args__)
+1708        return super().copy_with(params)
+1709
+1710
+1711@_SpecialForm
+1712def Unpack(self, parameters):
+1713    """Type unpack operator.
+1714
+1715    The type unpack operator takes the child types from some container type,
+1716    such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'. For
+1717    example::
+1718
+1719        # For some generic class `Foo`:
+1720        Foo[Unpack[tuple[int, str]]]  # Equivalent to Foo[int, str]
 1721
-1722    The type unpack operator takes the child types from some container type,
-1723    such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'.
-1724
-1725    For example::
-1726
-1727        # For some generic class `Foo`:
-1728        Foo[Unpack[tuple[int, str]]]  # Equivalent to Foo[int, str]
-1729
-1730        Ts = TypeVarTuple('Ts')
-1731        # Specifies that `Bar` is generic in an arbitrary number of types.
-1732        # (Think of `Ts` as a tuple of an arbitrary number of individual
-1733        #  `TypeVar`s, which the `Unpack` is 'pulling out' directly into the
-1734        #  `Generic[]`.)
-1735        class Bar(Generic[Unpack[Ts]]): ...
-1736        Bar[int]  # Valid
-1737        Bar[int, str]  # Also valid
+1722        Ts = TypeVarTuple('Ts')
+1723        # Specifies that `Bar` is generic in an arbitrary number of types.
+1724        # (Think of `Ts` as a tuple of an arbitrary number of individual
+1725        #  `TypeVar`s, which the `Unpack` is 'pulling out' directly into the
+1726        #  `Generic[]`.)
+1727        class Bar(Generic[Unpack[Ts]]): ...
+1728        Bar[int]  # Valid
+1729        Bar[int, str]  # Also valid
+1730
+1731    From Python 3.11, this can also be done using the `*` operator::
+1732
+1733        Foo[*tuple[int, str]]
+1734        class Bar(Generic[*Ts]): ...
+1735
+1736    Note that there is only some runtime checking of this operator. Not
+1737    everything the runtime allows may be accepted by static type checkers.
 1738
-1739    From Python 3.11, this can also be done using the `*` operator::
-1740
-1741        Foo[*tuple[int, str]]
-1742        class Bar(Generic[*Ts]): ...
+1739    For more information, see PEP 646.
+1740    """
+1741    item = _type_check(parameters, f'{self} accepts only single type.')
+1742    return _UnpackGenericAlias(origin=self, args=(item,))
 1743
-1744    Note that there is only some runtime checking of this operator. Not
-1745    everything the runtime allows may be accepted by static type checkers.
-1746
-1747    For more information, see PEP 646.
-1748    """
-1749    item = _type_check(parameters, f'{self} accepts only single type.')
-1750    return _UnpackGenericAlias(origin=self, args=(item,))
-1751
-1752
-1753class _UnpackGenericAlias(_GenericAlias, _root=True):
-1754    def __repr__(self):
-1755        # `Unpack` only takes one argument, so __args__ should contain only
-1756        # a single item.
-1757        return '*' + repr(self.__args__[0])
-1758
-1759    def __getitem__(self, args):
-1760        if self.__typing_is_unpacked_typevartuple__:
-1761            return args
-1762        return super().__getitem__(args)
-1763
-1764    @property
-1765    def __typing_unpacked_tuple_args__(self):
-1766        assert self.__origin__ is Unpack
-1767        assert len(self.__args__) == 1
-1768        arg, = self.__args__
-1769        if isinstance(arg, _GenericAlias):
-1770            assert arg.__origin__ is tuple
-1771            return arg.__args__
-1772        return None
-1773
-1774    @property
-1775    def __typing_is_unpacked_typevartuple__(self):
-1776        assert self.__origin__ is Unpack
-1777        assert len(self.__args__) == 1
-1778        return isinstance(self.__args__[0], TypeVarTuple)
+1744
+1745class _UnpackGenericAlias(_GenericAlias, _root=True):
+1746    def __repr__(self):
+1747        # `Unpack` only takes one argument, so __args__ should contain only
+1748        # a single item.
+1749        return '*' + repr(self.__args__[0])
+1750
+1751    def __getitem__(self, args):
+1752        if self.__typing_is_unpacked_typevartuple__:
+1753            return args
+1754        return super().__getitem__(args)
+1755
+1756    @property
+1757    def __typing_unpacked_tuple_args__(self):
+1758        assert self.__origin__ is Unpack
+1759        assert len(self.__args__) == 1
+1760        arg, = self.__args__
+1761        if isinstance(arg, _GenericAlias):
+1762            assert arg.__origin__ is tuple
+1763            return arg.__args__
+1764        return None
+1765
+1766    @property
+1767    def __typing_is_unpacked_typevartuple__(self):
+1768        assert self.__origin__ is Unpack
+1769        assert len(self.__args__) == 1
+1770        return isinstance(self.__args__[0], TypeVarTuple)
+1771
+1772
+1773class Generic:
+1774    """Abstract base class for generic types.
+1775
+1776    A generic type is typically declared by inheriting from
+1777    this class parameterized with one or more type variables.
+1778    For example, a generic mapping type might be defined as::
 1779
-1780
-1781class Generic:
-1782    """Abstract base class for generic types.
-1783
-1784    A generic type is typically declared by inheriting from
-1785    this class parameterized with one or more type variables.
-1786    For example, a generic mapping type might be defined as::
-1787
-1788      class Mapping(Generic[KT, VT]):
-1789          def __getitem__(self, key: KT) -> VT:
-1790              ...
-1791          # Etc.
-1792
-1793    This class can then be used as follows::
-1794
-1795      def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
-1796          try:
-1797              return mapping[key]
-1798          except KeyError:
-1799              return default
-1800    """
-1801    __slots__ = ()
-1802    _is_protocol = False
+1780      class Mapping(Generic[KT, VT]):
+1781          def __getitem__(self, key: KT) -> VT:
+1782              ...
+1783          # Etc.
+1784
+1785    This class can then be used as follows::
+1786
+1787      def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
+1788          try:
+1789              return mapping[key]
+1790          except KeyError:
+1791              return default
+1792    """
+1793    __slots__ = ()
+1794    _is_protocol = False
+1795
+1796    @_tp_cache
+1797    def __class_getitem__(cls, params):
+1798        """Parameterizes a generic class.
+1799
+1800        At least, parameterizing a generic class is the *main* thing this method
+1801        does. For example, for some generic class `Foo`, this is called when we
+1802        do `Foo[int]` - there, with `cls=Foo` and `params=int`.
 1803
-1804    @_tp_cache
-1805    def __class_getitem__(cls, params):
-1806        """Parameterizes a generic class.
-1807
-1808        At least, parameterizing a generic class is the *main* thing this method
-1809        does. For example, for some generic class `Foo`, this is called when we
-1810        do `Foo[int]` - there, with `cls=Foo` and `params=int`.
-1811
-1812        However, note that this method is also called when defining generic
-1813        classes in the first place with `class Foo(Generic[T]): ...`.
-1814        """
-1815        if not isinstance(params, tuple):
-1816            params = (params,)
-1817
-1818        params = tuple(_type_convert(p) for p in params)
-1819        if cls in (Generic, Protocol):
-1820            # Generic and Protocol can only be subscripted with unique type variables.
-1821            if not params:
+1804        However, note that this method is also called when defining generic
+1805        classes in the first place with `class Foo(Generic[T]): ...`.
+1806        """
+1807        if not isinstance(params, tuple):
+1808            params = (params,)
+1809
+1810        params = tuple(_type_convert(p) for p in params)
+1811        if cls in (Generic, Protocol):
+1812            # Generic and Protocol can only be subscripted with unique type variables.
+1813            if not params:
+1814                raise TypeError(
+1815                    f"Parameter list to {cls.__qualname__}[...] cannot be empty"
+1816                )
+1817            if not all(_is_typevar_like(p) for p in params):
+1818                raise TypeError(
+1819                    f"Parameters to {cls.__name__}[...] must all be type variables "
+1820                    f"or parameter specification variables.")
+1821            if len(set(params)) != len(params):
 1822                raise TypeError(
-1823                    f"Parameter list to {cls.__qualname__}[...] cannot be empty"
-1824                )
-1825            if not all(_is_typevar_like(p) for p in params):
-1826                raise TypeError(
-1827                    f"Parameters to {cls.__name__}[...] must all be type variables "
-1828                    f"or parameter specification variables.")
-1829            if len(set(params)) != len(params):
-1830                raise TypeError(
-1831                    f"Parameters to {cls.__name__}[...] must all be unique")
-1832        else:
-1833            # Subscripting a regular Generic subclass.
-1834            for param in cls.__parameters__:
-1835                prepare = getattr(param, '__typing_prepare_subst__', None)
-1836                if prepare is not None:
-1837                    params = prepare(cls, params)
-1838            _check_generic(cls, params, len(cls.__parameters__))
+1823                    f"Parameters to {cls.__name__}[...] must all be unique")
+1824        else:
+1825            # Subscripting a regular Generic subclass.
+1826            for param in cls.__parameters__:
+1827                prepare = getattr(param, '__typing_prepare_subst__', None)
+1828                if prepare is not None:
+1829                    params = prepare(cls, params)
+1830            _check_generic(cls, params, len(cls.__parameters__))
+1831
+1832            new_args = []
+1833            for param, new_arg in zip(cls.__parameters__, params):
+1834                if isinstance(param, TypeVarTuple):
+1835                    new_args.extend(new_arg)
+1836                else:
+1837                    new_args.append(new_arg)
+1838            params = tuple(new_args)
 1839
-1840            new_args = []
-1841            for param, new_arg in zip(cls.__parameters__, params):
-1842                if isinstance(param, TypeVarTuple):
-1843                    new_args.extend(new_arg)
-1844                else:
-1845                    new_args.append(new_arg)
-1846            params = tuple(new_args)
-1847
-1848        return _GenericAlias(cls, params,
-1849                             _paramspec_tvars=True)
-1850
-1851    def __init_subclass__(cls, *args, **kwargs):
-1852        super().__init_subclass__(*args, **kwargs)
-1853        tvars = []
+1840        return _GenericAlias(cls, params,
+1841                             _paramspec_tvars=True)
+1842
+1843    def __init_subclass__(cls, *args, **kwargs):
+1844        super().__init_subclass__(*args, **kwargs)
+1845        tvars = []
+1846        if '__orig_bases__' in cls.__dict__:
+1847            error = Generic in cls.__orig_bases__
+1848        else:
+1849            error = (Generic in cls.__bases__ and
+1850                        cls.__name__ != 'Protocol' and
+1851                        type(cls) != _TypedDictMeta)
+1852        if error:
+1853            raise TypeError("Cannot inherit from plain Generic")
 1854        if '__orig_bases__' in cls.__dict__:
-1855            error = Generic in cls.__orig_bases__
-1856        else:
-1857            error = (Generic in cls.__bases__ and
-1858                        cls.__name__ != 'Protocol' and
-1859                        type(cls) != _TypedDictMeta)
-1860        if error:
-1861            raise TypeError("Cannot inherit from plain Generic")
-1862        if '__orig_bases__' in cls.__dict__:
-1863            tvars = _collect_parameters(cls.__orig_bases__)
-1864            # Look for Generic[T1, ..., Tn].
-1865            # If found, tvars must be a subset of it.
-1866            # If not found, tvars is it.
-1867            # Also check for and reject plain Generic,
-1868            # and reject multiple Generic[...].
-1869            gvars = None
-1870            for base in cls.__orig_bases__:
-1871                if (isinstance(base, _GenericAlias) and
-1872                        base.__origin__ is Generic):
-1873                    if gvars is not None:
-1874                        raise TypeError(
-1875                            "Cannot inherit from Generic[...] multiple times.")
-1876                    gvars = base.__parameters__
-1877            if gvars is not None:
-1878                tvarset = set(tvars)
-1879                gvarset = set(gvars)
-1880                if not tvarset <= gvarset:
-1881                    s_vars = ', '.join(str(t) for t in tvars if t not in gvarset)
-1882                    s_args = ', '.join(str(g) for g in gvars)
-1883                    raise TypeError(f"Some type variables ({s_vars}) are"
-1884                                    f" not listed in Generic[{s_args}]")
-1885                tvars = gvars
-1886        cls.__parameters__ = tuple(tvars)
+1855            tvars = _collect_parameters(cls.__orig_bases__)
+1856            # Look for Generic[T1, ..., Tn].
+1857            # If found, tvars must be a subset of it.
+1858            # If not found, tvars is it.
+1859            # Also check for and reject plain Generic,
+1860            # and reject multiple Generic[...].
+1861            gvars = None
+1862            for base in cls.__orig_bases__:
+1863                if (isinstance(base, _GenericAlias) and
+1864                        base.__origin__ is Generic):
+1865                    if gvars is not None:
+1866                        raise TypeError(
+1867                            "Cannot inherit from Generic[...] multiple times.")
+1868                    gvars = base.__parameters__
+1869            if gvars is not None:
+1870                tvarset = set(tvars)
+1871                gvarset = set(gvars)
+1872                if not tvarset <= gvarset:
+1873                    s_vars = ', '.join(str(t) for t in tvars if t not in gvarset)
+1874                    s_args = ', '.join(str(g) for g in gvars)
+1875                    raise TypeError(f"Some type variables ({s_vars}) are"
+1876                                    f" not listed in Generic[{s_args}]")
+1877                tvars = gvars
+1878        cls.__parameters__ = tuple(tvars)
+1879
+1880
+1881class _TypingEllipsis:
+1882    """Internal placeholder for ... (ellipsis)."""
+1883
+1884
+1885_TYPING_INTERNALS = ['__parameters__', '__orig_bases__',  '__orig_class__',
+1886                     '_is_protocol', '_is_runtime_protocol']
 1887
-1888
-1889class _TypingEllipsis:
-1890    """Internal placeholder for ... (ellipsis)."""
+1888_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__',
+1889                  '__init__', '__module__', '__new__', '__slots__',
+1890                  '__subclasshook__', '__weakref__', '__class_getitem__']
 1891
-1892
-1893_TYPING_INTERNALS = ['__parameters__', '__orig_bases__',  '__orig_class__',
-1894                     '_is_protocol', '_is_runtime_protocol', '__final__']
+1892# These special attributes will be not collected as protocol members.
+1893EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker']
+1894
 1895
-1896_SPECIAL_NAMES = ['__abstractmethods__', '__annotations__', '__dict__', '__doc__',
-1897                  '__init__', '__module__', '__new__', '__slots__',
-1898                  '__subclasshook__', '__weakref__', '__class_getitem__']
-1899
-1900# These special attributes will be not collected as protocol members.
-1901EXCLUDED_ATTRIBUTES = _TYPING_INTERNALS + _SPECIAL_NAMES + ['_MutableMapping__marker']
-1902
-1903
-1904def _get_protocol_attrs(cls):
-1905    """Collect protocol members from a protocol class objects.
-1906
-1907    This includes names actually defined in the class dictionary, as well
-1908    as names that appear in annotations. Special names (above) are skipped.
-1909    """
-1910    attrs = set()
-1911    for base in cls.__mro__[:-1]:  # without object
-1912        if base.__name__ in ('Protocol', 'Generic'):
-1913            continue
-1914        annotations = getattr(base, '__annotations__', {})
-1915        for attr in list(base.__dict__.keys()) + list(annotations.keys()):
-1916            if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES:
-1917                attrs.add(attr)
-1918    return attrs
-1919
+1896def _get_protocol_attrs(cls):
+1897    """Collect protocol members from a protocol class objects.
+1898
+1899    This includes names actually defined in the class dictionary, as well
+1900    as names that appear in annotations. Special names (above) are skipped.
+1901    """
+1902    attrs = set()
+1903    for base in cls.__mro__[:-1]:  # without object
+1904        if base.__name__ in ('Protocol', 'Generic'):
+1905            continue
+1906        annotations = getattr(base, '__annotations__', {})
+1907        for attr in list(base.__dict__.keys()) + list(annotations.keys()):
+1908            if not attr.startswith('_abc_') and attr not in EXCLUDED_ATTRIBUTES:
+1909                attrs.add(attr)
+1910    return attrs
+1911
+1912
+1913def _is_callable_members_only(cls):
+1914    # PEP 544 prohibits using issubclass() with protocols that have non-method members.
+1915    return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls))
+1916
+1917
+1918def _no_init_or_replace_init(self, *args, **kwargs):
+1919    cls = type(self)
 1920
-1921def _is_callable_members_only(cls):
-1922    # PEP 544 prohibits using issubclass() with protocols that have non-method members.
-1923    return all(callable(getattr(cls, attr, None)) for attr in _get_protocol_attrs(cls))
-1924
-1925
-1926def _no_init_or_replace_init(self, *args, **kwargs):
-1927    cls = type(self)
+1921    if cls._is_protocol:
+1922        raise TypeError('Protocols cannot be instantiated')
+1923
+1924    # Already using a custom `__init__`. No need to calculate correct
+1925    # `__init__` to call. This can lead to RecursionError. See bpo-45121.
+1926    if cls.__init__ is not _no_init_or_replace_init:
+1927        return
 1928
-1929    if cls._is_protocol:
-1930        raise TypeError('Protocols cannot be instantiated')
-1931
-1932    # Already using a custom `__init__`. No need to calculate correct
-1933    # `__init__` to call. This can lead to RecursionError. See bpo-45121.
-1934    if cls.__init__ is not _no_init_or_replace_init:
-1935        return
-1936
-1937    # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
-1938    # The first instantiation of the subclass will call `_no_init_or_replace_init` which
-1939    # searches for a proper new `__init__` in the MRO. The new `__init__`
-1940    # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
-1941    # instantiation of the protocol subclass will thus use the new
-1942    # `__init__` and no longer call `_no_init_or_replace_init`.
-1943    for base in cls.__mro__:
-1944        init = base.__dict__.get('__init__', _no_init_or_replace_init)
-1945        if init is not _no_init_or_replace_init:
-1946            cls.__init__ = init
-1947            break
-1948    else:
-1949        # should not happen
-1950        cls.__init__ = object.__init__
-1951
-1952    cls.__init__(self, *args, **kwargs)
+1929    # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
+1930    # The first instantiation of the subclass will call `_no_init_or_replace_init` which
+1931    # searches for a proper new `__init__` in the MRO. The new `__init__`
+1932    # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
+1933    # instantiation of the protocol subclass will thus use the new
+1934    # `__init__` and no longer call `_no_init_or_replace_init`.
+1935    for base in cls.__mro__:
+1936        init = base.__dict__.get('__init__', _no_init_or_replace_init)
+1937        if init is not _no_init_or_replace_init:
+1938            cls.__init__ = init
+1939            break
+1940    else:
+1941        # should not happen
+1942        cls.__init__ = object.__init__
+1943
+1944    cls.__init__(self, *args, **kwargs)
+1945
+1946
+1947def _caller(depth=1, default='__main__'):
+1948    try:
+1949        return sys._getframe(depth + 1).f_globals.get('__name__', default)
+1950    except (AttributeError, ValueError):  # For platforms without _getframe()
+1951        return None
+1952
 1953
-1954
-1955def _caller(depth=1, default='__main__'):
-1956    try:
-1957        return sys._getframe(depth + 1).f_globals.get('__name__', default)
-1958    except (AttributeError, ValueError):  # For platforms without _getframe()
-1959        return None
-1960
+1954def _allow_reckless_class_checks(depth=3):
+1955    """Allow instance and class checks for special stdlib modules.
+1956
+1957    The abc and functools modules indiscriminately call isinstance() and
+1958    issubclass() on the whole MRO of a user class, which may contain protocols.
+1959    """
+1960    return _caller(depth) in {'abc', 'functools', None}
 1961
-1962def _allow_reckless_class_checks(depth=3):
-1963    """Allow instance and class checks for special stdlib modules.
-1964
-1965    The abc and functools modules indiscriminately call isinstance() and
-1966    issubclass() on the whole MRO of a user class, which may contain protocols.
-1967    """
-1968    return _caller(depth) in {'abc', 'functools', None}
-1969
+1962
+1963_PROTO_ALLOWLIST = {
+1964    'collections.abc': [
+1965        'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
+1966        'Hashable', 'Sized', 'Container', 'Collection', 'Reversible',
+1967    ],
+1968    'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
+1969}
 1970
-1971_PROTO_ALLOWLIST = {
-1972    'collections.abc': [
-1973        'Callable', 'Awaitable', 'Iterable', 'Iterator', 'AsyncIterable',
-1974        'Hashable', 'Sized', 'Container', 'Collection', 'Reversible',
-1975    ],
-1976    'contextlib': ['AbstractContextManager', 'AbstractAsyncContextManager'],
-1977}
-1978
-1979
-1980class _ProtocolMeta(ABCMeta):
-1981    # This metaclass is really unfortunate and exists only because of
-1982    # the lack of __instancehook__.
-1983    def __instancecheck__(cls, instance):
-1984        # We need this method for situations where attributes are
-1985        # assigned in __init__.
-1986        if (
-1987            getattr(cls, '_is_protocol', False) and
-1988            not getattr(cls, '_is_runtime_protocol', False) and
-1989            not _allow_reckless_class_checks(depth=2)
-1990        ):
-1991            raise TypeError("Instance and class checks can only be used with"
-1992                            " @runtime_checkable protocols")
-1993
-1994        if ((not getattr(cls, '_is_protocol', False) or
-1995                _is_callable_members_only(cls)) and
-1996                issubclass(instance.__class__, cls)):
-1997            return True
-1998        if cls._is_protocol:
-1999            if all(hasattr(instance, attr) and
-2000                    # All *methods* can be blocked by setting them to None.
-2001                    (not callable(getattr(cls, attr, None)) or
-2002                     getattr(instance, attr) is not None)
-2003                    for attr in _get_protocol_attrs(cls)):
-2004                return True
-2005        return super().__instancecheck__(instance)
-2006
-2007
-2008class Protocol(Generic, metaclass=_ProtocolMeta):
-2009    """Base class for protocol classes.
-2010
-2011    Protocol classes are defined as::
-2012
-2013        class Proto(Protocol):
-2014            def meth(self) -> int:
-2015                ...
-2016
-2017    Such classes are primarily used with static type checkers that recognize
-2018    structural subtyping (static duck-typing).
-2019
-2020    For example::
-2021
-2022        class C:
-2023            def meth(self) -> int:
-2024                return 0
+1971
+1972class _ProtocolMeta(ABCMeta):
+1973    # This metaclass is really unfortunate and exists only because of
+1974    # the lack of __instancehook__.
+1975    def __instancecheck__(cls, instance):
+1976        # We need this method for situations where attributes are
+1977        # assigned in __init__.
+1978        if (
+1979            getattr(cls, '_is_protocol', False) and
+1980            not getattr(cls, '_is_runtime_protocol', False) and
+1981            not _allow_reckless_class_checks(depth=2)
+1982        ):
+1983            raise TypeError("Instance and class checks can only be used with"
+1984                            " @runtime_checkable protocols")
+1985
+1986        if ((not getattr(cls, '_is_protocol', False) or
+1987                _is_callable_members_only(cls)) and
+1988                issubclass(instance.__class__, cls)):
+1989            return True
+1990        if cls._is_protocol:
+1991            if all(hasattr(instance, attr) and
+1992                    # All *methods* can be blocked by setting them to None.
+1993                    (not callable(getattr(cls, attr, None)) or
+1994                     getattr(instance, attr) is not None)
+1995                    for attr in _get_protocol_attrs(cls)):
+1996                return True
+1997        return super().__instancecheck__(instance)
+1998
+1999
+2000class Protocol(Generic, metaclass=_ProtocolMeta):
+2001    """Base class for protocol classes.
+2002
+2003    Protocol classes are defined as::
+2004
+2005        class Proto(Protocol):
+2006            def meth(self) -> int:
+2007                ...
+2008
+2009    Such classes are primarily used with static type checkers that recognize
+2010    structural subtyping (static duck-typing), for example::
+2011
+2012        class C:
+2013            def meth(self) -> int:
+2014                return 0
+2015
+2016        def func(x: Proto) -> int:
+2017            return x.meth()
+2018
+2019        func(C())  # Passes static type check
+2020
+2021    See PEP 544 for details. Protocol classes decorated with
+2022    @typing.runtime_checkable act as simple-minded runtime protocols that check
+2023    only the presence of given attributes, ignoring their type signatures.
+2024    Protocol classes can be generic, they are defined as::
 2025
-2026        def func(x: Proto) -> int:
-2027            return x.meth()
-2028
-2029        func(C())  # Passes static type check
+2026        class GenProto(Protocol[T]):
+2027            def meth(self) -> T:
+2028                ...
+2029    """
 2030
-2031    See PEP 544 for details. Protocol classes decorated with
-2032    @typing.runtime_checkable act as simple-minded runtime protocols that check
-2033    only the presence of given attributes, ignoring their type signatures.
-2034    Protocol classes can be generic, they are defined as::
-2035
-2036        class GenProto(Protocol[T]):
-2037            def meth(self) -> T:
-2038                ...
-2039    """
-2040
-2041    __slots__ = ()
-2042    _is_protocol = True
-2043    _is_runtime_protocol = False
-2044
-2045    def __init_subclass__(cls, *args, **kwargs):
-2046        super().__init_subclass__(*args, **kwargs)
-2047
-2048        # Determine if this is a protocol or a concrete subclass.
-2049        if not cls.__dict__.get('_is_protocol', False):
-2050            cls._is_protocol = any(b is Protocol for b in cls.__bases__)
-2051
-2052        # Set (or override) the protocol subclass hook.
-2053        def _proto_hook(other):
-2054            if not cls.__dict__.get('_is_protocol', False):
-2055                return NotImplemented
-2056
-2057            # First, perform various sanity checks.
-2058            if not getattr(cls, '_is_runtime_protocol', False):
-2059                if _allow_reckless_class_checks():
-2060                    return NotImplemented
-2061                raise TypeError("Instance and class checks can only be used with"
-2062                                " @runtime_checkable protocols")
-2063            if not _is_callable_members_only(cls):
-2064                if _allow_reckless_class_checks():
-2065                    return NotImplemented
-2066                raise TypeError("Protocols with non-method members"
-2067                                " don't support issubclass()")
-2068            if not isinstance(other, type):
-2069                # Same error message as for issubclass(1, int).
-2070                raise TypeError('issubclass() arg 1 must be a class')
-2071
-2072            # Second, perform the actual structural compatibility check.
-2073            for attr in _get_protocol_attrs(cls):
-2074                for base in other.__mro__:
-2075                    # Check if the members appears in the class dictionary...
-2076                    if attr in base.__dict__:
-2077                        if base.__dict__[attr] is None:
-2078                            return NotImplemented
-2079                        break
+2031    __slots__ = ()
+2032    _is_protocol = True
+2033    _is_runtime_protocol = False
+2034
+2035    def __init_subclass__(cls, *args, **kwargs):
+2036        super().__init_subclass__(*args, **kwargs)
+2037
+2038        # Determine if this is a protocol or a concrete subclass.
+2039        if not cls.__dict__.get('_is_protocol', False):
+2040            cls._is_protocol = any(b is Protocol for b in cls.__bases__)
+2041
+2042        # Set (or override) the protocol subclass hook.
+2043        def _proto_hook(other):
+2044            if not cls.__dict__.get('_is_protocol', False):
+2045                return NotImplemented
+2046
+2047            # First, perform various sanity checks.
+2048            if not getattr(cls, '_is_runtime_protocol', False):
+2049                if _allow_reckless_class_checks():
+2050                    return NotImplemented
+2051                raise TypeError("Instance and class checks can only be used with"
+2052                                " @runtime_checkable protocols")
+2053            if not _is_callable_members_only(cls):
+2054                if _allow_reckless_class_checks():
+2055                    return NotImplemented
+2056                raise TypeError("Protocols with non-method members"
+2057                                " don't support issubclass()")
+2058            if not isinstance(other, type):
+2059                # Same error message as for issubclass(1, int).
+2060                raise TypeError('issubclass() arg 1 must be a class')
+2061
+2062            # Second, perform the actual structural compatibility check.
+2063            for attr in _get_protocol_attrs(cls):
+2064                for base in other.__mro__:
+2065                    # Check if the members appears in the class dictionary...
+2066                    if attr in base.__dict__:
+2067                        if base.__dict__[attr] is None:
+2068                            return NotImplemented
+2069                        break
+2070
+2071                    # ...or in annotations, if it is a sub-protocol.
+2072                    annotations = getattr(base, '__annotations__', {})
+2073                    if (isinstance(annotations, collections.abc.Mapping) and
+2074                            attr in annotations and
+2075                            issubclass(other, Generic) and other._is_protocol):
+2076                        break
+2077                else:
+2078                    return NotImplemented
+2079            return True
 2080
-2081                    # ...or in annotations, if it is a sub-protocol.
-2082                    annotations = getattr(base, '__annotations__', {})
-2083                    if (isinstance(annotations, collections.abc.Mapping) and
-2084                            attr in annotations and
-2085                            issubclass(other, Generic) and other._is_protocol):
-2086                        break
-2087                else:
-2088                    return NotImplemented
-2089            return True
-2090
-2091        if '__subclasshook__' not in cls.__dict__:
-2092            cls.__subclasshook__ = _proto_hook
-2093
-2094        # We have nothing more to do for non-protocols...
-2095        if not cls._is_protocol:
-2096            return
-2097
-2098        # ... otherwise check consistency of bases, and prohibit instantiation.
-2099        for base in cls.__bases__:
-2100            if not (base in (object, Generic) or
-2101                    base.__module__ in _PROTO_ALLOWLIST and
-2102                    base.__name__ in _PROTO_ALLOWLIST[base.__module__] or
-2103                    issubclass(base, Generic) and base._is_protocol):
-2104                raise TypeError('Protocols can only inherit from other'
-2105                                ' protocols, got %r' % base)
-2106        if cls.__init__ is Protocol.__init__:
-2107            cls.__init__ = _no_init_or_replace_init
-2108
-2109
-2110class _AnnotatedAlias(_NotIterable, _GenericAlias, _root=True):
-2111    """Runtime representation of an annotated type.
-2112
-2113    At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
-2114    with extra annotations. The alias behaves like a normal typing alias.
-2115    Instantiating is the same as instantiating the underlying type; binding
-2116    it to types is also the same.
+2081        if '__subclasshook__' not in cls.__dict__:
+2082            cls.__subclasshook__ = _proto_hook
+2083
+2084        # We have nothing more to do for non-protocols...
+2085        if not cls._is_protocol:
+2086            return
+2087
+2088        # ... otherwise check consistency of bases, and prohibit instantiation.
+2089        for base in cls.__bases__:
+2090            if not (base in (object, Generic) or
+2091                    base.__module__ in _PROTO_ALLOWLIST and
+2092                    base.__name__ in _PROTO_ALLOWLIST[base.__module__] or
+2093                    issubclass(base, Generic) and base._is_protocol):
+2094                raise TypeError('Protocols can only inherit from other'
+2095                                ' protocols, got %r' % base)
+2096        if cls.__init__ is Protocol.__init__:
+2097            cls.__init__ = _no_init_or_replace_init
+2098
+2099
+2100class _AnnotatedAlias(_NotIterable, _GenericAlias, _root=True):
+2101    """Runtime representation of an annotated type.
+2102
+2103    At its core 'Annotated[t, dec1, dec2, ...]' is an alias for the type 't'
+2104    with extra annotations. The alias behaves like a normal typing alias.
+2105    Instantiating is the same as instantiating the underlying type; binding
+2106    it to types is also the same.
+2107
+2108    The metadata itself is stored in a '__metadata__' attribute as a tuple.
+2109    """
+2110
+2111    def __init__(self, origin, metadata):
+2112        if isinstance(origin, _AnnotatedAlias):
+2113            metadata = origin.__metadata__ + metadata
+2114            origin = origin.__origin__
+2115        super().__init__(origin, origin)
+2116        self.__metadata__ = metadata
 2117
-2118    The metadata itself is stored in a '__metadata__' attribute as a tuple.
-2119    """
-2120
-2121    def __init__(self, origin, metadata):
-2122        if isinstance(origin, _AnnotatedAlias):
-2123            metadata = origin.__metadata__ + metadata
-2124            origin = origin.__origin__
-2125        super().__init__(origin, origin)
-2126        self.__metadata__ = metadata
-2127
-2128    def copy_with(self, params):
-2129        assert len(params) == 1
-2130        new_type = params[0]
-2131        return _AnnotatedAlias(new_type, self.__metadata__)
-2132
-2133    def __repr__(self):
-2134        return "typing.Annotated[{}, {}]".format(
-2135            _type_repr(self.__origin__),
-2136            ", ".join(repr(a) for a in self.__metadata__)
-2137        )
-2138
-2139    def __reduce__(self):
-2140        return operator.getitem, (
-2141            Annotated, (self.__origin__,) + self.__metadata__
-2142        )
-2143
-2144    def __eq__(self, other):
-2145        if not isinstance(other, _AnnotatedAlias):
-2146            return NotImplemented
-2147        return (self.__origin__ == other.__origin__
-2148                and self.__metadata__ == other.__metadata__)
-2149
-2150    def __hash__(self):
-2151        return hash((self.__origin__, self.__metadata__))
-2152
-2153    def __getattr__(self, attr):
-2154        if attr in {'__name__', '__qualname__'}:
-2155            return 'Annotated'
-2156        return super().__getattr__(attr)
-2157
+2118    def copy_with(self, params):
+2119        assert len(params) == 1
+2120        new_type = params[0]
+2121        return _AnnotatedAlias(new_type, self.__metadata__)
+2122
+2123    def __repr__(self):
+2124        return "typing.Annotated[{}, {}]".format(
+2125            _type_repr(self.__origin__),
+2126            ", ".join(repr(a) for a in self.__metadata__)
+2127        )
+2128
+2129    def __reduce__(self):
+2130        return operator.getitem, (
+2131            Annotated, (self.__origin__,) + self.__metadata__
+2132        )
+2133
+2134    def __eq__(self, other):
+2135        if not isinstance(other, _AnnotatedAlias):
+2136            return NotImplemented
+2137        return (self.__origin__ == other.__origin__
+2138                and self.__metadata__ == other.__metadata__)
+2139
+2140    def __hash__(self):
+2141        return hash((self.__origin__, self.__metadata__))
+2142
+2143    def __getattr__(self, attr):
+2144        if attr in {'__name__', '__qualname__'}:
+2145            return 'Annotated'
+2146        return super().__getattr__(attr)
+2147
+2148
+2149class Annotated:
+2150    """Add context-specific metadata to a type.
+2151
+2152    Example: Annotated[int, runtime_check.Unsigned] indicates to the
+2153    hypothetical runtime_check module that this type is an unsigned int.
+2154    Every other consumer of this type can ignore this metadata and treat
+2155    this type as int.
+2156
+2157    The first argument to Annotated must be a valid type.
 2158
-2159class Annotated:
-2160    """Add context-specific metadata to a type.
-2161
-2162    Example: Annotated[int, runtime_check.Unsigned] indicates to the
-2163    hypothetical runtime_check module that this type is an unsigned int.
-2164    Every other consumer of this type can ignore this metadata and treat
-2165    this type as int.
-2166
-2167    The first argument to Annotated must be a valid type.
-2168
-2169    Details:
-2170
-2171    - It's an error to call `Annotated` with less than two arguments.
-2172    - Access the metadata via the ``__metadata__`` attribute::
-2173
-2174        assert Annotated[int, '$'].__metadata__ == ('$',)
-2175
-2176    - Nested Annotated types are flattened::
-2177
-2178        assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
+2159    Details:
+2160
+2161    - It's an error to call `Annotated` with less than two arguments.
+2162    - Access the metadata via the ``__metadata__`` attribute::
+2163
+2164        assert Annotated[int, '$'].__metadata__ == ('$',)
+2165
+2166    - Nested Annotated are flattened::
+2167
+2168        assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
+2169
+2170    - Instantiating an annotated type is equivalent to instantiating the
+2171    underlying type::
+2172
+2173        assert Annotated[C, Ann1](5) == C(5)
+2174
+2175    - Annotated can be used as a generic type alias::
+2176
+2177        Optimized = Annotated[T, runtime.Optimize()]
+2178        assert Optimized[int] == Annotated[int, runtime.Optimize()]
 2179
-2180    - Instantiating an annotated type is equivalent to instantiating the
-2181    underlying type::
+2180        OptimizedList = Annotated[List[T], runtime.Optimize()]
+2181        assert OptimizedList[int] == Annotated[List[int], runtime.Optimize()]
 2182
-2183        assert Annotated[C, Ann1](5) == C(5)
+2183    - Annotated cannot be used with an unpacked TypeVarTuple::
 2184
-2185    - Annotated can be used as a generic type alias::
+2185        Annotated[*Ts, Ann1]  # NOT valid
 2186
-2187        Optimized: TypeAlias = Annotated[T, runtime.Optimize()]
-2188        assert Optimized[int] == Annotated[int, runtime.Optimize()]
-2189
-2190        OptimizedList: TypeAlias = Annotated[list[T], runtime.Optimize()]
-2191        assert OptimizedList[int] == Annotated[list[int], runtime.Optimize()]
-2192
-2193    - Annotated cannot be used with an unpacked TypeVarTuple::
+2187      This would be equivalent to
+2188
+2189        Annotated[T1, T2, T3, ..., Ann1]
+2190
+2191      where T1, T2 etc. are TypeVars, which would be invalid, because
+2192      only one type should be passed to Annotated.
+2193    """
 2194
-2195        Variadic: TypeAlias = Annotated[*Ts, Ann1]  # NOT valid
+2195    __slots__ = ()
 2196
-2197      This would be equivalent to::
-2198
-2199        Annotated[T1, T2, T3, ..., Ann1]
-2200
-2201      where T1, T2 etc. are TypeVars, which would be invalid, because
-2202      only one type should be passed to Annotated.
-2203    """
-2204
-2205    __slots__ = ()
-2206
-2207    def __new__(cls, *args, **kwargs):
-2208        raise TypeError("Type Annotated cannot be instantiated.")
-2209
-2210    @_tp_cache
-2211    def __class_getitem__(cls, params):
-2212        if not isinstance(params, tuple) or len(params) < 2:
-2213            raise TypeError("Annotated[...] should be used "
-2214                            "with at least two arguments (a type and an "
-2215                            "annotation).")
-2216        if _is_unpacked_typevartuple(params[0]):
-2217            raise TypeError("Annotated[...] should not be used with an "
-2218                            "unpacked TypeVarTuple")
-2219        msg = "Annotated[t, ...]: t must be a type."
-2220        origin = _type_check(params[0], msg, allow_special_forms=True)
-2221        metadata = tuple(params[1:])
-2222        return _AnnotatedAlias(origin, metadata)
-2223
-2224    def __init_subclass__(cls, *args, **kwargs):
-2225        raise TypeError(
-2226            "Cannot subclass {}.Annotated".format(cls.__module__)
-2227        )
-2228
+2197    def __new__(cls, *args, **kwargs):
+2198        raise TypeError("Type Annotated cannot be instantiated.")
+2199
+2200    @_tp_cache
+2201    def __class_getitem__(cls, params):
+2202        if not isinstance(params, tuple) or len(params) < 2:
+2203            raise TypeError("Annotated[...] should be used "
+2204                            "with at least two arguments (a type and an "
+2205                            "annotation).")
+2206        if _is_unpacked_typevartuple(params[0]):
+2207            raise TypeError("Annotated[...] should not be used with an "
+2208                            "unpacked TypeVarTuple")
+2209        msg = "Annotated[t, ...]: t must be a type."
+2210        origin = _type_check(params[0], msg, allow_special_forms=True)
+2211        metadata = tuple(params[1:])
+2212        return _AnnotatedAlias(origin, metadata)
+2213
+2214    def __init_subclass__(cls, *args, **kwargs):
+2215        raise TypeError(
+2216            "Cannot subclass {}.Annotated".format(cls.__module__)
+2217        )
+2218
+2219
+2220def runtime_checkable(cls):
+2221    """Mark a protocol class as a runtime protocol.
+2222
+2223    Such protocol can be used with isinstance() and issubclass().
+2224    Raise TypeError if applied to a non-protocol class.
+2225    This allows a simple-minded structural check very similar to
+2226    one trick ponies in collections.abc such as Iterable.
+2227
+2228    For example::
 2229
-2230def runtime_checkable(cls):
-2231    """Mark a protocol class as a runtime protocol.
-2232
-2233    Such protocol can be used with isinstance() and issubclass().
-2234    Raise TypeError if applied to a non-protocol class.
-2235    This allows a simple-minded structural check very similar to
-2236    one trick ponies in collections.abc such as Iterable.
-2237
-2238    For example::
-2239
-2240        @runtime_checkable
-2241        class Closable(Protocol):
-2242            def close(self): ...
-2243
-2244        assert isinstance(open('/some/file'), Closable)
+2230        @runtime_checkable
+2231        class Closable(Protocol):
+2232            def close(self): ...
+2233
+2234        assert isinstance(open('/some/file'), Closable)
+2235
+2236    Warning: this will check only the presence of the required methods,
+2237    not their type signatures!
+2238    """
+2239    if not issubclass(cls, Generic) or not cls._is_protocol:
+2240        raise TypeError('@runtime_checkable can be only applied to protocol classes,'
+2241                        ' got %r' % cls)
+2242    cls._is_runtime_protocol = True
+2243    return cls
+2244
 2245
-2246    Warning: this will check only the presence of the required methods,
-2247    not their type signatures!
-2248    """
-2249    if not issubclass(cls, Generic) or not cls._is_protocol:
-2250        raise TypeError('@runtime_checkable can be only applied to protocol classes,'
-2251                        ' got %r' % cls)
-2252    cls._is_runtime_protocol = True
-2253    return cls
-2254
+2246def cast(typ, val):
+2247    """Cast a value to a type.
+2248
+2249    This returns the value unchanged.  To the type checker this
+2250    signals that the return value has the designated type, but at
+2251    runtime we intentionally don't check anything (we want this
+2252    to be as fast as possible).
+2253    """
+2254    return val
 2255
-2256def cast(typ, val):
-2257    """Cast a value to a type.
-2258
-2259    This returns the value unchanged.  To the type checker this
-2260    signals that the return value has the designated type, but at
-2261    runtime we intentionally don't check anything (we want this
-2262    to be as fast as possible).
-2263    """
-2264    return val
+2256
+2257def assert_type(val, typ, /):
+2258    """Ask a static type checker to confirm that the value is of the given type.
+2259
+2260    At runtime this does nothing: it returns the first argument unchanged with no
+2261    checks or side effects, no matter the actual type of the argument.
+2262
+2263    When a static type checker encounters a call to assert_type(), it
+2264    emits an error if the value is not of the specified type::
 2265
-2266
-2267def assert_type(val, typ, /):
-2268    """Ask a static type checker to confirm that the value is of the given type.
-2269
-2270    At runtime this does nothing: it returns the first argument unchanged with no
-2271    checks or side effects, no matter the actual type of the argument.
+2266        def greet(name: str) -> None:
+2267            assert_type(name, str)  # ok
+2268            assert_type(name, int)  # type checker error
+2269    """
+2270    return val
+2271
 2272
-2273    When a static type checker encounters a call to assert_type(), it
-2274    emits an error if the value is not of the specified type::
-2275
-2276        def greet(name: str) -> None:
-2277            assert_type(name, str)  # OK
-2278            assert_type(name, int)  # type checker error
-2279    """
-2280    return val
-2281
-2282
-2283_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
-2284                  types.MethodType, types.ModuleType,
-2285                  WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
-2286
-2287
-2288def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
-2289    """Return type hints for an object.
-2290
-2291    This is often the same as obj.__annotations__, but it handles
-2292    forward references encoded as string literals and recursively replaces all
-2293    'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
-2294
-2295    The argument may be a module, class, method, or function. The annotations
-2296    are returned as a dictionary. For classes, annotations include also
-2297    inherited members.
-2298
-2299    TypeError is raised if the argument is not of a type that can contain
-2300    annotations, and an empty dictionary is returned if no annotations are
-2301    present.
+2273_allowed_types = (types.FunctionType, types.BuiltinFunctionType,
+2274                  types.MethodType, types.ModuleType,
+2275                  WrapperDescriptorType, MethodWrapperType, MethodDescriptorType)
+2276
+2277
+2278def get_type_hints(obj, globalns=None, localns=None, include_extras=False):
+2279    """Return type hints for an object.
+2280
+2281    This is often the same as obj.__annotations__, but it handles
+2282    forward references encoded as string literals and recursively replaces all
+2283    'Annotated[T, ...]' with 'T' (unless 'include_extras=True').
+2284
+2285    The argument may be a module, class, method, or function. The annotations
+2286    are returned as a dictionary. For classes, annotations include also
+2287    inherited members.
+2288
+2289    TypeError is raised if the argument is not of a type that can contain
+2290    annotations, and an empty dictionary is returned if no annotations are
+2291    present.
+2292
+2293    BEWARE -- the behavior of globalns and localns is counterintuitive
+2294    (unless you are familiar with how eval() and exec() work).  The
+2295    search order is locals first, then globals.
+2296
+2297    - If no dict arguments are passed, an attempt is made to use the
+2298      globals from obj (or the respective module's globals for classes),
+2299      and these are also used as the locals.  If the object does not appear
+2300      to have globals, an empty dictionary is used.  For classes, the search
+2301      order is globals first then locals.
 2302
-2303    BEWARE -- the behavior of globalns and localns is counterintuitive
-2304    (unless you are familiar with how eval() and exec() work).  The
-2305    search order is locals first, then globals.
-2306
-2307    - If no dict arguments are passed, an attempt is made to use the
-2308      globals from obj (or the respective module's globals for classes),
-2309      and these are also used as the locals.  If the object does not appear
-2310      to have globals, an empty dictionary is used.  For classes, the search
-2311      order is globals first then locals.
-2312
-2313    - If one dict argument is passed, it is used for both globals and
-2314      locals.
-2315
-2316    - If two dict arguments are passed, they specify globals and
-2317      locals, respectively.
-2318    """
-2319    if getattr(obj, '__no_type_check__', None):
-2320        return {}
-2321    # Classes require a special treatment.
-2322    if isinstance(obj, type):
-2323        hints = {}
-2324        for base in reversed(obj.__mro__):
-2325            if globalns is None:
-2326                base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {})
-2327            else:
-2328                base_globals = globalns
-2329            ann = base.__dict__.get('__annotations__', {})
-2330            if isinstance(ann, types.GetSetDescriptorType):
-2331                ann = {}
-2332            base_locals = dict(vars(base)) if localns is None else localns
-2333            if localns is None and globalns is None:
-2334                # This is surprising, but required.  Before Python 3.10,
-2335                # get_type_hints only evaluated the globalns of
-2336                # a class.  To maintain backwards compatibility, we reverse
-2337                # the globalns and localns order so that eval() looks into
-2338                # *base_globals* first rather than *base_locals*.
-2339                # This only affects ForwardRefs.
-2340                base_globals, base_locals = base_locals, base_globals
-2341            for name, value in ann.items():
-2342                if value is None:
-2343                    value = type(None)
-2344                if isinstance(value, str):
-2345                    value = ForwardRef(value, is_argument=False, is_class=True)
-2346                value = _eval_type(value, base_globals, base_locals)
-2347                hints[name] = value
-2348        return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
-2349
-2350    if globalns is None:
-2351        if isinstance(obj, types.ModuleType):
-2352            globalns = obj.__dict__
-2353        else:
-2354            nsobj = obj
-2355            # Find globalns for the unwrapped object.
-2356            while hasattr(nsobj, '__wrapped__'):
-2357                nsobj = nsobj.__wrapped__
-2358            globalns = getattr(nsobj, '__globals__', {})
-2359        if localns is None:
-2360            localns = globalns
-2361    elif localns is None:
-2362        localns = globalns
-2363    hints = getattr(obj, '__annotations__', None)
-2364    if hints is None:
-2365        # Return empty annotations for something that _could_ have them.
-2366        if isinstance(obj, _allowed_types):
-2367            return {}
-2368        else:
-2369            raise TypeError('{!r} is not a module, class, method, '
-2370                            'or function.'.format(obj))
-2371    hints = dict(hints)
-2372    for name, value in hints.items():
-2373        if value is None:
-2374            value = type(None)
-2375        if isinstance(value, str):
-2376            # class-level forward refs were handled above, this must be either
-2377            # a module-level annotation or a function argument annotation
-2378            value = ForwardRef(
-2379                value,
-2380                is_argument=not isinstance(obj, types.ModuleType),
-2381                is_class=False,
-2382            )
-2383        hints[name] = _eval_type(value, globalns, localns)
-2384    return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
-2385
-2386
-2387def _strip_annotations(t):
-2388    """Strip the annotations from a given type."""
-2389    if isinstance(t, _AnnotatedAlias):
-2390        return _strip_annotations(t.__origin__)
-2391    if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired):
-2392        return _strip_annotations(t.__args__[0])
-2393    if isinstance(t, _GenericAlias):
+2303    - If one dict argument is passed, it is used for both globals and
+2304      locals.
+2305
+2306    - If two dict arguments are passed, they specify globals and
+2307      locals, respectively.
+2308    """
+2309    if getattr(obj, '__no_type_check__', None):
+2310        return {}
+2311    # Classes require a special treatment.
+2312    if isinstance(obj, type):
+2313        hints = {}
+2314        for base in reversed(obj.__mro__):
+2315            if globalns is None:
+2316                base_globals = getattr(sys.modules.get(base.__module__, None), '__dict__', {})
+2317            else:
+2318                base_globals = globalns
+2319            ann = base.__dict__.get('__annotations__', {})
+2320            if isinstance(ann, types.GetSetDescriptorType):
+2321                ann = {}
+2322            base_locals = dict(vars(base)) if localns is None else localns
+2323            if localns is None and globalns is None:
+2324                # This is surprising, but required.  Before Python 3.10,
+2325                # get_type_hints only evaluated the globalns of
+2326                # a class.  To maintain backwards compatibility, we reverse
+2327                # the globalns and localns order so that eval() looks into
+2328                # *base_globals* first rather than *base_locals*.
+2329                # This only affects ForwardRefs.
+2330                base_globals, base_locals = base_locals, base_globals
+2331            for name, value in ann.items():
+2332                if value is None:
+2333                    value = type(None)
+2334                if isinstance(value, str):
+2335                    value = ForwardRef(value, is_argument=False, is_class=True)
+2336                value = _eval_type(value, base_globals, base_locals)
+2337                hints[name] = value
+2338        return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
+2339
+2340    if globalns is None:
+2341        if isinstance(obj, types.ModuleType):
+2342            globalns = obj.__dict__
+2343        else:
+2344            nsobj = obj
+2345            # Find globalns for the unwrapped object.
+2346            while hasattr(nsobj, '__wrapped__'):
+2347                nsobj = nsobj.__wrapped__
+2348            globalns = getattr(nsobj, '__globals__', {})
+2349        if localns is None:
+2350            localns = globalns
+2351    elif localns is None:
+2352        localns = globalns
+2353    hints = getattr(obj, '__annotations__', None)
+2354    if hints is None:
+2355        # Return empty annotations for something that _could_ have them.
+2356        if isinstance(obj, _allowed_types):
+2357            return {}
+2358        else:
+2359            raise TypeError('{!r} is not a module, class, method, '
+2360                            'or function.'.format(obj))
+2361    hints = dict(hints)
+2362    for name, value in hints.items():
+2363        if value is None:
+2364            value = type(None)
+2365        if isinstance(value, str):
+2366            # class-level forward refs were handled above, this must be either
+2367            # a module-level annotation or a function argument annotation
+2368            value = ForwardRef(
+2369                value,
+2370                is_argument=not isinstance(obj, types.ModuleType),
+2371                is_class=False,
+2372            )
+2373        hints[name] = _eval_type(value, globalns, localns)
+2374    return hints if include_extras else {k: _strip_annotations(t) for k, t in hints.items()}
+2375
+2376
+2377def _strip_annotations(t):
+2378    """Strip the annotations from a given type."""
+2379    if isinstance(t, _AnnotatedAlias):
+2380        return _strip_annotations(t.__origin__)
+2381    if hasattr(t, "__origin__") and t.__origin__ in (Required, NotRequired):
+2382        return _strip_annotations(t.__args__[0])
+2383    if isinstance(t, _GenericAlias):
+2384        stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
+2385        if stripped_args == t.__args__:
+2386            return t
+2387        return t.copy_with(stripped_args)
+2388    if isinstance(t, GenericAlias):
+2389        stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
+2390        if stripped_args == t.__args__:
+2391            return t
+2392        return GenericAlias(t.__origin__, stripped_args)
+2393    if isinstance(t, types.UnionType):
 2394        stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
 2395        if stripped_args == t.__args__:
 2396            return t
-2397        return t.copy_with(stripped_args)
-2398    if isinstance(t, GenericAlias):
-2399        stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
-2400        if stripped_args == t.__args__:
-2401            return t
-2402        return GenericAlias(t.__origin__, stripped_args)
-2403    if isinstance(t, types.UnionType):
-2404        stripped_args = tuple(_strip_annotations(a) for a in t.__args__)
-2405        if stripped_args == t.__args__:
-2406            return t
-2407        return functools.reduce(operator.or_, stripped_args)
-2408
-2409    return t
-2410
-2411
-2412def get_origin(tp):
-2413    """Get the unsubscripted version of a type.
-2414
-2415    This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar,
-2416    Annotated, and others. Return None for unsupported types.
-2417
-2418    Examples::
-2419
-2420        assert get_origin(Literal[42]) is Literal
-2421        assert get_origin(int) is None
-2422        assert get_origin(ClassVar[int]) is ClassVar
-2423        assert get_origin(Generic) is Generic
-2424        assert get_origin(Generic[T]) is Generic
-2425        assert get_origin(Union[T, int]) is Union
-2426        assert get_origin(List[Tuple[T, T]][int]) is list
-2427        assert get_origin(P.args) is P
-2428    """
-2429    if isinstance(tp, _AnnotatedAlias):
-2430        return Annotated
-2431    if isinstance(tp, (_BaseGenericAlias, GenericAlias,
-2432                       ParamSpecArgs, ParamSpecKwargs)):
-2433        return tp.__origin__
-2434    if tp is Generic:
-2435        return Generic
-2436    if isinstance(tp, types.UnionType):
-2437        return types.UnionType
-2438    return None
-2439
-2440
-2441def get_args(tp):
-2442    """Get type arguments with all substitutions performed.
-2443
-2444    For unions, basic simplifications used by Union constructor are performed.
-2445
-2446    Examples::
-2447
-2448        assert get_args(Dict[str, int]) == (str, int)
-2449        assert get_args(int) == ()
-2450        assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
-2451        assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
-2452        assert get_args(Callable[[], T][int]) == ([], int)
-2453    """
-2454    if isinstance(tp, _AnnotatedAlias):
-2455        return (tp.__origin__,) + tp.__metadata__
-2456    if isinstance(tp, (_GenericAlias, GenericAlias)):
-2457        res = tp.__args__
-2458        if _should_unflatten_callable_args(tp, res):
-2459            res = (list(res[:-1]), res[-1])
-2460        return res
-2461    if isinstance(tp, types.UnionType):
-2462        return tp.__args__
-2463    return ()
-2464
-2465
-2466def is_typeddict(tp):
-2467    """Check if an annotation is a TypedDict class.
+2397        return functools.reduce(operator.or_, stripped_args)
+2398
+2399    return t
+2400
+2401
+2402def get_origin(tp):
+2403    """Get the unsubscripted version of a type.
+2404
+2405    This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar
+2406    Annotated, and others. Return None for unsupported types. Examples::
+2407
+2408        assert get_origin(Literal[42]) is Literal
+2409        assert get_origin(int) is None
+2410        assert get_origin(ClassVar[int]) is ClassVar
+2411        assert get_origin(Generic) is Generic
+2412        assert get_origin(Generic[T]) is Generic
+2413        assert get_origin(Union[T, int]) is Union
+2414        assert get_origin(List[Tuple[T, T]][int]) is list
+2415        assert get_origin(P.args) is P
+2416    """
+2417    if isinstance(tp, _AnnotatedAlias):
+2418        return Annotated
+2419    if isinstance(tp, (_BaseGenericAlias, GenericAlias,
+2420                       ParamSpecArgs, ParamSpecKwargs)):
+2421        return tp.__origin__
+2422    if tp is Generic:
+2423        return Generic
+2424    if isinstance(tp, types.UnionType):
+2425        return types.UnionType
+2426    return None
+2427
+2428
+2429def get_args(tp):
+2430    """Get type arguments with all substitutions performed.
+2431
+2432    For unions, basic simplifications used by Union constructor are performed.
+2433
+2434    Examples::
+2435
+2436        assert get_args(Dict[str, int]) == (str, int)
+2437        assert get_args(int) == ()
+2438        assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
+2439        assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
+2440        assert get_args(Callable[[], T][int]) == ([], int)
+2441    """
+2442    if isinstance(tp, _AnnotatedAlias):
+2443        return (tp.__origin__,) + tp.__metadata__
+2444    if isinstance(tp, (_GenericAlias, GenericAlias)):
+2445        res = tp.__args__
+2446        if _should_unflatten_callable_args(tp, res):
+2447            res = (list(res[:-1]), res[-1])
+2448        return res
+2449    if isinstance(tp, types.UnionType):
+2450        return tp.__args__
+2451    return ()
+2452
+2453
+2454def is_typeddict(tp):
+2455    """Check if an annotation is a TypedDict class.
+2456
+2457    For example::
+2458
+2459        class Film(TypedDict):
+2460            title: str
+2461            year: int
+2462
+2463        is_typeddict(Film)              # => True
+2464        is_typeddict(Union[list, str])  # => False
+2465    """
+2466    return isinstance(tp, _TypedDictMeta)
+2467
 2468
-2469    For example::
+2469_ASSERT_NEVER_REPR_MAX_LENGTH = 100
 2470
-2471        class Film(TypedDict):
-2472            title: str
-2473            year: int
+2471
+2472def assert_never(arg: Never, /) -> Never:
+2473    """Statically assert that a line of code is unreachable.
 2474
-2475        is_typeddict(Film)              # => True
-2476        is_typeddict(Union[list, str])  # => False
-2477    """
-2478    return isinstance(tp, _TypedDictMeta)
-2479
-2480
-2481_ASSERT_NEVER_REPR_MAX_LENGTH = 100
-2482
-2483
-2484def assert_never(arg: Never, /) -> Never:
-2485    """Statically assert that a line of code is unreachable.
-2486
-2487    Example::
+2475    Example::
+2476
+2477        def int_or_str(arg: int | str) -> None:
+2478            match arg:
+2479                case int():
+2480                    print("It's an int")
+2481                case str():
+2482                    print("It's a str")
+2483                case _:
+2484                    assert_never(arg)
+2485
+2486    If a type checker finds that a call to assert_never() is
+2487    reachable, it will emit an error.
 2488
-2489        def int_or_str(arg: int | str) -> None:
-2490            match arg:
-2491                case int():
-2492                    print("It's an int")
-2493                case str():
-2494                    print("It's a str")
-2495                case _:
-2496                    assert_never(arg)
-2497
-2498    If a type checker finds that a call to assert_never() is
-2499    reachable, it will emit an error.
-2500
-2501    At runtime, this throws an exception when called.
-2502    """
-2503    value = repr(arg)
-2504    if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
-2505        value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...'
-2506    raise AssertionError(f"Expected code to be unreachable, but got: {value}")
-2507
-2508
-2509def no_type_check(arg):
-2510    """Decorator to indicate that annotations are not type hints.
-2511
-2512    The argument must be a class or function; if it is a class, it
-2513    applies recursively to all methods and classes defined in that class
-2514    (but not to methods defined in its superclasses or subclasses).
-2515
-2516    This mutates the function(s) or class(es) in place.
-2517    """
-2518    if isinstance(arg, type):
-2519        for key in dir(arg):
-2520            obj = getattr(arg, key)
-2521            if (
-2522                not hasattr(obj, '__qualname__')
-2523                or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}'
-2524                or getattr(obj, '__module__', None) != arg.__module__
-2525            ):
-2526                # We only modify objects that are defined in this type directly.
-2527                # If classes / methods are nested in multiple layers,
-2528                # we will modify them when processing their direct holders.
-2529                continue
-2530            # Instance, class, and static methods:
-2531            if isinstance(obj, types.FunctionType):
-2532                obj.__no_type_check__ = True
-2533            if isinstance(obj, types.MethodType):
-2534                obj.__func__.__no_type_check__ = True
-2535            # Nested types:
-2536            if isinstance(obj, type):
-2537                no_type_check(obj)
-2538    try:
-2539        arg.__no_type_check__ = True
-2540    except TypeError:  # built-in classes
-2541        pass
-2542    return arg
-2543
+2489    At runtime, this throws an exception when called.
+2490    """
+2491    value = repr(arg)
+2492    if len(value) > _ASSERT_NEVER_REPR_MAX_LENGTH:
+2493        value = value[:_ASSERT_NEVER_REPR_MAX_LENGTH] + '...'
+2494    raise AssertionError(f"Expected code to be unreachable, but got: {value}")
+2495
+2496
+2497def no_type_check(arg):
+2498    """Decorator to indicate that annotations are not type hints.
+2499
+2500    The argument must be a class or function; if it is a class, it
+2501    applies recursively to all methods and classes defined in that class
+2502    (but not to methods defined in its superclasses or subclasses).
+2503
+2504    This mutates the function(s) or class(es) in place.
+2505    """
+2506    if isinstance(arg, type):
+2507        for key in dir(arg):
+2508            obj = getattr(arg, key)
+2509            if (
+2510                not hasattr(obj, '__qualname__')
+2511                or obj.__qualname__ != f'{arg.__qualname__}.{obj.__name__}'
+2512                or getattr(obj, '__module__', None) != arg.__module__
+2513            ):
+2514                # We only modify objects that are defined in this type directly.
+2515                # If classes / methods are nested in multiple layers,
+2516                # we will modify them when processing their direct holders.
+2517                continue
+2518            # Instance, class, and static methods:
+2519            if isinstance(obj, types.FunctionType):
+2520                obj.__no_type_check__ = True
+2521            if isinstance(obj, types.MethodType):
+2522                obj.__func__.__no_type_check__ = True
+2523            # Nested types:
+2524            if isinstance(obj, type):
+2525                no_type_check(obj)
+2526    try:
+2527        arg.__no_type_check__ = True
+2528    except TypeError:  # built-in classes
+2529        pass
+2530    return arg
+2531
+2532
+2533def no_type_check_decorator(decorator):
+2534    """Decorator to give another decorator the @no_type_check effect.
+2535
+2536    This wraps the decorator with something that wraps the decorated
+2537    function in @no_type_check.
+2538    """
+2539    @functools.wraps(decorator)
+2540    def wrapped_decorator(*args, **kwds):
+2541        func = decorator(*args, **kwds)
+2542        func = no_type_check(func)
+2543        return func
 2544
-2545def no_type_check_decorator(decorator):
-2546    """Decorator to give another decorator the @no_type_check effect.
+2545    return wrapped_decorator
+2546
 2547
-2548    This wraps the decorator with something that wraps the decorated
-2549    function in @no_type_check.
-2550    """
-2551    @functools.wraps(decorator)
-2552    def wrapped_decorator(*args, **kwds):
-2553        func = decorator(*args, **kwds)
-2554        func = no_type_check(func)
-2555        return func
+2548def _overload_dummy(*args, **kwds):
+2549    """Helper for @overload to raise when called."""
+2550    raise NotImplementedError(
+2551        "You should not call an overloaded function. "
+2552        "A series of @overload-decorated functions "
+2553        "outside a stub module should always be followed "
+2554        "by an implementation that is not @overload-ed.")
+2555
 2556
-2557    return wrapped_decorator
-2558
+2557# {module: {qualname: {firstlineno: func}}}
+2558_overload_registry = defaultdict(functools.partial(defaultdict, dict))
 2559
-2560def _overload_dummy(*args, **kwds):
-2561    """Helper for @overload to raise when called."""
-2562    raise NotImplementedError(
-2563        "You should not call an overloaded function. "
-2564        "A series of @overload-decorated functions "
-2565        "outside a stub module should always be followed "
-2566        "by an implementation that is not @overload-ed.")
-2567
-2568
-2569# {module: {qualname: {firstlineno: func}}}
-2570_overload_registry = defaultdict(functools.partial(defaultdict, dict))
-2571
-2572
-2573def overload(func):
-2574    """Decorator for overloaded functions/methods.
-2575
-2576    In a stub file, place two or more stub definitions for the same
-2577    function in a row, each decorated with @overload.
-2578
-2579    For example::
-2580
-2581        @overload
-2582        def utf8(value: None) -> None: ...
-2583        @overload
-2584        def utf8(value: bytes) -> bytes: ...
-2585        @overload
-2586        def utf8(value: str) -> bytes: ...
-2587
-2588    In a non-stub file (i.e. a regular .py file), do the same but
-2589    follow it with an implementation.  The implementation should *not*
-2590    be decorated with @overload::
-2591
-2592        @overload
-2593        def utf8(value: None) -> None: ...
-2594        @overload
-2595        def utf8(value: bytes) -> bytes: ...
-2596        @overload
-2597        def utf8(value: str) -> bytes: ...
-2598        def utf8(value):
-2599            ...  # implementation goes here
-2600
-2601    The overloads for a function can be retrieved at runtime using the
-2602    get_overloads() function.
-2603    """
-2604    # classmethod and staticmethod
-2605    f = getattr(func, "__func__", func)
-2606    try:
-2607        _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func
-2608    except AttributeError:
-2609        # Not a normal function; ignore.
-2610        pass
-2611    return _overload_dummy
-2612
-2613
-2614def get_overloads(func):
-2615    """Return all defined overloads for *func* as a sequence."""
-2616    # classmethod and staticmethod
-2617    f = getattr(func, "__func__", func)
-2618    if f.__module__ not in _overload_registry:
-2619        return []
-2620    mod_dict = _overload_registry[f.__module__]
-2621    if f.__qualname__ not in mod_dict:
-2622        return []
-2623    return list(mod_dict[f.__qualname__].values())
+2560
+2561def overload(func):
+2562    """Decorator for overloaded functions/methods.
+2563
+2564    In a stub file, place two or more stub definitions for the same
+2565    function in a row, each decorated with @overload.  For example::
+2566
+2567        @overload
+2568        def utf8(value: None) -> None: ...
+2569        @overload
+2570        def utf8(value: bytes) -> bytes: ...
+2571        @overload
+2572        def utf8(value: str) -> bytes: ...
+2573
+2574    In a non-stub file (i.e. a regular .py file), do the same but
+2575    follow it with an implementation.  The implementation should *not*
+2576    be decorated with @overload.  For example::
+2577
+2578        @overload
+2579        def utf8(value: None) -> None: ...
+2580        @overload
+2581        def utf8(value: bytes) -> bytes: ...
+2582        @overload
+2583        def utf8(value: str) -> bytes: ...
+2584        def utf8(value):
+2585            ...  # implementation goes here
+2586
+2587    The overloads for a function can be retrieved at runtime using the
+2588    get_overloads() function.
+2589    """
+2590    # classmethod and staticmethod
+2591    f = getattr(func, "__func__", func)
+2592    try:
+2593        _overload_registry[f.__module__][f.__qualname__][f.__code__.co_firstlineno] = func
+2594    except AttributeError:
+2595        # Not a normal function; ignore.
+2596        pass
+2597    return _overload_dummy
+2598
+2599
+2600def get_overloads(func):
+2601    """Return all defined overloads for *func* as a sequence."""
+2602    # classmethod and staticmethod
+2603    f = getattr(func, "__func__", func)
+2604    if f.__module__ not in _overload_registry:
+2605        return []
+2606    mod_dict = _overload_registry[f.__module__]
+2607    if f.__qualname__ not in mod_dict:
+2608        return []
+2609    return list(mod_dict[f.__qualname__].values())
+2610
+2611
+2612def clear_overloads():
+2613    """Clear all overloads in the registry."""
+2614    _overload_registry.clear()
+2615
+2616
+2617def final(f):
+2618    """Decorator to indicate final methods and final classes.
+2619
+2620    Use this decorator to indicate to type checkers that the decorated
+2621    method cannot be overridden, and decorated class cannot be subclassed.
+2622
+2623    For example::
 2624
-2625
-2626def clear_overloads():
-2627    """Clear all overloads in the registry."""
-2628    _overload_registry.clear()
-2629
-2630
-2631def final(f):
-2632    """Decorator to indicate final methods and final classes.
-2633
-2634    Use this decorator to indicate to type checkers that the decorated
-2635    method cannot be overridden, and decorated class cannot be subclassed.
-2636
-2637    For example::
+2625        class Base:
+2626            @final
+2627            def done(self) -> None:
+2628                ...
+2629        class Sub(Base):
+2630            def done(self) -> None:  # Error reported by type checker
+2631                ...
+2632
+2633        @final
+2634        class Leaf:
+2635            ...
+2636        class Other(Leaf):  # Error reported by type checker
+2637            ...
 2638
-2639        class Base:
-2640            @final
-2641            def done(self) -> None:
-2642                ...
-2643        class Sub(Base):
-2644            def done(self) -> None:  # Error reported by type checker
-2645                ...
-2646
-2647        @final
-2648        class Leaf:
-2649            ...
-2650        class Other(Leaf):  # Error reported by type checker
-2651            ...
+2639    There is no runtime checking of these properties. The decorator
+2640    attempts to set the ``__final__`` attribute to ``True`` on the decorated
+2641    object to allow runtime introspection.
+2642    """
+2643    try:
+2644        f.__final__ = True
+2645    except (AttributeError, TypeError):
+2646        # Skip the attribute silently if it is not writable.
+2647        # AttributeError happens if the object has __slots__ or a
+2648        # read-only property, TypeError if it's a builtin class.
+2649        pass
+2650    return f
+2651
 2652
-2653    There is no runtime checking of these properties. The decorator
-2654    attempts to set the ``__final__`` attribute to ``True`` on the decorated
-2655    object to allow runtime introspection.
-2656    """
-2657    try:
-2658        f.__final__ = True
-2659    except (AttributeError, TypeError):
-2660        # Skip the attribute silently if it is not writable.
-2661        # AttributeError happens if the object has __slots__ or a
-2662        # read-only property, TypeError if it's a builtin class.
-2663        pass
-2664    return f
-2665
-2666
-2667# Some unconstrained type variables.  These are used by the container types.
-2668# (These are not for export.)
-2669T = TypeVar('T')  # Any type.
-2670KT = TypeVar('KT')  # Key type.
-2671VT = TypeVar('VT')  # Value type.
-2672T_co = TypeVar('T_co', covariant=True)  # Any type covariant containers.
-2673V_co = TypeVar('V_co', covariant=True)  # Any type covariant containers.
-2674VT_co = TypeVar('VT_co', covariant=True)  # Value type covariant containers.
-2675T_contra = TypeVar('T_contra', contravariant=True)  # Ditto contravariant.
-2676# Internal type variable used for Type[].
-2677CT_co = TypeVar('CT_co', covariant=True, bound=type)
-2678
-2679# A useful type variable with constraints.  This represents string types.
-2680# (This one *is* for export!)
-2681AnyStr = TypeVar('AnyStr', bytes, str)
-2682
-2683
-2684# Various ABCs mimicking those in collections.abc.
-2685_alias = _SpecialGenericAlias
-2686
-2687Hashable = _alias(collections.abc.Hashable, 0)  # Not generic.
-2688Awaitable = _alias(collections.abc.Awaitable, 1)
-2689Coroutine = _alias(collections.abc.Coroutine, 3)
-2690AsyncIterable = _alias(collections.abc.AsyncIterable, 1)
-2691AsyncIterator = _alias(collections.abc.AsyncIterator, 1)
-2692Iterable = _alias(collections.abc.Iterable, 1)
-2693Iterator = _alias(collections.abc.Iterator, 1)
-2694Reversible = _alias(collections.abc.Reversible, 1)
-2695Sized = _alias(collections.abc.Sized, 0)  # Not generic.
-2696Container = _alias(collections.abc.Container, 1)
-2697Collection = _alias(collections.abc.Collection, 1)
-2698Callable = _CallableType(collections.abc.Callable, 2)
-2699Callable.__doc__ = \
-2700    """Deprecated alias to collections.abc.Callable.
-2701
-2702    Callable[[int], str] signifies a function that takes a single
-2703    parameter of type int and returns a str.
-2704
-2705    The subscription syntax must always be used with exactly two
-2706    values: the argument list and the return type.
-2707    The argument list must be a list of types, a ParamSpec,
-2708    Concatenate or ellipsis. The return type must be a single type.
+2653# Some unconstrained type variables.  These are used by the container types.
+2654# (These are not for export.)
+2655T = TypeVar('T')  # Any type.
+2656KT = TypeVar('KT')  # Key type.
+2657VT = TypeVar('VT')  # Value type.
+2658T_co = TypeVar('T_co', covariant=True)  # Any type covariant containers.
+2659V_co = TypeVar('V_co', covariant=True)  # Any type covariant containers.
+2660VT_co = TypeVar('VT_co', covariant=True)  # Value type covariant containers.
+2661T_contra = TypeVar('T_contra', contravariant=True)  # Ditto contravariant.
+2662# Internal type variable used for Type[].
+2663CT_co = TypeVar('CT_co', covariant=True, bound=type)
+2664
+2665# A useful type variable with constraints.  This represents string types.
+2666# (This one *is* for export!)
+2667AnyStr = TypeVar('AnyStr', bytes, str)
+2668
+2669
+2670# Various ABCs mimicking those in collections.abc.
+2671_alias = _SpecialGenericAlias
+2672
+2673Hashable = _alias(collections.abc.Hashable, 0)  # Not generic.
+2674Awaitable = _alias(collections.abc.Awaitable, 1)
+2675Coroutine = _alias(collections.abc.Coroutine, 3)
+2676AsyncIterable = _alias(collections.abc.AsyncIterable, 1)
+2677AsyncIterator = _alias(collections.abc.AsyncIterator, 1)
+2678Iterable = _alias(collections.abc.Iterable, 1)
+2679Iterator = _alias(collections.abc.Iterator, 1)
+2680Reversible = _alias(collections.abc.Reversible, 1)
+2681Sized = _alias(collections.abc.Sized, 0)  # Not generic.
+2682Container = _alias(collections.abc.Container, 1)
+2683Collection = _alias(collections.abc.Collection, 1)
+2684Callable = _CallableType(collections.abc.Callable, 2)
+2685Callable.__doc__ = \
+2686    """Deprecated alias to collections.abc.Callable.
+2687
+2688    Callable[[int], str] signifies a function of (int) -> str.
+2689    The subscription syntax must always be used with exactly two
+2690    values: the argument list and the return type.
+2691    The argument list must be a list of types, a ParamSpec or ellipsis.
+2692    The return type must be a single type.
+2693
+2694    There is no syntax to indicate optional or keyword arguments;
+2695    such function types are rarely used as callback types.
+2696    """
+2697AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet')
+2698MutableSet = _alias(collections.abc.MutableSet, 1)
+2699# NOTE: Mapping is only covariant in the value type.
+2700Mapping = _alias(collections.abc.Mapping, 2)
+2701MutableMapping = _alias(collections.abc.MutableMapping, 2)
+2702Sequence = _alias(collections.abc.Sequence, 1)
+2703MutableSequence = _alias(collections.abc.MutableSequence, 1)
+2704ByteString = _alias(collections.abc.ByteString, 0)  # Not generic
+2705# Tuple accepts variable number of parameters.
+2706Tuple = _TupleType(tuple, -1, inst=False, name='Tuple')
+2707Tuple.__doc__ = \
+2708    """Deprecated alias to builtins.tuple.
 2709
-2710    There is no syntax to indicate optional or keyword arguments;
-2711    such function types are rarely used as callback types.
-2712    """
-2713AbstractSet = _alias(collections.abc.Set, 1, name='AbstractSet')
-2714MutableSet = _alias(collections.abc.MutableSet, 1)
-2715# NOTE: Mapping is only covariant in the value type.
-2716Mapping = _alias(collections.abc.Mapping, 2)
-2717MutableMapping = _alias(collections.abc.MutableMapping, 2)
-2718Sequence = _alias(collections.abc.Sequence, 1)
-2719MutableSequence = _alias(collections.abc.MutableSequence, 1)
-2720ByteString = _alias(collections.abc.ByteString, 0)  # Not generic
-2721# Tuple accepts variable number of parameters.
-2722Tuple = _TupleType(tuple, -1, inst=False, name='Tuple')
-2723Tuple.__doc__ = \
-2724    """Deprecated alias to builtins.tuple.
-2725
-2726    Tuple[X, Y] is the cross-product type of X and Y.
-2727
-2728    Example: Tuple[T1, T2] is a tuple of two elements corresponding
-2729    to type variables T1 and T2.  Tuple[int, float, str] is a tuple
-2730    of an int, a float and a string.
-2731
-2732    To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
-2733    """
-2734List = _alias(list, 1, inst=False, name='List')
-2735Deque = _alias(collections.deque, 1, name='Deque')
-2736Set = _alias(set, 1, inst=False, name='Set')
-2737FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet')
-2738MappingView = _alias(collections.abc.MappingView, 1)
-2739KeysView = _alias(collections.abc.KeysView, 1)
-2740ItemsView = _alias(collections.abc.ItemsView, 2)
-2741ValuesView = _alias(collections.abc.ValuesView, 1)
-2742ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager')
-2743AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager')
-2744Dict = _alias(dict, 2, inst=False, name='Dict')
-2745DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict')
-2746OrderedDict = _alias(collections.OrderedDict, 2)
-2747Counter = _alias(collections.Counter, 1)
-2748ChainMap = _alias(collections.ChainMap, 2)
-2749Generator = _alias(collections.abc.Generator, 3)
-2750AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2)
-2751Type = _alias(type, 1, inst=False, name='Type')
-2752Type.__doc__ = \
-2753    """Deprecated alias to builtins.type.
-2754
-2755    builtins.type or typing.Type can be used to annotate class objects.
-2756    For example, suppose we have the following classes::
+2710    Tuple[X, Y] is the cross-product type of X and Y.
+2711
+2712    Example: Tuple[T1, T2] is a tuple of two elements corresponding
+2713    to type variables T1 and T2.  Tuple[int, float, str] is a tuple
+2714    of an int, a float and a string.
+2715
+2716    To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
+2717    """
+2718List = _alias(list, 1, inst=False, name='List')
+2719Deque = _alias(collections.deque, 1, name='Deque')
+2720Set = _alias(set, 1, inst=False, name='Set')
+2721FrozenSet = _alias(frozenset, 1, inst=False, name='FrozenSet')
+2722MappingView = _alias(collections.abc.MappingView, 1)
+2723KeysView = _alias(collections.abc.KeysView, 1)
+2724ItemsView = _alias(collections.abc.ItemsView, 2)
+2725ValuesView = _alias(collections.abc.ValuesView, 1)
+2726ContextManager = _alias(contextlib.AbstractContextManager, 1, name='ContextManager')
+2727AsyncContextManager = _alias(contextlib.AbstractAsyncContextManager, 1, name='AsyncContextManager')
+2728Dict = _alias(dict, 2, inst=False, name='Dict')
+2729DefaultDict = _alias(collections.defaultdict, 2, name='DefaultDict')
+2730OrderedDict = _alias(collections.OrderedDict, 2)
+2731Counter = _alias(collections.Counter, 1)
+2732ChainMap = _alias(collections.ChainMap, 2)
+2733Generator = _alias(collections.abc.Generator, 3)
+2734AsyncGenerator = _alias(collections.abc.AsyncGenerator, 2)
+2735Type = _alias(type, 1, inst=False, name='Type')
+2736Type.__doc__ = \
+2737    """Deprecated alias to builtins.type.
+2738
+2739    builtins.type or typing.Type can be used to annotate class objects.
+2740    For example, suppose we have the following classes::
+2741
+2742        class User: ...  # Abstract base for User classes
+2743        class BasicUser(User): ...
+2744        class ProUser(User): ...
+2745        class TeamUser(User): ...
+2746
+2747    And a function that takes a class argument that's a subclass of
+2748    User and returns an instance of the corresponding class::
+2749
+2750        U = TypeVar('U', bound=User)
+2751        def new_user(user_class: Type[U]) -> U:
+2752            user = user_class()
+2753            # (Here we could write the user object to a database)
+2754            return user
+2755
+2756        joe = new_user(BasicUser)
 2757
-2758        class User: ...  # Abstract base for User classes
-2759        class BasicUser(User): ...
-2760        class ProUser(User): ...
-2761        class TeamUser(User): ...
-2762
-2763    And a function that takes a class argument that's a subclass of
-2764    User and returns an instance of the corresponding class::
+2758    At this point the type checker knows that joe has type BasicUser.
+2759    """
+2760
+2761
+2762@runtime_checkable
+2763class SupportsInt(Protocol):
+2764    """An ABC with one abstract method __int__."""
 2765
-2766        U = TypeVar('U', bound=User)
-2767        def new_user(user_class: Type[U]) -> U:
-2768            user = user_class()
-2769            # (Here we could write the user object to a database)
-2770            return user
+2766    __slots__ = ()
+2767
+2768    @abstractmethod
+2769    def __int__(self) -> int:
+2770        pass
 2771
-2772        joe = new_user(BasicUser)
-2773
-2774    At this point the type checker knows that joe has type BasicUser.
-2775    """
+2772
+2773@runtime_checkable
+2774class SupportsFloat(Protocol):
+2775    """An ABC with one abstract method __float__."""
 2776
-2777
-2778@runtime_checkable
-2779class SupportsInt(Protocol):
-2780    """An ABC with one abstract method __int__."""
-2781
-2782    __slots__ = ()
+2777    __slots__ = ()
+2778
+2779    @abstractmethod
+2780    def __float__(self) -> float:
+2781        pass
+2782
 2783
-2784    @abstractmethod
-2785    def __int__(self) -> int:
-2786        pass
+2784@runtime_checkable
+2785class SupportsComplex(Protocol):
+2786    """An ABC with one abstract method __complex__."""
 2787
-2788
-2789@runtime_checkable
-2790class SupportsFloat(Protocol):
-2791    """An ABC with one abstract method __float__."""
-2792
-2793    __slots__ = ()
+2788    __slots__ = ()
+2789
+2790    @abstractmethod
+2791    def __complex__(self) -> complex:
+2792        pass
+2793
 2794
-2795    @abstractmethod
-2796    def __float__(self) -> float:
-2797        pass
+2795@runtime_checkable
+2796class SupportsBytes(Protocol):
+2797    """An ABC with one abstract method __bytes__."""
 2798
-2799
-2800@runtime_checkable
-2801class SupportsComplex(Protocol):
-2802    """An ABC with one abstract method __complex__."""
-2803
-2804    __slots__ = ()
+2799    __slots__ = ()
+2800
+2801    @abstractmethod
+2802    def __bytes__(self) -> bytes:
+2803        pass
+2804
 2805
-2806    @abstractmethod
-2807    def __complex__(self) -> complex:
-2808        pass
+2806@runtime_checkable
+2807class SupportsIndex(Protocol):
+2808    """An ABC with one abstract method __index__."""
 2809
-2810
-2811@runtime_checkable
-2812class SupportsBytes(Protocol):
-2813    """An ABC with one abstract method __bytes__."""
-2814
-2815    __slots__ = ()
+2810    __slots__ = ()
+2811
+2812    @abstractmethod
+2813    def __index__(self) -> int:
+2814        pass
+2815
 2816
-2817    @abstractmethod
-2818    def __bytes__(self) -> bytes:
-2819        pass
+2817@runtime_checkable
+2818class SupportsAbs(Protocol[T_co]):
+2819    """An ABC with one abstract method __abs__ that is covariant in its return type."""
 2820
-2821
-2822@runtime_checkable
-2823class SupportsIndex(Protocol):
-2824    """An ABC with one abstract method __index__."""
-2825
-2826    __slots__ = ()
+2821    __slots__ = ()
+2822
+2823    @abstractmethod
+2824    def __abs__(self) -> T_co:
+2825        pass
+2826
 2827
-2828    @abstractmethod
-2829    def __index__(self) -> int:
-2830        pass
+2828@runtime_checkable
+2829class SupportsRound(Protocol[T_co]):
+2830    """An ABC with one abstract method __round__ that is covariant in its return type."""
 2831
-2832
-2833@runtime_checkable
-2834class SupportsAbs(Protocol[T_co]):
-2835    """An ABC with one abstract method __abs__ that is covariant in its return type."""
-2836
-2837    __slots__ = ()
+2832    __slots__ = ()
+2833
+2834    @abstractmethod
+2835    def __round__(self, ndigits: int = 0) -> T_co:
+2836        pass
+2837
 2838
-2839    @abstractmethod
-2840    def __abs__(self) -> T_co:
-2841        pass
-2842
-2843
-2844@runtime_checkable
-2845class SupportsRound(Protocol[T_co]):
-2846    """An ABC with one abstract method __round__ that is covariant in its return type."""
+2839def _make_nmtuple(name, types, module, defaults = ()):
+2840    fields = [n for n, t in types]
+2841    types = {n: _type_check(t, f"field {n} annotation must be a type")
+2842             for n, t in types}
+2843    nm_tpl = collections.namedtuple(name, fields,
+2844                                    defaults=defaults, module=module)
+2845    nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types
+2846    return nm_tpl
 2847
-2848    __slots__ = ()
-2849
-2850    @abstractmethod
-2851    def __round__(self, ndigits: int = 0) -> T_co:
-2852        pass
+2848
+2849# attributes prohibited to set in NamedTuple class syntax
+2850_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__',
+2851                         '_fields', '_field_defaults',
+2852                         '_make', '_replace', '_asdict', '_source'})
 2853
-2854
-2855def _make_nmtuple(name, types, module, defaults = ()):
-2856    fields = [n for n, t in types]
-2857    types = {n: _type_check(t, f"field {n} annotation must be a type")
-2858             for n, t in types}
-2859    nm_tpl = collections.namedtuple(name, fields,
-2860                                    defaults=defaults, module=module)
-2861    nm_tpl.__annotations__ = nm_tpl.__new__.__annotations__ = types
-2862    return nm_tpl
-2863
-2864
-2865# attributes prohibited to set in NamedTuple class syntax
-2866_prohibited = frozenset({'__new__', '__init__', '__slots__', '__getnewargs__',
-2867                         '_fields', '_field_defaults',
-2868                         '_make', '_replace', '_asdict', '_source'})
-2869
-2870_special = frozenset({'__module__', '__name__', '__annotations__'})
-2871
-2872
-2873class NamedTupleMeta(type):
-2874    def __new__(cls, typename, bases, ns):
-2875        assert _NamedTuple in bases
-2876        for base in bases:
-2877            if base is not _NamedTuple and base is not Generic:
-2878                raise TypeError(
-2879                    'can only inherit from a NamedTuple type and Generic')
-2880        bases = tuple(tuple if base is _NamedTuple else base for base in bases)
-2881        types = ns.get('__annotations__', {})
-2882        default_names = []
-2883        for field_name in types:
-2884            if field_name in ns:
-2885                default_names.append(field_name)
-2886            elif default_names:
-2887                raise TypeError(f"Non-default namedtuple field {field_name} "
-2888                                f"cannot follow default field"
-2889                                f"{'s' if len(default_names) > 1 else ''} "
-2890                                f"{', '.join(default_names)}")
-2891        nm_tpl = _make_nmtuple(typename, types.items(),
-2892                               defaults=[ns[n] for n in default_names],
-2893                               module=ns['__module__'])
-2894        nm_tpl.__bases__ = bases
-2895        if Generic in bases:
-2896            class_getitem = Generic.__class_getitem__.__func__
-2897            nm_tpl.__class_getitem__ = classmethod(class_getitem)
-2898        # update from user namespace without overriding special namedtuple attributes
-2899        for key in ns:
-2900            if key in _prohibited:
-2901                raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
-2902            elif key not in _special and key not in nm_tpl._fields:
-2903                setattr(nm_tpl, key, ns[key])
-2904        if Generic in bases:
-2905            nm_tpl.__init_subclass__()
-2906        return nm_tpl
-2907
-2908
-2909def NamedTuple(typename, fields=None, /, **kwargs):
-2910    """Typed version of namedtuple.
-2911
-2912    Usage::
-2913
-2914        class Employee(NamedTuple):
-2915            name: str
-2916            id: int
-2917
-2918    This is equivalent to::
+2854_special = frozenset({'__module__', '__name__', '__annotations__'})
+2855
+2856
+2857class NamedTupleMeta(type):
+2858    def __new__(cls, typename, bases, ns):
+2859        assert _NamedTuple in bases
+2860        for base in bases:
+2861            if base is not _NamedTuple and base is not Generic:
+2862                raise TypeError(
+2863                    'can only inherit from a NamedTuple type and Generic')
+2864        bases = tuple(tuple if base is _NamedTuple else base for base in bases)
+2865        types = ns.get('__annotations__', {})
+2866        default_names = []
+2867        for field_name in types:
+2868            if field_name in ns:
+2869                default_names.append(field_name)
+2870            elif default_names:
+2871                raise TypeError(f"Non-default namedtuple field {field_name} "
+2872                                f"cannot follow default field"
+2873                                f"{'s' if len(default_names) > 1 else ''} "
+2874                                f"{', '.join(default_names)}")
+2875        nm_tpl = _make_nmtuple(typename, types.items(),
+2876                               defaults=[ns[n] for n in default_names],
+2877                               module=ns['__module__'])
+2878        nm_tpl.__bases__ = bases
+2879        if Generic in bases:
+2880            class_getitem = Generic.__class_getitem__.__func__
+2881            nm_tpl.__class_getitem__ = classmethod(class_getitem)
+2882        # update from user namespace without overriding special namedtuple attributes
+2883        for key in ns:
+2884            if key in _prohibited:
+2885                raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
+2886            elif key not in _special and key not in nm_tpl._fields:
+2887                setattr(nm_tpl, key, ns[key])
+2888        if Generic in bases:
+2889            nm_tpl.__init_subclass__()
+2890        return nm_tpl
+2891
+2892
+2893def NamedTuple(typename, fields=None, /, **kwargs):
+2894    """Typed version of namedtuple.
+2895
+2896    Usage::
+2897
+2898        class Employee(NamedTuple):
+2899            name: str
+2900            id: int
+2901
+2902    This is equivalent to::
+2903
+2904        Employee = collections.namedtuple('Employee', ['name', 'id'])
+2905
+2906    The resulting class has an extra __annotations__ attribute, giving a
+2907    dict that maps field names to types.  (The field names are also in
+2908    the _fields attribute, which is part of the namedtuple API.)
+2909    An alternative equivalent functional syntax is also accepted::
+2910
+2911        Employee = NamedTuple('Employee', [('name', str), ('id', int)])
+2912    """
+2913    if fields is None:
+2914        fields = kwargs.items()
+2915    elif kwargs:
+2916        raise TypeError("Either list of fields or keywords"
+2917                        " can be provided to NamedTuple, not both")
+2918    return _make_nmtuple(typename, fields, module=_caller())
 2919
-2920        Employee = collections.namedtuple('Employee', ['name', 'id'])
+2920_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {})
 2921
-2922    The resulting class has an extra __annotations__ attribute, giving a
-2923    dict that maps field names to types.  (The field names are also in
-2924    the _fields attribute, which is part of the namedtuple API.)
-2925    An alternative equivalent functional syntax is also accepted::
-2926
-2927        Employee = NamedTuple('Employee', [('name', str), ('id', int)])
-2928    """
-2929    if fields is None:
-2930        fields = kwargs.items()
-2931    elif kwargs:
-2932        raise TypeError("Either list of fields or keywords"
-2933                        " can be provided to NamedTuple, not both")
-2934    return _make_nmtuple(typename, fields, module=_caller())
-2935
-2936_NamedTuple = type.__new__(NamedTupleMeta, 'NamedTuple', (), {})
-2937
-2938def _namedtuple_mro_entries(bases):
-2939    assert NamedTuple in bases
-2940    return (_NamedTuple,)
-2941
-2942NamedTuple.__mro_entries__ = _namedtuple_mro_entries
-2943
-2944
-2945class _TypedDictMeta(type):
-2946    def __new__(cls, name, bases, ns, total=True):
-2947        """Create a new typed dict class object.
-2948
-2949        This method is called when TypedDict is subclassed,
-2950        or when TypedDict is instantiated. This way
-2951        TypedDict supports all three syntax forms described in its docstring.
-2952        Subclasses and instances of TypedDict return actual dictionaries.
-2953        """
-2954        for base in bases:
-2955            if type(base) is not _TypedDictMeta and base is not Generic:
-2956                raise TypeError('cannot inherit from both a TypedDict type '
-2957                                'and a non-TypedDict base class')
-2958
-2959        if any(issubclass(b, Generic) for b in bases):
-2960            generic_base = (Generic,)
-2961        else:
-2962            generic_base = ()
-2963
-2964        tp_dict = type.__new__(_TypedDictMeta, name, (*generic_base, dict), ns)
-2965
-2966        annotations = {}
-2967        own_annotations = ns.get('__annotations__', {})
-2968        msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
-2969        own_annotations = {
-2970            n: _type_check(tp, msg, module=tp_dict.__module__)
-2971            for n, tp in own_annotations.items()
-2972        }
-2973        required_keys = set()
-2974        optional_keys = set()
-2975
-2976        for base in bases:
-2977            annotations.update(base.__dict__.get('__annotations__', {}))
-2978            required_keys.update(base.__dict__.get('__required_keys__', ()))
-2979            optional_keys.update(base.__dict__.get('__optional_keys__', ()))
-2980
-2981        annotations.update(own_annotations)
-2982        for annotation_key, annotation_type in own_annotations.items():
-2983            annotation_origin = get_origin(annotation_type)
-2984            if annotation_origin is Annotated:
-2985                annotation_args = get_args(annotation_type)
-2986                if annotation_args:
-2987                    annotation_type = annotation_args[0]
-2988                    annotation_origin = get_origin(annotation_type)
+2922def _namedtuple_mro_entries(bases):
+2923    assert NamedTuple in bases
+2924    return (_NamedTuple,)
+2925
+2926NamedTuple.__mro_entries__ = _namedtuple_mro_entries
+2927
+2928
+2929class _TypedDictMeta(type):
+2930    def __new__(cls, name, bases, ns, total=True):
+2931        """Create a new typed dict class object.
+2932
+2933        This method is called when TypedDict is subclassed,
+2934        or when TypedDict is instantiated. This way
+2935        TypedDict supports all three syntax forms described in its docstring.
+2936        Subclasses and instances of TypedDict return actual dictionaries.
+2937        """
+2938        for base in bases:
+2939            if type(base) is not _TypedDictMeta and base is not Generic:
+2940                raise TypeError('cannot inherit from both a TypedDict type '
+2941                                'and a non-TypedDict base class')
+2942
+2943        if any(issubclass(b, Generic) for b in bases):
+2944            generic_base = (Generic,)
+2945        else:
+2946            generic_base = ()
+2947
+2948        tp_dict = type.__new__(_TypedDictMeta, name, (*generic_base, dict), ns)
+2949
+2950        annotations = {}
+2951        own_annotations = ns.get('__annotations__', {})
+2952        msg = "TypedDict('Name', {f0: t0, f1: t1, ...}); each t must be a type"
+2953        own_annotations = {
+2954            n: _type_check(tp, msg, module=tp_dict.__module__)
+2955            for n, tp in own_annotations.items()
+2956        }
+2957        required_keys = set()
+2958        optional_keys = set()
+2959
+2960        for base in bases:
+2961            annotations.update(base.__dict__.get('__annotations__', {}))
+2962            required_keys.update(base.__dict__.get('__required_keys__', ()))
+2963            optional_keys.update(base.__dict__.get('__optional_keys__', ()))
+2964
+2965        annotations.update(own_annotations)
+2966        for annotation_key, annotation_type in own_annotations.items():
+2967            annotation_origin = get_origin(annotation_type)
+2968            if annotation_origin is Annotated:
+2969                annotation_args = get_args(annotation_type)
+2970                if annotation_args:
+2971                    annotation_type = annotation_args[0]
+2972                    annotation_origin = get_origin(annotation_type)
+2973
+2974            if annotation_origin is Required:
+2975                required_keys.add(annotation_key)
+2976            elif annotation_origin is NotRequired:
+2977                optional_keys.add(annotation_key)
+2978            elif total:
+2979                required_keys.add(annotation_key)
+2980            else:
+2981                optional_keys.add(annotation_key)
+2982
+2983        tp_dict.__annotations__ = annotations
+2984        tp_dict.__required_keys__ = frozenset(required_keys)
+2985        tp_dict.__optional_keys__ = frozenset(optional_keys)
+2986        if not hasattr(tp_dict, '__total__'):
+2987            tp_dict.__total__ = total
+2988        return tp_dict
 2989
-2990            if annotation_origin is Required:
-2991                required_keys.add(annotation_key)
-2992            elif annotation_origin is NotRequired:
-2993                optional_keys.add(annotation_key)
-2994            elif total:
-2995                required_keys.add(annotation_key)
-2996            else:
-2997                optional_keys.add(annotation_key)
+2990    __call__ = dict  # static method
+2991
+2992    def __subclasscheck__(cls, other):
+2993        # Typed dicts are only for static structural subtyping.
+2994        raise TypeError('TypedDict does not support instance and class checks')
+2995
+2996    __instancecheck__ = __subclasscheck__
+2997
 2998
-2999        tp_dict.__annotations__ = annotations
-3000        tp_dict.__required_keys__ = frozenset(required_keys)
-3001        tp_dict.__optional_keys__ = frozenset(optional_keys)
-3002        if not hasattr(tp_dict, '__total__'):
-3003            tp_dict.__total__ = total
-3004        return tp_dict
-3005
-3006    __call__ = dict  # static method
-3007
-3008    def __subclasscheck__(cls, other):
-3009        # Typed dicts are only for static structural subtyping.
-3010        raise TypeError('TypedDict does not support instance and class checks')
-3011
-3012    __instancecheck__ = __subclasscheck__
+2999def TypedDict(typename, fields=None, /, *, total=True, **kwargs):
+3000    """A simple typed namespace. At runtime it is equivalent to a plain dict.
+3001
+3002    TypedDict creates a dictionary type such that a type checker will expect all
+3003    instances to have a certain set of keys, where each key is
+3004    associated with a value of a consistent type. This expectation
+3005    is not checked at runtime.
+3006
+3007    Usage::
+3008
+3009        class Point2D(TypedDict):
+3010            x: int
+3011            y: int
+3012            label: str
 3013
-3014
-3015def TypedDict(typename, fields=None, /, *, total=True, **kwargs):
-3016    """A simple typed namespace. At runtime it is equivalent to a plain dict.
-3017
-3018    TypedDict creates a dictionary type such that a type checker will expect all
-3019    instances to have a certain set of keys, where each key is
-3020    associated with a value of a consistent type. This expectation
-3021    is not checked at runtime.
+3014        a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
+3015        b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check
+3016
+3017        assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
+3018
+3019    The type info can be accessed via the Point2D.__annotations__ dict, and
+3020    the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
+3021    TypedDict supports an additional equivalent form::
 3022
-3023    Usage::
+3023        Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
 3024
-3025        class Point2D(TypedDict):
-3026            x: int
-3027            y: int
-3028            label: str
-3029
-3030        a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
-3031        b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check
-3032
-3033        assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
-3034
-3035    The type info can be accessed via the Point2D.__annotations__ dict, and
-3036    the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
-3037    TypedDict supports an additional equivalent form::
-3038
-3039        Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
-3040
-3041    By default, all keys must be present in a TypedDict. It is possible
-3042    to override this by specifying totality::
+3025    By default, all keys must be present in a TypedDict. It is possible
+3026    to override this by specifying totality::
+3027
+3028        class Point2D(TypedDict, total=False):
+3029            x: int
+3030            y: int
+3031
+3032    This means that a Point2D TypedDict can have any of the keys omitted. A type
+3033    checker is only expected to support a literal False or True as the value of
+3034    the total argument. True is the default, and makes all items defined in the
+3035    class body be required.
+3036
+3037    The Required and NotRequired special forms can also be used to mark
+3038    individual keys as being required or not required::
+3039
+3040        class Point2D(TypedDict):
+3041            x: int               # the "x" key must always be present (Required is the default)
+3042            y: NotRequired[int]  # the "y" key can be omitted
 3043
-3044        class Point2D(TypedDict, total=False):
-3045            x: int
-3046            y: int
-3047
-3048    This means that a Point2D TypedDict can have any of the keys omitted. A type
-3049    checker is only expected to support a literal False or True as the value of
-3050    the total argument. True is the default, and makes all items defined in the
-3051    class body be required.
-3052
-3053    The Required and NotRequired special forms can also be used to mark
-3054    individual keys as being required or not required::
-3055
-3056        class Point2D(TypedDict):
-3057            x: int               # the "x" key must always be present (Required is the default)
-3058            y: NotRequired[int]  # the "y" key can be omitted
+3044    See PEP 655 for more details on Required and NotRequired.
+3045    """
+3046    if fields is None:
+3047        fields = kwargs
+3048    elif kwargs:
+3049        raise TypeError("TypedDict takes either a dict or keyword arguments,"
+3050                        " but not both")
+3051    if kwargs:
+3052        warnings.warn(
+3053            "The kwargs-based syntax for TypedDict definitions is deprecated "
+3054            "in Python 3.11, will be removed in Python 3.13, and may not be "
+3055            "understood by third-party type checkers.",
+3056            DeprecationWarning,
+3057            stacklevel=2,
+3058        )
 3059
-3060    See PEP 655 for more details on Required and NotRequired.
-3061    """
-3062    if fields is None:
-3063        fields = kwargs
-3064    elif kwargs:
-3065        raise TypeError("TypedDict takes either a dict or keyword arguments,"
-3066                        " but not both")
-3067    if kwargs:
-3068        warnings.warn(
-3069            "The kwargs-based syntax for TypedDict definitions is deprecated "
-3070            "in Python 3.11, will be removed in Python 3.13, and may not be "
-3071            "understood by third-party type checkers.",
-3072            DeprecationWarning,
-3073            stacklevel=2,
-3074        )
+3060    ns = {'__annotations__': dict(fields)}
+3061    module = _caller()
+3062    if module is not None:
+3063        # Setting correct module is necessary to make typed dict classes pickleable.
+3064        ns['__module__'] = module
+3065
+3066    return _TypedDictMeta(typename, (), ns, total=total)
+3067
+3068_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
+3069TypedDict.__mro_entries__ = lambda bases: (_TypedDict,)
+3070
+3071
+3072@_SpecialForm
+3073def Required(self, parameters):
+3074    """Special typing construct to mark a TypedDict key as required.
 3075
-3076    ns = {'__annotations__': dict(fields)}
-3077    module = _caller()
-3078    if module is not None:
-3079        # Setting correct module is necessary to make typed dict classes pickleable.
-3080        ns['__module__'] = module
+3076    This is mainly useful for total=False TypedDicts. For example::
+3077
+3078        class Movie(TypedDict, total=False):
+3079            title: Required[str]
+3080            year: int
 3081
-3082    return _TypedDictMeta(typename, (), ns, total=total)
-3083
-3084_TypedDict = type.__new__(_TypedDictMeta, 'TypedDict', (), {})
-3085TypedDict.__mro_entries__ = lambda bases: (_TypedDict,)
+3082        m = Movie(
+3083            title='The Matrix',  # typechecker error if key is omitted
+3084            year=1999,
+3085        )
 3086
-3087
-3088@_SpecialForm
-3089def Required(self, parameters):
-3090    """Special typing construct to mark a TypedDict key as required.
-3091
-3092    This is mainly useful for total=False TypedDicts.
+3087    There is no runtime checking that a required key is actually provided
+3088    when instantiating a related TypedDict.
+3089    """
+3090    item = _type_check(parameters, f'{self._name} accepts only a single type.')
+3091    return _GenericAlias(self, (item,))
+3092
 3093
-3094    For example::
-3095
-3096        class Movie(TypedDict, total=False):
-3097            title: Required[str]
-3098            year: int
+3094@_SpecialForm
+3095def NotRequired(self, parameters):
+3096    """Special typing construct to mark a TypedDict key as potentially missing.
+3097
+3098    For example::
 3099
-3100        m = Movie(
-3101            title='The Matrix',  # typechecker error if key is omitted
-3102            year=1999,
-3103        )
-3104
-3105    There is no runtime checking that a required key is actually provided
-3106    when instantiating a related TypedDict.
-3107    """
-3108    item = _type_check(parameters, f'{self._name} accepts only a single type.')
-3109    return _GenericAlias(self, (item,))
-3110
+3100        class Movie(TypedDict):
+3101            title: str
+3102            year: NotRequired[int]
+3103
+3104        m = Movie(
+3105            title='The Matrix',  # typechecker error if key is omitted
+3106            year=1999,
+3107        )
+3108    """
+3109    item = _type_check(parameters, f'{self._name} accepts only a single type.')
+3110    return _GenericAlias(self, (item,))
 3111
-3112@_SpecialForm
-3113def NotRequired(self, parameters):
-3114    """Special typing construct to mark a TypedDict key as potentially missing.
+3112
+3113class NewType:
+3114    """NewType creates simple unique types with almost zero runtime overhead.
 3115
-3116    For example::
-3117
-3118        class Movie(TypedDict):
-3119            title: str
-3120            year: NotRequired[int]
+3116    NewType(name, tp) is considered a subtype of tp
+3117    by static type checkers. At runtime, NewType(name, tp) returns
+3118    a dummy callable that simply returns its argument. Usage::
+3119
+3120        UserId = NewType('UserId', int)
 3121
-3122        m = Movie(
-3123            title='The Matrix',  # typechecker error if key is omitted
-3124            year=1999,
-3125        )
-3126    """
-3127    item = _type_check(parameters, f'{self._name} accepts only a single type.')
-3128    return _GenericAlias(self, (item,))
+3122        def name_by_id(user_id: UserId) -> str:
+3123            ...
+3124
+3125        UserId('user')          # Fails type check
+3126
+3127        name_by_id(42)          # Fails type check
+3128        name_by_id(UserId(42))  # OK
 3129
-3130
-3131class NewType:
-3132    """NewType creates simple unique types with almost zero runtime overhead.
-3133
-3134    NewType(name, tp) is considered a subtype of tp
-3135    by static type checkers. At runtime, NewType(name, tp) returns
-3136    a dummy callable that simply returns its argument.
-3137
-3138    Usage::
-3139
-3140        UserId = NewType('UserId', int)
-3141
-3142        def name_by_id(user_id: UserId) -> str:
-3143            ...
+3130        num = UserId(5) + 1     # type: int
+3131    """
+3132
+3133    __call__ = _idfunc
+3134
+3135    def __init__(self, name, tp):
+3136        self.__qualname__ = name
+3137        if '.' in name:
+3138            name = name.rpartition('.')[-1]
+3139        self.__name__ = name
+3140        self.__supertype__ = tp
+3141        def_mod = _caller()
+3142        if def_mod != 'typing':
+3143            self.__module__ = def_mod
 3144
-3145        UserId('user')          # Fails type check
-3146
-3147        name_by_id(42)          # Fails type check
-3148        name_by_id(UserId(42))  # OK
+3145    def __mro_entries__(self, bases):
+3146        # We defined __mro_entries__ to get a better error message
+3147        # if a user attempts to subclass a NewType instance. bpo-46170
+3148        superclass_name = self.__name__
 3149
-3150        num = UserId(5) + 1     # type: int
-3151    """
-3152
-3153    __call__ = _idfunc
-3154
-3155    def __init__(self, name, tp):
-3156        self.__qualname__ = name
-3157        if '.' in name:
-3158            name = name.rpartition('.')[-1]
-3159        self.__name__ = name
-3160        self.__supertype__ = tp
-3161        def_mod = _caller()
-3162        if def_mod != 'typing':
-3163            self.__module__ = def_mod
-3164
-3165    def __mro_entries__(self, bases):
-3166        # We defined __mro_entries__ to get a better error message
-3167        # if a user attempts to subclass a NewType instance. bpo-46170
-3168        superclass_name = self.__name__
-3169
-3170        class Dummy:
-3171            def __init_subclass__(cls):
-3172                subclass_name = cls.__name__
-3173                raise TypeError(
-3174                    f"Cannot subclass an instance of NewType. Perhaps you were looking for: "
-3175                    f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`"
-3176                )
-3177
-3178        return (Dummy,)
+3150        class Dummy:
+3151            def __init_subclass__(cls):
+3152                subclass_name = cls.__name__
+3153                raise TypeError(
+3154                    f"Cannot subclass an instance of NewType. Perhaps you were looking for: "
+3155                    f"`{subclass_name} = NewType({subclass_name!r}, {superclass_name})`"
+3156                )
+3157
+3158        return (Dummy,)
+3159
+3160    def __repr__(self):
+3161        return f'{self.__module__}.{self.__qualname__}'
+3162
+3163    def __reduce__(self):
+3164        return self.__qualname__
+3165
+3166    def __or__(self, other):
+3167        return Union[self, other]
+3168
+3169    def __ror__(self, other):
+3170        return Union[other, self]
+3171
+3172
+3173# Python-version-specific alias (Python 2: unicode; Python 3: str)
+3174Text = str
+3175
+3176
+3177# Constant that's True when type checking, but False here.
+3178TYPE_CHECKING = False
 3179
-3180    def __repr__(self):
-3181        return f'{self.__module__}.{self.__qualname__}'
-3182
-3183    def __reduce__(self):
-3184        return self.__qualname__
+3180
+3181class IO(Generic[AnyStr]):
+3182    """Generic base class for TextIO and BinaryIO.
+3183
+3184    This is an abstract, generic version of the return of open().
 3185
-3186    def __or__(self, other):
-3187        return Union[self, other]
-3188
-3189    def __ror__(self, other):
-3190        return Union[other, self]
-3191
-3192
-3193# Python-version-specific alias (Python 2: unicode; Python 3: str)
-3194Text = str
+3186    NOTE: This does not distinguish between the different possible
+3187    classes (text vs. binary, read vs. write vs. read/write,
+3188    append-only, unbuffered).  The TextIO and BinaryIO subclasses
+3189    below capture the distinctions between text vs. binary, which is
+3190    pervasive in the interface; however we currently do not offer a
+3191    way to track the other distinctions in the type system.
+3192    """
+3193
+3194    __slots__ = ()
 3195
-3196
-3197# Constant that's True when type checking, but False here.
-3198TYPE_CHECKING = False
-3199
+3196    @property
+3197    @abstractmethod
+3198    def mode(self) -> str:
+3199        pass
 3200
-3201class IO(Generic[AnyStr]):
-3202    """Generic base class for TextIO and BinaryIO.
-3203
-3204    This is an abstract, generic version of the return of open().
+3201    @property
+3202    @abstractmethod
+3203    def name(self) -> str:
+3204        pass
 3205
-3206    NOTE: This does not distinguish between the different possible
-3207    classes (text vs. binary, read vs. write vs. read/write,
-3208    append-only, unbuffered).  The TextIO and BinaryIO subclasses
-3209    below capture the distinctions between text vs. binary, which is
-3210    pervasive in the interface; however we currently do not offer a
-3211    way to track the other distinctions in the type system.
-3212    """
-3213
-3214    __slots__ = ()
-3215
-3216    @property
-3217    @abstractmethod
-3218    def mode(self) -> str:
-3219        pass
-3220
-3221    @property
-3222    @abstractmethod
-3223    def name(self) -> str:
-3224        pass
-3225
-3226    @abstractmethod
-3227    def close(self) -> None:
-3228        pass
-3229
-3230    @property
+3206    @abstractmethod
+3207    def close(self) -> None:
+3208        pass
+3209
+3210    @property
+3211    @abstractmethod
+3212    def closed(self) -> bool:
+3213        pass
+3214
+3215    @abstractmethod
+3216    def fileno(self) -> int:
+3217        pass
+3218
+3219    @abstractmethod
+3220    def flush(self) -> None:
+3221        pass
+3222
+3223    @abstractmethod
+3224    def isatty(self) -> bool:
+3225        pass
+3226
+3227    @abstractmethod
+3228    def read(self, n: int = -1) -> AnyStr:
+3229        pass
+3230
 3231    @abstractmethod
-3232    def closed(self) -> bool:
+3232    def readable(self) -> bool:
 3233        pass
 3234
 3235    @abstractmethod
-3236    def fileno(self) -> int:
+3236    def readline(self, limit: int = -1) -> AnyStr:
 3237        pass
 3238
 3239    @abstractmethod
-3240    def flush(self) -> None:
+3240    def readlines(self, hint: int = -1) -> List[AnyStr]:
 3241        pass
 3242
 3243    @abstractmethod
-3244    def isatty(self) -> bool:
+3244    def seek(self, offset: int, whence: int = 0) -> int:
 3245        pass
 3246
 3247    @abstractmethod
-3248    def read(self, n: int = -1) -> AnyStr:
+3248    def seekable(self) -> bool:
 3249        pass
 3250
 3251    @abstractmethod
-3252    def readable(self) -> bool:
+3252    def tell(self) -> int:
 3253        pass
 3254
 3255    @abstractmethod
-3256    def readline(self, limit: int = -1) -> AnyStr:
+3256    def truncate(self, size: int = None) -> int:
 3257        pass
 3258
 3259    @abstractmethod
-3260    def readlines(self, hint: int = -1) -> List[AnyStr]:
+3260    def writable(self) -> bool:
 3261        pass
 3262
 3263    @abstractmethod
-3264    def seek(self, offset: int, whence: int = 0) -> int:
+3264    def write(self, s: AnyStr) -> int:
 3265        pass
 3266
 3267    @abstractmethod
-3268    def seekable(self) -> bool:
+3268    def writelines(self, lines: List[AnyStr]) -> None:
 3269        pass
 3270
 3271    @abstractmethod
-3272    def tell(self) -> int:
+3272    def __enter__(self) -> 'IO[AnyStr]':
 3273        pass
 3274
 3275    @abstractmethod
-3276    def truncate(self, size: int = None) -> int:
+3276    def __exit__(self, type, value, traceback) -> None:
 3277        pass
 3278
-3279    @abstractmethod
-3280    def writable(self) -> bool:
-3281        pass
+3279
+3280class BinaryIO(IO[bytes]):
+3281    """Typed version of the return of open() in binary mode."""
 3282
-3283    @abstractmethod
-3284    def write(self, s: AnyStr) -> int:
-3285        pass
-3286
-3287    @abstractmethod
-3288    def writelines(self, lines: List[AnyStr]) -> None:
-3289        pass
-3290
-3291    @abstractmethod
-3292    def __enter__(self) -> 'IO[AnyStr]':
-3293        pass
-3294
-3295    @abstractmethod
-3296    def __exit__(self, type, value, traceback) -> None:
-3297        pass
+3283    __slots__ = ()
+3284
+3285    @abstractmethod
+3286    def write(self, s: Union[bytes, bytearray]) -> int:
+3287        pass
+3288
+3289    @abstractmethod
+3290    def __enter__(self) -> 'BinaryIO':
+3291        pass
+3292
+3293
+3294class TextIO(IO[str]):
+3295    """Typed version of the return of open() in text mode."""
+3296
+3297    __slots__ = ()
 3298
-3299
-3300class BinaryIO(IO[bytes]):
-3301    """Typed version of the return of open() in binary mode."""
-3302
-3303    __slots__ = ()
-3304
+3299    @property
+3300    @abstractmethod
+3301    def buffer(self) -> BinaryIO:
+3302        pass
+3303
+3304    @property
 3305    @abstractmethod
-3306    def write(self, s: Union[bytes, bytearray]) -> int:
+3306    def encoding(self) -> str:
 3307        pass
 3308
-3309    @abstractmethod
-3310    def __enter__(self) -> 'BinaryIO':
-3311        pass
-3312
+3309    @property
+3310    @abstractmethod
+3311    def errors(self) -> Optional[str]:
+3312        pass
 3313
-3314class TextIO(IO[str]):
-3315    """Typed version of the return of open() in text mode."""
-3316
-3317    __slots__ = ()
+3314    @property
+3315    @abstractmethod
+3316    def line_buffering(self) -> bool:
+3317        pass
 3318
 3319    @property
 3320    @abstractmethod
-3321    def buffer(self) -> BinaryIO:
+3321    def newlines(self) -> Any:
 3322        pass
 3323
-3324    @property
-3325    @abstractmethod
-3326    def encoding(self) -> str:
-3327        pass
+3324    @abstractmethod
+3325    def __enter__(self) -> 'TextIO':
+3326        pass
+3327
 3328
-3329    @property
-3330    @abstractmethod
-3331    def errors(self) -> Optional[str]:
-3332        pass
-3333
-3334    @property
-3335    @abstractmethod
-3336    def line_buffering(self) -> bool:
-3337        pass
-3338
-3339    @property
-3340    @abstractmethod
-3341    def newlines(self) -> Any:
-3342        pass
-3343
-3344    @abstractmethod
-3345    def __enter__(self) -> 'TextIO':
-3346        pass
-3347
-3348
-3349class _DeprecatedType(type):
-3350    def __getattribute__(cls, name):
-3351        if name not in ("__dict__", "__module__") and name in cls.__dict__:
-3352            warnings.warn(
-3353                f"{cls.__name__} is deprecated, import directly "
-3354                f"from typing instead. {cls.__name__} will be removed "
-3355                "in Python 3.12.",
-3356                DeprecationWarning,
-3357                stacklevel=2,
-3358            )
-3359        return super().__getattribute__(name)
-3360
-3361
-3362class io(metaclass=_DeprecatedType):
-3363    """Wrapper namespace for IO generic classes."""
+3329class _DeprecatedType(type):
+3330    def __getattribute__(cls, name):
+3331        if name not in ("__dict__", "__module__") and name in cls.__dict__:
+3332            warnings.warn(
+3333                f"{cls.__name__} is deprecated, import directly "
+3334                f"from typing instead. {cls.__name__} will be removed "
+3335                "in Python 3.12.",
+3336                DeprecationWarning,
+3337                stacklevel=2,
+3338            )
+3339        return super().__getattribute__(name)
+3340
+3341
+3342class io(metaclass=_DeprecatedType):
+3343    """Wrapper namespace for IO generic classes."""
+3344
+3345    __all__ = ['IO', 'TextIO', 'BinaryIO']
+3346    IO = IO
+3347    TextIO = TextIO
+3348    BinaryIO = BinaryIO
+3349
+3350
+3351io.__name__ = __name__ + '.io'
+3352sys.modules[io.__name__] = io
+3353
+3354Pattern = _alias(stdlib_re.Pattern, 1)
+3355Match = _alias(stdlib_re.Match, 1)
+3356
+3357class re(metaclass=_DeprecatedType):
+3358    """Wrapper namespace for re type aliases."""
+3359
+3360    __all__ = ['Pattern', 'Match']
+3361    Pattern = Pattern
+3362    Match = Match
+3363
 3364
-3365    __all__ = ['IO', 'TextIO', 'BinaryIO']
-3366    IO = IO
-3367    TextIO = TextIO
-3368    BinaryIO = BinaryIO
-3369
-3370
-3371io.__name__ = __name__ + '.io'
-3372sys.modules[io.__name__] = io
-3373
-3374Pattern = _alias(stdlib_re.Pattern, 1)
-3375Match = _alias(stdlib_re.Match, 1)
-3376
-3377class re(metaclass=_DeprecatedType):
-3378    """Wrapper namespace for re type aliases."""
-3379
-3380    __all__ = ['Pattern', 'Match']
-3381    Pattern = Pattern
-3382    Match = Match
-3383
-3384
-3385re.__name__ = __name__ + '.re'
-3386sys.modules[re.__name__] = re
+3365re.__name__ = __name__ + '.re'
+3366sys.modules[re.__name__] = re
+3367
+3368
+3369def reveal_type(obj: T, /) -> T:
+3370    """Reveal the inferred type of a variable.
+3371
+3372    When a static type checker encounters a call to ``reveal_type()``,
+3373    it will emit the inferred type of the argument::
+3374
+3375        x: int = 1
+3376        reveal_type(x)
+3377
+3378    Running a static type checker (e.g., mypy) on this example
+3379    will produce output similar to 'Revealed type is "builtins.int"'.
+3380
+3381    At runtime, the function prints the runtime type of the
+3382    argument and returns it unchanged.
+3383    """
+3384    print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr)
+3385    return obj
+3386
 3387
-3388
-3389def reveal_type(obj: T, /) -> T:
-3390    """Reveal the inferred type of a variable.
-3391
-3392    When a static type checker encounters a call to ``reveal_type()``,
-3393    it will emit the inferred type of the argument::
-3394
-3395        x: int = 1
-3396        reveal_type(x)
+3388def dataclass_transform(
+3389    *,
+3390    eq_default: bool = True,
+3391    order_default: bool = False,
+3392    kw_only_default: bool = False,
+3393    field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (),
+3394    **kwargs: Any,
+3395) -> Callable[[T], T]:
+3396    """Decorator to mark an object as providing dataclass-like behaviour.
 3397
-3398    Running a static type checker (e.g., mypy) on this example
-3399    will produce output similar to 'Revealed type is "builtins.int"'.
-3400
-3401    At runtime, the function prints the runtime type of the
-3402    argument and returns it unchanged.
-3403    """
-3404    print(f"Runtime type is {type(obj).__name__!r}", file=sys.stderr)
-3405    return obj
-3406
-3407
-3408def dataclass_transform(
-3409    *,
-3410    eq_default: bool = True,
-3411    order_default: bool = False,
-3412    kw_only_default: bool = False,
-3413    field_specifiers: tuple[type[Any] | Callable[..., Any], ...] = (),
-3414    **kwargs: Any,
-3415) -> Callable[[T], T]:
-3416    """Decorator to mark an object as providing dataclass-like behaviour.
-3417
-3418    The decorator can be applied to a function, class, or metaclass.
-3419
-3420    Example usage with a decorator function::
-3421
-3422        T = TypeVar("T")
-3423
-3424        @dataclass_transform()
-3425        def create_model(cls: type[T]) -> type[T]:
-3426            ...
-3427            return cls
-3428
-3429        @create_model
-3430        class CustomerModel:
+3398    The decorator can be applied to a function, class, or metaclass.
+3399
+3400    Example usage with a decorator function::
+3401
+3402        T = TypeVar("T")
+3403
+3404        @dataclass_transform()
+3405        def create_model(cls: type[T]) -> type[T]:
+3406            ...
+3407            return cls
+3408
+3409        @create_model
+3410        class CustomerModel:
+3411            id: int
+3412            name: str
+3413
+3414    On a base class::
+3415
+3416        @dataclass_transform()
+3417        class ModelBase: ...
+3418
+3419        class CustomerModel(ModelBase):
+3420            id: int
+3421            name: str
+3422
+3423    On a metaclass::
+3424
+3425        @dataclass_transform()
+3426        class ModelMeta(type): ...
+3427
+3428        class ModelBase(metaclass=ModelMeta): ...
+3429
+3430        class CustomerModel(ModelBase):
 3431            id: int
 3432            name: str
 3433
-3434    On a base class::
-3435
-3436        @dataclass_transform()
-3437        class ModelBase: ...
-3438
-3439        class CustomerModel(ModelBase):
-3440            id: int
-3441            name: str
-3442
-3443    On a metaclass::
-3444
-3445        @dataclass_transform()
-3446        class ModelMeta(type): ...
-3447
-3448        class ModelBase(metaclass=ModelMeta): ...
-3449
-3450        class CustomerModel(ModelBase):
-3451            id: int
-3452            name: str
-3453
-3454    The ``CustomerModel`` classes defined above will
-3455    be treated by type checkers similarly to classes created with
-3456    ``@dataclasses.dataclass``.
-3457    For example, type checkers will assume these classes have
-3458    ``__init__`` methods that accept ``id`` and ``name``.
-3459
-3460    The arguments to this decorator can be used to customize this behavior:
-3461    - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
-3462        ``True`` or ``False`` if it is omitted by the caller.
-3463    - ``order_default`` indicates whether the ``order`` parameter is
-3464        assumed to be True or False if it is omitted by the caller.
-3465    - ``kw_only_default`` indicates whether the ``kw_only`` parameter is
-3466        assumed to be True or False if it is omitted by the caller.
-3467    - ``field_specifiers`` specifies a static list of supported classes
-3468        or functions that describe fields, similar to ``dataclasses.field()``.
-3469    - Arbitrary other keyword arguments are accepted in order to allow for
-3470        possible future extensions.
-3471
-3472    At runtime, this decorator records its arguments in the
-3473    ``__dataclass_transform__`` attribute on the decorated object.
-3474    It has no other runtime effect.
-3475
-3476    See PEP 681 for more details.
-3477    """
-3478    def decorator(cls_or_fn):
-3479        cls_or_fn.__dataclass_transform__ = {
-3480            "eq_default": eq_default,
-3481            "order_default": order_default,
-3482            "kw_only_default": kw_only_default,
-3483            "field_specifiers": field_specifiers,
-3484            "kwargs": kwargs,
-3485        }
-3486        return cls_or_fn
-3487    return decorator
+3434    The ``CustomerModel`` classes defined above will
+3435    be treated by type checkers similarly to classes created with
+3436    ``@dataclasses.dataclass``.
+3437    For example, type checkers will assume these classes have
+3438    ``__init__`` methods that accept ``id`` and ``name``.
+3439
+3440    The arguments to this decorator can be used to customize this behavior:
+3441    - ``eq_default`` indicates whether the ``eq`` parameter is assumed to be
+3442        ``True`` or ``False`` if it is omitted by the caller.
+3443    - ``order_default`` indicates whether the ``order`` parameter is
+3444        assumed to be True or False if it is omitted by the caller.
+3445    - ``kw_only_default`` indicates whether the ``kw_only`` parameter is
+3446        assumed to be True or False if it is omitted by the caller.
+3447    - ``field_specifiers`` specifies a static list of supported classes
+3448        or functions that describe fields, similar to ``dataclasses.field()``.
+3449    - Arbitrary other keyword arguments are accepted in order to allow for
+3450        possible future extensions.
+3451
+3452    At runtime, this decorator records its arguments in the
+3453    ``__dataclass_transform__`` attribute on the decorated object.
+3454    It has no other runtime effect.
+3455
+3456    See PEP 681 for more details.
+3457    """
+3458    def decorator(cls_or_fn):
+3459        cls_or_fn.__dataclass_transform__ = {
+3460            "eq_default": eq_default,
+3461            "order_default": order_default,
+3462            "kw_only_default": kw_only_default,
+3463            "field_specifiers": field_specifiers,
+3464            "kwargs": kwargs,
+3465        }
+3466        return cls_or_fn
+3467    return decorator
 
        
 
                 
@@ -3997,15 +3977,11 @@ 
        Source code for typing
               
         
        
   
        
-    Created using Sphinx 7.2.5.
+     Created with Sphinx 7.2.5, with some help from  ChatGPT (GPT 4).
     
        
   
        
 
        
       
-        
        
-  Built with the PyData Sphinx Theme 0.13.3.
-
        
-      
     
        
   
   
diff --git a/_sources/.DS_Store b/_sources/.DS_Store
deleted file mode 100644
index 7fc004a7..00000000
Binary files a/_sources/.DS_Store and /dev/null differ
diff --git a/_sources/api/abc.rst b/_sources/api/abc.rst
index f4a30d02..ecb5e505 100644
--- a/_sources/api/abc.rst
+++ b/_sources/api/abc.rst
@@ -1,19 +1,13 @@
 pyxu.abc
 ========
 
-.. Solver-Related -------------------------------------------------------------
-.. autoclass:: pyxu.abc.Solver
-
-   .. autoattribute:: _mstate
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
 
-   .. autoattribute:: _astate
-
-.. autoclass:: pyxu.abc.SolverMode
+pyxu.abc.arithmetic
+-------------------
 
-.. autoclass:: pyxu.abc.StoppingCriterion
-
-
-.. Arithmetic Rules -----------------------------------------------------------
 .. autoclass:: pyxu.abc.arithmetic.Rule
    :members: op
    :no-members:
@@ -39,7 +33,9 @@ pyxu.abc
 .. autoclass:: pyxu.abc.arithmetic.TransposeRule
    :no-members:
 
-.. Operator-Related -----------------------------------------------------------
+pyxu.abc.operator
+-----------------
+
 .. autoclass:: pyxu.abc.Property
 
 .. autoclass:: pyxu.abc.Operator
@@ -101,3 +97,16 @@ pyxu.abc
 
 .. autoclass:: pyxu.abc.LinFunc
    :no-members:
+
+pyxu.abc.solver
+---------------
+
+.. autoclass:: pyxu.abc.Solver
+
+   .. autoattribute:: _mstate
+
+   .. autoattribute:: _astate
+
+.. autoclass:: pyxu.abc.SolverMode
+
+.. autoclass:: pyxu.abc.StoppingCriterion
diff --git a/_sources/api/experimental.rst b/_sources/api/experimental.rst
deleted file mode 100644
index 998ad46f..00000000
--- a/_sources/api/experimental.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-pyxu.experimental
-=================
-
-.. automodule:: pyxu.experimental.sampler
diff --git a/_sources/api/index.rst b/_sources/api/index.rst
index 8a4b3038..c571d24d 100644
--- a/_sources/api/index.rst
+++ b/_sources/api/index.rst
@@ -430,8 +430,10 @@ Array Backend-Related
 
 .. autosummary::
 
+   ~pyxu.util.compute
    ~pyxu.util.get_array_module
    ~pyxu.util.redirect
+   ~pyxu.util.to_NUMPY
 
 Complex Number Handling
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -456,7 +458,6 @@ Misc
 
 .. autosummary::
 
-   ~pyxu.util.compute
    ~pyxu.util.copy_if_unsafe
    ~pyxu.util.import_module
    ~pyxu.util.infer_composition_shape
@@ -464,7 +465,6 @@ Misc
    ~pyxu.util.next_fast_len
    ~pyxu.util.parse_params
    ~pyxu.util.read_only
-   ~pyxu.util.to_NUMPY
 
 .. rubric:: Low-lever Helpers
 
@@ -479,7 +479,7 @@ Misc
    :maxdepth: 2
    :hidden:
 
-   abc/index
+   abc
    info.deps
    info.ptype
    info.warning
@@ -489,6 +489,6 @@ Misc
    opt.stop
    runtime
    math
-   util/index
+   util
    experimental.sampler
    ../references
diff --git a/_sources/api/info.deps.rst b/_sources/api/info.deps.rst
index ab346d37..117cefd9 100644
--- a/_sources/api/info.deps.rst
+++ b/_sources/api/info.deps.rst
@@ -3,5 +3,9 @@ pyxu.info.deps
 
 .. automodule:: pyxu.info.deps
    :members:
+   :exclude-members: CUPY_ENABLED
    :undoc-members:
    :show-inheritance:
+
+   .. autodata:: CUPY_ENABLED
+      :no-value:
diff --git a/_sources/api/info.ptype.rst b/_sources/api/info.ptype.rst
index 652a3ebb..a0c23519 100644
--- a/_sources/api/info.ptype.rst
+++ b/_sources/api/info.ptype.rst
@@ -1,4 +1,52 @@
 pyxu.info.ptype
 ===============
 
+.. [Sepand, 2023.09.15]
+.. `pyxu.info.ptype` contains alias types for Python type checkers.  When auto-documented via Sphinx, alias types
+.. contain "alias of ..." as part of their docstring, which depends on the machine config.  (Was unable to remove them
+.. via Sphinx's `autodoc-process-docstring` event.) To avoid machine-dependant outputs in HTML docs, we provide custom
+.. machine-agnostic documentation for some aliases as required. Provided descriptions match those given as comments in
+.. `pyxu.info.ptype`.
+
+
 .. automodule:: pyxu.info.ptype
+   :exclude-members: NDArray, ArrayModule, SparseArray, SparseModule, OpT, Property, SolverT, SolverM, Real, DType
+
+   .. class:: NDArray
+
+      Supported dense array types.
+
+   .. class:: ArrayModule
+
+      Supported dense array modules.
+
+   .. class:: SparseArray
+
+      Supported sparse array types.
+
+   .. class:: SparseModule
+
+      Supported sparse array modules.
+
+   .. class:: OpT
+
+      Top-level abstract :py:class:`~pyxu.abc.Operator` interface exposed to users.
+
+   .. autodata:: Property
+      :no-value:
+
+   .. class:: SolverT
+
+      Top-level abstract :py:class:`~pyxu.abc.Solver` interface exposed to users.
+
+   .. class:: SolverM
+
+      Solver run-mode(s).
+
+   .. class:: Real
+
+      Alias of :py:class:`numbers.Real`.
+
+   .. data:: DType
+
+      :py:attr:`~pyxu.info.ptype.NDArray` dtype specifier.
diff --git a/_sources/api/info.rst b/_sources/api/info.rst
deleted file mode 100644
index 7337a2a8..00000000
--- a/_sources/api/info.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-pyxu.info
-=========
-
-.. contents:: Table of Contents
-   :local:
-   :depth: 1
-   
-pyxu.info.ptype
----------------
-
-.. automodule:: pyxu.info.ptype
-
-pyxu.info.deps
---------------
-
-.. automodule:: pyxu.info.deps
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pyxu.info.warning
------------------
-
-.. automodule:: pyxu.info.warning
-   :no-special-members:
-   :exclude-members: add_note, args, with_traceback
diff --git a/_sources/api/operator.rst b/_sources/api/operator.rst
deleted file mode 100644
index c8a06615..00000000
--- a/_sources/api/operator.rst
+++ /dev/null
@@ -1,245 +0,0 @@
-pyxu.operator
-=============
-
-.. pyxu.operator.map.base -----------------------------------------------------
-
-.. autofunction:: pyxu.operator.ConstantValued
-
-.. pyxu.operator.func.norm ----------------------------------------------------
-
-.. autoclass:: pyxu.operator.L1Norm
-   :no-members:
-
-.. autoclass:: pyxu.operator.L2Norm
-   :no-members:
-
-.. autoclass:: pyxu.operator.SquaredL2Norm
-   :no-members:
-
-.. autoclass:: pyxu.operator.SquaredL1Norm
-   :no-members:
-   :members: prox
-   :special-members: __init__
-
-.. autofunction:: pyxu.operator.shift_loss
-
-.. autoclass:: pyxu.operator.KLDivergence
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.LInfinityNorm
-   :no-members:
-
-.. autoclass:: pyxu.operator.L21Norm
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.PositiveL1Norm
-   :no-members:
-
-.. pyxu.operator.func.indicator -----------------------------------------------
-
-.. autofunction:: pyxu.operator.L1Ball
-
-.. autofunction:: pyxu.operator.L2Ball
-
-.. autofunction:: pyxu.operator.LInfinityBall
-
-.. autoclass:: pyxu.operator.PositiveOrthant
-   :no-members:
-
-.. autoclass:: pyxu.operator.HyperSlab
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.RangeSet
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.AffineSet
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.ConvexSetIntersection
-   :no-members:
-   :members: prox
-   :special-members: __init__
-
-.. pyxu.operator.blocks -------------------------------------------------------
-
-.. autofunction:: pyxu.operator.stack
-
-.. autofunction:: pyxu.operator.vstack
-
-.. autofunction:: pyxu.operator.hstack
-
-.. autofunction:: pyxu.operator.block_diag
-
-.. autofunction:: pyxu.operator.block
-
-.. autofunction:: pyxu.operator.coo_block
-
-.. pyxu.operator.map.ufunc ----------------------------------------------------
-
-.. autofunction:: pyxu.operator.sin
-
-.. autofunction:: pyxu.operator.cos
-
-.. autofunction:: pyxu.operator.tan
-
-.. autofunction:: pyxu.operator.arcsin
-
-.. autofunction:: pyxu.operator.arccos
-
-.. autofunction:: pyxu.operator.arctan
-
-.. autofunction:: pyxu.operator.sinh
-
-.. autofunction:: pyxu.operator.cosh
-
-.. autofunction:: pyxu.operator.tanh
-
-.. autofunction:: pyxu.operator.arcsinh
-
-.. autofunction:: pyxu.operator.arccosh
-
-.. autofunction:: pyxu.operator.arctanh
-
-.. autofunction:: pyxu.operator.exp
-
-.. autofunction:: pyxu.operator.log
-
-.. autofunction:: pyxu.operator.clip
-
-.. autofunction:: pyxu.operator.sqrt
-
-.. autofunction:: pyxu.operator.cbrt
-
-.. autofunction:: pyxu.operator.square
-
-.. autofunction:: pyxu.operator.abs
-
-.. autofunction:: pyxu.operator.sign
-
-.. autofunction:: pyxu.operator.gaussian
-
-.. autofunction:: pyxu.operator.sigmoid
-
-.. autofunction:: pyxu.operator.softplus
-
-.. autofunction:: pyxu.operator.leakyrelu
-
-.. autofunction:: pyxu.operator.relu
-
-.. autofunction:: pyxu.operator.silu
-
-.. autofunction:: pyxu.operator.softmax
-
-.. pyxu.operator.linop.select -------------------------------------------------
-
-.. autoclass:: pyxu.operator.SubSample
-   :no-members:
-   :members: apply, adjoint, TrimSpec, IndexSpec
-   :special-members: __init__
-
-.. autofunction:: pyxu.operator.Trim
-
-.. pyxu.operator.linop.reduce -------------------------------------------------
-
-.. autofunction:: pyxu.operator.Sum
-
-.. pyxu.operator.linop.kron ---------------------------------------------------
-
-.. autofunction:: pyxu.operator.kron
-
-.. autofunction:: pyxu.operator.khatri_rao
-
-.. pyxu.operator.linop.base ---------------------------------------------------
-
-.. autoclass:: pyxu.operator.IdentityOp
-   :no-members:
-
-.. autoclass:: pyxu.operator.NullOp
-   :no-members:
-
-.. autofunction:: pyxu.operator.NullFunc
-
-.. autofunction:: pyxu.operator.HomothetyOp
-
-.. autofunction:: pyxu.operator.DiagonalOp
-
-.. pyxu.operator.linop.pad ----------------------------------------------------
-
-.. autoclass:: pyxu.operator.Pad
-   :no-members:
-   :members: WidthSpec, ModeSpec
-   :special-members: __init__
-
-.. pyxu.operator.linop.stencil ------------------------------------------------
-
-.. autoclass:: pyxu.operator._Stencil
-   :no-members:
-   :members: init, apply, IndexSpec
-
-.. autoclass:: pyxu.operator.Stencil
-   :no-members:
-   :members: KernelSpec, configure_dispatcher, kernel, center, relative_indices, visualize
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.Correlate
-
-.. autofunction:: pyxu.operator.Convolve
-
-.. pyxu.operator.linop.fft ----------------------------------------------------
-
-.. autoclass:: pyxu.operator.FFT
-   :no-members:
-   :members: apply, adjoint
-   :special-members: __init__
-
-.. autoclass:: pyxu.operator.NUFFT
-   :no-members:
-   :members: type1, type2, type3, apply, adjoint, ascomplexarray, mesh, plot_kernel, params, auto_chunk, allocate, diagnostic_plot, stats
-
-.. pyxu.operator.linop.diff ---------------------------------------------------
-
-.. autoclass:: pyxu.operator.PartialDerivative
-   :members: finite_difference, gaussian_derivative
-
-.. autofunction:: pyxu.operator.Gradient
-
-.. autofunction:: pyxu.operator.Jacobian
-
-.. autofunction:: pyxu.operator.Divergence
-
-.. autofunction:: pyxu.operator.Hessian
-
-.. autofunction:: pyxu.operator.Laplacian
-
-.. autofunction:: pyxu.operator.DirectionalDerivative
-
-.. autofunction:: pyxu.operator.DirectionalGradient
-
-.. autofunction:: pyxu.operator.DirectionalLaplacian
-
-.. autofunction:: pyxu.operator.DirectionalHessian
-
-.. pyxu.operator.linop.filter -------------------------------------------------
-
-.. autofunction:: pyxu.operator.MovingAverage
-
-.. autofunction:: pyxu.operator.Gaussian
-
-.. autofunction:: pyxu.operator.DifferenceOfGaussians
-
-.. autofunction:: pyxu.operator.DoG
-
-.. autofunction:: pyxu.operator.Laplace
-
-.. autofunction:: pyxu.operator.Sobel
-
-.. autofunction:: pyxu.operator.Prewitt
-
-.. autofunction:: pyxu.operator.Scharr
-
-.. autoclass:: pyxu.operator.StructureTensor
diff --git a/_sources/api/operator/interop.rst b/_sources/api/operator/interop.rst
deleted file mode 100644
index d4192034..00000000
--- a/_sources/api/operator/interop.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-pyxu.operator.interop
-=====================
-
-.. contents:: Table of Contents
-   :local:
-   :depth: 1
-
-Generic Constructor
--------------------
-
-.. autofunction:: pyxu.operator.interop.source.from_source
-
-SciPy Interoperability
-----------------------
-
-.. autofunction:: pyxu.operator.interop.sciop.from_sciop
-
-JAX Interoperability
---------------------
-
-.. autofunction:: pyxu.operator.interop.jax.from_jax
-
-.. autofunction:: pyxu.operator.interop.jax._from_jax
-
-.. autofunction:: pyxu.operator.interop.jax._to_jax
-
-PyTorch Interoperability
-------------------------
-
-.. autofunction:: pyxu.operator.interop.torch.from_torch
-
-.. autofunction:: pyxu.operator.interop.torch.astensor
-
-.. autofunction:: pyxu.operator.interop.torch.asarray
diff --git a/_sources/api/opt.rst b/_sources/api/opt.rst
deleted file mode 100644
index ff06006f..00000000
--- a/_sources/api/opt.rst
+++ /dev/null
@@ -1,94 +0,0 @@
-pyxu.opt
-========
-
-.. contents:: Table of Contents
-   :local:
-   :depth: 1
-
-pyxu.opt.stop
--------------
-
-.. autoclass:: pyxu.opt.stop.MaxIter
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.opt.stop.ManualStop
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.opt.stop.MaxDuration
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.opt.stop.MaxCarbon
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.opt.stop.Memorize
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.opt.stop.AbsError
-   :no-members:
-   :special-members: __init__
-
-.. autoclass:: pyxu.opt.stop.RelError
-   :no-members:
-   :special-members: __init__
-
-pyxu.opt.solver
----------------
-
-.. autoclass:: pyxu.opt.solver.pgd.PGD
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.cg.CG
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.nlcg.NLCG
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.adam.Adam
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.CondatVu
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.CV
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.PD3O
-   :no-members:
-
-.. autofunction:: pyxu.opt.solver.pds.ChambollePock
-
-.. autofunction:: pyxu.opt.solver.pds.CP
-
-.. autoclass:: pyxu.opt.solver.pds.LorisVerhoeven
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.LV
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.DavisYin
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.DY
-   :no-members:
-
-.. autofunction:: pyxu.opt.solver.pds.DouglasRachford
-
-.. autofunction:: pyxu.opt.solver.pds.DR
-
-.. autoclass:: pyxu.opt.solver.pds.ForwardBackward
-   :no-members:
-
-.. autoclass:: pyxu.opt.solver.pds.FB
-   :no-members:
-
-.. autofunction:: pyxu.opt.solver.pds.ProximalPoint
-
-.. autofunction:: pyxu.opt.solver.pds.PP
-
-.. autoclass:: pyxu.opt.solver.pds.ADMM
-   :no-members:
diff --git a/_sources/api/util.rst b/_sources/api/util.rst
index d3d99d53..3b9dcff5 100644
--- a/_sources/api/util.rst
+++ b/_sources/api/util.rst
@@ -1,14 +1,60 @@
 pyxu.util
 =========
 
-.. automodule:: pyxu.util
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
 
-   .. Force document of some non-public functions.
+pyxu.util.array_module
+----------------------
 
-   .. autofunction:: pyxu.util.misc.peaks
+.. autofunction:: pyxu.util.get_array_module
 
-   .. autofunction:: pyxu.util.misc.star_like_sample
+.. autofunction:: pyxu.util.redirect
 
-   .. autofunction:: pyxu.util.operator._dask_zip
+.. autofunction:: pyxu.util.compute
 
-   .. autofunction:: pyxu.util.operator._array_ize
+.. autofunction:: pyxu.util.to_NUMPY
+
+pyxu.util.complex
+-----------------
+
+.. autofunction:: pyxu.util.view_as_complex_mat
+
+.. autofunction:: pyxu.util.view_as_complex
+
+.. autofunction:: pyxu.util.view_as_real_mat
+
+.. autofunction:: pyxu.util.view_as_real
+
+pyxu.util.misc
+--------------
+
+.. autofunction:: pyxu.util.copy_if_unsafe
+
+.. autofunction:: pyxu.util.import_module
+
+.. autofunction:: pyxu.util.infer_composition_shape
+
+.. autofunction:: pyxu.util.infer_sum_shape
+
+.. autofunction:: pyxu.util.next_fast_len
+
+.. autofunction:: pyxu.util.parse_params
+
+.. autofunction:: pyxu.util.read_only
+
+.. autofunction:: pyxu.util.misc.peaks
+
+.. autofunction:: pyxu.util.misc.star_like_sample
+
+pyxu.util.operator
+------------------
+
+.. autofunction:: pyxu.util.as_canonical_shape
+
+.. autofunction:: pyxu.util.vectorize
+
+.. autofunction:: pyxu.util.operator._array_ize
+
+.. autofunction:: pyxu.util.operator._dask_zip
diff --git a/_sources/api/util/array_module.rst b/_sources/api/util/array_module.rst
index a3067b44..9d48670d 100644
--- a/_sources/api/util/array_module.rst
+++ b/_sources/api/util/array_module.rst
@@ -4,3 +4,7 @@ pyxu.util.array_module
 .. autofunction:: pyxu.util.get_array_module
 
 .. autofunction:: pyxu.util.redirect
+
+.. autofunction:: pyxu.util.compute
+
+.. autofunction:: pyxu.util.to_NUMPY
diff --git a/_sources/api/util/misc.rst b/_sources/api/util/misc.rst
index f1ef45d8..ca8bfff7 100644
--- a/_sources/api/util/misc.rst
+++ b/_sources/api/util/misc.rst
@@ -1,8 +1,6 @@
 pyxu.util.misc
 ==============
 
-.. autofunction:: pyxu.util.compute
-
 .. autofunction:: pyxu.util.copy_if_unsafe
 
 .. autofunction:: pyxu.util.import_module
@@ -17,8 +15,6 @@ pyxu.util.misc
 
 .. autofunction:: pyxu.util.read_only
 
-.. autofunction:: pyxu.util.to_NUMPY
-
 .. autofunction:: pyxu.util.misc.peaks
 
 .. autofunction:: pyxu.util.misc.star_like_sample
diff --git a/_sources/examples/contributing.ipynb b/_sources/examples/contributing.ipynb
new file mode 100644
index 00000000..817f3fd3
--- /dev/null
+++ b/_sources/examples/contributing.ipynb
@@ -0,0 +1,134 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "92ed2e98",
+   "metadata": {},
+   "source": [
+    "# Using Contributed Plugins in Pyxu\n",
+    "\n",
+    "In this notebook, we will explore how to use contributed plugins in the Pyxu software framework. We will focus on the `pyxu-gradient-descent` plugin. \n",
+    "\n",
+    "## Step 1: Attempting to Import Before Installation\n",
+    "\n",
+    "Before installing the plugin, let's try importing an object from the `pyxu-gradient-descent` namespace to see what happens.\n",
+    "```python\n",
+    "try:\n",
+    "    from pyxu.opt.solver import GradientDescent\n",
+    "except ImportError as e:\n",
+    "    print(e)\n",
+    "```\n",
+    "\n",
+    "
        \n",
+    "\n",
+    "cannot import name 'GradientDescent' from 'pyxu.opt.solver' (pyxu/opt/solver/__init__.py)\n",
+    "\n",
+    "    \n",
+    "
        \n",
+    "\n",
+    "\n",
+    "You should see an *ImportError*, indicating that the objects are not available because the plugin is not installed yet.\n",
+    "\n",
+    "## Step 2: Installing the Plugin\n",
+    "\n",
+    "To install the pyxu-gradient-descent plugin, use the following magic command:\n",
+    "\n",
+    "```python\n",
+    "!pip install pyxu-gradient-descent\n",
+    "```\n",
+    "\n",
+    "## Step 3: Importing the Necessary Objects\n",
+    "\n",
+    "Now that we have installed the plugin, let's import the necessary objects:\n",
+    "\n",
+    "```python\n",
+    "from pyxu.operator import SquaredL2Norm\n",
+    "from pyxu.opt.solver import GradientDescent\n",
+    "import numpy as np\n",
+    "```\n",
+    "
        \n",
+    "pyxu/info/plugin.py:69: ContributionWarning: Plugin `GradientDescent` loaded, use with caution.\n",
+    "  warnings.warn(f\"Plugin `{name}` loaded, use with caution.\", pxw.ContributionWarning)\n",
+    "
        \n",
+    "\n",
+    "The warning signals that a class or function has been imported from external code into the core Pyxu codebase, and should be used with caution. \n",
+    "\n",
+    "## Step 4: Using the Gradient Descent Algorithm\n",
+    "\n",
+    "In this step, we will use the gradient descent algorithm to minimize a function defined by the squared L2 norm. Here is how you can do it:\n",
+    "\n",
+    "```python\n",
+    "# Define the dimension\n",
+    "N = 100\n",
+    "\n",
+    "# Generate random data\n",
+    "rng = np.random.default_rng(seed=0)\n",
+    "y = rng.uniform(size=N)\n",
+    "\n",
+    "# Define the loss function\n",
+    "loss = SquaredL2Norm(dim=N).asloss(y)\n",
+    "\n",
+    "# Initialize the gradient descent algorithm\n",
+    "gd = GradientDescent(f=loss)\n",
+    "\n",
+    "# Define the initial point\n",
+    "x0 = np.random.randn(N)\n",
+    "\n",
+    "# Run the gradient descent algorithm\n",
+    "gd.fit(x0=x0, acceleration=True)\n",
+    "\n",
+    "# Check the solution\n",
+    "assert np.allclose(gd.solution(), y)\n",
+    "```\n",
+    "
        \n",
+    "\n",
+    "INFO -- [2023-09-13 09:28:52.933466] Iteration 0\n",
+    "    \n",
+    "\titeration: 0\n",
+    "    RelError[x]: 0.0\n",
+    "\n",
+    "INFO -- [2023-09-13 09:28:52.934287] Iteration 1\n",
+    "\n",
+    "    iteration: 1\n",
+    "    RelError[x]: 1.1798071385920126\n",
+    "\n",
+    "INFO -- [2023-09-13 09:28:52.934882] Iteration 2\n",
+    "\n",
+    "    iteration: 2\n",
+    "    RelError[x]: 9.55411637565644e-17\n",
+    "\n",
+    "INFO -- [2023-09-13 09:28:52.935515] Stopping Criterion satisfied -> END\n",
+    "\n",
+    "
        \n",
+    "\n",
+    "\n",
+    "If everything runs without errors, it means that the gradient descent algorithm has successfully found a solution that is close to the input data.\n",
+    "\n",
+    "## Conclusion\n",
+    "\n",
+    "In this notebook, we have seen how to use contributed plugins in the Pyxu software framework. We learned how to install a plugin and use it to run a gradient descent algorithm. We hope this guide has been helpful, and encourage you to explore other plugins available for the Pyxu framework."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/_sources/examples/index.rst b/_sources/examples/index.rst
index 0af24139..6cf5bb3a 100644
--- a/_sources/examples/index.rst
+++ b/_sources/examples/index.rst
@@ -4,12 +4,12 @@ Example Gallery
 .. nblinkgallery::
     :name: rst-link-gallery
 
-    Stencils
-    DifferentialOperators
+    stencils
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
-   Stencils
-   DifferentialOperators
+   contributing
+   stencils
+
diff --git a/_sources/examples/Stencils.ipynb b/_sources/examples/stencils.ipynb
similarity index 100%
rename from _sources/examples/Stencils.ipynb
rename to _sources/examples/stencils.ipynb
diff --git a/_sources/fair/howto.rst b/_sources/fair/howto.rst
index b52b4a9d..149e08db 100644
--- a/_sources/fair/howto.rst
+++ b/_sources/fair/howto.rst
@@ -26,7 +26,7 @@ For instance:
 
   .. code-block:: python
 
-     import pyxu.opt.solver.GradientDescent
+     from pyxu.opt.solver import GradientDescent
 
 - Without the installation of the plugin, the previous line of code would have raised an error.
 
@@ -55,9 +55,27 @@ as:
 * `pyxu.math <../api/math.html>`_
 * pyxu.contrib: for any other contribution
 
+To override a class or function in the core Pyxu framework, simply use the identical name as the target you wish to override.
+This process involves a critical step: specifying your intention in the setup.cfg file by prefixing the new entry point
+with an underscore (``_``).
+
+For example, to override the ``NullFunc`` class housed within the ``pyxu.operator.func`` namespace, insert the following
+directive in your setup.cfg file:
+
+.. code-block:: ini
+
+    [options.entry_points]
+       pyxu.operator.func =
+        _NullFunc = your_module_name:NullFunc
+
+
 Once ready, publish your plugin on `PyPI `_. The Pyxu-FAIR periodically scans PyPI for new plugins and
 `scores <./score.html>`_ them based on their popularity and quality. The higher the score, the higher the chances of your
 plugin being discovered by Pyxu users.
 
+If you believe your plugin enhances the Pyxu core codebase, we encourage you to reach out so we can evaluate the possibility
+of incorporating it. Even if you're uncertain, don't hesitate to open an issue on the `Pyxu GitHub repository `_
+for feedback and guidance.
+
 🌟 No matter your expertise level, the Pyxu-FAIR ensures a smooth experience. Dive in, and may your Pyxu journey be
 FAIR and fantastic! 🌟
diff --git a/_sources/fair/index.rst b/_sources/fair/index.rst
index dfe44c09..436f3025 100644
--- a/_sources/fair/index.rst
+++ b/_sources/fair/index.rst
@@ -233,3 +233,4 @@ communicate with the main framework.
    dev_notes
    score
    plugins/index
+   plugins_preview/index
diff --git a/_sources/fair/plugins/index.rst b/_sources/fair/plugins/index.rst
index 04cfde22..4f97ef7d 100644
--- a/_sources/fair/plugins/index.rst
+++ b/_sources/fair/plugins/index.rst
@@ -181,937 +181,132 @@
     }
     
 
-**************
-Plugin Catalog
-**************
+*********
+Catalogue
+*********
 
 
 .. raw:: html
 
-    
        Plugin Catalogue
        
+    
        Catalogue
        
 
 
-**Total Registered Plugin Packages: 17**
+**Total Registered Plugin Packages: 2**
 
 .. raw:: html
 
    
        
         
        
-
+            
             
                 Operator
-                17 plugins in 12 packages 
+                0 plugins in 0 packages 
             
-
+        
             
                 Solver
-                14 plugins in 10 packages 
+                1 plugin in 1 package 
             
-
+        
             
                 Stop
-                18 plugins in 11 packages 
+                0 plugins in 0 packages 
             
-
+        
             
                 Math
-                16 plugins in 10 packages 
+                1 plugin in 1 package 
             
-
+        
             
                 Contrib
-                20 plugins in 12 packages 
+                0 plugins in 0 packages 
             
-
+        
         
        
     
        
 
-**Plugin in alphabetical order:**
+**Plugin list in alphabetical order**
 
 
 .. grid:: 2 2 3 3
     :gutter: 3
 
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        CSEEG
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Solver
-                    1
-                
-
-            
        
-
-
+    
     .. grid-item-card::
 
         .. raw:: html
 
-            
        DSP-Notebooks
        
+            
        pyxu-eigh
        
 
             
        
-
-                 
        
+                
+                 
        
 
             
 
             
        
-
-                
-                    Operator
-                    2
-                
-
-                
-                    Stop
-                    2
-                
-
+                
                 
                     Math
-                    3
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        EnvironTracker
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        HoughDetector
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    1
-                
-
-                
-                    Solver
                     1
                 
-
-                
-                    Contrib
-                    4
-                
-
+                
             
        
 
-
+    
     .. grid-item-card::
 
         .. raw:: html
 
-            
        HVOX
        
+            
        pyxu-gradient-descent
        
 
             
        
-
-                 
        
+                
+                 
        
 
             
 
             
        
-
-                
-                    Operator
-                    1
-                
-
+                
                 
                     Solver
                     1
                 
-
-                
-                    Stop
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        OrientationPy
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    2
-                
-
-                
-                    Stop
-                    1
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        Palentologist
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Stop
-                    1
-                
-
-                
-                    Math
-                    1
-                
-
+                
             
        
 
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        PhaseRet
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    2
-                
-
-                
-                    Stop
-                    3
-                
-
-                
-                    Contrib
-                    3
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        PycGSP
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    2
-                
-
-                
-                    Solver
-                    1
-                
-
-                
-                    Math
-                    3
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        pycNUFFT
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    1
-                
-
-                
-                    Solver
-                    2
-                
-
-                
-                    Math
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        PycSphere
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    1
-                
-
-                
-                    Solver
-                    1
-                
-
-                
-                    Stop
-                    2
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        pycWavelet
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Solver
-                    2
-                
-
-                
-                    Stop
-                    3
-                
-
-                
-                    Math
-                    3
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        PYFW
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    2
-                
-
-                
-                    Stop
-                    1
-                
-
-                
-                    Math
-                    1
-                
-
-                
-                    Contrib
-                    2
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        TokemakRec
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    1
-                
-
-                
-                    Solver
-                    3
-                
-
-                
-                    Stop
-                    2
-                
-
-                
-                    Math
-                    1
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        TVDenoiser
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    1
-                
-
-                
-                    Solver
-                    1
-                
-
-                
-                    Stop
-                    1
-                
-
-                
-                    Math
-                    1
-                
-
-                
-                    Contrib
-                    3
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        UncertaintyQuant
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Math
-                    1
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
-    .. grid-item-card::
-
-        .. raw:: html
-
-            
        WaveProp
        
-
-            
        
-
-                 
        
-
-            
-
-            
        
-
-                
-                    Operator
-                    1
-                
-
-                
-                    Solver
-                    1
-                
-
-                
-                    Stop
-                    1
-                
-
-                
-                    Math
-                    1
-                
-
-                
-                    Contrib
-                    1
-                
-
-            
        
-
-
+    
 
 
 
@@ -1119,20 +314,6 @@ Plugin Catalog
    :maxdepth: 1
    :hidden:
 
-   CSEEG
-   DSP-Notebooks
-   EnvironTracker
-   HoughDetector
-   HVOX
-   OrientationPy
-   Palentologist
-   PhaseRet
-   PycGSP
-   pycNUFFT
-   PycSphere
-   pycWavelet
-   PYFW
-   TokemakRec
-   TVDenoiser
-   UncertaintyQuant
-   WaveProp
+   pyxu-eigh
+   pyxu-gradient-descent
+   
\ No newline at end of file
diff --git a/_sources/fair/plugins/pyxu-eigh.rst b/_sources/fair/plugins/pyxu-eigh.rst
new file mode 100644
index 00000000..65006100
--- /dev/null
+++ b/_sources/fair/plugins/pyxu-eigh.rst
@@ -0,0 +1,244 @@
+.. _plugins-page:
+
+.. |br| raw:: html
+
+   
        
+
+.. raw:: html
+
+    
+    
+
+*********
+pyxu-eigh
+*********
+
+
+Description
+===========
+
+.. raw:: html
+    Pyxu plugin to compute the eigenvectors and eigenvalues of a real symmetric matrix
+
+
+
+General information
+===================
+
+.. raw:: html
+
+    
+    
        
+        Short description: Pyxu plugin to compute the eigenvectors and eigenvalues of a real symmetric matrix
+    
        
+    
+
+    
        
+        
+        
        
+    
+
+    
        
+        Source code: Go to the source code repository
+    
        
+
+    
+    
        
+        Documentation: No documentation provided by the package author
+    
        
+    
+
+
+Detailed information
+====================
+
+.. raw:: html
+    
+    
        
+        Author(s): Joan Rue Queralt
+    
        
+    
+    
+    
        
+        Contact: joan.rue.q@gmail.com
+    
        
+    
+    
+    
        
+        Most recent version: 0.1.0
+    
        
+    
        
+        Compatibility:
+        
+    
        
+    
+
+
+Components contributed
+======================
+
+.. raw:: html
+    
        
+        
+        
+            Math
+            1
+        
+        
+    
        
+    
+    
+    
+      Math (pyxu.math)
+    
+    
          
+    
+    
        • eigh
+    
+    
        
+    
+    
\ No newline at end of file
diff --git a/_sources/fair/plugins/pyxu-gradient-descent.rst b/_sources/fair/plugins/pyxu-gradient-descent.rst
new file mode 100644
index 00000000..758cbacc
--- /dev/null
+++ b/_sources/fair/plugins/pyxu-gradient-descent.rst
@@ -0,0 +1,244 @@
+.. _plugins-page:
+
+.. |br| raw:: html
+
+   
        
+
+.. raw:: html
+
+    
+    
+
+*********************
+pyxu-gradient-descent
+*********************
+
+
+Description
+===========
+
+.. raw:: html
+    An accelerated gradient descent optimizer for Pyxu
+
+
+
+General information
+===================
+
+.. raw:: html
+
+    
+    
        
+        Short description: An accelerated gradient descent optimizer for Pyxu
+    
        
+    
+
+    
        
+        
+        
        
+    
+
+    
        
+        Source code: Go to the source code repository
+    
        
+
+    
+    
        
+        Documentation: No documentation provided by the package author
+    
        
+    
+
+
+Detailed information
+====================
+
+.. raw:: html
+    
+    
        
+        Author(s): Joan Rue Queralt
+    
        
+    
+    
+    
        
+        Contact: joan.rue.q@gmail.com
+    
        
+    
+    
+    
        
+        Most recent version: 0.1.0
+    
        
+    
        
+        Compatibility:
+        
+    
        
+    
+
+
+Components contributed
+======================
+
+.. raw:: html
+    
        
+        
+        
+            Solver
+            1
+        
+        
+    
        
+    
+    
+    
+      Solver (pyxu.solver)
+    
+    
          
+    
+    
        • GradientDescent
+    
+    
        
+    
+    
\ No newline at end of file
diff --git a/_sources/fair/plugins/CSEEG.rst b/_sources/fair/plugins_preview/CSEEG.rst
similarity index 100%
rename from _sources/fair/plugins/CSEEG.rst
rename to _sources/fair/plugins_preview/CSEEG.rst
diff --git a/_sources/fair/plugins/DSP-Notebooks.rst b/_sources/fair/plugins_preview/DSP-Notebooks.rst
similarity index 100%
rename from _sources/fair/plugins/DSP-Notebooks.rst
rename to _sources/fair/plugins_preview/DSP-Notebooks.rst
diff --git a/_sources/fair/plugins/EnvironTracker.rst b/_sources/fair/plugins_preview/EnvironTracker.rst
similarity index 100%
rename from _sources/fair/plugins/EnvironTracker.rst
rename to _sources/fair/plugins_preview/EnvironTracker.rst
diff --git a/_sources/fair/plugins/HVOX.rst b/_sources/fair/plugins_preview/HVOX.rst
similarity index 100%
rename from _sources/fair/plugins/HVOX.rst
rename to _sources/fair/plugins_preview/HVOX.rst
diff --git a/_sources/fair/plugins/HoughDetector.rst b/_sources/fair/plugins_preview/HoughDetector.rst
similarity index 100%
rename from _sources/fair/plugins/HoughDetector.rst
rename to _sources/fair/plugins_preview/HoughDetector.rst
diff --git a/_sources/fair/plugins/OrientationPy.rst b/_sources/fair/plugins_preview/OrientationPy.rst
similarity index 100%
rename from _sources/fair/plugins/OrientationPy.rst
rename to _sources/fair/plugins_preview/OrientationPy.rst
diff --git a/_sources/fair/plugins/PYFW.rst b/_sources/fair/plugins_preview/PYFW.rst
similarity index 100%
rename from _sources/fair/plugins/PYFW.rst
rename to _sources/fair/plugins_preview/PYFW.rst
diff --git a/_sources/fair/plugins/Palentologist.rst b/_sources/fair/plugins_preview/Palentologist.rst
similarity index 100%
rename from _sources/fair/plugins/Palentologist.rst
rename to _sources/fair/plugins_preview/Palentologist.rst
diff --git a/_sources/fair/plugins/PhaseRet.rst b/_sources/fair/plugins_preview/PhaseRet.rst
similarity index 100%
rename from _sources/fair/plugins/PhaseRet.rst
rename to _sources/fair/plugins_preview/PhaseRet.rst
diff --git a/_sources/fair/plugins/PycGSP.rst b/_sources/fair/plugins_preview/PycGSP.rst
similarity index 100%
rename from _sources/fair/plugins/PycGSP.rst
rename to _sources/fair/plugins_preview/PycGSP.rst
diff --git a/_sources/fair/plugins/PycSphere.rst b/_sources/fair/plugins_preview/PycSphere.rst
similarity index 100%
rename from _sources/fair/plugins/PycSphere.rst
rename to _sources/fair/plugins_preview/PycSphere.rst
diff --git a/_sources/fair/plugins/TVDenoiser.rst b/_sources/fair/plugins_preview/TVDenoiser.rst
similarity index 100%
rename from _sources/fair/plugins/TVDenoiser.rst
rename to _sources/fair/plugins_preview/TVDenoiser.rst
diff --git a/_sources/fair/plugins/TokemakRec.rst b/_sources/fair/plugins_preview/TokemakRec.rst
similarity index 100%
rename from _sources/fair/plugins/TokemakRec.rst
rename to _sources/fair/plugins_preview/TokemakRec.rst
diff --git a/_sources/fair/plugins/UncertaintyQuant.rst b/_sources/fair/plugins_preview/UncertaintyQuant.rst
similarity index 100%
rename from _sources/fair/plugins/UncertaintyQuant.rst
rename to _sources/fair/plugins_preview/UncertaintyQuant.rst
diff --git a/_sources/fair/plugins/WaveProp.rst b/_sources/fair/plugins_preview/WaveProp.rst
similarity index 100%
rename from _sources/fair/plugins/WaveProp.rst
rename to _sources/fair/plugins_preview/WaveProp.rst
diff --git a/_sources/fair/plugins_preview/index.rst b/_sources/fair/plugins_preview/index.rst
new file mode 100644
index 00000000..aee37f61
--- /dev/null
+++ b/_sources/fair/plugins_preview/index.rst
@@ -0,0 +1,1138 @@
+:html_theme.sidebar_secondary.remove:
+:sd_hide_title: true
+
+.. |br| raw:: html
+
+   
        
+
+.. raw:: html
+
+    
+    
+
+**********************
+Plugin Preview Catalog
+**********************
+
+
+.. raw:: html
+
+    
        Plugin Catalogue
        
+
+
+**Total Registered Plugin Packages: 17**
+
+.. raw:: html
+
+   
        
+        
        
+
+            
+                Operator
+                17 plugins in 12 packages 
+            
+
+            
+                Solver
+                14 plugins in 10 packages 
+            
+
+            
+                Stop
+                18 plugins in 11 packages 
+            
+
+            
+                Math
+                16 plugins in 10 packages 
+            
+
+            
+                Contrib
+                20 plugins in 12 packages 
+            
+
+        
        
+    
        
+
+**Plugin in alphabetical order:**
+
+
+.. grid:: 2 2 3 3
+    :gutter: 3
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        CSEEG
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Solver
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        DSP-Notebooks
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    2
+                
+
+                
+                    Stop
+                    2
+                
+
+                
+                    Math
+                    3
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        EnvironTracker
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        HoughDetector
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    1
+                
+
+                
+                    Contrib
+                    4
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        HVOX
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    1
+                
+
+                
+                    Stop
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        OrientationPy
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    2
+                
+
+                
+                    Stop
+                    1
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        Palentologist
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Stop
+                    1
+                
+
+                
+                    Math
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        PhaseRet
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    2
+                
+
+                
+                    Stop
+                    3
+                
+
+                
+                    Contrib
+                    3
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        PycGSP
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    2
+                
+
+                
+                    Solver
+                    1
+                
+
+                
+                    Math
+                    3
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        pycNUFFT
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    2
+                
+
+                
+                    Math
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        PycSphere
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    1
+                
+
+                
+                    Stop
+                    2
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        pycWavelet
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Solver
+                    2
+                
+
+                
+                    Stop
+                    3
+                
+
+                
+                    Math
+                    3
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        PYFW
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    2
+                
+
+                
+                    Stop
+                    1
+                
+
+                
+                    Math
+                    1
+                
+
+                
+                    Contrib
+                    2
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        TokemakRec
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    3
+                
+
+                
+                    Stop
+                    2
+                
+
+                
+                    Math
+                    1
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        TVDenoiser
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    1
+                
+
+                
+                    Stop
+                    1
+                
+
+                
+                    Math
+                    1
+                
+
+                
+                    Contrib
+                    3
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        UncertaintyQuant
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Math
+                    1
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+    .. grid-item-card::
+
+        .. raw:: html
+
+            
        WaveProp
        
+
+            
        
+
+                 
        
+
+            
+
+            
        
+
+                
+                    Operator
+                    1
+                
+
+                
+                    Solver
+                    1
+                
+
+                
+                    Stop
+                    1
+                
+
+                
+                    Math
+                    1
+                
+
+                
+                    Contrib
+                    1
+                
+
+            
        
+
+
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   CSEEG
+   DSP-Notebooks
+   EnvironTracker
+   HoughDetector
+   HVOX
+   OrientationPy
+   Palentologist
+   PhaseRet
+   PycGSP
+   pycNUFFT
+   PycSphere
+   pycWavelet
+   PYFW
+   TokemakRec
+   TVDenoiser
+   UncertaintyQuant
+   WaveProp
diff --git a/_sources/fair/plugins/pycNUFFT.rst b/_sources/fair/plugins_preview/pycNUFFT.rst
similarity index 100%
rename from _sources/fair/plugins/pycNUFFT.rst
rename to _sources/fair/plugins_preview/pycNUFFT.rst
diff --git a/_sources/fair/plugins/pycWavelet.rst b/_sources/fair/plugins_preview/pycWavelet.rst
similarity index 100%
rename from _sources/fair/plugins/pycWavelet.rst
rename to _sources/fair/plugins_preview/pycWavelet.rst
diff --git a/_sources/fair/score.rst b/_sources/fair/score.rst
index 70a9e4e8..34fdd4f5 100644
--- a/_sources/fair/score.rst
+++ b/_sources/fair/score.rst
@@ -1,15 +1,21 @@
 Pyxu Score Explained
 ====================
 
-The **Pyxu Score** is a quantitative measure we use to rank and evaluate Pyxu plugins. The score takes into account
-multiple criteria, ensuring you get a holistic understanding of a plugin's standing. Here's a breakdown:
+The **Pyxu Score** is a quantitative measure we use to rank and evaluate `Pyxu plugins <./plugins/index.html>`_.
 
-The Pyxu Score is calculated using the following criteria:
+.. warning::
 
-1. **Version Matching**: If a plugin's version matches the latest Pyxu version, it gets a point.
-2. **Pyxu Principles Adherence**: Plugins abiding by key Pyxu principles, namely:
+    While the Pyxu Score offers insights into a plugin's quality and popularity, it's just one of many metrics.
+    Users are encouraged to explore plugins individually and consider other factors before making a decision.
+
+The score takes into account multiple criteria, ensuring you get a holistic understanding of a plugin's standing. Here's
+a breakdown:
+
+1. **Version Matching**: If a plugin's version matches the latest Pyxu version, and the latest Python version it gets a point.
+2. **Pyxu Principles Adherence**: Plugins abiding by key `Pyxu principles <./dev_notes.html>`_, namely:
 
    * Input shape agnosticity (i.e., support for NDArrays),
+
    * Complete backend-agnosticity (i.e., support for Numpy, Cupy and Dask arrays),
    * Precision management (i.e., allow selection between computation at both single and double precision)
 
@@ -17,18 +23,16 @@ The Pyxu Score is calculated using the following criteria:
 
 3. **Development Stage Weight**:
 
-   * **Early stages** (Planning 📑, Pre-Alpha 🌒, Alpha 🌓) contribute 0.5 points.
-   * **Advanced stages** (Beta 🌔, Production/Stable ✔️, Mature 🌟) contribute 1 point.
-   * **Inactive 🚫** plugins do not recieive a score.
+   * **Early stages** (Planning, Pre-Alpha, Alpha) contribute 0.5 points.
+   * **Advanced stages** (Beta, Production/Stable, Mature) contribute 1 point.
+   * **Inactive** plugins do not recieive a score.
+   See `the PyPI classifiers `_ for more information on the development stages.
 
-4. **Downloads ⬇️**: Plugins get points based on the number of downloads in the last month, up to a maximum of 1 point
+4. **Downloads**: Plugins get points based on the number of downloads in the last month, up to a maximum of 1 point
    for 1000 downloads.
 
 The final score is then normalized by the number of criteria used (6 in this case) and presented as a percentage.
 
-**Note**: While the Pyxu Score offers insights into a plugin's quality and popularity, it's just one of many metrics.
-Users are encouraged to explore plugins individually and consider other factors before making a decision.
-
 
 .. raw:: html
 
@@ -37,8 +41,8 @@ Users are encouraged to explore plugins individually and consider other factors
 Your insights matter! If you're a developer with ideas on how we can further refine the Pyxu Score, we'd love to hear
 from you. 💡
 
-We invite you to **open an issue** suggesting novel metrics or criteria that, in your opinion, would better represent
-the value and quality of Pyxu plugins. By contributing your thoughts, you play an integral role in refining and shaping
-the Pyxu community's standards.
+We invite you to `open an issue `_ suggesting novel metrics or criteria
+that, in your opinion, would better represent the value and quality of Pyxu plugins. By contributing your thoughts, you
+play an integral role in refining and shaping the Pyxu community's standards.
 
 Together, let's make the Pyxu Score the best reflection of plugin excellence! 🌟
diff --git a/_sources/guide/algebra.ipynb b/_sources/guide/algebra.ipynb
index f4d56d58..267c042a 100644
--- a/_sources/guide/algebra.ipynb
+++ b/_sources/guide/algebra.ipynb
@@ -27,24 +27,24 @@
     "\n",
     "Every time you perform an arithmetic operation, Pyxu automatically infers the output type based on the properties of the operators involved in the operation. This type inference is super convenient because it saves you from manual calculations! \n",
     "\n",
-    "For example, Pyxu takes care of updating as needed methods like `apply()`, `jacobian()`, `grad()`, `prox()`, and `adjoint()` according to arithmetic rules. This means you can plug these composite operators directly into proximal gradient algorithms without sweating the details of implementing gradients or proximal steps.\n",
+    "For example, Pyxu takes care of updating as needed methods like `apply()`[🔗](../api/abc.html#pyxu.abc.Map.apply), `jacobian()`[🔗](../api/abc.html#pyxu.abc.DiffMap.jacobian), `grad()`[🔗](../api/abc.html#pyxu.abc.DiffFunc.grad), `prox()`[🔗](../api/abc.html#pyxu.abc.ProxFunc.prox), and `adjoint()`[🔗](../api/abc.html#pyxu.abc.LinOp.adjoint) according to arithmetic rules. This means you can plug these composite operators directly into proximal gradient algorithms without sweating the details of implementing gradients or proximal steps.\n",
     "\n",
     "## Behind the Scenes: Arithmetic Rules\n",
     "\n",
-    "For those who love to peek under the hood, Pyxu utilizes a set of arithmetic rules located in the `pyxu.abc.arithmetic` module:\n",
+    "For those who love to peek under the hood, Pyxu utilizes a set of arithmetic rules located in the `pyxu.abc.arithmetic`[🔗](../api/abc/arithmetic.html) module:\n",
     "\n",
-    "- `Rule`: The base class for all arithmetic rules.\n",
-    "- `ScaleRule`: Handles scaling of operators by scalars.\n",
-    "- `ArgScaleRule`: Manages the dilation of the arguments of operators.\n",
-    "- `ArgShiftRule`: Takes care of shifting the arguments of operators.\n",
-    "- `AddRule`: Manages the addition of two operators.\n",
-    "- `ChainRule`: Deals with the composition of two operators.\n",
-    "- `PowerRule`: Handles exponentiation of an operator.\n",
-    "- `TransposeRule`: Takes care of transposing a linear operator.\n",
+    "- `Rule`[🔗](../api/abc.html#pyxu.abc.arithmetic.Rule): The base class for all arithmetic rules.\n",
+    "- `ScaleRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.ScaleRule): Handles scaling of operators by scalars.\n",
+    "- `ArgScaleRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.ArgScaleRule): Manages the dilation of the arguments of operators.\n",
+    "- `ArgShiftRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.ArgShiftRule): Takes care of shifting the arguments of operators.\n",
+    "- `AddRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.AddRule): Manages the addition of two operators.\n",
+    "- `ChainRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.ChainRule): Deals with the composition of two operators.\n",
+    "- `PowerRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.PowerRule): Handles exponentiation of an operator.\n",
+    "- `TransposeRule`[🔗](../api/abc.html#pyxu.abc.arithmetic.TransposeRule): Takes care of transposing a linear operator.\n",
     "\n",
     "### Working Example 🎯\n",
     "\n",
-    "Consider the composition of a `DiffFunc` with a `DiffMap`. Let `f` be a `DiffFunc` and `L` be a `DiffMap`. Then their composition `h` is another `DiffFunc`, and the gradient is given by:\n",
+    "Consider the composition of a `DiffFunc`[🔗](../api/abc.html#pyxu.abc.DiffFunc) with a `DiffMap`[🔗](../api/abc.html#pyxu.abc.DiffMap). Let `f` be a `DiffFunc` and `L` be a `DiffMap`. Then their composition `h` is another `DiffFunc`, and the gradient is given by:\n",
     "\n",
     "```python\n",
     ">> h = f * L\n",
@@ -85,7 +85,7 @@
     "\n",
     "## Building Block-Operators \n",
     "\n",
-    "You can even define block-operators using the `coo_block` function. Alternatively, higher-level functions like `block`, `block_diag`, `stack`, `vstack`, and `hstack` can also be used.\n",
+    "You can even define block-operators using the `coo_block`[🔗](../api/operator/blocks.html#pyxu.operator.coo_block) function. Alternatively, higher-level functions like `block`[🔗](../api/operator/blocks.html#pyxu.operator.block), `block_diag`[🔗](../api/operator/blocks.html#pyxu.operator.block_diag), `stack`[🔗](../api/operator/blocks.html#pyxu.operator.stack), `vstack`[🔗](../api/operator/blocks.html#pyxu.operator.vstack), and `hstack`[🔗](../api/operator/blocks.html#pyxu.operator.hstack) can also be used.\n",
     "\n",
     "For example, the following code snippet: \n",
     "\n",
diff --git a/_sources/guide/algorithms.ipynb b/_sources/guide/algorithms.ipynb
index 3f937752..b6de671f 100644
--- a/_sources/guide/algorithms.ipynb
+++ b/_sources/guide/algorithms.ipynb
@@ -11,7 +11,7 @@
     "\n",
     "## Algorithms Overview\n",
     "\n",
-    "### Conjugate Gradient (CG)\n",
+    "### Conjugate Gradient (CG) [🔗](../api/opt.solver.html#pyxu.opt.solver.CG)\n",
     "👉 **Use case:** Quadratic problems, particularly when you have a well-conditioned matrix $A$.\n",
     "\n",
     "**Mathematical Form:**\n",
@@ -19,7 +19,7 @@
     "\\min_{x\\in\\mathbb{R}^{N}} \\frac{1}{2} \\mathbf{x}^{T} \\mathbf{A} \\mathbf{x} - \\mathbf{x}^{T} \\mathbf{b}\n",
     "$$\n",
     "\n",
-    "### Accelerated Proximal Gradient Descent (APGD)\n",
+    "### Accelerated Proximal Gradient Descent (APGD)  [🔗](../api/opt.solver.html#pyxu.opt.solver.PGD)\n",
     "👉 **Use case:** Problems that separate into smooth and non-smooth components. \n",
     "\n",
     "**Mathematical Form:**\n",
@@ -31,7 +31,7 @@
     "> **Note:** With acceleration, `APGD` can be shown to be an *optimal* first-order method, with the fastest possible convergence rate!\n",
     "\n",
     "\n",
-    "### Primal-Dual Splitting (PDS) Methods\n",
+    "### Primal-Dual Splitting (PDS) Methods \n",
     "👉 **Use case:** Multi-term problems, with smooth and non-smooth terms, possibly composed with a linear operator $K$.\n",
     "\n",
     "**Mathematical Form:**\n",
@@ -40,7 +40,7 @@
     "$$\n",
     "where $\\mathcal{F}$ is differentiable, $\\mathcal{G}$ and $\\mathcal{H}$ are proximable, and $K$ is a linear operator.\n",
     "\n",
-    "Methods under this category include `CondatVu`, `PD3O`, `ADMM`, `ChambollePock`, and more.\n",
+    "Methods under this category include `CondatVu` [🔗](../api/opt.solver.html#pyxu.opt.solver.CondatVu), `PD3O` [🔗](../api/opt.solver.html#pyxu.opt.solver.PD3O), `ADMM` [🔗](../api/opt.solver.html#pyxu.opt.solver.ADMM), `ChambollePock` [🔗](../api/opt.solver.html#pyxu.opt.solver.ChambollePock), and more.\n",
     "\n",
     "Note that, although implemented for three-term objective functionals, PDS methods can easilybe generalized to objective functionals of the form:\n",
     "$${\\min_{\\mathbf{x}\\in\\mathbb{R}^N} \\;\\mathcal{F}(\\mathbf{x})\\;\\;+\\;\\;\\mathcal{G}(\\mathbf{x})\\;\\;+\\;\\;\\sum_{i=1}^J\\mathcal{H}_i(K_i\\mathbf{x})}$$\n",
@@ -53,9 +53,9 @@
     "\n",
     "## Choosing the Right Algorithm\n",
     "\n",
-    "The golden rule is to **choose the most specific algorithm** —i.e., the one that makes the most assumptions consistent with your problem. This often results in faster convergence. For example, if your objective functional has a gradient, a gradient-based method like `APGD` will generally be more efficient than a generic proximal-based method like `DouglasRachford`.\n",
+    "The golden rule is to **choose the most specific algorithm** —i.e., the one that makes the most assumptions consistent with your problem. This often results in faster convergence. For example, if your objective functional has a gradient, a gradient-based method like `APGD` will generally be more efficient than a generic proximal-based method like `DouglasRachford` [🔗](../api/opt.solver.html#pyxu.opt.solver.DouglasRachford).\n",
     "\n",
-    "The most generic algorithms in Pyxu are `PD3O` and `CondatVu`, but they are also the least efficient, so use them only when simpler methods like `ADMM`, `APGD` or `CG` cannot be used. Note that `ADAM` can also be useful when step sizes are too complex to compute. \n",
+    "The most generic algorithms in Pyxu are `PD3O` and `CondatVu`, but they are also the least efficient, so use them only when simpler methods like `ADMM`, `APGD` or `CG` cannot be used. Note that `ADAM` [🔗](../api/opt.solver.html#pyxu.opt.solver.Adam) can also be useful when step sizes are too complex to compute. \n",
     "\n",
     "## Hyperparameter Tuning\n",
     "\n",
@@ -105,7 +105,7 @@
     "\n",
     "## Advanced Usage: Guru Interface \n",
     "\n",
-    "For those who want even more control, we provide a guru interface allowing you to overload default settings, including the stopping criteria (see module `pyxu.opt.stop` for available stopping criteria).\n",
+    "For those who want even more control, we provide a guru interface allowing you to overload default settings, including the stopping criteria (see module `pyxu.opt.stop`[🔗](../api/opt.stop.html) for available stopping criteria).\n",
     "\n",
     "For example, overloading the default stopping criterion of the `CondatVu` solver initialized above can be achieved as follows:\n",
     "\n",
@@ -121,12 +121,12 @@
     "\n",
     "## Implementing New Algorithms \n",
     "\n",
-    "To implement a new iterative solver, users need to sub-class `pyxu.abc.solver.Solver` and overwrite some of its core methods, such as `m_init()`,  and `m_step()`, which describe the initalization and update step of iterative algorithms (see the API Reference for more details). \n",
+    "To implement a new iterative solver, users need to sub-class `pyxu.abc.solver.Solver`[🔗](../api/abc.html#pyxu.abc.Solver) and overwrite some of its core methods, such as `m_init()`[🔗](../api/abc.html#pyxu.abc.Solver.m_init),  and `m_step()`[🔗](../api/abc.html#pyxu.abc.Solver.m_step), which describe the initalization and update step of iterative algorithms (see the API Reference for more details). \n",
     "\n",
     "\n",
     "Sub-classes of `Solver` inherit automatically from its very versatile API for solving optimisation problems, with the following notable features:\n",
     "\n",
-    " * manual/automatic/background execution of solver iterations via parameters provided to `fit()`. \n",
+    " * manual/automatic/background execution of solver iterations via parameters provided to `fit()`[🔗](../api/abc.html#pyxu.abc.Solver.fit). \n",
     " * automatic checkpointing of solver progress, providing a safe restore point in case of faulty numerical code. Each solver instance backs its state and final output to a folder on disk for post-analysis. In particular `fit()` will never crash: detailed exception information will always be available in a logfile for post-analysis.\n",
     " * solve for multiple initial points in parallel.\n",
     "\n",
diff --git a/_sources/examples/DifferentialOperators.ipynb b/_sources/guide/diff_ops.ipynb
similarity index 99%
rename from _sources/examples/DifferentialOperators.ipynb
rename to _sources/guide/diff_ops.ipynb
index 7495e98f..874d9f53 100644
--- a/_sources/examples/DifferentialOperators.ipynb
+++ b/_sources/guide/diff_ops.ipynb
@@ -1,62 +1,32 @@
 {
  "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "177a858e",
-   "metadata": {},
-   "source": [
-    "# Differential operators in Pyxu"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "ab2b2317",
    "metadata": {},
    "source": [
-    "The `pyxu.operator.linop.diff` module defines a set of classes and functions related to derivative operators. \n",
+    "# Differential Operators in Pyxu\n",
     "\n",
-    "In the context of inverse problems, derivative operators come handy when the spatial structure of the object or image be reconstructed can be leveraged. For example, common uses of derivatives are when the image is expected to be smooth in one or more directions, or in contrast, when it is  expected to have sharp edges and flat regions. In those cases, the derivative operators are used as part of regularization terms, adding prior knowledge to our solution (see example TODO).\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "6e2d5017",
-   "metadata": {},
-   "source": [
-    "## 1. Partial derivatives"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "7e401893",
-   "metadata": {},
-   "source": [
+    "The `pyxu.operator.linop.diff`[🔗](../api/operator/linop.html#derivatives)  module defines a set of classes and functions related to derivative operators. \n",
+    "\n",
+    "In the context of inverse problems, derivative operators come handy when the spatial structure of the object or image be reconstructed can be leveraged. For example, common uses of derivatives are when the image is expected to be smooth in one or more directions, or in contrast, when it is  expected to have sharp edges and flat regions. In those cases, the derivative operators are used as part of regularization terms, adding prior knowledge to our solution.\n",
+    "\n",
+    "## Partial Derivatives\n",
     "\n",
-    "The most basic differential operator is the **partial derivative**:\n",
     "\n",
+    "The most basic differential operator is the `PartialDerivative`[🔗](../api/operator/linop.html#pyxu.operator.PartialDerivative):\n",
     "\n",
-    "\\begin{align}\n",
-    "\\frac{\\partial^{n}}{\\partial x_0^{n_0} \\cdots \\partial x_{D-1}^{n_{D-1}}} \n",
-    "\\end{align}\n",
+    "$$\\frac{\\partial^{n}}{\\partial x_0^{n_0} \\cdots \\partial x_{D-1}^{n_{D-1}}}$$\n",
     "\n",
     "Which when applied to an given signal $\\mathbf{f}$, yields:\n",
     "\n",
-    "\\begin{align}\n",
-    "\\frac{\\partial^{n}}{\\partial x_0^{n_0} \\cdots \\partial x_{D-1}^{n_{D-1}}}\\mathbf{f} =\\mathbf{D}\\mathbf{f}\\in \\mathbb{R}^{N_0 \\times \\cdots \\times N_{D-1}}\n",
-    "\\end{align}\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "e8617455",
-   "metadata": {},
-   "source": [
+    "$$\\frac{\\partial^{n}}{\\partial x_0^{n_0} \\cdots \\partial x_{D-1}^{n_{D-1}}}\\mathbf{f} =\\mathbf{D}\\mathbf{f}\\in \\mathbb{R}^{N_0 \\times \\cdots \\times N_{D-1}}$$\n",
+    "\n",
+    "\n",
     "Partial derivatives in `Pyxu` are computed via efficient **matrix-free** implementation, which is based on [JIT compiled stencils](https://numba.pydata.org/numba-doc/latest/user/stencil.html). For illustrative purposes, consider the following approximation to the partial derivatives:\n",
     "\n",
     "\n",
-    "\\begin{align}\n",
-    "\\mathbf{D} f [n] = f[n+1] - f[n]\n",
-    "\\end{align}\n",
+    "$$\\mathbf{D} f [n] = f[n+1] - f[n]$$\n",
     "\n",
     "\n",
     "As we will see below, this is the forward finite difference approximation. This could be implemented in **matrix-form**, in which case it would look like this:\n",
@@ -91,15 +61,14 @@
     "```\n",
     "\n",
     "\n",
-    "Despite Python being very slow when it comes to for loops, there are some ways to make them really efficient (see [HPC example](TODO)).\n",
+    "Despite Python being very slow when it comes to for-loops, Pyxu leverages existing tools to run them efficiently (see [HPC Features](./hpc.ipynb)).\n",
     "\n",
     ""
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "0bdfbd20",
-   "metadata": {},
-   "source": [
-    "### 1.1. Parameters"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "b795b197",
-   "metadata": {},
-   "source": [
+    "--->\n",
+    "\n",
+    "### Partial Derivative Parametrization\n",
+    "\n",
     "The `PartialDerivative` class implements two main approximations to the partial derivatives as methods:`finite_difference` and `gaussian_derivative`:\n",
     "\n",
     "```python\n",
@@ -138,8 +95,7 @@
     "        gpu: bool = False,\n",
     "        dtype: typ.Optional[pyct.DType] = None,\n",
     "        sampling: typ.Union[pyct.Real, cabc.Sequence[pyct.Real, ...]] = 1,\n",
-    "    ) -> pyct.OpT\n",
-    "    \n",
+    "    ) -> pyct.OpT:\n",
     "``` \n",
     "\n",
     "```python\n",
@@ -153,16 +109,15 @@
     "        gpu: bool = False,\n",
     "        dtype: typ.Optional[pyct.DType] = None,\n",
     "        sampling: typ.Union[pyct.Real, cabc.Sequence[pyct.Real, ...]] = 1,\n",
-    "    ) -> pyct.OpT\n",
-    "    \n",
+    "    ) -> pyct.OpT:\n",
     "```\n",
     "\n",
     "The common arguments are: \n",
     "        \n",
     "- `arg_shape`: Shape of the input image. This is information is necessary in case batch processing is intended.\n",
     "- `order`: Derivative order in each axis. For example, for a 2D image input: \n",
-    "    - `order=(1, 2)` would yield: $$\\frac{\\partial^{3} \\mathbf{f}}{\\partial x \\partial y^{2}}$$\n",
-    "    - `order=(2, 0)` would yield: $$\\frac{\\partial^{2} \\mathbf{f}}{\\partial x^{2}}$$\n",
+    "    - `order=(1, 2)` would yield: $\\frac{\\partial^{3} \\mathbf{f}}{\\partial x \\partial y^{2}}$\n",
+    "    - `order=(2, 0)` would yield: $\\frac{\\partial^{2} \\mathbf{f}}{\\partial x^{2}}$\n",
     "\n",
     "- `mode`: Padding mode to define boundary conditions. Pre-padding and post-trimming are computed to yield an output array of the same shape as the input. It can be defined in general (with a `string`) or per axis (with a `tuple`). The available modes are: \n",
     "    - 'constant'\n",
@@ -176,44 +131,21 @@
     "- `sampling`: Spacing between pixels. It can be defined in general (with a `float/int`) or per axis (with a `tuple`)\n",
     "        \n",
     "        \n",
-    "The sections below it is explained the differences between these two methods and their specific arguments."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "80b3cc9c",
-   "metadata": {},
-   "source": [
+    "The sections below it is explained the differences between these two methods and their specific arguments.\n",
+    "\n",
     "
          \n",
     "Important: Differential operators are not backend nor dtype agnostic! The arguments `gpu` and `dtype` must be chosen adequately.\n",
-    "
        \n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "fe4582cd",
-   "metadata": {},
-   "source": [
-    "### 1.2. Finite differences"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "b3dc5538",
-   "metadata": {},
-   "source": [
+    "
        \n", + "\n", + "\n", + "### Finite Differences Approximation to the Partial Derivative\n", + "\n", "Finite differences approximate the derivatives by computing the difference between pixel values in the image. There are different variations of finite differences, such as forward differences, backward differences, and central differences.\n", "\n", "* *Forward Differences*: $\\mathbf{D}_{F} f [n] = \\frac{f[n+1] - f[n]}{h}$\n", "* *Backward Differences*: $\\mathbf{D}_{B} f [n] = \\frac{f[n] - f[n-1]}{h}$\n", - "* *Central Differences*: $\\mathbf{D}_{C} f [n] = \\frac{f[n+1] - f[n-1]}{2h}$" - ] - }, - { - "cell_type": "markdown", - "id": "8198e968", - "metadata": {}, - "source": [ + "* *Central Differences*: $\\mathbf{D}_{C} f [n] = \\frac{f[n+1] - f[n-1]}{2h}$\n", + "\n", "Another important parameter for finite difference is the accuracy, which defines the number of digits used for the approximation. \n", "\n", "These are some kernels generated by different parameterizations: the (parenthesis) indicates the central element.\n", @@ -353,7 +285,7 @@ "id": "1dd0f18f", "metadata": {}, "source": [ - "### 1.3.Gaussian derivative" + "### Gaussian Derivative Approximation to the Partial Derivative" ] }, { @@ -514,7 +446,7 @@ "id": "52dcd0e8", "metadata": {}, "source": [ - "### 1.4. How to choose?" + "### How to choose between Finite Differences and Gaussian Derivative?" ] }, { @@ -523,8 +455,9 @@ "metadata": {}, "source": [ "The choice between *finite difference* and *Gaussian derivative* can be seen as a **trade-off between bias and variance**:\n", - "- When estimating partial derivatives, the Gaussian derivative robustly captures the true behavior of the derivative of the smoothed signal, thus introducing bias in the estimation. \n", - "- On the other hand, finite differences, especially when using a small accuracy value, can be highly sensitive to noise and can produce unstable estimates of the derivative (variance). Gaussian derivatives, on the other hand, tend to be smoother and less affected by noise.\n", + "\n", + "* When estimating partial derivatives, the Gaussian derivative robustly captures the true behavior of the derivative of the smoothed signal, thus introducing bias in the estimation. \n", + "* On the other hand, finite differences, especially when using a small accuracy value, can be highly sensitive to noise and can produce unstable estimates of the derivative (variance). Gaussian derivatives, on the other hand, tend to be smoother and less affected by noise.\n", "\n", "As a rule of thumb, it is recommended to try both approaches and to use the Gaussian derivative for very noisy signals." ] @@ -534,7 +467,7 @@ "id": "eb92f038", "metadata": {}, "source": [ - "## 2. Stacks of partial derivatives" + "## Stacks of Partial Derivatives" ] }, { @@ -544,28 +477,24 @@ "source": [ "There are two main classes of stacks of partial derivative:\n", "\n", - "* `Gradient`: stack of all first order derivatives (one per axis), \n", + "* `Gradient`[🔗](../api/operator/linop.html#pyxu.operator.Gradient): stack of all first order derivatives (one per axis), \n", "\n", "\n", - "\\begin{align}\n", - "\\mathbf{f} = \\begin{bmatrix}\n", + "$$\\mathbf{f} = \\begin{bmatrix}\n", " \\frac{\\partial \\mathbf{f}}{\\partial x_0} \\\\\n", " \\vdots \\\\\n", " \\frac{\\partial \\mathbf{f}}{\\partial x_{D-1}}\n", - " \\end{bmatrix} \\in \\mathbb{R}^{D \\times N_{0} \\times \\cdots \\times N_{D-1}}\n", - "\\end{align}\n", + " \\end{bmatrix} \\in \\mathbb{R}^{D \\times N_{0} \\times \\cdots \\times N_{D-1}}$$\n", "\n", "\n", - "* `Hessian`: stack of all second order derivatives,\n", + "* `Hessian`[🔗](../api/operator/linop.html#pyxu.operator.Hessian): stack of all second order derivatives,\n", "\n", - "\\begin{align}\n", - " \\mathbf{H} \\mathbf{f} = \\begin{bmatrix}\n", + "$$\\mathbf{H} \\mathbf{f} = \\begin{bmatrix}\n", " \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{0}^{2} } & \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{0}\\,\\partial x_{1} } & \\cdots & \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{0} \\, \\partial x_{D-1} } \\\\\n", " \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{1} \\, \\partial x_{0} } & \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{1}^{2} } & \\cdots & \\dfrac{ \\partial^{2}\\mathbf{f} }{\\partial x_{1} \\,\\partial x_{D-1}} \\\\\n", " \\vdots & \\vdots & \\ddots & \\vdots \\\\\n", " \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{D-1} \\, \\partial x_{0} } & \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{D-1} \\, \\partial x_{1} } & \\cdots & \\dfrac{ \\partial^{2}\\mathbf{f} }{ \\partial x_{D-1}^{2}}\n", - " \\end{bmatrix}\n", - "\\end{align}" + " \\end{bmatrix}$$" ] }, { @@ -573,7 +502,7 @@ "id": "1eca7161", "metadata": {}, "source": [ - "### 2.1. Parameters" + "### Parameters" ] }, { @@ -616,9 +545,9 @@ "\n", "There are some common arguments that we didn't see in the previous `PartialDerivative` class:\n", " \n", - "- `diff_method`: This will select between `finite_difference` ('fd') or `gaussian_derivative` ('gd') type of partial derivatives.\n", - "- `parallel`: If `True`, it will compute the different partial derivatives in parrellalel on different threads.\n", - "- `diff_kwargs`: Placeholder to specify arguments that are specific to `finite_difference` and `gaussian_derivative`.\n", + "* `diff_method`: This will select between `finite_difference` ('fd') or `gaussian_derivative` ('gd') type of partial derivatives.\n", + "* `parallel`: If `True`, it will compute the different partial derivatives in parrellalel on different threads.\n", + "* `diff_kwargs`: Placeholder to specify arguments that are specific to `finite_difference` and `gaussian_derivative`.\n", " \n", "The sections below it is explained the differences between these two methods and their specific arguments." ] @@ -638,7 +567,7 @@ "id": "816838de", "metadata": {}, "source": [ - "### 2.2. Gradient" + "### Gradient" ] }, { @@ -650,12 +579,10 @@ "\n", "For example, in the case of a 2-dimensional image, the gradient operator implements:\n", "\n", - "\\begin{align}\n", - "\\boldsymbol{\\nabla} \\mathbf{f} = \\begin{bmatrix}\n", + "$$\\boldsymbol{\\nabla} \\mathbf{f} = \\begin{bmatrix}\n", " \\frac{\\partial \\mathbf{f}}{\\partial x} \\\\\n", " \\frac{\\partial \\mathbf{f}}{\\partial y}\n", - " \\end{bmatrix} \\in \\mathbb{R}^{2 \\times N_{x} \\times N_{y}}\n", - "\\end{align}\n", + " \\end{bmatrix} \\in \\mathbb{R}^{2 \\times N_{x} \\times N_{y}}$$\n", "\n" ] }, @@ -742,7 +669,7 @@ "id": "9bdfc5cb", "metadata": {}, "source": [ - "### 2.3. Hessian" + "### Hessian" ] }, { diff --git a/_sources/guide/funcs.ipynb b/_sources/guide/funcs.ipynb index c6dc7dab..b22ac70f 100644 --- a/_sources/guide/funcs.ipynb +++ b/_sources/guide/funcs.ipynb @@ -21,13 +21,12 @@ "> \n", "> 1. **Subclassing**: Extend these classes to create customized functionals tailored to your problem. \n", "> \n", - "> 2. **Generic Constructor Routine**: Utilize the `from_source` method to define new functionals from their core methods, like `apply()`, `grad()`, or `prox()`.\n", + "> 2. **Generic Constructor Routine**: Utilize the `from_source`[🔗](../api/operator.interop.html#general) method to define new functionals from their core methods, like `apply()`[🔗](../api/abc.html#pyxu.abc.Map.apply), `grad()`[🔗](../api/abc.html#pyxu.abc.DiffFunc.grad), or `prox()`[🔗](../api/abc.html#pyxu.abc.ProxFunc.prox).\n", ">\n", "> Additionally, don't forget to explore our comprehensive Reference API. It features pre-implemented versions of many commonly used functionals, serving as both a shortcut for common tasks and a useful learning resource.\n", "\n", "### `Func`: The Foundation Stone 🧱\n", - "\n", - "The `Func` class is the base class in the functional hierarchy. Its core method is `apply()`, which computes the value of the functional at a given input.\n", + "The `Func`[🔗](../api/abc.html#pyxu.abc.Func) class is the base class in the functional hierarchy. Its core method is `apply()`, which computes the value of the functional at a given input.\n", "\n", "Here's a simplified example, implementing the squared $L_2$ norm:\n", "\n", @@ -54,7 +53,7 @@ "\n", "### `DiffFunc`: Differentiable Functionals 🎯\n", "\n", - "The `DiffFunc` class extends `Func` for functionals that have a well-defined gradient. It introduces an additional method, `grad()`, for gradient computation.\n", + "The `DiffFunc`[🔗](../api/abc.html#pyxu.abc.DiffFunc) class extends `Func` for functionals that have a well-defined gradient. It introduces an additional method, `grad()`, for gradient computation.\n", "\n", "```python\n", "from pyxu.abc import DiffFunc\n", @@ -67,11 +66,11 @@ " return 2 * x\n", "```\n", "\n", - ">🌈Tip: With Pyxu, you can use `from_torch` or `from_jax` to automatically compute the gradient if you have a PyTorch or JAX implementation of your functional.\n", + ">🌈Tip: With Pyxu, you can use `from_torch`[🔗](../api/operator.interop.html#pyxu.operator.interop.from_torch) or `from_jax`[🔗](../api/operator.interop.html#pyxu.operator.interop.from_jax) to automatically compute the gradient if you have a PyTorch or JAX implementation of your functional.\n", "\n", "### `ProxFunc`: Proximable Functionals 🛡️\n", "\n", - "For functionals with a simple proximal operator, you'll find `ProxFunc` extremely useful. It offers the `prox()` method, which evaluates the proximal operator of the functional. Here's an example using the $L_1$ norm:\n", + "For functionals with a simple proximal operator, you'll find `ProxFunc`[🔗](../api/abc.html#pyxu.abc.ProxFunc) extremely useful. It offers the `prox()` method, which evaluates the proximal operator of the functional. Here's an example using the $L_1$ norm:\n", "\n", "```python\n", "from pyxu.abc import ProxFunc\n", @@ -86,7 +85,7 @@ "\n", "#### Moreau Envelope for Smoothing\n", "\n", - "You can also smooth out a proximable functional using the `moreau_envelope()` method. For example, you can smooth the L1 norm to create the [Huber loss function](https://www.wikiwand.com/en/Huber_loss) as follows:\n", + "You can also smooth out a proximable functional using the `moreau_envelope()`[🔗](../api/abc.html#pyxu.abc.ProxFunc.moreau_envelope) method. For example, you can smooth the L1 norm to create the [Huber loss function](https://www.wikiwand.com/en/Huber_loss) as follows:\n", "\n", "```python\n", "huber = L1Norm(dim).moreau_envelope(mu=0.1)\n", @@ -110,7 +109,7 @@ "\n", "### Specialized Classes: `ProxDiffFunc`, `LinFunc`, `QuadraticFunc` 🎨\n", "\n", - "These classes are for functionals that offer even more, like being both proximable and differentiable (`ProxDiffFunc`), or being linear (`LinFunc`) or quadratic (`QuadraticFunc`). Quadratic functionals are especially important in primal-dual methods for faster convergence, so do use them when you can! \n", + "These classes are for functionals that offer even more, like being both proximable and differentiable (`ProxDiffFunc`[🔗](../api/abc.html#pyxu.abc.ProxDiffFunc)), or being linear (`LinFunc`[🔗](../api/abc.html#pyxu.abc.LinFunc)) or quadratic (`QuadraticFunc`[🔗](../api/abc.html#pyxu.abc.QuadraticFunc)). Quadratic functionals are especially important in primal-dual methods for faster convergence, so do use them when you can! \n", "\n", "> Note: when dealing with `ProxDiffFunc` instances, it can be hard to decide whether the gradient or proximal operator should be used for optimization purposes. The general rule-of-thumb is to use the gradient as much as possible, as the latter requires more regularity on the objective functional, which can be leveraged by solvers for fatser convergence. \n", "\n", diff --git a/_sources/guide/fwdops.ipynb b/_sources/guide/fwdops.ipynb index 9c31a608..03d47405 100644 --- a/_sources/guide/fwdops.ipynb +++ b/_sources/guide/fwdops.ipynb @@ -8,7 +8,7 @@ "# Forward Operators\n", "\n", "In computational imaging, the ability to accurately model the acquisition system is cornerstone to solving inverse\n", - "problems. The `LinOp()` class in Pyxu serves as a foundational abstraction for defining linear forward operators,\n", + "problems. The `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp) class in Pyxu serves as a foundational abstraction for defining linear forward operators,\n", "essentially mapping the original signal or image to the data we observe. This guide distills the knowledge needed to\n", "implement custom forward operators using the `LinOp()` class, as well as related classes in the Pyxu library.\n", "\n", @@ -16,9 +16,9 @@ "> \n", "> 1. **Subclassing**: Extend these classes to create customized operators tailored to your problem. \n", "> \n", - "> 2. **Generic Constructor Routine**: Utilize the `from_source` method to define new operators from their core methods, like `apply()`, `adjoint()`, or `jacobian()`.\n", + "> 2. **Generic Constructor Routine**: Utilize the `from_source`[🔗](../api/operator.interop.html#general) method to define new operators from their core methods, like `apply()`[🔗](../api/abc.html#pyxu.abc.Map.apply), `adjoint()`[🔗](../api/abc.html#pyxu.abc.LinOp.adjoint), or `jacobian()`[🔗](../api/abc.html#pyxu.abc.DiffMap.jacobian).\n", ">\n", - "> Additionally, don't forget to explore our comprehensive Reference API. It features pre-implemented versions of many commonly used forward operators, serving as both a shortcut for common tasks and a useful learning resource.\n", + "> Additionally, don't forget to explore our comprehensive (Reference API)[../api/index.html]. It features pre-implemented versions of many commonly used forward operators, serving as both a shortcut for common tasks and a useful learning resource.\n", "\n", "## The Importance of Matrix-Free Operators\n", "\n", @@ -47,31 +47,31 @@ " class Sum(LinOp):\n", " pass\n", " ```\n", - " Here, a new class called `Sum()` is defined, inheriting from Pyxu's `LinOp()` base class, the primary abstraction\n", + " Here, a new class called `Sum()` is defined, inheriting from Pyxu's `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp) base class, the primary abstraction\n", " for designing real-valued linear operators. This inheritance means that `Sum()` is expected to implement certain\n", " core methods, namely `apply()` and `adjoint()`. \n", "\n", "\n", - "- **The ``apply()`` Method:**\n", + "- **The** ``apply()`` **Method:**\n", " \n", " ```python\n", " def apply(self, arr):\n", " return arr.sum(keepdims=True)\n", " ```\n", - " The `apply()` method takes an array `arr` as input and returns the sum of its elements. This is the core\n", + " The `apply()`[🔗](../api/abc.html#pyxu.abc.Map.apply) method takes an array `arr` as input and returns the sum of its elements. This is the core\n", " functionality of the operator. Instead of representing the sum operation as a matrix and performing matrix-vector\n", " multiplication, the method directly computes the sum, making it \"matrix-free.\"\n", "\n", " > **Note**: `keepdims=True` is required since, as per the `LinOp.apply()` signature, it must return an NDArray, and\n", " > not a scalar.\n", "\n", - "- **The ``adjoint()`` Method:**\n", + "- **The** ``adjoint()`` **Method:**\n", " \n", " ```python\n", " def adjoint(self, arr):\n", " return arr * np.ones(self.shape[1])\n", " ```\n", - " The `adjoint()` method also takes an array `arr` as input. The adjoint operation for this sum operator is\n", + " The `adjoint()`[🔗](../api/abc.html#pyxu.abc.LinOp.adjoint) method also takes an array `arr` as input. The adjoint operation for this sum operator is\n", " effectively a *broadcast* operation, mapping a scalar to a vector with the same dimension of the original array\n", " space.\n", "\n", @@ -127,24 +127,24 @@ "\n", "## Additional Features of LinOp: Batteries Included \n", "\n", - "Pyxu's `LinOp()` is designed to be as versatile and useful as possible for computational imaging. Here are some of the\n", + "Pyxu's `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp) is designed to be as versatile and useful as possible for computational imaging. Here are some of the\n", "extra capabilities baked right into the class to facilitate both simple and complex tasks:\n", "\n", "- **Lipschitz Constant**: Knowing the Lipschitz constant of an operator is invaluable for optimization routines. If you\n", - " know it, you can directly store it in the `lipschitz` property. Don't know it? No problem! The `estimate_lipschitz()`\n", + " know it, you can directly store it in the `lipschitz`[🔗](../api/abc.html#pyxu.abc.Map.lipschitz) property. Don't know it? No problem! The `estimate_lipschitz()`[🔗](../api/abc.html#pyxu.abc.Map.estimate_lipschitz)\n", " method will compute it for you, offering various methods to balance accuracy and execution time.\n", "\n", "```python\n", "my_operator.lipschitz = my_operator.estimate_lipschitz()\n", "```\n", "\n", - "- **Singular Value Decomposition**: Ever needed to compute the singular values of your operator? Use the `svdvals()`\n", + "- **Singular Value Decomposition**: Ever needed to compute the singular values of your operator? Use the `svdvals()`[🔗](../api/abc.html#pyxu.abc.LinOp.svdvals)\n", " method which employs the Arnoldi algorithm to get the job done without breaking the matrix-free paradigm.\n", "\n", - "- **Trace of Operator**: Sometimes you may need to compute the trace of an operator. The `trace()` method uses a\n", + "- **Trace of Operator**: Sometimes you may need to compute the trace of an operator. The `trace()`[🔗](../api/abc.html#pyxu.abc.SquareOp.trace) method uses a\n", " stochastic approximation with the Hutch++ algorithm to efficiently it.\n", "\n", - "- **Pseudo-Inverse**: If you're looking to solve an inverse problem, the `pinv()` method helps you evaluate the\n", + "- **Pseudo-Inverse**: If you're looking to solve an inverse problem, the `pinv()`[🔗](../api/abc.html#pyxu.abc.LinOp.pinv) method helps you evaluate the\n", " pseudo-inverse by solving the (dampened) normal equations, making it the most straightforward way to reverse your\n", " operations.\n", "\n", @@ -152,30 +152,30 @@ "pseudo_inv_result = my_operator.pinv(my_array, damp=value)\n", "```\n", "\n", - "- **Support for Explicit Matrices**: Though `LinOp()` is primarily built for matrix-free operations, you are not\n", - " restricted to them. If you prefer, you can work with explicit matrices using the `from_array()` method, supporting a\n", + "- **Support for Explicit Matrices**: Though `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp) is primarily built for matrix-free operations, you are not\n", + " restricted to them. If you prefer, you can work with explicit matrices using the `from_array()`[🔗](../api/abc.html#pyxu.abc.LinOp.from_array) method, supporting a\n", " variety of array formats including `numpy`, `cupy`, `sparse`, and `dask`.\n", "\n", "```python\n", "op = LinOp.from_array(np.ones((N, N)))\n", "```\n", "\n", - "With all these tools and methods at your disposal, `LinOp()` aims to be your go-to solution for implementing linear\n", + "With all these tools and methods at your disposal, `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp) aims to be your go-to solution for implementing linear\n", "operators in computational imaging tasks.\n", "\n", "## DiffMap for Non-linear Forward Operators \n", "\n", "Linear models are often an idealized representation. In some situations forward operators are inherently non-linear.\n", "Take phase retrieval or some forms of tomography as examples: these are scenarios where the relationship between the\n", - "object and its measurements isn't just a linear transformation. For such cases, Pyxu provides the `DiffMap()` class to\n", + "object and its measurements isn't just a linear transformation. For such cases, Pyxu provides the `DiffMap()`[🔗](../api/abc.html#pyxu.abc.DiffMap) class to\n", "implement these non-linear forward operators.\n", "\n", "### Core Methods\n", "\n", - "- **`apply()`**: This method is where you'll implement your forward model. Just like in `LinOp()`, you override this\n", + "- `apply()`[🔗](../api/abc.html#pyxu.abc.Map.apply): This method is where you'll implement your forward model. Just like in `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp), you override this\n", " function to define how your specific forward model operates on an input array.\n", "\n", - "- **`jacobian`**: In calculus, the Jacobian matrix represents the best linear approximation to a function at a given\n", + "- `jacobian()`[🔗](../api/abc.html#pyxu.abc.DiffMap.jacobian): In calculus, the Jacobian matrix represents the best linear approximation to a function at a given\n", " point. For a function $\\mathbf{f}: \\mathbb{R}^{M} \\to \\mathbb{R}^{N}$, the Jacobian\n", " $\\mathbf{J}_{\\mathbf{f}}(\\mathbf{x})$ at a point $\\mathbf{x}$ is an $N \\times M$ matrix where the entry $(i, j)$ is\n", " $\\frac{\\partial f_{i}}{\\partial x_{j}}$. When the forward operator is non-linear, knowing the Jacobian is crucial for\n", @@ -190,17 +190,17 @@ "Libraries like JAX or PyTorch offer automatic differentiation techniques (autograd) to compute derivatives, which you\n", "can use to obtain the Jacobian efficiently in matrix-free fashion.\n", "\n", - "In Pyxu, methods `from_torch()` and `from_jax()` allow you to define operators whose Jacobians are computed via\n", + "In Pyxu, methods `from_torch`[🔗](../api/operator.interop.html#pyxu.operator.interop.from_torch) and `from_jax`[🔗](../api/operator.interop.html#pyxu.operator.interop.from_jax) allow you to define operators whose Jacobians are computed via\n", "autograd. This means you can utilize the power of these deep learning libraries to implement non-linear operators\n", "seamlessly.\n", "\n", - "With `DiffMap()`, you're well-equipped to tackle the challenges posed by non-linear forward operators in computational\n", + "With `DiffMap()`[🔗](../api/abc.html#pyxu.abc.DiffMap), you're well-equipped to tackle the challenges posed by non-linear forward operators in computational\n", "imaging.\n", "\n", "## Wrapping Up\n", "\n", "Pyxu offers a robust and scalable framework for computational imaging professionals to deal with both linear and\n", - "non-linear forward operators. With the abstraction provided by classes like `LinOp()` and `DiffMap()`, you can focus on\n", + "non-linear forward operators. With the abstraction provided by classes like `LinOp()`[🔗](../api/abc.html#pyxu.abc.LinOp) and `DiffMap()`[🔗](../api/abc.html#pyxu.abc.DiffMap), you can focus on\n", "the problem you're solving rather than computational limitations. These classes are meant to be subclassed to tailor to\n", "your specific problem domain. Happy coding! 🚀\n" ] diff --git a/_sources/guide/hpc.ipynb b/_sources/guide/hpc.ipynb index 5438dabd..89add656 100644 --- a/_sources/guide/hpc.ipynb +++ b/_sources/guide/hpc.ipynb @@ -185,7 +185,7 @@ ], "source": [ "import time as t\n", - "from pyxu.util.deps import supported_array_modules\n", + "from pyxu.info.deps import supported_array_modules\n", "from pyxu.util import compute\n", "\n", "timings = dict()\n", @@ -208,7 +208,7 @@ } }, "source": [ - "If called from within the context manager ``Precision``, the decorated apply method will automatically coerce the input/output to the user-specified precision:" + "If called from within the context manager ``Precision``[🔗](../api/runtime.html#pyxu.runtime.Precision), the decorated apply method will automatically coerce the input/output to the user-specified precision:" ] }, { diff --git a/_sources/guide/index.rst b/_sources/guide/index.rst index 9dba494b..cbc0a4ec 100644 --- a/_sources/guide/index.rst +++ b/_sources/guide/index.rst @@ -16,3 +16,4 @@ essential aspects of the library, helping you harness its full power for your re algorithms.ipynb lipschitz.ipynb hpc.ipynb + diff_ops.ipynb diff --git a/_sources/guide/lipschitz.ipynb b/_sources/guide/lipschitz.ipynb index f74f0803..0296bebe 100644 --- a/_sources/guide/lipschitz.ipynb +++ b/_sources/guide/lipschitz.ipynb @@ -23,7 +23,7 @@ "\n", "## Accessing Lipschitz Constants\n", "\n", - "Pyxu operators come equipped with attributes `lipschitz` and `diff_lipschitz` for storing the Lipschitz constants of a map and its derivative (if defined), respectively. These constants are leveraged under the hood by Pyxu to auto-tune the step sizes in various optimization algorithms.\n", + "Pyxu operators come equipped with attributes `lipschitz`[🔗](../api/abc.html#pyxu.abc.Map.lipschitz) and `diff_lipschitz`[🔗](../api/abc.html#pyxu.abc.DiffMap.diff_lipschitz) for storing the Lipschitz constants of a map and its derivative (if defined), respectively. These constants are leveraged under the hood by Pyxu to auto-tune the step sizes in various optimization algorithms.\n", "\n", "```python\n", "# Access Lipschitz constant of an operator 'op'\n", @@ -32,7 +32,7 @@ "\n", "## Estimating Lipschitz Constants\n", "\n", - "For user-defined or complicated operators where Lipschitz constants are unknown, you can estimate them using Pyxu's `estimate_lipschitz()` method.\n", + "For user-defined or complicated operators where Lipschitz constants are unknown, you can estimate them using Pyxu's `estimate_lipschitz()`[🔗](../api/abc.html#pyxu.abc.Map.estimate_lipschitz) method.\n", "\n", "```python\n", "# Estimate Lipschitz constant and update the attribute\n", @@ -43,7 +43,7 @@ "\n", "Pyxu offers two methods to estimate Lipschitz constants:\n", "\n", - "1. **Trace Method (`trace`)**: This is the default and computationally lighter option. It computes a rough estimate using the Frobenius norm of the operator, making use of the [Hutch++ stochastic algorithm](https://arxiv.org/abs/2010.09649):\n", + "1. **Trace Method (**`trace`**)**: This is the default and computationally lighter option. It computes a rough estimate using the Frobenius norm of the operator, making use of the [Hutch++ stochastic algorithm](https://arxiv.org/abs/2010.09649):\n", "\n", " ```python\n", " # Using trace method\n", @@ -52,7 +52,7 @@ " ```\n", "\n", "\n", - "2. **SVD Method (`svd`)**: This method computes the spectral norm of the operator and generally provides a tighter Lipschitz constant. However, it can be computationally intensive for large operators. A reduced-accuracy mode is available for quicker but slightly overestimated constants:\n", + "2. **SVD Method (**`svd`**)**: This method computes the spectral norm of the operator and generally provides a tighter Lipschitz constant. However, it can be computationally intensive for large operators. A reduced-accuracy mode is available for quicker but slightly overestimated constants:\n", "\n", " ```python\n", " # Using SVD method with reduced accuracy\n", @@ -208,7 +208,7 @@ "... \n", "```\n", "\n", - "More details on this feature can be found in the API reference under `pyxu.abc.arithmetic`.\n", + "More details on this feature can be found in the [API reference](../api/index.html) under `pyxu.abc.arithmetic`[🔗](../api/abc/arithmetic.html#).\n", "\n", "> **Note 📝**: While the propagated constants are usually good enough for step size tuning, they may not always be the tightest estimates.\n", "\n", diff --git a/_sources/references.rst b/_sources/references.rst index 6aa449f4..3f671cbf 100644 --- a/_sources/references.rst +++ b/_sources/references.rst @@ -2,10 +2,10 @@ ============== .. [ProxAdam] Melchior, Joseph, Moolekamp. "Proximal Adam: Robust Adaptive Update Scheme for Constrained Optimization" (2020). -.. .. [ProxAlg] Parikh, Neal, and Stephen Boyd. "Proximal algorithms." Foundations and Trends in optimization 1.3 (2014): 127-239. +.. [ProxAlg] Parikh, Neal, and Stephen Boyd. "Proximal algorithms." Foundations and Trends in optimization 1.3 (2014): 127-239. .. [FirstOrd] Beck, Amir. First-order methods in optimization. Society for Industrial and Applied Mathematics, 2017. .. [OnKerLearn] Martins, André FT, et al. "Online multiple kernel learning for structured prediction." arXiv preprint arXiv:1010.2770 (2010). -.. .. [ProxSplit] Combettes, Patrick L., and Jean-Christophe Pesquet. "Proximal splitting methods in signal processing." Fixed-point algorithms for inverse problems in science and engineering. Springer, New York, NY, 2011. 185-212. +.. [ProxSplit] Combettes, Patrick L., and Jean-Christophe Pesquet. "Proximal splitting methods in signal processing." Fixed-point algorithms for inverse problems in science and engineering. Springer, New York, NY, 2011. 185-212. .. [FuncSphere] Simeoni, Matthieu Martin Jean-Andre. Functional Inverse Problems on Spheres: Theory, Algorithms and Applications. No. THESIS. EPFL, 2020. .. [CVS] Condat, Laurent. "A primal–dual splitting method for convex optimization involving Lipschitzian, proximable and linear composite terms." Journal of Optimization Theory and Applications 158.2 (2013): 460-479. .. [PD3O] Yan, Ming. "A new primal-dual algorithm for minimizing the sum of three functions with a linear operator." arXiv preprint arXiv:1611.09805 (2018). @@ -16,9 +16,9 @@ .. [APGD] Liang, Jingwei, Tao Luo, and Carola-Bibiane Schönlieb. "Improving" Fast Iterative Shrinkage-Thresholding Algorithm": Faster, Smarter and Greedier." arXiv preprint arXiv:1811.01430 (2018). .. [NLCP] Valkonen, Tuomo, "A primal-dual hybrid gradient method for nonlinear operators with applications to MRI." Inverse Problems 30 (2014), 055012, doi:10.1088/0266-5611/30/5/055012. .. [PP] Rockafellar, R. Tyrrell. "Monotone operators and the proximal point algorithm." SIAM journal on control and optimization 14.5 (1976): 877-898. -.. .. [P2] Jain, Raj, and Imrich Chlamtac. "The P2 algorithm for dynamic calculation of quantiles and histograms without storing observations." Communications of the ACM 28.10 (1985): 1076-1085. -.. .. [GaussProcesses] Rasmussen, Carl Edward, and C. K. Williams. "Gaussian processes for machine learning, vol. 1." (2006). -.. .. [SubGauss] Aziznejad, Shayan, and Michael Unser. "An L1 representer theorem for multiple-kernel regression." arXiv preprint arXiv:1811.00836 (2018). +.. [P2] Jain, Raj, and Imrich Chlamtac. "The P2 algorithm for dynamic calculation of quantiles and histograms without storing observations." Communications of the ACM 28.10 (1985): 1076-1085. +.. [GaussProcesses] Rasmussen, Carl Edward, and C. K. Williams. "Gaussian processes for machine learning, vol. 1." (2006). +.. [SubGauss] Aziznejad, Shayan, and Michael Unser. "An L1 representer theorem for multiple-kernel regression." arXiv preprint arXiv:1811.00836 (2018). .. [FINUFFT] Barnett, Alexander H., Jeremy Magland, and Ludvig af Klinteberg. "A parallel nonuniform fast Fourier transform library based on an “Exponential of semicircle" kernel." SIAM Journal on Scientific Computing 41.5 (2019): C479-C504. .. [cuFINUFFT] Shih, Yu-hsuan, et al. "cuFINUFFT: a load-balanced GPU library for general-purpose nonuniform FFTs." 2021 IEEE International Parallel and Distributed Processing Symposium Workshops (IPDPSW). IEEE, 2021. .. [NumOpt_NocWri] Wright S, Nocedal J. "Numerical optimization". Springer Science. 1999 Apr 3;35(67-68):7. @@ -26,4 +26,4 @@ .. [WelfordAlg] Welford, B. P. "Note on a method for calculating corrected sums of squares and products." Technometrics 4.3 (1962): 419-420. .. [ULA] Alain Durmus, and Éric Moulines. "Nonasymptotic convergence analysis for the unadjusted Langevin algorithm." The Annals of Applied Probability 27(3) 1551-1587, 2017. .. [MYULA] Alain Durmus, Éric Moulines, and Marcelo Pereyra, "Efficient Bayesian Computation by Proximal Markov Chain Monte Carlo: When Langevin Meets Moreau", SIAM Journal of Imaging Science, 2018 -.. .. [UQ_MCMC] Cai, Xiaohao, Marcelo Pereyra, and Jason D. McEwen. "Uncertainty quantification for radio interferometric imaging–I. Proximal MCMC methods." Monthly Notices of the Royal Astronomical Society 480.3 (2018): 4154-4169. +.. [UQ_MCMC] Cai, Xiaohao, Marcelo Pereyra, and Jason D. McEwen. "Uncertainty quantification for radio interferometric imaging–I. Proximal MCMC methods." Monthly Notices of the Royal Astronomical Society 480.3 (2018): 4154-4169. diff --git a/_static/.DS_Store b/_static/.DS_Store deleted file mode 100644 index de9348f5..00000000 Binary files a/_static/.DS_Store and /dev/null differ diff --git a/_static/css/custom.css b/_static/css/custom.css index 131512f3..651d6d3e 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -60,6 +60,11 @@ background: linear-gradient(to right, var(--pst-color-primary), rgb(245, 188, 71 -webkit-text-fill-color: transparent; } +h2 code { + -webkit-background-clip: initial; + -webkit-text-fill-color: initial; + color: var(--pst-color-primary); +} .navbar-icon-links img.icon-link-image { border-radius: 0rem; diff --git a/_static/documentation_options.js b/_static/documentation_options.js index 612f5a96..ac6da9ee 100644 --- a/_static/documentation_options.js +++ b/_static/documentation_options.js @@ -1,5 +1,5 @@ const DOCUMENTATION_OPTIONS = { - VERSION: '1.0.1.dev1', + VERSION: '1.0.1.dev58', LANGUAGE: 'en', COLLAPSE_INDEX: false, BUILDER: 'html', diff --git a/_static/pygments.css b/_static/pygments.css index f188c252..4f5fd852 100644 --- a/_static/pygments.css +++ b/_static/pygments.css @@ -22,7 +22,6 @@ html[data-theme="light"] .highlight .c1 { color: #8f5902; font-style: italic } / html[data-theme="light"] .highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ html[data-theme="light"] .highlight .gd { color: #a40000 } /* Generic.Deleted */ html[data-theme="light"] .highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ -html[data-theme="light"] .highlight .ges { color: #000000; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ html[data-theme="light"] .highlight .gr { color: #ef2929 } /* Generic.Error */ html[data-theme="light"] .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ html[data-theme="light"] .highlight .gi { color: #00A000 } /* Generic.Inserted */ diff --git a/api/abc.html b/api/abc.html index ef9062d0..470de0ba 100644 --- a/api/abc.html +++ b/api/abc.html @@ -18,7 +18,7 @@ - + @@ -28,11 +28,11 @@ - + - + @@ -139,7 +139,7 @@
      • - +
      • @@ -212,7 +212,7 @@
      • - +
      • @@ -229,7 +229,13 @@
      • pyxu.info.deps
      • pyxu.info.ptype
      • pyxu.info.warning
        • -
      • pyxu.operator
        • +
      • pyxu.operator +
      • pyxu.operator.interop
      • pyxu.opt.solver
      • pyxu.opt.stop
        • @@ -272,493 +278,149 @@

        pyxu.abc#

        -
        -
        -class Solver(*, folder=None, exist_ok=False, stop_rate=1, writeback_rate=None, verbosity=None, show_progress=True, log_var=frozenset({}))[source]#
        -

        Bases: object

        -

        Iterative solver for minimization problems of the form \(\hat{x} = \arg\min_{x \in \mathbb{R}^{N}} -\mathcal{F}(x)\), where the form of \(\mathcal{F}\) is solver-dependent.

        -

        Solver provides a versatile API for solving optimisation problems, with the following features:

        -
          -

        • manual/automatic/background execution of solver iterations via parameters provided to -fit(). (See below.)

          • -

        • automatic checkpointing of solver progress, providing a safe restore point in case of faulty numerical code. Each -solver instance backs its state and final output to a folder on disk for post-analysis. In particular -fit() will never crash: detailed exception information will always be available in a -logfile for post-analysis.

          • -

        • arbitrary specification of complex stopping criteria via the StoppingCriterion class.

          • -

        • solve for multiple initial points in parallel.

          • -
        -

        To implement a new iterative solver, users need to sub-class Solver and overwrite the methods -below:

        + +
        +

        pyxu.abc.arithmetic#

        +
        +
        +class Rule[source]#
        +

        Bases: object

        +

        General arithmetic rule.

        +

        This class defines default arithmetic rules applicable unless re-defined by sub-classes.

        +
        +
        +op()[source]#
        +
        +
        Returns:
        +

        op – Synthesize operator.

        +
        +
        Return type:
        +

        OpT

        -
        -
        -_mstate: dict[str, Any]#
        -

        Mathematical state.

        -
        -
        -_astate: dict[str, Any]#
        -

        Book-keeping (non-math) state.

        -
        -
        -__init__(*, folder=None, exist_ok=False, stop_rate=1, writeback_rate=None, verbosity=None, show_progress=True, log_var=frozenset({}))[source]#
        -
        +
        +
        +class ScaleRule(op, cst)[source]#
        +

        Bases: Rule

        +

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

        +

        Special Cases:

        +
        \alpha = 0  => NullOp/NullFunc
+\alpha = 1  => self
+
        +
        +

        Else:

        +
        |--------------------------|-------------|--------------------------------------------------------------------|
+|         Property         |  Preserved? |                     Arithmetic Update Rule(s)                      |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| CAN_EVAL                 | yes         | op_new.apply(arr) = op_old.apply(arr) * \alpha                     |
+|                          |             | op_new.lipschitz = op_old.lipschitz * abs(\alpha)                  |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| FUNCTIONAL               | yes         | op_new.asloss(\beta) = op_old.asloss(\beta) * \alpha               |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| PROXIMABLE               | \alpha > 0  | op_new.prox(arr, tau) = op_old.prox(arr, tau * \alpha)             |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| DIFFERENTIABLE           | yes         | op_new.jacobian(arr) = op_old.jacobian(arr) * \alpha               |
+|                          |             | op_new.diff_lipschitz = op_old.diff_lipschitz * abs(\alpha)        |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| DIFFERENTIABLE_FUNCTION  | yes         | op_new.grad(arr) = op_old.grad(arr) * \alpha                       |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| QUADRATIC                | \alpha > 0  | Q, c, t = op_old._quad_spec()                                      |
+|                          |             | op_new._quad_spec() = (\alpha * Q, \alpha * c, \alpha * t)         |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR                   | yes         | op_new.adjoint(arr) = op_old.adjoint(arr) * \alpha                 |
+|                          |             | op_new.asarray() = op_old.asarray() * \alpha                       |
+|                          |             | op_new.svdvals() = op_old.svdvals() * abs(\alpha)                  |
+|                          |             | op_new.pinv(x, damp) = op_old.pinv(x, damp / (\alpha**2)) / \alpha |
+|                          |             | op_new.gram() = op_old.gram() * (\alpha**2)                        |
+|                          |             | op_new.cogram() = op_old.cogram() * (\alpha**2)                    |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR_SQUARE            | yes         | op_new.trace() = op_old.trace() * \alpha                           |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR_NORMAL            | yes         |                                                                    |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR_UNITARY           | \alpha = -1 |                                                                    |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR_SELF_ADJOINT      | yes         |                                                                    |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR_POSITIVE_DEFINITE | \alpha > 0  |                                                                    |
+|--------------------------|-------------|--------------------------------------------------------------------|
+| LINEAR_IDEMPOTENT        | no          |                                                                    |
+|--------------------------|-------------|--------------------------------------------------------------------|
+
        +
        +
        Parameters:
          -

        • folder (Path) – Directory on disk where instance data should be stored. A location will be automatically chosen if -unspecified. (Default: OS-dependent tempdir.)

          • -

        • exist_ok (bool) – If folder is specified and exist_ok is false (default), FileExistsError is raised if the -target directory already exists.

          • -

        • stop_rate (Integer) – Rate at which solver evaluates stopping criteria.

          • -

        • writeback_rate (Integer) – Rate at which solver checkpoints are written to disk. No checkpointing is done if unspecified: only the -final solver output will be written back to disk. Must be a multiple of stop_rate if specified.

          • -

        • verbosity (Integer) – Rate at which stopping criteria statistics are logged. Must be a multiple of stop_rate. Defaults to -stop_rate if unspecified.

          • -

        • show_progress (bool) – If True (default) and fit() is run with mode=BLOCK, then statistics are also -logged to stdout.

          • -

        • log_var (VarName) – Variables from the solver’s math-state (_mstate) to be logged per iteration. -These are the variables made available when calling stats().

          • +

        • op (OpT) –

          • +

        • cst (Real) –

        -

        Notes

        -
          -

        • Partial device<>CPU synchronization takes place when stopping-criteria are evaluated. Increasing stop_rate -is advised to reduce the effect of such transfers when applicable.

          • -

        • Full device<>CPU synchronization takes place at checkpoint-time. Increasing writeback_rate is advised to -reduce the effect of such transfers when applicable.

          • -
        -
        -
        -fit(**kwargs)[source]#
        -

        Solve minimization problem(s) defined in __init__(), with the provided run-specifc -parameters.

        +
        +
        +class ArgScaleRule(op, cst)[source]#
        +

        Bases: Rule

        +

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

        +

        Special Cases:

        +
        \alpha = 0  => ConstantValued (w/ potential vector-valued output)
+\alpha = 1  => self
+
        +
        +

        Else:

        +
        |--------------------------|-------------|-----------------------------------------------------------------------------|
+|         Property         |  Preserved? |                          Arithmetic Update Rule(s)                          |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| CAN_EVAL                 | yes         | op_new.apply(arr) = op_old.apply(arr * \alpha)                              |
+|                          |             | op_new.lipschitz = op_old.lipschitz * abs(\alpha)                           |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| FUNCTIONAL               | yes         | op_new.asloss(\beta) = AMBIGUOUS -> DISABLED                                |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| PROXIMABLE               | yes         | op_new.prox(arr, tau) = op_old.prox(\alpha * arr, \alpha**2 * tau) / \alpha |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| DIFFERENTIABLE           | yes         | op_new.diff_lipschitz = op_old.diff_lipschitz * (\alpha**2)                 |
+|                          |             | op_new.jacobian(arr) = op_old.jacobian(arr * \alpha) * \alpha               |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| DIFFERENTIABLE_FUNCTION  | yes         | op_new.grad(arr) = op_old.grad(\alpha * arr) * \alpha                       |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| QUADRATIC                | yes         | Q, c, t = op_old._quad_spec()                                               |
+|                          |             | op_new._quad_spec() = (\alpha**2 * Q, \alpha * c, t)                        |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR                   | yes         | op_new.adjoint(arr) = op_old.adjoint(arr) * \alpha                          |
+|                          |             | op_new.asarray() = op_old.asarray() * \alpha                                |
+|                          |             | op_new.svdvals() = op_old.svdvals() * abs(\alpha)                           |
+|                          |             | op_new.pinv(x, damp) = op_old.pinv(x, damp / (\alpha**2)) / \alpha          |
+|                          |             | op_new.gram() = op_old.gram() * (\alpha**2)                                 |
+|                          |             | op_new.cogram() = op_old.cogram() * (\alpha**2)                             |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR_SQUARE            | yes         | op_new.trace() = op_old.trace() * \alpha                                    |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR_NORMAL            | yes         |                                                                             |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR_UNITARY           | \alpha = -1 |                                                                             |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR_SELF_ADJOINT      | yes         |                                                                             |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR_POSITIVE_DEFINITE | \alpha > 0  |                                                                             |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+| LINEAR_IDEMPOTENT        | no          |                                                                             |
+|--------------------------|-------------|-----------------------------------------------------------------------------|
+
        +
        Parameters:
          -

        • kwargs – See class-level docstring for class-specific keyword parameters.

          • -

        • stop_crit (StoppingCriterion) – Stopping criterion to end solver iterations. If unspecified, defaults to -default_stop_crit().

          • -

        • mode (SolverMode) –

          Execution mode. -See Solver for usage examples.

          -

          Useful method pairs depending on the execution mode:

          - -

          • -

        • track_objective (bool) – Auto-compute objective function every time stopping criterion is evaluated.

          • -
        -
        -
        -
        -
        -
        -m_init(**kwargs)[source]#
        -

        Set solver’s initial mathematical state based on kwargs provided to fit().

        -

        This method must only manipulate _mstate.

        -

        After calling this method, the solver must be able to complete its 1st iteration via a call to -m_step().

        -
        -
        -
        -m_step()[source]#
        -

        Perform one (mathematical) step.

        -

        This method must only manipulate _mstate.

        -
        -
        -
        -steps(n=None)[source]#
        -

        Generator of logged variables after each iteration.

        -

        The i-th call to next() on this object returns the logged variables after the i-th solver iteration.

        -

        This method is only usable after calling fit() with mode=MANUAL. See -Solver for usage examples.

        -

        There is no guarantee that a checkpoint on disk exists when the generator is exhausted. (Reason: potential -exceptions raised during solver’s progress.) Users should invoke writeback() -afterwards if needed.

        -
        -
        Parameters:
        -

        n (Integer) –

        Maximum number of next() calls allowed before exhausting the generator. Defaults to infinity if -unspecified.

        -

        The generator will terminate prematurely if the solver naturally stops before n calls to next() -are made.

        -

        -
        -
        Return type:
        -

        Generator

        -
        -
        -
        -
        -
        -stats()[source]#
        -

        Query solver state.

        -
        -
        Returns:
        -

          -

        • data (Mapping) – Value(s) of log_var (s) after last iteration.

          • -

        • history (numpy.ndarray, None) – (N_iter,) records of stopping-criteria values per iteration.

          • -
        -

        -
        -
        Return type:
        -

        tuple[dict[str, Real | NDArray | None], ndarray | None]

        -
        -
        -

        Notes

        -

        If any of the log_var (s) and/or history are not (yet) known at query time, None is returned.

        -
        -
        -
        -property workdir: str | Path#
        -
        -
        Returns:
        -

        wd – Absolute path to the directory on disk where instance data is stored.

        -
        -
        Return type:
        -

        Path

        -
        -
        -
        -
        -
        -property logfile: str | Path#
        -
        -
        Returns:
        -

        lf – Absolute path to the log file on disk where stopping criteria statistics are logged.

        -
        -
        Return type:
        -

        Path

        -
        -
        -
        -
        -
        -property datafile: str | Path#
        -
        -
        Returns:
        -

        df – Absolute path to the file on disk where log_var (s) are stored during checkpointing or after solver has -stopped.

        -
        -
        Return type:
        -

        Path

        -
        -
        -
        -
        -
        -busy()[source]#
        -

        Test if an async-running solver has stopped.

        -

        This method is only usable after calling fit() with mode=ASYNC. See -Solver for usage examples.

        -
        -
        Returns:
        -

        b – True if solver has stopped, False otherwise.

        -
        -
        Return type:
        -

        bool

        -
        -
        -
        -
        -
        -solution()[source]#
        -

        Output the “solution” of the optimization problem.

        -

        This is a helper method intended for novice users. The return type is sub-class dependent, so don’t write an -API using this: use stats() instead.

        -
        -
        -
        -stop()[source]#
        -

        Stop an async-running solver.

        -

        This method is only usable after calling fit() with mode=ASYNC. See -Solver for usage examples.

        -

        This method will block until the solver has stopped.

        -

        There is no guarantee that a checkpoint on disk exists once halted. (Reason: potential exceptions raised during -solver’s progress.) Users should invoke writeback() afterwards if needed.

        -

        Users must call this method to terminate an async-solver, even if busy() is False.

        -
        -
        -
        -writeback()[source]#
        -

        Checkpoint state to disk.

        -
        -
        -
        -default_stop_crit()[source]#
        -

        Default stopping criterion for solver if unspecified in fit() calls.

        -

        Sub-classes are expected to overwrite this method. If not overridden, then omitting the stop_crit parameter -in fit() is forbidden.

        -
        -
        Return type:
        -

        StoppingCriterion

        -
        -
        -
        -
        -
        -objective_func()[source]#
        -

        Evaluate objective function given current math state.

        -

        The output array must have shape:

        -
          -

        • (1,) if evaluated at 1 point,

          • -

        • (N, 1) if evaluated at N different points.

          • -
        -

        Sub-classes are expected to overwrite this method. If not overridden, then enabling track_objective in -fit() is forbidden.

        -
        -
        Return type:
        -

        NDArray

        -
        -
        -
        -
        -
        -
        -class SolverMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#
        -

        Bases: Enum

        -

        Solver execution mode.

        -
        -
        -BLOCK = 1#
        -
        -
        -
        -MANUAL = 2#
        -
        -
        -
        -ASYNC = 3#
        -
        -
        -
        -
        -class StoppingCriterion[source]#
        -

        Bases: object

        -

        State machines (SM) which decide when to stop iterative solvers by examining their mathematical state.

        -

        SM decisions are always accompanied by at least one numerical statistic. These stats may be queried by solvers via -info() to provide diagnostic information to users.

        -

        Composite stopping criteria can be implemented via the overloaded (and[&], or[|]) operators.

        -
        -
        -stop(state)[source]#
        -

        Compute a stop signal based on the current mathematical state.

        -
        -
        Parameters:
        -

        state (Mapping) –

        Full mathematical state of solver at some iteration, i.e. _mstate.

        -

        Values from state may be cached inside the instance to form complex stopping conditions.

        -

        -
        -
        Returns:
        -

        s – True if no further iterations should be performed, False otherwise.

        -
        -
        Return type:
        -

        bool

        -
        -
        -
        -
        -
        -info()[source]#
        -

        Get statistics associated with the last call to stop().

        -
        -
        Returns:
        -

        data

        -
        -
        Return type:
        -

        Mapping

        -
        -
        -
        -
        -
        -clear()[source]#
        -

        Clear SM state (if any).

        -

        This method is useful when a StoppingCriterion instance must be reused in another call to -fit().

        -
        -
        -
        -
        -class Rule[source]#
        -

        Bases: object

        -

        General arithmetic rule.

        -

        This class defines default arithmetic rules applicable unless re-defined by sub-classes.

        -
        -
        -op()[source]#
        -
        -
        Returns:
        -

        op – Synthesize operator.

        -
        -
        Return type:
        -

        OpT

        -
        -
        -
        -
        -
        -
        -class ScaleRule(op, cst)[source]#
        -

        Bases: Rule

        -

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

        -

        Special Cases:

        -
        \alpha = 0  => NullOp/NullFunc
-\alpha = 1  => self
-
        -
        -

        Else:

        -
        |--------------------------|-------------|--------------------------------------------------------------------|
-|         Property         |  Preserved? |                     Arithmetic Update Rule(s)                      |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| CAN_EVAL                 | yes         | op_new.apply(arr) = op_old.apply(arr) * \alpha                     |
-|                          |             | op_new.lipschitz = op_old.lipschitz * abs(\alpha)                  |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| FUNCTIONAL               | yes         | op_new.asloss(\beta) = op_old.asloss(\beta) * \alpha               |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| PROXIMABLE               | \alpha > 0  | op_new.prox(arr, tau) = op_old.prox(arr, tau * \alpha)             |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| DIFFERENTIABLE           | yes         | op_new.jacobian(arr) = op_old.jacobian(arr) * \alpha               |
-|                          |             | op_new.diff_lipschitz = op_old.diff_lipschitz * abs(\alpha)        |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| DIFFERENTIABLE_FUNCTION  | yes         | op_new.grad(arr) = op_old.grad(arr) * \alpha                       |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| QUADRATIC                | \alpha > 0  | Q, c, t = op_old._quad_spec()                                      |
-|                          |             | op_new._quad_spec() = (\alpha * Q, \alpha * c, \alpha * t)         |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR                   | yes         | op_new.adjoint(arr) = op_old.adjoint(arr) * \alpha                 |
-|                          |             | op_new.asarray() = op_old.asarray() * \alpha                       |
-|                          |             | op_new.svdvals() = op_old.svdvals() * abs(\alpha)                  |
-|                          |             | op_new.pinv(x, damp) = op_old.pinv(x, damp / (\alpha**2)) / \alpha |
-|                          |             | op_new.gram() = op_old.gram() * (\alpha**2)                        |
-|                          |             | op_new.cogram() = op_old.cogram() * (\alpha**2)                    |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR_SQUARE            | yes         | op_new.trace() = op_old.trace() * \alpha                           |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR_NORMAL            | yes         |                                                                    |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR_UNITARY           | \alpha = -1 |                                                                    |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR_SELF_ADJOINT      | yes         |                                                                    |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR_POSITIVE_DEFINITE | \alpha > 0  |                                                                    |
-|--------------------------|-------------|--------------------------------------------------------------------|
-| LINEAR_IDEMPOTENT        | no          |                                                                    |
-|--------------------------|-------------|--------------------------------------------------------------------|
-
        -
        -
        -
        Parameters:
        -
        -
        -
        -
        -
        -
        -class ArgScaleRule(op, cst)[source]#
        -

        Bases: Rule

        -

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

        -

        Special Cases:

        -
        \alpha = 0  => ConstantValued (w/ potential vector-valued output)
-\alpha = 1  => self
-
        -
        -

        Else:

        -
        |--------------------------|-------------|-----------------------------------------------------------------------------|
-|         Property         |  Preserved? |                          Arithmetic Update Rule(s)                          |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| CAN_EVAL                 | yes         | op_new.apply(arr) = op_old.apply(arr * \alpha)                              |
-|                          |             | op_new.lipschitz = op_old.lipschitz * abs(\alpha)                           |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| FUNCTIONAL               | yes         | op_new.asloss(\beta) = AMBIGUOUS -> DISABLED                                |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| PROXIMABLE               | yes         | op_new.prox(arr, tau) = op_old.prox(\alpha * arr, \alpha**2 * tau) / \alpha |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| DIFFERENTIABLE           | yes         | op_new.diff_lipschitz = op_old.diff_lipschitz * (\alpha**2)                 |
-|                          |             | op_new.jacobian(arr) = op_old.jacobian(arr * \alpha) * \alpha               |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| DIFFERENTIABLE_FUNCTION  | yes         | op_new.grad(arr) = op_old.grad(\alpha * arr) * \alpha                       |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| QUADRATIC                | yes         | Q, c, t = op_old._quad_spec()                                               |
-|                          |             | op_new._quad_spec() = (\alpha**2 * Q, \alpha * c, t)                        |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR                   | yes         | op_new.adjoint(arr) = op_old.adjoint(arr) * \alpha                          |
-|                          |             | op_new.asarray() = op_old.asarray() * \alpha                                |
-|                          |             | op_new.svdvals() = op_old.svdvals() * abs(\alpha)                           |
-|                          |             | op_new.pinv(x, damp) = op_old.pinv(x, damp / (\alpha**2)) / \alpha          |
-|                          |             | op_new.gram() = op_old.gram() * (\alpha**2)                                 |
-|                          |             | op_new.cogram() = op_old.cogram() * (\alpha**2)                             |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR_SQUARE            | yes         | op_new.trace() = op_old.trace() * \alpha                                    |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR_NORMAL            | yes         |                                                                             |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR_UNITARY           | \alpha = -1 |                                                                             |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR_SELF_ADJOINT      | yes         |                                                                             |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR_POSITIVE_DEFINITE | \alpha > 0  |                                                                             |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-| LINEAR_IDEMPOTENT        | no          |                                                                             |
-|--------------------------|-------------|-----------------------------------------------------------------------------|
-
        -
        -
        -
        Parameters:
        -
        @@ -811,7 +473,7 @@

        pyxu.abc
        Parameters:

        @@ -1033,6 +695,9 @@

        pyxu.abc

        +
        +
        +

        pyxu.abc.operator#

        class Property(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#
        @@ -1451,7 +1116,7 @@

        pyxu.abc

        -property lipschitz: Real#
        +property lipschitz: Real#

        Return the last computed Lipschitz constant of \(\mathbf{f}\).

        Notes

          @@ -1495,7 +1160,7 @@

          pyxu.abc

          kwargs (Mapping) – Class-specific kwargs to configure Lipschitz estimation.

          Return type:
          -

          Real

          +

          Real

        Notes

        @@ -1602,7 +1267,7 @@

        pyxu.abc
        -property diff_lipschitz: Real#
        +property diff_lipschitz: Real#

        Return the last computed Lipschitz constant of \(\mathbf{J}_{\mathbf{f}}\).

        Notes

          @@ -1646,7 +1311,7 @@

          pyxu.abc

          kwargs (Mapping) – Class-specific kwargs to configure diff-Lipschitz estimation.

          Return type:
          -

          Real

          +

          Real

        Notes

        @@ -1931,7 +1596,7 @@

        pyxu.abc

      • shape (tuple[Integral, Integral]) –

      • Q (PosDefOp) –

      • c (LinFunc) –

        • -

      • t (Real) –

        • +

      • t (Real) –

      @@ -2040,7 +1705,7 @@

      pyxu.abc

    Return type:
    -

    Real

    +

    Real

    Notes

    @@ -2090,276 +1755,634 @@

    pyxu.abc

    Matrix representation of the linear operator.

    Parameters:
    -
      -

    • xp (ArrayModule) – Which array module to use to represent the output. (Default: NumPy.)

      • -

    • dtype (DType) – Precision of the array. (Default: current runtime precision.)

      • -
    -
    -
    Returns:
    -

    A – (N, M) array-representation of the operator.

    -
    -
    Return type:
    -

    NDArray

    +
      +

    • xp (ArrayModule) – Which array module to use to represent the output. (Default: NumPy.)

      • +

    • dtype (DType) – Precision of the array. (Default: current runtime precision.)

      • +
    +
    +
    Returns:
    +

    A – (N, M) array-representation of the operator.

    +
    +
    Return type:
    +

    NDArray

    +
    +
    +
    +

    Note

    +

    This generic implementation assumes the operator is backend-agnostic. Thus, when defining a new +backend-specific operator, asarray() may need to be overriden.

    +
    +
    +
    +
    +gram()[source]#
    +

    Gram operator \(\mathbf{A}^{\ast} \mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{M}\).

    +
    +
    Returns:
    +

    op – (M, M) 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.

    +
    +
    +
    +
    +cogram()[source]#
    +

    Co-Gram operator \(\mathbf{A}\mathbf{A}^{\ast}:\mathbb{R}^{N} \to \mathbb{R}^{N}\).

    +
    +
    Returns:
    +

    op – (N, N) 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.

    +
    +
    +
    +
    +pinv(arr, damp, kwargs_init=None, kwargs_fit=None)[source]#
    +

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

    +
    +
    Parameters:
    +
      +

    • arr (NDArray) – (…, N) 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 – (…, M) pseudo-inverse(s).

    +
    +
    Return type:
    +

    NDArray

    +
    +
    +

    Notes

    +

    The Moore-Penrose pseudo-inverse of an operator \(\mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{N}\) is defined +as the operator \(\mathbf{A}^{\dagger}: \mathbb{R}^{N} \to \mathbb{R}^{M}\) verifying the Moore-Penrose +conditions:

    +
    +
      +

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

      2. +

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

      3. +

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

      4. +

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

      5. +
    +
    +

    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}\) 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} \times \mathbb{R}^{N}.\]
    +

    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_init=None, kwargs_fit=None)[source]#
    +

    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 – (M, N) Moore-Penrose pseudo-inverse operator.

    +
    +
    Return type:
    +

    OpT

    +
    +
    +
    +
    +
    +classmethod from_array(A, enable_warnings=True)[source]#
    +

    Instantiate a LinOp from its array representation.

    +
    +
    Parameters:
    +
      +

    • A (NDArray) – (N, M) array

      • +

    • enable_warnings (bool) – If True, emit a warning in case of precision mis-match issues.

      • +
    +
    +
    Returns:
    +

    op – (N, M) linear operator

    +
    +
    Return type:
    +

    OpT

    +
    +
    +
    + +
    +
    +class SquareOp(shape)[source]#
    +

    Bases: LinOp

    +

    Base class for square linear operators, i.e. \(\mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{M}\) +(endomorphsisms).

    +
    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    +
    +
    +
    +
    +trace(**kwargs)[source]#
    +

    Compute trace of the operator.

    +
    +
    Parameters:
    +
      +

    • method ("explicit" | "hutchpp") –

        +

      • If explicit, compute the exact trace.

        • +

      • If hutchpp, compute an approximation.

        • +
      +

      • +

    • kwargs (Mapping) –

      Optional kwargs passed to:

      + +

      • +
    +
    +
    Returns:
    +

    tr – Trace estimate.

    +
    +
    Return type:
    +

    Real

    +
    +
    +
    +
    +
    +
    +class NormalOp(shape)[source]#
    +

    Bases: SquareOp

    +

    Base class for normal operators.

    +

    Normal operators satisfy the relation \(\mathbf{A} \mathbf{A}^{\ast} = \mathbf{A}^{\ast} \mathbf{A}\). It can +be shown that an operator is normal iff it is +unitarily diagonalizable, i.e. \(\mathbf{A} = \mathbf{U} \mathbf{D} \mathbf{U}^{\ast}\).

    +
    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    +
    +
    +
    +
    +
    +class SelfAdjointOp(shape)[source]#
    +

    Bases: NormalOp

    +

    Base class for self-adjoint operators.

    +

    Self-adjoint operators satisfy the relation \(\mathbf{A}^{\ast} = \mathbf{A}\).

    +
    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    +
    +
    +
    +
    +
    +class UnitOp(shape)[source]#
    +

    Bases: NormalOp

    +

    Base class for unitary operators.

    +

    Unitary operators satisfy the relation \(\mathbf{A} \mathbf{A}^{\ast} = \mathbf{A}^{\ast} \mathbf{A} = I\).

    +
    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    +
    +
    +
    +
    +
    +class ProjOp(shape)[source]#
    +

    Bases: SquareOp

    +

    Base class for projection operators.

    +

    Projection operators are idempotent, i.e. \(\mathbf{A}^{2} = \mathbf{A}\).

    +
    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    +
    +
    +
    +
    +
    +class OrthProjOp(shape)[source]#
    +

    Bases: ProjOp, SelfAdjointOp

    +

    Base class for orthogonal projection operators.

    +

    Orthogonal projection operators are idempotent and self-adjoint, i.e. \(\mathbf{A}^{2} = \mathbf{A}\) and +\(\mathbf{A}^{\ast} = \mathbf{A}\).

    +
    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    -
    -

    Note

    -

    This generic implementation assumes the operator is backend-agnostic. Thus, when defining a new -backend-specific operator, asarray() may need to be overriden.

    -
    -
    -
    -gram()[source]#
    -

    Gram operator \(\mathbf{A}^{\ast} \mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{M}\).

    +
    +
    +class PosDefOp(shape)[source]#
    +

    Bases: SelfAdjointOp

    +

    Base class for positive-definite operators.

    -
    Returns:
    -

    op – (M, M) Gram operator.

    -
    -
    Return type:
    -

    OpT

    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    -
    -

    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.

    -
    -
    -
    -cogram()[source]#
    -

    Co-Gram operator \(\mathbf{A}\mathbf{A}^{\ast}:\mathbb{R}^{N} \to \mathbb{R}^{N}\).

    +
    +
    +class LinFunc(shape)[source]#
    +

    Bases: ProxDiffFunc, LinOp

    +

    Base class for real-valued linear functionals \(f: \mathbb{R}^{M} \to \mathbb{R}\).

    +

    Instances of this class must implement apply(), and adjoint().

    +

    If known, the Lipschitz constant \(L\) should be stored in the lipschitz property.

    -
    Returns:
    -

    op – (N, N) Co-Gram operator.

    -
    -
    Return type:
    -

    OpT

    +
    Parameters:
    +

    shape (tuple[Integral, Integral]) –

    -
    -

    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.

    -
    -
    -
    -pinv(arr, damp, kwargs_init=None, kwargs_fit=None)[source]#
    -

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

    + +
    +

    pyxu.abc.solver#

    +
    +
    +class Solver(*, folder=None, exist_ok=False, stop_rate=1, writeback_rate=None, verbosity=None, show_progress=True, log_var=frozenset({}))[source]#
    +

    Bases: object

    +

    Iterative solver for minimization problems of the form \(\hat{x} = \arg\min_{x \in \mathbb{R}^{N}} +\mathcal{F}(x)\), where the form of \(\mathcal{F}\) is solver-dependent.

    +

    Solver provides a versatile API for solving optimisation problems, with the following features:

    +
      +

    • manual/automatic/background execution of solver iterations via parameters provided to +fit(). (See below.)

      • +

    • automatic checkpointing of solver progress, providing a safe restore point in case of faulty numerical code. Each +solver instance backs its state and final output to a folder on disk for post-analysis. In particular +fit() will never crash: detailed exception information will always be available in a +logfile for post-analysis.

      • +

    • arbitrary specification of complex stopping criteria via the StoppingCriterion class.

      • +

    • solve for multiple initial points in parallel.

      • +
    +

    To implement a new iterative solver, users need to sub-class Solver and overwrite the methods +below:

    + +

    Advanced functionalities of Solver are automatically inherited by sub-classes.

    +

    Examples

    +

    Here are examples on how to solve minimization problems with this class:

    +
    slvr = Solver()
+
+### 1. Blocking mode: .fit() does not return until solver has stopped.
+>>> slvr.fit(mode=SolverMode.BLOCK, ...)
+>>> data, hist = slvr.stats()  # final output of solver.
+
+### 2. Async mode: solver iterations run in the background.
+>>> slvr.fit(mode=SolverMode.ASYNC, ...)
+>>> print('test')  # you can do something in between.
+>>> slvr.busy()  # or check whether the solver already stopped.
+>>> slvr.stop()  # and preemptively force it to stop.
+>>> data, hist = slvr.stats()  # then query the result after a (potential) force-stop.
+
+### 3. Manual mode: fine-grain control of solver data per iteration.
+>>> slvr.fit(mode=SolverMode.MANUAL, ...)
+>>> for data in slvr.steps():
+...     # Do something with the logged variables after each iteration.
+...     pass  # solver has stopped after the loop.
+>>> data, hist = slvr.stats()  # final output of solver.
+
    +
    Parameters:
      -

    • arr (NDArray) – (…, N) 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.

      • +

    • folder (str | Path) –

      • +

    • exist_ok (bool) –

      • +

    • stop_rate (Integral) –

      • +

    • writeback_rate (Integral) –

      • +

    • verbosity (Integral) –

      • +

    • show_progress (bool) –

      • +

    • log_var (str | Collection[str]) –

    -
    Returns:
    -

    out – (…, M) pseudo-inverse(s).

    -
    -
    Return type:
    -

    NDArray

    -
    -

    Notes

    -

    The Moore-Penrose pseudo-inverse of an operator \(\mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{N}\) is defined -as the operator \(\mathbf{A}^{\dagger}: \mathbb{R}^{N} \to \mathbb{R}^{M}\) verifying the Moore-Penrose -conditions:

    -
    -
      -

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

      2. -

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

      3. -

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

      4. -

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

      5. -
    -
    -

    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}\) 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} \times \mathbb{R}^{N}.\]
    -

    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.

    +
    +
    +_mstate: dict[str, Any]#
    +

    Mathematical state.

    +
    +
    +
    +_astate: dict[str, Any]#
    +

    Book-keeping (non-math) state.

    -
    -dagger(damp, kwargs_init=None, kwargs_fit=None)[source]#
    -

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

    -
    +
    +__init__(*, folder=None, exist_ok=False, stop_rate=1, writeback_rate=None, verbosity=None, show_progress=True, log_var=frozenset({}))[source]#
    +
    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.

      • +

    • folder (Path) – Directory on disk where instance data should be stored. A location will be automatically chosen if +unspecified. (Default: OS-dependent tempdir.)

      • +

    • exist_ok (bool) – If folder is specified and exist_ok is false (default), FileExistsError is raised if the +target directory already exists.

      • +

    • stop_rate (Integer) – Rate at which solver evaluates stopping criteria.

      • +

    • writeback_rate (Integer) – Rate at which solver checkpoints are written to disk. No checkpointing is done if unspecified: only the +final solver output will be written back to disk. Must be a multiple of stop_rate if specified.

      • +

    • verbosity (Integer) – Rate at which stopping criteria statistics are logged. Must be a multiple of stop_rate. Defaults to +stop_rate if unspecified.

      • +

    • show_progress (bool) – If True (default) and fit() is run with mode=BLOCK, then statistics are also +logged to stdout.

      • +

    • log_var (VarName) – Variables from the solver’s math-state (_mstate) to be logged per iteration. +These are the variables made available when calling stats().

    -
    Returns:
    -

    op – (M, N) Moore-Penrose pseudo-inverse operator.

    -
    -
    Return type:
    -

    OpT

    -
    +

    Notes

    +
      +

    • Partial device<>CPU synchronization takes place when stopping-criteria are evaluated. Increasing stop_rate +is advised to reduce the effect of such transfers when applicable.

      • +

    • Full device<>CPU synchronization takes place at checkpoint-time. Increasing writeback_rate is advised to +reduce the effect of such transfers when applicable.

      • +
    -
    -classmethod from_array(A, enable_warnings=True)[source]#
    -

    Instantiate a LinOp from its array representation.

    +
    +fit(**kwargs)[source]#
    +

    Solve minimization problem(s) defined in __init__(), with the provided run-specifc +parameters.

    Parameters:
      -

    • A (NDArray) – (N, M) array

      • -

    • enable_warnings (bool) – If True, emit a warning in case of precision mis-match issues.

      • +

    • kwargs – See class-level docstring for class-specific keyword parameters.

      • +

    • stop_crit (StoppingCriterion) – Stopping criterion to end solver iterations. If unspecified, defaults to +default_stop_crit().

      • +

    • mode (SolverMode) –

      Execution mode. +See Solver for usage examples.

      +

      Useful method pairs depending on the execution mode:

      + +

      • +

    • track_objective (bool) – Auto-compute objective function every time stopping criterion is evaluated.

    -
    -
    Returns:
    -

    op – (N, M) linear operator

    -
    -
    Return type:
    -

    OpT

    +
    +
    +m_init(**kwargs)[source]#
    +

    Set solver’s initial mathematical state based on kwargs provided to fit().

    +

    This method must only manipulate _mstate.

    +

    After calling this method, the solver must be able to complete its 1st iteration via a call to +m_step().

    +
    +
    +
    +m_step()[source]#
    +

    Perform one (mathematical) step.

    +

    This method must only manipulate _mstate.

    -
    -
    -class SquareOp(shape)[source]#
    -

    Bases: LinOp

    -

    Base class for square linear operators, i.e. \(\mathbf{A}: \mathbb{R}^{M} \to \mathbb{R}^{M}\) -(endomorphsisms).

    +
    +
    +steps(n=None)[source]#
    +

    Generator of logged variables after each iteration.

    +

    The i-th call to next() on this object returns the logged variables after the i-th solver iteration.

    +

    This method is only usable after calling fit() with mode=MANUAL. See +Solver for usage examples.

    +

    There is no guarantee that a checkpoint on disk exists when the generator is exhausted. (Reason: potential +exceptions raised during solver’s progress.) Users should invoke writeback() +afterwards if needed.

    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +

    n (Integer) –

    Maximum number of next() calls allowed before exhausting the generator. Defaults to infinity if +unspecified.

    +

    The generator will terminate prematurely if the solver naturally stops before n calls to next() +are made.

    +

    +
    +
    Return type:
    +

    Generator

    +
    -
    -trace(**kwargs)[source]#
    -

    Compute trace of the operator.

    +
    +stats()[source]#
    +

    Query solver state.

    -
    Parameters:
    -
      -

    • method ("explicit" | "hutchpp") –

        -

      • If explicit, compute the exact trace.

        • -

      • If hutchpp, compute an approximation.

        • -
      -

      • -

    • kwargs (Mapping) –

      Optional kwargs passed to:

      - -

      • +
      Returns:
      +

        +

      • data (Mapping) – Value(s) of log_var (s) after last iteration.

        • +

      • history (numpy.ndarray, None) – (N_iter,) records of stopping-criteria values per iteration.

      +

      -
      Returns:
      -

      tr – Trace estimate.

      -
      -
      Return type:
      -

      Real

      +
      Return type:
      +

      tuple[dict[str, Real | NDArray | None], ndarray | None]

    +

    Notes

    +

    If any of the log_var (s) and/or history are not (yet) known at query time, None is returned.

    +
    +
    +property workdir: str | Path#
    +
    +
    Returns:
    +

    wd – Absolute path to the directory on disk where instance data is stored.

    +
    +
    Return type:
    +

    Path

    +
    +
    -
    -
    -class NormalOp(shape)[source]#
    -

    Bases: SquareOp

    -

    Base class for normal operators.

    -

    Normal operators satisfy the relation \(\mathbf{A} \mathbf{A}^{\ast} = \mathbf{A}^{\ast} \mathbf{A}\). It can -be shown that an operator is normal iff it is -unitarily diagonalizable, i.e. \(\mathbf{A} = \mathbf{U} \mathbf{D} \mathbf{U}^{\ast}\).

    -
    -
    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +
    +
    +property logfile: str | Path#
    +
    +
    Returns:
    +

    lf – Absolute path to the log file on disk where stopping criteria statistics are logged.

    +
    +
    Return type:
    +

    Path

    -
    -
    -class SelfAdjointOp(shape)[source]#
    -

    Bases: NormalOp

    -

    Base class for self-adjoint operators.

    -

    Self-adjoint operators satisfy the relation \(\mathbf{A}^{\ast} = \mathbf{A}\).

    -
    -
    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +
    +
    +property datafile: str | Path#
    +
    +
    Returns:
    +

    df – Absolute path to the file on disk where log_var (s) are stored during checkpointing or after solver has +stopped.

    +
    +
    Return type:
    +

    Path

    -
    -
    -class UnitOp(shape)[source]#
    -

    Bases: NormalOp

    -

    Base class for unitary operators.

    -

    Unitary operators satisfy the relation \(\mathbf{A} \mathbf{A}^{\ast} = \mathbf{A}^{\ast} \mathbf{A} = I\).

    +
    +
    +busy()[source]#
    +

    Test if an async-running solver has stopped.

    +

    This method is only usable after calling fit() with mode=ASYNC. See +Solver for usage examples.

    -
    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +
    Returns:
    +

    b – True if solver has stopped, False otherwise.

    +
    +
    Return type:
    +

    bool

    -
    -
    -class ProjOp(shape)[source]#
    -

    Bases: SquareOp

    -

    Base class for projection operators.

    -

    Projection operators are idempotent, i.e. \(\mathbf{A}^{2} = \mathbf{A}\).

    +
    +
    +solution()[source]#
    +

    Output the “solution” of the optimization problem.

    +

    This is a helper method intended for novice users. The return type is sub-class dependent, so don’t write an +API using this: use stats() instead.

    +
    +
    +
    +stop()[source]#
    +

    Stop an async-running solver.

    +

    This method is only usable after calling fit() with mode=ASYNC. See +Solver for usage examples.

    +

    This method will block until the solver has stopped.

    +

    There is no guarantee that a checkpoint on disk exists once halted. (Reason: potential exceptions raised during +solver’s progress.) Users should invoke writeback() afterwards if needed.

    +

    Users must call this method to terminate an async-solver, even if busy() is False.

    +
    +
    +
    +writeback()[source]#
    +

    Checkpoint state to disk.

    +
    +
    +
    +default_stop_crit()[source]#
    +

    Default stopping criterion for solver if unspecified in fit() calls.

    +

    Sub-classes are expected to overwrite this method. If not overridden, then omitting the stop_crit parameter +in fit() is forbidden.

    -
    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +
    Return type:
    +

    StoppingCriterion

    -
    -
    -class OrthProjOp(shape)[source]#
    -

    Bases: ProjOp, SelfAdjointOp

    -

    Base class for orthogonal projection operators.

    -

    Orthogonal projection operators are idempotent and self-adjoint, i.e. \(\mathbf{A}^{2} = \mathbf{A}\) and -\(\mathbf{A}^{\ast} = \mathbf{A}\).

    +
    +
    +objective_func()[source]#
    +

    Evaluate objective function given current math state.

    +

    The output array must have shape:

    +
      +

    • (1,) if evaluated at 1 point,

      • +

    • (N, 1) if evaluated at N different points.

      • +
    +

    Sub-classes are expected to overwrite this method. If not overridden, then enabling track_objective in +fit() is forbidden.

    -
    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +
    Return type:
    +

    NDArray

    +
    -
    -class PosDefOp(shape)[source]#
    -

    Bases: SelfAdjointOp

    -

    Base class for positive-definite operators.

    +
    +class SolverMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#
    +

    Bases: Enum

    +

    Solver execution mode.

    +
    +
    +BLOCK = 1#
    +
    +
    +
    +MANUAL = 2#
    +
    +
    +
    +ASYNC = 3#
    +
    +
    +
    +
    +class StoppingCriterion[source]#
    +

    Bases: object

    +

    State machines (SM) which decide when to stop iterative solvers by examining their mathematical state.

    +

    SM decisions are always accompanied by at least one numerical statistic. These stats may be queried by solvers via +info() to provide diagnostic information to users.

    +

    Composite stopping criteria can be implemented via the overloaded (and[&], or[|]) operators.

    +
    +
    +stop(state)[source]#
    +

    Compute a stop signal based on the current mathematical state.

    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +

    state (Mapping) –

    Full mathematical state of solver at some iteration, i.e. _mstate.

    +

    Values from state may be cached inside the instance to form complex stopping conditions.

    +

    +
    +
    Returns:
    +

    s – True if no further iterations should be performed, False otherwise.

    +
    +
    Return type:
    +

    bool

    -
    -
    -class LinFunc(shape)[source]#
    -

    Bases: ProxDiffFunc, LinOp

    -

    Base class for real-valued linear functionals \(f: \mathbb{R}^{M} \to \mathbb{R}\).

    -

    Instances of this class must implement apply(), and adjoint().

    -

    If known, the Lipschitz constant \(L\) should be stored in the lipschitz property.

    +
    +
    +info()[source]#
    +

    Get statistics associated with the last call to stop().

    -
    Parameters:
    -

    shape (tuple[Integral, Integral]) –

    +
    Returns:
    +

    data

    +
    +
    Return type:
    +

    Mapping

    +
    +
    +clear()[source]#
    +

    Clear SM state (if any).

    +

    This method is useful when a StoppingCriterion instance must be reused in another call to +fit().

    +
    +
    +
    @@ -2391,144 +2414,153 @@

    pyxu.abc

    diff --git a/api/abc/arithmetic.html b/api/abc/arithmetic.html index 9f2c9103..f6d68d97 100644 --- a/api/abc/arithmetic.html +++ b/api/abc/arithmetic.html @@ -28,7 +28,7 @@ - + @@ -38,13 +38,13 @@ - + - + diff --git a/api/abc/index.html b/api/abc/index.html index a2c4ad1c..c22640a8 100644 --- a/api/abc/index.html +++ b/api/abc/index.html @@ -28,7 +28,7 @@ - + @@ -38,13 +38,13 @@ - + - + diff --git a/api/abc/operator.html b/api/abc/operator.html index 3687ed9f..52ca7c9c 100644 --- a/api/abc/operator.html +++ b/api/abc/operator.html @@ -1,125 +1,199 @@ - - - - -pyxu.abc.operator — Pyxu Documentation - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    -
    -
    -
    - - -Ctrl+K + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    + + + + Ctrl+K
    -
    -
    + + -
    -
    -
    -
    -
    -
    + +
    +
    + +
    + + + +
    + + +
    + +
    -
    -
    -
    Pyxu v1.0.1
    -
    + + + +
    + +
    Pyxu v1.0.1
    + +
    -
    -
    -
    -
    + +
    +
    -
    -
    -
    - -
    -
    -
    -
    -
    +
    + + +
    +
    + + + + +
    + +
    + + +
    +
    + +
    -
    -
    + +
    + +
    + + +
    + +
    + +
    -
    + + + + -
    -
    +
    + +

    pyxu.abc.operator#

    @@ -303,54 +513,67 @@

    pyxu.abc.operator CAN_EVAL = 1#

    +
    FUNCTIONAL = 2#
    +
    PROXIMABLE = 3#
    +
    DIFFERENTIABLE = 4#
    +
    DIFFERENTIABLE_FUNCTION = 5#
    +
    LINEAR = 6#
    +
    LINEAR_SQUARE = 7#
    +
    LINEAR_NORMAL = 8#
    +
    LINEAR_IDEMPOTENT = 9#
    +
    LINEAR_SELF_ADJOINT = 10#
    +
    LINEAR_POSITIVE_DEFINITE = 11#
    +
    LINEAR_UNITARY = 12#
    +
    QUADRATIC = 13#
    +
    arithmetic_methods()[source]#
    @@ -361,7 +584,9 @@

    pyxu.abc.operator
    class Operator(shape)[source]#
    @@ -388,21 +613,25 @@

    pyxu.abc.operator
    property shape: tuple[Integral, Integral]#

    Return (N, M) operator shape.

    +
    property dim: Integral#

    Return dimension of operator’s domain. (M)

    +
    property codim: Integral#

    Return dimension of operator’s co-domain. (N)

    +
    classmethod properties()[source]#
    @@ -413,6 +642,7 @@

    pyxu.abc.operator
    classmethod has(prop)[source]#
    @@ -426,6 +656,7 @@

    pyxu.abc.operator
    asop(cast_to)[source]#
    @@ -453,6 +684,7 @@

    pyxu.abc.operatorNotImplementedError when called.

+
__add__(other)[source]#
@@ -484,6 +716,7 @@

pyxu.abc.operatorAddRule

+
__sub__(other)[source]#
@@ -503,6 +736,7 @@

pyxu.abc.operator
__neg__()[source]#
@@ -516,6 +750,7 @@

pyxu.abc.operator
__mul__(other)[source]#
@@ -543,6 +778,7 @@

pyxu.abc.operatorScaleRule, ChainRule

+
__pow__(k)[source]#
@@ -565,6 +801,7 @@

pyxu.abc.operatorPowerRule

+
argscale(scalar)[source]#
@@ -585,6 +822,7 @@

pyxu.abc.operatorArgScaleRule

+
argshift(shift)[source]#
@@ -605,6 +843,7 @@

pyxu.abc.operatorArgShiftRule

+
squeeze()[source]#
@@ -615,6 +854,7 @@

pyxu.abc.operator
expr(level=0, strip=True)[source]#
@@ -653,7 +893,9 @@

pyxu.abc.operator
class Map(shape)[source]#
@@ -677,6 +919,7 @@

pyxu.abc.operator
apply(arr)[source]#
@@ -693,6 +936,7 @@

pyxu.abc.operator
__call__(arr)[source]#
@@ -706,6 +950,7 @@

pyxu.abc.operator
property lipschitz: Real#
@@ -743,6 +988,7 @@

pyxu.abc.operator
estimate_lipschitz(**kwargs)[source]#
@@ -772,7 +1018,9 @@

pyxu.abc.operator
class Func(shape)[source]#
@@ -805,7 +1053,9 @@

pyxu.abc.operator
class DiffMap(shape)[source]#
@@ -857,6 +1107,7 @@

pyxu.abc.operator
property diff_lipschitz: Real#
@@ -894,6 +1145,7 @@

pyxu.abc.operator
estimate_diff_lipschitz(**kwargs)[source]#
@@ -923,7 +1175,9 @@

pyxu.abc.operator
class DiffFunc(shape)[source]#
@@ -965,7 +1219,9 @@

pyxu.abc.operator
class ProxFunc(shape)[source]#
@@ -1010,6 +1266,7 @@

pyxu.abc.operator
fenchel_prox(arr, sigma)[source]#
@@ -1041,6 +1298,7 @@

pyxu.abc.operator
moreau_envelope(mu)[source]#
@@ -1083,56 +1341,58 @@

pyxu.abc.operator\(f^{\mu}\) is strongly-convex.

Example

Construct and plot the Moreau envelope of the \(\ell_{1}\)-norm:

-
import numpy as np
-import matplotlib.pyplot as plt
-from pyxu.abc import ProxFunc
+
import numpy as np
+import matplotlib.pyplot as plt
+from pyxu.abc import ProxFunc
 
-class L1Norm(ProxFunc):
-    def __init__(self, dim: int):
-        super().__init__(shape=(1, dim))
+class L1Norm(ProxFunc):
+    def __init__(self, dim: int):
+        super().__init__(shape=(1, dim))
     def apply(self, arr):
-        return np.linalg.norm(arr, axis=-1, keepdims=True, ord=1)
+        return np.linalg.norm(arr, axis=-1, keepdims=True, ord=1)
     def prox(self, arr, tau):
-        return np.clip(np.abs(arr)-tau, a_min=0, a_max=None) * np.sign(arr)
+        return np.clip(np.abs(arr)-tau, a_min=0, a_max=None) * np.sign(arr)
 
 N = 512
 l1_norm = L1Norm(dim=N)
 mus = [0.1, 0.5, 1]
 smooth_l1_norms = [l1_norm.moreau_envelope(mu) for mu in mus]
 
-x = np.linspace(-1, 1, N)[:, None]
-labels=['mu=0']
-labels.extend([f'mu={mu}' for mu in mus])
-plt.figure()
-plt.plot(x, l1_norm(x))
+x = np.linspace(-1, 1, N)[:, None]
+labels=['mu=0']
+labels.extend([f'mu={mu}' for mu in mus])
+plt.figure()
+plt.plot(x, l1_norm(x))
 for f in smooth_l1_norms:
-    plt.plot(x, f(x))
-plt.legend(labels)
-plt.title('Moreau Envelope')
+    plt.plot(x, f(x))
+plt.legend(labels)
+plt.title('Moreau Envelope')
 
-labels=[f'mu={mu}' for mu in mus]
-plt.figure()
+labels=[f'mu={mu}' for mu in mus]
+plt.figure()
 for f in smooth_l1_norms:
-    plt.plot(x, f.grad(x))
-plt.legend(labels)
-plt.title('Derivative of Moreau Envelope')
+    plt.plot(x, f.grad(x))
+plt.legend(labels)
+plt.title('Derivative of Moreau Envelope')
 

 

 
(Source code)

 

-../../_images/operator-1_00.png
+../../_images/operator-1_00.png
 

 
(png, hires.png, pdf)#

 

 

 

-../../_images/operator-1_01.png
+../../_images/operator-1_01.png
 

 
(png, hires.png, pdf)#

+ +
class ProxDiffFunc(shape)[source]#
@@ -1149,6 +1409,7 @@

pyxu.abc.operator
class QuadraticFunc(shape, Q=None, c=None, t=0)[source]#
@@ -1206,13 +1467,16 @@

pyxu.abc.operator
_quad_spec()[source]#

Canonical quadratic parameterization.

Useful for some internal methods, and overloaded during operator arithmetic.

+ +
class LinOp(shape)[source]#
@@ -1251,11 +1515,13 @@

pyxu.abc.operator
property T: OpT#

Return the (M, N) adjoint of \(\mathbf{A}\).

+
to_sciop(dtype=None, gpu=False)[source]#
@@ -1276,6 +1542,7 @@

pyxu.abc.operator
estimate_lipschitz(**kwargs)[source]#
@@ -1283,7 +1550,7 @@

pyxu.abc.operator
Parameters:

+
gram()[source]#
@@ -1384,6 +1654,7 @@

pyxu.abc.operator
cogram()[source]#
@@ -1403,6 +1674,7 @@

pyxu.abc.operator
pinv(arr, damp, kwargs_init=None, kwargs_fit=None)[source]#
@@ -1450,6 +1722,7 @@

pyxu.abc.operator\(\tau > 0\) corresponds to the damp parameter.

+
dagger(damp, kwargs_init=None, kwargs_fit=None)[source]#
@@ -1470,6 +1743,7 @@

pyxu.abc.operator
classmethod from_array(A, enable_warnings=True)[source]#
@@ -1489,7 +1763,9 @@

pyxu.abc.operator
class SquareOp(shape)[source]#
@@ -1508,7 +1784,7 @@

pyxu.abc.operator
Parameters: