episimmer.vulnerability_detection

Contents

Vulnerable Agents API
Agent Vulnerability API
Event Vulnerability API

class VD(vd_config_obj, world_obj)[source]

Class for implementing all types of Vulnerability Detection modules.

Parameters

vd_config_obj (episimmer.read_file.ReadVDConfiguration) – ReadVDConfiguration object
world_obj (episimmer.world.World) – World object of simulation

get_class(name)[source]

Returns the class of the vulnerability detection module.

Parameters: name (str) – Name of module given as a string
Returns: Class of vulnerability detection module
Return type: Callable

add_target_name()[source]

Returns the name of python file for given user target.

Returns: Name of python file
Return type: str

get_algorithm()[source]

Returns the class of the vulnerability detection algorithm based on user input in vd_config.txt.

Returns: Class of the vulnerability detection algorithm
Return type: Callable

run_vul_detection()[source]

Runs the vulnerability detection algorithm

Return type: None

run_output(algo_object)[source]

This function by default prints 10 maximum and 10 minimum scores post detection.

Parameters: algo_object (Union[episimmer.vulnerability_detection.base.AgentVD, episimmer.vulnerability_detection.base.EventVD]) – Object of the vulnerability detection module
Return type: None

run_preprocess()[source]

Functionality to be run pre detection

Return type: None

run_postprocess()[source]

Functionality to be run post detection

Return type: None

class AgentVD(world_obj)[source]

Base class for implementing Agent Vulnerability Detection modules.

Parameters: world_obj (episimmer.world.World) – World object of simulation

init_scores()[source]

Initialises scores for all agents with value 0.0.

Return type: None

one_run(*args, **kwargs)[source]

Executes a single run of the agent vulnerability detection module.

Return type: object

update_agent_scores(*args, **kwargs)[source]

Function to update the agent scores.

Return type: None

run_detection()[source]

Function to run the complete agent vulnerability detection module. This function will ideally call the one_run function multiple times.

Return type: None

get_max_score_agents(n)[source]

Function to return the n maximum agent scores as a dictionary.

Parameters: n (int) – Number of elements to be returned
Returns: A dictionary mapping agent keys to agent scores. Scores are ordered in descending order
Return type: Dict[str, float]

get_min_score_agents(n)[source]

Function to return the n minimum agent scores as a dictionary.

Parameters: n (int) – Number of elements to be returned
Returns: A dictionary mapping agent keys to agent scores. Scores are ordered in ascending order
Return type: Dict[str, float]

print_default_output(n)[source]

Prints the n maximum and n minimum agent scores.

Parameters: n (int) – Number of elements to be printed
Return type: None

class EventVD(world_obj)[source]

Base class for implementing Event Vulnerability Detection modules.

Parameters: world_obj (episimmer.world.World) – World object of simulation

init_scores()[source]

Initialises scores for all events..

Return type: None

one_run(*args, **kwargs)[source]

Executes a single run of the event vulnerability detection module.

Return type: None

update_event_scores(*args, **kwargs)[source]

Function to update the event scores.

Return type: None

run_detection()[source]

Function to run the complete event vulnerability detection module. This function will ideally call the one_run function multiple times.

Return type: None

get_max_score_events(n)[source]

Function to return the n maximum event scores as a dictionary.

Parameters: n (int) – Number of elements to be returned
Returns: A dictionary mapping event keys to event scores. Scores are ordered in descending order
Return type: Dict[str, float]

get_min_score_events(n)[source]

Function to return the n minimum event scores as a dictionary.

Parameters: n (int) – Number of elements to be returned
Returns: A dictionary mapping event keys to event scores. Scores are ordered in ascending order
Return type: Dict[str, float]

print_default_output(n)[source]

Prints the n maximum and n minimum event scores.

Parameters: n (int) – Number of elements to be printed
Return type: None

Vulnerable Agents API 

`VulnerableAgent`	Class for implementing Vulnerable Agent modules.
`SimpleVulnerableAgent`	Class that implements the Simple Vulnerable Agent module.
`EarlyVulnerableAgent`	Class that implements the Early Vulnerable Agent module.

