Rename network movement types (#181)

* Rename travel to walk.
* Rename snap to jump.
* Rename step to teleport.
* Rename network_type to network_movement.

Author: wenzeslaus

include/pops/anthropogenic_kernel.hpp

@@ -59,11 +59,11 @@ std::unique_ptr<KernelInterface<Generator>> create_anthro_kernel(
     else if (anthro_kernel == DispersalKernelType::Network) {
         using Kernel =
             DynamicWrapperKernel<NetworkDispersalKernel<RasterIndex>, Generator>;
-        if (config.network_type == "step")
+        if (config.network_movement == "teleport")
             return std::unique_ptr<Kernel>(new Kernel(network));
-        bool snap = config.network_type == "snap" ? true : false;
+        bool jump = config.network_movement == "jump" ? true : false;
         return std::unique_ptr<Kernel>(new Kernel(
-            network, config.network_min_distance, config.network_max_distance, snap));
+            network, config.network_min_distance, config.network_max_distance, jump));
     }
     else if (config.deterministic) {
         using Kernel = DynamicWrapperKernel<

include/pops/config.hpp

@@ -71,7 +71,7 @@ class Config
     std::string anthro_kernel_type;
     double anthro_scale{0};
     std::string anthro_direction;
-    std::string network_type;  ///< travel, snap, step
+    std::string network_movement;  ///< walk, jump, teleport
     double network_min_distance{0};
     double network_max_distance{0};
     double anthro_kappa{0};

include/pops/network.hpp

@@ -157,16 +157,16 @@ class EdgeGeometryView : public ContainerView<EdgeGeomertyType>
  * The network consists of nodes connected by edges. Edges are spatially represented
  * as segments. Edges themselves don't carry cost and have meaning only as indicators of
  * existence of a connection between nodes. Cost for each edge is a travel distance
- * determined by advancing through cells in a segment.
+ * (cost) determined by advancing through all cells in a segment.
  *
  * Nodes are the hop-on locations for dispersers. The dispersers can hop-off anywhere.
  *
  * The general workflow is contructing the object (with the constructor) and loading the
  * data (with the load() function). Then the network is ready to be used for simulating
- * trips over the network (with the travel() function).
+ * trips over the network (with the walk() or teleport() functions).
  *
- * When the travel() function is used from a kernel, user of the network directly calls
- * only the setup functions.
+ * When the walk() or teleport() functions are used from a kernel, user of the network
+ * directly calls only the setup functions.
  *
  * The class exposes number of functions as public which are meant for testing or other
  * special workflows.
@@ -449,7 +449,7 @@ class Network
     }
 
     /**
-     * Travel given distance in the network from given row and column.
+     * Walk a given distance (cost) in the network from given row and column.
      *
      * All previously visited nodes are tracked and, if possible, excluded
      * from further traveling.
@@ -458,20 +458,20 @@ class Network
      * the decision to call this function was based on the caller knowing there is a
      * node. If there is no node, an std::invalid_argument exception is thrown.
      * If there is more than one node at the given *row* and *column*, a random node is
-     * picked and used for traveling.
+     * picked and used as a next walking destination.
      *
-     * If *snap* is true, then results are snapped to the closest node, otherwise
+     * If *jump* is true, then results are snapped to the closest node, otherwise
      * result can be anywhere in between the nodes based on the edge geomerty (segment).
      *
      * @returns Final row and column pair
      */
     template<typename Generator>
-    std::tuple<int, int> travel(
+    std::tuple<int, int> walk(
         RasterIndex row,
         RasterIndex col,
         double distance,
         Generator& generator,
-        bool snap = false) const
+        bool jump = false) const
     {
         auto node_id = get_random_node_at(row, col, generator);
         std::set<NodeId> visited_nodes;
@@ -494,26 +494,27 @@ class Network
                 distance -= segment.cost();
                 continue;
             }
