NeatChromosomeAddConnection.java

package net.bmahe.genetics4j.neat.mutation.chromosome;

import java.util.ArrayList;

import java.util.Comparator;

import java.util.List;

import java.util.random.RandomGenerator;

import org.apache.commons.lang3.Validate;

import org.apache.logging.log4j.LogManager;

import org.apache.logging.log4j.Logger;

import net.bmahe.genetics4j.core.chromosomes.Chromosome;

import net.bmahe.genetics4j.core.mutation.chromosome.ChromosomeMutationHandler;

import net.bmahe.genetics4j.core.spec.chromosome.ChromosomeSpec;

import net.bmahe.genetics4j.core.spec.mutation.MutationPolicy;

import net.bmahe.genetics4j.neat.Connection;

import net.bmahe.genetics4j.neat.InnovationManager;

import net.bmahe.genetics4j.neat.chromosomes.NeatChromosome;

import net.bmahe.genetics4j.neat.spec.NeatChromosomeSpec;

import net.bmahe.genetics4j.neat.spec.mutation.AddConnection;

/**

 * Chromosome mutation handler that adds new connections to NEAT (NeuroEvolution of Augmenting Topologies) neural

 * networks.

 * 

 * <p>NeatChromosomeAddConnection implements the add-connection structural mutation for NEAT chromosomes, which

 * increases network connectivity by creating new weighted links between existing nodes. This mutation is essential for

 * NEAT's ability to explore different network topologies and discover optimal connectivity patterns.

 * 

 * <p>Add-connection mutation process:

 * <ol>

 * <li><strong>Node selection</strong>: Randomly select source and target nodes from all available nodes</li>

 * <li><strong>Validity checking</strong>: Ensure the connection doesn't violate network constraints</li>

 * <li><strong>Duplicate prevention</strong>: Verify the connection doesn't already exist</li>

 * <li><strong>Innovation assignment</strong>: Assign unique innovation number via InnovationManager</li>

 * <li><strong>Weight initialization</strong>: Set random weight within chromosome bounds</li>

 * <li><strong>Connection creation</strong>: Add enabled connection to the chromosome</li>

 * </ol>

 * 

 * <p>Connection constraints:

 * <ul>

 * <li><strong>No self-connections</strong>: Source and target nodes must be different</li>

 * <li><strong>No duplicate connections</strong>: Connection between same nodes cannot already exist</li>

 * <li><strong>Feed-forward topology</strong>: Output nodes cannot be sources, input nodes cannot be targets</li>

 * <li><strong>Valid node references</strong>: Both nodes must exist in the network</li>

 * </ul>

 * 

 * <p>Node selection strategy:

 * <ul>

 * <li><strong>Available nodes</strong>: All input, output, and hidden nodes are potential connection endpoints</li>

 * <li><strong>Dynamic range</strong>: Node range adapts to include any hidden nodes created by add-node mutations</li>

 * <li><strong>Uniform selection</strong>: All valid nodes have equal probability of being selected</li>

 * <li><strong>Constraint filtering</strong>: Invalid connections are rejected and no mutation occurs</li>

 * </ul>

 * 

 * <p>Common usage patterns:

 * 

 * <pre>{@code

 * // Create add-connection mutation handler

 * RandomGenerator randomGen = RandomGenerator.getDefault();

 * InnovationManager innovationManager = new InnovationManager();

 * NeatChromosomeAddConnection handler = new NeatChromosomeAddConnection(

 *     randomGen, innovationManager

 * );

 * 

 * // Check if handler can process mutation

 * AddConnection mutationPolicy = AddConnection.of(0.1);

 * NeatChromosomeSpec chromosomeSpec = NeatChromosomeSpec.of(3, 2, -1.0f, 1.0f);

 * boolean canHandle = handler.canHandle(mutationPolicy, chromosomeSpec);

 * 

 * // Apply mutation to chromosome

 * NeatChromosome originalChromosome = // ... existing chromosome

 * NeatChromosome mutatedChromosome = handler.mutate(mutationPolicy, originalChromosome);

 * 

 * // Result: chromosome may have one additional connection (if valid connection found)

 * }</pre>

 * 

 * <p>Integration with NEAT algorithm:

 * <ul>

 * <li><strong>Innovation tracking</strong>: Uses InnovationManager for consistent innovation number assignment</li>

 * <li><strong>Population consistency</strong>: Same connection types get same innovation numbers across population</li>

 * <li><strong>Genetic alignment</strong>: Innovation numbers enable proper crossover alignment</li>

 * <li><strong>Structural diversity</strong>: Increases topological diversity in the population</li>

 * </ul>

 * 

 * <p>Weight initialization:

 * <ul>

 * <li><strong>Random weights</strong>: New connections get random weights within chromosome bounds</li>

 * <li><strong>Uniform distribution</strong>: Weights uniformly distributed between min and max values</li>

 * <li><strong>Immediate activation</strong>: New connections are enabled and immediately affect network behavior</li>

 * <li><strong>Bounded values</strong>: Weights respect chromosome's min/max weight constraints</li>

 * </ul>

 * 

 * <p>Performance considerations:

 * <ul>

 * <li><strong>Efficient validation</strong>: Fast checks for connection existence and validity</li>

 * <li><strong>Innovation caching</strong>: Leverages InnovationManager's O(1) innovation lookup</li>

 * <li><strong>Memory efficiency</strong>: Minimal allocation during mutation</li>

 * <li><strong>Failed mutation handling</strong>: Gracefully handles cases where no valid connection can be added</li>

 * </ul>

 * 

 * @see AddConnection

 * @see NeatChromosome

 * @see InnovationManager

 * @see ChromosomeMutationHandler

 */

