Merge pull request #369 from p2t2/DEV3.0.0

Dev3.0.0

.gitignore

@@ -19,3 +19,4 @@ project/plugins/project/
 .cache
 .classpath
 .project
+/bin/

Figaro/META-INF/MANIFEST.MF

@@ -2,7 +2,7 @@ Manifest-Version: 1.0
 Bundle-ManifestVersion: 2
 Bundle-Name: Figaro
 Bundle-SymbolicName: com.cra.figaro
-Bundle-Version: 2.5.0
+Bundle-Version: 3.0.0
 Export-Package: com.cra.figaro.algorithm,
  com.cra.figaro.algorithm.decision,
  com.cra.figaro.algorithm.decision.index,

Figaro/figaro_build.properties

@@ -1 +1 @@
-version=2.5.0.0
+version=3.0.0.0

Figaro/src/main/scala/com/cra/figaro/algorithm/Abstraction.scala

@@ -1,5 +1,5 @@
 /*
- * Abstraction
+ * Abstraction.scala
  * Abstractions of elements to a smaller set of values.
  * 
  * Created By:      Avi Pfeffer (apfeffer@cra.com)
@@ -29,7 +29,7 @@ import scala.language.postfixOps
  * argument is used to generate the sample concrete points from which the abstract points are selected, in
  * case the full set of concrete points cannot be generated (e.g., for continuous elements). The value of
  * this argument is multiplied by the number of abstract points to determine the total number of concrete
- * points. The default value for this argument is 10.This is indicated by attaching an Abstraction to the
+ * points. The default value for this argument is 10. This is indicated by attaching an Abstraction to the
  * element.
  */
 

Figaro/src/main/scala/com/cra/figaro/algorithm/Anytime.scala

@@ -1,13 +1,13 @@
 /*
  * Anytime.scala
  * Anytime algorithms
- * 
+ *
  * Created By:      Avi Pfeffer (apfeffer@cra.com)
  * Creation Date:   Jan 1, 2009
- * 
+ *
  * Copyright 2013 Avrom J. Pfeffer and Charles River Analytics, Inc.
  * See http://www.cra.com or email figaro@cra.com for information.
- * 
+ *
  * See http://www.github.com/p2t2/figaro for a copy of the software license.
  */
 
