Class MetricKeeper

java.lang.Object
gametree.MetricKeeper
public class MetricKeeper extends Object
This class is intended for use with algorithm testing by keeping track of metrics used to evaluate different algorithms on game tree search problems.

Three metrics are kept by this class:

  • Number of Evaluations
  • Number of Expansions
  • Number of Nodes (kept in memory)
These metrics are kept separate from the GameTreeNode logic because they are independent from the structure of the tree and depend not only on the algorithm used, but also on the GameTreeNode implementation. Therefore, during exploration of the game tree, calls of GameTreeNode.children(MetricKeeper...), GameTreeNode.lowerbound(MetricKeeper...), and GameTreeNode.upperbound(MetricKeeper...) may increment the counters for the provided MetricKeeper object. The totals for these metrics can be obtained at any time.

The metrics are stored in volatile fields such that multi-threaded operation still obtains expected results from the MetricKeeper.

It is good practice for GameTreeNode implementations to call incrementEvaluations() whenever either IGamePosition.upperbound() or IGamePosition.lowerbound() are called. This is to keep maximum accuracy in the described metric. Some implementations of IGamePosition may compute both bounds at the same time and simply store this metric for when it is requested. In those cases, the final evaluations() metric may be divided by 2 to account for this. It is also recommended, for this reason, that GameTreeNode implementations only ask the same IGamePosition object for each of these bounds once.

Version:
1.0
Author:
Pascal Anema

  • Field Details

    • name

      public final String name

  • Constructor Details

    • MetricKeeper

      public MetricKeeper(String metricName, long numEvaluations, long numExpansions, long numNodes, long maxNumNodes)
      Initialises this object with the specified initial values.
      Parameters:
      numEvaluations - initial value for the number of evaluations measured.
      numExpansions - initial value for the number of expansions measured.
      numNodes - initial value for the number of nodes measured.
      maxNumNodes - initial value for the maximum number of nodes measured.

    • MetricKeeper

      public MetricKeeper(String metricName, long numEvaluations, long numExpansions, long numNodes)
      Initialises this object with the specified initial values.
      Parameters:
      numEvaluations - initial value for the number of evaluations measured.
      numExpansions - initial value for the number of expansions measured.
      numNodes - initial value for the number of nodes measured.

    • MetricKeeper

      public MetricKeeper(String metricName, MetricKeeper m)
      Initialises this object with initial values equal to the current values of the given MetricKeeper object m.
      Parameters:
      m - Some MetricKeeper object

    • MetricKeeper

      public MetricKeeper(MetricKeeper m)

    • MetricKeeper

      public MetricKeeper(String name)
      Initialises this object with initial values of 0 for all metrics.

    • MetricKeeper

      public MetricKeeper()
      Initialises this object with initial values of 0 for all metrics, and name "Metrics".

  • Method Details

    • copy

      public MetricKeeper copy(String name)
      Creates a copy of this MetricKeeper with the same metric values, but no link to this object. Measurements made by this metric keeper will not be registered by the returned object, only past measurements are copied over.
      Parameters:
      name - the name of the returned copy
      Returns:
      A new MetricKeeper with the same metric values as this metric keeper.

    • copy

      public MetricKeeper copy()
      Creates a copy of this MetricKeeper with the same metric values, but no link to this object. Measurements made by this metric keeper will not be registered by the returned object, only past measurements are copied over.

      The name of the returned copy will be the name of the original plus a counter "(1)" or the increment of an existing counter, e.g.: "metric (9)" becomes "metric (10)".

      Returns:
      A new MetricKeeper with the same metric values as this metric keeper.

    • incrementEvaluations

      public void incrementEvaluations(long value)
      Increments the number of node evaluations observed by this MetricKeeper by value.

      A node evaluation occurs every time a node has to be evaluated to compute its upper- and/or lower-bound value.

      Parameters:
      value - the value to increment evaluations by

    • incrementEvaluations

      public void incrementEvaluations()
      Increments the number of node evaluations observed by this MetricKeeper by one.

      A node evaluation occurs every time a node has to be evaluated to compute its upper- and/or lower-bound value.

    • evaluations

      public long evaluations()
      Returns:
      The total number of node evaluations observed by this MetricKeeper.

    • incrementExpansions

      public void incrementExpansions(long value)
      Increments the number of node expansions observed by this MetricKeeper by value.

      A node expansion occurs every time a node's children have to be computed in order to expand the tree further from that node.

      Parameters:
      value - the value to increment expansions by

    • incrementExpansions

      public void incrementExpansions()
      Increments the number of node expansions observed by this MetricKeeper by one.

      A node expansion occurs every time a node's children have to be computed in order to expand the tree further from that node.

    • expansions

      public long expansions()
      Returns:
      The total number of node expansions observed by this MetricKeeper.

    • adjustNodeCount

      public void adjustNodeCount(long value)
      Increases the number of nodes kept in memory observed by this MetricKeeper by value.

      value may be negative.

      A node is kept in memory if there is a path of memory positions from the root of the tree to it.

      Parameters:
      value - the value to increment nodes by

    • setNodeCount

      public void setNodeCount(long value)

    • nodes

      public long nodes()
      Returns:
      The total number of nodes kept in memory observed by this MetricKeeper.

    • maxObservedNodes

      public long maxObservedNodes()
      Returns:
      The maximum number of nodes kept in memory observed by this MetricKeeper.

    • describe

      public String describe()

    • incrementMetrics

      public static void incrementMetrics(long evaluationsIncrement, long expansionsIncrement, MetricKeeper... metrics)
      Updates the given MetricKeeper objects with the supplied values to increment the evaluations and expansions counts by. This will increment the counts of all metrics by at least 0, so negative values are ignored.
      Parameters:
      evaluationsIncrement - the value with which to increment the number of evaluations
      expansionsIncrement - the value with which to increment the number of expansions
      metrics - the MetricKeeper objects to update

    • incrementEvaluations

      public static void incrementEvaluations(long evaluationsIncrement, MetricKeeper... metrics)
      Increments the number of evaluations of all MetricKeeper objects provided by 0 or evaluationsIncrement if it is positive.
      Parameters:
      evaluationsIncrement - the value with which to increment the number of evaluations
      metrics - the MetricKeeper objects to update

    • incrementEvaluations

      public static void incrementEvaluations(MetricKeeper... metrics)
      Increments the number of evaluations of all MetricKeeper objects provided by 1.
      Parameters:
      metrics - the MetricKeeper objects to update

    • incrementExpansions

      public static void incrementExpansions(long expansionsIncrement, MetricKeeper... metrics)
      Increments the number of expansions of all MetricKeeper objects provided by 0 or expansionsIncrement if it is positive.
      Parameters:
      expansionsIncrement - the value with which to increment the number of expansions
      metrics - the MetricKeeper objects to update

    • incrementExpansions

      public static void incrementExpansions(MetricKeeper... metrics)
      Increments the number of expansions of all MetricKeeper objects provided by 1.
      Parameters:
      metrics - the MetricKeeper objects to update

    • adjustNodeCount

      public static void adjustNodeCount(long nodesSavedIncrease, MetricKeeper... metrics)
      Increases the number of nodes kept in memory of all MetricKeeper objects provided by nodesSavedIncrease which may be negative.
      Parameters:
      nodesSavedIncrease - the value with which to increment the number of expansions
      metrics - the MetricKeeper objects to update

    • combineArrays

      @SafeVarargs public static <T> T[] combineArrays(T[] a, T... b)