class VulnerableAgent(world_obj)[source]

Class for implementing Vulnerable Agent modules.

Parameters: world_obj (episimmer.world.World) – World object of simulation

class SimpleVulnerableAgent(world_obj, parameter_dict)[source]

Class that implements the Simple Vulnerable Agent module. This class scores the agent based on the number of times he was infected in multiple simulations. Inherits VulnerableAgent class.

\[Agent\ Score = \sum_{i=0}^{N-1}{ 1[Agent\ Infected]}\]

where N refers to the total number of simulation runs.

The Algorithm Parameter File in the vd_config file must contain the parameters states and num_runs.

‘states’ refers to the states in the simulation that are infectious or post-infectious

‘num_runs’ refers to the total number of simulation runs

An example of the vd_config.txt file and the algorithm parameter file (parameter.json) is given below

vd_config.txt

VD Target <Agent>
VD Algorithm <SimpleVulnerableAgent>
Algorithm Parameter File <parameter.json>
Pre Processing <>
Post Processing <>
Output Mode <Default>

parameter.json

{
    "states":["Infected","Recovered"],
    "num_runs":100
}

Parameters

world_obj (episimmer.world.World) – World object of simulation
parameter_dict (Dict[str, Union[List[str], int]]) – Dictionary of parameters relevant to the algorithm

update_agent_scores(agents_obj)[source]

Function to update the agent scores.

Parameters: agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
Return type: None

one_run()[source]

Executes a single run of the detection module.

Return type: None

run_detection()[source]

Function to run the complete detection module.

Return type: None

class EarlyVulnerableAgent(world_obj, parameter_dict)[source]

Class that implements the Early Vulnerable Agent module. This class scores the agent based on the number of times he was infected in multiple simulations and also given a higher score if he was infected earlier. Inherits VulnerableAgent class.

\[Agent\ Score = \sum_{i=0}^{N-1}(Total\ Timesteps - Timestep\ Infected)\]

where N refers to the total number of simulation runs. Note that if the agent was not infected, his score for that run would be 0.

The Algorithm Parameter File in the vd_config file must contain the parameters states and num_runs.

‘states’ refers to the states in the simulation that are infectious or post-infectious

‘num_runs’ refers to the total number of simulation runs

An example of the vd_config.txt file and the algorithm parameter file (parameter.json) is given below

vd_config.txt

VD Target <Agent>
VD Algorithm <EarlyVulnerableAgent>
Algorithm Parameter File <parameter.json>
Pre Processing <>
Post Processing <>
Output Mode <Default>

parameter.json

{
    "states":["Infected","Recovered"],
    "num_runs":100
}

Parameters

world_obj (episimmer.world.World) – World object of simulation
parameter_dict (Dict[str, Union[List[str], int]]) – Dictionary of parameters relevant to the algorithm

reset_start_infection(agents_obj)[source]

Resets each agent’s start infection step dictionary

Parameters: agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
Return type: None

update_agent_scores(agents_obj)[source]

Function to update the agent scores.

Parameters: agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
Return type: None

update_agent_start_infection(agents_obj, time_step)[source]

Updates the agents start infection time step

Parameters

agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
time_step (int) – Current time step

Return type

None

one_run()[source]

Executes a single run of the module.

Returns: The end_state, agents object and locations object
Return type: Tuple[Dict[str, List[int]], episimmer.read_file.ReadAgents, episimmer.read_file.ReadLocations]

run_detection()[source]

Function to run the complete detection module.

Return type: None

Agent Vulnerability API 

`AgentVulnerability`	Class for implementing Agent Vulnerability modules.
`SimpleAgentVulnerability`	Class that implements the Simple Agent Vulnerability module.
`ChunkAgentVulnerability`	Class that implements the Chunk Agent Vulnerability module.
`BanditAlgos`	Class that implements the Agent Vulnerability module with Bandit Algorithms.

