Tasks

The Task class is one of the fundamental blocks of an UPSTAGE simulation. It controls the changes to Actor states and coordinates with the underlying SimPy event queue.

Tasks are defined by subclassing from Task and creating the task method. In the example below, the task is properly typed. UPSTAGE provides a type hint for the generator object that task() is. Not also that actor is a required named argument.

import upstage_des.api as UP
from upstage_des.type_help import TASK_GEN

class Lathe(UP.Actor):
    outgoing_bin = UP.ResourceState[UP.SelfMonitoringStore]()


class UseLathe(UP.Task):
    def task(self, *, actor: Lathe) -> TASK_GEN:
        """Run the lathe task."""
        piece = self.get_actor_knowledge("work_piece", must_exist=True)
        time = actor.estimate_work_time(piece)
        yield UP.Wait(time)
        piece.status = "Done"
        actor.number_worked += 1
        yield UP.Put(actor.outgoing_bin, piece)

In that example, the task yields out UPSTAGE Events only, which is the typical usage. UPSTAGE will also let you yield a simpy process, but this will raise a warning and is discouraged as interrupt handling and other services won’t work. If a process is yielded on, and your task is interrupted, the yielded process will receive an interrupt as well.

Tasks only allow one actor, so use Knowledge to help manage interactions or other information. For more complex interactions, see State Sharing.

Interrupts

Task interruption, by default, will raise the usual SimPy exception. The user can add the on_interrupt method to their task subclass to handle interruption. That method must accept an actor, a cause object, and must return a enumerator that tells UPSTAGE how to handle the interruption.

See Interrupts for more.

Decision Tasks

Decision tasks are a special form of Task that does not touch the simulation queue, except for a zero time wait. The zero-time wait exists so the user knows that other decision tasks may run before the Actor using the task proceeds on to the next yield statement.

Subclass and implement make_decision to use the class. The rehearse_decision method can also be implemented to provide rehearsal decision making. That is useful for separating planning and action code when the simpy clock will not be advancing.

See Decision Tasks for more.

Rehearsal

Rehearsal is a feature for estimating the results of a Task on a “cloned” Actor to examine actor state for planning purposes. See Rehearsal for more.