This Wiki describes the components of a timing graph provided by LSA to supply the Datamaster via BSS

Please note, that the shown graphs here only provide parts of a real schedule and may be mixed. The graphs themselves may also become obsolete, to be sure you may have a look at the tests graphs used by LSA. Each node type has a separate meaning, some types are typically in a special layout, but this is not mandatory. The different node types have a common set of attributes but also may have type specific attributes, see list below:

Node type	attribute	meaning
all nodes	type	the type of the node
	cpu	the datamaster cpu the node should be executed on
	patentry	boolean value to mark the entry block of a pattern
	patexit	boolean value to mark the exit block of a pattern
	pattern	the pattern name this node belongs to
block		A block defines the time that has to pass before the datamaster leaves this block. A block node provides queues to switch between different outgoing edges.
	tperiod	The amount of time in ns this block reserves for playing the timing events before the next block gets executed. The minimal tperiod is 10.000ns.
	qlo	low priority queue
	qhi	high priority queue
	qil	interlock priority queue
blockalign		same as block, but aligns the timePeriod to the next 10.000ns BUTIS time raster
tmsg		This node represents a timing event.
	beamin	flag to mark if there should be beam when this event is played
	bpid	the beam process index
	evtno	the event number to be played
	fid	the format id of the timing message
	gid	the group id of the event
	par	the parameter, requestNoBam, bpcStart
	sid	sequenceIndex
	toffs	the time offset relative to the previous block when this node should become active
	vacc	virtualAccelerator
Flow		A flow node instructs a block node to use "qty" often its alternative destination before going back to default, this is realized using the "qlo" queue of the block.
	qty	the amount of times the alternative should be used
	toffs	the time offset relative to the previous block when this node should become active
	tvalid	the point in time when this flow becomes valid, should be 0 in static graphs
	vabs	flag to determine if the times are absolute, should be true in static graphs
Flush	prio	the priority of this flush (0=qlo, 1=qhi, 2=qil, writes the queues to be flushed in the priority queue of a block)
	qlo	flag to determin if "qlo" should be flushed (optional)
	qhi	flag to determin if "qhi" should be flushed (optional)
	qil	flag to determin if "qil" should be flushed (optional)
	toffs	the time offset relative to the previous block when this node should become active
	tvalid	the point in time when this flow becomes valid, should be 0 in static graphs
	vabs	flag to determine if the times are absolute, should be true in static graphs
	destpattern	the name of the pattern holding the block to be flushed (may be null if the block is within the same pattern)
	permanent	flag to determine, if this flush should be permanent
Switch	toffs	the time offset relative to the previous block when this node should become active
ThreadaOrigin	thread	the id (1-32) of the thread to prepare
	toffs	the time offset relative to the previous block when this node should become active
StartThread	startoffs	the offset relative to this event when the new threads should be started
	threads	the bitmask of IDs of threads to be start, e.g. 0b110 would start threads 2 and 3
	toffs	the time offset relative to the previous block when this node should become active

Graph elements and their meaning

All nodes must have a default destination (defdst, red). Blocks and BlockAligns may have additional alternative destinations (altdst, black). Blocks can have optional queues of different priority (low, high, interlock), every time the datamaster visits a block one queue entry with the highest priority is processed. The flow node must have a target (blue) and a flow destination (pink). This means, that the flow writes an entry in the queue of the target block, so that this will activate the alternative destination pointing to the flow destination. In the example graph above, the "FLOW" sets a queue entry to the "BLOCK" so that the blocks alternative to "TIMING_MESSAGE" will become the default destination when the queue gets evaluated. Note: only the most highest non empty queue entry will be evaluated when the block gets executed by the datamaster. The flush node must have a target (blue) whose queue should be flushed. In the graph above, the "FLUSH" node would add a queue entry to the "BLOCK" so that the block would flush its queues, as specified by the flushs attributes. Note: only the most highest non empty queue entry will be evaluated when the block gets executed by the datamaster. The flushovr node is a special flush node that has an additional "flushovr" edge. This means, that the targets queue of the flushovr gets flushed, like in the normal flush but the flush is executed immediately and not just when the blocks queue gets evaluated. Also the default destination gets switched to the "flushovr" node. In this example, the queue of the "BLOCK" will be flushed and the default destination will be set to "TIMING_MESSAGE". This is more or less a combination of Flush and Flow with the difference, that the queue gets flushed immediately. The switch node must have a target (blue) and a switch destination (darkorange3). In the graph above, the "SWITCH" would immediately change the default destination of the "BLOCK" (target) to "TIMING_MESSAGE" (switch destination), the previous default destination to "BLOCK_ALIGN" would then be the alternative destination. The ThreadOrigin node must have an origindst (gray) which points to a node that represents the start of a new thread. The StartThread node defines which threads should be startet. Each thread now executes the subgraph starting at the point where the previous ThreadOrigin pointed to for its ID.

