Marginal gain list update (#24)

Author: eliotwrobson

CITATION.cff

@@ -72,9 +72,31 @@ avg = total / n_sim
 ### Advanced Usage
 See the [documentation](https://eliotwrobson.github.io/CyNetDiff/examples/activated/).
 
+## Citation
+
+If you use this code in your research, please use the following citation:
+```bibtex
+@article{DBLP:journals/pvldb/RobsonRU24,
+  author       = {Eilot W. Robson and
+                  Dhemath Reddy and
+                  Abhishek Kumar Umrawal},
+  title        = {CyNetDiff: {A} Python Library for Accelerated Implementation of Network
+                  Diffusion Models},
+  journal      = {Proc. {VLDB} Endow.},
+  volume       = {17},
+  number       = {12},
+  pages        = {4409--4412},
+  year         = {2024},
+  url          = {https://www.vldb.org/pvldb/vol17/p4409-umrawal.pdf},
+  timestamp    = {Thu, 19 Sep 2024 13:09:38 +0200},
+  biburl       = {https://dblp.org/rec/journals/pvldb/RobsonRU24.bib},
+  bibsource    = {dblp computer science bibliography, https://dblp.org}
+}
+```
+
 ## Project Status
 
-This project is still considered in an alpha stage of development. As such,
+This project is still considered in a beta stage of development. As such,
 the API could still change to facilitate easier community adoption.
 
 All feedback is greatly appreciated!

README.md

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cynetdiff"
-version = "0.1.14"
+version = "0.1.15"
 description = "A fast network diffusion library"
 authors = ["Eliot W. Robson <eliot.robson24@gmail.com>"]
 license = "MIT"

pyproject.toml

@@ -1,6 +1,7 @@
 from libcpp.deque cimport deque as cdeque
 from libcpp.unordered_set cimport unordered_set as cset
 from libcpp.unordered_map cimport unordered_map as cmap
+from libcpp.vector cimport vector as cvector
 
 cdef class DiffusionModel:
     cdef readonly float[:] payoffs
@@ -10,8 +11,7 @@ cdef class DiffusionModel:
     cpdef void advance_until_completion(self)
     cdef float _compute_payoff(
         self,
-        cset[unsigned int]& new_seeds,
-        cset[unsigned int]& old_seeds,
+        cdeque[unsigned int]& activated_nodes,
         float[:] payoffs,
     )
 
@@ -32,16 +32,17 @@ cdef class IndependentCascadeModel(DiffusionModel):
     cdef cset[unsigned int] original_seeds
 
     cdef int _activation_succeeds(self, unsigned int edge_idx) except -1 nogil
+
     cdef int _advance_model(
         self,
         cdeque[unsigned int]& work_deque,
         cset[unsigned int]& seen_set
     ) except -1 nogil
 
-    cdef float _compute_marginal_gain(
+    cdef cvector[float] _compute_marginal_gains(
         self,
-        cset[unsigned int]& original_seeds,
-        unsigned int new_seed,
+        cvector[unsigned int]& original_seeds,
+        cvector[unsigned int]& new_seeds,
         unsigned int num_trials
     )
 
@@ -69,10 +70,10 @@ cdef class LinearThresholdModel(DiffusionModel):
         cmap[unsigned int, float]& buckets,
     ) except -1 nogil
 
-    cdef float _compute_marginal_gain(
+    cdef cvector[float] _compute_marginal_gains(
         self,
-        cset[unsigned int]& original_seeds,
-        unsigned int new_seed,
+        cvector[unsigned int]& original_seeds,
+        cvector[unsigned int]& new_seeds,
         unsigned int num_trials,
         float[:] _node_thresholds
     )

src/cynetdiff/models.pxd

@@ -111,27 +111,28 @@ class IndependentCascadeModel(DiffusionModel):
         payoffs: t.Optional[array.array] = None,
         _edge_probabilities: t.Optional[array.array] = None,
     ) -> None: ...
-    def compute_marginal_gain(
-        self, seed_set: t.Iterable[int], new_seed: t.Optional[int], num_trials: int
-    ) -> float:
+    def compute_marginal_gains(
+        self, seed_set: t.Iterable[int], new_seeds: t.List[int], num_trials: int
+    ) -> t.List[float]:
         """
-        Computes the marginal gain of adding new_seed on top of seed_set. Averages over the given number
-        of trials. If new_seed is None, just gives the average influence of the seed set.  Computes
-        marginal gain using payoffs if set.
+        Computes the marginal gain of adding each seed in new_seeds on top of the original seed_set.
+        Averages over num_trials number of randomized activations.
 
         Parameters
         ----------
         seed_set : Iterable[int]
             An iterable representing the current seed set. Can be empty.
-        new_seed : int
-            New seed set to compute marginal gain on.
+        new_seeds : List[int]
+            New seeds to compute marginal gains on. Can be empty.
         num_trials : int
             Number of randomized trials to run.
 
         Returns
         ----------
-        float
-            Average marginal gain in profit over all trials.
+        List[float]
+            List containing computed marginal gains. First entry is average influence of the
+            starting seed set. Following entries are marginal gains with the addition of vertices
+            from new_seeds in order. Has length len(new_seeds)+1.
         """
 
 class LinearThresholdModel(DiffusionModel):
@@ -171,30 +172,31 @@ class LinearThresholdModel(DiffusionModel):
         """
         ...
 
-    def compute_marginal_gain(
+    def compute_marginal_gains(
         self,
         seed_set: t.Iterable[int],
-        new_seed: t.Optional[int],
+        new_seeds: t.List[int],
         num_trials: int,
         *,
         _node_thresholds: t.Optional[array.array] = None,
-    ) -> float:
+    ) -> t.List[float]:
         """
-        Computes the marginal gain of adding new_seed on top of seed_set. Averages over the given number
-        of trials. If new_seed is None, just gives the average influence of the seed set. Computes
-        marginal gain using payoffs if set.
+        Computes the marginal gain of adding each seed in new_seeds on top of the original seed_set.
+        Averages over num_trials number of randomized activations.
 
         Parameters
         ----------
         seed_set : Iterable[int]
             An iterable representing the current seed set. Can be empty.
-        new_seed : int
-            New seed set to compute marginal gain on.
+        new_seeds : List[int]
+            New seeds to compute marginal gains on. Can be empty.
         num_trials : int
             Number of randomized trials to run.
 
         Returns
         ----------
-        float
-            Average marginal gain in profit over all trials.
+        List[float]
+            List containing computed marginal gains. First entry is average influence of the
+            starting seed set. Following entries are marginal gains with the addition of vertices
+            from new_seeds in order. Has length len(new_seeds)+1.
         """