class AgentVulnerability(world_obj)[source]

Class for implementing Agent Vulnerability modules.

Parameters: world_obj (episimmer.world.World) – World object of simulation

remove_agents(*args, **kwargs)[source]

Function used to remove agents from the list of valid agents.

Return type: None

class SimpleAgentVulnerability(world_obj, parameter_dict)[source]

Class that implements the Simple Agent Vulnerability module. This class scores the agent based on the severity of outbreak after the agent’s removal. Multiple simulations are run by randomly selecting and removing an agent and running the simulation. The agent score is calculated by finding the running average of scores for each run. Inherits AgentVulnerability class.

\[Agent\ Score = 1 - \frac{Total\ Agents\ Infected}{Total\ Agents}\]

The Algorithm Parameter File in the vd_config file must contain the parameters states, num_runs and num_agents_to_remove.

‘states’ refers to the states in the simulation that are infectious or post-infectious

‘num_runs’ refers to the total number of simulation runs

‘num_agents_to_remove’ refers to the number of agents to be removed

An example of the vd_config.txt file and the algorithm parameter file (parameter.json) is given below

vd_config.txt

VD Target <Agent>
VD Algorithm <SimpleAgentVulnerability>
Algorithm Parameter File <parameter.json>
Pre Processing <>
Post Processing <>
Output Mode <Default>

parameter.json

{
    "states":["Infected","Recovered"],
    "num_runs":100,
    "num_agents_to_remove":1
}

Parameters

world_obj (episimmer.world.World) – World object of simulation
parameter_dict (Dict[str, Union[List[str], int]]) – Dictionary of parameters relevant to the algorithm

init_scores()[source]

Initialises scores and counts for all agents with value 0.0 and 0 respectively.

Return type: None

remove_agents(agents_obj, num_agents_to_remove)[source]

Function used to remove agents from the list of valid agents.

Parameters

agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
num_agents_to_remove (int) – Number of agents to remove each simulation

Return type

None

update_agent_scores(end_state)[source]

Function to update the agent scores.

Parameters: end_state (Dict[str, List[int]]) – Dictionary mapping states to time step wise population
Return type: None

one_run()[source]

Executes a single run of the detection module.

Return type: None

run_detection()[source]

Function to run the complete detection module.

Return type: None

class ChunkAgentVulnerability(world_obj, parameter_dict)[source]

Class that implements the Chunk Agent Vulnerability module. This class scores the agent based on the severity of outbreak after the agent’s removal. Multiple simulations are run by randomly selecting and removing an agent and running the simulation. The agent score is calculated by finding the running average of scores for each run. For higher stability, chunks of the entire simulation are considered instead of the entire simulation. Inherits AgentVulnerability class.

\[Agent\ Score = \sum_{i=0}^{N-1}((Agents\ Infected\ at\ timestep\ \gamma) - (Agents\ Infected\ at\ timestep\ \beta))\]

where \(\beta\) is a randomly generated integer based on the user defined parameters for chunk length, and \(\gamma\) = \(\beta\) + \(chunk\ length\) - 1. N refers to the total number of simulation runs.

The Algorithm Parameter File in the vd_config file must contain the parameters states, num_runs, num_agents_to_remove and chunk_len_range.

‘states’ refers to the states in the simulation that are infectious or post-infectious

‘num_runs’ refers to the total number of simulation runs

‘num_agents_to_remove’ refers to the number of agents to be removed

‘chunk_len_range’ refers to the range of time steps the simulation should be run (default = [1,50])

An example of the vd_config.txt file and the algorithm parameter file (parameter.json) is given below

vd_config.txt

VD Target <Agent>
VD Algorithm <ChunkAgentVulnerability>
Algorithm Parameter File <parameter.json>
Pre Processing <>
Post Processing <>
Output Mode <Default>

parameter.json

{
    "states":["Infected","Recovered"],
    "num_runs":100,
    "num_agents_to_remove":1,
    "chunk_len_range":[1,30]
}

Parameters

