Module org.cicirello.chips_n_salsa
Package org.cicirello.search.operators

Interface MutationIterator

public interface MutationIterator
Defines an interface for iterating over all of the mutants (i.e., neighbors) of a candidate solution to a problem. MutationIterators are used in combination with IterableMutationOperator objects.

Example 1: Here is an example of its use. In this first example, we iterate over all neighbors. At the completion of this block, the state of x will be as of the most recent call to setSavepoint() or its original state if that method was never called. 


 T x = some object of type T.
 IterableMutationOperator<T> mutation = ....
 MutationIterator iter = mutation.iterator(x);
 while (iter.hasNext()) {
     iter.nextMutant();
     if (new state of x is one we'd like to be able to revert to) {
          iter.setSavepoint();
     }
 }
 // This next statement rolls x back to the last savepoint.
 iter.rollback();

Example 2: In this next example, we iterate over neighbors only until we find one we like. 


 T x = some object of type T.
 IterableMutationOperator<T> mutation = ....
 MutationIterator iter = mutation.iterator(x);
 boolean foundOneToKeep = false;
 while (iter.hasNext()) {
     iter.nextMutant();
     if (new state of x is one we'd like to keep) {
          foundOneToKeep = true;
          break;
     }
 }
 if (!foundOneToKeep) iter.rollback();

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    hasNext()
    Checks whether there are any additional neighbors of the candidate solution.
    void
    nextMutant()
    Mutates the candidate solution into its next neighbor.
    void
    rollback()
    Reverts the candidate solution to its state as of the most recent call to the setSavepoint() method, or its original state if that method has not been called.
    void
    setSavepoint()
    Records internally within the MutationIterator the current neighbor/mutant, enabling reverting back to this neighbor when the rollback() method is called.

  • Method Details

    • hasNext

      boolean hasNext()
      Checks whether there are any additional neighbors of the candidate solution.
      Returns:
      true if there are additional neighbors that can be iterated over via the nextMutant() method, provided the rollback() method has not been called.

    • nextMutant

      void nextMutant()
      Mutates the candidate solution into its next neighbor.
      Throws:
      IllegalStateException - if there are no additional neighbors to iterate over or if the rollback() method was called. You should use the hasNext() method to check first.

    • setSavepoint

      void setSavepoint()
      Records internally within the MutationIterator the current neighbor/mutant, enabling reverting back to this neighbor when the rollback() method is called. This does not affect the order of neighbors returned by future calls to the nextMutant() method.

    • rollback

      void rollback()
      Reverts the candidate solution to its state as of the most recent call to the setSavepoint() method, or its original state if that method has not been called. Upon calling the rollback method, all future calls to the nextMutant() method will throw an IllegalStateException. If rollback is not called, then the candidate solution's state will be as of the most recent call to nextMutant().