Metadata-Version: 2.4
Name: spacecore
Version: 0.1.4
Summary: Backend-agnostic vector spaces and linear operators.
Author: Pavlo Pelikh
License-Expression: Apache-2.0
Keywords: linear-algebra,jax,pytorch,numpy,operators,spaces
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: numpy>=2.0.0
Requires-Dist: scipy>=1.17
Provides-Extra: jax
Requires-Dist: jax>=0.9.1; extra == "jax"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.8; extra == "examples"
Requires-Dist: optax>=0.2; extra == "examples"
Provides-Extra: docs
Requires-Dist: sphinx>=8.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-design>=0.6; extra == "docs"
Requires-Dist: numpydoc>=1.8; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# SpaceCore

SpaceCore is a lightweight backend-agnostic library for working with vector spaces and linear operators.

It provides a small set of abstractions for:

- backend-aware numerical operations
- contexts carrying backend and dtype information
- structured vector spaces
- structured linear operators
- conversion between compatible contexts

## Installation

Base install:

```bash
pip install spacecore
```

With JAX support:

```bash
pip install "spacecore[jax]"
```

With PyTorch support:

```bash
pip install "spacecore[torch]"
```

* `spacecore[jax]`: installs optional JAX support.
* GPU users should install the appropriate CUDA-enabled JAX build first, following the official JAX installation guide.
* `spacecore[torch]`: installs optional PyTorch support for `torch.Tensor` backends.
* GPU users should install the appropriate CUDA-enabled PyTorch build first, following the official PyTorch installation guide.

## Main concepts

### `Context`

A `Context` specifies how objects are represented, in particular:

* backend (`NumPy`, `JAX`, `PyTorch`, etc.)
* dtype
* validation/conversion behavior

Constructors resolve contexts in priority order: explicit `ctx=...`, then
contexts inferred from inputs, then the global default context. Advanced code
that needs this resolution step directly can call
`spacecore.resolve_context_priority(...)`.

### `Space`

A `Space` describes the structure of objects space, for example:

* `VectorSpace` - Euclidean space
* `HermitianSpace` - space of Hermitian (symmetric) matrices 
* `ProductSpace` - Cartesian product of spaces

### `LinOp`

A `LinOp` represents a linear operator between spaces, for example:

* `DenseLinOp` - linear operator represented by dense matrix
* `SparseLinOp` - linear operator represented by sparse matrix
* `BlockDiagonalLinOp` - linear operator from $X_1 \times \dots \times X_k$ to $Y_1 \times \dots \times Y_k$
* `StackedLinOp` - linear operator from $X$ to $Y_1 \times \dots \times Y_k$
* `SumToSingleLinOp` - linear operator from $X_1 \times \dots \times X_k$ to $Y$

## Minimal example

```python
import numpy as np
import spacecore as sc

sc.set_context('numpy', dtype='float64')

X = sc.VectorSpace((3,))
Y = sc.VectorSpace((2,))

A = np.array(
    [[1.0, 2.0, 3.0],
     [0.0, 1.0, 0.0]]
)
linop = sc.DenseLinOp(
    A,
    dom=X,
    cod=Y,
)

x = X.ctx.asarray([1.0, 0.0, -1.0])
y = linop.apply(x)

print(y)
```

PyTorch tensors can be used by selecting the `torch` backend:

```python
import torch
import spacecore as sc

ctx = sc.Context(sc.TorchOps(), dtype=torch.float64)
X = sc.VectorSpace((3,), ctx)
x = ctx.asarray([1.0, 2.0, 3.0])

print(X.inner(x, x))
```

## Status

SpaceCore is currently experimental and under active development.
The public API may still evolve.

## Tutorials

See the Sphinx documentation under `docs/source/` for tutorials, design notes,
API reference, and release notes.

## Documentation

The documentation website is built with Sphinx from `docs/source`.

Install the documentation dependencies:

```bash
pip install -e ".[docs]"
```

Build the local HTML documentation:

```bash
sphinx-build -b html docs/source docs/build/html
```

## License

Apache License 2.0
