Merge pull request #213 from cicirello/cycle-distance

Cycle distance

Author: cicirello

.gitignore

@@ -7,3 +7,4 @@ type-search-index.zip
 package-search-index.zip
 module-search-index.zip
 tag-search-index.zip
+dependency-reduced-pom.xml

CHANGELOG.md

@@ -4,9 +4,10 @@ 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] - 2022-04-16
+## [Unreleased] - 2022-05-31
 
 ### Added
+* CycleDistance: implementation of cycle distance described in https://doi.org/10.3390/app12115506
 
 ### Changed
 

src/main/java/org/cicirello/permutations/Permutation.java

@@ -44,6 +44,9 @@ public final class Permutation implements Serializable, Iterable<Permutation>, C
 
 	private static final long serialVersionUID = 1L;
 
+	/** 
+	 * Raw permutation, which should consist of a permutation of the integers in [0, permutation.length). 
+	 */
 	private final int[] permutation;
 
 	/**

src/main/java/org/cicirello/permutations/distance/CycleDistance.java

@@ -0,0 +1,100 @@
+/*
+ * JavaPermutationTools: A Java library for computation on permutations and sequences
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ *
+ * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ *
+ * JavaPermutationTools is free software: you can 
+ * redistribute it and/or modify it under the terms of the GNU 
+ * General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your 
+ * option) any later version.
+ *
+ * JavaPermutationTools is distributed in the hope 
+ * that it will be useful, but WITHOUT ANY WARRANTY; without even 
+ * the implied warranty of MERCHANTABILITY or FITNESS FOR A 
+ * PARTICULAR PURPOSE.  See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.cicirello.permutations.distance;
+
+import org.cicirello.permutations.Permutation;
+
+/**
+ * <p>Cycle distance is the count of the number of non-singleton permutation cycles
+ * between a pair of permutations. Cycle distance is a semi-metric, satisfying all
+ * of the metric properties except for the triangle inequality.</p>
+ *
+ * <p>It was introduced in the following article:</p>
+ *
+ * <p>Vincent A. Cicirello. 2022. <a href="https://www.cicirello.org/publications/applsci-12-05506.pdf">Cycle 
+ * Mutation: Evolving Permutations via Cycle Induction</a>, <i>Applied Sciences</i>, 12(11), Article 5506 (June 2022). 
+ * doi:<a href="https://doi.org/10.3390/app12115506">10.3390/app12115506</a></p>
+ *
+ * <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>
+ */
+public final class CycleDistance implements NormalizedPermutationDistanceMeasurer {
+	
+	/**
+	 * Constructs the distance measurer as specified in the class documentation.
+	 */
+	public CycleDistance() {
+		
+	}
+	
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @throws IllegalArgumentException if p1.length() is not equal to p2.length().
+	 */
+    @Override
+	public int distance(Permutation p1, Permutation p2) {
+		if (p1.length() != p2.length()) {
+			throw new IllegalArgumentException("Permutations must be the same length");
+		}
+        boolean[] used = new boolean[p1.length()];
+		for (int k = 0; k < used.length; k++) {
+			if (p1.get(k) == p2.get(k)) {
+				used[p1.get(k)] = true;
+			}
+		}
+		int i = 0;
+		for (i = 0; i < used.length; i++) {
+			if (!used[p1.get(i)]) { 
+				break; 
+			}  
+        }
+		
+		int[] invP1 = p1.getInverse();
+		int cycleCount = 0;
+		int iLast = i;
+		
+		while (i < used.length) {
+			int j = p1.get(i);
+			while (!used[j]) {
+				used[j] = true;
+				j = p2.get(i);
+				i = invP1[j];
+            }
+			cycleCount++;
+			for (i = iLast + 1; i < used.length; i++) {
+				if (!used[p1.get(i)]) {  
+					break; 
+				}
+			}
+			iLast = i;
+		}
+		return cycleCount;
+	}
+	
+	@Override
+	public int max(int length) {
+		return length >> 1;
+	}
+}

src/test/java/org/cicirello/permutations/distance/PermutationDistanceMaxTests.java

@@ -216,6 +216,16 @@ public void testReinsertionDistance() {
 		}
 	}
 
+	@Test
+	public void testCycleDistance() {
+		CycleDistance d = new CycleDistance();
+		for (int n = 0; n <= 7; n++) {
+			int expected = bruteForceComputeMax(d,n);
+			assertEquals(expected, d.max(n), "Failed on length: " + n);
+			assertEquals(1.0*expected, d.maxf(n), EPSILON, "Failed on length: " + n);
+		}
+	}
+	
 	//@Test // uncomment if we implement
 	public void testEditDistance() {
 		/* // Uncomment if we implement. 

src/test/java/org/cicirello/permutations/distance/PermutationDistanceNormTests.java

@@ -159,6 +159,14 @@ public void testReinsertionDistance() {
 		}
 	}
 
+	@Test
+	public void testCycleDistance() {
+		CycleDistance d = new CycleDistance();
+		for (int n = 0; n <= 7; n++) {
+			assertEquals(n<=1 ? 0.0 : 1.0, bruteForceComputeMax(d,n), EPSILON, "Failed on length: " + n);
+		}
+	}
+	
 	//@Test // uncomment if we implement
 	public void testEditDistance() {
 		/* // Uncomment if we implement. 

src/test/java/org/cicirello/permutations/distance/PermutationDistanceTests.java

@@ -799,6 +799,32 @@ public void testEditDistance() {
 		assertEquals(1.0, d.distancef(new Permutation(first), new Permutation(second)), EPSILON);
 	}
 
+	@Test
+	public void testCycleDistance() {
+		CycleDistance d = new CycleDistance();
+		identicalPermutations(d);
+		int[][] cases = {
+			{1, 0},
+			{1, 2, 0},
+			{1, 2, 3, 0},
+			{1, 0, 3, 2},
+			{1, 2, 3, 4, 5, 6, 7, 0},
+			{7, 1, 2, 3, 4, 5, 6, 0},
+			{7, 1, 5, 3, 4, 2, 6, 0},
+			{7, 6, 5, 4, 3, 2, 1, 0}
+		};
+		int[] expected = {1, 1, 1, 2, 1, 1, 2, 4};
+		for (int i = 0; i < expected.length; i++) {
+			Permutation p1 = new Permutation(cases[i].length, 0);
+			Permutation p2 = new Permutation(cases[i]);
+			assertEquals(expected[i], d.distance(p1, p2));
+			assertEquals(expected[i], d.distance(p2, p1));
+		}
+		IllegalArgumentException thrown = assertThrows( 
+			IllegalArgumentException.class,
+			() -> d.distance(new Permutation(1), new Permutation(2))
+		);
+	}
 
 	private void identicalPermutations(PermutationDistanceMeasurer d) {
 		for (int n = 0; n <= 10; n++) {