spacecore-optimize 0.0.1__py3-none-any.whl

spacecore_optimize/_scipy.py

@@ -0,0 +1,216 @@
+"""
+SciPy optimizer adapters: ``scipy.optimize`` on flat real coordinates.
+
+The gradient passed is ``X.riesz(F.grad(x))``. Structure is flattened away, so
+``bounds`` and ``constraints`` act on coordinates. SciPy's own models are
+Euclidean, and complex domains are rejected.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ._common import (
+    coordinate_gradient,
+    domain_with_geometry,
+    require_functional,
+    require_real_field,
+)
+
+
+def _flat_host(X: Any, element: Any) -> np.ndarray:
+    """Return ``element`` of ``X`` as a flat host ``float64`` array for SciPy."""
+    return np.asarray(X.flatten(element), dtype=np.float64).reshape(-1)
+
+
+def _reject_args(kw: dict, fname: str) -> None:
+    """Reject SciPy's ``args`` parameter, which is meaningless for a Functional.
+
+    SciPy splats ``args`` into every ``fun(x, *args)``/``jac(x, *args)`` call, but
+    a SpaceCore ``Functional`` takes only its domain element. Rejecting here turns
+    a cryptic ``takes 1 positional argument but 2 were given`` into an actionable
+    error.
+    """
+    if "args" in kw:
+        raise ValueError(
+            f"{fname} does not support the SciPy 'args' parameter: a SpaceCore "
+            "Functional takes only its domain element. Bake any extra parameters "
+            "into F instead."
+        )
+
+
+def _make_value_and_grad(F: Any, X: Any):
+    """Build SciPy ``fun``/``jac`` callables over flat host coordinate vectors."""
+    # SciPy works on flat real host vectors: unflatten into X, flatten the gradient back.
+    ctx = X.ctx
+
+    def fun(v: np.ndarray) -> float:
+        x = X.unflatten(ctx.asarray(np.asarray(v)))
+        return float(np.real(F.value(x)))
+
+    def jac(v: np.ndarray) -> np.ndarray:
+        x = X.unflatten(ctx.asarray(np.asarray(v)))
+        return _flat_host(X, coordinate_gradient(F, X, x))
+
+    return fun, jac
+
+
+def minimize_scipy(
+    F: Any,
+    x0: Any,
+    *,
+    method: str = "L-BFGS-B",
+    jac: Any = True,
+    **kw: Any,
+) -> Any:
+    r"""
+    Minimize a functional with :func:`scipy.optimize.minimize`.
+
+    SciPy sees flat coordinates: the gradient handed over is ``X.riesz(F.grad(x))``,
+    which is the identity on a Euclidean space and required on a weighted one.
+
+    Parameters
+    ----------
+    F : Functional
+        Objective on a real inner-product space ``X = F.domain``.
+    x0 : array-like
+        Initial guess in ``F.domain``.
+    method : str, optional
+        SciPy method; ``"L-BFGS-B"`` by default.
+    jac : bool, str, callable, or None, optional
+        ``True`` supplies the coordinate gradient; ``False``/``None`` or a real
+        finite-difference string lets SciPy approximate it; a callable is forwarded.
+        ``"cs"`` is rejected.
+    **kw
+        Forwarded to SciPy; ``bounds`` and ``constraints`` act on flat coordinates.
+        ``args`` is not supported.
+
+    Returns
+    -------
+    scipy.optimize.OptimizeResult
+        SciPy's result, plus ``x_element``: the minimizer as an element of ``F.domain``.
+
+    Raises
+    ------
+    TypeError
+        If ``F`` is not a :class:`~spacecore.Functional` or its domain has no inner product.
+    ValueError
+        If the domain is complex, ``jac="cs"``, or ``args`` is passed.
+
+    See Also
+    --------
+    line_search_scipy : Wolfe line search with the same gradient handoff.
+
+    Examples
+    --------
+    Minimize ``f(x) = 1/2 x^T diag(3, 1) x - 3 x_0 - 2 x_1`` on a Euclidean
+    space; the minimizer is ``(1, 2)``.
+
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx)
+    >>> Q = sc.DenseLinOp(ctx.asarray([[3.0, 0.0], [0.0, 1.0]]), X, X, ctx)
+    >>> linear = sc.InnerProductFunctional(ctx.asarray([-3.0, -2.0]), X)
+    >>> F = sc.LinOpQuadraticForm(Q, linear)
+    >>> result = spo.minimize_scipy(F, X.zeros(), options={"gtol": 1e-10})
+    >>> bool(result.success)
+    True
+    >>> np.allclose(np.asarray(result.x_element), [1.0, 2.0])
+    True
+    """
+    import scipy.optimize as sopt
+
+    # A Functional on a real inner-product space, without SciPy's args.
+    F = require_functional(F, "minimize_scipy")
+    X = domain_with_geometry(F, "minimize_scipy")
+    require_real_field(X, "minimize_scipy")
+    _reject_args(kw, "minimize_scipy")
+
+    # jac=True: analytic coordinate gradient. Complex step is rejected. Else SciPy's own scheme.
+    fun, riesz_jac = _make_value_and_grad(F, X)
+    if jac is True:
+        jac_arg: Any = riesz_jac
+    elif jac is False or jac is None:
+        jac_arg = None
+    elif jac == "cs":
+        raise ValueError(
+            "minimize_scipy does not support jac='cs' (complex-step) on a real "
+            "domain: SciPy evaluates the objective at complex perturbations the "
+            "real backend rejects. Use the default jac=True (analytic "
+            "X.riesz(F.grad(x))) or a real finite-difference scheme "
+            "(jac='2-point' or '3-point')."
+        )
+    else:
+        jac_arg = jac
+
+    # Minimize on flat coordinates; also return the minimizer as an element of X.
+    x0_flat = _flat_host(X, x0)
+    result = sopt.minimize(fun, x0_flat, method=method, jac=jac_arg, **kw)
+    result.x_element = X.unflatten(X.ctx.asarray(np.asarray(result.x)))
+    return result
+
+
+def line_search_scipy(F: Any, x: Any, d: Any, **kw: Any) -> Any:
+    r"""
+    Wolfe line search along ``d`` with :func:`scipy.optimize.line_search`.
+
+    The coordinate gradient ``X.riesz(F.grad(x))`` makes SciPy's slope equal the
+    directional derivative on any geometry.
+
+    Parameters
+    ----------
+    F : Functional
+        Objective on a real inner-product space ``X = F.domain``.
+    x : array-like
+        Current iterate in ``F.domain``.
+    d : array-like
+        Search direction; the new iterate is ``x + alpha * d``.
+    **kw
+        Forwarded to SciPy (``gfk``, ``c1``, ``c2``, ``amax``, ...). ``args`` is not supported.
+
+    Returns
+    -------
+    tuple
+        SciPy's ``(alpha, fc, gc, new_fval, old_fval, new_slope)``; ``alpha`` is ``None``
+        when the Wolfe conditions are not met.
+
+    Raises
+    ------
+    TypeError
+        If ``F`` is not a :class:`~spacecore.Functional` or its domain has no inner product.
+    ValueError
+        If the domain is complex or ``args`` is passed.
+
+    Examples
+    --------
+    A descent step on a convex quadratic returns a positive step length.
+
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx)
+    >>> Q = sc.DenseLinOp(ctx.asarray([[3.0, 0.0], [0.0, 1.0]]), X, X, ctx)
+    >>> F = sc.LinOpQuadraticForm(Q)
+    >>> x = ctx.asarray([1.0, 1.0])
+    >>> d = X.scale(-1.0, F.grad(x))
+    >>> alpha = spo.line_search_scipy(F, x, d)[0]
+    >>> bool(alpha > 0.0)
+    True
+    """
+    import scipy.optimize as sopt
+
+    # A Functional on a real inner-product space, without SciPy's args.
+    F = require_functional(F, "line_search_scipy")
+    X = domain_with_geometry(F, "line_search_scipy")
+    require_real_field(X, "line_search_scipy")
+    _reject_args(kw, "line_search_scipy")
+
+    # SciPy's line search on the flat coordinates of x and the direction d.
+    fun, jac = _make_value_and_grad(F, X)
+    xk = _flat_host(X, x)
+    pk = _flat_host(X, d)
+    return sopt.line_search(fun, jac, xk, pk, **kw)

spacecore_optimize/functionals/__init__.py

@@ -0,0 +1,36 @@
+"""Named functionals and closed-form proximal steps built on SpaceCore.
+
+Least squares, entropy objectives, the Huber loss, spectral lifts, the
+realified (stacked real) view and the metric-aware shrinkage primitive. The
+norms the SpaceCore prox rules use (``LpNormFunctional``,
+``SquaredL2NormFunctional``, ``L1NormFunctional``) stay in SpaceCore.
+"""
+
+from ._entropy import KLDivergenceFunctional, NegativeEntropyFunctional
+from ._huber import HuberFunctional
+from ._least_squares import least_squares
+from ._proximal import generalized_shrinkage, project_nonneg, prox_l1, prox_l2sq
+from ._realified import RealifiedFunctional, realify
+from ._spectral import (
+    NuclearNormFunctional,
+    SpectralFunctional,
+    eigenvalue_space,
+    spectralize,
+)
+
+__all__ = [
+    "HuberFunctional",
+    "KLDivergenceFunctional",
+    "NegativeEntropyFunctional",
+    "NuclearNormFunctional",
+    "RealifiedFunctional",
+    "SpectralFunctional",
+    "eigenvalue_space",
+    "generalized_shrinkage",
+    "least_squares",
+    "project_nonneg",
+    "prox_l1",
+    "prox_l2sq",
+    "realify",
+    "spectralize",
+]

spacecore_optimize/functionals/_entropy.py

@@ -0,0 +1,134 @@
+"""
+Entropy objectives: negative entropy and KL divergence.
+
+The negative entropy is the standard mirror-descent kernel (Beck, *First-Order
+Methods in Optimization*, Example 9.10, on the probability simplex); its spectral
+lift is ``Tr(X log X)``, the negative von Neumann entropy for a density matrix.
+"""
+from __future__ import annotations
+
+from typing import Any, cast
+
+from spacecore import CheckLevel, Context, checked_method
+from spacecore.functional._base import Domain
+from spacecore.functional._linear import _convert_space_element
+from spacecore.functional.tools._coordinate import _CoordinateFunctional
+
+
+class NegativeEntropyFunctional(_CoordinateFunctional[Domain]):
+    r"""
+    Negative entropy ``sum_i x_i log x_i``, with ``0 log 0 = 0``; the gradient ``log x_i + 1`` needs ``x_i > 0``.
+
+    Parameters
+    ----------
+    dom : Space
+        Domain.
+    ctx : Context, str, or None, optional
+        Backend context; resolved from ``dom`` when omitted.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level; the ambient default when omitted.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx)
+    >>> f = spo.NegativeEntropyFunctional(X)
+    >>> float(f.value(ctx.asarray([1.0, 1.0])))
+    0.0
+    >>> np.asarray(f.grad(ctx.asarray([1.0, 1.0])))  # log(x) + 1
+    array([1., 1.])
+    """
+
+    _fields = ("dom", "ctx")
+
+    def __init__(
+        self,
+        dom: Domain,
+        ctx: Context | str | None = None,
+        check_level: CheckLevel | None = None,
+    ) -> None:
+        super().__init__(dom, ctx, check_level=check_level)
+
+    @checked_method(in_space="domain", out_space="codomain")
+    def value(self, x: Any) -> Any:
+        """Return ``sum_i x_i log x_i`` with ``0 log 0 = 0``."""
+        # sum x log x, with 0 log 0 = 0 (log evaluated on a safe input).
+        o = self.ops
+        positive = x > 0
+        safe = o.where(positive, x, cast(Any, 1.0))
+        return o.sum(o.where(positive, x * o.log(safe), cast(Any, 0.0)))
+
+    def _coordinate_grad(self, x: Any) -> Any:
+        """Euclidean coordinate gradient ``log x_i + 1`` (defined for ``x_i > 0``)."""
+        return self.ops.log(x) + 1.0
+
+class KLDivergenceFunctional(_CoordinateFunctional[Domain]):
+    r"""
+    Kullback-Leibler divergence ``sum_i x_i log(x_i / t_i)`` to a positive target ``t``.
+
+    Defined for ``x_i >= 0`` (``0 log 0 = 0``); the gradient is ``log(x_i / t_i) + 1``.
+    With ``t`` all ones it is :class:`NegativeEntropyFunctional`. On probability
+    vectors this is KL divergence (Beck, *First-Order Methods in Optimization*,
+    Example 9.10, Eq. (9.13)); without equal total mass it can be negative.
+
+    Parameters
+    ----------
+    target : array-like
+        Target ``t`` in ``dom``, strictly positive.
+    dom : Space
+        Domain.
+    ctx : Context, str, or None, optional
+        Backend context; resolved from ``dom`` when omitted.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level; the ambient default when omitted.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx)
+    >>> f = spo.KLDivergenceFunctional(ctx.asarray([1.0, 1.0]), X)
+    >>> float(f.value(ctx.asarray([1.0, 1.0])))  # zero divergence at x == target
+    0.0
+    >>> np.asarray(f.grad(ctx.asarray([1.0, 1.0])))  # log(x / t) + 1
+    array([1., 1.])
+    """
+
+    _fields = ("target:_target", "dom", "ctx")
+    _dynamic = ("target",)
+
+    def __init__(
+        self,
+        target: Any,
+        dom: Domain,
+        ctx: Context | str | None = None,
+        check_level: CheckLevel | None = None,
+    ) -> None:
+        super().__init__(dom, ctx, check_level=check_level)
+        # Store the target on the functional's backend and check it belongs.
+        self._target = _convert_space_element(self.domain, target)
+        if self._checks_at_least("standard"):
+            self.domain._check_member(self._target)
+
+    @property
+    def target(self) -> Any:
+        """Stored reference element ``t``."""
+        return self._target
+
+    @checked_method(in_space="domain", out_space="codomain")
+    def value(self, x: Any) -> Any:
+        """Return ``sum_i x_i log(x_i / t_i)`` with ``0 log 0 = 0``."""
+        # sum x log(x / t), with 0 log 0 = 0.
+        o = self.ops
+        positive = x > 0
+        ratio = o.where(positive, x / self._target, cast(Any, 1.0))
+        return o.sum(o.where(positive, x * o.log(ratio), cast(Any, 0.0)))
+
+    def _coordinate_grad(self, x: Any) -> Any:
+        """Euclidean coordinate gradient ``log(x_i / t_i) + 1`` (for ``x_i > 0``)."""
+        return self.ops.log(x / self._target) + 1.0

spacecore_optimize/functionals/_huber.py

@@ -0,0 +1,77 @@
+"""The separable Huber loss functional."""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from spacecore import CheckLevel, Context, checked_method
+from spacecore.functional._base import Domain
+from spacecore.functional.tools._coordinate import _CoordinateFunctional
+
+
+class HuberFunctional(_CoordinateFunctional[Domain]):
+    r"""
+    Separable Huber loss ``sum_i h_delta(x_i)``.
+
+    ``h_delta(r)`` is ``r^2 / 2`` for ``|r| <= delta`` and ``delta (|r| - delta / 2)``
+    beyond; it is ``C^1``. This is ``delta * H_delta`` in Beck, *First-Order Methods
+    in Optimization*, Examples 6.54 and 6.62; multiplying both branches by ``delta``
+    gives this scaling and the derivative ``r`` or ``delta sign(r)``.
+
+    Parameters
+    ----------
+    dom : Space
+        Domain.
+    delta : float
+        Positive, finite threshold.
+    ctx : Context, str, or None, optional
+        Backend context; resolved from ``dom`` when omitted.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level; the ambient default when omitted.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx)
+    >>> f = spo.HuberFunctional(X, 1.0)
+    >>> float(f.value(ctx.asarray([0.5, 3.0])))  # 0.125 + (3 - 0.5)
+    2.625
+    """
+
+    _fields = ("dom", "delta", "ctx")
+
+    def __init__(
+        self,
+        dom: Domain,
+        delta: Any,
+        ctx: Context | str | None = None,
+        check_level: CheckLevel | None = None,
+    ) -> None:
+        super().__init__(dom, ctx, check_level=check_level)
+        # delta must be finite and positive.
+        delta = float(delta)
+        if not math.isfinite(delta) or delta <= 0.0:
+            raise ValueError(f"HuberFunctional requires a finite delta > 0, got {delta}.")
+        self.delta = delta
+
+    @checked_method(in_space="domain", out_space="codomain")
+    def value(self, x: Any) -> Any:
+        """Return ``sum_i h_delta(x_i)``."""
+        # Quadratic inside |x| <= delta, linear outside.
+        o = self.ops
+        d = self.delta
+        a = o.abs(x)
+        quadratic = 0.5 * a * a
+        linear = d * (a - 0.5 * d)
+        return o.sum(o.where(a <= d, quadratic, linear))
+
+    def _coordinate_grad(self, x: Any) -> Any:
+        """Euclidean coordinate gradient: ``x`` (quadratic) or ``delta sign(x)`` (tail)."""
+        # Gradient: x inside, delta sign(x) outside.
+        o = self.ops
+        d = self.delta
+        a = o.abs(x)
+        return o.where(a <= d, x, d * o.sign(x))

spacecore_optimize/functionals/_least_squares.py

@@ -0,0 +1,106 @@
+"""The :func:`least_squares` constructor.
+
+The ``0.4.0`` ergonomics study found every least-squares persona hand-expanding
+``1/2 ||A x - b||^2`` into ``Q = A.H @ A`` and ``c = -A^# b`` to fit a
+:class:`~spacecore.functional.LinOpQuadraticForm`. This module provides that
+expansion as a single front door. It returns an existing
+``LinOpQuadraticForm`` -- no new type -- so the whole quadratic toolbox
+(gradient, Hessian action, batched evaluation, composition) applies unchanged.
+"""
+from __future__ import annotations
+
+import numpy as _np
+from typing import Any
+
+from spacecore import DiagonalLinOp, InnerProductFunctional, LinOp, LinOpQuadraticForm
+from spacecore.functional._linear import _convert_space_element
+
+
+def least_squares(
+    A: LinOp,
+    b: Any,
+    *,
+    weights: Any = None,
+    scale: float = 0.5,
+) -> LinOpQuadraticForm:
+    r"""
+    Build ``scale * ||A x - b||^2`` as a :class:`~spacecore.functional.LinOpQuadraticForm`.
+
+    It is ``1/2 <x, Q x> + <c, x> + a`` with ``Q = 2 scale A.H A``, ``c = -2 scale A.H b``
+    and ``a = scale <b, b>``, all in the operator's own geometry. Expanding
+    the squared norm and moving ``A`` by the adjoint identity gives this formula
+    on real spaces; on complex spaces the cross term must be ``Re<c, x>``.
+    The current linear term retains the full pairing, so the squared-norm
+    interpretation requires real data. Trefethen & Bau, *Numerical Linear Algebra*,
+    Lecture 2, pp. 11-12.
+
+    Parameters
+    ----------
+    A : LinOp
+        Forward operator ``X -> Y``.
+    b : array-like
+        Observation in ``A.codomain``.
+    weights : array-like or None, optional
+        Positive diagonal residual weights ``w``, giving ``scale <r, diag(w) r>``.
+    scale : float, optional
+        Positive factor; ``0.5`` gives the textbook ``1/2 ||A x - b||^2``.
+
+    Returns
+    -------
+    LinOpQuadraticForm
+        The objective; its gradient is ``2 scale A.H (W (A x - b))``.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx)
+    >>> Y = sc.DenseCoordinateSpace((2,), ctx)
+    >>> A = sc.DenseLinOp(ctx.asarray([[1.0, 0.0], [0.0, 2.0]]), X, Y, ctx)
+    >>> f = spo.least_squares(A, ctx.asarray([1.0, 4.0]))
+    >>> float(f.value(ctx.asarray([1.0, 2.0])))
+    0.0
+    """
+    # Validate A and scale.
+    if not isinstance(A, LinOp):
+        raise TypeError(f"least_squares requires A to be a LinOp, got {type(A).__name__}.")
+
+    scale = float(scale)
+    if not _np.isfinite(scale):
+        raise ValueError(f"least_squares requires a finite scale, got {scale}.")
+
+    X = A.domain
+    Y = A.codomain
+    ctx = A.ctx
+    b = _convert_space_element(Y, b)  # native members pass through untouched
+    two_scale = 2.0 * scale
+
+    # Unweighted: Gram A* A, right-hand side A* b, energy <b, b>.
+    if weights is None:
+        gram = A.H @ A
+        rhs = A.H.apply(b)
+        b_energy = Y.inner(b, b)
+    # Weighted: the same with W = diag(w) inserted, after validating w.
+    else:
+        w = ctx.asarray(weights)
+        w_np = _np.asarray(w)
+        if tuple(w_np.shape) != tuple(Y.shape):
+            raise ValueError(
+                f"least_squares weights must have the codomain shape {tuple(Y.shape)}, "
+                f"got {tuple(w_np.shape)}."
+            )
+        if not _np.all(_np.isfinite(w_np)) or not _np.all(w_np > 0):
+            raise ValueError("least_squares weights must be strictly positive and finite.")
+        W = DiagonalLinOp(w, Y, ctx)
+        Wb = W.apply(b)
+        gram = A.H @ W @ A
+        rhs = A.H.apply(Wb)
+        b_energy = Y.inner(b, Wb)
+
+    # Assemble 1/2 <x, Q x> + <c, x> + a with Q = 2s Gram, c = -2s rhs, a = s energy.
+    Q = gram if two_scale == 1.0 else two_scale * gram
+    linear = InnerProductFunctional(X.scale(-two_scale, rhs), X, ctx)
+    offset = scale * ctx.ops.real(b_energy)
+    return LinOpQuadraticForm(Q, linear, offset, ctx)