Batch

Converts a number of agents into one agent (batch) by either discarding the original agents and creating a new one -
permanent
batch (whose properties possibly depend on the original ones), or by
adding the original agents to the contents of the new agent - temporary
batch that can later on be unbatched by
Unbatch
block.
This block embeds a
Queue
block where it stores the incoming agents. Once the number of the
stored agents reaches the batch size, the batch is created and leaves
the block immediately. To obtain a list of agent in the batch, call agent.contents(), where agent is the batch that will exit the block. To obtain the number of agents in the batch, either call the size() function of the Batch block, e.g. batch.size(), where batch is the Batch block, or agent.contents().size(), where agent is the batch itself.
Example of a permanent batch: assume you wish to accumulate n agents of type
Packet, each having a field
size
and create a new one of the same type but with size equal to the sum of
original packet sizes. Then you should do the following. Specify the
original and resulting types: Packet, Packet, leave Permanent batch parameter set to true, in the New batch parameter write new Packet(), set Batch size to n, and write in On add action field:
batch.size += agent.size.
If
the agents should be batched not by the number but by some other
criteria (e.g. by total weight that can vary from agent to agent), it
may be easier to use a customized
Queue
block instead of
Batch.
The other blocks that work with the agent contents are
Pickup
and
Dropoff.
Parameters
- Batch size
- The size of the batch. May be changed dynamically by calling
set_batchSize().
Syntax:
int batchSize
Default value:
10
- Permanent batch
- If the option is selected (true), the original agents are discarded after the new one (permanent batch) is created, if
false
- the original agents are added to the contents of the new agent (temporary batch that can later on be unbatched by
Unbatch
block).
Syntax:
boolean permanent
- New batch
[dynamic]
- Specify here the
agent type
for the batches created by this block.
Default value:
Agent
Referred as:
TBatch
- Change dimensions
[dynamic]
-
If the option is selected (true), you will be able to change the dimensions of the batch generated 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 created agent (batch).
Type of value:
double
Local variable:
agent
- the agent
- Width
[dynamic]
- [Visible if the
Change dimensions
option is selected] The new width of the created agent (batch).
Type of value:
double
Local variable:
agent
- the agent
- Height
[dynamic]
- [Visible if the
Change dimensions
option is selected] The new height of the created agent (batch).
Type of value:
double
Local variable:
agent
- the agent
- Agent location
- Space markup shape (node
or
path) where the agents are located while being in this block.
Get value:
entityLocation
- Location of batch
- Defines the place where the new agent (batch) will be placed. There are six alternative options:
Not specified
- You do not specify the location for batches.
Network / GIS node -
Batches are placed in the given network
node,
GIS point, or
GIS region.
Attractor -
Batches are placed in the specified
attractor.
(x, y, z) -
Batches are placed in the point with the specified coordinates
X,
Y,
Z.
(latitude, longitude) -
Batches are placed in the given point on the GIS map with the specified
Latitude
and
Longitude.
Geographic place -
Batches 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:
Batch.LOCATION_NOT_SPECIFIED,
Batch.LOCATION_NODE,
Batch.LOCATION_ATTRACTOR,
Batch.LOCATION_XYZ,
Batch.LOCATION_LATLON,
Batch.LOCATION_GEO_PLACE
- Node
[dynamic]
- [Visible if Location of batch
is Network / GIS node] Network
node,
GIS point, or
GIS region
where the agents created by this block are placed.
Local variable:
agent
- the batch agent created at this block
- Attractor
[dynamic]
- [Visible if Location of batch
is Attractor]
Attractor
where the agents created by this block are put.
Value type:
Attractor
Local variable:
agent
- the batch agent created in this block
- X, Y, Z
[dynamic]
- [Visible if
Location of batch
is (x, y, z)] X,Y,Z coordinates of the point where the agents will be put.
Type of value:
double
Local variable:
agent
- the batch agent created in this block
- ... located in
[dynamic]
- [Visible and applies only if the
Location of batch
option is set to
(x, y, z)] Specifies where the batch agent will be added to upon leaving the block: either
Level
or
Network.
Type of value:
boolean
destinationInNetwork
Default value:
false
- Level
[dynamic]
- [Visible and applies only if the
...located in Level
option is selected] The
level
the batch agent will be added to once it leaves the block.
Type of value:
Level
Local variables:
agent
- the agent
- Network
[dynamic]
- [Visible and applies only if the
...located in Network
option is selected] The network the agent will be added to once it leaves the block.
Type of value:
INetwork
Local variables:
agent
- the agent
- Latitude, Longitude
[dynamic]
- [Visible if
Location of batch
is (latitude, longitude)] Latitude and longitude of the point on the
GIS map
where the batches will be placed.
Type of value:
double
Local variable:
agent
- the agent
- Name of place
[dynamic]
- [Visible if
Location of batch
is Geographic place]
The name of the particular location on the GIS map, where the batches
are placed. 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
- Speed
[dynamic]
- [Visible if
Location of batch
is specified] The speed of the generated agents (batches).
Value type:
double
Default value:
10
m/s
Local variable:
agent
- the agent
-
Advanced
- Add batches to
- Here you specify where the agents-batches 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
- Population
[dynamic]
- [Visible if
Add batches to:
custom population] The name of the agent population where the batches created by this block will be stored.
Value type:
AgentList
Local variable:
TBatch
batch
- the batch agent created in this block
- Forced pushing
- If the option is selected (true), when agents finish processing at the block, they are instantly pushed further regardless the state of the succeeding block.
If the option is not selected, agents are not pushed, but pulled: only
when the succeeding block is ready to accept one more agent, it
requests the agent from this block, and only then the agent passes
further.
Syntax:
boolean
pushProtocol
Default value:
false
- Restore agent location on exit
- If the option is selected, after being animated in the
Agent location
shape, the agents will return to their original location (node
or
path) where they were before entering this
Batch
block.
Syntax:
boolean restoreEntityLocationOnExit
- Force statistics collection
- By
default statistics is collected for all Process Modeling Library
blocks. However, you may tune this and switch off the statistics
collection to optimize your model performance. To do this, add
PML Settings
block and deselect there the option
Enable statistics by default.
This way you switch stats collecting off for all flowchart blocks in
the model. However, you can choose some specific blocks to override
this setting and collect statistics by selecting this particular option
Force statistics collection
in the block properties.
Syntax:
boolean
forceStatisticsCollection
Default value:
false
-
Actions
- On enter
[code]
- Code executed when the agent enters the block.
Local variable:
agent
- the agent
- On add
[code]
- Code executed for each original agent when the (permanent or temporary) batch is formed.
Local variables:
agent
- the agent
TBatch
batch
- the batch agent created in this block
- On exit
[code]
- Code executed when the batch agent exits the block.
Local variable:
TBatch agent
- the batch agent
- On remove
[code]
- Code executed when the agent is intentionally removed from this block by calling agent's
remove()
function. This code is automatically executed after the
remove()
function call.
Local variable:
agent
- the agent
Functions
int size()
- returns the number of agents in this
Batch block.
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.
void resetStats()
- Resets the statistics collected for this block.
Iterator
iterator()
- Returns the iterator over agents in this block.
Ports
- in
- The input port.
- out
- The output port.