=======================
Element-wise Operations
=======================

This module implements some basic element-wise operations such as addition or division.

Because aliasing is not a problem for element-wise operations, you can make the operations
in-place simply by repeating *x* or *y* in *out*. Following examples are therefore valid
and produce expected results::

   ceygen.elemwise.add_mm(x, y, x)
   ceygen.elemwise.multiply_vv(a, b, b)

.. note:: This module exists only as a stop-gap until support for element-wise operations
   with memoryviews is implemented in Cython. It will be phased out once Cython with Mark
   Florisson's `array expressions`_ `pull request`_ merged is released.

.. module:: ceygen.elemwise

Vector-scalar Operations
========================

.. function:: add_vs(x, y[, out=None])

   Add scalar *y* to each coefficient of vector *x* and return the resulting vector.

   Note: there's no **subtract_vs**, just add opposite number.

   :param x: first addend (vector)
   :type x: |vector|
   :param y: second addend (scalar)
   :type y: |scalar|
   :param out: |out_elemwise|
   :type out: |vector|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |vector|

.. function:: multiply_vs(x, y[, out=None])

   Multiply each coefficient of vector *x* by scalar *y* and return the resulting vector.

   Note: there's no **divide_vs**, just multiply by inverse number.

   :param x: first addend (vector)
   :type x: |vector|
   :param y: second addend (scalar)
   :type y: |scalar|
   :param out: |out_elemwise|
   :type out: |vector|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |vector|

Vector-vector Operations
========================

.. function:: add_vv(x, y[, out=None])

   Vector-vector addition: *x* + *y*

   :param x: first addend
   :type x: |vector|
   :param y: second addend
   :type y: |vector|
   :param out: |out_elemwise|
   :type out: |vector|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |vector|

.. function:: subtract_vv(x, y[, out=None])

   Vector-vector subtraction: *x* - *y*

   :param x: minuend
   :type x: |vector|
   :param y: subtrahend
   :type y: |vector|
   :param out: |out_elemwise|
   :type out: |vector|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |vector|

.. function:: multiply_vv(x, y[, out=None])

   Vector-vector element-wise multiplication: *x* \* *y*

   :param x: first factor
   :type x: |vector|
   :param y: second factor
   :type y: |vector|
   :param out: |out_elemwise|
   :type out: |vector|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |vector|

.. function:: divide_vv(x, y[, out=None])

   Vector-vector element-wise division: *x* / *y*

   :param x: numerator
   :type x: |vector|
   :param y: denominator
   :type y: |vector|
   :param out: |out_elemwise|
   :type out: |vector|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |vector|

Matrix-scalar Operations
========================

.. function:: add_ms(x, y[, out=None])

   Add scalar *y* to each coefficient of matrix *x* and return the resulting matrix.

   Note: there's no **subtract_ms**, just add opposite number.

   :param x: first addend (matrix)
   :type x: |matrix|
   :param y: second addend (scalar)
   :type y: |scalar|
   :param out: |out_elemwise|
   :type out: |matrix|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |matrix|

.. function:: multiply_ms(x, y[, out=None])

   Multiply each coefficient of matrix *x* by scalar *y* and return the resulting matrix.

   Note: there's no **divide_ms**, just multiply by inverse number.

   :param x: first addend (vector)
   :type x: |matrix|
   :param y: second addend (scalar)
   :type y: |scalar|
   :param out: |out_elemwise|
   :type out: |matrix|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |matrix|

Matrix-matrix Operations
========================

.. function:: add_mm(x, y[, out=None])

   Matrix-matrix addition: *x* + *y*

   :param x: first addend
   :type x: |matrix|
   :param y: second addend
   :type y: |matrix|
   :param out: |out_elemwise|
   :type out: |matrix|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |matrix|

.. function:: subtract_mm(x, y[, out=None])

   Matrix-matrix subtraction: *x* - *y*

   :param x: minuend
   :type x: |matrix|
   :param y: subtrahend
   :type y: |matrix|
   :param out: |out_elemwise|
   :type out: |matrix|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |matrix|

.. function:: multiply_mm(x, y[, out=None])

   Matrix-matrix element-wise multiplication: *x* \* *y*

   :param x: first factor
   :type x: |matrix|
   :param y: second factor
   :type y: |matrix|
   :param out: |out_elemwise|
   :type out: |matrix|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |matrix|

.. function:: divide_mm(x, y[, out=None])

   Matrix-matrix element-wise division: *x* / *y*

   :param x: numerator
   :type x: |matrix|
   :param y: denominator
   :type y: |matrix|
   :param out: |out_elemwise|
   :type out: |matrix|
   :raises: |valueerror|
   :raises: |typeerror|
   :rtype: |matrix|

.. _`array expressions`: https://github.com/markflorisson88/minivect/raw/master/thesis/thesis.pdf
.. _`pull request`: https://github.com/cython/cython/pull/144

.. include:: definitions.rst
