v1.0.0: Added scipy requirement, tested on previous Python versions down to 3.10, added the possibility to customize classes and pass them inside the InfluenceMaximization object

Author: lorenzobloise

.idea/misc.xml

@@ -32,6 +32,7 @@ NetMax was developed with Python 3.12 and requires the installation of the follo
 
 - **networkx** (version 3.3)
 - **numpy**
+- **scipy**
 - **tqdm**
 - **heapdict**
 
@@ -55,9 +56,9 @@ This framework wants to be a useful tool for all those people who study the prob
 - `r`: number of simulations to execute (default is 100)
 - `verbose`: if `True` sets the logging level to `INFO`, otherwise displays only the minimal information
 
-**Important**: `alg`, `diff_model`, `inf_prob` and `endorsement_policy` are `str` parameters, in order to prevent the user from directly importing and instantiating all the specific classes, which could have not been user-friendly.
-If the user, after reading the documentation, wants to customize some specific parameters, he can still change the corresponding attribute after the instantiation of the `InfluenceMaximization` object.
-To view all the keywords for these parameters, see the corresponding section.
+**Important**: `alg`, `diff_model`, `inf_prob` and `endorsement_policy` can be either `str` or class parameters:
+- If they are `str` parameters, they represent the `name` attribute of the corresponding class already present in the framework. This was done in order to prevent the user from directly importing and instantiating all the specific classes, which could have not been user-friendly. To view all the keywords for these parameters, see the corresponding section
+- Otherwise, they must extend the corresponding superclass depending on the parameters (`Algorithm` for `alg`, `DiffusionModel` for `diff_model`, `InfluenceProbability` for `inf_prob`, `EndorsementPolicy` for `endorsement_policy`). This way, the user can define his own custom classes
 
 After creating the `InfluenceMaximization` object, the user may call its `run()` method, which returns:
 

.idea/netmax.iml

@@ -0,0 +1,26 @@
+import copy
+
+class Agent(object):
+
+    def __init__(self, name: str, budget: int, id: int = -1):
+        """
+        This class models an agent.
+        :param name: The name of the agent.
+        :param budget: The budget of the agent.
+        :param id: The id of the agent.
+        """
+        self.name: str = name
+        self.budget: int = budget
+        self.seed: [int] = []
+        self.spread = 0
+        self.id: int = id
+
+    def __deepcopy__(self, memodict={}):
+        """
+        Makes a deep copy of the agent object.
+        """
+        new_agent = Agent(self.name, self.budget)
+        new_agent.seed = copy.deepcopy(self.seed)
+        new_agent.spread = self.spread
+        new_agent.id = self.id
+        return new_agent

README.md

@@ -0,0 +1,10 @@
+from .proxy_based.degdis import DegDis
+from .proxy_based.highest_out_degree import HighestOutDegree
+from .proxy_based.group_pr import Group_PR
+from .simulation_based.mcgreedy import MCGreedy
+from .simulation_based.celf import CELF
+from .simulation_based.celfpp import CELF_PP
+from .sketch_based.static_greedy import StaticGreedy
+from .sketch_based.ris import RIS
+from .sketch_based.tim import TIM
+from .sketch_based.timp import TIMp

__pycache__/utils.cpython-310.pyc

@@ -0,0 +1,42 @@
+import networkx as nx
+from netmax.agent import Agent
+
+class Algorithm:
+
+    def __init__(self, graph: nx.DiGraph, agents: list[Agent], curr_agent_id: int, budget, diff_model, r):
+        """
+        :param graph: networkx DiGraph
+        :param agents: list of Agent
+        :param curr_agent_id: int - index of the current agent
+        :param budget: int - budget of the current agent
+        :param diff_model: str - diffusion model
+        :param r: float - discount factor
+        """
+        self.graph = graph
+        self.agents = agents
+        self.curr_agent_id = curr_agent_id
+        self.budget = budget
+        self.diff_model = diff_model
+        self.r = r
+
+    def set_curr_agent(self, curr_agent_id):
+        """
+        Sets the current agent as the one passed.
+        :param curr_agent_id: index of the current agent.
+        """
+        self.curr_agent_id = curr_agent_id
+
+    def __in_some_seed_set__(self, v, agents):
+        """
+        Checks if a node is in some seed set.
+        :param v: the node to check.
+        :param agents: the 'agents' dictionary, which contain all the seed sets.
+        :return: True if the node is in some seed set, False otherwise.
+        """
+        for a in agents:
+            if v in a.seed:
+                return True
+        return False
+
+    def run(self):
+        raise NotImplementedError("This method must be implemented by subclasses")

