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
42 changes: 17 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ 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.
rows of the Jacobian, the scope values) are column-major. Reading `x.value`
gives a read-only copy, so assign to `x.value` to change it.

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

Expand All @@ -59,12 +60,12 @@ 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:
`objective()`, `gradient()`, `constraints()`, `jacobian()` and the Lagrangian
Hessian `hessian(obj_factor, lagrange)` = `obj_factor * H_f + sum_i lagrange_i * H_gi`.
Like `compile`, everything is evaluated at the scope's current values, so a solver
callback sets the flat point with `scope.set_values(u)` and then asks for what it
needs, in any order. Each stage runs once per point and its result is a read-only
array. Here it drives SciPy:

```python
import numpy as np
Expand All @@ -78,25 +79,16 @@ 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 at(u, method, *args): # evaluate prob.method(*args) at the flat point u
scope.set_values(u)
return getattr(prob, method)(*args)

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,
con = NonlinearConstraint(lambda u: at(u, "constraints"), -np.inf, 1.0,
jac=lambda u: at(u, "jacobian"),
hess=lambda u, v: at(u, "hessian", 0.0, v))
res = minimize(lambda u: at(u, "objective"), np.zeros(4),
jac=lambda u: at(u, "gradient"),
hess=lambda u: at(u, "hessian", 1.0, [0.0]),
method="trust-constr", constraints=con)
print(res.x) # approx. [0. 0.289 0.549 0.784], on the boundary ||x|| = 1
```
Expand Down
144 changes: 66 additions & 78 deletions sparsediffpy/_compile.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,19 +90,26 @@ def _csr(triple):
return sps.csr_matrix((data, indices, indptr), shape=shape)


def _read_only(arr):
"""Mark arr read-only and return it, so cached results cannot be mutated."""
arr.flags.writeable = False
return arr


class Problem:
"""A scalar objective plus a list of constraint expressions.

Typical solver loop (u is the flat variable vector)::
Everything is evaluated at the scope's current values: set ``x.value`` (or
``scope.set_values(u)`` with the flat vector) to move the point, then call
any method in any order::

prob.objective_forward(u); prob.constraint_forward(u)
prob.gradient(); prob.jacobian(); prob.hessian(obj_factor, lagrange)
scope.set_values(u)
prob.objective(); prob.gradient()
prob.constraints(); prob.jacobian()
prob.hessian(obj_factor, lagrange)

Each stage runs in the engine only when its point changed: a forward is
skipped when u (or the scope's values and parameters) is unchanged, and
gradient/jacobian are skipped when the matching forward has not moved.
Skipped calls return the cached object, which the problem owns: do not
modify it in place.
Each engine call runs at most once per point (scope values and
parameters), and the results are read-only arrays.
"""

def __init__(self, objective, constraints=(), verbose=False):
Expand All @@ -111,9 +118,8 @@ def __init__(self, objective, constraints=(), verbose=False):
if objective.shape != (1, 1):
raise ValueError(f"Objective must be scalar, got {objective.shape}")
self._scope = _find_scope([objective, *constraints])
# The objective and the constraints are evaluated at separate points, so
# they must not share engine nodes: a constraint_forward would overwrite
# values that the objective's gradient still reads.
# Separate engine nodes for the objective and the constraints, so that
# neither evaluation can overwrite values the other one reads.
obj_build, con_build = _Builder(self._scope), _Builder(self._scope)
obj_cap = obj_build(objective)
con_caps = [con_build(c) for c in constraints]
Expand All @@ -126,10 +132,10 @@ def __init__(self, objective, constraints=(), verbose=False):
self._param_version = None
self.n_vars = self._scope.total_var_size
self.total_constraint_size = sum(c.size for c in constraints)
# Point keys: ("scope", values_version, param_version) or ("u", u_version,
# param_version). Each stage remembers the key it was last computed at.
self._last_u, self._u_version = None, 0
self._obj_at = self._con_at = self._grad_at = self._jac_at = None
# The engine holds one point; _key identifies it (scope values and
# parameters). Results computed there are cached until it moves.
self._key = None
self._obj = self._con = self._grad = self._jac = None

def _sync_params(self):
"""Push Parameter values to the engine if any changed since last time."""
Expand All @@ -144,71 +150,57 @@ def _sync_params(self):
_C.problem_update_params(self._capsule, theta)
self._param_version = self._scope._param_version

def _point(self, u):
"""Return (key, flat u) for the evaluation point u (None: scope values).

The C side does not check the length of u, so it is checked here.
"""
if u is None:
key = ("scope", self._scope._values_version)
u = self._scope._values[:self.n_vars]
else:
u = _flatten_vector(u, self.n_vars, "u")
if self._last_u is None or not np.array_equal(u, self._last_u):
self._last_u, self._u_version = u.copy(), self._u_version + 1
key = ("u", self._u_version)
return key + (self._scope._param_version,), u

def objective_forward(self, u=None):
"""Objective value at u (default: the scope's current values)."""
key, u = self._point(u)
if self._obj_at != key:
self._sync_params()
self._obj_value = _C.problem_objective_forward(self._capsule, u)
self._obj_at = key
return self._obj_value

def constraint_forward(self, u=None):
"""Stacked constraint values at u (default: the scope's current values)."""
key, u = self._point(u)
if self._con_at != key:
def _refresh(self):
"""Forget cached results if the scope's values or parameters changed."""
key = (self._scope._values_version, self._scope._param_version)
if key != self._key:
self._sync_params()
self._con_value = _C.problem_constraint_forward(self._capsule, u)
self._con_at = key
return self._con_value
self._key = key
self._obj = self._con = self._grad = self._jac = None

