#######
Traces
#######

=======
Trace
=======

.. autoclass:: mhi.enerplot.Trace
	:members: data, domain, read_only, increasing, decreasing


================
Basic Operations
================

Many basic operations are already possible on a :class:`.Trace`.
All operations return a new trace; the original trace is unmodified.

Given the trace ``a`` the following unary operations exist:

.. table::

   =================== =======================================
   Operators           Operation
   =================== =======================================
   ``len(a)``		   Number of data points in the trace
   ``a[n]``		       Access the n-th data point in the trace
   ``-a``              Negation of all values in the trace
   ``abs(a)``          Absolute value of all values
   ``math.ceil(a)``    Values rounded up to an integer
   ``math.floor(a)``   Values rounded down to an integer
   ``math.trunc(a)``   Values truncate towards zero
   =================== =======================================

Given two traces, ``a`` and ``b``, or a trace and a scalar number
in either order, the following operations exist:

.. table::

   =================== ======================================
   Operators           Operation
   =================== ======================================
   ``a + b``           Addition
   ``a - b``           Subtraction
   ``a * b``           Multiplication
   ``a / b``           Division
   ``a ** b``          Exponentiation
   =================== ======================================

.. note::

	If an operation is performed on two traces of different lengths,
	these operations will the result in a trace which matches the
	length of the shorter of the two traces.  The extra data in the
	longer trace is ignored.

===================
Convolution
===================

Given two traces, ``a`` and ``b``, the operation ``a @ b`` returns
a convolution of the two traces.

For example, given the Finite Impulse Response of a transfer function,
the output signal can be created by convolving the input with the
finite impulse response::

    fir = mhi.enerplot.Trace([0.75, 1.0, 0.5, 0.25, 0.125])

    output = input @ fir

The length of the output is 1 sample less than the sum of the lengths
of the two input traces.


===================
Other Operations
===================

.. currentmodule:: mhi.enerplot.math

Additional operations on traces require importing methods from the
``mhi.enerplot.math`` library.

Example:

	The following computed trace would approximate the full wave
	rectifier output::

		from mhi.enerplot.math import minimum, maximum
		
		cigre = enerplot.datafile('Cigre_47.csv')
		
		a = cigre[r'Rectifier\AC Voltage:1']
		b = cigre[r'Rectifier\AC Voltage:2']
		c = cigre[r'Rectifier\AC Voltage:3']
		
		rectifier_out = maximum(a, b, c) - minimum(a, b, c)




Logarthimic
===========

.. autofunction:: exp
.. autofunction:: ln
.. autofunction:: log
.. autofunction:: log10
.. autofunction:: sqrt


Circular
=========

.. autofunction:: degrees
.. autofunction:: radians
.. autofunction:: sin
.. autofunction:: cos
.. autofunction:: tan
.. autofunction:: asin
.. autofunction:: acos
.. autofunction:: atan
.. autofunction:: hypot
.. autofunction:: atan2


Selection
==========

.. autofunction:: maximum
.. autofunction:: minimum


Processing
===========

.. autofunction:: smooth
