Source

Generates agents. Is usually a starting point of a process model.

The agents may be standard, or of any user-defined agent type. You can customize the generated agents by specifying the agent type in New agent field, and then specifying the action that should be performed before the agent exits the Source block in On exit action field.

There is a number of ways to define when and how many agents should be generated.

You can use arrival rate (and change it dynamically by calling set_rate()), interarrival time, rate defined by a schedule, schedule of exact arrival times and quantities, and you also can programmatically call the inject() function of this block. For example, a Poisson stream of arrivals can be implemented by choosing arrivals with a certain rate, or by specifying the exponentially distributed interarrival time. You can also set the number of agents in each arrival and limit the total number of arrivals.

In some cases it makes sense to use two or more Source blocks to implement complex arrival patterns.

Apart from Source, there are other ways to create agents in the Process Modeling Library models. For example, you can use Enter block as a flow starting point and call its take() function to inject agents. The latter function makes sense when the agents are generated elsewhere (e.g by a statechart or an event) and just need to be injected into the process.

Arrivals defined by

Specifies the mode of agent generation:

Rate — agents are generated at the specified arrival rate (which is equivalent to exponentially distributed interarrival time with mean = 1/rate).
Interarrival time — the time between two subsequent agents is defined by the specified expression (use this option to generate agents with e.g. regular intervals or with non-exponential interarrival times).
Arrival table in Database — agents are generated according to the records in the specified database table. You specify the table below in the Database table parameter, then select the table column containing the arrival moments in the Arrival date drop-down list. The block will generate one agent per each data record in the specified table. If you need to generate multiple agents per one record, select the Multiple agents per arrival checkbox below, and specify how many agents should be generated per arrival in the Agents per arrival field.
Rate schedule — agents are generated using rate schedule — a schedule defining how the arrival rate changes with time.
Arrival schedule — agents are generated using arrival schedule — a schedule defining how many agents should be generated at particular moments of time.
Calls of inject() function — agents are not generated automatically and are only generated on calls of inject() method.

Syntax: int arrivalType
Default value: Rate
Valid values:
Source.RATE — Rate
Source.INTERARRIVAL_TIME — Interarrival time
Source.DATABASE_ARRIVAL_TABLE — Arrival table in Database
Source.RATE_TABLE — Rate schedule
Source.ARRIVAL_TABLE — Arrival schedule
Source.MANUAL — Calls of inject() function

Arrival rate

[Visible if Arrivals defined by: Rate]
The arrival rate of agents. If rate is used and its value becomes negative or zero, no next arrival will be scheduled until the rate changes to a positive value.

Syntax: double rate
Default value: 1 per second

Interarrival time

[Visible if Arrivals defined by: Interarrival time]
Expression used to evaluate the delay time for each agent. If interarrival time is used and it occasionally evaluates to infinity, the Source stops generating agents and will never resume. If timeout value becomes negative or zero, the error raises.

Value type: double
Default value: exponential(1) seconds

First arrival occurs

[Visible if Arrivals defined by: Interarrival time]
Specifies the time of the first agent arrival to block Source.

After timeout — the first agent arrival occurs after the time specified in Interarrival time parameter has run out.
At model start — the first arrival occurs when the model is run.
At the specified time — the first arrival occurs at the moment of time specified in the First arrival time parameter.

Syntax: FirstArrivalMode firstArrivalMode
Valid values:
Source.AFTER_TIMEOUT
Source.AT_START
Source.AT_TIME

First arrival time

[Visible if First arrival occurs: At the specified time]
The exact time when the Source block generates the first agent(s). This time cannot be less that the model run time or the time of creation and initialization of this Source block.

Syntax: double firstArrivalTime

Database table

[Visible if Arrivals defined by: Arrival table in Database]
Choose here the database table containing the data on agent arrivals.

Syntax: TableInput databaseTable

Arrival date

[Visible if Arrivals defined by: Arrival table in Database]
Choose here the column of the Database table that contains the agent arrival timestamps.

Rate schedule

[Visible if Arrivals defined by: Rate schedule]
The name of the schedule defining how the arrival rate changes with time.

Syntax: Schedule rateSchedule

Modify rate

[Visible if Arrivals defined by: Rate schedule]
If the option is enabled, you can specify the expression, according to which rate is modified, in the parameter below.

Syntax: boolean modifyRate
Default value: false

Rate expression

[Visible if Modify rate is enabled]
Here you can enter the expression that will evaluate rate.

Value type: double
Default value: baseRate
Local variable: double baseRate — schedule rate value

Arrival schedule

[Visible if Arrivals defined by: Arrival schedule]
The name of the schedule defining how many agents should be generated at particular moments of time.

Syntax: Schedule<Integer> arrivalSchedule

Set agent parameters from DB

[Visible and applies if Arrivals defined by option isn’t set to Arrival table in Database or Calls of inject() function]
If the option is selected (true), enables initialization of agents' parameters from the model database. The technique is described here.

Syntax: boolean setAgentParametersFromDB
Set new value at runtime: set_setAgentParametersFromDB(new value)

Database table

[Visible and applies only if the Set agent parameters from DB option is set]
Specify the database table containing the data (parameter values) of arriving agents.

