Basic documentation should be added

[CoronelBuendia]

OK, so I've had a quick look at this and it all seems to work fine, but I had a few hiccoughs along the way, mostly to do with some assumptions I made. I think it would be great to add the following minor additions to the documentation:

• Make explicit the form of the QSP being solved. Specifically the orders of the Taylor expansions of the objective (2nd) and constraint functions (1st). But this would be made clear by simply stating that the objective is assumed to be quadratic and the constraints are linearised. Or just the equation!
• Clearly document that the sign convention for inequality constraints is >= 0.0. This is not a universal convention in optimisers and is worth mentioning.
• I briefly tried in Add complex alkylation test #20 to include equality and inequality constraints with vector outputs, but did not succeed. From briefly looking at the code (specifically T) it would appear possible to have vector-valued constraints. Either make it clearer what the proper API is for specifying vector-valued constraints and matrix Jacobians (also i, j or j,i ?) or error if this is attempted.

[timothy-nunn]

@CoronelBuendia I cannot assign you to review #25 or mention you in its comments, but is that what you had in mind?

Cheers,
Tim

[CoronelBuendia]

Hi @timothy-nunn, yes what you've added looks fine. Apologies for not reading the documentation; I was working mostly off the docstrings. I see now that the convention for inequalities was in the docs all along, and is in fact also detailed in the AbstractProblem base-class, which is probably why I didn't notice it.

Just as I point of clarification though; I wasn't struggling with the type-hints for vector-valued functions. I couldn't get it to work with what I believe were properly-dimensioned vectors and matrices.

From the type-hints (before and on this branch) I would expect the following to be possible:

import numpy as np
from pyvmcon import solve
from pyvmcon.problem import Problem


def f(x):
    return x[0]**2

def df(x):
    return np.array([2 * x[0]])


def g(x):
    return np.array([x[0] - 1, x[1] - 1, x[1]**2 - 1])

def dg(x):
     # Assuming row = constraint index and col = variable index
    return np.array([[1, 0], [0, 1], [0, 2 * x[1]]])  # .T otherwise

problem = Problem(
    f=f,
    df=df,
    equality_constraints=[],
    dequality_constraints=[],
    inequality_constraints=[g],
    dinequality_constraints=[dg],
)


solve(problem, x=np.array([2.0, 2.0]), max_iter=10, epsilon=1e-8)

But it errors:

(env) matti@ubuntu24:~/code/PyVMCON$ python examples/test_vector.py 
Traceback (most recent call last):
  File "/home/matti/code/PyVMCON/examples/test_vector.py", line 37, in <module>
    solve(problem, x=np.array([2.0, 2.0]), max_iter=10, epsilon=1e-8)
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/pyvmcon/vmcon.py", line 152, in solve
    delta, lamda_equality, lamda_inequality = solve_qsp(
                                              ^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/pyvmcon/vmcon.py", line 270, in solve_qsp
    + (delta.T @ result.df)
       ~~~~~~~~^~~~~~~~~~~
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/expressions/expression.py", line 51, in cast_op
    return binary_op(self, other)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/expressions/expression.py", line 694, in __matmul__
    return cvxtypes.matmul_expr()(self, other)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/atoms/affine/binary_operators.py", line 51, in __init__
    super(BinaryOperator, self).__init__(lh_exp, rh_exp)
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/atoms/atom.py", line 51, in __init__
    self._shape = self.shape_from_args()
                  ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/atoms/affine/binary_operators.py", line 121, in shape_from_args
    return u.shape.mul_shapes(self.args[0].shape, self.args[1].shape)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/utilities/shape.py", line 130, in mul_shapes
    lh_shape, rh_shape, shape = mul_shapes_promote(lh_shape, rh_shape)
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/cvxpy/utilities/shape.py", line 91, in mul_shapes_promote
    raise ValueError("Incompatible dimensions %s %s" % (lh_shape, rh_shape))
ValueError: Incompatible dimensions (1, 2) (1, 1)

so unless I am doing something fundamentally wrong, it appears vector-valued constraints are not supported. To be clear: I don't need them; it's just the type-hints suggested I could use them.

Note that I was also trying to do this in a "ragged context" as well, i.e. inequality_constraints = [g (of size n), h (of size 1)], and here the error is different:

(env) matti@ubuntu24:~/code/PyVMCON$ python examples/test_vector.py 
Traceback (most recent call last):
  File "/home/matti/code/PyVMCON/examples/test_vector.py", line 37, in <module>
    solve(problem, x=np.array([2.0, 2.0]), max_iter=10, epsilon=1e-8)
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/pyvmcon/vmcon.py", line 146, in solve
    result = problem(x)
             ^^^^^^^^^^
  File "/home/matti/code/PyVMCON/env/lib/python3.12/site-packages/pyvmcon/problem.py", line 103, in __call__
    np.array([c(x) for c in self._inequality_constraints]),
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: setting an array element with a sequence. The requested array has an inhomogeneous shape after 1 dimensions. The detected shape was (2,) + inhomogeneous part.

[timothy-nunn]

Hi @CoronelBuendia,

You are right, I had got confused between the types VMCON expected and the types the Problem expected. Hopefully these are now correct and make sense. 8647b8e

Cheers,
Tim