__pycache__/utils.cpython-39.pyc

@@ -0,0 +1,92 @@
+import copy
+from netmax.algorithms.proxy_based.proxy_based import ProxyBasedAlgorithm
+from heapdict import heapdict
+
+class DegDis(ProxyBasedAlgorithm):
+    """
+    Paper: Chen et al. - "Efficient Influence Maximization in Social Networks".
+    The Degree Discount heuristic is an improvement over the Highest Out-Degree algorithm. It takes into account the
+    influence of already selected nodes and adjusts the degree of remaining nodes accordingly.
+    """
+
+    name = 'degdis'
+
+    def __init__(self, graph, agents, curr_agent_id, budget, diff_model, r):
+        super().__init__(graph, agents, curr_agent_id, budget, diff_model, r)
+        self.d = None
+        self.t = None
+        self.p = None
+        self.dd = None
+
+    def __initialize_degree_discount__(self):
+        """
+        Initializes all the data structures needed for the algorithm. Most of them are agent-dependant, so every agent
+        has its own version of the data structure.
+        """
+        # Influence probabilities for every agent, dictionary of dictionaries <agent: <vertex: influence_probability>>,
+        # where we compute this probability as the highest edge label among the in-edges of the vertex, instead
+        # the author of the paper sets it as a fixed value (for example 0.01)
+        self.p = {a.id: {} for a in self.agents}
+        self.t = {a.id: {} for a in self.agents} # Number of adjacent vertices that are in the seed set,
+                                                # dictionary of dictionaries <agent: <vertex: adjacent_vertices_in_ss>>
+        self.dd = {a.id: heapdict() for a in self.agents} # Degree discount heuristic, dictionary <agent: heapdict>
+        self.d = {}  # Degree of each vertex, dictionary <vertex: degree>
+        # Build the node degrees
+        for u in self.graph.nodes():
+            self.d[u] = self.graph.out_degree(u)
+            # Initialize the heuristic value as the current degree (negative because of the min-heap),
+            # and the number of adjacent vertices that are in the seed set (at this moment 0 of course)
+            for a in self.agents:
+                self.dd[a.id][u] = -self.d[u]
+                self.t[a.id][u] = 0
+
+    def __delete_from_dd__(self, v):
+        """
+        Removes the node v from the degree discount dictionary.
+        :param v: The node to remove.
+        """
+        for a in self.agents:
+            del self.dd[a.id][v]
+
+    def __compute_node_score__(self, v):
+        """
+        :return: the score of the degree discount heuristic for the node v, as shown in the paper. Only difference is
+        that the paper works with fixed-value influence probabilities, while we extend this considering different
+        probability values by taking the highest edge label among the in-edges of the vertex.
+        """
+        return self.d[v] - 2 * self.t[self.curr_agent_id][v] - (self.d[v] - self.t[self.curr_agent_id][v]) * self.t[self.curr_agent_id][v] * self.p[self.curr_agent_id][v]
+
+    def run(self):
+        """
+        :return: The nodes to add in the seed set of the current agent and the spreads for each agent.
+        """
+        # This method is necessary since when the input network is signed, the graph of the proxy-based algorithm
+        # contains only the trust-edges (see super-class ProxyBasedAlgorithm)
+        self.__update_active_nodes__()
+        # Initialize degrees and degree discounts if it's the first turn of the first round
+        if self.dd is None:
+            self.__initialize_degree_discount__()
+        # Add vertices to the seed set of the current agent
+        agents_copy = copy.deepcopy(self.agents)
+        # Repeats until the budget is fulfilled (in the InfluenceMaximization class, inside the run method, the algorithm
+        # is always invoked with the budget parameter set to 1, but we preferred to write the code in a more general way)
+        for _ in range(self.budget):
+            # Select the node with the maximum value of the degree discount heuristic
+            u, _ = self.dd[self.curr_agent_id].peekitem()
+            agents_copy[self.curr_agent_id].seed.append(u) # Add it into the seed set of the current agent
+            self.__delete_from_dd__(u) # Delete u from the degree discount of all agents
+            for v in self.graph[u]: # Neighbors of node u
+                if not self.__in_some_seed_set__(v, agents_copy): # If the node is not part of any seed set
+                    # Compute influence probability of node v as the maximum edge label
+                    # among his in-edges (different from the paper)
+                    if v not in self.p[self.curr_agent_id]: # If v hasn't been reached yet
+                        self.p[self.curr_agent_id][v] = self.graph.edges[u, v]['p']
+                    elif self.p[self.curr_agent_id][v] < self.graph.edges[u, v]['p']:
+                        self.p[self.curr_agent_id][v] = self.graph.edges[u, v]['p']
+                    self.t[self.curr_agent_id][v] += 1 # Increase the number of selected neighbors
+                    score = self.__compute_node_score__(v) # Compute the degree-discount heuristic of node v
+                    self.dd[self.curr_agent_id][v] = -score
+        # Return the new nodes to add to the seed set and the spread (which is 0 because we didn't do any simulation,
+        # in fact this is only a fictional value, since the real spread will be computed at the end of the game)
+        result_seed_set = agents_copy[self.curr_agent_id].seed[:-self.budget] if self.budget > 1 else [agents_copy[self.curr_agent_id].seed[-1]]
+        return result_seed_set, {a.name: 0 for a in self.agents}

