saealib.MutationUniform#

class saealib.MutationUniform(prob=1.0, *, prob_var=None)[source]#

Bases: Mutation

Uniform mutation operator.

Parameters:

prob (float)
prob_var (float | None)

prob#

Individual-level mutation probability.

Type:: float

prob_var#

Per-variable mutation probability. Defaults to min(0.5, 1/dim) when None.

Type:: float or None

Methods

`__init__`	Initialize uniform mutation operator.
`contract`	Return the real-valued uniform mutation contract.
`mutate`	Execute mutation for one candidate.
`mutate_batch`	Execute uniform 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

MutationUniform.__init__(prob=1.0, *, prob_var=None)[source]#

Initialize uniform mutation operator.

Parameters:

prob (float, optional) – Individual-level mutation probability, by default 1.0.
prob_var (float or None, optional) – Per-variable mutation probability. None uses min(0.5, 1/dim).

MutationUniform.contract()[source]#

Return the real-valued uniform mutation contract.

Return type:: ComponentContract

MutationUniform.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

MutationUniform.mutate_batch(candidates_batch, mutate_range, rng=Generator(PCG64) at 0x7F79179151C0)[source]#

Execute uniform mutation on a batch of candidates at once.

This is the primary uniform mutation implementation. An individual-level prob gate (one Bernoulli draw per row via rng.random(n) < self.prob) selects which rows are touched at all; a per-dimension prob_var gate is then drawn only for the selected rows, and only dimensions passing that gate are replaced with a value drawn Uniform(lb[i], ub[i]). The replacement is drawn only for the positions var_gate actually selects (via boolean fancy-indexing into the broadcast lb/ub arrays, then Generator.uniform’s array-valued low/high form with no explicit size), rather than for every (row, dim) position unconditionally – this avoids drawing (and validating the range of) a replacement for a dimension that var_gate will discard anyway, which matters when that dimension is unbounded (see Notes). Rows that fail the individual-level gate are returned byte-identical to the input; dimensions failing the per-dimension gate on a selected row keep their original value exactly. If no row passes the individual-level gate (gate.sum() == 0), no further random draws happen at all and the input is returned unchanged, mirroring PymooMutation.mutate_batch’s empty-gate skip.

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

For multiple rows, a loop of separate single-row mutate_batch calls (equivalently, separate mutate() calls) does not reproduce the same per-row results as one batched call with the same seeded rng. Separate calls interleave each row’s individual gate, full per-dimension gate array, and replacement draws before moving to the next row. The number of replacements is data-dependent (dim + m post-individual-gate draws, where m dimensions pass the variable gate). One batched call instead draws all individual gates, then a full (k, dim) variable-gate array for the k selected rows, followed by one replacement draw sized to all selected positions. NumPy vectorized calls cannot conditionally skip drawing per element within a single call, so the draw count and interleaving generally diverge. Only the statistical and distributional semantics are guaranteed to match.

The output is always float64 (via the internal dtype=float cast), regardless of the input array’s dtype.

MutationUniform.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

MutationUniform.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.

MutationUniform.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