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.