build/lib/netmax/__init__.py

@@ -0,0 +1,105 @@
+import copy
+import networkx as nx
+from heapdict import heapdict
+from netmax.algorithms.proxy_based.proxy_based import ProxyBasedAlgorithm
+
+class Group_PR(ProxyBasedAlgorithm):
+    """
+    Paper: Liu et al. - "Influence Maximization over Large-Scale Social Networks A Bounded Linear Approach".
+    Group-PageRank starts from the fact that PageRank as un upper bound to the influence of single nodes under
+    linear influence processes (and it's called influence-PageRank), and extends this concept to compute the
+    influence of groups of nodes via the so-called Group-PageRank. Then it plugs this heuristic into a linear
+    framework to maximize the influence spread.
+    """
+
+    name = 'group_pr'
+
+    def __init__(self, graph, agents, curr_agent_id, budget, diff_model, r):
+        super().__init__(graph, agents, curr_agent_id, budget, diff_model, r)
+        self.d = 0.85 # Parameter of PageRank
+        # PageRank works with incoming links, but the influence propagation has only sense considering outgoing links,
+        # so we use the inverted graph to compute PageRank
+        self.inverted_graph = self.graph.reverse(copy=True)
+        self.influencee = list(self.graph.nodes) # Nodes that can be influenced for each agent
+        self.delta_dict = None # Dictionary of heaps which store the value of delta for each node and for each agent
+
+    def __initialize_delta_dict__(self):
+        """
+        Initialize the dictionary of heaps with the same heap for each agent as in the beginning the delta value
+        is the same.
+        """
+        # Compute influence-PageRank with a bias towards the nodes that can be influenced
+        personalization = {u: 1 / len(self.influencee) for u in self.influencee}
+        fPR = nx.pagerank(self.inverted_graph, alpha=self.d, personalization=personalization, weight='p')
+        curr_delta_dict = heapdict()
+        for s in self.graph.nodes():
+            # Formula in the paper, negative because we have to insert in the heap which orders in descending order
+            curr_delta_dict[s] = - ((len(self.influencee) / (1 - self.d)) * fPR[s])
+        self.delta_dict = {a.id: copy.deepcopy(curr_delta_dict) for a in self.agents}
+
+    def __remove_node_from_heaps__(self, v):
+        """
+        Removes a node from all heaps.
+        :param v: the node to remove.
+        """
+        for a in self.agents:
+            del self.delta_dict[a.id][v]
+
+    def __get_delta_bound__(self, seed_set, s):
+        """
+        Method used to update the entries of the delta dictionary. In the paper there are two ways to do so: a linear
+        approach or a bound approach. We chose to implement the bound approach with this method.
+        :param seed_set: the seed set.
+        :param s: the node which delta value has to be computed.
+        :return: the value of delta for the node s.
+        """
+        # If no node can be influenced, compute the influence-PageRank with the default personalization vector
+        if len(self.influencee) == 0:
+            fPR = nx.pagerank(self.inverted_graph, alpha=self.d, weight='p')
+        # Otherwise compute the influence-PageRank with a bias towards the nodes that can be influenced
+        else:
+            personalization = {u: 1 / len(self.influencee) for u in self.influencee}
+            fPR = nx.pagerank(self.inverted_graph, alpha=self.d, personalization=personalization, weight='p')
+        # Initialize the value of delta with the influence-PageRank of the node
+        delta_s = fPR[s]
+        # For each node j in the seed set, subtract two contributions from the current value of delta:
+        # 1) The influence-PageRank of node s multiplied by the weight of the edge (j,s), if exists
+        # 2) The influence-PageRank of node j multiplied by the weight of the edge (s,j), if exists
+        for j in seed_set:
+            p_js = self.graph.edges[j, s]['p'] if self.graph.has_edge(j, s) else 0
+            p_sj = self.graph.edges[s, j]['p'] if self.graph.has_edge(s, j) else 0
+            delta_s = delta_s - self.d * p_js * fPR[s] - self.d * p_sj * fPR[j]
+        # Formula inside the paper
+        return delta_s * (len(self.influencee) / (1 - self.d))
+
+    def run(self):
+        """
+        :return: The nodes to add in the seed set of the current agent and the spreads for each agent.
+        """
+        # This method is necessary since when the input network is signed, the graph of the proxy-based algorithm
+        # contains only the trust-edges (see super-class ProxyBasedAlgorithm)
+        self.__update_active_nodes__()
+        # Initialize the delta dictionary if it's the first turn of the first round
+        if self.delta_dict is None:
+            self.__initialize_delta_dict__()
+        agents_copy = copy.deepcopy(self.agents)
+        # Repeats until the budget is fulfilled (in the InfluenceMaximization class, inside the run method, the algorithm
+        # is always invoked with the budget parameter set to 1, but we preferred to write the code in a more general way)
+        added_nodes = 0
+        while added_nodes < self.budget:
+            # Take the node which has the maximum value of delta. The heap property guarantees that
+            # the first item is the one with the highest value of delta
+            s, neg_delta = self.delta_dict[self.curr_agent_id].popitem()
+            # Update this node's delta value with bound method and reinsert the node into the heap
+            self.delta_dict[self.curr_agent_id][s] = -self.__get_delta_bound__(agents_copy[self.curr_agent_id].seed, s)
+            # If it's still the node with the highest value of delta
+            if s == self.delta_dict[self.curr_agent_id].peekitem()[0]:
+                s_max, _ = self.delta_dict[self.curr_agent_id].peekitem()
+                agents_copy[self.curr_agent_id].seed.append(s_max) # Add it into the seed set of the current agent
+                self.__remove_node_from_heaps__(s_max) # And remove it from all the heaps
+                self.influencee.remove(s_max) # Remove it also from the set of nodes that can be influenced
+                added_nodes += 1
+        # Return the new nodes to add to the seed set and the spread (which is 0 because we didn't do any simulation,
+        # in fact this is only a fictional value, since the real spread will be computed at the end of the game)
+        result_seed_set = agents_copy[self.curr_agent_id].seed[:-self.budget] if self.budget > 1 else [agents_copy[self.curr_agent_id].seed[-1]]
+        return result_seed_set, {a.name: 0 for a in self.agents}

