================
Virtual Channels
================

Virtual channels are software-defined channels as compared to the real input channels. Virtual channels can be understood as a stream flow processing units. They have an input through which they receive time-tags from a real or another virtual channel and output to which they send processed time-tags.

Virtual channels are used as input channels to the measurement classes the same way as real channels. Since the virtual channels are created during run-time, the corresponding channel number(s) are assigned dynamically and can be retrieved using :meth:`~VirtualChannel.getChannel()` or :meth:`~VirtualChannel.getChannels()` methods of virtual channel object.


Available virtual channels
--------------------------------------------------------------------------------

.. note::

    In MATLAB, the Virtual Channel names have common prefix ``TT*``. For example: ``Combiner`` is named as ``TTCombiner``. This prevents possible name collisions with existing MATLAB or user functions.

`Coincidence`_
  Detects coincidence clicks on two or more channels within a given time window.
`Coincidences`_
  Detects coincidence clicks on multiple channel groups within a given time window.
`Combinations`_
  Detects coincidence clicks on all possible combinations of given channels within a given time window, preceded and followed by two guard windows of the same width without any events on these channels.
`Combiner`_
  Merges events from multiple channels into a single channel.
`ConstantFractionDiscriminator`_
  Detects rising and falling edges of an input signal and returns the average time.
`DelayedChannels`_
  Creates delayed replicas input channels.
`EventGenerator`_
  Generates a signal pattern for each trigger event.
`FrequencyMultiplier`_
  Multiplies the frequency of a periodic signal on a channel.
`GatedChannels`_
  Passes input signals only while the gate is open, defined by start and stop trigger channels.
`TriggerOnCountrate`_
  Generates an event when the count rate of a given channel crosses given threshold value.


.. |common methods vch| replace:: :ref:`See all common methods<common-methods-vch>`

.. _common-methods-vch:

Common methods
-------------------

.. method:: VirtualChannel.getChannel()
            VirtualChannel.getChannels()

   Returns the channel number(s) corresponding to the virtual channel(s). Use this channel number the very same way as the channel number of physical channel, for example, as an input to a measurement class or another virtual channel.

   .. important::

       Virtual channels operate on the time tags that arrive at their input. These time tags can be from rising or falling edges of the physical signal. However, the virtual channels themselves do not support such a concept as an inverted channel.


.. method:: getConfiguration()
    :noindex:

    Returns configuration data of the virtual channel object. The configuration includes the name, 
    values of the current parameters and the channel numbers.
    Information returned by this method is also provided with :cpp:func:`~TimeTaggerBase::getConfiguration`.

    :returns: Configuration data of the virtual channel object.
    :rtype: dict

.. _api.Coincidence:

Coincidence
-----------

.. doxygenclass:: Coincidence

.. _api.Coincidences:

Coincidences
------------

.. doxygenclass:: Coincidences

.. _api.Combinations:

Combinations
--------------------

.. doxygenclass:: Combinations

.. _api.Combiner:


Combiner
----------------

.. doxygenclass:: Combiner
    :members: Combiner

ConstantFractionDiscriminator
-----------------------------

.. doxygenclass:: ConstantFractionDiscriminator
    :members: ConstantFractionDiscriminator

.. _api.DelayedChannels:

DelayedChannels
---------------

.. doxygenclass:: DelayedChannels
    :members: DelayedChannels, setDelay

.. doxygenclass:: DelayedChannel
    :members: DelayedChannel

.. _api.EventGenerator:

EventGenerator
--------------

.. doxygenclass:: EventGenerator
    :members: EventGenerator

FrequencyMultiplier
-------------------

.. doxygenclass:: FrequencyMultiplier

.. _api.GatedChannels:


GatedChannels
-------------

.. doxygenclass:: GatedChannels

.. doxygenclass:: GatedChannel


TriggerOnCountrate
------------------

.. plot:: figures_engine/TriggerOnCountrate.py
    :align: center

.. doxygenclass:: TriggerOnCountrate