Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/build-and-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,10 @@ jobs:
CIBW_ENVIRONMENT_WINDOWS: "CMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake SKBUILD_CMAKE_ARGS=-DSDE_WARNINGS_AS_ERRORS=ON"
# Bundle openblas.dll into the wheel (auditwheel/delocate handle this on Linux/macOS)
CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair -w {dest_dir} {wheel} --add-path C:/vcpkg/installed/x64-windows/bin"
# On free-threaded builds, assert the import did not re-enable the GIL.
CIBW_TEST_COMMAND: python -c "import sys, sysconfig, sparsediffpy; ft = bool(sysconfig.get_config_var('Py_GIL_DISABLED')); assert not ft or not sys._is_gil_enabled(), 'GIL re-enabled on import'; print('freethreaded_build=', ft)"
# On free-threaded builds, assert the import did not re-enable the GIL,
# then run the test suite against the installed wheel.
CIBW_TEST_REQUIRES: pytest
CIBW_TEST_COMMAND: python -c "import sys, sysconfig, sparsediffpy; ft = bool(sysconfig.get_config_var('Py_GIL_DISABLED')); assert not ft or not sys._is_gil_enabled(), 'GIL re-enabled on import'; print('freethreaded_build=', ft)" && pytest {project}/tests -q
- name: Check wheels
shell: bash
run: |
Expand Down
108 changes: 105 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,121 @@
# SparseDiffPy