Default Pattern

The default pattern takes always 1 second so that the hardware is not flooded with events when nothing is played but also don't turn off themself.

This is the default pattern that is played, when patterns are resident but all are disabled to keep the hardware alive.	The default pattern may also contain an EVT_COMMAND event, that is only needed for the old DeviceAccess devices and therefore only available on SIS18 and ESR.

Simple Ring Pattern containing Pattern Repetition

Involved Events	---
Involved Signals	PATTERN_DISABLED_BY_LSA
	PATTERN_DISABLED_BY_OP
	PATTERN_GROUP_DISABLED_BY_OP
	BEAM_REQUESTED (depending on the target)

This kind of pattern would be used for hardware tests / commissioning, not for productive beam times since there is neither an injection (from Unilac or another ring) nor extraction. Each pattern starts with a "*_ENTRY" block (only this block sets the attribute "patentry" to true), followed by a block align, to synchronize the pattern to the BUTIS time raster. The "*_REPCOUNT_FLOW" then tells the "*REPCOUNT_BLOCK" to jump back to the first event for "qty" times (according to the flows attributes). This "target" destination points to "*REPCOUNT_BLOCK" and "flowdst" points to the first event (this edge might be overlapping with the default destination edge) The events are now being played relative to the "*_ALIGN" block according to their "toffs" attribute. The events must be ordered ascending according to ther time offset and the last events time offset may not be larger than the following blocks "tperiod". Repetitions can also be canceled via the BSS rest interface. When the repetition counter has reached zero, the "*_EXIT" block gets active which provides the "patexit" = true attribute.

Unilac coupling to SIS18

For reasons of simplicity, the events not involved in the Unilac coupling and other features like pattern repetition or extraction are not shown in the example below.

Involved Events	350 - CMD_UNI_TCREQ
	351 - CMD_UNI_TCREL
	352 - CMD_UNI_BREQ
Involved Signals	---

For simplicity reasons of the timing programming, there is no difference in the timing graph for a single unilac request or multi-multi-turn injection. The Unilac coupling starts with event 350 (CMD_UNI_TCREQ), played in the BEAMOUT_INIT beam process, which requests the transfer channel to SIS18. This event has a special edge in the graph, "dynpar0" (shown in pink). This special edge is used to instruct the old UnilacPZ to synchronize with the waiting blocks, e.g. to skip it when beam is delivered. The next relevant element is the "_DMBlk_InjectionStart" which adds the "FG Nachlauf" and "FG Interrupt" time. After that time is over, the "_DMCmd_InjectMulti" flow instructs the "_BMBlk_InjectionEnd" block to jump back to the "_DMBlk_InjectionMultiLoopStart" block. When there is a single request, the instruction is to jump zero times back. On MMI the counter represents the amounts of repetitions, so n jump back will provide n+1 shots from Unilac to SIS18. Naw a new Thread (fixed ID 0) is prepared by the ThreadOrigin "_DMBlik_InjectionThreadOrigin". This node prepares tha Thread 0 to start at the destination of its "origindst" (gray edge) once it is called. The event 352 (CMD_UNI_BREQ) now requests the beam. It also has the special edge "dynpar1" that instructs the "UnilacPZ" to start the Thread 0. The following block "_DMBlk_BReq" ensures, that there is enough time for all events between "_DMBlk_InjectionMultiLoopStart" and the wait loop that follows afterwards. The "_DMCmd_Wait10s" flow now instructs the "_DMBlk_WaitLoop" block to repeat itself for 10 seconds. The "_DMBlk_WaitLoop" block has the minimal time period of 10.000ns and repeats itself now 1.000.000 times. This loop gets interrupted by the "dynpar0" edge, so the UnilacPZ tells the datamaster, that the beam will be ready in the near future. Also the Thread 0 will be started now by the "UnilacPZ" which now executes the injection events in SIS18. When using MMI, the "_DMBlk_InjectionEnd" may repeat this loop or otherwise leaves it and the event 351 (CMD_UNI_TCREL) is played which releases the transfer channel.