build/lib/netmax/agent.py

@@ -0,0 +1,37 @@
+from networkx import DiGraph
+from netmax.algorithms.proxy_based.proxy_based import ProxyBasedAlgorithm
+from netmax import influence_maximization as im
+
+
+class HighestOutDegree(ProxyBasedAlgorithm):
+    """
+    The Highest Out-Degree algorithm selects nodes based on their out-degree,
+    which is the number of edges directed outwards from a node.
+    The idea is that nodes with higher out-degree have more influence over other nodes in the network.
+    """
+
+    name = 'outdeg'
+
+    def __init__(self, graph: DiGraph, agents, curr_agent_id, budget, diff_model, r):
+        super().__init__(graph, agents, curr_agent_id, budget, diff_model, r)
+        self.out_deg_ranking = None
+
+    def run(self):
+        """
+        :return: The nodes to add in the seed set of the current agent and the spreads for each agent.
+        """
+        # This method is necessary since when the input network is signed, the graph of the proxy-based algorithm
+        # contains only the trust-edges (see super-class ProxyBasedAlgorithm)
+        self.__update_active_nodes__()
+        # Compute the out-degrees if not already done
+        if self.out_deg_ranking is None:
+            self.out_deg_ranking = sorted(im.inactive_nodes(self.graph), key=lambda node: self.graph.out_degree(node))
+        # Iteratively, take the nodes with the highest out-degree.
+        # Repeats until the budget is fulfilled (in the InfluenceMaximization class, inside the run method, the algorithm
+        # is always invoked with the budget parameter set to 1, but we preferred to write the code in a more general way)
+        seed_set = []
+        for _ in range(self.budget):
+            seed_set.append(self.out_deg_ranking.pop())
+        # Return the new nodes to add to the seed set and the spread (which is 0 because we didn't do any simulation,
+        # in fact this is only a fictional value, since the real spread will be computed at the end of the game)
+        return seed_set, {a.name: 0 for a in self.agents}