.. _replay:

=========================================
System simulation by replaying data files
=========================================

**Events files** and **raw files** may be used to simulate a running system.
Raw files contain all the information generated by a running system (*i.e.* status messages, start and stop timestamps, configuration files,...).
Events files contain only the processed events and can only simulate a stream of processed data.

Using ``replay_raw`` or ``replay_raw.py`` a raw file may be replayed simulating a full working system.
``replay_raw.py`` also supports raw files compressed with ``gzip``, ``bzip2``, or ``xz``.
If python is not available, the C version of ``replay_raw`` may be used, but it does not support compressed raw files.
Only ``replay_raw.py`` supports the replay of ``waan`` status messages saved in the raw files.
``replay_events`` supports only ``.ade`` files.

.. warning::
    Any running instance of the hardware interfacing modules will always conflict with any replay, because the replaying will try to substitute the hardware interfacing module. 

.. warning::
    A running instance of ``waan`` conflicts with ``replay_raw.py`` if the replay of the ``waan`` status messages is enabled.
    For this reason this feature is disabled by default.

.. _replay-raw:

Replaying raw files
-------------------

All the programs have an in-line help that can be viewed launching them with the ``-h`` option::

    user-tutorial@abcd-tutorial:~$ replay_raw.py -h
    usage: replay_raw.py [-h] [-T BASE_PERIOD] [-S ABCD_STATUS_ADDRESS] [-D ABCD_DATA_ADDRESS]
                         [-W WAAN_STATUS_ADDRESS] [-w] [-s SKIP_PACKETS] [-v] [-c]
                         file_name

    System simulator that uses ABCD raw files, supporting also compressed files.

    positional arguments:
      file_name             Input file name

    options:
      -h, --help            show this help message and exit
      -T BASE_PERIOD, --base_period BASE_PERIOD
                            Set base period in milliseconds (default: 100.000000 ms)
      -S ABCD_STATUS_ADDRESS, --abcd_status_address ABCD_STATUS_ADDRESS
                            abcd status socket address (default: tcp://*:16180)
      -D ABCD_DATA_ADDRESS, --abcd_data_address ABCD_DATA_ADDRESS
                            Data socket address (default: tcp://*:16181)
      -W WAAN_STATUS_ADDRESS, --waan_status_address WAAN_STATUS_ADDRESS
                            waan status socket address (default: tcp://*:16206)
      -w, --enable_waan_status
                            Enable the publication of waan status messages
      -s SKIP_PACKETS, --skip_packets SKIP_PACKETS
                            Skip initial packets (default: 0)
      -v, --verbose         Set verbose execution
      -c, --continuous_execution
                            Enable continuous execution

The default settings should give a working replay.
The ``--base_period`` option changes the repetition rate of the messages that are sent through the sockets.
The smaller this number, the faster the repetition rate will be.
This could be useful for a faster replaying of experiments with a very small acquisition rate, to speedup an offline analysis.
The ``--continuos_execution`` option enables an infinite repetition loop of the data file being replayed.
The normal operation mode of the replaying is to stop at the end of the file.
This option could be useful for a user that wants to test on-line analysis procedures.

.. _replay-events:

Replaying events files
----------------------

Since events files contain only processed events, replaying them will only generate a stream data without the other information about the acquisition.
The replaying program has an in-line help::

    user-tutorial@abcd-tutorial:~$ replay_events -h
    Usage: ./replay_events [options] <file_name>
    
    System simulator that uses ABCD events files.
    
    Optional arguments:
    	-h: Display this message
    	-v: Set verbose execution
    	-V: Set verbose execution with more details
    	-S <address>: Status socket address, default: tcp://*:16180
    	-D <address>: Data socket address, default: tcp://*:16181
    	-T <period>: Set base period in milliseconds, default: 100
    	             For a very fast replay, 0 ms is also accepted.
    	-B <size>: Events output buffers size, default: 1024
    	-s <pknum>: Skip pknum packets, default: 0

The ``-T`` option works as the aforementioned ``--base_period`` option in the :numref:`replay-raw`.
The ``-B`` option sets the number of processed events that are shipped for each message.
The messages structure is lost when the data is saved in the events file, thus the user has to choose the desired buffer size.

.. note::
    Both ``replay_raw.c`` as well as ``replay_raw.py`` may also be used by the users as an example of how to directly read and process raw file.