RING extraction to target

For the RING extraction (slow, fast and KO), there are only events involved provided by the Modeleers Team. So no special treatments fpr the datamaster programming.

Coupling between two Rings

Precondition: The extracting RING has to use fast extraction so that the kicker events between the two rings can properly be synchronized.

Since for now it is not possible to supply two patterns at once the coupling mechanism contains two supply steps, each providing a slightly different timing graph (regardless of the type of the coupling). When two patterns shall be coupled, both have to be already resident and therefore the timing graphs already exist in the datamaster without the coupling. When the first ring gets coupled now, it will leave out all edges (and reference nodes) to the second ring. This will provide an incomplete timing graph that will nevertheless be able to be played without any limitations, also it might not be functional (Strong Coupling) or also may contaminate the machine (Fire and Forget). As far as the second patterns gets supplied, the missing edges are added and the timing graphs are complete and functional.

To visualize this, the nodes of the coupled context are shown in gray in the examples below. This means, that the gray nodes are not supplied on the first context, when the two contexts are being coupled and are not present in the datamaster, when the coupled context is being trimmed.

Involved Events	47 - EVT_MK_LOAD_1
	48 - EVT_MK_LOAD_2
Involved Signals	DISABLE_FIRE_AND_FORGET_NOTIFY - used in extraction context for Fire and Forget
	DISABLE_COUPLED_BEAM_REQUEST - used in injection context for Strong Coupling

Strong Coupling

This type of coupling provides a kind of handshake, where the extraction context (e.g. SIS18) per default skips its own execution unless it gets requested by the injection context (e.g. ESR). The injection context requests beam from the extraction context and waits for the injection.

Fire and Forget

This type of coupling provides a kind of fire and forget coupling, where the extraction context (e.g. ESR) per default provides beam and extracts it towards the injection context (e.g. YR) by only notifying the injection context but without respect of its current state. The injection context does not requests beam from the extraction context in this case, but also may wait for the injection notify. This concept is useful when the creation of the beam takes longer than the lifetime of the beam in the injection context and the injection ring is able to consume an alternative beam from another source in the meantime.

Extraction to another Ring

For reasons of simplicity, the events not involved in the coupling coupling and other features like pattern repetition are not shown in the examples below.

Strong Coupling

Starting point of the strong coupled extraction context (e.g. SIS18) is the "_DMBlk_SR_ExecuteOrSkipDecision" block. This block is located directly after the "_ALIGN" block and its default destination is the "_Skip_000" event which is the same as the default pattern. IN contrast to the default pattern, the "_Block" block takes only 40ms (instead of 1s).

During the coupling process or during trims of the injection context, the "INJECTION_CTX_*" nodes and their edges are not present. This removes the possibility that the real content of the extraction context can be played and the pattern will always skip itself using the "_Skip" path.

When the injection context is also supplied and currently being executed, it switches the default destination from "_DMBlk_SR_ExecuteOrSkipDecision" to "_REPCOUNT_FLOW" and the extraction context will be executed.

