saealib.MutationCategorical

class saealib.MutationCategorical(prob=1.0, *, prob_var=None)

ベースクラス: _MutationDiscreteUniform

Uniform categorical mutation.

Replaces each dimension's category index with a uniform random draw from {0, 1, ..., n_categories - 1}. The valid range is inferred from mutate_range, where ub[i] == n_categories - 1.

パラメータ:

• 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 categorical mutation operator.
contract	Return the categorical mutation contract.
mutate	Execute mutation for one candidate.
mutate_batch	Execute discrete 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

MutationCategorical.__init__(prob=1.0, *, prob_var=None)

Initialize categorical mutation operator.

パラメータ:

• 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).

MutationCategorical.contract()

Return the categorical mutation contract.

戻り値の型:

ComponentContract

MutationCategorical.mutate(p, mutate_range, rng=Generator(PCG64) at 0x7FE0F47AA6C0)

Execute mutation for one candidate.

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

メモ

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().

パラメータ:

• 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()

戻り値:

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.

戻り値の型:

np.ndarray

MutationCategorical.mutate_batch(candidates_batch, mutate_range, rng=Generator(PCG64) at 0x7FE0F47AB4C0)

Execute discrete uniform mutation on a batch of candidates at once.

This is the primary discrete 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 as a uniform random integer from [lb[i], ub[i]] (both inclusive) via rng.integers(lb, ub + 1, size=(k, dim)) -- rng.integers's high argument is exclusive by default, so ub + 1 makes the upper bound inclusive. The integer draw is cast to float via .astype(float) because the whole codebase represents integer and categorical dimensions as floats internally. 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 (np.where copies rather than recomputes them). 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 MutationUniform.mutate_batch's empty-gate skip.

パラメータ:

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

• mutate_range (tuple) -- Tuple of (lower_bound, upper_bound) arrays.

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

戻り値:

Mutated individuals. shape = (n, dim)

戻り値の型:

np.ndarray

メモ

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 full replacement array before moving to the next row. One batched call instead draws all individual gates, then the variable-gate arrays for all gated rows, then the replacement arrays for all of them. These phases therefore have a different draw order whenever more than one row is involved. 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.

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

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

パラメータ:

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

戻り値:

Processed individual. shape = (dim,)

戻り値の型:

np.ndarray

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

パラメータ:

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

戻り値:

Processed offspring. shape = (n, dim)

戻り値の型:

np.ndarray

メモ

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.

MutationCategorical.with_post(fn)

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

パラメータ:

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

戻り値:

Shallow copy with the hook registered.

戻り値の型:

Mutation