1 package net.bmahe.genetics4j.core.mutation;
2
3 import net.bmahe.genetics4j.core.Genotype;
4
5 /**
6 * Functional interface for applying mutation operations to genotypes in evolutionary algorithms.
7 *
8 * <p>Mutation is a crucial genetic operator that introduces variation into the population by making small random
9 * changes to individual genotypes. This helps maintain genetic diversity and enables the exploration of new areas in
10 * the solution space.
11 *
12 * <p>The mutator operates on the genotype level, potentially modifying one or more chromosomes within the genotype
13 * according to the specific mutation strategy being applied.
14 *
15 * <p>Common mutation strategies include:
16 * <ul>
17 * <li><strong>Random mutation</strong>: Randomly change allele values with a given probability</li>
18 * <li><strong>Creep mutation</strong>: Make small incremental changes to numeric values</li>
19 * <li><strong>Swap mutation</strong>: Exchange positions of two alleles (useful for permutations)</li>
20 * <li><strong>Partial mutation</strong>: Apply mutation to only a subset of chromosomes</li>
21 * </ul>
22 *
23 * <p>Implementations should be:
24 * <ul>
25 * <li><strong>Stateless</strong>: The same input should produce consistent probabilistic behavior</li>
26 * <li><strong>Thread-safe</strong>: May be called concurrently during parallel evolution</li>
27 * <li><strong>Preserve structure</strong>: Maintain genotype integrity and constraints</li>
28 * </ul>
29 *
30 * @see net.bmahe.genetics4j.core.spec.mutation.MutationPolicy
31 * @see net.bmahe.genetics4j.core.mutation.MutationPolicyHandler
32 * @see Genotype
33 */
34 @FunctionalInterface
35 public interface Mutator {
36
37 /**
38 * Applies mutation to the given genotype and returns a new mutated genotype.
39 *
40 * <p>The original genotype should not be modified; instead, a new genotype with the mutations applied should be
41 * returned. The specific mutation behavior depends on the implementation and the mutation policy being used.
42 *
43 * <p>Mutation may affect:
44 * <ul>
45 * <li>Individual alleles within chromosomes (bit flips, value changes)</li>
46 * <li>Chromosome structure (for variable-length representations)</li>
47 * <li>Multiple chromosomes simultaneously</li>
48 * </ul>
49 *
50 * @param generation the current generation
51 * @param original the genotype to mutate, must not be null
52 * @return a new genotype with mutations applied, never null
53 * @throws IllegalArgumentException if original genotype is null or invalid
54 * @throws RuntimeException if mutation fails due to constraint violations
55 */
56 Genotype mutate(long generation, Genotype original);
57 }