Simulation Framework

The simulation module provides tools for simulating attacks and analyzing their effects on hypernetworks.

hiper.simulation.simulator

simulator.py

Defines the HypernetworkSimulator class for orchestrating attack simulations.

class hiper.simulation.simulator.HypernetworkSimulator(simulator_id)

Bases: object

Orchestrates and manages hypernetwork attack simulations.

The simulator provides high-level functionality for running attack simulations, analyzing results, and managing multiple scenarios. It can work with both individual attacks and attack sequences.

__init__(simulator_id)

Initialize the hypernetwork simulator.

Parameters:

simulator_id (str) – Unique identifier for this simulator instance.

set_hypernetwork(hypernetwork, create_backup=True)

Set the target hypernetwork for simulations.

Parameters:

• hypernetwork (Hypernetwork) – The hypernetwork to use for simulations.

• create_backup (bool) – If True, creates a backup of the original state.

Return type:

None

simulate_attack(attack, restore_after=True)

Simulate a single attack on the current hypernetwork.

Parameters:

• attack (Attack) – The attack to simulate.

• restore_after (bool) – If True, restore the hypernetwork to its original

• attack. (state after the)

Return type:

Dict[str, Any]

Returns:

Dictionary containing simulation results.

Raises:

RuntimeError – If no hypernetwork has been set.

simulate_sequence(sequence, restore_after=True, stop_on_failure=False)

Simulate an attack sequence on the current hypernetwork.

Parameters:

• sequence (AttackSequence) – The attack sequence to simulate.

• restore_after (bool) – If True, restore the hypernetwork to its original

• sequence. (state after the)

• stop_on_failure (bool) – If True, stop execution when an attack fails.

Return type:

Dict[str, Any]

Returns:

Dictionary containing simulation results.

Raises:

RuntimeError – If no hypernetwork has been set.

get_simulation_history()

Get the complete simulation history.

Return type:

List[Dict[str, Any]]

Returns:

List of all simulation results.

get_baseline_stats()

Get the baseline statistics of the original hypernetwork.

Return type:

Optional[Dict[str, Any]]

Returns:

Baseline statistics dictionary, or None if not available.

clear_history()

Clear the simulation history.

Return type:

None

generate_summary_report()

Generate a comprehensive summary report of all simulations.

Return type:

Dict[str, Any]

Returns:

Dictionary containing summary statistics and analysis.

hiper.simulation.attack

attack.py

Defines the base Attack class and specific attack implementations.

class hiper.simulation.attack.Attack(attack_id)

Bases: ABC

Abstract base class for hypernetwork attacks.

An attack represents a single operation that can be applied to a hypernetwork, such as adding or removing nodes or hyperedges.

__init__(attack_id)

Initialize the attack with a unique identifier.

Parameters:

attack_id (str) – Unique identifier for this attack.

abstractmethod execute(hypernetwork)

Execute the attack on the given hypernetwork.

Parameters:

hypernetwork (Hypernetwork) – The target hypernetwork.

Return type:

bool

Returns:

True if the attack was successful, False otherwise.

abstractmethod describe()

Return a human-readable description of the attack.

Return type:

str

Returns:

String description of the attack.

is_executed()

Check if the attack has been executed.

Return type:

bool

get_result()

Get the result of the attack execution.

Return type:

Dict[str, Any]

reset()

Reset the attack state to allow re-execution.

Return type:

None

class hiper.simulation.attack.AddNodeAttack(attack_id, node_id)

Bases: Attack

Attack that adds a single node to the hypernetwork.

__init__(attack_id, node_id)

Initialize the add node attack.

Parameters:

• attack_id (str) – Unique identifier for this attack.

• node_id (int) – ID of the node to add.

execute(hypernetwork)

Execute the node addition attack.

Parameters:

hypernetwork (Hypernetwork) – The target hypernetwork.

Return type:

bool

Returns:

True if the node was added successfully.

describe()

Return description of the add node attack.

Return type:

str

class hiper.simulation.attack.RemoveNodeAttack(attack_id, node_id)

Bases: Attack

Attack that removes a single node from the hypernetwork.

__init__(attack_id, node_id)

Initialize the remove node attack.

Parameters:

