Genetic Algorithm (NSGA-III)

CONFETTI’s own NSGA-III genetic algorithm.

class confetti.algorithm.BinaryRandomSampling(seed: int | None = None)

Bases: Sampling

Generate an initial population of binary decision vectors.

Each variable in each individual is drawn independently from a Bernoulli(0.5) distribution.

Parameters:

seed (int or None, default=None) – Seed for the internal numpy.random.Generator.

class confetti.algorithm.BitflipMutation(prob: float = 1.0, prob_var: float | None = None)

Bases: Mutation

Flip individual bits of binary decision vectors.

Each bit in every selected individual is independently flipped with probability prob_var.

There are two probability knobs:

• prob — population-level probability that an individual is mutated at all. Handled by the inherited Mutation.do() method.

• prob_var — per-variable probability that each bit is flipped inside _do(). When None, defaults to min(0.5, 1 / problem.n_var).

Parameters:

• prob (float, default=1.0) – Probability that an individual is selected for mutation.

• prob_var (float or None, default=None) – Per-bit flip probability. When None, the default min(0.5, 1 / problem.n_var) is used.

class confetti.algorithm.Crossover(prob: float = 0.9, n_parents: int = 2, n_offsprings: int = 2)

Bases: ABC

Base class for crossover operators with per-mating probability gating.

Parameters:

• prob (float) – Probability that a given mating actually performs crossover.

• n_parents (int) – Number of parents per mating.

• n_offsprings (int) – Number of offspring produced per mating.

do(problem: Any, X: ndarray, parents: ndarray, rng: Generator) → ndarray

Perform crossover on selected parent pairs.

Parameters:

• problem (Problem) – The optimization problem.

• X (np.ndarray) – Decision-variable matrix of shape (n, n_var).

• parents (np.ndarray) – Index array of shape (n_matings, 2) selecting parent rows.

• rng (numpy.random.Generator) – Random number generator for probability sampling.

Returns:

Offspring matrix of shape (n_offsprings * n_matings, n_var).

Return type:

np.ndarray

class confetti.algorithm.Mutation(prob: float = 1.0, prob_var: float | None = None)

Bases: ABC

Base class for mutation operators with per-individual probability gating.

The do method decides which individuals are mutated (controlled by prob). The subclass _do applies the actual mutation to the selected rows.

Parameters:

• prob (float) – Probability that any given individual is passed to _do.

• prob_var (float or None) – Per-variable mutation probability used by get_prob_var(). When None, defaults to min(0.5, 1 / problem.n_var).

do(problem: Any, X: ndarray, rng: Generator) → ndarray

Mutate a population with per-individual probability gating.

Parameters:

• problem (Problem) – The optimization problem.

• X (np.ndarray) – Decision-variable matrix of shape (n, n_var).

• rng (numpy.random.Generator) – Random number generator for probability sampling.

Returns:

Mutated population, same shape as X.

Return type:

np.ndarray

get_prob_var(problem: Any) → float

Return the per-variable mutation probability.

When prob_var was not set at construction, defaults to min(0.5, 1 / problem.n_var).

Parameters:

problem (object) – Must expose an n_var attribute.

Returns:

Per-variable mutation probability.

Return type:

float

class confetti.algorithm.NSGA3(pop_size: int, ref_dirs: ndarray, sampling: Sampling, crossover: Crossover, mutation: Mutation)

Bases: object

NSGA-III: Non-dominated Sorting Genetic Algorithm III.

Parameters:

• pop_size (int) – Population size (number of individuals per generation).

• ref_dirs (np.ndarray) – Reference directions, shape (n_ref, n_obj).

• sampling (Sampling) – Population initialization operator.

• crossover (Crossover) – Crossover operator.

• mutation (Mutation) – Mutation operator.

run(problem: Any, n_gen: int, seed: int | None = None) → Result

Execute the NSGA-III optimisation loop.

Parameters:

• problem (Problem) – The multi-objective problem to solve.

• n_gen (int) – Number of generations to run.

• seed (int or None) – Random seed for reproducibility.

Returns:

The optimisation result with feasible non-dominated solutions.

Return type:

Result

class confetti.algorithm.Problem(n_var: int, n_obj: int, n_ieq_constr: int = 0)

Bases: ABC

Base class for multi-objective optimization problems.

