Event Call Sequence

As an experienced INOSIM user, you are aware that you are working with a discrete-event simulation software. For most events, VBA controls can be called to change the simulation behavior. This article takes a closer look at some specific events and controls and the sequence in which they are called. When is the MaterialMix event called? How can there be three separate controls called for one operation parameterization event? Continue to read to learn more about INOSIM’s event call sequence.

The Demo Process Model

The modelled demo plant consists of a source, two reactors, a filter and two barrels. In the reactors, two materials, A and B, are mixed and then transferred through the filter into one of the barrels. The model can be downloaded, please find the link at the bottom of the page.

The plant layout and recipe of the demo process is shown below. The experiment’s order list contains four orders for that recipe. While one order starts at the beginning of the simulation run, the other three are scheduled to start one day later.

Please note:

This model has been created for the sake of showcasing as many controls as possible and the events that call them. It is not an example of a thought-through model.

Some events can call several controls, e. g., whenever a material is pulled from a source, the Simulation.MaterialCost control and the MaterialCost control assigned to the project are called. Usually, it does not make sense to use both controls. For an in-depth description of the events, controls, and objects mentioned in this article, please refer to our user documentation from the download section.

In the following sections, we will follow all control calls through INOSIM events that happen after the simulation start button is pressed.

At the Beginning of the Simulation Run

Simulation.Init

Called by the simulation initialization event (start after reset). Some properties that will be write-protected later on can be changed here, e. g., changing the contents of a unit or the member list of a unit pool.

Simulation.Start

Called by the simulation start event (after initialization) and by every restart after the simulation has been paused or stopped. (Also see Simulation.Stop, and Simulation.EndSim below.)

Recipe Selection Control

In this example, the checkbox Fixed Recipe has been unselected for Order 1. Therefore, this control is called as soon as the order has been scheduled. It allows to change the recipe assigned to the order.

Simulation.OrderSchedule

Control is called when an order has been scheduled.

Recipe Load

When the recipe is loaded (used) for the first time, this control is called. It can be added in the recipe-attached VBA code, or by globally declaring a recipe object WithEvents.

Unit Pool Allocation Control

A pool is assigned to the unit procedure Reaction, therefore the assigned unit pool allocation control is called. It allows controlling which unit of the pool should be allocated (see Tip & Trick Using the New Controls for Unit Pools in INOSIM 13).

Simulation.OrderStart

Control is called when an order has started, i. e., the order has allocated its first unit.

Events Triggered by Recipe Elements

The reactor gets allocated, and the first operation (Loading) is parameterized, starts, and ends after 1 h. In this example, these events do not call any controls. (Furthermore, two global controls are called, which will be explained later.)

The following figure gives an overview of the events for the recipe module Reaction containing a single operation named Reaction.

Events and Controls called for the Recipe Module Reaction

The operation Reaction in the recipe is part of the recipe module Reaction. In addition to the controls linked in the operation dialog, recipe modules and recipes can have internal VBA code. The code is accessible through the button in the recipe (module) editor. The code will also be exported/imported with the respective element. This can be useful, when designing reusable recipe modules for easy re-distribution. See user documentation for further information.

Recipe Module Parameterization Event

Recipe Module Parameterization Control

This control is called for the global parameterization event for the complete recipe module, i. e., before the parameterization of the first operation of a recipe module. The control is linked to the module instance via the operation dialog, see circled M above the operation.

Operation Parameterization Event

At the operation parameterization event, all writable parameters of an operation can be changed, such as duration, amount, resource demand, and many more. After the parameterization event is finished, these parameters are fix and cannot be changed anymore.

For this specific operation, three controls are called in this specific order:

Control Operation Parameterization Control

Operation parameter control linked to the operation via the operation dialog.

Recipe Module Operation Parameterization Control

If the operation is part of a recipe module, this control, created and linked in the recipe-specific VBA code, is called.

Recipe Operation Parameterization Control

Control created and linked in the recipe-specific VBA code.

Operation Start Event

Ideally, the operation start event happens right after parameterization. However, in case an operation is waiting for a resource, transfer partner, or synchronization link, waiting times can occur between parameterization and start.

As for the parameterization event, three controls are called for this operation in this specific order:

Control Operation Start Control

Recipe Module Operation Start Control

Recipe Operation Start Control

Material Cost Event

