Network: clarified issue of transpose and incoming/outgoing represent…

…ation

include/network.hpp

@@ -7,6 +7,21 @@
 namespace Seldon
 {
 
+/*
+    A class that represents a directed graph using adjacency lists.
+    Either incoming or outgoing edges are stored.
+    To switch between the different representations (in/out)
+    and the network and its transpose (N/N^T), refer to the following table:
+
+              | N (inc)   |  N (out)  |  N^T (inc) | N^T (out) |
+    ------------------------------------------------------------
+    N (inc)   |     X     |  toggle   |  transpose |   switch  |
+    N (out)   |  toggle   |     X     |  switch    | transpose |
+    N^T (inc) | transpose |   switch  |      X     |  toggle   |
+    N^T (out) |   switch  | transpose |   toggle   |     X     |
+
+    Note: switch is equivalent to toggle + transpose, but much cheaper!
+*/
 class Network
 {
 public:
@@ -78,16 +93,23 @@ class Network
     void push_back_neighbour_and_weight( size_t agent_idx_i, size_t agent_idx_j, WeightT w );
 
     /*
-    Switches the directionality and *changes the topolgy*.
-    *Note*: This is cheap and changes the effective network topology by simply changing the directionality flag.
+    Transposes the network, without switching the direction flag (expensive).
+    Example: N(inc) -> N(inc)^T
     */
     void transpose();
 
     /*
-    Switches the directionality *without changing the topolgy*. *Note*: This is expensive and toggles the
-    directionality, while compensating by changing the adjacency list.
+    Switches the direction flag *without* transposing the network (expensive)
+    Example: N(inc) -> N(out)
     */
-    void toggle_direction();
+    void toggle_incoming_outgoing();
+
+    /*
+    Only switches the direction flag. This effectively transposes the network and, simultaneously, changes its
+    representation.
+    Example: N(inc) -> N^T(out)
+    */
+    void switch_direction_flag();
 
 private:
     std::vector<std::vector<size_t>> neighbour_list; // Neighbour list for the connections

src/models/ActivityDrivenModel.cpp

@@ -62,7 +62,8 @@ void Seldon::ActivityAgentModel::update_network_probabilistic()
         {
             // Implement the weight for the probability of agent `idx_agent` contacting agent `j`
             // Not normalised since this is taken care of by the reservoir sampling
-            auto weight_callback = [idx_agent, this]( size_t j ) {
+            auto weight_callback = [idx_agent, this]( size_t j )
+            {
                 if( idx_agent == j ) // The agent does not contact itself
                     return 0.0;
                 return std::pow(
@@ -113,7 +114,7 @@ void Seldon::ActivityAgentModel::update_network_probabilistic()
         }
     }
 
-    network.toggle_direction(); // switch direction, so that we have incoming edges
+    network.toggle_incoming_outgoing(); // switch direction, so that we have incoming edges
 }
 
 void Seldon::ActivityAgentModel::update_network_mean()
@@ -128,7 +129,8 @@ void Seldon::ActivityAgentModel::update_network_mean()
         contact_prob_list[idx_agent] = weights; // set to zero
     }
 
-    auto probability_helper = []( double omega, size_t m ) {
+    auto probability_helper = []( double omega, size_t m )
+    {
         double p = 0;
         for( size_t i = 1; i <= m; i++ )
             p += ( std::pow( -omega, i + 1 ) + omega ) / ( omega + 1 );
@@ -139,7 +141,8 @@ void Seldon::ActivityAgentModel::update_network_mean()
     {
         // Implement the weight for the probability of agent `idx_agent` contacting agent `j`
         // Not normalised since this is taken care of by the reservoir sampling
-        auto weight_callback = [idx_agent, this]( size_t j ) {
+        auto weight_callback = [idx_agent, this]( size_t j )
+        {
             constexpr double tolerance = 1e-16;
             auto opinion_diff = std::abs( this->agents[idx_agent].data.opinion - this->agents[j].data.opinion );
             if( opinion_diff < tolerance )

src/network.cpp

@@ -101,20 +101,7 @@ void Seldon::Network::set_weights( std::size_t agent_idx, std::span<const Seldon
     weight_list[agent_idx].assign( weights.begin(), weights.end() );
 }
 
-void Seldon::Network::toggle_direction()
-{
-    // Swap the edge direction
-    if( direction() == EdgeDirection::Incoming )
-    {
-        _direction = EdgeDirection::Outgoing;
-    }
-    else
-    {
-        _direction = EdgeDirection::Incoming;
-    }
-}
-
-void Seldon::Network::transpose()
+void Seldon::Network::toggle_incoming_outgoing()
 {
     std::vector<std::vector<size_t>> neighbour_list_transpose( n_agents(), std::vector<size_t>( 0 ) );
     std::vector<std::vector<WeightT>> weight_list_transpose( n_agents(), std::vector<WeightT>( 0 ) );
@@ -130,7 +117,28 @@ void Seldon::Network::transpose()
         }
     }
 
-    toggle_direction();
     neighbour_list = std::move( neighbour_list_transpose );
     weight_list    = std::move( weight_list_transpose );
+
+    // Swap the edge direction
+    switch_direction_flag();
+}
+
+void Seldon::Network::transpose()
+{
+    toggle_incoming_outgoing();
+    switch_direction_flag();
+}
+
+void Seldon::Network::switch_direction_flag()
+{
+    // Swap the edge direction
+    if( direction() == EdgeDirection::Incoming )
+    {
+        _direction = EdgeDirection::Outgoing;
+    }
+    else
+    {
+        _direction = EdgeDirection::Incoming;
+    }
 }