Andrew Jackson

Dimitri is not being dumb here. The author has failed to provide a tool that has any useful documentation. Your job as a programmer does not stop when you write the last line of code. If you think so, then you should be fired. You should document your code. Provide help. Otherwise, that code is just a bunch of random bits, useful to nobody else in the world.

This code has a couple of uses that I might think of. (The fact that I need to document the author's code is a major failure on this author's part. Does my irritation show through?)

You MIGHT choose to use this tool to enable an unconstrained nonlinear least squares solver to solve a linearly equality constrained problem, with a nonlinear objective function. For example, suppose you wish to use fminsearch to solve a problem where the sum of the parameters must be 1. You could use this function to help. You would still need to know what to do, but the author failed to provide any hints. Too bad.

Another possible use might be to solve a linear least squares problem with linear equality constraints. Suppose you wished to solve the problem

  G*x = h

subject to the equality constraint(s)

  A*x = b

This code provides a transformation x = C*y + d, so that the linear least squares problem reduces to

  A*(C*y+d) = b

or

  (A*C)*y = b - A*d

Solve it as

  y = (A*C)\(b - A*d)

and then recover the value of x from the supplied relation

  x = C*y + d

So, in theory, this code has some utility. Without the comments I've just provided, it is useless though to anybody who does not know enough about the problem that what it does is trivial. My point is that while I personally might in theory have found a tool like this of some use, I also know how to do what it does in only a few lines, so it still offers no value to me.

How about the help? Poor. It does not tell you what the inputs should be, in terms of their order, shape, class, or size. The outputs are similarly undescribed.

There is error checking, but since there is no real description of the inputs, how can you check for errors? There is no error check on the number of columns of b either (should be 1).

I feel there is also a flaw in the error checks. If you pass in an inconsistent system, the code will error out, but the error generated will be a very confusing one.

There are some internal comments, and the author has chosen descriptive variable names, so you can read the code.

How about the code itself? This uses loops to do what can be done in one line of code, at least if your matrix is full. I've not checked the algorithm itself to decide if it is as stable, as say, a call to null, but on a few tests I found that a numerically nonsingular (although poorly conditioned) matrix caused this code to fail.

An interesting point is, if A has many columns (i.e., x has many elements) but few rows, then the resulting C matrix will be very large, but if A is sparse, then C will be stored in a sparse format, and it will be sparse. The null solution would yield a full matrix here.

Had this code full documentation, coupled with complete examples on how to use it for at least the two classes of problems I've described, and if it had good help, then it would have earned a better rating from me. As it is, I can't justify a better rating than to say it needs improvement.