(Closes #2774) Refactor matmul2code to allow for more permutations of full ranges

[DrTVockerodtMO]

Fixes #2774.

There was a hardcoded standard in PSyclone where for matrix multiplications, the first one or two indices must be full ranges (i.e.: the Fortran would be written as matrix(:,:,...) or vector(:,...)). However, Fortran can perform matrix multiplications with the full ranges in different orderings, as long as the shape conforms.

When recent LFRic changes re-ordered some of the operator index accesses, this shifted the full ranges into forbidden permutations.

This change addresses this issue by allowing more permutations that produce valid Fortran matmul code.

Description of changes
Added a new private method _get_full_range_split to matmul2code_trans.py, which splits information about full range and non full range nodes as well as performs some validation. For a given array, the method iterates over the children, and checks whether or not they are Range nodes. If the Range node is a full range, we append its position in the array to a list. If not, we throw an error. If it is not a Range node then its position and the node itself are appended to two different lists.

After the children are iterated over, if we have more than two full ranges then this array is not a valid input for matmul, so we throw an error. Otherwise, return the two lists containing the positions of the full range and non full range nodes in the array, as well as the non full range node list.

Some further validation is performed to ensure that the first matrix involved in the matmul has exactly two full ranges, and that the second matrix has one or two (since it can be a vector or matrix).

The orderings and list of non full range nodes are fed to the modified _create_matrix_ref to make the matrix reference.

Testing
A new test test_apply_matmat_reordered has been added which tests the expected behaviour directly, by feeding the PSyIR some Fortran code with spatially conforming but re-ordered (with respect to the old standard) matrices. Other tests will be modified since a lot of them tested aspects of the old standard that no longer apply.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.88%. Comparing base (4cb5070) to head (54f5cb8).
Report is 27 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2795   +/-   ##
=======================================
  Coverage   99.88%   99.88%           
=======================================
  Files         356      356           
  Lines       49481    49507   +26     
=======================================
+ Hits        49423    49451   +28     
+ Misses         58       56    -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[arporter]

Good stuff @DrTVockerodtMO.
I think the fix/extension is good. Just a few minor things to tidy up and I've requested an extra test.
Although not strictly your fault, I note that the associated test file does not give 100% coverage - lines 424-425 are missed. You can see this by doing pytest --cov psyclone.psyir.transformations.intrinsics.matmul2code_trans -- cov-report term-missing psyir/transformations/intrinsics/matmul2code_trans_test.py. Could you take a look?
Please could you also update the class docstring of apply() to mention the restriction to full ranges and simple arrays (i.e. structures of arrays etc.).
I've fired off the integration tests so these can run in the meantime.

[arporter]

Just a note to say integration tests were OK (barring the expected failures).

[DrTVockerodtMO]

Thanks Terry. Apologies for the confusion over the strings (KGOs) in the tests. Apart from that, looking at the missed lines made me realise that we still seem to have an implicit assumption in the code about the form of the result array that we support. We can either generalise this too or we can make the assumption explicit by checking for it in validate. The good news is that the integration tests were all fine :-)

Addressed in 4629275 and 703c3e1 which now has a different permutation of the result matrix in the calculation.

[arporter]

Thanks Terry. Looking very good now.
I think the only thing left is to refactor the validation as we have quite a bit of duplication there now (the part that checks the number of ranges).
Once that's done this I'll proceed to merge!

[arporter]

(Just a note to say that the test file now gives 100% coverage of the transformation file :-) )

[arporter]

All good now - thanks for removing the duplication.
There are no unaccounted-for coverage changes.
CI is green. Integration tests were previously green.
Will proceed to merge.