Refactor permutation and sequence distance interfaces and classes

CHANGELOG.md

@@ -4,12 +4,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - 2021-03-31
+## [Unreleased] - 2021-04-02
 
 ### Added
 * Added the `Permutation.Mechanic.set(Permutation, int[], int, int, int)` method.
 
 ### Changed
+* Refactored the SequenceDistanceMeasurer and SequenceDistanceMeasurerDouble interfaces 
+  into a hierarchy, eliminated an abstract base class made obsolete by that change, and
+  changed all sequence distances in the library to use the new hierarchy. This is a non-breaking
+  change, as the only thing removed was a package-private abstract class, and the
+  change to the SequenceDistanceMeasurer interface was done in such a way that all inherited
+  methods have default implementations.
+* Refactored the PermutationDistanceMeasurer, PermutationDistanceMeasurerDouble,
+  NormalizedPermutationDistanceMeasurer, and NormalizedPermutationDistanceMeasurerDouble 
+  interfaces, and all of the classes that implement them, to move default implementations 
+  from an abstract base class into the appropriate subinterfaces in hierarchy. This is a 
+  non-breaking change, as the only thing removed was a package-private abstract class, and the
+  changes to interfaces were done in such a way that all inherited methods have default 
+  implementations.
 
 ### Deprecated
 

src/org/cicirello/permutations/distance/AcyclicEdgeDistance.java

