1 package net.bmahe.genetics4j.core.spec.chromosome;
2
3 import org.apache.commons.lang3.Validate;
4 import org.immutables.value.Value;
5
6 /**
7 * Specification for integer array chromosomes in evolutionary algorithms.
8 *
9 * <p>IntChromosomeSpec defines the blueprint for creating chromosomes that represent solutions as arrays of integer
10 * values. This is one of the most commonly used chromosome types, suitable for discrete optimization problems,
11 * permutation problems, and integer programming.
12 *
13 * <p>The specification includes:
14 * <ul>
15 * <li><strong>Size</strong>: The number of integer genes in the chromosome</li>
16 * <li><strong>Value range</strong>: Minimum and maximum bounds for each integer value</li>
17 * <li><strong>Validation</strong>: Automatic constraint checking for valid parameters</li>
18 * </ul>
19 *
20 * <p>Common use cases for integer chromosomes:
21 * <ul>
22 * <li><strong>Combinatorial optimization</strong>: Knapsack, bin packing, scheduling problems</li>
23 * <li><strong>Parameter optimization</strong>: Integer hyperparameters, configuration values</li>
24 * <li><strong>Permutation problems</strong>: Traveling salesman, job scheduling (with appropriate operators)</li>
25 * <li><strong>Graph problems</strong>: Node selection, path optimization, network design</li>
26 * <li><strong>Resource allocation</strong>: Assignment problems, load balancing</li>
27 * </ul>
28 *
29 * <p>The integer values in the chromosome are constrained to the specified range [minValue, maxValue], inclusive on
30 * both ends. The genetic operators (crossover and mutation) respect these constraints and ensure that offspring remain
31 * within valid bounds.
32 *
33 * <p>Example usage:
34 *
35 * <pre>{@code
36 * // Create specification for 10 integers in range [0, 100]
37 * IntChromosomeSpec spec = IntChromosomeSpec.of(10, 0, 100);
38 *
39 * // Create specification for permutation of 20 items (values 0-19)
40 * IntChromosomeSpec permutationSpec = IntChromosomeSpec.of(20, 0, 19);
41 *
42 * // Use in EA configuration
43 * EAConfiguration<Double> config = EAConfigurationBuilder.<Double>builder()
44 * .chromosomeSpecs(spec)
45 * .parentSelectionPolicy(Tournament.of(3))
46 * .build();
47 * }</pre>
48 *
49 * @see net.bmahe.genetics4j.core.chromosomes.IntChromosome
50 * @see net.bmahe.genetics4j.core.chromosomes.factory.IntChromosomeFactory
51 * @see ChromosomeSpec
52 */
53 @Value.Immutable
54 public abstract class IntChromosomeSpec implements ChromosomeSpec {
55
56 /**
57 * Returns the number of integer values in chromosomes created from this specification.
58 *
59 * @return the chromosome size, always positive
60 */
61 @Value.Parameter
62 public abstract int size();
63
64 /**
65 * Returns the minimum value (inclusive) for integer alleles in the chromosome.
66 *
67 * @return the minimum allowed integer value
68 */
69 @Value.Parameter
70 public abstract int minValue();
71
72 /**
73 * Returns the maximum value (inclusive) for integer alleles in the chromosome.
74 *
75 * @return the maximum allowed integer value
76 */
77 @Value.Parameter
78 public abstract int maxValue();
79
80 @Value.Check
81 protected void check() {
82 Validate.isTrue(size() > 0);
83 Validate.isTrue(minValue() <= maxValue());
84 }
85
86 public static class Builder extends ImmutableIntChromosomeSpec.Builder {
87 }
88
89 /**
90 * Creates a new integer chromosome specification with the given parameters.
91 *
92 * @param size the number of integer values in the chromosome, must be positive
93 * @param minValue the minimum value (inclusive) for each integer in the chromosome
94 * @param maxValue the maximum value (inclusive) for each integer in the chromosome
95 * @return a new IntChromosomeSpec instance with the specified parameters
96 * @throws IllegalArgumentException if size is not positive or if minValue > maxValue
97 */
98 public static IntChromosomeSpec of(final int size, final int minValue, final int maxValue) {
99 return ImmutableIntChromosomeSpec.of(size, minValue, maxValue);
100 }
101
102 }