public class NeatChromosomeAddConnection implements ChromosomeMutationHandler<NeatChromosome> {

	private final RandomGenerator randomGenerator;

	private final InnovationManager innovationManager;

	/**

	 * Constructs a new add-connection mutation handler with the specified components.

	 * 

	 * <p>The random generator is used for node selection and weight initialization. The innovation manager provides

	 * unique innovation numbers for new connections, ensuring consistent tracking across the population.

	 * 

	 * @param _randomGenerator   random number generator for stochastic operations

	 * @param _innovationManager innovation manager for tracking structural changes

	 * @throws IllegalArgumentException if randomGenerator or innovationManager is null

	 */

	public NeatChromosomeAddConnection(final RandomGenerator _randomGenerator,

	/**

	 * Determines whether this handler can process the given mutation policy and chromosome specification.

	 * 

	 * <p>This handler specifically processes AddConnection mutations applied to NeatChromosomeSpec specifications,

	 * ensuring type compatibility for NEAT neural network connection addition.

	 * 

	 * @param mutationPolicy the mutation policy to check

	 * @param chromosome     the chromosome specification to check

	 * @return true if policy is AddConnection and chromosome is NeatChromosomeSpec, false otherwise

	 * @throws IllegalArgumentException if any parameter is null

	 */

	@Override

	public boolean canHandle(final MutationPolicy mutationPolicy, final ChromosomeSpec chromosome) {

	}

	/**

	 * Applies add-connection mutation to a NEAT chromosome.

	 * 

	 * <p>This method attempts to add a new connection between two randomly selected nodes in the neural network. The

	 * mutation may fail if no valid connection can be found (e.g., all possible connections already exist or violate

	 * network constraints).

	 * 

	 * <p>Mutation algorithm:

	 * <ol>

	 * <li>Determine the range of available nodes (inputs, outputs, and hidden nodes)</li>

	 * <li>Randomly select source and target nodes</li>

	 * <li>Validate the connection doesn't violate constraints</li>

	 * <li>If valid, create new connection with innovation number and random weight</li>

	 * <li>Add connection to chromosome and return modified chromosome</li>

	 * <li>If invalid, return chromosome unchanged</li>

	 * </ol>

	 * 

	 * @param mutationPolicy the add-connection mutation policy

	 * @param chromosome     the NEAT chromosome to mutate

	 * @return a new chromosome with potentially one additional connection

	 * @throws IllegalArgumentException if policy is not AddConnection or chromosome is not NeatChromosome

	 */

	@Override

	public NeatChromosome mutate(final MutationPolicy mutationPolicy, final Chromosome chromosome) {

		}

	}

}

Mutations

1.1
Location : lambda$mutate$0
Killed by : none removed call to net/bmahe/genetics4j/neat/Connection::fromNodeIndex → SURVIVED Covering tests

2.2
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] removed call to java/util/stream/Stream::map → KILLED

3.3
Location : lambda$mutate$0
Killed by : none removed call to net/bmahe/genetics4j/neat/Connection::toNodeIndex → SURVIVED Covering tests

4.4
Location : lambda$mutate$0
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] removed call to java/lang/Integer::valueOf → KILLED

5.5
Location : lambda$mutate$0
Killed by : none replaced Integer return value with 0 for net/bmahe/genetics4j/neat/mutation/chromosome/NeatChromosomeAddConnection::lambda$mutate$0 → SURVIVED Covering tests

6.6
Location : lambda$mutate$0
Killed by : none removed call to java/lang/Math::max → SURVIVED Covering tests

7.7
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] replaced call to java/util/stream/Stream::map with receiver → KILLED

8.8
Location : lambda$mutate$0
Killed by : none replaced call to java/lang/Math::max with argument → SURVIVED Covering tests

3.3
Location : mutate
Killed by : none Substituted 0 with 1 → SURVIVED Covering tests

1.1
Location : mutate
Killed by : none removed call to java/lang/Integer::intValue → SURVIVED Covering tests

