Articulated Proximity: Rosy¹

/**
 * Instances of the {@link Rosy} class generate a driver sequence in
 * which the most significant bits have a controllable likelihood to hold
 * over from the previous value.
 * @author Charles Ames
 */
public class Rosy extends DriverBase {
   /**
    * Number of bits manipulated, from most-significant downward.
    */
   private int depth;
   /**
    * Likelihood of most-significant bit retaining previous value.
    */
   private double retention;
   /**
    * Divisor for calculating retention rate for bit i+1 relative to
    * retention rate for bit i.
    */
   private double rolloff;
   private double scale;
   private int msb;
    /**
    * Constructor for {@link Rosy} instances with container.
    * @param container An entity which contains this driver.
    */
   public Rosy(WriteableEntity container) {
      super(container);
      this.retention = Double.NaN;
      this.depth = Integer.MIN_VALUE;
      this.rolloff = Double.NaN;
   }
   /**
    * Constructor for {@link Rosy} instances without container.
    */
   public Rosy() {
      this(null);
   }
   /**
    * Setter for {@link #depth}.
    * @param depth The intended {@link #depth}.
    */
   public void setDepth(int depth) {
      checkDepth(depth);
      if (this.depth != depth) {
         this.depth = depth;
         this.scale = Math.pow(2., depth);
         this.msb = ((int) scale) >> 1;
      }
   }
   /**
    * Check if the indicated value is suitable for {@link #depth}.
    * @param depth The indicated value;
    */
   public void checkDepth(int depth) {
      if (0 >= depth)
         throw new IllegalArgumentException("Depth not positive");
   }
   /**
    * Getter for {@link #depth}.
    * @return The assigned {@link #depth} value.
    */
   public int getDepth() {
      if (Integer.MIN_VALUE == depth) throw new UninitializedException("Depth not initialized");
      return depth;
   }
   /**
    * Getter for {@link #retention}.
    * @return The assigned {@link #retention} value.
    */
   public double getRetention() {
      if (Double.isNaN(retention)) throw new UninitializedException("Retention not initialized");
      return retention;
   }
   /**
    * Setter for {@link #retention}.
    * @param retention The intended {@link #retention} value.
    */
   public void setRetention(double retention) {
      checkRetention(retention);
      this.retention = retention;
   }
   /**
    * Check if the indicated value is appropriate for {@link #retention}.
    * @param retention The indicated value.
    */
   public void checkRetention(double retention) {
      if (retention < 0. || retention > 1.)
         throw new IllegalArgumentException("Retention rate outside range from zero to unity");
   }
   /**
    * Getter for {@link #rolloff}.
    * @return The assigned {@link #rolloff} value.
    */
   public double getRolloff() {
      if (Double.isNaN(rolloff)) throw new UninitializedException("Rolloff not initialized");
      return rolloff;
   }
   /**
    * Setter for {@link #rolloff}.
    * @param rolloff The intended {@link #rolloff} value.
    */
   public void setRolloff(double rolloff) {
      checkRolloff(rolloff);
      this.rolloff = rolloff;
   }
   /**
    * Check if the indicated value is appropriate for {@link #rolloff}.
    * @param rolloff The indicated value.
    */
   public void checkRolloff(double rolloff) {
      if (rolloff < MathMethods.ONE_PLUS)
         throw new IllegalArgumentException("Rolloff rate must be larger than unity");
   }
   @Override
   protected double generate() {
      Random random = getRandom();
      double result = getValue();
      double p = getRetention();
      double r = getRolloff();
      int limit = getDepth();
      int mask = msb; // must be valid if getDepth() worked.
      int oldValue = (int) Math.floor(scale * result);
      int newValue = 0;
      for (int level = 0; level < limit; level++) {
         int increment;
         if (random.nextDouble() < p) {
            increment = mask & oldValue;
         }
         else {
            increment = random.nextBoolean() ? mask : 0;
         }
         newValue += increment;
         mask >>= 1;
         p /= r;
      }
      return (newValue + random.nextDouble()) / scale;
   }
}