world_obj (episimmer.world.World) – World object of simulation
parameter_dict (Dict[str, Union[List[str], int, List[int]]]) – Dictionary of parameters relevant to the algorithm

remove_agents(agents_obj, num_agents_to_remove)[source]

Function used to remove agents from the list of valid agents.

Parameters

agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
num_agents_to_remove (int) – Number of agents to remove each simulation

Return type

None

reset_world()[source]

Initialisations to be performed each world.

Return type: None

get_scores(agents_obj)[source]

Returns the agent score based on the agent states

Parameters: agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
Returns: The agent score
Return type: float

update_agent_scores(agents_obj, time_step, mode)[source]

Function to update the agent scores.

Parameters

agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
time_step (int) – Current time step
mode (str) – Mode decides whether the simulation is at its start or end

Return type

None

one_run(start, end)[source]

Executes a single run of the module from start to end time step.

Parameters

start (int) – Start time step where simulation must be considered
end (int) – End time step where simulation must be ended

Return type

None

generate_bounds()[source]

Returns the start and end time steps for a simulation

Returns: Start and End time steps.
Return type: Tuple[int, int]

run_detection()[source]

Function to run the complete detection module.

Return type: None

get_maximum_agent_vulnerability(n)[source]

Function to return the n maximum agent vulnerabilities as a dictionary.

Parameters: n (int) – Number of elements to be returned
Returns: A dictionary mapping agent keys to agent scores. Scores are ordered in ascendinng order
Return type: Dict[str, float]

get_minimum_agent_vulnerability(n)[source]

Function to return the n minimum agent vulnerabilities as a dictionary.

Parameters: n (int) – Number of elements to be returned
Returns: A dictionary mapping agent keys to agent scores. Scores are ordered in descending order
Return type: Dict[str, float]

class BanditAlgos(world_obj, parameter_dict)[source]

Class that implements the Agent Vulnerability module with Bandit Algorithms. Inherits AgentVulnerability class.

We first select an agent for removal based on either epsilon greedy or the UCB1 algorithm, then we run the simulation.

I) Agent Selection

Epsilon Greedy

Random selection of agent done with probability \(\epsilon\) and greedy (highest scoring agent) selection of agent with probability 1 - \(\epsilon\).

UCB1

Selection of agent based on equation -

\[\arg \max_{a} \bigg( running\ avg\ score_{a} + \sqrt{\frac{2 \log{t}}{N_t(a)}} \bigg)\]

where \(a\) represents an agent and \(N_t(a)\) represents the number of times agent \(a\) has been selected for removal.

II) Agent Score

After removal, the simulation is run to get the score of the removed agent. Score of the agent is based on the severity of outbreak after the agent’s removal.

The agent score is calculated by finding the running average of scores for each run. The score for a single run is given by -

\[Agent\ Score = 1 - \frac{Total\ Agents\ Infected}{Total\ Agents}\]

The Algorithm Parameter File in the vd_config file must contain the parameters ‘states’, ‘num_runs’, and ‘mode’.

‘states’ refers to the states in the simulation that are infectious or post-infectious

‘num_runs’ refers to the total number of simulation runs

‘mode’ refers to the mode or algorithm to be used to select agent. Two options are present - ‘EPS’ or epsilon greedy and ‘UCB’ or Upper Confidence Bound algorithm. (default = ‘EPS’)

An example of the vd_config.txt file and the algorithm parameter file (parameter.json) is given below

vd_config.txt

VD Target <Agent>
VD Algorithm <BanditAlgos>
Algorithm Parameter File <parameter.json>
Pre Processing <>
Post Processing <>
Output Mode <Default>

parameter.json

{
    "states":["Infected","Recovered"],
    "num_runs":100,
    "mode":"UCB"
}

Parameters

world_obj (episimmer.world.World) – World object of simulation
parameter_dict (Dict[str, Union[List[str], int, str]]) – Dictionary of parameters relevant to the algorithm

init_scores()[source]