Python bindings for [SparseDiffEngine](https://github.com/SparseDifferentiation/SparseDiffEngine), a C library for computing sparse Jacobians and Hessians.
Sparse Jacobians and Hessians of nonlinear expressions, computed by
[SparseDiffEngine](https://github.com/SparseDifferentiation/SparseDiffEngine),
a C library that works out the sparsity pattern once and then only computes
the structural nonzeros. Results are `scipy.sparse.csr_matrix`.

## Installation

```bash
pip install sparsediffpy
```

## Usage
From source: `git clone --recursive https://github.com/SparseDifferentiation/SparseDiffPy && pip install -e SparseDiffPy`.

## Quick start

```python
import numpy as np
import sparsediffpy as sp

scope = sp.Scope() # owns the flat variable vector
x = scope.Variable(3, 1) # shapes are always 2-D: (rows, cols)

f = sp.exp(x) + 2.0 * x # build an expression with operators and sp.* atoms
fn = sp.compile(f) # analyze sparsity once

x.value = [1.0, 2.0, 3.0]
print(fn.forward()) # [[4.718] [11.389] [26.086]], shaped like f
print(fn.jacobian().toarray()) # diag(exp(x) + 2), a 3x3 csr_matrix
print(fn.hessian(np.ones(3))) # Hessian of w' f(x) for weights w
```

`forward()` has the shape of `f`, `jacobian()` has shape `(f.size, n_vars)`
and `hessian(w)` has shape `(n_vars, n_vars)`, where `n_vars` is the total
size of all variables in the scope, in declaration order. Values must have
the exact shape of what they set: `x.value` takes an array shaped like `x`,
`hessian(w)` takes `w` shaped like `f` (for vectors a 1-D array also works),
and flat vectors such as `scope.set_values(u)` must be 1-D. Flat vectors (the
rows of the Jacobian, the scope values) are column-major.

**Parameters** are data you can change without recompiling:

```python
from sparsediffpy import _sparsediffengine
import numpy as np
import sparsediffpy as sp

scope = sp.Scope()
x = scope.Variable(3, 1)
A = scope.Parameter(2, 3, value=np.ones((2, 3)))
fn = sp.compile(sp.sin(A @ x))

x.value = [0.1, 0.2, 0.3]
J1 = fn.jacobian()
A.value = np.arange(6.0).reshape(2, 3) # no recompile needed
J2 = fn.jacobian()
```

## Using it in a solver

`sp.Problem(objective, constraints)` exposes the callbacks NLP solvers ask for:
objective value and gradient, constraint values and Jacobian, and the Lagrangian
Hessian `obj_factor * H_f + sum_i lagrange_i * H_gi`. A stage runs in the engine
only when its point changed: a forward called again with the same `u` (or with
unchanged scope values and parameters) returns the cached result, and
`gradient()`/`jacobian()` are reused until the matching forward moves. Returned
arrays are owned by the problem, so do not modify them in place. Here it drives SciPy:

```python
import numpy as np
from scipy.optimize import NonlinearConstraint, minimize

import sparsediffpy as sp

# minimize sum(exp(x) - c * x) subject to ||x||^2 <= 1
scope = sp.Scope()
x = scope.Variable(4, 1)
c = np.array([[1.0], [2.0], [3.0], [4.0]]) # constants are 2-D, like variables
prob = sp.Problem(sp.sum(sp.exp(x) - c * x), [sp.sum(x ** 2)])

def grad(u):
prob.objective_forward(u)
return prob.gradient()

def obj_hess(u): # the Lagrangian Hessian needs both forwards at u (cached if done)
prob.objective_forward(u); prob.constraint_forward(u)
return prob.hessian(1.0, [0.0])

def con_jac(u):
prob.constraint_forward(u)
return prob.jacobian()

def con_hess(u, v):
prob.objective_forward(u); prob.constraint_forward(u)
return prob.hessian(0.0, v)

con = NonlinearConstraint(prob.constraint_forward, -np.inf, 1.0,
jac=con_jac, hess=con_hess)
res = minimize(prob.objective_forward, np.zeros(4), jac=grad, hess=obj_hess,
method="trust-constr", constraints=con)
print(res.x) # approx. [0. 0.289 0.549 0.784], on the boundary ||x|| = 1
```

## Supported operations

- **Operators:** `+ - * @ **`, `/` by a constant, `.T`, and indexing with ints, slices and integer lists: `x[1:3]` on a
vector, `X[0, :]` or `X[[0, 2], 1]` on a matrix (a matrix always takes two indices).
Scalars, rows and columns broadcast. NumPy arrays and `scipy.sparse` matrices are accepted as
constants; like every expression they must be 2-D, so pass `a[:, None]` or `a[None, :]` for a 1-D `a`.
- **Elementwise:** `sin cos tan exp log sinh tanh asinh atan atanh logistic normal_cdf entr xexp power atan2`.
- **Affine:** `sum prod reshape broadcast hstack vstack trace diag_vec index_flat`.
- **Other:** `quad_form quad_over_lin rel_entr`.

`log`, `tan`, `atanh`, `entr`, `atan2`, `rel_entr`, `quad_over_lin` and `prod`
currently need plain Variables as arguments (an engine limitation).

The low-level C bindings remain available as `sparsediffpy._sparsediffengine`.

## Free-threaded Python

Wheels are published for free-threaded CPython 3.14 (`cp314t`) as well as the
Expand Down
1 change: 1 addition & 0 deletions conda.recipe/recipe.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ requirements:
run:
- python
- numpy >=2
- scipy

tests:
- python:
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ name = "sparsediffpy"
version = "0.9.0"
description = "Python bindings for SparseDiffEngine algorithmic differentiation"
requires-python = ">=3.11"
dependencies = ["numpy >= 2.0.0"]
dependencies = ["numpy >= 2.0.0", "scipy"]
license = "Apache-2.0"

[project.readme]
Expand Down
9 changes: 9 additions & 0 deletions sparsediffpy/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,12 @@
"""

from sparsediffpy import _sparsediffengine # noqa: F401
from sparsediffpy._expression import ( # noqa: F401
DimensionError, Expression, Parameter, Scope, Variable, broadcast, index_flat,
)
from sparsediffpy._atoms import ( # noqa: F401
asinh, atan, atan2, atanh, cos, diag_vec, entr, exp, hstack, log, logistic,
normal_cdf, power, prod, quad_form, quad_over_lin, rel_entr, reshape, sin,
sinh, sum, tan, tanh, trace, vstack, xexp,
)
from sparsediffpy._compile import CompiledExpression, Problem, compile # noqa: F401
189 changes: 189 additions & 0 deletions sparsediffpy/_atoms.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
"""Named functions: elementwise atoms, reductions, stacking, and special forms."""

import numpy as np
import scipy.sparse as sps

from sparsediffpy import _sparsediffengine as _C
from sparsediffpy._expression import (
Constant, Node, Parameter, Variable, _check_shape, _check_symmetric,
cast_to_const,
)


def _require_variables(name, *xs):
"""Restricted-domain atoms in the engine only accept plain Variables."""
if not all(isinstance(x, Variable) for x in xs):
raise ValueError(f"{name} cannot be applied directly to a composite "
"expression; its arguments must be plain Variables")
if len(xs) == 2 and xs[0] is xs[1]:
raise ValueError(f"{name}: arguments must be distinct Variables")


def _elementwise(make, name, restricted=False):
"""Make the elementwise atom ``name`` from its engine constructor.

A restricted atom (domain not all of R) only accepts a plain Variable.
"""
def atom(x):
x = cast_to_const(x)
if restricted:
_require_variables(name, x)
return Node(make, [x], x.shape)
atom.__name__ = atom.__qualname__ = name
atom.__doc__ = f"Elementwise {name}."
return atom


sin = _elementwise(_C.make_sin, "sin")
cos = _elementwise(_C.make_cos, "cos")
tan = _elementwise(_C.make_tan, "tan", restricted=True)
exp = _elementwise(_C.make_exp, "exp")
log = _elementwise(_C.make_log, "log", restricted=True)
sinh = _elementwise(_C.make_sinh, "sinh")
tanh = _elementwise(_C.make_tanh, "tanh")
asinh = _elementwise(_C.make_asinh, "asinh")
atanh = _elementwise(_C.make_atanh, "atanh", restricted=True)
atan = _elementwise(_C.make_atan, "atan")
logistic = _elementwise(_C.make_logistic, "logistic")
normal_cdf = _elementwise(_C.make_normal_cdf, "normal_cdf")
entr = _elementwise(_C.make_entr, "entr", restricted=True)
xexp = _elementwise(_C.make_xexp, "xexp")


def power(x, p):
"""Elementwise x ** p for a constant exponent p."""
return cast_to_const(x) ** p


def atan2(y, x):
"""Elementwise atan2(y, x) for distinct Variables of the same shape."""
_require_variables("atan2", y, x)
if y.shape != x.shape:
raise ValueError(f"atan2: shape mismatch {y.shape} vs {x.shape}")
return Node(_C.make_atan2, [y, x], y.shape)


def _reduction_shape(x, axis):
"""Output shape of sum/prod. The engine always returns a row vector."""
d1, d2 = x.shape
shapes = {None: (1, 1), 0: (1, d2), 1: (1, d1)}
if axis not in shapes:
raise ValueError(f"Invalid axis {axis}, must be None, 0, or 1")
return shapes[axis]


def sum(x, axis=None):
"""Sum of entries: axis=None -> (1, 1), axis=0 -> (1, d2), axis=1 -> (1, d1)."""
x = cast_to_const(x)
shape = _reduction_shape(x, axis)
c_axis = -1 if axis is None else axis
return Node(lambda c: _C.make_sum(c, c_axis), [x], shape)


def prod(x, axis=None):
"""Product of entries; shapes as for :func:`sum`. ``x`` must be a Variable."""
if not isinstance(x, Variable):
raise ValueError("prod requires its argument to be a plain Variable "
"(the engine has no chain rule for prod yet)")
shape = _reduction_shape(x, axis)
make = {None: _C.make_prod, 0: _C.make_prod_axis_zero,
1: _C.make_prod_axis_one}[axis]
return Node(make, [x], shape)


def reshape(x, d1, d2):
"""Column-major reshape."""
x, shape = cast_to_const(x), _check_shape(d1, d2)
if x.size != shape[0] * shape[1]:
raise ValueError(f"Cannot reshape {x.shape} to {shape}")
return Node(lambda c: _C.make_reshape(c, *shape), [x], shape)


def trace(x):
"""Sum of the diagonal of a square matrix, as a (1, 1) expression."""
x = cast_to_const(x)
if x.shape[0] != x.shape[1]:
raise ValueError(f"trace requires a square matrix, got {x.shape}")
return Node(_C.make_trace, [x], (1, 1))


def diag_vec(x):
"""(n, 1) column vector -> (n, n) diagonal matrix."""
x = cast_to_const(x)
if x.shape[1] != 1:
raise ValueError(f"diag_vec requires a column vector, got {x.shape}")
return Node(_C.make_diag_vec, [x], (x.shape[0], x.shape[0]))


def hstack(exprs):
"""Concatenate horizontally; all arguments need the same number of rows."""
exprs = [cast_to_const(e) for e in exprs]
if not exprs or len({e.shape[0] for e in exprs}) != 1:
raise ValueError(f"hstack: need >=1 args with equal rows, got "
f"{[e.shape for e in exprs]}")
shape = (exprs[0].shape[0], np.sum([e.shape[1] for e in exprs]).item())
return Node(lambda *caps: _C.make_hstack(list(caps)), exprs, shape)


def vstack(exprs):
"""Concatenate vertically; all arguments need the same number of columns."""
exprs = [cast_to_const(e) for e in exprs]
if not exprs or len({e.shape[1] for e in exprs}) != 1:
raise ValueError(f"vstack: need >=1 args with equal columns, got "
f"{[e.shape for e in exprs]}")
shape = (np.sum([e.shape[0] for e in exprs]).item(), exprs[0].shape[1])
return Node(lambda *caps: _C.make_vstack(list(caps)), exprs, shape)


def quad_form(x, Q):
"""x' Q x for a column vector x (n, 1) and a constant or Parameter Q (n, n).

A NumPy Q uses the engine's dense (BLAS) path, a scipy.sparse Q the sparse
path. Constant Q is symmetrized; a Parameter Q must be symmetric, which is
checked here and on every later ``Q.value`` update.
"""
x, Q = cast_to_const(x), cast_to_const(Q)
n = x.shape[0]
if x.shape[1] != 1 or Q.shape != (n, n):
raise ValueError(f"quad_form: need x (n, 1) and Q (n, n), "
f"got {x.shape} and {Q.shape}")
if isinstance(Q, Parameter):
Q._symmetric = True # checked now and on every later Q.value update
if Q._flat is not None:
_check_symmetric(Q._flat, Q.shape)
return Node(lambda p, c: _C.make_quad_form(p, c, "dense", None, n),
[Q, x], (1, 1))
if not isinstance(Q, Constant):
raise TypeError("quad_form: Q must be a constant or a Parameter")
V = (Q.value + Q.value.T) / 2 # the engine assumes symmetric Q
if not sps.issparse(V):
data = np.ascontiguousarray(V).ravel()
return Node(lambda c: _C.make_quad_form(None, c, "dense", data, n),
[x], (1, 1))
V = sps.csr_matrix(V)
return Node(lambda c: _C.make_quad_form(
None, c, "sparse", V.data, V.indices.astype(np.int32),
V.indptr.astype(np.int32), n, n), [x], (1, 1))


def quad_over_lin(x, z):
"""sum(x**2) / z for distinct Variables x and scalar z."""
_require_variables("quad_over_lin", x, z)
if z.shape != (1, 1):
raise ValueError(f"quad_over_lin: z must be scalar, got {z.shape}")
return Node(_C.make_quad_over_lin, [x, z], (1, 1))


def rel_entr(x, y):
"""Elementwise x * log(x / y) for distinct Variables x, y.

Shapes must match, or one of them must be scalar.
"""
_require_variables("rel_entr", x, y)
if x.shape == y.shape or y.shape == (1, 1):
shape = x.shape
elif x.shape == (1, 1):
shape = y.shape
else:
raise ValueError(f"rel_entr: incompatible shapes {x.shape} and {y.shape}")
return Node(_C.make_rel_entr, [x, y], shape)
Loading
Loading