Controllable Proximity: Bolt

/**
 * Instances of the {@link Bolt} class generate a Brownian driver
 * sequence with a specified number of values.
 * @author Charles Ames
 */
public class Bolt extends DriverBase {
   /**
    * Value of element 0 in the {@link #values} array.
    * Can be set explicitly by {@link #setOrigin(double)} or randomized
    * by {@link #randomizeOrigin()}.
    */
   private double origin;
   /**
    * Value of element {@link #length}-1 in the {@link #values} array.
    * Defaults to 0.5. Can be set explicitly by {@link #setGoal(double)}
    * or randomized by {@link #randomizeGoal()}.
    */
   private double goal;
   /**
    * Root-mean-square distance between consecutive sequence values.
    */
   private double deviation;
   /**
    * Holds the sequence of samples.  Sized by calling {@link #setLength(int)}.
    */
   private List<Double> values;
   private Iterator<Double> iterator;
   /**
    * Option for handling out-of-range values.
    */
   private ContainmentMode containmentMode;
   /**
    * Singleton {@link ContinuousDistribution} instance of a standard bell curve
    * centered around zero with unit deviation.
    */
   private ContinuousDistribution normalDistribution;
   /**
    * Constructor for {@link Bolt} instances with container.
    * @param container An entity which contains this driver.
    */
   public Bolt(WriteableEntity container) {
      super(container);
      this.normalDistribution = ContinuousDistribution.getNormalDistribution();
      this.values = new ArrayList<Double>();
      this.iterator = null;
      this.origin = .5;
      this.goal = .5;
      this.deviation = .1;
      this.containmentMode = ContainmentMode.REFLECT;
   }
   /**
    * Constructor for {@link Bolt} instances without container.
    */
   public Bolt() {
      this(null);
   }
   /**
    * Getter for {@link #containmentMode}.
    * @return The assigned {@link #containmentMode} value.
    */
   public ContainmentMode getMode() {
      return containmentMode;
   }
   /**
    * Setter for {@link #containmentMode}.
    * @param containmentMode The intended {@link #containmentMode} value.
    */
   public void setMode(ContainmentMode containmentMode) {
      this.containmentMode = containmentMode;
   }
   /**
    * Getter for {@link #length}.
    * @return The assigned {@link #length} value.
    * @throws UninitializedException when the output array has not been allocated
    * via a call to {@link #setLength(int)}.
    */
   public int getLength() {
      if (null == values) throw new UninitializedException("Output array not initialized");
      return values.size() - 1;
   }
   /**
    * Setter for {@link #length}.
    * @param length The intended {@link #length} value.
    * @throws IllegalArgumentException when the length is not positive.
    */
   public void setLength(int length) {
      if (0 >= length) {
         throw new IllegalArgumentException("Length not positive");
      }
      if (values.size()-1 != length) {
         values.clear();
         for (int index = 0; index <= length; index++)
            values.add(0.);
      }
   }
   /**
    * Getter for {@link #origin}.
    * @return the assigned {@link #origin} value.
    */
   public double getOrigin() {
      return origin;
   }
   /**
    * Setter for {@link #origin}.
    * @param origin the intended {@link #origin} value.
    * @throws IllegalArgumentException when the argument falls outside
    * the range from zero to unity.
    */
   public void setOrigin(double origin) {
      Driver.checkDriverValue(origin);
      this.origin = origin;
   }
   /**
    * Randomize {@link #origin}.
    */
   public void randomizeOrigin() {
      this.origin = getRandom().nextDouble();
   }
   /**
    * Getter for {@link #goal}.
    * @return the assigned {@link #goal} value.
    */
   public double getGoal() {
      return goal;
   }
   /**
    * Setter for {@link #goal}.
    * @param goal the intended {@link #goal} value.
    * @throws IllegalArgumentException when the argument falls outside
    * the range from zero to unity.
    */
   public void setGoal(double goal) {
      Driver.checkDriverValue(goal);
      this.goal = goal;
   }
   /**
    * Randomize {@link #goal}.
    */
   public void randomizeGoal() {
      this.goal = getRandom().nextDouble();
   }
   /**
    * Getter for {@link #goal}.
    * @return The assigned {@link #goal} value.
    */
   public double getDeviation() {
      return deviation;
   }
   /**
    * Setter for {@link #deviation}.
    * @param deviation The intended {@link #deviation} value.
    * @throws IllegalArgumentException when the argument is not positive.
    */
   public void setDeviation(double deviation) {
      if (deviation < MathMethods.TINY)
         throw new IllegalArgumentException("Deviation not positive");
      this.deviation = deviation;
   }
   protected double generate() {
      if (null == iterator) throw new UnsupportedOperationException("Iteration not in progress");
      return containmentMode.contain(iterator.next());
   }
   /**
    * Test if the if the {@link values} collection still contains unpresented values
    * @return true if the sequence from {@link values} contains unpresented values; false
    * if the sequence is complete.
    * @throws {@link UnsupportedOperationException} when iteration from {@link values} is not in progress.
    */
   @Override
   public boolean hasNext() {
      if (null == iterator) throw new UnsupportedOperationException("Iteration not in progress");
      return iterator.hasNext();
   }
   @Override
   public boolean hasReset() {return true;}
   @Override
   public void reset() {
      int length = values.size()-1;
      values.set(0, origin);
      values.set(length, goal);
      calculate(values, deviation, 0, length);
      iterator = values.iterator();
      setValue(iterator.next());
   }
   private void calculate(List<Double> values, double deviation, int low, int high) {
      if (low >= high - 1) return;
      int mid = (low + high) / 2;
      Double lowValue = values.get(low);
      Double highValue = values.get(high);
      double avg = (lowValue + highValue) / 2.;
      double midValue;
      double u = getRandom().nextDouble();
      midValue = avg + (Math.sqrt(mid - low) * deviation *  normalDistribution.quantile(u));
      values.set(mid, midValue);
      if (low < mid - 1) calculate(values, deviation, low, mid);
      if (high > mid + 1) calculate(values, deviation, mid, high);
   }
}