.. _matrix-py:

#########
matrix.py
#########

    >>> from minimock import Mock


*********************
class Matrix(object):
*********************

Five dimensional Numpy array that acts as the simulation data core, stored as mx attribute.

Dimensions:

- 1. dimension: iteration
- 2. dimension: branch
- 3. dimension: level
- 4. dimension: object
- 5. dimension: attribute

The data matrix is accompanied with three auxiliary matrices: omap, emap and dmx.

omap (object map) is a four dimensional boolean Numpy array, having dimensions: 

- 1. dimension: iteration
- 2. dimension: branch
- 3. dimension: level
- 4. dimension: object
  
The omap values indicate the object existence for the particular index combination in the data matrix; i.e., if omap[0, 0, 1, 3] has the value of False, the values at mx[0, 0, 1, 3, :] are not data but regarded as random data. If omap[0, 0, 1, 3] has the value of True, however, the values at mx[0, 0, 1, 3, :] are the attribute values for the object 3 at data level 1 at data branch 0 and iteration 0.

emap (evaluation map) is a five dimensional boolean Numpy array, having dimensions:

- 1. dimension: iteration
- 2. dimension: branch
- 3. dimension: level
- 4. dimension: model chain depth
- 5. dimension: object

The emap values indicate the current model chain task evaluation status at the given model chain depth.

dmx (date matrix) contains current date for each simulation unit. Date matrix is a one dimensional datetime array:

- 1. dimension: object

init_dmx (initial date matrix) contains simulation starting date for each simulation unit. Initial date matrix has same shape as date matrix


def __init__(self, levels, attributes, mcdepth, objcount):
==========================================================

Initialize a data matrix::

   >>> from simo.matrix.matrix import Matrix
   >>> sim = Mock('simulator')
   >>> d = Matrix(1, 2, 10, 5, sim, 0)
   >>> d.shape
   (1, 1, 2, 0, 10)
   >>> d.branches
   1
   >>> d.objects
   0
   >>> d.omap
   array([], shape=(1, 1, 2, 0), dtype=bool)
   >>> d.emap
   array([], shape=(1, 1, 2, 5, 0), dtype=bool)
   >>> d.dmx
   array([], dtype=object)
   >>> d.init_dmx
   array([], dtype=object)
   >>> d.errormx
   array([], shape=(1, 1, 0), dtype=int32)


def reset(self):
================

Reset all matrix values::

   >>> d.reset()


def modify_matrix(self, axis, inc):
===================================

Modify data matrix by increasing array size along given axis::

   >>> d.modify_matrix(0, 1)
   Called simulator.add_error(
       'Bad axis (expected 1 or 3, got 0), the size of the matrix can not be modified.',
       None,
       None)
   False
   >>> d.modify_matrix(1, 1)
   True
   >>> d.branches
   2
   >>> d.objects
   0
   >>> d.shape
   (1, 2, 2, 0, 10)
   >>> d.modify_matrix(3, 5)
   True
   >>> d.branches
   2
   >>> d.objects
   5
   >>> d.shape
   (1, 2, 2, 5, 10)
   >>> d.modify_matrix(3, 5)
   True
   >>> d.branches
   2
   >>> d.objects
   10
   >>> d.shape
   (1, 2, 2, 10, 10)
   >>> d.modify_matrix(1, 2)
   True
   >>> d.branches
   4
   >>> d.objects
   10
   >>> d.shape
   (1, 4, 2, 10, 10)
   >>> d.omap.shape
   (1, 4, 2, 10)
   >>> d.emap.shape
   (1, 4, 2, 5, 10)
   >>> d.omap[0, 3, 1, 9]
   False
   >>> d.emap.shape
   (1, 4, 2, 5, 10)
   >>> d.dmx.shape
   (10,)
   >>> d.branches
   4
   >>> d.objects
   10
   >>> d.shape
   (1, 4, 2, 10, 10)
   >>> d.dmx.shape
   (10,)
   >>> d.init_dmx.shape
   (10,)