Add cp.nlp submodule namespace for NLP atoms (cvxpy#3222)

* Add cp.nlp submodule namespace for NLP atoms

Closes cvxpy#3198

Creates a dedicated cvxpy.nlp namespace for atoms that require
an NLP solver (nlp=True). Users can now write:

    import cvxpy as cp
    x = cp.Variable()
    prob = cp.Problem(cp.Minimize(cp.nlp.sin(x)), [x >= 0])
    prob.solve(nlp=True)

Atoms available under cp.nlp:
- Trigonometric: sin, cos, tan
- Hyperbolic: sinh, tanh, asinh, atanh

Note: cp.sin etc. still work as before via cp.atoms import.
cp.nlp provides a dedicated namespace making it clear these
atoms require NLP solvers.

AI assistance was used for codebase exploration, as per
CVXPY's AI disclosure policy.

* Remove NLP atoms from top-level cp namespace, keep only under cp.nlp

Per PTNobel's review: NLP atoms (sin, cos, tan, sinh, tanh, asinh, atanh)
should not be in the top-level cp namespace since they require nlp=True.
They are now only accessible via cp.nlp.sin etc.

Also update tests to reflect new design:
- Remove test_atoms_same_as_direct (cp.sin no longer exists)
- Add test_atoms_not_in_top_level to enforce the new policy
- Add test_atoms_same_class_as_direct_import to verify cp.nlp points
  to the correct classes

* Update NLP tests to use cp.nlp namespace

NLP atoms (sin, cos, tan, sinh, tanh, asinh, atanh) are no longer
exported at the top-level cp namespace. Update all nlp_tests to use
cp.nlp.sin, cp.nlp.cos etc. consistently.

* Fix ruff linting: remove unused imports and sort import block in test_nlp_namespace.py

* update dnlp docs

---------

Co-authored-by: Steven Diamond <diamond@cs.stanford.edu>

Author: Nikitaa104

cvxpy/__init__.py

@@ -64,6 +64,7 @@
     suppfunc as suppfunc,
 )
 from cvxpy import logic as logic
+from cvxpy import nlp as nlp
 from cvxpy.reductions.solvers.defines import installed_solvers as installed_solvers
 from cvxpy.settings import (
     CBC as CBC,

cvxpy/atoms/__init__.py

@@ -72,8 +72,8 @@
 from cvxpy.atoms.elementwise.sqrt import sqrt
 from cvxpy.atoms.elementwise.square import square
 from cvxpy.atoms.elementwise.xexp import xexp
-from cvxpy.atoms.elementwise.trig import sin, cos, tan
-from cvxpy.atoms.elementwise.hyperbolic import sinh, asinh, tanh, atanh
+# NLP atoms (require nlp=True solver) are accessible via cp.nlp namespace only.
+# e.g. cp.nlp.sin, cp.nlp.cos  — not at the top-level cp namespace.
 from cvxpy.atoms.eye_minus_inv import eye_minus_inv, resolvent
 from cvxpy.atoms.gen_lambda_max import gen_lambda_max
 from cvxpy.atoms.geo_mean import GeoMean, GeoMeanApprox, geo_mean

cvxpy/nlp/__init__.py

@@ -0,0 +1,19 @@
+"""
+cvxpy.nlp — Namespace for NLP (nonlinear programming) atoms.
+
+These atoms require a solver that supports nlp=True (e.g. IPOPT, UNO).
+
+Example usage:
+    import cvxpy as cp
+    x = cp.Variable()
+    prob = cp.Problem(cp.Minimize(cp.nlp.sin(x)), [x >= 0])
+    prob.solve(nlp=True)
+"""
+
+from cvxpy.atoms.elementwise.trig import sin, cos, tan
+from cvxpy.atoms.elementwise.hyperbolic import sinh, tanh, asinh, atanh
+
+__all__ = [
+    "sin", "cos", "tan",
+    "sinh", "tanh", "asinh", "atanh",
+]

cvxpy/tests/nlp_tests/test_hyperbolic.py

@@ -27,7 +27,7 @@ class TestHyperbolic():
     def test_sinh(self):
         n = 10
         x = cp.Variable(n)
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.sinh(cp.logistic(x * 2)))),
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.sinh(cp.logistic(x * 2)))),
                            [x >= 0.1, cp.sum(x) == 10])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
@@ -38,7 +38,7 @@ def test_sinh(self):
     def test_tanh(self):
         n = 10
         x = cp.Variable(n)
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.tanh(cp.logistic(x * 2)))),
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.tanh(cp.logistic(x * 2)))),
                            [x >= 0.1, cp.sum(x) == 10])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
@@ -49,7 +49,7 @@ def test_tanh(self):
     def test_asinh(self):
         n = 10
         x = cp.Variable(n)
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.asinh(cp.logistic(x * 3)))),
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.asinh(cp.logistic(x * 3)))),
                            [x >= 0.1, cp.sum(x) == 10])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
