Useful Resources
****************

.. contents::
    :depth: 1
    :local:
    :backlinks: top

.. _tigresquickref:

Quick Reference
===============

Basic steps to create a workflow
--------------------------------

| **(1)** Define input types and values for tasks **(2)** Create tasks
| **(3)** Create (and run) template with tasks and inputs and use output from template for next stage of workflow.

Data Types
----------

| :code:`Task`: Function or program; atomic unit of execution
| :code:`TaskArray`: List of one or more Tasks, which will be executed in a Template
| :code:`InputTypes`: Types for inputs of a Task.
| :code:`InputValues`: Values for inputs of a Task.
| :code:`InputArray`: One or more InputValues, which will be inputs to a TaskArray in a Template

| **Templates:**
|   :code:`sequence`: List of tasks placed in series; output of one is the input of the next
|   :code:`parallel`: List of tasks processing their inputs in parallel
|   :code:`split`: “split” task feeding inputs to a set of parallel tasks
|   :code:`merge`: Collect output of parallel tasks

Functions
---------

.. note::
    Name is an optional parameter in all below functions.

(1) Create inputs for tasks
+++++++++++++++++++++++++++

=====================          =====================================================================================
Description                    Functions and examples
=====================          =====================================================================================
Create InputTypes               | :class:`tigres.InputTypes`
                                | :code:`input_type_1 = InputTypes("Types1", [int, str])`
Create InputValue               | :class:`tigres.InputValues`
                                | :code:`input_value_1 = InputValues("Values1", [1, "hello"])`
Create InputArray               | :class:`tigres.InputArray`
                                | :code:`input_array_12 = InputArray("Array12", [input_value_1, input_value_2])`
=====================          =====================================================================================

(2) Create tasks and task arrays
++++++++++++++++++++++++++++++++

=====================          =====================================================================================
Description                    Functions and examples
=====================          =====================================================================================
Create a Task	                | :class:`tigres.Task`
                                | :code:`task_f1 = Task("A", FUNCTION, "myfunc", input_type_1)`
                                | :code:`task_x1 = Task("X", EXECUTABLE, "./bin/x", input_type_1)`
Create a TaskArray              | :class:`tigres.TaskArray`
                                | :code:`task_array_xyz = TaskArray("xyz", [task_f1, task_x1])`
                                | :code:`task_array_12 = TaskArray("tasks12", [task_f1, task_f2])`
=====================          =====================================================================================

(3) Create templates
++++++++++++++++++++

=====================          ==========================================================================================
Description                    Functions and examples
=====================          ==========================================================================================
Sequence                        | :func:`tigres.sequence`
                                | :code:`output = sequence("my_sequence", task_array_12, input_array_12)`
Data parallel	                | :func:`tigres.parallel`
                                | :code:`output = parallel("abc", task_array_12, input_array_12)`
Split	                        | :func:`tigres.split`
                                | :code:`output = split("split", task_x1, input_value_1, spl_taskarray, spl_input_array)`
Merge	                        | :func:`tigres.merge`
                                | :code:`output = merge("sync", syn_ta, syn_ia, task_x1, input_value_1)`
=====================          ==========================================================================================


Constants and Special Notations
+++++++++++++++++++++++++++++++

===============================  ==========================================
Constant                         Description
===============================  ==========================================
FUNCTION                         Function in current program
EXECUTABLE                       Different program to execute
PREVIOUS.task_name.i[output_no]  Output number of previous task task_name
===============================  ==========================================

.. _tigresprogramskeleton:

Program Skeleton
================
Below is a skeleton to help kickstart writing your Tigres code. This will allow you to specify
different Execution plugins.
You can download the Tigres skeleton program :download:`here <_static/code/tigres_program_skeleton.py>`

.. literalinclude:: _static/code/tigres_program_skeleton.py
    :language: python
    :emphasize-lines: 6-7,13,18
    :linenos:

This program allows you to execute your workflow with any of the available execution plugins. If you execute this
python code, you will see all the available execution plugins::

    $ python hello_world_parallel.py
    Usage: hello_world_parallel.py (EXECUTION_SLURM|EXECUTION_DISTRIBUTE_PROCESS|EXECUTION_LOCAL_THREAD|EXECUTION_LOCAL_PROCESS|EXECUTION_SGE)>


Execute the script with :code:`EXECUTION_LOCAL_THREAD`::

    $ hello_world_parallel.py EXECUTION_LOCAL_THREAD

There is no output to the screen but you will see a log file in the current directory::

    $ ls
    hello_world_parallel.log	hello_world_parallel.py


.. include:: /includes/program_skeleton_description.rst