• attack_id (str) – Unique identifier for this attack.

• node_id (int) – ID of the node to remove.

execute(hypernetwork)

Execute the node removal attack.

Parameters:

hypernetwork (Hypernetwork) – The target hypernetwork.

Return type:

bool

Returns:

True if the node was removed successfully.

describe()

Return description of the remove node attack.

Return type:

str

class hiper.simulation.attack.AddHyperedgeAttack(attack_id, edge_id, members)

Bases: Attack

Attack that adds a single hyperedge to the hypernetwork.

__init__(attack_id, edge_id, members)

Initialize the add hyperedge attack.

Parameters:

• attack_id (str) – Unique identifier for this attack.

• edge_id (int) – ID of the hyperedge to add.

• members (list[int]) – List of node IDs that form the hyperedge.

execute(hypernetwork)

Execute the hyperedge addition attack.

Parameters:

hypernetwork (Hypernetwork) – The target hypernetwork.

Return type:

bool

Returns:

True if the hyperedge was added successfully.

describe()

Return description of the add hyperedge attack.

Return type:

str

class hiper.simulation.attack.RemoveHyperedgeAttack(attack_id, edge_id)

Bases: Attack

Attack that removes a single hyperedge from the hypernetwork.

__init__(attack_id, edge_id)

Initialize the remove hyperedge attack.

Parameters:

• attack_id (str) – Unique identifier for this attack.

• edge_id (int) – ID of the hyperedge to remove.

execute(hypernetwork)

Execute the hyperedge removal attack.

Parameters:

hypernetwork (Hypernetwork) – The target hypernetwork.

Return type:

bool

Returns:

True if the hyperedge was removed successfully.

describe()

Return description of the remove hyperedge attack.

Return type:

str

hiper.simulation.sequence

sequence.py

Defines the AttackSequence class for managing multiple attacks.

class hiper.simulation.sequence.AttackSequence(sequence_id)

Bases: object

Manages and executes a sequence of attacks on a hypernetwork.

An attack sequence represents a series of operations that can be applied to a hypernetwork in order. It provides functionality to execute all attacks track results, and handle failures.

__init__(sequence_id)

Initialize the attack sequence.

Parameters:

sequence_id (str) – Unique identifier for this sequence.

add_attack(attack)

Add an attack to the sequence.

Parameters:

attack (Attack) – The attack to add to the sequence.

Return type:

None

add_attacks(attacks)

Add multiple attacks to the sequence.

Parameters:

attacks (List[Attack]) – List of attacks to add to the sequence.

Return type:

None

execute(hypernetwork, stop_on_failure=False)

Execute all attacks in the sequence on the given hypernetwork.

Parameters:

• hypernetwork (Hypernetwork) – The target hypernetwork.

• stop_on_failure (bool) – If True, stop execution when an attack fails.

Return type:

bool

Returns:

True if all attacks were successful, False otherwise.

get_results()

Get detailed results of all executed attacks.

Return type:

List[Dict[str, Any]]

Returns:

List of dictionaries containing attack results.

get_execution_stats()

Get overall execution statistics.

Return type:

Dict[str, Any]

Returns:

Dictionary containing execution statistics.

is_executed()

Check if the sequence has been executed.

Return type:

bool

reset()

Reset the sequence state to allow re-execution.

This resets both the sequence and all individual attacks.

Return type:

None

clear()

Clear all attacks from the sequence and reset state.

Return type:

None

size()

Get the number of attacks in the sequence.

Return type:

int

describe()

Return a human-readable description of the sequence.

Return type:

str

Returns:

String description of the attack sequence.

get_attack(index)

Get an attack by its index in the sequence.

Parameters:

index (int) – Index of the attack to retrieve.

Return type:

Optional[Attack]

Returns:

The attack at the given index, or None if index is invalid.

remove_attack(index)

Remove and return an attack by its index.

Parameters:

index (int) – Index of the attack to remove.

Return type:

Optional[Attack]

Returns:

The removed attack, or None if index is invalid.

insert_attack(index, attack)

Insert an attack at a specific position in the sequence.

Parameters:

• index (int) – Position where to insert the attack.

• attack (Attack) – The attack to insert.

Return type:

bool

Returns:

True if the attack was inserted successfully.