More matrix features to MathObject matrices

[pstaabp]

This builds on #1012 and includes

• new methods for setting elements, removing columns and rows and a submatrix.
• A test suite for nearly all of the methods in the module.
• updated POD.

[Alex-Jordan]

I was looking at the POD since a lot of that is in the diff here, and I left some comments. But I'm going to pause because I think if you proofread the actual POD output you will see a lot of the same things that I'm seeing. I'll move on to testing the new tools now.

[Alex-Jordan]

This has some issues as well. If I try it on a 1D matrix, I get an error:

$A = Matrix([ 1, 2, 3, 4 ]);
$B = $A->subMatrix([3]);

And if I try it on a 3D matrix, it is not returning what I would expect it to:

$A = Matrix([ [[1,2],[3,4]], [[5,6], [7,8]]]);
$B = $A->subMatrix([1], [1,2], [2]);
# $B seems to be what I would expect from subMatrix([1], [1,2], [1,2]);

[Alex-Jordan]

(It did seem to work when I tested with 2D matrices though.)

[pstaabp]

I thought of subMatrix only on 2D matrices, so will rework for other dimensions.

[pstaabp]

Rewrote this now. Should be working on non-2D matrices.

[drgrice1]

This needs to be

Suggested change

	my $el = $self->{data}[ $ind->[0] - 1 ];
	for my $i (1 .. scalar(@$ind) - 1) { $el = $el->{data}[ $ind->[$i] - 1 ]; }
	# update the value of $el
	$el = Value::makeValue($value);
	my $el = \($self->{data}[ $ind->[0] - 1 ]);
	for my $i (1 .. scalar(@$ind) - 1) { $el = \($$el->{data}[ $ind->[$i] - 1 ]); }
	# update the value of $el
	$$el = Value::makeValue($value);

	my $el = \($self->{data}[ $ind->[0] - 1 ]);
	for my $i (1 .. scalar(@$ind) - 1) { $el = \($$el->{data}[ $ind->[$i] - 1 ]); }

	# update the value of $el
	$$el = Value::makeValue($value);

in order to actually mutate the matrix.

[pstaabp]

Changed this, but odd that the test works for the previous version of the code as well as this one, however, I think the test needs some help.

[Alex-Jordan]

This seems to be incorrect. (It was incorrect before this PR.) $matrix->value produces an actual array, not an array reference. Its entries are either numbers (if $matrix was 1D) or are array references. I don't have a suggestion for how to succinctly write that in the POD.

[Alex-Jordan]

This is also incorrect (and was before). There is no dimension method. However there is dimensions, which returns an array of integers as you would expect. Usually two for what we think of normally as a matrix.

I think it would be goo if there were a dimension method though, that tells you if it is a 1D, 2D, 3D, etc matrix. It would just be evaluating $matrix->dimensions in a scalar context.

[Alex-Jordan]

It would be convenient if row could take for its argument:

• a whole number, returning a matrix that is one dimension less (in the 1D, 2D, 3D, etc sense) or just 1D if applied to a 1D matrix (as it currently does)
• several whole numbers, returning a submatrix of the same dimension (2D, 3D)
• an array ref of several whole numbers, equivalent to the above

[Alex-Jordan]

Similar to my comment about row, the column method could take multiple whole numbers as arguments.

Also I am seeing what I think is undesirable behavior here with 1D matrices. For an nD matrix with n > 1, $matrix->column(1) is still an nD matrix. Good. But with a 1D matrix, $matrix->column(1) is a Real rather than a 1D matrix. I think for consistency it should still be a 1D matrix.

[Alex-Jordan]

See my other comment about column. Currently for a 1D matrix, $matrix->column(1) is a Real. I do think it should be changed to be a MathObject Matrix though.

With the element method, it is more complicated than this. If you have an nD matrix and you pass n whole numbers to element, then yes you get a Real (or Complex, I assume). But if you pass fewer than n whole numbers, you get a Matrix. (And if you pass more than n, you get null.)

[Alex-Jordan]

See my recent comments just now. I feel like we need to work on this file in a more methodical manner, especially since there are things to fix that precede the new things here. I propose:

1. Go through the current methods and (a) make them better if we see opportunity for that, and (b) correct their POD without moving POD around.
2. Then reorganize the POD and provide/update a test suite for the existing methods. The test suite should be thorough with at least 1D, 2D, and 3D matrices.
3. Then add new methods, with new POD, and new tests.

When I look at the diff for this PR, it's just too overwhelming to sort out what is just POD moving around and what is new content.

[pstaabp]

Would it make sense if we split this in two pieces?

1. update the POD for existing methods and functionality
2. Update the methods as you mentioned and with them any needed POD.