==================
Pattern generation
==================

Abstraction module for signals. The signal module allows the creation of signals entities, characterized by a series of parameters and linked to a particular pattern generator (PG). The signal module is agnostic about the PG. Communicates to the device via a secondary module from which it requires a specific API. It is up to that module to send the appropriate commands to the PG. The module can use (or not) one of the available lower-level interfacing modules (:doc:`GPIB <cmd_gpib>`, :doc:`TCP <cmd_tcp>`, :doc:`serial <cmd_serial>`).

As of this writing, modules for the following PG are implemented:

.. toctree::
    :titlesonly:

    Agilent 33200 series <cmd_ag_33200>
    Agilent 33500 series <cmd_ag_33500>
    Agilent 81160 <cmd_ag_81160>
    Tektronix AFG 3000 series <cmd_tk_afg3000>

On the following, the signal module and the way to implement new PG modules compatible with it is described. For information on how to interface with the bus modules, refer to :doc:`their documentation <buses>`.

.. figure:: cmd_signal.doc.png
    :align: center
    :scale: 50%

    Figure 1: Example of interaction between cmd_signal, PG modules and pyrame bus modules (gpib, serial, tcp). 

Pool and identification
=======================

Every signal in the pool is identified uniquely by an identifier passed to the function :py:func:`init_signal <cmd_ps.init_signal>`. All the other functions require this *id* token as the first argument.

During init_signal, the initialization function for the particular model is called. Its name must be *init_MODEL* (e.g.: :py:func:`init_ag_33500 <cmd_ag_33500.init_ag_33500>`). The convention style for MODEL is a two-letter maker symbol plus the model, separated by an underscore (_).

Initialization
==============

As pointed out previously, cmd_signal provides a function init_signal and requires functions init_MODEL from the modules with which it interfaces. The init_signal declaration is:

.. py:function:: init_signal (signal_id,conf_string,function,hl,ll,freq,dc,pw,re,fe,sym,phase,delay,sync)

    Registers in the pool and initializes a new PS with *signal_id*. *conf_string* is the configuration string for the module to be initialized. On pulse generators supporting multiple channels, the *conf_string* must include the parameter chan to indicate the channel that will be used. An identificator will be needed for each channel.

The init_MODEL functions of pattern generators must accept a conf_string and initialize all necessary memory structures. Communication with the hardware is performed with the config_MODEL function.

Functions
=========

cmd_signal requires a set of functions on the API of the pulse generator module in order to be compatible with it:

- init_MODEL (*MODEL_id*, *conf_string*, *function*, *hl*, *ll*, *freq*, *dc*, *pw*, *re*, *fe*, *sym*, *phase*, *delay*, *sync*)
- deinit_MODEL (*MODEL_id*)
- config_MODEL (*MODEL_id*)
- inval_MODEL (*MODEL_id*)
- power_on_MODEL (*MODEL_id*)
- power_off_MODEL (*MODEL_id*)

In addition, at least one configure\_FUNCTION function must be implemented. Each one will provide support for the FUNCTION (e.g.: sine) function, as configured with :py:func:`init_signal <cmd_signal.init_signal>` or :py:func:`set_function_signal <cmd_signal.set_function_signal>`. The :py:func:`power_on_signal <cmd_signal.power_on_signal>` function of cmd_signal will look for a matching configure\_FUNCTION function in the module. configure\_FUNCTION functions must have a few mandatory arguments: *MODEL_id*, *frequency*, *sync*, *high_level*, *low_level*. Then, depending on the FUNCTION, the following arguments will need to follow:

  - configure_sine_MODEL (*MODEL_id*, *frequency*, *sync*, *high_level*, *low_level*, *phase*)
  - configure_square_MODEL (*MODEL_id*, *frequency*, *sync*, *high_level*, *low_level*, *phase*, *duty_cycle*)
  - configure_ramp_MODEL (*MODEL_id*, *frequency*, *sync*, *high_level*, *low_level*, *phase*, *symmetry*)
  - configure_pulse_MODEL (*MODEL_id*, *frequency*, *sync*, *high_level*, *low_level*, *delay*, *pulse_width*, *rising_edge*, *falling_edge*)

.. note::

    Pulse generators not accepting certain parameters must check that their value is undef.

In all cases:

- Magnitudes (i.e.: voltage, current, slew_rate, etc.), either sent or returned, must be expressed in base units of the International System of Units (V, A, V/s, etc.).

API
===

.. automodule:: cmd_signal
   :members:
   :member-order: bysource