Therefore the events preparing the beam (including previous ring couplings or unilac coupling) are executed and prior to the beam extraction, the "SR_Flush_WaitLoop" is reached, which will interrupt the injection contexts wait loop (target to "INJECTION_CTX_DMBlk_WaitLoop").

Afterwards it switches its "_DMBlk_SR_ExecuteOrSkipDecision" default destination back to the "_Skip" path to not produce beam again.

Now the extraction event is being executed (event 47 - EVT_MK_LOAD_1, or event 48, depending on the hardware) and the beam gets extracted.

The repetition mechanics is present but should not be used.

Fire and Forget

The fire and forget extraction does not have a skip mechanism, so this context will always produce beam regardless if the injection context is running or not. Howver, this makes the nodes involved to the extraction coupling much more simple.

When the beam is prepared, the "_DMBlk_SR_Skip_Flush_ENTRY" node is evaluated. Per default, it would just pass and flush the injection contexts wait loops. When the injection context is currently being trimmed, a signal "DISABLE_FIRE_AND_FORGET_NOTIFY" gets activated and BSS will switch the default destination of "_DMBlk_SR_Skip_Flush_ENTRY" to "_DMBlk_SR_Skip_Flush_EXIT". In this case, the beam will be produced but there is no notify to the injection context. When this happens, the beam should be dumped in the injection context by not activating the kicker, this however may activate the dump target.

In the default case, the two flushes "_DMCmd_SR_Flush_WaitLoop_OUTER" and "_DMCmd_SR_Flush_WaitLoop" will be processed and the waiting loop in the injection context will be interrupted.

Afterwards the extraction kicker will be loaded (event 48 - EVT_MK_LOAD_2, or event 47, depending on the hardware) and the beam gets extracted.

Injection from another Ring

Strong Coupling

When the injection beam process starts, the "_DMBlk_SR_BReq_ENTRY" block is reached. Depending on the "DISABLE_COUPLED_BEAM_REQUEST" signal, it either executes the request (default) or skips it (this is the case, when the extraction beam process is being trimmed).

If the request gets executed, the injection contexts skip path gets switched to the execution path. Then the wait loop gets initialized by the "_DMCmd_SR_Flow_Wait" flow. The quantity is set via the COUPLING_TIMEOUT setting. The minimal waiting time (the tPeriod of the block itself) is set to 100.000ns, the maximum repetition count (quantity of the flow) is a 20 bit number, so 0xFFFF = 1.048.575. So the maximum wait time is 1.048.575 * 100.000ns = 104,8575 seconds ~ 1,75 min. The WaitLoop block length should not be larger than 100.000ns so that the loop can be interrupted without a large delay, otherwise the beam might get loss. If a longer waiting time is needed, the WaitLoop mechanism has to be switched according to the Fire and Forget Injection Contexts WaitLoop.

The "_DMBlk_SR_WaitLoop" now repeats itself until the timeout gets reached or the loop gets interrupted by the injection context.

For safety reasons, the injection context is now switched back to the skip path. This is necessary, when the injection context did not run and the timeout was reached. In this case one does not want to produce beam immediately when the injection context gets activated.

Fire and Forget

When the injection beam process starts, the "_DMBlk_SR_BReq" block is reached. This block only reserves the time needed for all prior events.

Since this coupling mode was designed to transferring beam from one storage ring to another, the possible wait time is much higher than the one of strong coupled synchrotron mode contexts. Therefore a second wait loop, surrounding the first one, is needed. This enables a multiplied wait time. At the moment the WaitLoop block lengths are set to 10.000ns each, the maximum repetition count (quantity of the flow) is a 20 bit number, so 0xFFFF = 1.048.575. The inner wait loop is now able to wait at most nearly 10,49 seconds, this can now be extended by the outer loop, so the maximal entire wait time is nearly 127,26 days. The WaitLoop block length should not be larger than 100.000ns (see also simple wait loop) so that the loop can be interrupted without a large delay, otherwise the beam might get loss. The double wait loop is realized by a more or less complex combination of "FlushOvr", "Flow" and "Block" nodes.