@@ -42,9 +42,9 @@
  * S. Ronald, "Distance functions for order-based encodings," in Proc. IEEE CEC. IEEE Press, 1997, pp. 49–54.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public final class AcyclicEdgeDistance extends AbstractPermutationDistanceMeasurer {
+public final class AcyclicEdgeDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/BlockInterchangeDistance.java

@@ -40,9 +40,9 @@
  * <p>Runtime: O(n), where n is the permutation length.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public class BlockInterchangeDistance extends AbstractPermutationDistanceMeasurer {
+public class BlockInterchangeDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/CyclicEdgeDistance.java

@@ -42,9 +42,9 @@
  * S. Ronald, "Distance functions for order-based encodings," in Proc. IEEE CEC. IEEE Press, 1997, pp. 49–54.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public final class CyclicEdgeDistance extends AbstractPermutationDistanceMeasurer {
+public final class CyclicEdgeDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/CyclicIndependentDistance.java

@@ -32,7 +32,7 @@
  * the constructor.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  *  
  */
 public final class CyclicIndependentDistance implements PermutationDistanceMeasurer {
@@ -68,19 +68,4 @@ public int distance(Permutation p1, Permutation p2) {
 		}
 		return result;
 	}
-
-	/**
-	 * Measures the distance between two permutations, with cyclic independence:
-	 * distance = min_{i in [0,N)} distance(p1,rotate(p2,i))
-	 * 
-	 * @param p1 first permutation
-	 * @param p2 second permutation 
-	 * @return distance between p1 and p2 
-	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
-	 */
-	@Override
-	public final double distancef(Permutation p1, Permutation p2) {
-		return distance(p1,p2);
-	}
-
 }

src/org/cicirello/permutations/distance/CyclicRTypeDistance.java

@@ -44,9 +44,9 @@
  * IEEE Transactions on Evolutionary Computation, 20(3):434-446, June 2016.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public final class CyclicRTypeDistance extends AbstractPermutationDistanceMeasurer {
+public final class CyclicRTypeDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/CyclicReversalIndependentDistance.java

@@ -33,7 +33,7 @@
  * the constructor.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  *  
  */
 public final class CyclicReversalIndependentDistance implements PermutationDistanceMeasurer {
@@ -83,19 +83,4 @@ public int distance(Permutation p1, Permutation p2) {
 		}
 		return result;
 	}
-
-	/**
-	 * Measures the distance between two permutations, with cyclic and reversal independence:
-	 * distance = min_{i in [0,N)} { distance(p1,rotate(p2,i)), distance(p1,rotate(reverse(p2),i)) }
-	 * 
-	 * @param p1 first permutation
-	 * @param p2 second permutation 
-	 * @return distance between p1 and p2 
-	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
-	 */
-	@Override
-	public final double distancef(Permutation p1, Permutation p2) {
-		return distance(p1,p2);
-	}
-
 }

src/org/cicirello/permutations/distance/DeviationDistance.java

@@ -42,10 +42,10 @@
  * S. Ronald, "More distance functions for order-based encodings," in Proc. IEEE CEC. IEEE Press, 1998, pp. 558–563.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  * 
  */
-public final class DeviationDistance extends AbstractPermutationDistanceMeasurer {
+public final class DeviationDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/DeviationDistanceNormalized.java

@@ -48,10 +48,10 @@
  * Proc. IEEE CEC. IEEE Press, 1998, pp. 558–563.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  * 
  */
-public final class DeviationDistanceNormalized implements PermutationDistanceMeasurerDouble, NormalizedPermutationDistanceMeasurerDouble  {
+public final class DeviationDistanceNormalized implements NormalizedPermutationDistanceMeasurerDouble  {
 
 	private DeviationDistance devDistance;
 
@@ -81,17 +81,4 @@ public double maxf(int length) {
 		if (length <= 1) return 0;
 		return (length * length - (length & 1)) / (2.0 * (length-1));
 	}
-
-	/**
-	 * {@inheritDoc}
-	 *
-	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
-	 */
-	@Override
-	public double normalizedDistance(Permutation p1, Permutation p2) {
-		double m = maxf(p1.length());
-		if (m == 0.0) return 0;
-		return distancef(p1,p2) / m; 
-	}
-
 }

src/org/cicirello/permutations/distance/DeviationDistanceNormalized2005.java

@@ -62,10 +62,10 @@
  * management," in Proc. of MIC2005, 2005.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021  
+ * @version 4.2.2021  
  * 
  */
-public final class DeviationDistanceNormalized2005 implements PermutationDistanceMeasurerDouble, NormalizedPermutationDistanceMeasurerDouble  {
+public final class DeviationDistanceNormalized2005 implements NormalizedPermutationDistanceMeasurerDouble  {
 
 	private DeviationDistance devDistance;
 

src/org/cicirello/permutations/distance/ExactMatchDistance.java

@@ -33,9 +33,9 @@
  * S. Ronald, "More distance functions for order-based encodings," in Proc. IEEE CEC. IEEE Press, 1998, pp. 558–563.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public final class ExactMatchDistance extends AbstractPermutationDistanceMeasurer {
+public final class ExactMatchDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/InterchangeDistance.java

@@ -40,9 +40,9 @@
  * IEEE Transactions on Evolutionary Computation, 20(3):434-446, June 2016.</p>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public final class InterchangeDistance extends AbstractPermutationDistanceMeasurer {
+public final class InterchangeDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/KendallTauDistance.java

@@ -48,10 +48,10 @@
  * M. G. Kendall, "A new measure of rank correlation," Biometrika, vol. 30, no. 1/2, pp. 81–93, June 1938.</p>
  * 
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  * 
  */
-public final class KendallTauDistance extends AbstractPermutationDistanceMeasurer {
+public final class KendallTauDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/LeeDistance.java

@@ -43,10 +43,10 @@
  * C. Lee, "Some properties of nonbinary error-correcting codes," in IRE Transactions on Information Theory, vol. 4, no. 2, pp. 77-82, June 1958.</p>
  * 
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  * 
  */
-public final class LeeDistance extends AbstractPermutationDistanceMeasurer {
+public final class LeeDistance implements NormalizedPermutationDistanceMeasurer {
 
 	/**
 	 * Constructs the distance measurer as specified in the class documentation.

src/org/cicirello/permutations/distance/NormalizedPermutationDistanceMeasurer.java

@@ -27,9 +27,9 @@
  * normalizing the distance to the interval [0,1], but where the base distance is an integer value.
  * 
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public interface NormalizedPermutationDistanceMeasurer extends NormalizedPermutationDistanceMeasurerDouble {
+public interface NormalizedPermutationDistanceMeasurer extends NormalizedPermutationDistanceMeasurerDouble, PermutationDistanceMeasurer {
 
 	/**
 	 * Computes the maximum possible distance between permutations
@@ -39,4 +39,21 @@ public interface NormalizedPermutationDistanceMeasurer extends NormalizedPermuta
 	 * @return the maximum distance between a pair of permutations of the specified length.
 	 */
 	int max(int length);
+
+	@Override
+	default double maxf(int length) {
+		return max(length);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
+	 */
+	@Override
+	default double normalizedDistance(Permutation p1, Permutation p2) {
+		int m = max(p1.length());
+		if (m==0) return 0;
+		return distance(p1,p2) / ((double)m);
+	}
 }

src/org/cicirello/permutations/distance/NormalizedPermutationDistanceMeasurerDouble.java

@@ -27,19 +27,9 @@
  * normalizing the distance to the interval [0,1].
  * 
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 1.28.2021
+ * @version 4.2.2021
  */
-public interface NormalizedPermutationDistanceMeasurerDouble {
-
-	/**
-	 * <p>Measures the distance between two permutations, normalized to the interval [0.0, 1.0].</p>
-	 * 
-	 * @param p1 first permutation
-	 * @param p2 second permutation 
-	 * @return distance between p1 and p2 normalized to the interval [0.0, 1.0] 
-	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
-	 */
-	double normalizedDistance(Permutation p1, Permutation p2);
+public interface NormalizedPermutationDistanceMeasurerDouble extends PermutationDistanceMeasurerDouble {
 
 	/**
 	 * Computes the maximum possible distance between permutations
@@ -49,4 +39,18 @@ public interface NormalizedPermutationDistanceMeasurerDouble {
 	 * @return the maximum distance between a pair of permutations of the specified length.
 	 */
 	double maxf(int length);
+
+	/**
+	 * <p>Measures the distance between two permutations, normalized to the interval [0.0, 1.0].</p>
+	 * 
+	 * @param p1 first permutation
+	 * @param p2 second permutation 
+	 * @return distance between p1 and p2 normalized to the interval [0.0, 1.0] 
+	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
+	 */
+	default double normalizedDistance(Permutation p1, Permutation p2) {
+		double m = maxf(p1.length());
+		if (m==0) return 0;
+		return distancef(p1,p2) / m;
+	}
 }