@@ -56,7 +56,7 @@ trait Anytime extends Algorithm {
   def runStep(): Unit
 
   /**
-   * Optional function to run when the algorithm is stopped (not killed). Used in samplers to update lazy values
+   * Optional function to run when the algorithm is stopped (not killed). Used in samplers to update lazy values.
    */
   def stopUpdate(): Unit = {  }
 
@@ -65,17 +65,17 @@ trait Anytime extends Algorithm {
    */
   class Runner extends Actor {
     import context._
-    
+
     def active: Receive = {
       case Handle(service) =>
         sender ! handle(service)
-      case "stop" => 
+      case "stop" =>
         stopUpdate()
         become (inactive)
-      case "next" => 
+      case "next" =>
         runStep()
         self ! "next"
-      case _ => 
+      case _ =>
         sender ! ExceptionResponse("Algorithm is still running")
     }
 
@@ -86,23 +86,23 @@ trait Anytime extends Algorithm {
         runStep()
         become(active)
         self ! "next"
-      case "resume" => 
+      case "resume" =>
         resume()
         become(active)
       	self ! "next"
-      case "kill" => 
+      case "kill" =>
          become(shuttingDown)
-      case _ => 
+      case _ =>
         sender ! ExceptionResponse("Algorithm is stopped")
     }
-    
+
     def shuttingDown: Receive = {
-      case _ => 
+      case _ =>
         sender ! ExceptionResponse("Anytime algorithm has terminated")
     }
-    
+
     def receive = inactive
-    
+
 
   }
 
@@ -116,7 +116,7 @@ trait Anytime extends Algorithm {
 
 		  }
 		  """)
-		  
+
   var system: ActorSystem = null
   var runner: ActorRef = null
   var running = false;
@@ -126,16 +126,15 @@ trait Anytime extends Algorithm {
    */
   def handle(service: Service): Response
 
-  
+
   protected def doStart() = {
     if (!running) {
     	system = ActorSystem("Anytime", ConfigFactory.load(customConf))
     	runner = system.actorOf(Props(new Runner))
     	initialize()
-//    	println("Using ANYTIME")
     	running = true
     }
-      
+
     runner ! "start"
   }
 
@@ -146,7 +145,10 @@ trait Anytime extends Algorithm {
   protected def doKill() = {
     shutdown
   }
-
+
+  /**
+   * Release all resources from this anytime algorithm.
+   */
   def shutdown {
     cleanUp()
     if (running)
@@ -155,6 +157,5 @@ trait Anytime extends Algorithm {
     	system.stop(runner)
     	system.shutdown
     }
-//    println("Shutdown ANYTIME")
   }
 }

Figaro/src/main/scala/com/cra/figaro/algorithm/AnytimeProbQuery.scala

@@ -35,7 +35,7 @@ trait AnytimeProbQuery extends ProbQueryAlgorithm with Anytime {
    */
   case class Distribution[T](distribution: Stream[(Double, T)]) extends Response
    /**
-   * A message instructing the handler to compute the expectation of the target element under the given function
+   * A message instructing the handler to compute the expectation of the target element under the given function.
    */
   case class ComputeExpectation[T](target: Element[T], function: T => Double) extends Service
     /**

Figaro/src/main/scala/com/cra/figaro/algorithm/LazyAlgorithm.scala

@@ -1,30 +1,54 @@
 /*
  * LazyAlgorithm.scala
  * Lazy algorithms.
- * 
+ *
  * Created By:      Avi Pfeffer (apfeffer@cra.com)
  * Creation Date:   Dec 28, 2013
- * 
+ *
  * Copyright 2013 Avrom J. Pfeffer and Charles River Analytics, Inc.
  * See http://www.cra.com or email figaro@cra.com for information.
- * 
+ *
  * See http://www.github.com/p2t2/figaro for a copy of the software license.
  */
 
 package com.cra.figaro.algorithm
 
+/**
+ * A lazy algorithm is an algorithm that can be run to increasing depths.
+ */
 trait LazyAlgorithm extends Algorithm {
+  /**
+   * The current depth to which the algorithm should be run.
+   */
   var depth = 0
-
+
+  /**
+   * Run the algorithm to the given depth.
+   */
   def run(depth: Int): Unit
-
+
+  /**
+   * Start the algorithm. This will run the algorithm to one depth.
+   */
   def doStart() { pump() }
-
+
+  /**
+   * Increase the depth and run the algorithm again.
+   */
   def pump() { depth += 1; run(depth) }
-
+
+  /**
+   * Stop the algorithm.
+   */
   def doStop() { }
-
+
+  /**
+   * Resume the algorithm by increasing the depth and running again.
+   */
   def doResume() { pump() }
-
+
+  /**
+   * Kill the algorithm.
+   */
   def doKill() { depth = -1 }
 }

Figaro/src/main/scala/com/cra/figaro/algorithm/ParameterLearner.scala

@@ -14,7 +14,7 @@
 package com.cra.figaro.algorithm
 
 /**
- * Trait of algorithms that learn parameters
+ * Trait of algorithms that learn parameters.
  */
 trait ParameterLearner {
 

Figaro/src/main/scala/com/cra/figaro/algorithm/ProbEvidenceAlgorithm.scala

@@ -50,15 +50,15 @@ trait ProbEvidenceAlgorithm extends Algorithm {
   }
 
   /**
-   * The computed probability of evidence
+   * The computed probability of evidence.
    */
   def probEvidence: Double = {
     if (!active) throw new AlgorithmInactiveException
     computedResult
   }
 
    /**
-   * The computed log probability of evidence
+   * The computed log probability of evidence.
    */
   def logProbEvidence: Double = {
     if (!active) throw new AlgorithmInactiveException

Figaro/src/main/scala/com/cra/figaro/algorithm/ProbQueryAlgorithm.scala

@@ -94,14 +94,14 @@ trait ProbQueryAlgorithm
   }
 
   /**
-   * Return the mean of the probability density function for the given continuous element
+   * Return the mean of the probability density function for the given continuous element.
    */
   def mean(target: Element[Double]): Double = {
     expectation(target, (d: Double) => d)
   }
 
   /**
-   * Return the variance of the probability density function for the given continuous element
+   * Return the variance of the probability density function for the given continuous element.
    */
   def variance(target: Element[Double]): Double = {
     val m = mean(target)
@@ -110,7 +110,7 @@ trait ProbQueryAlgorithm
   }
 
   /**
-   * Return an element representing the posterior probability distribution of the given element
+   * Return an element representing the posterior probability distribution of the given element.
    */
   def posteriorElement[T](target: Element[T], universe: Universe = Universe.universe): Element[T] = {
     Select(distribution(target).toList:_*)("", universe)

Figaro/src/main/scala/com/cra/figaro/algorithm/decision/DecisionAlgorithm.scala

@@ -21,7 +21,7 @@ import scala.collection.immutable.Map
 
 /**
  * Trait that defines some common interface functions for decision algorithms.
- * Every decision algorithm must define the function computeUtility()
+ * Every decision algorithm must define the function computeUtility().
  */
 
 trait DecisionAlgorithm[T, U] extends Algorithm {
@@ -38,24 +38,24 @@ trait DecisionAlgorithm[T, U] extends Algorithm {
   private lazy val util = computeUtility()
 
   /** 
-   *  Get the total utility and weight for all sampled values of the parent and decision
+   *  Get the total utility and weight for all sampled values of the parent and decision.
    */
   def getUtility() = util
 
   /** 
-   *  Get the total utility and weight for a specific value of a parent and decision
+   *  Get the total utility and weight for a specific value of a parent and decision.
    */
   def getUtility(p: T, d: U) = util((p, d))
 
   /** 
    *  Sets the policy for the given decision. This will get the computed utility of the algorithm
    *  and call setPolicy on the decision. Note there is no error checking here, so the decision in
-   *  the argument must match the target decision in the algorithm
+   *  the argument must match the target decision in the algorithm.
    */
   def setPolicy(e: Decision[T, U]): Unit = e.setPolicy(getUtility())
 }
 
 /**
- * Trait for one time Decision Algorithms
+ * Trait for one time Decision Algorithms.
  */
 trait OneTimeProbQueryDecision[T, U] extends OneTimeProbQuery with DecisionAlgorithm[T, U]

Figaro/src/main/scala/com/cra/figaro/algorithm/decision/DecisionImportance.scala

@@ -29,7 +29,7 @@ import scala.collection.mutable.{ Set, Map }
  */
 /**
  * Importance sampling for decisions. Almost the exact same as normal importance sampling except that it keeps
- * track of utilities and probabilities (to compute expected utility) and it implements DecisionAlgorithm trait
+ * track of utilities and probabilities (to compute expected utility) and it implements DecisionAlgorithm trait.
  */
 
 abstract class DecisionImportance[T, U] private (override val universe: Universe, utilityNodes: List[Element[_]], decisionTarget: Decision[T, U],
@@ -45,7 +45,7 @@ abstract class DecisionImportance[T, U] private (override val universe: Universe
   private def utilitySum = (0.0 /: utilityNodes)((s: Double, n: Element[_]) => s + n.value.asInstanceOf[Double])
 
   /**
-   * Cleans up the temporary elements created during sampling
+   * Cleans up the temporary elements created during sampling.
    */
   def cleanup() = universe.deactivate(queryTargets)
 
@@ -86,7 +86,7 @@ abstract class DecisionImportance[T, U] private (override val universe: Universe
    *
    * For decisions, our weight is actually the weight of the sampled state times the sum of the utility nodes. This will be
    * used as the "weight" in the weighted sampler, ie, we are accumulating the expected utility of each state. Note that the weights
-   * will not be normalized, but that is ok since strategies are an optimization and everything will be divided by a constant
+   * will not be normalized, but that is ok since strategies are an optimization and everything will be divided by a constant.
    *
    */
   @tailrec final def sample(): Sample = {