Subclasses must implement _evaluate which populates an output dictionary with objective values ("F") and, optionally, inequality-constraint values ("G").

Parameters:

• n_var (int) – Number of decision variables.

• n_obj (int) – Number of objectives.

• n_ieq_constr (int) – Number of inequality constraints (G ≤ 0 convention).

evaluate(X: ndarray) → tuple[ndarray, ndarray]

Evaluate a batch of solutions.

Calls the user-defined _evaluate and normalises the output shapes so downstream code can rely on consistent array layouts.

Parameters:

X (np.ndarray) – Decision-variable matrix of shape (n, n_var).

Returns:

(F, G) where F has shape (n, n_obj) and G has shape (n, n_ieq_constr).

Return type:

tuple[np.ndarray, np.ndarray]

class confetti.algorithm.Result(X: ndarray | None, F: ndarray | None, G: ndarray | None, algorithm: NSGA3)

Bases: object

Outcome of a multi-objective optimisation run.

``X``

Decision variables of the feasible non-dominated front, shape (n_solutions, n_var). None when no feasible solution was found.

Type:

np.ndarray or None

``F``

Objective values, shape (n_solutions, n_obj).

Type:

np.ndarray or None

``G``

Inequality-constraint values, shape (n_solutions, n_ieq_constr).

Type:

np.ndarray or None

``algorithm``

The algorithm instance (carries n_gen and other state).

Type:

NSGA3

F: ndarray | None

G: ndarray | None

X: ndarray | None

algorithm: NSGA3

class confetti.algorithm.Sampling

Bases: ABC

Base class for population initialization operators.

Subclasses must implement _do which returns a raw ndarray of shape (n_samples, problem.n_var).

do(problem: Any, n_samples: int) → ndarray

Generate an initial population.

Parameters:

• problem (Problem) – The optimization problem (must expose n_var).

• n_samples (int) – Number of individuals to generate.

Returns:

Population matrix of shape (n_samples, problem.n_var).

Return type:

np.ndarray

class confetti.algorithm.TwoPointCrossover(**kwargs)

Bases: Crossover

Binary two-point crossover.

For each mating, two split points i and j (0 < i <= j < n) are chosen uniformly at random. Offspring are constructed by swapping the middle segment [i, j) between the two parents:

• Offspring 0: parent_0[:i]  | parent_1[i:j] | parent_0[j:]

• Offspring 1: parent_1[:i]  | parent_0[i:j] | parent_1[j:]

Parameters:

prob (float, default=0.9) – Per-mating probability that crossover is applied. Matings that do not undergo crossover copy parents unchanged. Handled by the inherited Crossover.do() method.

confetti.algorithm.das_dennis(n_dim: int, n_partitions: int) → ndarray

Generate Das-Dennis reference directions on an (n_dim - 1)-simplex.

Produces a set of uniformly spaced weight vectors whose components sum to one and are all non-negative. The number of points equals C(n_dim + n_partitions - 1, n_partitions) (stars-and-bars).

Parameters:

• n_dim (int) – Number of objectives (dimensionality of each reference direction). Must be >= 1.

• n_partitions (int) – Number of equal divisions along each axis. Must be >= 0.

Returns:

Array of shape (n_points, n_dim) with dtype=float64, lexicographically sorted by row.

Return type:

np.ndarray

Raises:

ValueError – If n_dim < 1 or n_partitions < 0.

References

Das, I. & Dennis, J.E. (1998). Normal-Boundary Intersection: A New Method for Generating the Pareto Surface in Nonlinear Multicriteria Optimization Problems. SIAM Journal on Optimization, 8(3), 631-657.

confetti.algorithm.minimize(problem: Any, algorithm: NSGA3, termination: Any, seed: int | None = None, verbose: bool = False) → Result

Run an NSGA-III optimisation.

Parameters:

• problem (Problem) – The multi-objective problem.

• algorithm (NSGA3) – A configured NSGA-III instance.

• termination (int or object) – Number of generations, or an object with an n_max_gen attribute.

• seed (int or None) – Random seed.

• verbose (bool) – Unused (kept for API compatibility).

Returns:

The optimisation result.

Return type:

Result

NSGA-III multi-objective evolutionary algorithm.

class confetti.algorithm._nsga3.NSGA3(pop_size: int, ref_dirs: ndarray, sampling: Sampling, crossover: Crossover, mutation: Mutation)