-            if (snap) {
+            if (jump) {
                 if (distance < segment.cost() / 2) {
                     // Less than half snaps to the start node.
                     return segment.front();
                 }
                 // Half or more snaps to the end node.
                 return segment.back();
             }
-            // No snapping, advance in a segment.
+            // No jumping (snapping), advance in a segment.
             // This includes the special cases when distance is 0 or total segment cost.
             return segment.cell_by_cost(distance);
         }
         throw std::invalid_argument("Distance must be greater than or equal to zero");
     }
 
     /**
-     * Step to a different node in the network from given row and column.
+     * Teleport to a different node in the network from given row and column.
      *
      * Returns any node of the nodes connected to the start node possibly based on the
-     * edge probability if probability was assigned to the edges.
+     * edge probability if probability was assigned to the edges without considering
+     * cost to travel from one node to the next one.
      *
      * If *num_steps* is greater than 1, multiple steps are perfomed and the last node
      * is returned. In each node, the probability of picking a specific connection is
@@ -526,12 +527,12 @@ class Network
      * was either checked beforehand or otherwise ensured. If there is no node, an
      * std::invalid_argument exception is thrown.
      * If there is more than one node at the given *row* and *column*, a random node is
-     * picked and used for traveling.
+     * picked and used.
      *
      * @returns Destination row and column pair
      */
     template<typename Generator>
-    std::tuple<int, int> step(
+    std::tuple<int, int> teleport(
         RasterIndex row, RasterIndex col, Generator& generator, int num_steps = 1) const
     {
         auto node_id = get_random_node_at(row, col, generator);
@@ -1092,7 +1093,7 @@ class Network
     double ns_res_;  ///< North-south resolution of the grid
     RasterIndex max_row_;  ///< Maximum row index in the grid
     RasterIndex max_col_;  ///< Maximum column index in the grid
-    double distance_per_cell_;  ///< Distance to travel through one cell (cost)
+    double distance_per_cell_;  ///< Distance (cost) to walk through one cell
     /** Node IDs stored by row and column (multiple nodes per cell) */
     std::map<std::pair<RasterIndex, RasterIndex>, std::set<NodeId>> nodes_by_row_col_;
     NodeMatrix node_matrix_;  ///< List of node neighbors by node ID (edges)

include/pops/network_kernel.hpp

@@ -33,39 +33,39 @@ class NetworkDispersalKernel
 {
 public:
     /**
-     * @brief Create kernel which travels through the network including edges.
+     * @brief Create kernel which travels through a network.
      *
      * The kernel assumes that the *network* is already initialized. It does not modify
      * the network.
      *
      * The *min_distance* and *max_distance* parameters are used as a range for uniform
-     * real distribution which determines the travel distance through the network for
-     * one trip.
+     * real distribution which determines the travel distance (cost) through the network
+     * for one trip if the network movement is walking (and not teleporting).
      *
      * @param network Existing network
-     * @param min_distance Minimum travel distance
-     * @param max_distance Maximum travel distance
-     * @param snap Snap result to the closest node
+     * @param min_distance Minimum travel distance (cost)
+     * @param max_distance Maximum travel distance (cost)
+     * @param jump End always on a node (snaps result to the closest node)
      */
     NetworkDispersalKernel(
         const Network<RasterIndex>& network,
         double min_distance,
         double max_distance,
-        bool snap = false)
+        bool jump = false)
         : network_(network),
           distance_distribution_(min_distance, max_distance),
-          snap_(snap)
+          jump_(jump)
     {}
     /**
-     * @brief Create kernel which steps from one node to another.
+     * @brief Create kernel which teleports from one node to another.
      *
      * The kernel assumes that the *network* is already initialized. It does not modify
      * the network.
      *
      * @param network Existing network
      */
     NetworkDispersalKernel(const Network<RasterIndex>& network)
-        : network_(network), step_{true}
+        : network_(network), teleport_{true}
     {}
 
     /*! \copybrief RadialDispersalKernel::operator()()
@@ -76,11 +76,11 @@ class NetworkDispersalKernel
     template<typename Generator>
     std::tuple<int, int> operator()(Generator& generator, int row, int col)
     {
-        if (step_) {
-            return network_.step(row, col, generator);
+        if (teleport_) {
+            return network_.teleport(row, col, generator);
         }
         double distance = distance_distribution_(generator);
-        std::tie(row, col) = network_.travel(row, col, distance, generator);
+        std::tie(row, col) = network_.walk(row, col, distance, generator);
 
         return std::make_tuple(row, col);
     }
@@ -107,12 +107,12 @@ class NetworkDispersalKernel
 protected:
     /** Reference to the network */
     const Network<RasterIndex>& network_;
-    /** Travel distance distribution */
+    /** Travel distance (cost) distribution */
     std::uniform_real_distribution<double> distance_distribution_;
     /** Step through network instead of traveling between nodes */
-    bool step_{false};
+    bool teleport_{false};
     /** Snap to nodes when traveling between nodes */
-    bool snap_{false};
+    bool jump_{false};
 };
 
 }  // namespace pops

