spacecore-optimize 0.0.1__py3-none-any.whl

spacecore_optimize/functionals/_proximal.py

@@ -0,0 +1,193 @@
+"""
+Closed-form proximal steps in the space metric.
+
+For diagonal weights, divide each scalar proximal objective by ``w_i`` to obtain
+the Euclidean problem with step ``t / w_i``; other metrics raise.
+Beck, *First-Order Methods in Optimization*, Thm 6.6 and Lemma 6.5.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from spacecore import WeightedInnerProduct
+from spacecore.functional._prox import _soft_threshold, validate_step
+
+
+def _diagonal_weights_or_raise(X: Any, fname: str) -> Any:
+    """Return diagonal weights (``None`` for Euclidean) or raise on a non-diagonal metric."""
+    # Euclidean gives None, diagonal gives its weights, anything else cannot separate.
+    geometry = getattr(X, "geometry", None)
+    if geometry is None:
+        raise TypeError(
+            f"{fname} requires an inner-product space with a geometry; "
+            f"got {type(X).__name__}."
+        )
+    if geometry.is_euclidean:
+        return None
+    if isinstance(geometry, WeightedInnerProduct):
+        return X.ops.real(geometry.weights)
+    raise ValueError(
+        f"{fname} is a separable closed form valid only for Euclidean or diagonal "
+        f"(weighted) metrics; the metric {type(geometry).__name__} is not diagonal, "
+        f"so the subproblem does not separate. Refusing to return a wrong "
+        f"(separable) answer."
+    )
+
+
+def _require_member_shape(X: Any, arr: Any, name: str, fname: str) -> None:
+    """Raise when ``arr`` does not have the coordinate shape of ``X``."""
+    shape = tuple(getattr(arr, "shape", ()))
+    if shape != tuple(X.shape):
+        raise ValueError(
+            f"{fname} {name} must have the space shape {tuple(X.shape)}, got {shape}."
+        )
+
+
+def generalized_shrinkage(
+    X: Any,
+    *,
+    c: Any,
+    x0: Any,
+    eps: float,
+    lam: float = 0.0,
+    nonneg: bool = False,
+) -> Any:
+    r"""
+    Solve ``min_x Re<c, x>_X + eps ||x - x0||_X^2 + lam ||x||_1`` coordinatewise, optionally with ``x >= 0``.
+
+    The smooth minimizer is ``v = x0 - c / (2 eps)``; the l1 term soft-thresholds it
+    with width ``lam / (2 eps w_i)`` for diagonal metric weights ``w``: complete
+    the square, then divide by ``2 eps w_i``. Beck, *First-Order Methods in
+    Optimization*, Sec. 6.2.2 and Lemma 6.5; for complex coordinates, minimizing
+    over phase aligns ``x_i`` with ``v_i`` and leaves the same scalar radius problem.
+
+    Parameters
+    ----------
+    X : Space
+        Euclidean or diagonal-metric space; other metrics raise.
+    c : array-like
+        Metric gradient in ``X``.
+    x0 : array-like
+        Proximal center in ``X``.
+    eps : float
+        Positive quadratic weight.
+    lam : float, optional
+        Non-negative l1 weight; ``0`` disables thresholding.
+    nonneg : bool, optional
+        Constrain to ``x >= 0`` (real spaces only).
+
+    Returns
+    -------
+    Element
+        The minimizer.
+    """
+    # Validate eps, lam, the metric, the shapes, and nonneg on real spaces only.
+    validate_step(eps, X, "generalized_shrinkage eps")
+    validate_step(lam, X, "generalized_shrinkage lam", positive=False)
+
+    weights = _diagonal_weights_or_raise(X, "generalized_shrinkage")
+
+    ops = X.ops
+    c = X.ctx.asarray(c)
+    x0 = X.ctx.asarray(x0)
+    _require_member_shape(X, c, "c", "generalized_shrinkage")
+    _require_member_shape(X, x0, "x0", "generalized_shrinkage")
+    if nonneg and ops.is_complex_dtype(ops.get_dtype(x0)):
+        raise ValueError("generalized_shrinkage(nonneg=True) is defined for real spaces only.")
+
+    # Data step: minimizer of <c, x>_X + eps ||x - x0||^2_X. The metric weight
+    # cancels here precisely because c is a metric gradient.
+    v = x0 - c / (2.0 * eps)
+
+    # Threshold width lam / (2 eps w_i), with w_i = 1 on Euclidean spaces.
+    if weights is None:
+        tau = lam / (2.0 * eps)
+    else:
+        tau = lam / (2.0 * eps * weights)
+
+    # On x >= 0 the l1 term is linear, so the step is a one-sided shift.
+    if nonneg:
+        return ops.maximum(v - tau, ops.zeros_like(v))
+    # Soft-threshold; tau == 0 collapses to the identity v.
+    return _soft_threshold(ops, v, tau)
+
+
+def prox_l1(v: Any, t: Any, X: Any, *, nonneg: bool = False) -> Any:
+    r"""
+    Prox of ``t ||.||_1`` in the space metric: soft-threshold with width ``t / w_i``.
+
+    Parameters
+    ----------
+    v : array-like
+        Point in ``X``.
+    t : float
+        Non-negative threshold.
+    X : Space
+        Euclidean or diagonal-metric space.
+    nonneg : bool, optional
+        Constrain to ``x >= 0``, giving ``max(v_i - t / w_i, 0)``; at ``t = 0`` this is
+        :func:`project_nonneg` (Beck, *First-Order Methods in Optimization*, Lemma 6.5).
+
+    Returns
+    -------
+    Element
+        The thresholded point; divide each scalar objective by ``w_i`` to apply
+        Beck, *First-Order Methods in Optimization*, Example 6.8.
+    """
+    # prox of t ||.||_1 = shrinkage with c = 0, x0 = v, eps = 1/2.
+    validate_step(t, X, "prox_l1", positive=False)
+    v = X.ctx.asarray(v)
+    _require_member_shape(X, v, "v", "prox_l1")
+    return generalized_shrinkage(X, c=X.zeros(), x0=v, eps=0.5, lam=t, nonneg=nonneg)
+
+
+def prox_l2sq(v: Any, t: Any, X: Any, *, nonneg: bool = False) -> Any:
+    r"""
+    Prox of ``(t / 2) ||.||_X^2``: the shrinkage ``v / (1 + t)``.
+
+    Parameters
+    ----------
+    v : array-like
+        Point in ``X``.
+    t : float
+        Non-negative step size.
+    X : Space
+        Euclidean or diagonal-metric space.
+    nonneg : bool, optional
+        Constrain to ``x >= 0``, giving ``max(v, 0) / (1 + t)``.
+
+    Returns
+    -------
+    Element
+        The shrunk point; cancel ``w_i`` in the scalar quadratic optimality equation.
+        Beck, *First-Order Methods in Optimization*, Sec. 6.2.3.
+    """
+    # prox of (t/2) ||.||^2 = shrinkage with c = -v, x0 = 0, eps = (1 + t) / 2.
+    validate_step(t, X, "prox_l2sq", positive=False)
+    v = X.ctx.asarray(v)
+    _require_member_shape(X, v, "v", "prox_l2sq")
+    return generalized_shrinkage(
+        X, c=-v, x0=X.zeros(), eps=0.5 * (1.0 + t), lam=0.0, nonneg=nonneg
+    )
+
+
+def project_nonneg(v: Any, X: Any) -> Any:
+    r"""
+    Project onto ``x >= 0`` in the space metric: coordinatewise ``max(v, 0)``.
+
+    Parameters
+    ----------
+    v : array-like
+        Point in ``X``.
+    X : Space
+        Euclidean or diagonal-metric space.
+
+    Returns
+    -------
+    Element
+        ``max(v, 0)``; positive diagonal weights do not change each scalar minimizer.
+        Beck, *First-Order Methods in Optimization*, Lemma 6.5 (``mu = 0``).
+    """
+    v = X.ctx.asarray(v)
+    _require_member_shape(X, v, "v", "project_nonneg")
+    return generalized_shrinkage(X, c=X.zeros(), x0=v, eps=0.5, lam=0.0, nonneg=True)

spacecore_optimize/functionals/_realified.py

@@ -0,0 +1,166 @@
+r"""
+Real-coordinate view of a complex-domain functional.
+
+For real-valued ``F`` with metric gradient ``g`` and ``v = a + i b``, the real
+gradient is ``(Re g_v, Im g_v)`` where ``g_v = flatten(X.riesz(g))``. The view
+writes that bookkeeping once: ``DF[h] = Re(g_v^H flatten(h))`` gives the stacked
+partials. Kreutz-Delgado, *The Complex Gradient Operator and the CR-Calculus*,
+arXiv:0906.4835, Eqs. (51), (55)-(56); SpaceCore's ``g`` is twice that paper's
+complex gradient. Stacking is an isometry to this Euclidean view when ``X`` is
+Euclidean; a non-Euclidean ``X`` requires the displayed Riesz conversion.
+"""
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+from spacecore import (
+    Context,
+    CoordinateSpace,
+    DenseCoordinateSpace,
+    Functional,
+    checked_method,
+)
+
+
+class RealifiedFunctional(Functional):
+    r"""
+    View of a complex-domain functional over stacked real coordinates ``(Re v, Im v)``.
+
+    The real gradient is :math:`(\operatorname{Re} g_v, \operatorname{Im} g_v)` with
+    :math:`g_v = \operatorname{flatten}(X.\operatorname{riesz}(g))`.
+
+    Parameters
+    ----------
+    base : Functional
+        Functional on a complex :class:`~spacecore.space.CoordinateSpace`.
+
+    Raises
+    ------
+    TypeError
+        If the base domain is not a coordinate space.
+    ValueError
+        If the base domain is already real.
+
+    Notes
+    -----
+    :class:`~spacecore.HermitianSpace` stores complex entries but is a real space of
+    dimension :math:`n^2` (``n`` real diagonal entries and two real coordinates per
+    off-diagonal pair). Its stacked representation still has Hermitian constraints;
+    this view does not supply an unconstrained extension of the functional.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.complex128)
+    >>> X = sc.DenseCoordinateSpace((2,), ctx=ctx)
+    >>> F = sc.SquaredL2NormFunctional(X)
+    >>> R = spo.realify(F)
+    >>> R.domain.shape
+    (4,)
+    >>> float(R.value(R.to_real(ctx.asarray([3.0 + 4.0j, 0.0]))))
+    12.5
+    """
+
+    _fields = ("base",)
+    _dynamic = ("base",)
+
+    def __init__(self, base: Functional) -> None:
+        # Only complex coordinate spaces can be split into real and imaginary parts.
+        X = base.domain
+        if not isinstance(X, CoordinateSpace):
+            raise TypeError(
+                "RealifiedFunctional requires a CoordinateSpace domain; "
+                f"got {type(X).__name__}."
+            )
+        if X.field == "real":
+            raise ValueError(
+                "The base functional already has a real domain; use it directly."
+            )
+        ops = X.ops
+        # check_level is a property of the bound object, not of the Context, so
+        # it is threaded through the constructors rather than the context.
+        # The view's domain: real coordinates of twice the size.
+        real_ctx = Context(ops, dtype=ops.real_dtype(X.dtype))
+        dom = DenseCoordinateSpace(
+            (2 * X.size,), real_ctx, check_level=X.check_level
+        )
+        super().__init__(dom, real_ctx, check_level=X.check_level)
+        self.base = base
+        self.complex_space = X
+
+    def to_real(self, y: Any) -> Any:
+        """Flatten a base-domain element into stacked real coordinates."""
+        ops = self.ops
+        v = self.complex_space.flatten(y)
+        return ops.concatenate([ops.real(v), ops.imag(v)])
+
+    def from_real(self, w: Any) -> Any:
+        """Rebuild a base-domain element from stacked real coordinates."""
+        m = self.complex_space.size
+        v = w[:m] + 1j * w[m:]
+        return self.complex_space.unflatten(self.complex_space.ctx.asarray(v))
+
+    # Output-only: the input is validated by ``base.value`` against the *complex*
+    # domain after ``from_real``, so an ``in_space`` here would check ``w``
+    # against the wrong space.
+    @checked_method(out_space="codomain")
+    def value(self, w: Any, *args: Any, **kwargs: Any) -> Any:
+        """Return ``base.value`` at the complex element ``w`` encodes."""
+        return self.base.value(self.from_real(w), *args, **kwargs)
+
+    def grad(self, w: Any, *args: Any, **kwargs: Any) -> Any:
+        """Return the stacked real gradient ``(Re g_v, Im g_v)``."""
+        return self.value_and_grad(w, *args, **kwargs)[1]
+
+    def value_and_grad(self, w: Any, *args: Any, **kwargs: Any) -> Tuple[Any, Any]:
+        """Return ``(value, stacked real gradient)`` from one fused base evaluation.
+
+        ``riesz`` maps the base's metric gradient back to coordinates before the
+        real/imaginary split; skipping it would silently return the wrong vector
+        on any non-Euclidean geometry.
+        """
+        X, ops = self.complex_space, self.ops
+        # Evaluate the base at v = a + i b, then stack Re and Im of its coordinate gradient.
+        val, g = self.base.value_and_grad(self.from_real(w), *args, **kwargs)
+        gv = X.flatten(X.riesz(g))
+        return val, ops.concatenate([ops.real(gv), ops.imag(gv)])
+
+    def _convert(self, new_ctx: Context) -> "RealifiedFunctional":
+        """Convert the wrapped functional to ``new_ctx`` and re-derive the view.
+
+        ``new_ctx`` describes the *real view*, so the base must be converted to
+        the matching **complex** dtype — passing the real context straight
+        through would make the base's domain real and the view impossible to
+        rebuild. The pairing comes from ``ops.complex_dtype`` because it is not
+        portable to derive: NumPy promotes ``float32`` against a Python complex
+        to ``complex128``, JAX and Torch to ``complex64``.
+        """
+        ops = new_ctx.ops
+        base_ctx = Context(ops, dtype=ops.complex_dtype(new_ctx.dtype))
+        return RealifiedFunctional(self.base.convert(base_ctx))
+
+def realify(F: Functional) -> Functional:
+    """
+    Return ``F`` unchanged on a real domain, realified on a complex one.
+
+    The idempotent entry point: calling it on an already-real functional is a
+    no-op rather than an error, so a caller preparing an objective for a
+    real-only optimizer need not branch on the field.
+
+    Parameters
+    ----------
+    F : Functional
+        Functional on a real or complex coordinate space.
+
+    Returns
+    -------
+    Functional
+        ``F`` itself when its domain is real, else a :class:`RealifiedFunctional`
+        over stacked real coordinates.
+    """
+    if F.domain.field == "real":
+        return F
+    return RealifiedFunctional(F)
+

spacecore_optimize/functionals/_spectral.py

@@ -0,0 +1,226 @@
+"""
+Spectral lift ``F(X) = f(lambda(X))`` of a symmetric coordinate functional.
+
+For real-valued symmetric ``f`` differentiable at the spectrum of a Hermitian ``X``,
+the Frobenius gradient is ``from_spectrum(grad f(lambda), frame)``.
+Lewis, "Derivatives of Spectral Functions", 1996, Thm 1.1 (convex subgradients: Thm 1.3).
+"""
+from __future__ import annotations
+
+from typing import Any, cast
+
+from spacecore import (
+    CheckLevel,
+    Context,
+    DenseCoordinateSpace,
+    Functional,
+    JordanAlgebraSpace,
+    LpNormFunctional,
+    checked_method,
+)
+from spacecore.functional._base import Domain
+from spacecore.functional.tools._coordinate import _CoordinateFunctional
+
+
+def eigenvalue_space(dom: Any, check_level: CheckLevel | None = None) -> Any:
+    r"""
+    Return the real Euclidean space of shape ``(rank,)`` that the spectrum of ``dom`` lives in.
+
+    Hermitian eigenvalues are real even with complex entries (Horn & Johnson,
+    *Matrix Analysis*, 2nd ed., Thm 4.1.5). Other domains must supply a real
+    spectrum for this helper; the rank is read off the zero element.
+
+    Parameters
+    ----------
+    dom : JordanAlgebraSpace
+        Domain whose spectrum is modelled.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level; ``dom``'s by default.
+
+    Returns
+    -------
+    DenseCoordinateSpace
+        The eigenvalue space.
+    """
+    # The rank is the length of the spectrum of the zero element.
+    if not isinstance(dom, JordanAlgebraSpace):
+        raise TypeError(
+            "eigenvalue_space requires a Jordan-algebra domain with a spectral "
+            f"decomposition; got {type(dom).__name__}."
+        )
+    ops = dom.ops
+    rank = int(dom.spectrum(dom.zeros()).shape[0])
+    real_ctx = Context(ops, dtype=ops.real_dtype(dom.dtype))
+    level = dom.check_level if check_level is None else check_level
+    return DenseCoordinateSpace((rank,), real_ctx, check_level=level)
+
+
+class SpectralFunctional(_CoordinateFunctional[Domain]):
+    r"""
+    Lift a symmetric coordinate functional onto a Jordan spectrum: :math:`F(X) = f(\lambda(X))`.
+
+    ``LpNormFunctional`` lifts to the Schatten norm and ``NegativeEntropyFunctional`` to
+    the negative von Neumann entropy on positive trace-one matrices.
+    Horn & Johnson, *Matrix Analysis*, 2nd ed., Thm 7.4.7.2; for Hermitian matrices
+    the singular values are the absolute eigenvalues, so the gauge is the p-norm.
+
+    .. warning::
+
+        The gradient formula requires permutation-invariant ``f`` and differentiability
+        at ``lambda(X)`` (or a convex subgradient). Lewis, "Derivatives of Spectral
+        Functions", Thms 1.1 and 1.3. Permutation invariance is not checked; a generic
+        :class:`~spacecore_optimize.KLDivergenceFunctional` with unequal targets fails it.
+        Elementwise spaces reduce to coordinate differentiation; custom Jordan spaces
+        must supply a compatible spectral-gradient reconstruction.
+
+    Parameters
+    ----------
+    dom : JordanAlgebraSpace
+        Domain with a spectral decomposition, e.g. :class:`~spacecore.HermitianSpace`.
+    base : Functional
+        Symmetric functional on the ``(rank,)`` eigenvalue space; see :func:`eigenvalue_space`.
+    ctx : Context, str, or None, optional
+        Backend context; resolved from ``dom`` when omitted.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.HermitianSpace(2, ctx=ctx)
+    >>> S = spo.eigenvalue_space(X)
+    >>> vn = spo.SpectralFunctional(X, spo.NegativeEntropyFunctional(S))
+    >>> rho = ctx.asarray([[0.5, 0.0], [0.0, 0.5]])   # maximally mixed state
+    >>> float(vn.value(rho))                          # -log 2, i.e. sum p log p
+    -0.6931471805599453
+    """
+
+    _fields = ("dom", "base", "ctx")
+    _dynamic = ("base",)
+
+    def __init__(
+        self,
+        dom: Domain,
+        base: Functional,
+        ctx: Context | str | None = None,
+        check_level: CheckLevel | None = None,
+    ) -> None:
+        super().__init__(dom, ctx, check_level=check_level)
+        # Check the domain has a spectrum and base lives on its eigenvalue space.
+        domain = cast(Any, self.domain)
+        if not isinstance(domain, JordanAlgebraSpace):
+            raise TypeError(
+                "SpectralFunctional requires a Jordan-algebra domain with a "
+                f"spectral decomposition (e.g. HermitianSpace); got "
+                f"{type(domain).__name__}."
+            )
+        if not isinstance(base, Functional):
+            raise TypeError(f"base must be a Functional, got {type(base).__name__}.")
+        expected = eigenvalue_space(domain)
+        if base.domain.shape != expected.shape:
+            raise ValueError(
+                f"base domain shape {base.domain.shape} does not match the "
+                f"spectrum of {type(domain).__name__} (rank {expected.shape[0]}); "
+                f"build it on eigenvalue_space(dom)."
+            )
+        # Lewis's formula needs the plain coordinate gradient of f.
+        if not getattr(base.domain, "is_euclidean", True):
+            # Lewis needs the EUCLIDEAN gradient of f. On a Euclidean eigenvalue
+            # space base.grad already is that; under any other metric it would be
+            # G^-1 df, silently scaling the reconstructed spectral gradient.
+            raise ValueError(
+                "SpectralFunctional requires a Euclidean eigenvalue space so that "
+                "base.grad is the plain coordinate gradient Lewis's formula needs."
+            )
+        self.base = base
+
+    @checked_method(in_space="domain", out_space="codomain")
+    def value(self, x: Any) -> Any:
+        """Return ``f(lambda(x))``."""
+        return self.base.value(cast(Any, self.domain).spectrum(x))
+
+    def _coordinate_grad(self, x: Any) -> Any:
+        """Return the spectral gradient (Lewis, "Derivatives of Spectral Functions", Thm 1.1)."""
+        domain = cast(Any, self.domain)
+        eigvals, frame = domain.spectral_decompose(x)
+        return domain.from_spectrum(self.base.grad(eigvals), frame)
+
+def spectralize(
+    dom: Domain,
+    make_base: Any,
+    ctx: Context | str | None = None,
+    check_level: CheckLevel | None = None,
+) -> "SpectralFunctional[Domain]":
+    r"""
+    Build the spectral lift of ``make_base(eigenvalue_space(dom))`` on ``dom``.
+
+    Parameters
+    ----------
+    dom : JordanAlgebraSpace
+        Domain with a spectral decomposition.
+    make_base : callable
+        ``make_base(eigenvalue_space) -> Functional``, symmetric.
+    ctx : Context, str, or None, optional
+        Backend context.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level.
+
+    Returns
+    -------
+    SpectralFunctional
+        ``f(lambda(.))`` on ``dom``.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.HermitianSpace(2, ctx=ctx)
+    >>> vn = spo.spectralize(X, spo.NegativeEntropyFunctional)   # negative von Neumann entropy
+    >>> float(vn.value(ctx.asarray([[0.5, 0.0], [0.0, 0.5]])))
+    -0.6931471805599453
+    """
+    base = make_base(eigenvalue_space(dom, check_level=check_level))
+    return SpectralFunctional(dom, base, ctx, check_level=check_level)
+
+
+def NuclearNormFunctional(
+    dom: Domain,
+    ctx: Context | str | None = None,
+    check_level: CheckLevel | None = None,
+) -> "SpectralFunctional[Domain]":
+    r"""
+    Nuclear norm ``sum_i |lambda_i(X)|``, i.e. the Schatten-1 lift of the 1-norm.
+
+    Parameters
+    ----------
+    dom : JordanAlgebraSpace
+        Domain with a spectral decomposition.
+    ctx : Context, str, or None, optional
+        Backend context; resolved from ``dom`` when omitted.
+    check_level : {"none", "cheap", "standard", "strict"}, optional
+        Validation level.
+
+    Returns
+    -------
+    SpectralFunctional
+        The Schatten-1 lift.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import spacecore as sc
+    >>> import spacecore_optimize as spo
+    >>> ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+    >>> X = sc.HermitianSpace(2, ctx=ctx)
+    >>> f = spo.NuclearNormFunctional(X)
+    >>> float(f.value(ctx.asarray([[2.0, 0.0], [0.0, -3.0]])))
+    5.0
+    """
+    return spectralize(
+        dom, lambda s: LpNormFunctional(s, 1.0), ctx, check_level=check_level
+    )

spacecore_optimize-0.0.1.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: spacecore-optimize
+Version: 0.0.1
+Summary: Optimization on top of SpaceCore: SciPy and optax adapters, and a catalogue of functionals and proximal steps.
+Author: Pavlo Pelikh
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://pavlo3p.github.io/spacecore-optimize/
+Project-URL: Source, https://github.com/Pavlo3P/spacecore-optimize
+Project-URL: SpaceCore, https://github.com/Pavlo3P/SpaceCore
+Project-URL: Changelog, https://github.com/Pavlo3P/spacecore-optimize/blob/main/CHANGELOG.md
+Keywords: optimization,proximal,scipy,optax,spacecore
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: spacecore>=0.5.0
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: scipy>=1.17
+Provides-Extra: optax
+Requires-Dist: jax>=0.9.1; extra == "optax"
+Requires-Dist: optax>=0.2; extra == "optax"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
+Dynamic: license-file
+
+# spacecore-optimize
+
+Optimization on top of [SpaceCore](https://github.com/Pavlo3P/SpaceCore). SpaceCore supplies
+spaces, geometry, operators, functionals and proximal steps; this package hands them to
+external optimizers and adds a catalogue of common objectives.
+
+The one rule it enforces: an optimizer that works on flat coordinates gets the gradient as
+the covector `X.riesz(F.grad(x))`, not the Riesz gradient `F.grad(x)`. On a Euclidean space
+the two coincide; on a weighted or operator geometry only the covector is the derivative
+with respect to the coordinates SciPy and optax update.
+
+## Install
+
+```bash
+pip install spacecore-optimize            # SciPy adapters and functionals
+pip install "spacecore-optimize[optax]"   # plus minimize_optax (JAX backend)
+```
+
+Requires Python 3.11+ and SpaceCore 0.5.0+.
+
+## Example
+
+Least squares on a space with a weighted inner product:
+
+```python
+import numpy as np
+import spacecore as sc
+import spacecore_optimize as spo
+
+ctx = sc.Context(sc.NumpyOps(), dtype=np.float64)
+X = sc.DenseCoordinateSpace((3,), ctx, geometry=sc.WeightedInnerProduct(ctx.asarray([1.0, 4.0, 9.0])))
+Y = sc.DenseCoordinateSpace((5,), ctx)
+rng = np.random.default_rng(0)
+A = sc.DenseLinOp(ctx.asarray(rng.standard_normal((5, 3))), X, Y, ctx)
+b = ctx.asarray(rng.standard_normal(5))
+
+F = spo.least_squares(A, b)                 # 1/2 ||A x - b||^2
+result = spo.minimize_scipy(F, X.zeros())   # scipy.optimize.minimize, L-BFGS-B
+x = result.x_element                        # the minimizer, an element of X
+```
+
+## What is in it
+
+| Name | What it does |
+|---|---|
+| `minimize_scipy`, `line_search_scipy` | Run `scipy.optimize.minimize` / `line_search` on a SpaceCore `Functional`. |
+| `minimize_optax`, `OptaxResult` | A compiled optax loop on a JAX-backed domain, stopping on the dual gradient norm. |
+| `least_squares` | `scale * ‖A x − b‖²` as a quadratic form, optionally weighted. |
+| `NegativeEntropyFunctional`, `KLDivergenceFunctional`, `HuberFunctional` | Coordinate objectives whose gradients follow the domain geometry. |
+| `SpectralFunctional`, `spectralize`, `eigenvalue_space`, `NuclearNormFunctional` | Spectral functions on Jordan-algebra spaces such as Hermitian matrices. |
+| `RealifiedFunctional`, `realify` | A complex-domain functional seen on stacked real coordinates. |
+| `generalized_shrinkage`, `prox_l1`, `prox_l2sq`, `project_nonneg` | Closed-form proximal steps in diagonal geometry. |
+
+The norms covered by SpaceCore's own prox rules (`LpNormFunctional`,
+`SquaredL2NormFunctional`, `L1NormFunctional`) live in SpaceCore.
+
+## Documentation
+
+Published at https://pavlo3p.github.io/spacecore-optimize/. To build locally:
+
+```bash
+pip install -e ".[docs]"
+sphinx-build -W docs docs/_build/html
+```
+
+## License
+
+Apache-2.0.