Bases: object

NSGA-III: Non-dominated Sorting Genetic Algorithm III.

Parameters:

• pop_size (int) – Population size (number of individuals per generation).

• ref_dirs (np.ndarray) – Reference directions, shape (n_ref, n_obj).

• sampling (Sampling) – Population initialization operator.

• crossover (Crossover) – Crossover operator.

• mutation (Mutation) – Mutation operator.

n_gen: int

run(problem: Any, n_gen: int, seed: int | None = None) → Result

Execute the NSGA-III optimisation loop.

Parameters:

• problem (Problem) – The multi-objective problem to solve.

• n_gen (int) – Number of generations to run.

• seed (int or None) – Random seed for reproducibility.

Returns:

The optimisation result with feasible non-dominated solutions.

Return type:

Result

class confetti.algorithm._nsga3.Result(X: ndarray | None, F: ndarray | None, G: ndarray | None, algorithm: NSGA3)

Bases: object

Outcome of a multi-objective optimisation run.

``X``

Decision variables of the feasible non-dominated front, shape (n_solutions, n_var). None when no feasible solution was found.

Type:

np.ndarray or None

``F``

Objective values, shape (n_solutions, n_obj).

Type:

np.ndarray or None

``G``

Inequality-constraint values, shape (n_solutions, n_ieq_constr).

Type:

np.ndarray or None

``algorithm``

The algorithm instance (carries n_gen and other state).

Type:

NSGA3

F: ndarray | None

G: ndarray | None

X: ndarray | None

algorithm: NSGA3

confetti.algorithm._nsga3.minimize(problem: Any, algorithm: NSGA3, termination: Any, seed: int | None = None, verbose: bool = False) → Result

Run an NSGA-III optimisation.

Parameters:

• problem (Problem) – The multi-objective problem.

• algorithm (NSGA3) – A configured NSGA-III instance.

• termination (int or object) – Number of generations, or an object with an n_max_gen attribute.

• seed (int or None) – Random seed.

• verbose (bool) – Unused (kept for API compatibility).

Returns:

The optimisation result.

Return type:

Result

Abstract base class for optimization problems.

class confetti.algorithm._problem.Problem(n_var: int, n_obj: int, n_ieq_constr: int = 0)

Bases: ABC

Base class for multi-objective optimization problems.

Subclasses must implement _evaluate which populates an output dictionary with objective values ("F") and, optionally, inequality-constraint values ("G").

Parameters:

• n_var (int) – Number of decision variables.

• n_obj (int) – Number of objectives.

• n_ieq_constr (int) – Number of inequality constraints (G ≤ 0 convention).

evaluate(X: ndarray) → tuple[ndarray, ndarray]

Evaluate a batch of solutions.

Calls the user-defined _evaluate and normalises the output shapes so downstream code can rely on consistent array layouts.

Parameters:

X (np.ndarray) – Decision-variable matrix of shape (n, n_var).

Returns:

(F, G) where F has shape (n, n_obj) and G has shape (n, n_ieq_constr).

Return type:

tuple[np.ndarray, np.ndarray]

Abstract base classes for genetic algorithm operators.

class confetti.algorithm._operators.Crossover(prob: float = 0.9, n_parents: int = 2, n_offsprings: int = 2)

Bases: ABC

Base class for crossover operators with per-mating probability gating.

Parameters:

• prob (float) – Probability that a given mating actually performs crossover.

• n_parents (int) – Number of parents per mating.

• n_offsprings (int) – Number of offspring produced per mating.

do(problem: Any, X: ndarray, parents: ndarray, rng: Generator) → ndarray

Perform crossover on selected parent pairs.

Parameters:

• problem (Problem) – The optimization problem.

• X (np.ndarray) – Decision-variable matrix of shape (n, n_var).

• parents (np.ndarray) – Index array of shape (n_matings, 2) selecting parent rows.

• rng (numpy.random.Generator) – Random number generator for probability sampling.

Returns:

Offspring matrix of shape (n_offsprings * n_matings, n_var).

Return type:

np.ndarray

class confetti.algorithm._operators.Mutation(prob: float = 1.0, prob_var: float | None = None)

Bases: ABC

Base class for mutation operators with per-individual probability gating.

The do method decides which individuals are mutated (controlled by prob). The subclass _do applies the actual mutation to the selected rows.