After the injection context has reached its injection settings, the wait loop is entered ("_DMBlk_SR_BReq"). Afterwards, the "_DMCmd_SR_FLUSHOVR_WAIT_LOOP_JUMP_BACK_OUTER" flushes the low and high queues of "_DMBlk_SR_WaitLoop_OUTER" and sets the default destination of "_DMBlk_SR_WaitLoop_OUTER" to "_DMCmd_SR_Flow_Wait_OUTER" (non permanent). The same is now done with "_DMCmd_SR_FLUSHOVR_WAIT_LOOP_JUMP_BACK" which flushes the low and high queues of "_DMBlk_SR_WaitLoop" and sets the defaut destination to "_DMCmd_SR_Flow_Wait" (non permanent).

"_DMBlk_SR_WaitLoop_OUTER" is now processed, its queues gets flushed and it follows the one-time default destination to "_DMCmd_SR_Flow_Wait_OUTER". This now initializes the "_DMBlk_SR_WaitLoop_OUTER" to jump to "_DMCmd_SR_Flow_Wait" for a calculated amount of times (See calculation in CouplingExtensionFireForget#getWaitLoopQuantityOuter). After that flow, the inner loop is entered. At this point, the queues of "_DMBlk_SR_WaitLoop" are empty so it directly follows the one-time default destination to "_DMCmd_SR_Flow_Wait". This initializes the inner loop to repeat itself and just goes back. Now the inner loop is repeated until the counter reaches zero or an interrupt flush arrived from the extraction context. When the loop ends, it follows to the "_DMBlk_SR_WaitLoop_OUTER". If this queues counter is zero, the block would next exit the loop and the injection events would follow, otherwise it now jumps back to "_DMCmd_SR_Flow_Wait" which would again initialize the inner loop and starts it.

Storage Ring Mode

Precondition: All Storage Ring Mode Features are places within subchains, some features need to be their own subchain.

For a more detailed overview of the concept, please visit this overview page.

Subchain

Subchains are cunstructed like patterns, they have their own entry and exit blocks that are used by individual features.

Skipping

Involved Events --- Involved Signals "_SCx_SKIP_ENABLED" "SKIPS_ENABLED" If a subchain is skipped or not is decided by the signal states when the "_SCx_ENTRY" block is reached. Either it jumps directly to "_SCx_EXIT" and skips the subchain execution, or it jumps to "_SCx_BLOCK_ENTRY" and the subchain events are played.

Repetition

The repetition is basically identical to the pattern repetition. The "*SCx_REPCOUNT_FLOW" tells the "_SCx_REPCOUNT_BLOCK" to jump back to the "_SCx_BLOCK_ENTRY" to repeat the subchain events. Repetitions can be canceled via the BSS rest interface.

Breakpoint

Involved Events --- Involved Signals "_SCx_BREAK_ENABLED" "ALL_BREAKS_ENABLED" The breakpoint is located at the end of a subchain after its "_BLOCK_EXIT" block. The "_SCx_BREAK_ENTRY" block now decides, based on the signal states, if the breakpoint is entered or not. The breakpoint itself now plays events analog to the default pattern and goes back to the break entry. This loop is repeated until the signal states have changed so that the subchain continues.

Manipulation

Involved Events --- Involved Signals "_SCx_WAIT_FOR_MANIP_BY_OP" "_SCx_WAIT_FOR_MANIP_SAFE" "_SCx_PERFORM_MANIP" Please find a detailed description here.

Getting schedule graphs

from Datamaster

Please use the script provided at here.

from existing patterns

Starting with 16.1.0-SNAPSHOT one can use the expert-lsa-infodump-cli project using the arguments --export-dot PATTERN_NAME.

Viewing schedule graphs

One can use /common/usr/cscoap/bin/xdot-app --neato filename.dot to view a scheduling graph including a search feature and information dialog for timing nodes.