GSoC/GCI Archive
GSoC/GCI Archive

### Refactor Key PMC handling in Parrot-Linear-Algebra

completed by: Fernando Brito

mentors: whiteknight

Task Description: Parrot-Linear-Algebra(PLA) is a linear-algebra package for the Parrot Virtual Machine. PLA adds matrix/vector data types and operations for Parrot's users.

A Key PMC is a linked-list structure which contains indices. A Key PMC can be used to make lookups in multi-dimensional structures by doing linear lookups recursively. Arity is the number of elements in a Key. If we have an array of arrays, we can use n Arity 2 Key (a Key with two elements) to find a single element in it. We pop the first index off the key, and use it to look up the inner array. Then we pass the new Arity 1 key to the inner array to perform the second lookup.

PLA matrix types are flat structures in memory, so lookups cannot be made recursively like it can for array-in-array structures. PLA matrix types require that a Key PMC have arity 1 (to lookup in the matrix like an array) or arity 2 exactly. No other arities make sense.

PLA uses the GET_KEY_INDICES_ROWMAJOR and GET_KEY_INDICES_COLMAJOR macros to read values out of a Key. However, this macro does no error checking, and does not accept any other types of inputs (like an integer array) that may also be useful. This needs to be fixed.

Steps to Complete:

1. Create a fork of Whiteknight/parrot-linear-algebra on Github
2. In the file src/lib/matrix_common.c, create a new function "pmckey_to_coords" to convert a PMC into two INTVAL coordinates. You can use the intkey_to_coords function as a template.
1. If the PMC is a Key (pmc->vtable->base_type == enum_class_Key) you will need to figure out how many elements it has, and throw an error if it isn't 1 or 2. Get those values out of the key.
2. If the PMC is an array (VTABLE_does(interp, pmc, CONST_STRING(interp, "array"))) make sure it has one or two elements. Get those values out of the array
3. If we have 1 element, we can duplicate the logic from intkey_to_coords, or call that function directly to avoid duplicating logic
4. If we have 2 elements, we can return them directly
3. Update the macros GET_KEY_INDICES_ROWMAJOR and GET_KEY_INDICES_COLMAJOR to call your new function
4. Add at 3 tests each to t/pmc/complexmatrix2d.t, t/pmc/nummatrix2d.t and t/pmc/pmcmatrix2d.t. These new tests should test:
1. That a Key with more than 2 elements throws an exception
2. That an array of 2 integers can be used to look up an item in the matrix
3. That an empty array (0 elements) throws an exception
5. Build PLA and run all tests to verify
6. Open a pull request on github to have your work merged in.