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

This object embeds a Queue object where it stores the incoming agents. Once the number of the stored agents reaches the batch size, the batch is created and leaves the object immediately.

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 object instead of Batch.

The other objects 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 object).
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 nodeGIS 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
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
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 at this object
... in the network
[Visible if Location of batch 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 batch agent created at this object
Node [dynamic]
[Visible if Location of batch is Network / GIS node] Network nodeGIS point, or GIS region where the agents created by this block are placed.
Local variable: agent -  the batch agent created at this object
Attractor [dynamic]
[Visible if Location of batch is AttractorAttractor where the agents created by this block are put.
Value type
: Attractor
Local variable: agent -  the batch agent created at this object
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
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 at this object
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 object.
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 at this object
On exit [code]
Code executed when the batch agent exits the object.
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 to be batched in this Batch.

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

Iterator<T> iterator() - Returns the iterator over agents in this block.

Ports

in
The input port.
out
The output port.