From 02f5ed46f7487738f36a53583370e8f2711816c1 Mon Sep 17 00:00:00 2001 From: Seth Tisue Date: Sat, 10 Sep 2011 11:07:48 -0400 Subject: [PATCH] relocate commentary from source code to documentation --- README.md | 42 +++++++++++++++++++++++++++++++++++++----- src/Metrics.scala | 36 +----------------------------------- 2 files changed, 38 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 10d09a1..75d8831 100644 --- a/README.md +++ b/README.md @@ -21,33 +21,65 @@ It requires NetLogo 5.0beta5, which isn't out yet. ## Description of primitives in src directory +Anywhere a link breed is required, `links` is also accepted. + ### network:in-link-radius -syntax: `TURTLESET network:in-link-radius RADIUS LINKSET` +syntax: `TURTLESET network:in-link-radius RADIUS LINK-BREED` example: `ask one-of bankers [ show other bankers in-network-radius 5 friendships ]` +Returns the set of turtles within the given distance (number of links followed) +of the calling turtle. +Searches breadth-first from the calling turtle, +following links of the given link breed. + ### network:link-distance -syntax: `network:link-distance TURTLE LINK-SET` +syntax: `network:link-distance TURTLE LINK-BREED` example: `ask one-of-bankers [ show network:link-distance the-best-banker friendships ]` +Finds the distance to the destination turtle (number of links followed). +Searches breadth-first from the calling turtle, +following links of the given link breed. + +Reports -1 if no path exists. + ### network:path-turtles -syntax: `network:path-turtles TURTLE LINK-SET` +syntax: `network:path-turtles TURTLE LINK-BREED` example: `ask banker1 [ show network:path-turtles banker3 friendships ]` -> [(banker 1) (banker 2) (banker 3)] +Reports a list of turtles following the shortest path from the calling +turtle to the destination turtle. The calling turtle and the +destination are included in the list. + +Reports an empty list if no path exists. + +Searches breadth-first from the calling turtle, +following links of the given link breed. + +Follows links at the same depth in random order. If there are +multiple shortest paths, a different path may be returned on +subsequent calls, depending on the random choices made during search. + ### network:path-links -syntax: `network:path-links TURTLE LINK-SET` +syntax: `network:path-links TURTLE LINK-BREED` example: `ask banker1 [ show network:path-links banker3 friendships ]` -> [(link 1 2) (link 2 3)] -### __average-path-length +### network:mean-path-length + +Reports the average shortest-path length between all distinct pairs of +nodes in the given set of turtles, following links of the given link +breed. + +Reports -1 if the turtles are not fully connected. ### Notes diff --git a/src/Metrics.scala b/src/Metrics.scala index 4949fc6..d1b67e3 100644 --- a/src/Metrics.scala +++ b/src/Metrics.scala @@ -15,7 +15,7 @@ object Metrics { // all of the primitives use this to traverse the network in breadth-first order. // each List[Turtle] is a reversed path (destination is head); the paths share - // structure so total memory usage stays within O(n). + // storage, so total memory usage stays within O(n). private def breadthFirstSearch(start: Turtle, links: AgentSet): Stream[List[Turtle]] = { val seen: Turtle => Boolean = { val memory = collection.mutable.HashSet[Turtle](start) @@ -41,23 +41,12 @@ object Metrics { .flatten } - /** - * This method performs a BFS from the sourceNode, following the network imposed by the given - * linkBreed, to find the distance to destNode. Directed links are only followed in the "forward" - * direction. It returns -1 if there is no path between the two nodes. - */ def linkDistance(start: Turtle, end: Turtle, links: AgentSet): Int = breadthFirstSearch(start, links) .find(_.head eq end) .map(_.size - 1) .getOrElse(-1) - /** - * This method performs a BFS from the sourceNode, following the network imposed by the given - * linkBreed, going up to radius layers out. - * - * Note: this method follows directed links only in one direction. - */ def extendedLinkNeighbors(start: Turtle, radius: Double, links: AgentSet): AgentSet = { val resultArray = breadthFirstSearch(start, links) @@ -67,17 +56,6 @@ object Metrics { new ArrayAgentSet(classOf[Turtle], resultArray, start.world) } - /** - * This method performs a BFS from the sourceNode, following the network imposed by the given - * linkBreed, to find the shortest path to destNode. Directed links are only followed in the - * "forward" direction. - * - * It returns an empty list if there is no path between the two nodes. The BFS proceeds in a - * random order, so if there are multiple shortest paths, a random one will be returned. Note, - * however, that the probability distribution of this random choice is subtly different from if we - * had enumerated *all* shortest paths, and chose one of them uniformly at random. I don't think - * there is an efficient way to implement it that other way. - */ def pathTurtles(random: Random, start: Turtle, end: Turtle, links: AgentSet): LogoList = breadthFirstSearch(start, links) .find(_.head eq end) @@ -95,20 +73,8 @@ object Metrics { .getOrElse(LogoList.Empty) } - /** - * Calculates the mean shortest-path length between all (distinct) pairs of nodes in the given - * nodeSet, by traveling along links of the given linkBreed. - * - * It returns -1 if any two nodes in nodeSet are not connected by a path. - * - * Note: this method follows directed links both directions. But we could change its - * functionality when dealing with directed links -- I'm not sure what the right thing is. Seems - * like often the mean path length (when only following links "forward") in a directed-graph would - * be undefined. - */ def meanPathLength(nodeSet: AgentSet, linkBreed: AgentSet): Double = 0 - /* var linkManager: LinkManager = null val seen = collection.mutable.HashSet[Turtle]()