Syntax: TableInput databaseTable
Set new value at runtime: set_databaseTable(new value)

Multiple agents per arrival

[Visible if Arrivals defined by: Rate, Interarrival time, Arrival table in Database, Rate schedule]
If the option is selected (true), multiple agents will be generated per every arrival.

Syntax: boolean multipleEntitiesPerArrival
Default value: false

Agents per arrival

[Visible if Multiple agents per arrival is selected]
The number of agents in an arrival.

Value type: int
Default value: uniform_discr(3, 5)

Limited number of arrivals

If the option is selected (true), the number of arrivals will be limited to Number of arrivals.

Syntax: boolean limitArrivals

Maximum number of arrivals

[Visible when Limited number of arrivals is selected]
The maximum number of arrivals to be generated by this block.

Syntax: long maxArrivals

Location of arrival

Defines the place where the generated agents will be put. There are several alternative options:

Not specified — You do not specify the agents' arrival place.
Network / GIS node — Agents appear in the given network node, GIS point, or GIS region.
Attractor — Agents appear in the specified attractor.
(x, y, z) — Agents appear in the point with the specified coordinates X, Y, Z.
(latitude, longitude) — Agents appear in the given point on the GIS map with the specified Latitude and Longitude.
Geographic place — Agents appear in the particular location on the GIS map. You define this place using the Name of place parameter below.

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

Node

[Visible if Location of arrival: Network / GIS node]
Network node, GIS point, or GIS region where the agents created by this block are put.

Value type: INode
Local variable: T agent — the agent

Attractor

[Visible if Location of arrival: Attractor]
Attractor where the agent will move.

Value type: Attractor
Local variable: T agent — the agent

X, Y, Z

[Visible if Location of arrival: (x, y, z)]
X, Y, Z coordinates of the point where the agents will be put.

Value type: double
Local variable: T agent — the agent

... located in

[Visible and applies only if Location of arrival: (x, y, z)]
Specifies where the agents will be added to when they are generated by this block: either Level or Network.

Syntax: boolean destinationInNetwork
Default value: false

Level

[Visible and applies only if ...located in Level option is selected]
The level the agents will be added to once they are generated by this block.

Value type: Level
Local variable: T agent — the agent

Network

[Visible and applies only if ...located in Network option is selected]
The network the agent will be added to once they are generated by this block.

Value type: INetwork
Local variable: T agent — the agent

Latitude, Longitude

[Visible if Location of arrival: (latitude, longitude)]
Latitude and longitude of the point on the GIS map where the agents will be placed.

Value type: double
Local variable: T agent — the agent

Name of place

[Visible if Location of arrival: Geographic place]
The name of the particular location on the GIS map, where the 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.

Value type: String
Local variable: T agent — the agent

Speed

[Visible if Location of arrival is specified]
The speed of the generated agents.

Value type: double
Default value: 10 meters per second
Local variable: T agent — the agent

New agent

The type of agents generated by block. Referred in the article as T. Typically you just select the agent type name from the list. In rare cases (e.g. when you need to parameterize agents with different attribute values), you can switch to the dynamic value editor and specify the agent type constructor there.

Default value: Agent

Change dimensions

If the option is selected (true), you will be able to change the dimensions of the agent generated by this block specifying the new Length, Width, and Height values below.

Value type: boolean
Local variable: T agent — the agent

Length

[Visible if Change dimensions option is selected]
The new length of the generated agent.

Value type: double
Local variable: T agent — the agent

Width

[Visible if Change dimensions option is selected]
The new width of the generated agent.

Value type: double
Local variable: T agent — the agent

Height

[Visible if Change dimensions option is selected]
The new height of the generated agent.

Value type: double
Local variable: T agent — the agent

Custom time of start

If the option is selected (true), you can set the block to start generating agents at some custom moment of model time.

Syntax: boolean enableCustomStartTime

Time of start

[Visible when Custom time of start is selected]
The moment of model time when the block starts generating agents.

Syntax: double startTime

Add agents to

Here you specify where the agents 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
Default value: false — default population

Population

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

Name: AgentList
Local variable: T agent — the agent

Forced pushing

If the option is selected (true), when agents are generated by 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 act according the behavior chosen in the parameter below.

Syntax: boolean pushProtocol
Default value: true

Agents which can't exit

[Visible if Forced pushing is not selected]
Choose here how the agents that cannot exit the block, are treated: whether they are destroyed or wait in this block.

Syntax: boolean discardHangingEntities
Default value: true — are destroyed

On before arrival

Code executed before the agent is generated.

On at exit

Code executed when the agent is ready to exit the block.

Local variable: T agent — the agent

On exit

Code executed when the agent exits the block.

Local variable: T agent — the agent

On discard

[Visible if Agents which can't exit: are destroyed]
Code executed when the agent exits the block.

Local variable: T agent — the agent

Injecting agents

Function	Description
void inject()	Generates a single agent at the time of the call.
void inject(int n)	Generates the specified number of agents at the time of call. n — The number of agents to generate.

Count generated agents

Function	Description
long count()	Returns the number of agents generated by this block.
long countArrivals()	Returns the number of arrivals (note that one arrival can generate several agents) occurred in this Source block so far.

out

The output port.

How can we improve this article?

Send