Assembler


The object allows certain number of agents from several sources (5 or less) to be joined into a single agent. The type of the new agent, as well as its initialization, is specified by the user. The number of agents for each input required to produce one new agent is also specified using the object parameters (Quantity 1, Quantity 2, etc.). All arrived agents wait inside the object until all required agents arrive. Once the new agent can be build, the assembly operation starts. This operation takes the time specified in the Delay time parameter. 

Using resources

Assembly may involve resource usage - in this case you should specify what resource(s) are required to perform the assembly. 


The new agent may be "completely new", i.e. a newly constructed object whose properties possibly depend on the original agents, or it may be one of the original agents, again, possibly modified. If you want new agent to be exactly the same as the agent that arrived at the first input port, switch to the dynamic editor of the New agent parameter, and type there queue1.removeFirst()

Assembler may be used for a number of purposes. First, it can serve as a synchronization point to let one of the agents go further only after other ones arrive. Also this object can be used to combine different parts of a job. 

Please note that in this object agents may be disposed. Assembler however does not know which of them will be disposed and will not check if disposal is OK (i.e. no resources, etc.). It is your responsibility to make sure the disposed agents are "clean".

All agents that arrive into the object may be animated at the specified positions.

Parameters

Quantity 1, 2, ...5
Number of agents required to arrive into in1, in2, ..., in5 port to start producing one new agent.
Syntax: int quantity1, quantity2, ... quantity5
New agent [dynamic]
The type of the agents exiting this object.
Local variables: Queue queue1,  queue2, ... , queue5 - Assembler queues. You can access the agents stored there while generating new agent.
Change dimensions [dynamic]
If the option is selected (true), you will be able to change the dimensions of the agent created by this block specifying the new Length, Width and Height values below.
Type of value: boolean
Local variable:  agent - the agent
Length [dynamic]
[Visible if the Change dimensions option is selected] The new length of the assembled agent.
Type of value: double
Local variable:  agent - the agent
Width [dynamic]
[Visible if the Change dimensions option is selected] The new width of the assembled agent.
Type of value: double
Local variable:  agent - the agent
Height [dynamic]
[Visible if the Change dimensions option is selected] The new height of the assembled agent.
Type of value: double
Local variable:  agent - the agent
Seize resources
Here you can choose whether the assembly requires resource(s) of just one single resource type (units of the same pool), or resources of different types ((alternative) resource sets).
Please refer to the details above.
Syntax: boolean seizeFromOnePool
Resource sets [dynamic]
[Visible if Seize resources is set to (alternative) resource sets] Here you define set(s) of resources required to perform the assembly. You can define several alternative resource sets (add new list by clicking the Add list button). The resource set is chosen based on the availability of resource units. 
Please refer to the details above.
Local variable: agent - the agent
Resource pool [dynamic]
[Visible if Seize resources is set to units of the same poolResourcePool block defining the resources requested to perform the assembly.
Please refer to the details above.
Local variable: agent - the agent.
Number of units [dynamic]
[Visible if Seize resources is set to units of the same pool] Expression evaluated to obtain the required number of resource units for the agent.
Value type: int
Local variable: agent - the agent
Delay time [dynamic]
Expression evaluated to obtain the delay time for the assembly operation.
Value type: double
Local variable: agent - the current agent.
Animation
Location of assembled agent
Defines the place where the new assembled agent will be placed. There are six alternative options:
Not specified - You do not specify the new location for assembled agents.
Network / GIS node - Assembled agents are placed in the given network nodeGIS point, or GIS region.
Attractor - Assembled agents are placed in the specified attractor.
(x, y, z) - Assembled agents are placed in the point with the specified coordinates X, Y, Z.
(latitude, longitude) - Assembled agents are placed in the given point on the GIS map with the specified Latitude and Longitude.
Geographic place - Assembled agents are placed in the particular location on the GIS map. You define this place using the Name of place parameter below.
Get value: locationType
Valid values: Assembler.LOCATION_NOT_SPECIFIED, Assembler.LOCATION_NODE, Assembler.LOCATION_ATTRACTOR, Assembler.LOCATION_XYZ, Assembler.LOCATION_LATLON, Assembler.LOCATION_GEO_PLACE
Speed [dynamic]
[Visible if Location of assembed agent is specified] The speed of the assembled agents.
Value type: double
Default value: 10 m/s
Local variable: agent - the agent
X, Y, Z [dynamic]
[Visible if Location of assembled agent is (x, y, z)] X,Y,Z coordinates of the point where the agents created by this block will be put.
Type of value: double
Local variable: agent -  the agent created at this object
... in the network
[Visible if Location of assembled agent is (x, y, z)] If the option is selected (true), the agents are added into the network you choose in the parameter Network below.
Syntax:  boolean locationXYZInNetwork
Network [dynamic]
[Visible if ...in network is selected] Network where the agents created by this block are put.
Value type: Network
Local variable: agent -  the agent created at this object
Node [dynamic]
[Visible if Location of assembled agent is Network / GIS node] Network nodeGIS point, or GIS region where the agents created by this block are put.
Local variable: agent -  the agent created at this object
Attractor [dynamic]
[Visible if Location of assembled agent is AttractorAttractor where the agents created by this block are put.
Value type
: Attractor
Local variable: agent -  the agent created at this object
Latitude, Longitude [dynamic]
[Visible if Location of assembled agent is (latitude, longitude)] Latitude and longitude of the point on the GIS map where the assembled agents will be placed.
Type of value: double
Local variable: agent - the agent
Name of place [dynamic]
[Visible if Location of assembled agent is Geographic place] The name of the particular location on the GIS map, where the assembled agents will get on generation. You specify the name as text put in quotes, e.g. "London". GIS map will search for a location with such name. The first location from the list of GIS search results will be used. 
Type of value: String
Local variable: agent - the agent
Agent location (delay)
Space markup shape (node or path) where the agents are located while being in the embedded Delay object.
Get value: entityLocationDelay
Agent location (queue 1, .. , queue 5)
Space markup shape (node or path) where the agents are located while being in the embedded queue1, queue2, ... queue5 object.
Get value: entityLocationQueue1, entityLocationQueue2, ...
Priorities / preemption
Task priority [dynamic]
The priority of the task for the incoming agent (the larger the higher).
Value type: double
Default value: 0
Local variable: agent - the agent
Task may preempt [dynamic]
If the option is selected, this task may preempt other tasks of the requested resource units.
Value type: boolean
Default value: true
Local variable: agent - the agent
Task preemption policy [dynamic]
Here you can choose what is done when some other task incomes for the resource unit(s) currently busy with the assembly operation.
No preemption - the current task continues executing.
Wait for original resource - the task is interrupted and waits for the same resource unit to finish it.
Terminate serving - the task is interrupted and never continued.
Seize any resource - the task is interrupted and tries to seize any resource of the specified type.
Continue without resource - the task is finished without resources assistance.
Default value: No preemption (Assembler.PP_NO_PREEMPTION)
Local variable: agent - the agent
Auto suspend/resume agents
[Visible if Task preemption policy is set to Wait for original resource or Seize any resource] This parameter defines whether the agent whose task is suspended should be automatically suspended in its current flowchart block and automatically resumed at the time when the resources become available.
Syntax: boolean suspendResumeEntities
Default value: true
Enter for terminated agents [dynamic]
[Visible if Task preemption policy is set to Terminate serving] Enter block starting the flowchart branch for the agents which lost all obtained resource units because of Terminate serving preemption policy, when one of units in the resource set gets grabbed by another task with higher priority.
Local variables: agent - the agent
                          Agent unit - the resource unit which has originated termination
Advanced
Customize resource choice
If the option is selected, you can choose some specific resource units for the operation (using the Resource choice condition below.) 
Syntax: boolean customizeResourceChoice
Default value: false
Resource choice condition [dynamic]
[Visible if Customize resource choice is selected] Here you can specify boolean expression that will be checked to find the specific resource unit(s) that may perform the operation. If none currently available resource unit(s) satisfy the specified condition (the condition returns false), the Assembler will wait for the first resource unit that matches the condition. 
Usually you define some field inside the agent type (say, myAssistant), store there the reference to the resource unit when it starts working with this agent (agent.myAssistant=unit), and then specify here the condition agent.myAssistant==unit enabling only this particular unit to continue working with this particular agent.
Value type: boolean
Default value: true
Local variables: agent - the agent
                          Agent unit - the unit
                          ResourcePool pool - the resource pool
Add combined agents to
Here you specify where the agents created by this block will be stored: in the default population of root agent, or in some custom population (specified below in the Population property).
Syntax: boolean addToCustomPopulation
Default value:
Default population (false)
Population [dynamic]
[Visible if Add combined agents to is set to Custom population] The name of the agent population where the agents created by this block will be stored.
Value type: AgentList
Local variable: agent - the agent created by this object.
Restore agent location on exit
If the option is selected, after being animated in the Agent location (delay, queue) shapes, the agents will return to their original location (node or path) where they were before entering this Assembler block.
Syntax: boolean restoreEntityLocationOnExit
Force statistics collection
If selected (true), statistics are collected for this and embedded objects, otherwise statistics collection is configured by PMLSettings block (where the default is true).
Syntax: boolean forceStatisticsCollection
Default value: false
Actions
On enter 1, 2, ..., 5 [code]
Code executed when an agent enters the object at in1, in2, ..., in5.
Local variable: T1, T2, ... T5 agent - the agent. 
On enter delay [code]
Code executed when the agent enters the delay.
Local variable: agent - the agent.
On at exit [code]
The callback executed when agent has finished its delay and ready to leave this block (if the subsequent block is not busy).
Local variable: agent - the agent.
On exit [code]
Code executed when the resulting agent exits the object. 
Local variable: agent - the resulting agent that will exit.
On task suspended [code]
[Visible if Task preemption policy is set to Wait for original resource or Seize any resource]
Callback for action executed when agent task is suspended because of Seize any resource and Wait for original resource preemption policy, when its unit gets grabbed by another task with higher priority. 
Local variables: agent - the agent.
                          Agent unit - the unit.
On task resumed [code]
[Visible if Task preemption policy is set to Wait for original resource or Seize any resource]
Callback for action executed when agent resumes processing after it has been suspended because of Seize any resource and Wait for original resource preemption policy.
Local variables: agent - the agent.
                          Agent unit - the unit.
On task terminated [code]
[Visible if Task preemption policy is set to Terminate serving]
Callback for action executed when agent loses all units obtained in this Seize block because of Terminate serving preemption policy, when one of units in the resource set (defined in this Seize) gets grabbed by another task with higher priority.
Local variables: agent - the agent.
                          Agent unit - the unit which has originated termination.

Functions

int queueSize( int n ) - returns the number of agents in the queue with the given number. 

Agent queueGet( int n, int index ) -  returns the agent from the queue with a given index at the specified position (0 is at the exit).

int delaySize() - returns the number of agents in the embedded Delay object.

T delayGet( int index ) - returns the agent at the index position in the Delay (the oldest agent is at the position 0)

T remove(Agent agent) - Removes the given agent from the queue and returns it. If the agent is not contained in the queue, returns null.

T resume(Agent agent) - Resumes previously suspended Delay (if was not suspended, throws error).

T suspend(Agent agent) - Suspends this delay for the given timeout dt.

double utilization() - Returns the mean utilization of this block. The returned value is the average (collected over time) of number of agents being serviced.

Ports

in1, in2, in3, in4, in5
The input ports.
out
The output port.