Módulo PySAG.mutation

Módulo que implementa operadores de mutación para algoritmos genéticos.

Este módulo proporciona varias estrategias de mutación que pueden ser utilizadas en algoritmos genéticos. Las funciones están diseñadas para ser flexibles y eficientes, utilizando Numba para la optimización del núcleo computacional.

Operadores de Mutación Disponibles:

  • mutation_bit_flip: Invierte bits aleatorios en un individuo binario.

  • mutation_random_gene_uniform: Reemplaza genes con valores de una dist. uniforme.

  • mutation_gaussian: Añade ruido gaussiano a genes numéricos.

  • mutation_swap: Intercambia dos genes aleatorios en el individuo.

  • mutation_inversion: Invierte un segmento del cromosoma (para permutaciones).

PySAG.mutation.mutation_bit_flip(individual, mutation_rate=0.01, **kwargs)[fuente]

Invierte bits aleatorios en un individuo de representación binaria.

Cada bit tiene una probabilidad mutation_rate de ser invertido.

Parámetros:

  • individual (ndarray[tuple[int, ...], dtype[int64]]) – Individuo a mutar (array NumPy 1D de enteros, 0s y 1s).

  • mutation_rate (float) – Probabilidad de que cada bit mute. Por defecto es 0.01.

  • **kwargs (Dict[str, Any]) – Argumentos adicionales (no utilizados).

Devuelve:

Una copia del individuo con los bits posiblemente invertidos.

Muestra:

  • TypeValidationError –

  • Si el individuo no es un array de NumPy o no es de tipo entero. –

  • ParameterError –

  • Si el individuo no es 1D. –

  • RangeError –

  • Si mutation_rate está fuera del rango [0, 1]. –

  • ValueError –

  • Si el individuo no es binario (no contiene solo 0s y 1s). –

  • MutationError –

  • Si ocurre un error inesperado durante la mutación. –

Tipo del valor devuelto:

ndarray[tuple[int, …], dtype[int64]]

Ejemplo

>>> import numpy as np
>>> ind = np.array([0, 1, 0, 1, 0, 0, 1, 1])
>>> mutated = mutation_bit_flip(ind, mutation_rate=0.5)
>>> mutated.shape == ind.shape
True
>>> # El resultado es probabilístico, pero algunos bits deberían cambiar.
PySAG.mutation.mutation_gaussian(individual, mu=0.0, sigma=1.0, mutation_rate=0.01, clip_low=None, clip_high=None, **kwargs)[fuente]

Añade ruido gaussiano a los genes del individuo.

Cada gen tiene una probabilidad mutation_rate de ser mutado. Si muta, se le suma un valor muestreado de N(mu, sigma). Opcionalmente, los valores pueden ser recortados a un rango [clip_low, clip_high].

Parámetros:

  • individual (ndarray[tuple[int, ...], dtype[float64]]) – Individuo a mutar (array NumPy 1D de flotantes).

  • mu (float) – Media de la distribución normal para el ruido. Por defecto es 0.0.

  • sigma (float) – Desviación estándar de la distribución normal. Debe ser no negativo. Por defecto es 1.0.

  • mutation_rate (float) – Probabilidad de que cada gen mute. Por defecto es 0.01.

  • clip_low (float | None) – Límite inferior opcional para recortar los valores mutados.

  • clip_high (float | None) – Límite superior opcional para recortar los valores mutados.

  • **kwargs (Dict[str, Any]) – Argumentos adicionales (no utilizados).

Devuelve:

Una copia del individuo con ruido gaussiano posiblemente añadido y recortado.

Muestra:

  • TypeValidationError – Si individual no es array de flotantes, o mu/sigma no son numéricos.

  • ParameterError – Si el individuo no es 1D.

  • RangeError – Si mutation_rate está fuera de rango, sigma es negativo, o clip_low > clip_high.

  • MutationError – Si ocurre un error inesperado.

Tipo del valor devuelto:

ndarray[tuple[int, …], dtype[float64]]

Ejemplo

>>> import numpy as np
>>> ind = np.array([1.0, 2.0, 3.0, 4.0])
>>> mutated = mutation_gaussian(
    ind,
    sigma=0.1,
    mutation_rate=0.5,
    clip_low=0.0,
    clip_high=5.0,
)
PySAG.mutation.mutation_inversion(individual, mutation_rate=0.01, **kwargs)[fuente]

Invierte un segmento aleatorio del cromosoma.

