Tutorial

The purpose of the sequencer is to execute Sequencer scripts, either for engineering or science purposes.

The unit of execution is a single step which is just a normal python function or method with no input parameters.

Sequences are modeled as Directed Acyclic Graph (DAG). Each node in the graph can either be a simple action which just invokes a single sequencer step or a more complex node which contains a complete sequencer script.

This allows sequences to be grouped and nested freely. Ultimately they will execute steps.

The Sequencer API allows to create these graphs.

Building Sequences

Sequencer scripts are modeled as DAGs, the Sequencer API allows to create nodes in the DAG. There are different node types that determine the way its children are scheduled for execution (e.g. Parallel, Sequential), you are free to select, mix and match the node type(s) that suits better to your needs.

Each node in the DAG depends, for execution purposes, from its parent nodes. Meaning that a node will not be started until every node that precedes it has finished its own execution.

The Sequencer Engine expects to find either a module method or a specific class in a module in order to construct a Sequencer script from it. The conventions are the following.

1. A module level create_sequence() function. See Tutorial 1.

2. A class named Tpl which must provide a static method create_sequence. See Parallel tasks sample.

In either case, the return value is the root node of the graph being implemented.

The first convention is tried first, if no create_sequence() function is found, the second convention is attempted.

For very simple scripts, following the first convention is perfectly fine. For more complex scripts, e.g. one is creating a class and methods to control .e.g. a detector, and it is going to be instantiated many times to control many detectors in parallel, the class approach is advised.

Node Dependencies

Node dependencies determines the execution order of the sequence steps. A node wont’t run until all its dependencies have finished. In the graph, a node dependency is seen as an icoming edge.

The basic node types Sequence and Parallel defines a dependency hierarchy.

Sequence nodes are executed one after the other, therefore each node depends on its predecessor. On the other hand, Parallel nodes indicates that all nodes it contains shall be executed together. By combining and chaining this two basic node types it is possible to express any dependency graph.

Very simple sequences

Let’s start with a simple sequence.

As mentioned before the simplest step is a python coroutine with no input parameters which is used to create an Action node.

Note

The no input parameter rule can be bypassed with strategies shows in Passing Arguments to Actions

In this case, we define a sequence that executes two steps, one after the other, namely do_a() and do_b(). Source codes is shown below.

Tutorial 1

""" Sequencer tutorial 01.

The simplest sequence.
Execute one step after the other.
"""
import asyncio
from seqlib.nodes import Sequence, Action


async def do_a():
    print("A")


async def do_b():
    await asyncio.sleep(1)
    print("B")


def create_sequence(*args, **kw):
    """Creates a simple sequence"""
    return Sequence.create(
        Action(do_a, name="A"), do_b, name="Tut_01"
    )

Important

The Sequencer Engine is based on asyncio library, therefore it is biased towards coroutines, but they are not mandatory as shown in Loop example.

There are some simple rules to create sequences:

• A step (Action) is a python coroutine with no input parameters. See Passing Arguments to Actions to break this rule.

• In this case, the sequence is created using the Sequence.create (Sequence) constructor, which receives the steps to be executed (in the given order).

• The python module which contains the sequence must define a create_sequence function as shown in the example. It returns a Sequence node that holds the nodes (Action (s) in this case) that it will execute.

Note

The Sequence.create constructor provides syntax sugar in order to support passing coroutines as the sequence’s grapn nodes (do_b in the above example). In such a case a node of type seq.nodes.Action is automagically created and inserted in the graph.

This simple sequence 01 is graphically shown below.

simple sequence 01

Notice that despite that in the create_sequence() function only two nodes were specified, the simple sequence 01 figure shows 4 nodes. The sequencer engine adds a start node (black circle) and end node (double black circle) to every node container type, i.e. those nodes that have children: Parallel, Sequence and Loop.

Note

The start and end node, among other things, makes easy to chain nodes together by linking the end node of a container with the start of the next.

Executing Tasks in Parallel

One is not limited to create just linear sequences. Parallel activities (pseudo parallel) can be created using the Parallel.create() constructor. It receives the same parameters as the Sequence node constructor. When executed, the sequencer engine processes the :class:’Parallel’ nodes children in parallel.

Parallel tasks sample

