Metadata-Version: 2.1
Name: tablarray
Version: 0.3.1
Summary: Extend broadcasting rules of numpy to abstract tabularshape of data from cellular shape
Home-page: https://github.com/chriscannon9001/tablarray
Author: Chris Cannon
Author-email: chris.cannon.9001@gmail.com
License: BSD
Platform: UNKNOWN
Requires-Python: >=3.2
Description-Content-Type: text/x-rst
Requires-Dist: attrs
Requires-Dist: numpy

Introduction
============
When the best structure of data is any-dimensional cells arranged
in any-dimensional tables - tablarray provides fast numpy-like array
operations with broadcasting modified to handle both cellular-dimensions
and tabular-dimensions at once.

tablarray was originally developed to manage large numbers of optical modes.

Here is a short example:


.. code-block:: python

    import numpy as np
    import tablarray as ta
    x = ta.TablArray(np.linspace(-2, 2, 4), 0)
    y = ta.TablArray(np.linspace(-1.5, 1.5, 4).reshape(4,1), 0)
    E = ta.zeros((4, 4, 2), cdim=1)
    E.cell[0] = 1.5 / (x**2 + y**2)
    E.cell[1] = -.01 + x * 0
    print(E)

::

    [[|[ 0.24  -0.01 ]|
      |[ 0.557 -0.01 ]|
      |[ 0.557 -0.01 ]|
      |[ 0.24  -0.01 ]|]

     [|[ 0.353 -0.01 ]|
      |[ 2.16  -0.01 ]|
      |[ 2.16  -0.01 ]|
      |[ 0.353 -0.01 ]|]

     [|[ 0.353 -0.01 ]|
      |[ 2.16  -0.01 ]|
      |[ 2.16  -0.01 ]|
      |[ 0.353 -0.01 ]|]

     [|[ 0.24  -0.01 ]|
      |[ 0.557 -0.01 ]|
      |[ 0.557 -0.01 ]|
      |[ 0.24  -0.01 ]|]]t(4, 4)|c(2,)

Those '|' separate tabular vs cellular structure. Similarly 't(4, 4)|c(2,)' is a reminder that E is set of arrays 'c(2,)' arranged in a 4x4 table 't(4, 4)'.

.. code-block:: python

    En = ta.abs(ta.linalg.norm(E)**2)
    Efield = ta.TablaSet(x=x, y=y, E=E, En=En)
    Efield['r'] = ta.sqrt(Efield['x']**2 + Efield['y']**2)
    ta.set_printoptions(threshold=10, precision=3)
    print(Efield.table)

::

            | x      | y      | E        | En    | r     |
    --------+--------+--------+----------+-------+-------+
     [0, 0] | -2.000 | -1.500 | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [0, 1] | -0.667 |        | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [0, 2] | 0.667  |        | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [0, 3] | 2.000  |        | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 0] |        | -0.500 | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 1] |        |        | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 2] |        |        | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 3] |        |        | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 0] |        | 0.500  | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 1] |        |        | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 2] |        |        | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 3] |        |        | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 0] |        | 1.500  | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 1] |        |        | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 2] |        |        | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 3] |        |        | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+

.. code-block:: python

	print(Efield.bcast)

::

            | x      | y      | E        | En    | r     |
    --------+--------+--------+----------+-------+-------+
     [0, 0] | -2.000 | -1.500 | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [0, 1] | -0.667 | -1.500 | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [0, 2] | 0.667  | -1.500 | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [0, 3] | 2.000  | -1.500 | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 0] | -2.000 | -0.500 | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 1] | -0.667 | -0.500 | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 2] | 0.667  | -0.500 | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [1, 3] | 2.000  | -0.500 | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 0] | -2.000 | 0.500  | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 1] | -0.667 | 0.500  | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 2] | 0.667  | 0.500  | [ 2.16   | 4.666 | 0.833 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [2, 3] | 2.000  | 0.500  | [ 0.353  | 0.125 | 2.062 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 0] | -2.000 | 1.500  | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 1] | -0.667 | 1.500  | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 2] | 0.667  | 1.500  | [ 0.557  | 0.310 | 1.641 |
            |        |        |  -0.01 ] |       |       |
    --------+--------+--------+----------+-------+-------+
     [3, 3] | 2.000  | 1.500  | [ 0.24   | 0.058 | 2.500 |
            |        |        |  -0.01]  |       |       |
    --------+--------+--------+----------+-------+-------+

.. code-block:: python

	print(Efield.cell)

::

         | x          | y          | E           | En          | r           |
    -----+------------+------------+-------------+-------------+-------------+
     [0] | [|-2.|     | [[|-1.5|]  | [[|0.24|    | [[|0.058|   | [[|2.5|     |
         |  |-0.667|  |  [|-0.5|]  |   |0.557|   |   |0.31|    |   |1.641|   |
         |  | 0.667|  |  [| 0.5|]  |   |0.557|   |   |0.31|    |   |1.641|   |
         |  | 2.   |] |  [| 1.5|]] |   |0.24 |]  |   |0.058|]  |   |2.5  |]  |
         |            |            |  [|0.353|   |  [|0.125|   |  [|2.062|   |
         |            |            |   |2.16|    |   |4.666|   |   |0.833|   |
         |            |            |   |2.16|    |   |4.666|   |   |0.833|   |
         |            |            |   |0.353|]  |   |0.125|]  |   |2.062|]  |
         |            |            |  [|0.353|   |  [|0.125|   |  [|2.062|   |
         |            |            |   |2.16|    |   |4.666|   |   |0.833|   |
         |            |            |   |2.16|    |   |4.666|   |   |0.833|   |
         |            |            |   |0.353|]  |   |0.125|]  |   |2.062|]  |
         |            |            |  [|0.24|    |  [|0.058|   |  [|2.5|     |
         |            |            |   |0.557|   |   |0.31|    |   |1.641|   |
         |            |            |   |0.557|   |   |0.31|    |   |1.641|   |
         |            |            |   |0.24 |]] |   |0.058|]] |   |2.5  |]] |
    -----+------------+------------+-------------+-------------+-------------+
     [1] |            |            | [[|-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|]  |             |             |
         |            |            |  [|-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|]  |             |             |
         |            |            |  [|-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|]  |             |             |
         |            |            |  [|-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|   |             |             |
         |            |            |   |-0.01|]] |             |             |
    -----+------------+------------+-------------+-------------+-------------+

Lessons from above:

1. TablArray and TablaSet have bcast, table, and cell views.
2. Broadcasting rules of numpy are extended to recognize tabular and cellular shapes.
3. This frees physics libraries to write formulas while blind to tabular super-structure of the application. In other words, the goal is to abstract formulas from tabular shape.
4. TablaSet adds to TablArray by enforcing broadcast-ability across datasets. Once a TablaSet is built, you know it is ready for formulas.


Installation
============
pip install tablarray

Status
======
Alpha - tablarray might be stable enough for prototype applications.

I.e.:

* Key features are implemented and not expected to change.
* A few features need further adaptation for certain cases.
* A fair amount of testing is not done.
* Some features are still missing.
* Packaging needs work.

Todo
====
* Provide setup.py
* testing
* benchmark, cythonize, re-benchmark