Esta mutación es comúnmente usada para representaciones de permutación. La operación de inversión ocurre en el individuo completo con una probabilidad mutation_rate. Si ocurre, se seleccionan dos puntos aleatorios y el segmento entre ellos (inclusive) se invierte.

Parámetros:

  • individual (ndarray[tuple[int, ...], dtype[ChromosomeType]]) – Individuo a mutar (array NumPy 1D).

  • mutation_rate (float) – Probabilidad de que la operación de inversión ocurra. Por defecto es 0.01.

  • **kwargs (Dict[str, Any]) – Argumentos adicionales (no utilizados).

Devuelve:

Una copia del individuo, con un segmento posiblemente invertido.

Muestra:

  • TypeValidationError – Si individual no es un array de NumPy.

  • ParameterError – Si el individuo no es 1D o tiene menos de 2 elementos (necesario para una inversión significativa).

  • RangeError – Si mutation_rate está fuera del rango [0, 1].

  • MutationError – Si ocurre un error inesperado.

Tipo del valor devuelto:

ndarray[tuple[int, …], dtype[ChromosomeType]]

Ejemplo

>>> import numpy as np
>>> ind = np.array([1, 2, 3, 4, 5, 6])
>>> # Para asegurar que la inversión ocurra para el ejemplo:
>>> mutated = mutation_inversion(ind, mutation_rate=1.0)
>>> len(mutated) == len(ind) and set(mutated) == set(ind)
True
>>> # Es probable que el orden cambie si la longitud es >= 2
PySAG.mutation.mutation_random_gene_uniform(individual, gene_low, gene_high, mutation_rate=0.01, **kwargs)[fuente]

Muta genes aleatorios reemplazándolos con un valor de una distribución uniforme.

Cada gen tiene una probabilidad mutation_rate de ser mutado. Si el dtype del individuo es flotante, se usa np.random.uniform(low, high). Si es entero, se usa np.random.randint(low, high + 1).

Parámetros:

  • individual (ndarray[tuple[int, ...], dtype[ChromosomeType]]) – Individuo a mutar (array NumPy 1D).

  • gene_low (float | int) – Límite inferior para los nuevos valores de los genes.

  • gene_high (float | int) – Límite superior para los nuevos valores de los genes. (Exclusivo para flotantes, inclusivo para enteros).

  • mutation_rate (float) – Probabilidad de que cada gen mute. Por defecto es 0.01.

  • **kwargs (Dict[str, Any]) – Argumentos adicionales (no utilizados).

Devuelve:

Una copia del individuo con genes posiblemente mutados.

Muestra:
Tipo del valor devuelto:

ndarray[tuple[int, …], dtype[ChromosomeType]]

Ejemplo

>>> import numpy as np
>>> ind_float = np.array([1.0, 2.0, 3.0, 4.0])
>>> mutated_float = mutation_random_gene_uniform(ind_float, 0.0, 10.0, 0.5)
>>> ind_int = np.array([1, 2, 3, 4])
>>> mutated_int = mutation_random_gene_uniform(ind_int, 0, 10, 0.5)
PySAG.mutation.mutation_swap(individual, mutation_rate=0.01, **kwargs)[fuente]

Intercambia dos genes aleatorios en el individuo.

La operación de intercambio (swap) ocurre en el individuo completo con una probabilidad mutation_rate. Si ocurre, se eligen dos genes distintos al azar y se intercambian sus posiciones.

Parámetros:

  • individual (ndarray[tuple[int, ...], dtype[ChromosomeType]]) – Individuo a mutar (array NumPy 1D).

  • mutation_rate (float) – Probabilidad de que la operación de intercambio ocurra. Por defecto es 0.01.

  • **kwargs (Dict[str, Any]) – Argumentos adicionales (no utilizados).

Devuelve:

Una copia del individuo, con dos genes posiblemente intercambiados.

Muestra:

  • TypeValidationError – Si individual no es un array de NumPy.

  • ParameterError – Si el individuo no es 1D o tiene menos de 2 elementos (necesario para un intercambio).

  • RangeError – Si mutation_rate está fuera del rango [0, 1].

  • MutationError – Si ocurre un error inesperado.

Tipo del valor devuelto:

ndarray[tuple[int, …], dtype[ChromosomeType]]

Ejemplo

>>> import numpy as np
>>> ind = np.array([1, 2, 3, 4, 5])
>>> # Para asegurar que el swap ocurra para el ejemplo:
>>> mutated = mutation_swap(ind, mutation_rate=1.0)
>>> len(mutated) == len(ind) and set(mutated) == (
    set(ind) and not np.array_equal(mutated, ind)
)
True