README.rst 5.22 KB
Newer Older
Christoph Groth's avatar
Christoph Groth committed
1 2 3
Tinyarray
=========

4 5 6 7 8 9 10
Tinyarrays are similar to NumPy arrays, but optimized for small sizes.
Common operations on very small arrays are to 3-7 times faster than with
NumPy (with NumPy 1.6 it used to be up to 35 times), and 3 times less
memory is used to store them.  Tinyarrays are useful if you need many
small arrays of numbers, and cannot combine them into a few large ones.
(The resulting code is still much slower than C, but it may now be fast
enough.)
Christoph Groth's avatar
Christoph Groth committed
11

12 13 14
Unlike Python's built-in tuples, Tinyarrays support mathematical
operations like element-wise addition and matrix multiplication.  Unlike
Numpy arrays, Tinyarrays can be used as dictionary keys because they are
15 16 17
hashable and immutable.  What is more, tinyarrays are equivalent to
tuples with regard to hashing and comparisons: a dictionary or set with
tinyarray keys may by transparently indexed by tuples.
Christoph Groth's avatar
Christoph Groth committed
18

19 20 21
The module's interface is a subset of that of NumPy and thus should be
familiar to many.  Whenever an operation is missing from Tinyarray,
NumPy functions can be used directly with Tinyarrays.
Christoph Groth's avatar
Christoph Groth committed
22 23


24 25
Tinyarray is licensed under the "simplified BSD License".  See
`<LICENSE.rst>`_.
Christoph Groth's avatar
Christoph Groth committed
26

27 28 29 30
Website: https://gitlab.kwant-project.org/kwant/tinyarray

Please report bugs here:
https://gitlab.kwant-project.org/kwant/tinyarray/issues
Christoph Groth's avatar
Christoph Groth committed
31 32


33 34 35 36 37 38 39
Source code
-----------

Source tarballs are available at http://downloads.kwant-project.org/tinyarray/

Clone the Git repository with ::

40
    git clone https://gitlab.kwant-project.org/kwant/tinyarray.git
41 42


43 44
Installation
------------
Christoph Groth's avatar
Christoph Groth committed
45

46
Tinyarray can be built from source with the usual ::
Christoph Groth's avatar
Christoph Groth committed
47

48
    pip install tinyarray
Christoph Groth's avatar
Christoph Groth committed
49

50
One can also download the source tarball (or clone it from git) and use ::
Christoph Groth's avatar
Christoph Groth committed
51

52
    python setup.py install
Christoph Groth's avatar
Christoph Groth committed
53 54

Prepared packages exist for
Christoph Groth's avatar
Christoph Groth committed
55

56
* Windows
Christoph Groth's avatar
Christoph Groth committed
57

58 59
  Use `Christoph Gohlke's installer
  <http://www.lfd.uci.edu/~gohlke/pythonlibs/#tinyarray>`_.
Christoph Groth's avatar
Christoph Groth committed
60

61
* Ubuntu and derivatives ::
62

63 64 65
      sudo apt-add-repository ppa:kwant-project/ppa
      sudo apt-get update
      sudo apt-get install python-tinyarray
66

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
* Debian and derivatives

  1. Add the following lines to ``/etc/apt/sources.list``::

         deb http://downloads.kwant-project.org/debian/ stable main
         deb-src http://downloads.kwant-project.org/debian/ stable main

  2. (Optional) Add the OpenPGP key used to sign the repositories by executing::

         sudo apt-key adv --keyserver pgp.mit.edu --recv-key C3F147F5980F3535

  3. Update the package data, and install::

         sudo apt-get update
         sudo apt-get install python-tinyarray

* Mac OS X

  Follow the `instructions for installing "Kwant"
  <http://kwant-project.org/install#mac-os-x>`_ but install
  ``py27-tinyarray`` instead of ``py27-kwant`` etc.
Christoph Groth's avatar
Christoph Groth committed
88 89


90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
Build configuration
-------------------

If necessary, the compilation and linking of tinyarray can be configured with
a build configuration file.  By default, this file is ``build.conf`` in the
root directory of the tinyarray distribution.  A different path may be
provided using the ``--configfile=PATH`` option.

The configuration file consists of sections, one for each extension module
(currently there is only one: ``tinyarray``), led by a ``[section name]``
header and followed by ``key = value`` lines.

Possible keys are the keyword arguments for ``distutils.core.Extension`` (For
a complete list, see its `documentation
<https://docs.python.org/3/distutils/apiref.html#distutils.core.Extension>`_).
The corresponding values are whitespace-separated lists of strings.

Example ``build.conf`` for compiling Tinyarray with C assertions::

    [tinyarray]
    undef_macros = NDEBUG


113 114
Usage example
-------------
Christoph Groth's avatar
Christoph Groth committed
115

116 117
The following example shows that in simple cases Tinyarray works just as
NumPy. ::
118

119 120
    from math import sin, cos, sqrt
    import tinyarray as ta
121

122 123
    # Make a vector.
    v = ta.array([1.0, 2.0, 3.0])
Christoph Groth's avatar
Christoph Groth committed
124

125 126 127 128 129 130
    # Make a rotation matrix.
    alpha = 0.77
    c, s = cos(alpha), sin(alpha)
    rot_z = ta.array([[c, -s, 0],
                      [s,  c, 0],
                      [0,  0, 1]])
Christoph Groth's avatar
Christoph Groth committed
131

132 133 134 135
    # Rotate the vector, normalize, and print it.
    v = ta.dot(rot_z, v)
    v /= sqrt(ta.dot(v, v))
    print v
Christoph Groth's avatar
Christoph Groth committed
136 137


138 139
Documentation
-------------
Christoph Groth's avatar
Christoph Groth committed
140

141 142 143 144
The module's interface is a basic subset of NumPy and hence should be familiar
to many Python programmers.  All functions are simplified versions of their
NumPy counterparts.  The module's docstring serves as main documentation.  To
see it, run in Python::
Christoph Groth's avatar
Christoph Groth committed
145

146 147
    import tinyarray as ta
    help(ta)
Christoph Groth's avatar
Christoph Groth committed
148

149 150 151 152 153
Or in the system shell::

    pydoc tinyarray


154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
Contributing
------------

Contributions to tinyarray are most welcome.  Patches may be sent by email, or
a merge request may be opened on the Project's website.

Please add tests for any new functionality and make sure that all existing
tests still run.  To run the tests, execute::

    python setup.py test

It is a good idea to enable C assertions as shown above under
`Build configuration`_.


169 170 171
Authors
-------

172
The principal developer of Tinyarray is Christoph Groth (CEA
173 174 175 176 177 178 179
Grenoble).  His contributions are part of his work at `CEA <http://cea.fr/>`_,
the French Commissariat à l'énergie atomique et aux énergies alternatives.

The author can be reached at christoph.groth@cea.fr.

Other people that have contributed to Tinyarray include

180 181
* Michael Wimmer (Leiden University, TU Delft)
* Joseph Weston (CEA Grenoble, TU Delft)
Christoph Groth's avatar
Christoph Groth committed
182
* Jörg Behrmann (FU Berlin)