========
Pycaldaq
========

Pycaldaq is a suite of Python code that allows users to easily interact with Pyrame, and more specifically the Run Control. It also allows to launch those scripts throught the graphical interface, once installed in `/opt/pyrame/rc_scripts/`.

For example, it allows to execute any transition of the :doc:`Calicoes state machine <launch>`.

We will analyze a simple run script to understand the way to use it:

.. code:: python

  #!/usr/bin/env python2

  def timed_run_init():
      declare_param("run_name","name of run","test")
      declare_param("acq_time","duration of acquisition (min)","1")

  def timed_run_run(run_name,acq_time):
      run=new_run(run_name)
      timed_acq("%s_minutes"%(acq_time),run,float(acq_time)*60)
      wait_run_finished(run)

  def timed_run_get_progress():
      return progress_acq

  execfile("/opt/calicoes/pycaldaq_rcs.py")

The name of the script is `timed_run`. The filename must therefore be named `timed_run.py`. At least one function named `NAME_run` must exist. In this case that is `timed_run_run`. Two more functions can optionally be used:

  - NAME_run: This is the main function that runs the script.
  - NAME_init: This is the initialization function. It is run when loading the script and is typically used to declare parameters. The declaration of parameters allows to define a description and a default value. This is how GUIs can expose meaningful dialogs for scripts.
  - NAME_get_progress: This function must return the progress status of the script at any moment. In the example, timed_acq sets a global variable named `progress_acq` that we can use externally.

At the end of the script, the mandatory `execfile("/opt/calicoes/pycaldaq_rcs.py")` command is required. `pycaldaq_rcs.py` will in turn load the required Pyrame's `/opt/pyrame/rc_script.py`.

These scripts can be simply executed as `./timed_run.py` or through the GUI.

See more information about `Run Control Scripts on Pyrame's documentation <http://llr.in2p3.fr/sites/pyrame/documentation/cmd_rc.html>`_.

Functions available to scripts
==============================

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

As you can see, it is very easy to create calibration sequences with this tool. You are also free to launch an analysis tool at every iteration with the `rc_exec` command. This tool can generate :py:func:`reconfigure <pycaldaq_rcs.reconfigure>` patterns (in a file for example) that can be applied by the `run_cmdfile` pycaldaq script.