saealib.Mutation

class saealib.Mutation

Bases: ABC

Base class for mutation operators.

prob

Individual-level mutation probability. Rows whose gate draw is greater than or equal to prob are returned unchanged.

Type:

float

prob_var

Per-variable mutation probability. None means the effective value is resolved at call time as min(0.5, 1 / dim).

Type:

float or None

Methods

__init__
contract	Return the mutation contract; mutate_range is required for every mutation.
mutate	Execute mutation for one candidate.
mutate_batch	Execute mutation on a batch of candidates at once.
post_mutation	Post-mutation lifecycle hook; override to inject custom processing.
post_mutation_batch	Run the post-mutation lifecycle hook for a batch.
with_post	Return a copy of this operator with fn appended to the hook.

Method Details

Mutation.__init__()

Mutation.contract()

Return the mutation contract; mutate_range is required for every mutation.

Return type:

ComponentContract

Mutation.mutate(p, mutate_range, rng=Generator(PCG64) at 0x7F7917914740)

Execute mutation for one candidate.

This method is derived from mutate_batch() by passing a single-row batch.

Notes

Overriding only this method (not mutate_batch()) has no effect under GA’s default variation_execution="batch": the batch path calls mutate_batch() directly and never calls mutate(). Such an override only takes effect under variation_execution="sequential". To customize behavior under both modes, override mutate_batch().

Parameters:

• p (np.ndarray) – Parent individual. shape = (dim,)

• mutate_range (tuple) – Tuple of (lower_bound, upper_bound) for mutation.

• rng (np.random.Generator, optional) – Random number generator, by default np.random.default_rng()

Returns:

Mutated individual. shape = (dim,). The result is always float64 because mutate_batch() casts its input internally; the result does not preserve the input’s dtype.

Return type:

np.ndarray

abstractmethod Mutation.mutate_batch(candidates_batch, mutate_range, rng=Generator(PCG64) at 0x7F7917914AC0)

Execute mutation on a batch of candidates at once.

This is the required primitive that every concrete mutation class must implement directly. Each implementation self-gates prob internally; see Notes for why this differs from Crossover.crossover_batch.

Parameters:

• candidates_batch (np.ndarray) – Batch of candidate individuals. shape = (n, dim)

• mutate_range (tuple) – Tuple of (lower_bound, upper_bound) for mutation.

• rng (np.random.Generator, optional) – Random number generator, by default np.random.default_rng()

Returns:

Mutated individuals. shape = (n, dim)

Return type:

np.ndarray

Notes

Unlike Crossover.crossover_batch, prob gating is NOT the caller’s responsibility here — it must be applied by the overriding implementation itself, per row. Implementations must draw one gate value per row and leave ungated rows unchanged, rather than expecting the caller to pre-filter candidates_batch. This is a deliberate asymmetry with Crossover.crossover_batch.

Mutation.post_mutation(offspring, mutate_range, rng, ctx=None)

Post-mutation lifecycle hook; override to inject custom processing.

Parameters:

• offspring (np.ndarray) – Individual after mutation. shape = (dim,)

• mutate_range (tuple) – Tuple of (lower_bound, upper_bound) used for mutation.

• rng (np.random.Generator) – Random number generator.

• ctx (ExecutionContext or None, optional) – Current optimization context.

Returns:

Processed individual. shape = (dim,)

Return type:

np.ndarray

Mutation.post_mutation_batch(offspring_batch, mutate_range, rng, ctx=None)

Run the post-mutation lifecycle hook for a batch.

The default implementation calls post_mutation() once per individual, in order. Override this method to provide genuinely vectorized post-processing.

Parameters:

• offspring_batch (np.ndarray) – Offspring produced by mutation. shape = (n, dim)

• mutate_range (tuple) – Tuple of (lower_bound, upper_bound) used for mutation.

• rng (np.random.Generator) – Random number generator.

• ctx (ExecutionContext or None, optional) – Current optimization context.

Returns:

Processed offspring. shape = (n, dim)

Return type:

np.ndarray

Notes

with_post() reassigns only the instance’s post_mutation() hook. A subclass override of this method is responsible for composing that hook itself. If the override does not call self.post_mutation, a hook installed with with_post() will not run in GA batch mode. It still runs in GA sequential mode, which calls post_mutation() directly.

Mutation.with_post(fn)

Return a copy of this operator with fn appended to the hook.

Parameters:

fn (callable) – fn(offspring, mutate_range, rng, ctx) -> np.ndarray

Returns:

Shallow copy with the hook registered.

Return type:

Mutation