Continuous Fracture Transform¹

/**
 * The {@link ContinuousFracture} class transforms a driver sequence by
 * dividing the driver domain into regions which are then permuted.
 * It is a rough and ready way of deriving quasi-periodic sequences from
 * (unflattened) {@link net.charlesames.seqgen.driver.Baker} or
 * {@link net.charlesames.seqgen.driver.Logistic} output.
 * This transform works best with drivers when the incoming driver values
 * have strong attractors; that is, when most driver values are
 * concentrated around sharp peaks in the distribution. It is least effective
 * for relatively uniform driver sequences such as those produced by
 * {@link net.charlesames.seqgen.driver.Lehmer},
 * {@link net.charlesames.seqgen.driver.Balance}, or
 * {@link net.charlesames.seqgen.driver.Brownian}.
 * @author Charles Ames
 */
public class ContinuousFracture
extends TransformBase<Double> implements Transform.Continuous, Driver {
   private Permutation permutation;
   /**
    * Constructor for {@link ContinuousFracture} instances.
    * @param container An entity which contains this transform.
    */
   public ContinuousFracture(WriteableEntity container) {
      super(container);
      permutation = new Permutation(this);
      permutation.setIDQuality(AttributeQuality.UNUSED);
      permutation.setNameQuality(AttributeQuality.UNUSED);
   }
   /**
    * Setter for {@link #itemCount}.
    * @param itemCount The intended {@link #itemCount} value.
    */
   public void setItemCount(int itemCount) {
      checkItemCount(itemCount);
      permutation.fillAscending(itemCount);
      makeDirty();
   }
   /**
    * Check if the indicated value is suitable for {@link #itemCount}.
    * @param itemCount The indicated value.
    */
   public void checkItemCount(int itemCount) {
      if (0 >= itemCount)
         throw new IllegalArgumentException("Item count not positive");
   }
   /**
    * Populate the member array of the embedded {@link Permutation} instance with
    * values derived from a source {@link Permutation}.
    * This method leverages {@link Permutation#iterateMembers(int, int, int, int)},
    * whose documentation further explains the start, increment, multiplier, and
    * transposition arguments.
    * @param source The source {@link Permutation} instance.
    * @param start Starting position.
    * @param increment Position increment between iterations.
    * @param multiplier Multiplier applied modulo N to each member.
    * @param transposition Offset added modulo N to each member.
    */
   public void setPermutation(Permutation source, int start, int increment,
         int multiplier, int transposition) {
      permutation.copyMembers(source, start, increment, multiplier, transposition);
      makeDirty();
   }
   /**
    * Populate the member array of the embedded {@link Permutation} instance with
    * values from a source {@link Permutation}.
    * @param source The source {@link Permutation} instance.
    */
   public void setPermutation(Permutation source) {
      permutation.copyMembers(source, 0, 1, 1, 0);
      makeDirty();
   }
   /**
    * Copy the members of the embedded {@link Permutation} instance to
    * a newly allocated instance.
    * @return A {@link Permutation} instance with the same content as
    * the embedded {@link Permutation} instance.
    */
   public Permutation copyPermutation() {
      Permutation result = new Permutation(null);
      result.copyMembers(permutation, 0, 1, 1, 0);
      return result;
   }
   /**
    * Populate the member array of the embedded {@link Permutation} instance with
    * an ascending sequence of integers.
    * @param itemCount The permutation length.
    */
   public void fillAscending(int itemCount) {
      permutation.fillAscending(itemCount);
   }
   /**
    * Getter for {@link #itemCount}.
    * @return The assigned {@link #itemCount} value.
    */
   public int itemCount() {
      return permutation.itemCount();
   }
   /**
    * Shuffle the region mapping.
    * Do this rarely.
    */
   public void shuffle() {
      permutation.shuffleMembers();
   }
   @Override
   public Double minGraphValue(double tail) {
      return 0.;
   }
   @Override
   public Double maxGraphValue(double tail) {
      return 1.;
   }
   @Override
   public Double minRange() {
      return 0.;
   }
   @Override
   public Double maxRange() {
      return 1.;
   }
   @Override
   protected ContinuousDistribution createDistribution() {
      throw new UnsupportedOperationException("Method not implemented");
   }
   @Override
   protected void validate(DistributionBase<Double> distribution) {
      throw new UnsupportedOperationException("Method not implemented");
   }
   @Override
   public Double convert(double driver) {
      Driver.checkDriverValue(driver);
      double chooser = itemCount() * driver;
      int index = (int) chooser;
      double residue = chooser - index;
      int newIndex = permutation.memberAt(index);
      double value = (newIndex + residue) / (double) itemCount();
      return value;
   }
   @Override
   public boolean hasReset() {
      return getDriver().hasReset();
   }
   @Override
   public void reset() {
      getDriver().reset();
   }
   @Override
   public double getValue() {
      return getDriver().getValue();
   }
   @Override
   public void setValue(double value) {
      getDriver().setValue(value);
   }
   @Override
   public void randomizeValue() {
      getDriver().randomizeValue();
   }
}