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

Please note that by default Source does not allow the agents to wait at its output until they can be consumed by the next object. You can change this setting by deselecting the advanced option Forced pushing and choosing the required behavior from the list Agents which can't exit.

Apart from Source, there are other ways to create agents in the Process Modeling Library models. For example, you can use Enter object 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.

Demo model: Source Arrival Modes

Parameters

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, Source.INTERARRIVAL_TIME, Source.DATABASE_ARRIVAL_TABLE, Source.RATE_TABLE, Source.ARRIVAL_TABLE, Source.MANUAL
Arrival rate
[Visible if Arrivals defined by: Rate] The arrival rate of agents. If rate is used and it becomes 0, no next arrival will be scheduled until the rate changes to a positive value.
Syntax: double rate
Default value: 1 per second
Interarrival time [dynamic]
[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. 
Value type: double
Default value: exponential(1) second
Database table
[Visible if Arrivals defined by: Arrival table in Database] Choose here the database table containing the data on agent arrivals.
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
Rate expression [dynamic]
[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
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
Agents per arrival [dynamic]
[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 the Limited number of arrivals is selected] The maximum number of arrivals to be generated by this object.
Syntax: long maxArrivals
Location of arrival
Defines the place where the generated agents will be put. There are six alternative options:
Not specified - You do not specify the agents' arrival place.
Network / GIS node - Agents appear in the given network nodeGIS 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.
Get value: locationType
Valid values: Source.LOCATION_NOT_SPECIFIED, Source.LOCATION_NODE, Source.LOCATION_ATTRACTOR, Source.LOCATION_XYZ, Source.LOCATION_LATLON, Source.LOCATION_GEO_PLACE
Speed [dynamic]
[Visible if Location of arrival is specified] The speed of the generated agents.
Value type: double
Default value: 10 meters per second
Local variable: agent - the agent
X, Y, Z [dynamic]
[Visible if Location of arrival 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 agent
... in the network
[Visible if Location of arrival 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 agent
Node [dynamic]
[Visible if Location of arrival is Network / GIS node] Network nodeGIS point, or GIS region where the agents created by this block are put.
Value type: Node
Local variable: agent - the agent
Attractor [dynamic]
[Visible if Location of arrival is AttractorAttractor where the agent will move.
Value type
: Attractor
Local variable: agent - the agent
Latitude, Longitude [dynamic]
[Visible if Location of arrival is (latitude, longitude)] Latitude and longitude of the point on the GIS map where the agents will be placed.
Type of value: double
Local variable: agent - the agent
Name of place [dynamic]
[Visible if Location of arrival is 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.
Type of value: String
Local variable: agent - the agent
Agent
New agent [dynamic]
The type of agents generated by block.
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 [dynamic]
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.
Type of value: boolean
Local variable:  agent - the agent
Length [dynamic]
[Visible if the Change dimensions option is selected] The new length of the generated agent.
Type of value: double
Local variable:  agent - the agent
Width [dynamic]
[Visible if the Change dimensions option is selected] The new width of the generated agent.
Type of value: double
Local variable:  agent - the agent
Height [dynamic]
[Visible if the Change dimensions option is selected] The new height of the generated agent.
Type of value: double
Local variable:  agent - the agent
Advanced
Custom time of start
If the option is selected (true), you can set the object to start generating agents at some custom moment of model time.
Syntax: boolean enableCustomStartTime
Time of start
[Visible when the Custom time of start is selected] The moment of model time when the object 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, or in some custom population (specified below in the Population property). The default population (Java collection of type AgentList<Agent> ) contained in the top-level agent can be accessed with the function getDefaultPopulation().
Syntax:  boolean addToCustomPopulation
Population [dynamic]
[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: 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
Choose here how the agents that cannot exit the block, are treated: whether they are destroyed, or wait in this block.
Syntax: boolean discardHangingEntities
Actions
On before arrival [code]
Code executed before the agent is generated.
On at exit [code]
Code executed when the agent is ready to exit the object.
Local variable: agent - the agent.
On exit [code]
Code executed when the agent exits the object.
Local variable: agent - the agent.
On discard [code]
[Visible if Agents which can't exit are destroyed] Code executed when the agent exits the object.
Local variable: agent - the agent.

Functions

void inject(int n) - Generates the specified number of agents (n) agents at the time of call.

long count() - Returns number of agents generated by this object.

long countArrivals() - Returns the number of arrivals (note that one arrival can generate several agents) occurred in this Source object so far.

Ports

out
The output port.