@@ -60,7 +60,7 @@ def test_asinh(self):
     def test_atanh(self):
         n = 10
         x = cp.Variable(n)
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.atanh(cp.logistic(x * 0.1)))),
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.atanh(cp.logistic(x * 0.1)))),
                            [x >= 0.1, cp.sum(x) == 10])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL

cvxpy/tests/nlp_tests/test_matmul.py

@@ -68,7 +68,7 @@ def test_matmul_with_function_right(self):
         X = np.random.rand(m, n)
         Y = cp.Variable((n, p), bounds=[-2, 2], name='Y')
         Y.value = np.random.rand(n, p)
-        obj = cp.sum(cp.matmul(X, cp.cos(Y)))
+        obj = cp.sum(cp.matmul(X, cp.nlp.cos(Y)))
         problem = cp.Problem(cp.Minimize(obj))
 
         problem.solve(solver=cp.IPOPT, nlp=True, hessian_approximation='exact',
@@ -84,7 +84,7 @@ def test_matmul_with_function_left(self):
         X = cp.Variable((m, n), bounds=[-2, 2], name='X')
         Y = np.random.rand(n, p)
         X.value = np.random.rand(m, n)
-        obj = cp.sum(cp.matmul(cp.cos(X), Y))
+        obj = cp.sum(cp.matmul(cp.nlp.cos(X), Y))
         problem = cp.Problem(cp.Minimize(obj))
 
         problem.solve(solver=cp.IPOPT, nlp=True, hessian_approximation='exact',
@@ -101,7 +101,7 @@ def test_matmul_with_functions_both_sides(self):
         Y = cp.Variable((n, p), bounds=[-2, 2], name='Y')
         X.value = np.random.rand(m, n)
         Y.value = np.random.rand(n, p)
-        obj = cp.sum(cp.matmul(cp.cos(X), cp.sin(Y)))
+        obj = cp.sum(cp.matmul(cp.nlp.cos(X), cp.nlp.sin(Y)))
         problem = cp.Problem(cp.Minimize(obj))
 
         problem.solve(solver=cp.IPOPT, nlp=True, hessian_approximation='exact',

cvxpy/tests/nlp_tests/test_nlp_solvers.py

@@ -459,13 +459,13 @@ def test_clnlbeam(self, solver):
         u = cp.Variable(N+1)
         u.value = np.zeros(N+1)
         control_terms = cp.multiply(0.5 * h, cp.power(u[1:], 2) + cp.power(u[:-1], 2))
-        trigonometric_terms = cp.multiply(0.5 * alpha * h, cp.cos(t[1:]) + cp.cos(t[:-1]))
+        trigonometric_terms = cp.multiply(0.5 * alpha * h, cp.nlp.cos(t[1:]) + cp.nlp.cos(t[:-1]))
         objective_terms = cp.sum(control_terms + trigonometric_terms)
 
         objective = cp.Minimize(objective_terms)
         constraints = []
         position_constraints = (x[1:] - x[:-1] -
-                                cp.multiply(0.5 * h, cp.sin(t[1:]) + cp.sin(t[:-1])) == 0)
+                                cp.multiply(0.5 * h, cp.nlp.sin(t[1:]) + cp.nlp.sin(t[:-1])) == 0)
         constraints.append(position_constraints)
         angle_constraint = (t[1:] - t[:-1] - 0.5 * h * (u[1:] + u[:-1]) == 0)
         constraints.append(angle_constraint)

cvxpy/tests/nlp_tests/test_power_flow.py

@@ -95,7 +95,7 @@ def test_power_flow_dense_formulation(self):
         v = cp.Variable((N, 1), bounds=[v_min, v_max])
         p = cp.Variable(N, bounds=[p_min, p_max])
         q = cp.Variable(N, bounds=[q_min, q_max])
-        C, S = cp.cos(theta - theta.T), cp.sin(theta - theta.T)
+        C, S = cp.nlp.cos(theta - theta.T), cp.nlp.sin(theta - theta.T)
 
         constr = [theta[0] == 0,  p == cp.sum(P, axis=1), q == cp.sum(Q, axis=1),
                 P == cp.multiply(v @ v.T, cp.multiply(G, C) + cp.multiply(B, S)),

cvxpy/tests/nlp_tests/test_scalar_and_matrix_problems.py

@@ -132,67 +132,67 @@ def test_power_fractional_matrix(self):
 
     def test_scalar_trig(self):
         x = cp.Variable()
-        prob = cp.Problem(cp.Minimize(cp.tan(x)), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.nlp.tan(x)), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
-        prob = cp.Problem(cp.Minimize(cp.sin(x)), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.nlp.sin(x)), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
-        prob = cp.Problem(cp.Minimize(cp.cos(x)), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.nlp.cos(x)), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
     def test_matrix_trig(self):
         x = cp.Variable((3, 2))
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.tan(x))), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.tan(x))), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.sin(x))), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.sin(x))), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.cos(x))), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.cos(x))), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
     def test_matrix_hyperbolic(self):
         x = cp.Variable((3, 2))
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.sinh(x))), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.sinh(x))), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
-        prob = cp.Problem(cp.Minimize(cp.sum(cp.tanh(x))), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.sum(cp.nlp.tanh(x))), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
     def test_scalar_hyperbolic(self):
         x = cp.Variable()
