The Batch block converts a number of agents into one agent (batch), either by discarding the original agents and creating a new one — permanent batch (whose properties may depend on the original ones), or by adding the original agents to the contents of the new agent — temporary batch, which can later be unbatched by the Unbatch block.

This block embeds a Queue block where it stores the incoming agents. When 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 agents that are currently contained in the batch using the contents() function. The current number of agents in the batch is obtained as batch.contents().size().

Suppose you want to accumulate n agents of type Packet, each with a field size, and create a new agent of the same type but with a size equal to the sum of the original packet sizes. For this purpose, do the following:

1. Specify the original and resulting types: Packet, Packet.
2. Leave the Permanent batch parameter set to true.
3. In the New batch parameter, type new Packet().
4. Set Batch size to n.
5. Enter the following code in the On add action field:

   batch.size = agent.size

If the agents are to be batched not by the number but by some other criteria (for example, total weight, which may 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.

Batch size

The size of the batch.

Syntax: int batchSize
Set new value dynamically: set_batchSize(new value)
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 Set new value dynamically: set_permanent(new value)
Default value: false

New batch

Specify here the agent type for the batches created by this block. Referred below as TBatch.

Default value: Agent

Change dimensions

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

[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

[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

[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.

Syntax: InitialLocationType locationType
Valid values:
Batch.LOCATION_NOT_SPECIFIED
Batch.LOCATION_NODE
Batch.LOCATION_ATTRACTOR
Batch.LOCATION_XYZ
Batch.LOCATION_LATLON
Batch.LOCATION_GEO_PLACE

Node

[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

[Visible if Location of batch is Attractor]
Attractor where the agents created by this block are put.

Type of value: Attractor
Local variable: agent — the batch agent created in this block

X, Y, Z

[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

[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.

Syntax: boolean destinationInNetwork

Level

[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 variable agent — the agent

Network

[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 variable: agent — the agent

Latitude, Longitude

[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

[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

[Visible if Location of batch is specified] The speed of the generated agents (batches).

Type of value: double
Default value: 10 meters per second
Local variable: agent — the agent

Add batches to

Here you specify where the agents-batches created by this block will be stored: in the default population of the top-level agent of the model or in a custom population (specified below in the Population property). The default population (Java collection of type AgentList) contained in the top-level agent can be accessed with the function getDefaultPopulation().

Syntax: boolean addToCustomPopulation

Population

[Visible if Add batches to: custom population]
The name of the agent population where the batches created by this block will be stored.

Type of value: 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
Default value: true

Force statistics collection

This block collects the statistics on the queue size. If the statistics collection is turned off for all Process Modeling Library blocks in the model by the PMLSettings block, this option enables you to override this setting and collect the statistics for this specific block. Otherwise, the statistics will be collected regardless this setting.

Syntax: boolean forceStatisticsCollection
Default value: false

On enter

Code executed when the agent enters the block.

Local variable: agent — the agent

On add

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 executed when the batch agent exits the block.

Local variable: TBatch agent — the batch agent

On remove

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

StatisticsContinuous statsSize

Continuous statistics on the queue size. Is collected if the statistics collection is not turned off by PML Settings block.

Agent

Function	Description
int size()	Returns the number of agents waiting in the embedded queue to be batched in this Batch block.
T remove(Agent agent)	Removes the specified agent from the queue and returns it. If the agent is not contained in the queue, returns null. agent — The agent to remove.
Iterator<T> iterator()	Returns the iterator over the agents in this block.

Statistics

Function	Description
boolean isStatisticsCollected()	Returns true if the block collects statistics.
void resetStats()	Resets the statistics collected for this block.

in

The input port.

out

The output port.

How can we improve this article?

Send