# Real Matrix Package

## Proposal Information

• Who Updates: DavidBishop, JimLewis, ...
• Date Proposed: 2013-11-13
• Date Last Updated: 2013-11-13
• Priority:
• Complexity:
• Focus: Testbench

## Summary

Implement real matrix package. Package is required for 1076.1.

## Proposed Changes - David's Summary of the discussion

1) In the packages I reference a matrix with A(row,col). Matlab references with A(col, row). The change would involve reversing the index of every funciton. Pro: Make it more like matlab and less like C Con: Would take several days to make the change.

2) Ability to flatten a matrix into a vector.

3) Remove the polyval, tril, triu, blkdiag functions Pro: These are standard Matlab function. Con: There are typically only used it Matlab demonstrations...

4) better documentaiton for "buildmatrix" function.

5) "randn" function Creates a random matrix with a gausian destribution.

6) create versions of the "zeros" and "ones" and other matrix initalizing commands which take a matrix as an argument (just to get the size). Thus you could say: a <= zeros (5,5); a <= zeros (a);

7) Use "positive" ranges instead of "natural" ranges. This would make the matrix package work more like Matlab. However an address of "(0,0)" would be illegal. The VHDL-2008 predefined types for index_vector and real_vector include zero, so this would be a disconnect.

8) Check ranges to make sure that it is always 1 to x and not "downto" x.

9) "**" operator This operator is recursive is the power is greater than 2. Should someting greather than 2 create an error?

10) The function polyval takes two real_vectors arguments and returns real_vector. This definition is, in my opinion, questionable because in all my life I have never had a need to determine a polynomial value for a vector argument, the argument was always a scalar. This most common use case of a polynomial evaluated for a scalar is made rather complicated: var := polyval (coeff, (0=>x))(0); I recommend to either change the definition of polyval or to add an overloaded version with a scalar argument and scalar return type. Also, change the names of the formal arguments to indicate which is the coefficients.

11) The algorithm used for polyval is numerically poor, both from the perspective of accuracy and performance. According to several books on numerical algebra I consulted Horner's method is much preferable here.

12) There a strict distinction between the mathematical concepts of row vectors and column vectors. A row vector is represented as a VHDL vector, a column vector as a VHDL matrix with a single column. While you have defined transpose functions to convert between row and column vector I foresee overloading ambiguities requiring qualified expressions, which adds complexity. Another approach would be to use a convention: if the left argument of a function is a VHDL vector it's considered a row vector. If the right argument of a function is a VHDL vector it's considered a column vector. I believe this convention works for all the functions taking a real_vector as argument, including mrdivide and mldivide.

13) I propose to add "*"(l, r: real_vector) as an equivalent to dot()

14) Equivalent functions: should they be defined as separate declarations or as aliases? I haven't thought through all the implications of one approach or the other, but the package currently maintains separate definitions (e.g. "/", mrdivide)

15) Modify the "x, y" inputs to be "row, column"

1) Addressing the Matrix via A(row, col) works fine now.

2) To flatten a matrix you can use the "reshape" command (as documented in Matlab)

vec := reshape (mat, 1, mat'length(1)*mat'length(2))

works.

4) Documented this function.

6) Created "size_res" version of zeros, ones, eye, rand, and reshape functions.

8) Created a function to check the ranges. Should this be an error or a warning? The algorithms are designed so that they don't care.