Initialises agent scores to the score from one run of the algorithm without the said agent. Agent counts is also initialised to 0.

Return type: None

get_init_score(agent_index)[source]

Returns the agent’s score by running one simulation without the agent

Parameters: agent_index (str) – Current agent’s index
Returns: Score of the agent
Return type: float

remove_agents(agents_obj)[source]

Function to remove an agent

Parameters: agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
Return type: None

get_score(end_state)[source]

Function to return agent’s score

Parameters: end_state (Dict[str, List[int]]) – Dictionary mapping states to time step wise population
Returns: Score of the agent
Return type: float

update_agent_scores(end_state)[source]

Function to update the agent scores.

Parameters: end_state (Dict[str, List[int]]) – Dictionary mapping states to time step wise population
Return type: None

one_run_helper(agents_obj)[source]

One Run helper

Parameters: agents_obj (episimmer.read_file.ReadAgents) – ReadAgents object
Returns: The end_state, agents object and locations object
Return type: Tuple[Dict[str, List[int]], episimmer.read_file.ReadAgents, episimmer.read_file.ReadLocations]

one_run()[source]

Executes a single run of the detection module.

Return type: None

run_detection()[source]

Function to run the complete detection module.

Return type: None

print_default_output(n)[source]

Prints the n maximum agent scores.

Parameters: n (int) – Number of elements to be printed
Return type: None

Event Vulnerability API 

SimpleEventVulnerability

This class implements the Simple Event Vulnerability module.

class SimpleEventVulnerability(world_obj, parameter_dict)[source]

This class implements the Simple Event Vulnerability module. This class scores the event based on the severity of outbreak after locking down all other events. Multiple simulations are run by randomly selecting an event. The event score is calculated by finding the running average of scores for each run. Inherits EventVulnerability class.

\[Event\ Score = \frac{Total\ Agents\ Infected}{Total\ Agents}\]

The Algorithm Parameter File in the vd_config file must contain the parameters ‘states’, ‘num_runs’ and ‘event_identifier’.

‘states’ refers to the states in the simulation that are infectious or post-infectious

‘num_runs’ refers to the total number of simulation runs

‘event_identifier’ refers to the name of the event identifier to differentiate events

An example of the vd_config.txt file and the algorithm parameter file (parameter.json) is given below

vd_config.txt

VD Target <Event>
VD Algorithm <SimpleEventVulnerability>
Algorithm Parameter File <parameter.json>
Pre Processing <>
Post Processing <>
Output Mode <Default>

parameter.json

{
    "states":["Infected","Recovered"],
    "num_runs":1000,
    "event_identifier":"Id"
}

The event identifier will be defined in an individual event file.

four_event.txt

2
Id:Location Index:Agents
4:1:12,17,9,7,19,11,4,1,13,3,16,2,8,10
5:0:14,2,9,10,4,19,3,18,11,13,15,16,7,5,6,17,0

Parameters

world_obj (episimmer.world.World) – World object of simulation
parameter_dict (Dict[str, Union[List[str], int, str]]) – Dictionary of parameters relevant to the algorithm

init_scores()[source]

Initialises scores and counts for all event with value 0.0 and 0 respectively.

Return type: None

get_events()[source]

Returns list of events in the simulation as event identifiers.

Returns: List of event identifiers
Return type: List[str]

select_event()[source]

Selects a random event and locks down the rest of the events.

Returns: List of EventLockdown objects corresponding to all events other than the selected event
Return type: List[episimmer.policy.lockdown_policy.EventLockdown]

update_event_scores(end_state)[source]

Function to update the event scores.

Parameters: end_state (Dict[str, List[int]]) – Dictionary mapping states to time step wise population
Return type: None

one_run()[source]

Executes a single run of the detection module.

Return type: None

run_detection()[source]

Function to run the complete detection module.

Return type: None

episimmer.vulnerability_detection

Vulnerable Agents API

Agent Vulnerability API

Event Vulnerability API

Vulnerable Agents API 

Agent Vulnerability API 

Event Vulnerability API 