Simplify diff-engine converter cleanups

- Inline the 1D-array reshape in convert_matmul (was a helper used twice).
- Extract _matmul_param_node to dedupe the param-source branching.
- Trim over-verbose docstrings and WHAT-not-WHY comments in
  convert_matmul, convert_expr, convert_reshape, convert_transpose,
  convert_conv, and test_matmul_param_inside_transpose.

No behavior change: same 217 passed / 77 skipped / 0 failed in
cvxpy/tests/nlp_tests/ and 17/17 new tests green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Transurgeon

cvxpy/reductions/solvers/nlp_solvers/diff_engine/converters.py

@@ -30,65 +30,51 @@
 from cvxpy.reductions.solvers.nlp_solvers.diff_engine.registry import ATOM_CONVERTERS
 
 
-def _matmul_normalize_1d(A, side):
-    """Reshape a 1D numpy array to 2D for matmul.
+def _matmul_param_node(arg, child, param_dict):
+    """param_node for the constant side of a matmul.
 
-    NumPy matmul treats 1D arrays differently depending on which side:
-      Left 1D:  (k,) → (1, k) — row vector
-      Right 1D: (k,) → (k, 1) — column vector
-    2D input is returned unchanged.
+    Returns the parameter capsule for a bare Parameter, the child capsule
+    when the constant side contains parameters wrapped in an affine atom
+    (so update_params keeps them live in the DAG), or None otherwise.
     """
-    if A.ndim == 1:
-        return A.reshape(1, -1) if side == 'left' else A.reshape(-1, 1)
-    return A
+    if isinstance(arg, cp.Parameter):
+        return param_dict[arg.id]
+    if arg.parameters():
+        return child
+    return None
 
 
 def convert_matmul(expr, children, var_dict, n_vars, param_dict):
     """Convert matrix multiplication A @ f(x), f(x) @ A, or X @ Y.
 
