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. You can obtain the collection of the agents that have been added to the queue with the help of the contents() function.

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 generic parameters the original and resulting types: Packet, Packet, leave permanent parameter set to true, set batchSize to N, specify new Packet() in newEntity, and write in onAdd: 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 ifLocation of batch isNetwork / 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 ifLocation of batch isAttractor] 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 isGeographic 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 waiting in the embedded queue to be batched in this Batch.

Queue contents() - Returns the collection of agents that have been added to the embedded queue so far.

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.