Matrices containing physical quantities

If one were to populate a large numpy.matrix A with Quantity objects, operations performed on A would be computationally slow. A QuantMatrix is a numpy.matrix associated with two Unit vectors, where the dimension of an entry in the matrix is calculated from the outer product of the two vectors. One should view a QuantMatrix as follows:

   kg  mol 
m 1.0  2.0 
s 3.0  4.0

which represents the matrix:

1.0 m kg  2.0 m mol
3.0 s kg  4.0 s mol

Creation

To create a QuantMatrix call:

QuantMatrix(matrix, [vertical_unit_vector, horizontal_unit_vector])

The elements of the unit vectors may have type Dimension, Unit or Quantity. DimPy will then calibrate the base matrix so that the matrix is displayed in SI units (and only Dimension types are stored):

>>> base_matrix = numpy.array([[1,2],[3,4]])
>>> vertical = [meter, second]
>>> horizontal = [mile, mole]
>>> A = QuantMatrix(base_matrix, [vertical, horizontal])
>>> A
      m     mol 
m 1609.344  2.0 
s 4828.032  4.0

The base matrix or quantities can be changed after creation using the raw_numbers and quantities attributes, but DimPy will check that the new values are compatible (i.e. that the size of the new matrix matches that of the old one).

>>> A.raw_numbers = numpy.array([[3,3],[3,3]])
>>> A
  m  mol 
m 3   3  
s 3   3 
>>> A.quantities = [[meter, meter],[second,second]]
>>> A
   s    s  
m 3.0  3.0 
m 3.0  3.0
>>> A.raw_numbers = numpy.array([[1,2,3],[4,5,6]])
Traceback (most recent call last):
dimpy.qmatrix.QuantMatrixError: Shape of given array, (2, 3), does not match
existing shape, (2, 2).

Methods

A QuantMatrix has methods shape, trace, transpose and dtype, these behave the same as in numpy.

Functions

• qhomogeneous(size, dimension) will create a unit vector of length size where each element has dimension dimension.
• qmat(array) will cast any two dimensional array into a QuantMatrix with dimensionless dimensions.
• qcolumn_vector(raw_numbers, quantities) will create a column vector from the list raw_numbers with dimensions from quantities.

  >>> qcolumn_vector([1,2,3],[meter, second, mole])
       1  
   m  1.0 
   s  2.0 
  mol 3.0
  

• shuffle(qmatrix, shuffle_vector) does not alter the value of a QuantMatrix but may be used to alter the appearance of a QuantMatrix. It multiplies each dimension in the horizontal dimensions by shuffle_vector and divides each vertical dimension by shuffle_vector:

  >>> A
    m  mol 
  m 1   2  
  s 3   4 
  >>> shuffle(A, meter/second); A
           m^2 s^-1  m s^-1 mol 
      s        1          2     
  m^-1 s^2     3          4
  

  shuffle_vector may be a Dimension, Unit or Quantity.

The functions qidentity, qones and qzeros behave the same as their numpy counterparts, returning a QuantMatrix with dimensionless units. They may also be given the dtype keyword argument -- the associated matrix will then have entries of that form.

Arithmetic

Before adding or multiplying instances of QuantMatrix, DimPy will first check that the operations are valid using the following criterion.

Addition: Suppose we are computing A+B, let AL and AT be the left and top dimensions of A respectively and similarly BL and BT for B. The addition is valid if:

• The pointwise division AL/BL gives a list of dimensions which are all the same (i.e. AL/BL is homogeneous).
• Similarly for AT, BT.
• If C and D are these two common dimensions, C*D must be dimensionless.

Multiplication: Suppose we are computing A*B. If exactly one of A or B is a scalar, we perform elementwise multiplication, otherwise we require:

• We need A.shape()[1] == B.shape()[0] (so that standard matrix multiplication is defined).
• We require the inner product of AT and BL to be defined (i.e. the sum is allowed, which occurs if each term has the same dimensions).

These raise a QuantMatrixError if illegal. To exponentiate a QuantMatrix, it must be legal to multiply that QuantMatrix by itself.

Reading values

To read values from a QuantMatrix users should use a single set of square brackets containing a single index or a tuple (as for numpy.matrix). The output is equivalent to that of numpy.matrix. This notation supports slicing:

>>> A
  m  mol 
m 1   2  
s 3   4 
>>> A[0,0]
1609.344 m^2
>>> A[0,:]
      m     mol 
m 1609.344  2.0
>>> A[:,0]
      m    
m 1609.344 
s 4828.032
>>> A[0]
      m     mol 
m 1609.344  2.0