tests/test_network.cpp

@@ -99,7 +99,7 @@ int test_bbox_functions()
     return ret;
 }
 
-int test_travel_network()
+int test_walk_network()
 {
     int ret = 0;
     BBox<double> bbox;
@@ -152,7 +152,7 @@ int test_travel_network()
         int end_row;
         int end_col;
         std::tie(end_row, end_col) =
-            network.travel(start_row, start_col, distance, generator);
+            network.walk(start_row, start_col, distance, generator);
         if (correct->first != end_row || correct->second != end_col) {
             std::cerr << "from (" << start_row << ", " << start_col << ") to ("
                       << end_row << ", " << end_col << ") in " << distance
@@ -169,7 +169,7 @@ int test_travel_network()
     return ret;
 }
 
-int test_snap_network()
+int test_jump_network()
 {
     int ret = 0;
     BBox<double> bbox;
@@ -204,7 +204,7 @@ int test_snap_network()
         }
         int end_row;
         int end_col;
-        std::tie(end_row, end_col) = network.travel(
+        std::tie(end_row, end_col) = network.walk(
             start_row, start_col, std::get<0>(destination), generator, true);
         if (std::get<1>(destination) != end_row
             || std::get<2>(destination) != end_col) {
@@ -264,7 +264,7 @@ int test_cost_network()
         int end_row;
         int end_col;
         std::tie(end_row, end_col) =
-            network.travel(start_row, start_col, std::get<0>(destination), generator);
+            network.walk(start_row, start_col, std::get<0>(destination), generator);
         if (std::get<1>(destination) != end_row
             || std::get<2>(destination) != end_col) {
             std::cerr << "from (" << start_row << ", " << start_col << ") to ("
@@ -463,7 +463,7 @@ int test_network_probability_last()
     return 0;
 }
 
-int test_step_network()
+int test_teleport_network()
 {
     int ret = 0;
     BBox<double> bbox;
@@ -499,7 +499,7 @@ int test_step_network()
         int end_row;
         int end_col;
         std::tie(end_row, end_col) =
-            network.step(start_row, start_col, generator, std::get<0>(destination));
+            network.teleport(start_row, start_col, generator, std::get<0>(destination));
         if (std::get<1>(destination) != end_row
             || std::get<2>(destination) != end_col) {
             std::cerr << "from (" << start_row << ", " << start_col << ") to ("
@@ -761,7 +761,7 @@ int create_network_from_files(int argc, char** argv)
     if (trips || trace) {
         double min_distance = config.get("min_distance", 1.);
         double max_distance = config.get("max_distance", 1.);
-        bool snap = config.get("snap", false);
+        bool jump = config.get("jump", false);
         double distance_increment = config.get("distance_increment", 1.);
         int seed = config.get("seed", 1);
         std::default_random_engine generator;
@@ -794,7 +794,7 @@ int create_network_from_files(int argc, char** argv)
                 int end_row;
                 int end_col;
                 std::tie(end_row, end_col) =
-                    network.travel(start_row, start_col, distance, generator, snap);
+                    network.walk(start_row, start_col, distance, generator, jump);
                 trips.emplace_back(end_row, end_col, distance);
             }
             if (trace) {
@@ -840,10 +840,10 @@ int run_tests()
 
     ret += test_bbox_functions();
     ret += test_create_network();
-    ret += test_travel_network();
-    ret += test_snap_network();
+    ret += test_walk_network();
+    ret += test_jump_network();
     ret += test_cost_network();
-    ret += test_step_network();
+    ret += test_teleport_network();
     ret += test_network_probability_0_100();
     ret += test_network_probability_0_1();
     ret += test_network_negative_probability();