diff --git a/README.md b/README.md index 87a77bb..e4601b6 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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 @@ -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 ``` diff --git a/sparsediffpy/_compile.py b/sparsediffpy/_compile.py index 37f25eb..710b0d1 100644 --- a/sparsediffpy/_compile.py +++ b/sparsediffpy/_compile.py @@ -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): @@ -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] @@ -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.""" @@ -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)) @@ -220,12 +212,11 @@ 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): @@ -233,10 +224,7 @@ def hessian(self, weights): 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): diff --git a/sparsediffpy/_expression.py b/sparsediffpy/_expression.py index 6cecaf4..535b318 100644 --- a/sparsediffpy/_expression.py +++ b/sparsediffpy/_expression.py @@ -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): @@ -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): @@ -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) @@ -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).""" diff --git a/tests/test_api.py b/tests/test_api.py index 9329d82..99263a9 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -326,35 +326,27 @@ def test_derivatives_reuse_forward_and_jacobian(scope, monkeypatch): assert (len(n_fwd), len(n_jac), len(n_hess)) == (2, 2, 3) -def test_problem_skips_repeated_u(scope, monkeypatch): - n_fwd = count_calls(monkeypatch, "problem_constraint_forward") - x = scope.Variable(2, 1) - prob = sp.Problem(sp.sum(x), [sp.exp(x)]) - prob.constraint_forward(np.array([1.0, 2.0])) - prob.constraint_forward(np.array([1.0, 2.0])) # equal, distinct array - assert len(n_fwd) == 1 - prob.constraint_forward(np.array([1.0, 3.0])) - assert len(n_fwd) == 2 - prob.constraint_forward() # scope values are a different point - assert len(n_fwd) == 3 - np.testing.assert_allclose(prob.constraint_forward(), [1.0, 1.0]) - assert len(n_fwd) == 3 - - -def test_derivatives_require_forward(scope): - x = scope.Variable(2, 1) - prob = sp.Problem(sp.sum(x), [sp.exp(x)]) - with pytest.raises(RuntimeError, match="objective_forward"): - prob.gradient() - with pytest.raises(RuntimeError, match="constraint_forward"): - prob.jacobian() - prob.objective_forward([1.0, 2.0]) - prob.constraint_forward([1.0, 3.0]) - with pytest.raises(RuntimeError, match="same point"): +def test_problem_runs_each_stage_once_per_point(scope, monkeypatch): + names = ["problem_objective_forward", "problem_constraint_forward", + "problem_gradient", "problem_jacobian", "problem_hessian"] + calls = {n: count_calls(monkeypatch, n) for n in names} + counts = lambda: tuple(len(calls[n]) for n in names) # noqa: E731 + x, a = scope.Variable(2, 1), scope.Parameter(1, 1, value=1.0) + prob = sp.Problem(sp.sum(a * x ** 2), [sp.exp(x)]) + scope.set_values([1.0, 2.0]) + for _ in range(2): prob.hessian(1.0, [1.0, 1.0]) - prob.objective_forward([1.0, 2.0]) # a point is "the last u": redo both forwards - prob.constraint_forward([1.0, 2.0]) - assert prob.hessian(1.0, [1.0, 1.0]).shape == (2, 2) + prob.objective(), prob.gradient(), prob.constraints(), prob.jacobian() + assert counts() == (1, 1, 1, 1, 2) + scope.set_values(np.array([1.0, 2.0])) # equal values: same point + prob.gradient() + assert counts() == (1, 1, 1, 1, 2) + x.value = [1.0, 3.0] + prob.gradient() + assert counts() == (2, 1, 2, 1, 2) + a.value = 2.0 + prob.jacobian() + assert counts() == (2, 2, 2, 2, 2) def test_problem(scope): @@ -363,11 +355,11 @@ def test_problem(scope): prob = sp.Problem(sp.sum(sp.exp(shared)), [x[0:2] * x[1:3], shared]) u = np.array([0.3, -0.5, 0.8]) s, c = np.sin(u), np.cos(u) + scope.set_values(u) - assert prob.objective_forward(u) == pytest.approx(np.exp(s).sum()) + assert prob.objective() == pytest.approx(np.exp(s).sum()) np.testing.assert_allclose(prob.gradient(), np.exp(s) * c) - np.testing.assert_allclose(prob.constraint_forward(u), - np.r_[u[:2] * u[1:], s]) + np.testing.assert_allclose(prob.constraints(), np.r_[u[:2] * u[1:], s]) J = prob.jacobian().toarray() np.testing.assert_allclose(J[:2], [[u[1], u[0], 0], [0, u[2], u[1]]]) @@ -381,37 +373,63 @@ def test_problem(scope): with pytest.raises(ValueError, match="lagrange"): prob.hessian(1.0, np.ones(4)) - for bad in (np.zeros(2), np.zeros(4)): - with pytest.raises(sp.DimensionError, match="1-D array of 3 elements"): - prob.objective_forward(bad) - with pytest.raises(sp.DimensionError, match="1-D array of 3 elements"): - prob.constraint_forward(bad) - with pytest.raises(sp.DimensionError): - prob.objective_forward(u[:, None]) with pytest.raises(sp.DimensionError, match="lagrange"): prob.hessian(1.0, lam[:, None]) with pytest.raises(ValueError, match="scalar"): sp.Problem(x) +def test_problem_without_constraints(scope): + x = scope.Variable(2, 1) + prob = sp.Problem(sp.sum(sp.exp(x))) + x.value = [0.0, 1.0] + np.testing.assert_allclose(prob.gradient(), np.exp([0.0, 1.0])) + assert prob.constraints().shape == (0,) + assert prob.jacobian().shape == (0, 2) + np.testing.assert_allclose(prob.hessian(1.0, []).diagonal(), np.exp([0.0, 1.0])) + + def test_problem_parameters(scope): x, a = scope.Variable(2, 1), scope.Parameter(1, 1, value=2.0) prob = sp.Problem(sp.sum(a * x ** 2)) - u = np.array([1.0, 3.0]) - assert prob.objective_forward(u) == pytest.approx(20.0) + x.value = [1.0, 3.0] + assert prob.objective() == pytest.approx(20.0) a.value = 0.5 - assert prob.objective_forward(u) == pytest.approx(5.0) - np.testing.assert_allclose(prob.gradient(), u) + assert prob.objective() == pytest.approx(5.0) + np.testing.assert_allclose(prob.gradient(), [1.0, 3.0]) -def test_objective_and_constraints_at_different_points(scope): - x, a = scope.Variable(3, 1), scope.Parameter(1, 1, value=2.0) - e = sp.exp(a * x) # shared by the objective and the constraint - prob = sp.Problem(sp.sum(e), [e]) - prob.objective_forward(np.zeros(3)) - prob.constraint_forward(np.ones(3)) - np.testing.assert_allclose(prob.gradient(), [2.0, 2.0, 2.0]) - np.testing.assert_allclose(prob.jacobian().diagonal(), 2 * np.exp([2.0] * 3)) +@pytest.mark.parametrize("shared", [True, False]) +def test_problem_interleaved_points(scope, shared): + """Moving the point between a forward and its derivative never goes stale.""" + x = scope.Variable(3, 1) + e = sp.exp(x) + obj, con = (sp.sum(e), e * x) if shared else (sp.sum(x * x), sp.exp(x) * x) + grad = (lambda u: np.exp(u)) if shared else (lambda u: 2 * u) # noqa: E731 + jac = lambda u: np.exp(u) * (1 + u) # noqa: E731 + u1, u2 = np.zeros(3), np.array([1.0, 2.0, 3.0]) + prob = sp.Problem(obj, [con]) + scope.set_values(u1) + prob.objective() + scope.set_values(u2) + prob.constraints() + np.testing.assert_allclose(prob.gradient(), grad(u2)) + scope.set_values(u1) + np.testing.assert_allclose(prob.jacobian().diagonal(), jac(u1)) + np.testing.assert_allclose(prob.gradient(), grad(u1)) + + +def test_results_are_read_only(scope): + x, p = scope.Variable(2, 1), scope.Parameter(2, 1, value=[1.0, 2.0]) + fn = sp.compile(p * sp.exp(x)) + prob = sp.Problem(sp.sum(sp.exp(x)), [sp.exp(x)]) + x.value = [0.0, 1.0] + for arr in (x.value, p.value, fn.forward(), fn.jacobian().data, + prob.constraints(), prob.gradient(), prob.jacobian().data): + with pytest.raises(ValueError, match="read-only"): + arr[0] = 5.0 + np.testing.assert_array_equal(x.value, [[0.0], [1.0]]) + assert scope.get_values().flags.writeable def test_hessian_without_prior_jacobian(scope): @@ -429,8 +447,6 @@ def test_hessian_without_prior_jacobian(scope): H = np.block([[np.diag(d2(yv, yv)), off], [off, np.diag(d2(xv, xv))]]) np.testing.assert_allclose(fn.hessian(w).toarray(), H, atol=1e-12) - prob.objective_forward(u) - prob.constraint_forward(u) H_prob = np.block([[np.zeros((2, 2)), np.diag(2.0 + w)], [np.diag(2.0 + w), np.zeros((2, 2))]]) np.testing.assert_allclose(prob.hessian(2.0, w).toarray(), H_prob, @@ -485,10 +501,9 @@ def test_compile_deep_nonlinear_chain(scope): np.testing.assert_allclose(fn.hessian(1.0).toarray(), [[d2]], rtol=1e-8) prob = sp.Problem(sp.sum(g), [g]) - u = np.array([x0]) - assert prob.objective_forward(u) == pytest.approx(v, rel=1e-12) + assert prob.objective() == pytest.approx(v, rel=1e-12) np.testing.assert_allclose(prob.gradient(), [d1], rtol=1e-10) - np.testing.assert_allclose(prob.constraint_forward(u), [v], rtol=1e-12) + np.testing.assert_allclose(prob.constraints(), [v], rtol=1e-12) np.testing.assert_allclose(prob.jacobian().toarray(), [[d1]], rtol=1e-10) np.testing.assert_allclose(prob.hessian(1.0, [2.0]).toarray(), [[3 * d2]], rtol=1e-8)