After a transfer of a material from the source is completed, but before the End event is triggered, two controls for material costing can be called:

Material Cost Control

This control was assigned to the project properties.

Simulation.MaterialCost

This control was created for the simulation object.

Material Mix Event

After a transfer of a material into a unit that already contained a material has completed, two controls can be called to calculate the new material properties, e. g., the density of the mixture.

Simulation.MaterialMix

This control was created for the simulation object and is called whenever materials are mixed in any unit.

reactor1.MaterialMix

The variable reactor1 has been globally declared WithEvents as unit object. This control will only be called if materials are mixed in the unit assigned to the variable reactor1 during Simulation.Init.

Operation End Event

As for the parameterization and start event, three controls are called for this operation in this specific order, when the operation has finished:

Control Operation End

Recipe Module Operation End

Recipe Operation End

Events called for the transfer from Reactor to Filter

The sequence of events is shown in the figure below. The events that belong to the same operation are horizontally aligned, whereas the vertical position depicts the sequence in which they are called. It might look confusing at first sight. We encourage you to download the model and investigate the event call sequence it yourself with breakpoints, console message or similar.

Please note: Due to the specific structure of the influx–outflux–startTransfer construct, if an influx or outflux can start after parametrization, the start and end event are called immediately.

Control Operation Control for IN

[Waiting for Loading to finish]

Control Operation Parametrization Control for Transfer

Operation Transfer Control for the Transfer Link between Transfer and IN

This control was assigned to the transfer link (therefore highlighted blue). It can be used to parametrize the transfer (amount, duration, mass rate, material).

Control Operation Start Control for IN

Control Operation End Control for IN

Control Operation Parametrization Control for OUT

Unit Pool Transfer Control

This control is called whenever a simpletransfer or simpleinflux/outflux into or from a unit pool is parametrized. The transfer partner can be selected by assigning another unit. The control can be recalled in case the transfer stops, e. g., because the Entrance/ExitState is locked, the unit has a failure, or is full/empty. Learn more about this control in this Tip & Trick.

Control Operation Start Control for OUT

In this example, the control linked to this operation start event schedules the call of another control to close the EntranceState of the chosen barrel in 60 min. from now.

Control Operation End Control for OUT

Control Operation Parametrization Control for Filtration

Control Operation Start Control for Filtration

Control Operation Start Control for Transfer

Finally, the transfer can start. Material is now being transferred from a reactor, through the Filter and into Barrel B.

Control called by Simulation.ScheduleSub

Using the ScheduleSub method of the simulation object, any control can be called at a specific simulation time. In this case, the control closes the EntranceState of the transfer partner Barrel B.

Unit Pool Transfer Control

The control is called again because the transfer has stopped (because Barrel B´s EntranceState is locked). In this example, Barrel A, the other unit from the pool, is chosen to replace Barrel B as transfer partner.

The material is now being transferred from the Filter into Barrel A.

Control Operation End Control for Transfer

Control Operation End Control for Filtration

Excursus: ScheduleSub method

The ScheduleSub method of the simulation object schedules the call of a specific control (sub procedure) at a specific point in (simulation) time. It is a great way to force certain things to happen at a specific time (e. g., manually starting or ending a failure via VBA). However, one must be sure that objects passed as arguments are still valid at that future point in time.

In this example, the start control of the operation OUT calls the sub Macro1.CloseOpenEntrance, 60 mins from now, and passes two arguments: the transfer target unit (Barrel B) and the target state of the EntranceState property (ulocked).

The control CloseOpenEntrance prints a message to the console and then sets the EntranceState property. If it was set to ulocked, the control calls itself again in 60 min, using the ScheduleSub method, to re-open the EntranceState of the same unit.

Sub StartControl_CloseEntrance(cop As OrderOperation)
    Simulation.ScheduleSub("Macro1.CloseOpenEntrance",60*60,DateReferenceType.bRelative,cop.Transfer.OtherUnit, UnitEntranceExitState.uLocked)
End Sub

Sub CloseOpenEntrance(u As Unit, target_state As UnitEntranceExitState)
    Console.Information("Simulation.ScheduleSub to set EntranceState of " & u.Name & " to " & target_state)

    u.EntranceState = target_state

    If target_state = UnitEntranceExitState.uLocked Then
        Simulation.ScheduleSub("Macro1.CloseOpenEntrance",60*60,DateReferenceType.bRelative,u, UnitEntranceExitState.uOpen)
    End If