Parameters:

• prob (float) – Probability that any given individual is passed to _do.

• prob_var (float or None) – Per-variable mutation probability used by get_prob_var(). When None, defaults to min(0.5, 1 / problem.n_var).

do(problem: Any, X: ndarray, rng: Generator) → ndarray

Mutate a population with per-individual probability gating.

Parameters:

• problem (Problem) – The optimization problem.

• X (np.ndarray) – Decision-variable matrix of shape (n, n_var).

• rng (numpy.random.Generator) – Random number generator for probability sampling.

Returns:

Mutated population, same shape as X.

Return type:

np.ndarray

get_prob_var(problem: Any) → float

Return the per-variable mutation probability.

When prob_var was not set at construction, defaults to min(0.5, 1 / problem.n_var).

Parameters:

problem (object) – Must expose an n_var attribute.

Returns:

Per-variable mutation probability.

Return type:

float

class confetti.algorithm._operators.Sampling

Bases: ABC

Base class for population initialization operators.

Subclasses must implement _do which returns a raw ndarray of shape (n_samples, problem.n_var).

do(problem: Any, n_samples: int) → ndarray

Generate an initial population.

Parameters:

• problem (Problem) – The optimization problem (must expose n_var).

• n_samples (int) – Number of individuals to generate.

Returns:

Population matrix of shape (n_samples, problem.n_var).

Return type:

np.ndarray

Binary random sampling operator for CONFETTI’s genetic algorithm.

class confetti.algorithm.sampling.BinaryRandomSampling(seed: int | None = None)

Bases: Sampling

Generate an initial population of binary decision vectors.

Each variable in each individual is drawn independently from a Bernoulli(0.5) distribution.

Parameters:

seed (int or None, default=None) – Seed for the internal numpy.random.Generator.

Bitflip mutation operator for CONFETTI’s genetic algorithm.

class confetti.algorithm.mutation.BitflipMutation(prob: float = 1.0, prob_var: float | None = None)

Bases: Mutation

Flip individual bits of binary decision vectors.

Each bit in every selected individual is independently flipped with probability prob_var.

There are two probability knobs:

• prob — population-level probability that an individual is mutated at all. Handled by the inherited Mutation.do() method.

• prob_var — per-variable probability that each bit is flipped inside _do(). When None, defaults to min(0.5, 1 / problem.n_var).

Parameters:

• prob (float, default=1.0) – Probability that an individual is selected for mutation.

• prob_var (float or None, default=None) – Per-bit flip probability. When None, the default min(0.5, 1 / problem.n_var) is used.

Two-point crossover operator for CONFETTI’s genetic algorithm.

class confetti.algorithm.crossover.TwoPointCrossover(**kwargs)

Bases: Crossover

Binary two-point crossover.

For each mating, two split points i and j (0 < i <= j < n) are chosen uniformly at random. Offspring are constructed by swapping the middle segment [i, j) between the two parents:

• Offspring 0: parent_0[:i]  | parent_1[i:j] | parent_0[j:]

• Offspring 1: parent_1[:i]  | parent_0[i:j] | parent_1[j:]

Parameters:

prob (float, default=0.9) – Per-mating probability that crossover is applied. Matings that do not undergo crossover copy parents unchanged. Handled by the inherited Crossover.do() method.

Das-Dennis reference directions for NSGA-III.

confetti.algorithm.reference_directions.das_dennis(n_dim: int, n_partitions: int) → ndarray

Generate Das-Dennis reference directions on an (n_dim - 1)-simplex.

Produces a set of uniformly spaced weight vectors whose components sum to one and are all non-negative. The number of points equals C(n_dim + n_partitions - 1, n_partitions) (stars-and-bars).

Parameters:

• n_dim (int) – Number of objectives (dimensionality of each reference direction). Must be >= 1.

• n_partitions (int) – Number of equal divisions along each axis. Must be >= 0.

Returns:

Array of shape (n_points, n_dim) with dtype=float64, lexicographically sorted by row.

Return type:

np.ndarray

Raises:

ValueError – If n_dim < 1 or n_partitions < 0.

References

Das, I. & Dennis, J.E. (1998). Normal-Boundary Intersection: A New Method for Generating the Pareto Surface in Nonlinear Multicriteria Optimization Problems. SIAM Journal on Optimization, 8(3), 631-657.