-        prob = cp.Problem(cp.Minimize(cp.sinh(x)), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.nlp.sinh(x)), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)
         checker.run_and_assert()
 
-        prob = cp.Problem(cp.Minimize(cp.tanh(x)), [x >= 0.1])
+        prob = cp.Problem(cp.Minimize(cp.nlp.tanh(x)), [x >= 0.1])
         prob.solve(nlp=True, solver=cp.IPOPT)
         assert prob.status == cp.OPTIMAL
         checker = DerivativeChecker(prob)

cvxpy/tests/test_nlp_namespace.py

@@ -0,0 +1,39 @@
+"""Tests for cp.nlp namespace."""
+import cvxpy as cp
+from cvxpy.atoms.elementwise.hyperbolic import tanh
+from cvxpy.atoms.elementwise.trig import cos, sin
+
+
+class TestNLPNamespace:
+    def test_nlp_namespace_accessible(self):
+        """Test that cp.nlp submodule is accessible."""
+        assert hasattr(cp, 'nlp')
+
+    def test_trig_atoms(self):
+        x = cp.Variable()
+        assert cp.nlp.sin(x) is not None
+        assert cp.nlp.cos(x) is not None
+        assert cp.nlp.tan(x) is not None
+
+    def test_hyperbolic_atoms(self):
+        x = cp.Variable()
+        assert cp.nlp.sinh(x) is not None
+        assert cp.nlp.tanh(x) is not None
+        assert cp.nlp.asinh(x) is not None
+        assert cp.nlp.atanh(x) is not None
+
+    def test_atoms_not_in_top_level(self):
+        """NLP atoms should only be accessible via cp.nlp, not cp directly."""
+        assert not hasattr(cp, 'sin')
+        assert not hasattr(cp, 'cos')
+        assert not hasattr(cp, 'tan')
+        assert not hasattr(cp, 'sinh')
+        assert not hasattr(cp, 'tanh')
+        assert not hasattr(cp, 'asinh')
+        assert not hasattr(cp, 'atanh')
+
+    def test_atoms_same_class_as_direct_import(self):
+        """cp.nlp.sin should be the same class as a direct import."""
+        assert cp.nlp.sin is sin
+        assert cp.nlp.cos is cos
+        assert cp.nlp.tanh is tanh

doc/source/tutorial/dnlp/index.rst

@@ -149,7 +149,8 @@ but in DNLP, ``multiply`` is smooth and can be used with two variable arguments.
      - depends on sign
 
 In addition, DNLP introduces the following new smooth atoms that are neither convex
-nor concave. These atoms can only be used in DNLP problems.
+nor concave. These atoms can only be used in DNLP problems and are available in the
+``cp.nlp`` module.
 
 .. list-table::
    :header-rows: 1
@@ -159,50 +160,52 @@ nor concave. These atoms can only be used in DNLP problems.
      - Domain
      - Monotonicity
 
-   * - sin(x)
+   * - cp.nlp.sin(x)
 
      - :math:`\sin(x)`
      - :math:`x \in \mathbf{R}`
      - none
 
-   * - cos(x)
+   * - cp.nlp.cos(x)
 
      - :math:`\cos(x)`
      - :math:`x \in \mathbf{R}`
      - none
 
-   * - tan(x)
+   * - cp.nlp.tan(x)
 
      - :math:`\tan(x)`
      - :math:`x \in (-\pi/2, \pi/2)`
      - none
 
-   * - sinh(x)
+   * - cp.nlp.sinh(x)
 
      - :math:`(e^x - e^{-x})/2`
      - :math:`x \in \mathbf{R}`
      - incr.
 
-   * - tanh(x)
+   * - cp.nlp.tanh(x)
 
      - :math:`(e^x - e^{-x})/(e^x + e^{-x})`
      - :math:`x \in \mathbf{R}`
      - incr.
 
-   * - asinh(x)
+   * - cp.nlp.asinh(x)
 
      - :math:`\ln(x + \sqrt{x^2 + 1})`
      - :math:`x \in \mathbf{R}`
      - incr.
 
-   * - atanh(x)
+   * - cp.nlp.atanh(x)
 
      - :math:`\frac{1}{2} \ln \frac{1+x}{1-x}`
      - :math:`x \in (-1, 1)`
      - incr.
 
-   * - sigmoid(x)
+..
+   TODO: re-add the sigmoid row below once the ``sigmoid`` atom is implemented.
 
+   * - sigmoid(x)
      - :math:`\frac{1}{1 + e^{-x}}`
      - :math:`x \in \mathbf{R}`
      - incr.