Expressions
===========

A network is defined as a giant expression object that is built using
normal-looking operations, but isn't evaluated right away::

    x = constant(2.)
    y = constant(2.)
    z = x + y

``constant(value)`` creates an expression whose value is ``value``,
typically a NumPy array, and ``x + y`` creates a new expression that is
the sum of ``x`` and ``y``, but doesn't actually perform the addition
yet. 

Evaluating
----------

To evaluate an expression::

    >>> compute_value(z)
    4.0

This also evaluates all the subexpressions of ``z`` but discards their
values. To get a dictionary mapping from all subexpressions to their
values::

    >>> values = compute_values(z)
    >>> values[z]
    4.0

Arrays
------

The ``[]`` operator can be used to get an index or slice of an array. 

- Negative indices (``a[-1]``) work.
- Extended slices (``a[::2]``) work.
- Ellipses (``a[...]``) work.
- ``numpy.newaxis`` does *not* work. Use ``expand_dims`` instead.
- Assignment (``a[0] = 1.``) does *not* work. Use ``setitem`` instead::

    a = setitem(a, 0, 1.)

Note that this creates a new Expression object, and during evaluation,
will copy the whole array.

Many NumPy operators and functions have equivalents in Penne that work
more or less the same way. See the reference below. Note that none of
the *methods* of ``numpy.ndarray`` are implemented in Penne, so, for
example, instead of ``x.dot(y)``, write ``dot(x, y)``.

Penne has one other array operation that NumPy doesn't have:
``vecdot(x, y)`` is equivalent to ``numpy.sum(x * y)``. It takes
optional ``axis`` and ``keepdims`` arguments just like
``numpy.sum``. This especially comes in handy when dealing with
:doc:`minibatch`.

Reference
---------

.. autofunction:: penne.constant
.. autofunction:: penne.compute_value
.. autofunction:: penne.compute_values
.. autofunction:: penne.setitem

Array creation
..............

.. autofunction:: penne.zeros
.. autofunction:: penne.ones
.. autofunction:: penne.full

Elementwise operations
......................

.. autofunction:: penne.add
.. autofunction:: penne.subtract
.. autofunction:: penne.multiply
.. autofunction:: penne.divide
.. autofunction:: penne.power
.. autofunction:: penne.log
.. autofunction:: penne.exp
.. autofunction:: penne.maximum
.. autofunction:: penne.minimum
.. autofunction:: penne.clip

Reductions
..........

.. autofunction:: penne.asum
.. autofunction:: penne.amax
.. autofunction:: penne.amin
.. autofunction:: penne.mean

Shape-changing operations
.........................

.. autofunction:: penne.concatenate
.. autofunction:: penne.stack
.. autofunction:: penne.transpose
.. autofunction:: penne.reshape
.. autofunction:: penne.expand_dims

Product-like operations
.......................

.. autofunction:: penne.dot
.. autofunction:: penne.vecdot