Skip to content
Junling Ma edited this page Mar 24, 2023 · 5 revisions

Agent Class

This is an R6 class that represent an agent. The key task of an agent is to maintain events, and handle them in the chronological order. Agents also maintain their states, which is a list of values. The events, when handled, operate on the state of the agent (or other agents).

During the simulation the agent with the earliest event in the simulation is picked out, unscheduled, then its earliest event is handled, which potentially causes the state change of the agent (or another agent in the simulation). The state change is then logged by loggers that recognize the state change.

An agent itself cannot handle the event. Instead, it has to be added to a simulation (or a population that itself is added to a simulation).

Constructor

Usage

    initialize = function(agent=NULL)

Arguments

  • agent: either an external pointer to an agent such as one returned by newAgent, or a list representing the initial state for creating a new agent, or NULL (an empty state)

Schedule an event

Usage

    schedule = function(event)

Argument

  • event: an object of the R6 class Event, or an external pointer returned by newEvent

Return value

The agent itself to chain actions.

Unschedule an event

Usage

    unschedule = function(event)

Argument

  • event: an object of the R6 class Event, or an external pointer returned by newEvent

Return value

The agent itself to chain actions.

Unschedule all events

Usage

    clearEvents = function()

Return value

The agent itself to chain actions.

Leaving a population

Usage

    leave = function()

Return value

the agent itself

Details

When an agent leaves a population, it is not in the simulation any more. If it does not enter another population, it is then considered dead.

Set the time of death

Usage

    setDeathTime = function(time)

Argument

  • time: the time of death, a numeric value

Return value

the agent itself

Details

At the time of death, the agent is removed from the simulation. Calling it multiple times causes the agent to die at the earliest time.

Active Fields

State

The field $state can access or change the state of an agent

ID

The field $id retrieves the ID of an agent. Each agent in a population gets a unique ID in the population.

The C++ Pointer

The field $get retrieves the C++ pointer to the C++ Agent object.

State of an agent

In this framework, a state is an R list, each named component is called a domain. The value of a domain can be any R value. The list can be at most one unnamed value, which corresponds to a domain with no name. This is useful if there is only one domain.

Matching states

A state can be matched to an R list (called a rule in this case). The state matches the rule if and only if each domain (names of the list) in rule has the same value as in state. The domains in domains of the state not listed in rule are not matched. In addition, to match to a rule, the domain values must be either a number or a character. This is usefulfor identifying state changes. See the newCounter function and the Simulation class' addTransition method for more details.

The R functions

newAgent

Usage

   newAgent = function(state, death_time)

Arguments

  • state: a list giving the initial state of the agent, or NULL (an empty list)
  • death_time: the death time for the agent, an optional numeric value.

Return value

an external pointer pointing to the agent

Details

Setting death_time is equivalent to calling the setDeathTime function.

getID

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a

Return value

an integer value

Details

Before an agent is added to a population, its id is 0. After it is added, its id is the index in the population (starting from 1). If agent is an R6 object, then we should either use agent$id or use getID(agent$get)

getState

Get the sate of an agent. In this framework, a state is a list, each named component is called a domain. This function only updates the values of the domain given in the "value" list, while leave the other components not in the "value" list unchanged.

Usage

   getState = function(agent)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a

Return value

a list holding the state

Details `

If agent is an R6 object, then we should either use agent$schedule(event), or use schedule(agent$get, event)

setState

set the state of an agent. In this framework, a state is a list, each named component is called a domain. This function only updates the values of the domain given in the "value" list, while leave the other components not in the "value" list unchanged.

Usage

   setState = function(agent, state)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a
  • state: a list giving the components of the state to be undated.

Return value

the agent itself

Details

If agent is an R6 object, then we should either use agent$schedule, or use schedule(agent$get, event)

matchState

Check if the state of the agent matches the rule.

Usage

   matchState = function(agent, rule)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a
  • rule a list holding the state to match against

@return a logical value

details The state of an agent matches the rule if and only if each domain (names of the

list) in rule has the same value as in state. The domains in domains of the state not listed in rule are not matched

schedule

Usage

   schedule = function(agent, event)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a
  • event: an external pointer returned by the newEvent function

Return value

the agent itself

Details

If agent is an R6 object, then we should use either agent$schedule(event) or schedule(agent$get, event). Similarly, if event is an R6 object, then we should use schedule(agent, event$get)

unschedule

Usage

   unschedule = function(agent, event)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a
  • event: an external pointer returned by the newEvent function

Return value

the agent itself

Details

If agent is an R6 object, then we should use either agent$unschedule(event) or unschedule(agent$get, event). Similarly, if event is an R6 object, then we should use unschedule(agent, event$get)

clearEvents

Usage

   clearEvents = function(agent)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a

Return value

the agent itself

Details

If agent is an R6 object, then we should use either agent$clearEvents() or clearEvents(agent$get)

leave

Cause the agent to leave the population it was in. Without entering another population, it leaves the simulation.

Usage

   leave = function(agent)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a

setDeathTime

Usage

   setDeathTime = function(agent, time)

Arguments

  • agent: an external pointer pointing to the agent, e.g., returned by the newAgent function or by the getAgent method of a population.
  • time: the death time for the agent, a numeric value.