Tech Note

Title:               GraphContext Contents in The Simulation Object Model
Date:              March 19, 2003
Written by:     Peter C. Bosch
Number:        TN-004
Version:         0.2

Note – See TN-001 for a discussion of the Task Graph Architecture and a discussion of the purpose of the GraphContext. This tech note will discuss the actual contents of the Simulation Object Model GraphContext. As an aside, it will discuss the pre- and post-state snapshots attributed to each unit, and filled in as the task graph executes.

A SOMOperation provides on most of its events, and requires on many of its member functions, an IDictionary called graphContext.  Recall that a task graph is a recipe or plan for accomplishing something, and as such, it is a static description of a procedure to follow. Assuming that we do not want to replicate copies of the recipe for each instance of execution, and furthermore acknowledging that we may be executing the recipe in several such instances at the same time, there must be a way to store the data (primitives and objects) that describes the dynamic progress of that execution outside of the recipe, or task graph. That mechanism is the graphContext, a hashtable that is passed through the thread of execution (this is not necessarily an operating system thread) of a particular instance of execution of that recipe. This instance of execution is, of course, correlates to the Batch – and in fact, the GraphContext can be acquired through the Batch.GraphContext property. Since the thread of execution transits potentially many units, and each unit has equipment state, it follows that there are many unit states stored in each graphContext by the time it has completed.

The graphContext contains most information relevant to dynamic aspects of that traversal. There are, in many cases, two ways to extract that information – helper methods, and directly querying the graphContext.

Raw-Accessible Keys

Each task has a number of keys that are used to store objects in the GraphContext. These are described in the table below.

Key

Object

Type

Description

Task.Unit

Unit Context

UnitContext

Contains TargetEquipment, EquipmentResourceRequest and ValidationStateTargetEquipment[1]

String keys

Resource Requests

IResourceRequest

Each resource request known to a task in a particular execution thread, is maintained in the GraphContext.

Task.
m_preExecution
EquipmentStateKey

Equipment State

IMemento

This is the unit state prior to execution of the given task.

Task.
m_postExecution
EquipmentStateKey

Equipment State

IMemento

This is the unit state following execution of the given task.

“SOMBatch”

SOM Batch

SOMBatch

This is the SOMBatch object that initiated this thread of execution.

“PostMortemData”

Post Mortem Data

PMData

This is an object that contains diagnostic information on which vertices fired and which edges were run.

Task.
SelfStartTimeKey

Time of task start

DateTime

This is the time that execution of the task began.

Task.
SelfFinishTimeKey

Time of task
finish

DateTime

This is the time that execution of the task finished.

various

object

Other esoteric objects may be stored, such as vertex execution data…

 

Shortcut Accessor Methods

There are accessor methods in various places that will give you access to the embedded data elements without the use of a key. The following table depicts the major ones.

Base Object

Method

What it returns

SOMTask

GetCurrentEquipment(GraphContext)

Equipment

Equipment

Mixture

Mixture in the equipment

Equipment

Volume

Volume of the equipment

SOMTask

GetCurrentMixture(GraphContext)

Mixture in current equipment

SOMTask

GetPreState(GraphContext)

The IMemento recorded as the precursor unit state.

SOMTask

GetPostState(GraphContext)

The IMemento recorded as the post-execution unit state.

 

So Where IS Unit State?

Recall that the SOM casts the Unit as a collection of instances of candidate equipment. In the view of the SOM, it is this equipment that retains Unit State.

So, UnitContext is obtained from graphContext[task.Unit], and unit state is obtained (and manipulated) through the UnitContext.TargetEquipment field, which is a SmartPropertyBag. It has a field keyed as “Mixture”, which is a Mixture object, and a Mixture contains materials in its Constituents field. Equipment also comes pre-configured with a “Volume” field, which represents the total volume of the equipment.

Since another SmartPropertyBag can be added as a child field to an existing SmartPropertyBag, resources and other data items can be added to the equipment. Each of these can also have fields that are values, aliases, expressions, delegates and child-SPB’s.

PreState and PostState are Snapshots

It is also important to remember that the IMementos returned from the GetPreState(…) and GetPostState(…) APIs are snapshots. Unit state changes that are intended to be working changes, should be made to the equipment, its properties, mixture, or child property bags, not the snapshot.

 

pre and post state snapshots



[1] ValidationStateTargetEquipment is a reference to the assigned equipment that is left available after resource release for use during revalidation operations.