End Sub

Alternative Branch and Link Conditions

If an alternative branch has a link condition, the assigned control will always be called. If there are several link conditions, the controls will be called subsequently. Per default, the sequence depends on the order in which the connections were created. You can manipulate this sequence by adjusting the sequence number of the connection as shown in the figure below.

As shown above, the sequence number 1 has been assigned to the connection before Short Clean, the sequence number 2 has been assigned to the connection before Long Clean. Therefore, the link condition controls are called in the following order:

Link Condition Control before Short Clean

Link Condition Control before Long Clean

The control sets the value of the link condition object to false, so that neither short nor long cleaning is carried out.

Failure and Maintenance Events

For Reactor 1, maintenance is due 8 h after simulation start (Settings: every 48 h, initial age of 40 h, scheduling: Breakpoint). With these settings, maintenance does not start immediately when due, but only when the unit is available. Unfortunately, in this example, a failure occurs while maintenance is waiting for the unit to be available.

A failure control and a maintenance control were linked to the unit via its dialog. Additionally, a control was created for the variable reactor1 that has been globally declared WithEvents as unit object (see above). This control will be called after the one linked in the dialog.

Please note that the same control will be called for start and end of a failure. The same applies to maintenance, plus the schedule event. The argument reason depicts if it is the start or end (or schedule). The sequence of events is also represented in the figure below.

Maintenance Control (Schedule)

The control is called with reason bMaintenanceSchedule when the maintenance is due.

Failure Control (Begin)

The control is called with reason bFailureBegin at the start of the failure.

Failure Control (End)

The control is called with reason bFailureEnd at the end of the failure.

Maintenance Control (Begin)

The control is called with reason bMaintenanceBegin at the start of the maintenance.

Simulation.OrderEnd

This control is called for every order when all its ProcedureInstances have finished.

Maintenance Control (End)

The control is called with reason bMaintenanceEnd when at the end of the maintenance.

As the simulation continues

After the first order has been processed, the three orders are scheduled to start at midnight. As they (try to) start at the same time, the allocation priority control for the Filter is called. After all orders have been processed, or the simulation end date is reached, the simulation ends.

Allocation Priority Control

Assigned to the unit Filter. Control is called whenever there is more than one procedure instance (think of them as unit procedures searching for a unit) waiting for this unit. By calling the MoveToFront or MoveToEnd-Methods for a PendingProcedureInstance-object, they can be moved within the queue (waiting list of a unit). (Hint: Prioritization of procedure instances can also be achieved with a unit pool allocation control.)

In this example, the simulation is stopped when this control is executed for the first time. You will need to press the Start button again to continue the simulation run.

Simulation.Stop

Whenever the Stop or Pause button are pressed, or the VBA command Simulation.Stop is evaluated, this control will be called. Press the Start button to continue.

Simulation.Start

See above.

Simulation.EndSim

This control is called when there are no more open or active orders or when the simulation end date is reached. During this event, the Reporting object is available. Learn more about the Reporting object in this Tip & Trick.

Simulation.Stop

Excursus: Dim WithEvents

The global MaterialMix control is called whenever two materials mix in any unit. Additionally, a specific control can be defined for a single unit. Read on to learn how:

Several INOSIM objects can be declared WithEvents, e. g., units and recipes. Selecting the object from the Object dropdown menu in the editor allows you to browse the available event controls for this object in the Proc dropdown menu, such as MaterialMix.

In the example below, the variable reactor 1 is declared globally as a unit object WithEvents. In the Simulation.Init procedure, a unit is assigned to the variable. A specific control has been specified to handle MaterialMix events of Reactor 1.

'#Language "WWB.NET"
Option Explicit
Dim WithEvents reactor1 As Unit

Private Sub Simulation_Init() Handles Simulation.Init
    reactor1 = Units("Reactor 1")
End Sub

Private Sub reactor1_MaterialMix(ByVal u As INOSIM.Unit, ByVal matIn As INOSIM.MaterialAmounts, ByVal matOut As INOSIM.Material) Handles reactor1.MaterialMix
    Console.Information("reactor1.MaterialMix")
End Sub

Downloads

(for registered INOSIM users)

Example model Event Call Sequence.ixml
PDF printout of this Tip & Trick

More Tips & Tricks

9. May 2023