2.2
Location : mutate
Killed by : none replaced call to java/util/Optional::orElse with argument → SURVIVED Covering tests

3.3
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] removed call to java/util/Optional::orElse → KILLED

4.4
Location : mutate
Killed by : none removed call to java/lang/Integer::valueOf → SURVIVED Covering tests

1.1
Location : mutate
Killed by : none removed call to java/lang/Math::max → SURVIVED Covering tests

2.2
Location : mutate
Killed by : none replaced call to java/lang/Math::max with argument → SURVIVED Covering tests

1.1
Location : mutate
Killed by : none removed call to net/bmahe/genetics4j/neat/chromosomes/NeatChromosome::getNumInputs → SURVIVED Covering tests

2.2
Location : mutate
Killed by : none Replaced integer addition with subtraction → SURVIVED Covering tests

3.3
Location : mutate
Killed by : none Substituted 1 with 0 → SURVIVED Covering tests

4.4
Location : mutate
Killed by : none Replaced integer subtraction with addition → SURVIVED Covering tests

5.5
Location : mutate
Killed by : none removed call to net/bmahe/genetics4j/neat/chromosomes/NeatChromosome::getNumOutputs → SURVIVED Covering tests

1.1
Location : mutate
Killed by : none Replaced integer addition with subtraction → SURVIVED Covering tests

2.2
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] removed call to java/util/random/RandomGenerator::nextInt → KILLED

3.3
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] replaced call to java/util/random/RandomGenerator::nextInt with argument → KILLED

4.4
Location : mutate
Killed by : none Substituted 1 with 0 → SURVIVED Covering tests

2.2
Location : mutate
Killed by : none Replaced integer addition with subtraction → SURVIVED Covering tests

3.3
Location : mutate
Killed by : none Substituted 1 with 0 → SURVIVED Covering tests

4.4
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] replaced call to java/util/random/RandomGenerator::nextInt with argument → KILLED

2.2
Location : mutate
Killed by : none removed conditional - replaced comparison check with true → SURVIVED Covering tests

3.3
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] negated conditional → KILLED

4.4
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] removed conditional - replaced comparison check with false → KILLED

5.5
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] Substituted 0 with 1 → KILLED

6.6
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] removed conditional - replaced comparison check with false → KILLED

7.7
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] changed conditional boundary → KILLED

8.8
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] Replaced integer addition with subtraction → KILLED

9.9
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] Substituted 1 with 0 → KILLED

10.10
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed conditional - replaced comparison check with true → KILLED

11.11
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] negated conditional → KILLED

1.1
Location : mutate
Killed by : none removed conditional - replaced comparison check with false → SURVIVED Covering tests

2.2
Location : mutate
Killed by : none changed conditional boundary → SURVIVED Covering tests

3.3
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] Substituted 0 with 1 → KILLED

4.4
Location : mutate
Killed by : none Substituted 1 with 0 → SURVIVED Covering tests

5.5
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed conditional - replaced comparison check with true → KILLED

6.6
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] negated conditional → KILLED

1.1
Location : mutate
Killed by : none removed conditional - replaced equality check with true → SURVIVED Covering tests

2.2
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] negated conditional → KILLED

3.3
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed conditional - replaced equality check with false → KILLED

4.4
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromAndToAreSame()] negated conditional → KILLED

5.5
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromOutput()] removed conditional - replaced equality check with true → KILLED

6.6
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionFromAndToAreSame()] removed conditional - replaced equality check with true → KILLED

7.7
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] negated conditional → KILLED

8.8
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed conditional - replaced equality check with false → KILLED

9.9
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed conditional - replaced equality check with false → KILLED

10.10
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutateConnectionExist()] removed conditional - replaced equality check with true → KILLED

11.11
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] negated conditional → KILLED

12.12
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed conditional - replaced equality check with false → KILLED

1.1
Location : mutate
Killed by : none replaced call to net/bmahe/genetics4j/neat/InnovationManager::computeNewId with argument → SURVIVED Covering tests

2.2
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed call to net/bmahe/genetics4j/neat/InnovationManager::computeNewId → KILLED

2.2
Location : mutate
Killed by : none Substituted 1 with 0 → SURVIVED Covering tests

3.3
Location : mutate
Killed by : net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest.[engine:junit-jupiter]/[class:net.bmahe.genetics4j.neat.mutation.chromosome.NeatChromosomeAddConnectionTest]/[method:mutate()] removed call to net/bmahe/genetics4j/neat/Connection$Builder::weight → KILLED

4.4
Location : mutate
Killed by : none removed call to java/util/random/RandomGenerator::nextFloat → SURVIVED Covering tests

5.5
Location : mutate
Killed by : none replaced call to java/util/random/RandomGenerator::nextFloat with argument → SURVIVED Covering tests