-    NumPy matmul semantics for 1D arrays:
-      (n,) @ (m,k) → treat left as (1,n)   — normalize_shape already does this
-      (m,k) @ (n,) → treat right as (n,1)  — must reshape from (1,n) storage
-      (n,) @ (n,)  → dot product: (1,n) @ (n,1) → scalar
-
-    The C engine only has 2D nodes. 1D expressions are stored as (1,n) by
-    normalize_shape. All 1D→2D matmul normalization is handled here so that
-    helper functions always receive properly shaped 2D data.
+    1D operands are stored as (1, n) in the C engine. Left 1D stays (1, n);
+    right 1D must be reshaped to (n, 1) for matmul.
     """
     left_arg, right_arg = expr.args
     left_child, right_child = children
 
-    # Right 1D child: C stores as (1, n) but matmul needs (n, 1).
-    # Do this once, before branching — used by all three branches.
     if len(right_arg.shape) <= 1 and right_arg.size > 1:
         right_child = _diffengine.make_reshape(right_child, right_arg.size, 1)
 
     if left_arg.is_constant():
-        A = _matmul_normalize_1d(left_arg.value, 'left')
-        if isinstance(left_arg, cp.Parameter):
-            param_node = param_dict[left_arg.id]
-        elif left_arg.parameters():
-            param_node = left_child
-        else:
-            param_node = None
+        A = left_arg.value
+        if A.ndim == 1:
+            A = A.reshape(1, -1)
+        param_node = _matmul_param_node(left_arg, left_child, param_dict)
         if sparse.issparse(A):
             return make_sparse_left_matmul(param_node, right_child, A)
         return make_dense_left_matmul(param_node, right_child, A)
 
-    elif right_arg.is_constant():
-        A = _matmul_normalize_1d(right_arg.value, 'right')
-        if isinstance(right_arg, cp.Parameter):
-            param_node = param_dict[right_arg.id]
-        elif right_arg.parameters():
-            param_node = right_child
-        else:
-            param_node = None
+    if right_arg.is_constant():
+        A = right_arg.value
+        if A.ndim == 1:
+            A = A.reshape(-1, 1)
+        param_node = _matmul_param_node(right_arg, right_child, param_dict)
         if sparse.issparse(A):
             return make_sparse_right_matmul(param_node, left_child, A)
         return make_dense_right_matmul(param_node, left_child, A)
 
-    else:
-        return _diffengine.make_matmul(left_child, right_child)
+    return _diffengine.make_matmul(left_child, right_child)
 
 # TODO we should support sparse elementwise multiply at some point.
 def convert_multiply(expr, children, var_dict, n_vars, param_dict):
@@ -156,9 +142,7 @@ def convert_expr(expr, var_dict, n_vars, param_dict=None):
     d1_Python, d2_Python = normalize_shape(expr.shape)
 
     if d1_C != d1_Python or d2_C != d2_Python:
-        # 1D Python shapes (n,) normalize to (1, n), but the C engine may
-        # produce (n, 1) — e.g. matrix @ scalar or transpose of a vector.
-        # Both represent the same 1D data; reshape to match Python convention.
+        # 1D shape (n,) normalizes to (1, n) but C may produce (n, 1); reshape.
         if len(expr.shape) <= 1 and d1_C * d2_C == d1_Python * d2_Python:
             C_expr = _diffengine.make_reshape(C_expr, d1_Python, d2_Python)
         else:

cvxpy/reductions/solvers/nlp_solvers/diff_engine/registry.py

@@ -41,12 +41,7 @@ def convert_vstack(expr, children):
 
 
 def convert_conv(expr, children):
-    """Convert cp.conv / cp.convolve to _diffengine.make_convolve.
-
-    Both atoms take args = [constant_kernel, signal] with the kernel
-    validated as constant. The C node computes full 1D convolution
-    (length m + n - 1) given a length-m kernel capsule and length-n child.
-    """
+    """Convert cp.conv / cp.convolve (full 1D convolution)."""
     return _diffengine.make_convolve(children[0], children[1])
 
 
@@ -128,16 +123,13 @@ def convert_quad_form(expr, children):
 
 
 def convert_reshape(expr, children):
-    """Convert reshape.
+    """Convert reshape. C-order via transpose(F-reshape(transpose(x))).
 
-    F-order (column-major) uses make_reshape directly.
-    C-order (row-major) is decomposed as: transpose(reshape(transpose(x), (n, m), F))
-    since reshape(x, (m, n), C) == transpose(reshape(transpose(x), (n, m), F)).
+    Identity: reshape(x, (m, n), C) == transpose(reshape(transpose(x), (n, m), F)).
     """
     d1, d2 = normalize_shape(expr.shape)
     if expr.order == "F":
         return _diffengine.make_reshape(children[0], d1, d2)
-    # C-order: transpose input, F-reshape to swapped dims, transpose output
     transposed = _diffengine.make_transpose(children[0])
     reshaped = _diffengine.make_reshape(transposed, d2, d1)
     return _diffengine.make_transpose(reshaped)
@@ -186,8 +178,7 @@ def convert_prod(expr, children):
         return _diffengine.make_prod_axis_one(children[0])
 
 def convert_transpose(expr, children):
-    # In CVXPY, transposing a 1D vector (n,) is a no-op: (n,).T == (n,).
-    # The C engine stores 1D as (1, n), so we must not flip it to (n, 1).
+    # 1D transpose is a numpy no-op; C stores 1D as (1, n), don't flip to (n, 1).
     if len(expr.args[0].shape) <= 1:
         return children[0]
 

cvxpy/tests/nlp_tests/test_matmul.py

@@ -162,12 +162,8 @@ def test_matmul_1d_dot(self):
         checker.run_and_assert()
 
     def test_matmul_param_inside_transpose(self):
-        """Parameter wrapped in transpose on the left-matmul side.
-
-        Ensures convert_matmul's param_source fallback keeps the Parameter
-        referenced in the DAG so update_params doesn't dereference unregistered
-        memory. Mutate A.value and re-solve to exercise the param update path.
-        """
+        """Parameter wrapped in transpose on the left-matmul side; re-solve
+        after mutating A.value to exercise the update_params path."""
         np.random.seed(0)
         m, p = 4, 5
         A1 = np.random.rand(m, p)