"""
Defines a sequence where activities are executed in (pseudo) Parallel.
"""
import asyncio
from seqlib.nodes import Action, ActionInThread, Parallel


class Tpl:
    def do_a(self):
        """I don't need to be a coroutine"""
        print("A")

    async def do_b(self):
        await asyncio.sleep(1)
        print("B")

    @staticmethod
    def create(*args, **kw):
        t = Tpl()
        return Parallel.create(
            ActionInThread(t.do_a, name="one"),
            Action(t.do_b, name="two"),
            name="Tut_02",
        )

Which is represented graphically as follows.

Parallel Sequence

Points to notice:

1. In this case the Sequencer Engine discover a class named Tpl and calls its create method (@staticmethod as the convention mandates).

2. The example Parallel Sequence also shows that steps are not limited to coroutines. Just wrap it in ActionInThread node.

In order to avoid normal methods or functions to potentially block the asyncio loop (by holding th e CPU) they must be executed on their own Thread.

This is achieved with the ActionInThread node. In the example the do_a() method is wrapped in such node. Otherwise the Sequence constructor will complain and raise an exception.

Executing Tasks in a Loop

The Loop node allows to repeat a set of steps while a condition is True.

Loop example

"""
Defines a Loop
"""
import asyncio
from seqlib.nodes import Action, ActionInThread, Loop


def do_a():
    """I don't need to be a coroutine"""
    print("A")


async def do_b():
    await asyncio.sleep(1)
    print("B")


async def do_c():
    print("C")


async def my_condition():
    """Loop.index is a contex variable. Use get() to access it"""
    return Loop.index.get() < 5


def create_sequence(*args, **kw):
    """Creates a simple sequence"""

    return Loop.create(
        ActionInThread(do_a, name="one"),
        Action(do_b, name="two"),
        Action(do_c, name="three"),
        condition=my_condition,
        name="Tut_Loop",
    )

Which is represented graphically as follows.

Loop example

As the code in Loop example shows, the Loop’s constructor takes a variable number of arguments as the Loop’s body, the part that is repeated, do_a(), do_b() and do_c() in this case. The condition node is specified with the condition keyword.

The Loop’s index is kept in the context variable index, meaning it can be accessed as Loop.index.get() as the my_condition() function shows.

In order to separate the index value of the different loops that might be occurring at the same time the Loop’s index is implemented as a context variable. Therefore to get its value one has to call its get() method as the my_condition() function shows.

Embedding Sequencer Scripts

Sequences can be reused or embedded in order to produce more complex activities. The following example uses the sequences “Tut_01” and “Tut_02” to create a new sequence and just for the kicks it puts each one in a different Loop, combined with a couple of local functions.

Important

Embedding a Sequence entails to import the module and instantiate its Sequencer script (either with create_sequence() or by Tpl.create(). But how do you know which one to call? You don’t have to know. You let the OB object do it for you as:

from seqlib.ob import OB
from seq.samples.tut import tut01

mynode = OB.create_sequence(tut01)

Sequence embedding example

""" Tut03 - Sequence embedding

Defines a sequence reusing other sequencer scripts.
"""
from seqlib.nodes import Loop, Parallel
from seq.samples.tut import tut01, tut02
from seqlib.ob import OB


async def do_something():
    print("something")


async def a_condition():
    return Loop.index < 5


async def b_condition():
    return Loop.index < 3


def create_sequence():
    a = OB.create_sequence(tut01)
    # .create_sequence()
    b = OB.create_sequence(tut02)
    # .create_sequence()

    loop_a = Loop.create(
        a, do_something, condition=a_condition
    )
    loop_b = Loop.create(
        b, do_something, condition=b_condition
    )

    return Parallel.create(
        loop_a, loop_b, name="EMBED_SAMPLE"
    )

Some points to note:

• Use seqlib.ob.OB.create_sequence() to select the right method to instantiate a predefined sequencer script, so it can be reused.

• There are two loops. Each condition node has its own copy of Loop.index.

The graphical representation of Sequence embedding example is shown at embedded sequence, it has many levels due to the two loops running in parallel.

embedded sequence

Conclusion

This finishes the basic tutorial. One can create any type of flow using the node types show. Mor details about node’s attributes and context are given in A Deeper Look.