Metadata-Version: 2.4
Name: spacecore
Version: 0.1.1
Summary: Backend-agnostic vector spaces and linear operators.
Author: Pavlo Pelikh
License-Expression: Apache-2.0
Keywords: linear-algebra,jax,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: 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]"
```

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

## Main concepts

### `Context`

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

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

### `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)
```

## Status

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

## Tutorials

See the `tutorials/` directory for usage examples and design guidance.

## License

Apache License 2.0