def _u(self):
"""The flat variable vector this problem is evaluated at."""
return self._scope._values[:self.n_vars]

def objective(self):
"""Objective value (float)."""
self._refresh()
if self._obj is None:
self._obj = _C.problem_objective_forward(self._capsule, self._u())
return self._obj

def constraints(self):
"""Stacked constraint values, shape (total_constraint_size,)."""
self._refresh()
if self._con is None:
self._con = _read_only(
_C.problem_constraint_forward(self._capsule, self._u()))
return self._con

def gradient(self):
"""Objective gradient at the point of the last objective_forward."""
if self._obj_at is None:
raise RuntimeError("call objective_forward before gradient")
if self._grad_at != self._obj_at:
self._grad_value = _C.problem_gradient(self._capsule)
self._grad_at = self._obj_at
return self._grad_value
"""Objective gradient, shape (n_vars,)."""
self.objective()
if self._grad is None:
self._grad = _read_only(_C.problem_gradient(self._capsule))
return self._grad

def jacobian(self):
"""Constraint Jacobian (csr_matrix) at the last constraint_forward point."""
if self._con_at is None:
raise RuntimeError("call constraint_forward before jacobian")
if self._jac_at != self._con_at:
self._jac_value = _csr(_C.problem_jacobian(self._capsule))
self._jac_at = self._con_at
return self._jac_value
"""Constraint Jacobian, csr_matrix of shape (total_constraint_size, n_vars)."""
self.constraints()
if self._jac is None:
self._jac = _csr(_C.problem_jacobian(self._capsule))
_read_only(self._jac.data)
_read_only(self._jac.indices)
_read_only(self._jac.indptr)
return self._jac

def hessian(self, obj_factor, lagrange):
"""Lagrangian Hessian obj_factor H_f + sum_i lagrange_i H_gi (csr_matrix).

Call objective_forward and constraint_forward at the same point first.
"""
"""Lagrangian Hessian obj_factor H_f + sum_i lagrange_i H_gi (csr_matrix)."""
lagrange = _flatten_vector(lagrange, self.total_constraint_size, "lagrange")
# The engine's Hessian reads Jacobian values cached by eval_jacobian, so
# the gradient and Jacobian must be current (no-ops if they already are).
# The engine's Hessian reads values left by the forwards, the gradient
# and the Jacobian, so all four must be current (no-ops if they are).
self.gradient()
if self.total_constraint_size:
self.jacobian()
if self._con_at != self._obj_at:
raise RuntimeError("objective_forward and constraint_forward must "
"be evaluated at the same point before hessian")
self.jacobian()
return _csr(_C.problem_hessian(self._capsule, float(obj_factor), lagrange))


Expand All @@ -220,23 +212,19 @@ def __init__(self, expr):
self._problem = Problem(Constant(0.0), [expr])

def forward(self):
"""f(x) as an array of shape f.shape."""
return self._problem.constraint_forward().reshape(self.shape, order="F")
"""f(x) as a read-only array of shape f.shape."""
return self._problem.constraints().reshape(self.shape, order="F")

def jacobian(self):
"""Sparse Jacobian df/dx, shape (f.size, n_vars)."""
self.forward()
return self._problem.jacobian()

def hessian(self, weights):
"""Sparse Hessian of sum(weights * f(x)), shape (n_vars, n_vars).

weights has f's shape (a 1-D array is also accepted when f is a vector).
"""
weights = _flatten_shaped(weights, self.shape)
self._problem.objective_forward() # the zero objective; needed by gradient()
self.forward()
return self._problem.hessian(0.0, weights)
return self._problem.hessian(0.0, _flatten_shaped(weights, self.shape))


def compile(expr):
Expand Down
17 changes: 13 additions & 4 deletions sparsediffpy/_expression.py
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ def __init__(self, scope, offset, shape):
def value(self):
"""The variable's current entries, shaped like the variable."""
flat = self._scope._values[self._offset:self._offset + self.size]
return flat.reshape(self.shape, order="F").copy()
return _read_only_copy(flat.reshape(self.shape, order="F"))

@value.setter
def value(self, val):
Expand All @@ -161,7 +161,7 @@ def value(self):
"""The parameter's current value, or None if it was never set."""
if self._flat is None:
return None
return self._flat.reshape(self.shape, order="F").copy()
return _read_only_copy(self._flat.reshape(self.shape, order="F"))

@value.setter
def value(self, val):
Expand Down Expand Up @@ -196,6 +196,13 @@ def _flatten_shaped(val, shape):
return arr.ravel(order="F")


def _read_only_copy(arr):
"""A copy of arr that raises on assignment (edits would be silently lost)."""
arr = arr.copy()
arr.flags.writeable = False
return arr


def _flatten_vector(val, n, name):
"""Return ``val`` as a float64 1-D array of exactly n entries."""
arr = np.asarray(val, dtype=np.float64)
Expand Down Expand Up @@ -235,8 +242,10 @@ def total_var_size(self):

def set_values(self, array):
"""Set all variables at once from a flat array (declaration order)."""
self._values[:] = _flatten_vector(array, self._values.size, "values")
self._values_version += 1
values = _flatten_vector(array, self._values.size, "values")
if not np.array_equal(values, self._values): # same point: keep caches
self._values[:] = values
self._values_version += 1

def get_values(self):
"""A copy of the flat variable vector (declaration order)."""
Expand Down
Loading
Loading