Evolution API Reference

Complete API documentation for genetic algorithms and evolutionary operations.

GeneticEvolver Class

Main class for evolutionary algorithms and meme population evolution.

Constructor

class GeneticEvolver:
    def __init__(
        self,
        population_size: int = 20,
        mutation_rate: float = 0.25,
        crossover_rate: float = 0.75,
        elitism_ratio: float = 0.1,
        fitness_function: Optional[Callable] = None,
        selection_method: str = "tournament",
        **kwargs
    ) -> None:
        """
        Initialize genetic evolver.

        Args:
            population_size: Size of the evolution population
            mutation_rate: Probability of mutation (0.0 to 1.0)
            crossover_rate: Probability of crossover (0.0 to 1.0)
            elitism_ratio: Fraction of elite individuals preserved
            fitness_function: Custom fitness evaluation function
            selection_method: Parent selection method
            **kwargs: Additional evolution parameters
        """

Evolution Parameters

Parameter	Type	Default	Range	Description
population_size	int	20	2-1000	Number of individuals
mutation_rate	float	0.25	0.0-1.0	Mutation probability
crossover_rate	float	0.75	0.0-1.0	Crossover probability
elitism_ratio	float	0.1	0.0-0.5	Elite preservation ratio
tournament_size	int	3	2-10	Tournament selection size
max_stagnation	int	10	1-100	Generations before restart

Core Evolution Methods

Basic Evolution

def evolve(
    self,
    initial_population: List[Meme],
    generations: int = 5,
    target_fitness: Optional[float] = None,
    convergence_threshold: float = 0.001
) -> EvolutionResult:
    """
    Evolve population of memes.

    Args:
        initial_population: Starting meme population
        generations: Number of generations to evolve
        target_fitness: Stop when fitness reached
        convergence_threshold: Stop when improvement < threshold

    Returns:
        EvolutionResult: Evolution results and final population

    Raises:
        MemeticEvolutionError: If evolution process fails
    """

def evolve_with_constraints(
    self,
    initial_population: List[Meme],
    constraints: EvolutionConstraints,
    generations: int = 5
) -> EvolutionResult:
    """
    Evolve with specific constraints.

    Args:
        initial_population: Starting population
        constraints: Evolution constraints
        generations: Number of generations

    Returns:
        EvolutionResult: Constrained evolution results
    """

Example:

from qmemetic_ai.core.evolution import GeneticEvolver, EvolutionConstraints

# Initialize evolver
evolver = GeneticEvolver(
    population_size=30,
    mutation_rate=0.3,
    crossover_rate=0.8,
    elitism_ratio=0.15
)

# Create initial population
initial_memes = [engine.create_meme(f"Research idea {i}") for i in range(15)]

# Basic evolution
result = evolver.evolve(
    initial_population=initial_memes,
    generations=20,
    target_fitness=0.9
)

print(f"Final fitness: {result.best_fitness:.3f}")
print(f"Generations completed: {result.generations_completed}")
print(f"Convergence achieved: {result.converged}")

Advanced Evolution

def multi_objective_evolution(
    self,
    initial_population: List[Meme],
    objectives: List[Callable],
    generations: int = 10,
    archive_size: int = 100
) -> MultiObjectiveResult:
    """
    Perform multi-objective evolution.

    Args:
        initial_population: Starting population
        objectives: List of objective functions
        generations: Number of generations
        archive_size: Size of Pareto archive

    Returns:
        MultiObjectiveResult: Pareto-optimal solutions
    """

def coevolution(
    self,
    populations: List[List[Meme]],
    interaction_matrix: np.ndarray,
    generations: int = 10
) -> CoevolutionResult:
    """
    Perform cooperative coevolution.

    Args:
        populations: Multiple populations to coevolve
        interaction_matrix: Population interaction strengths
        generations: Number of generations

    Returns:
        CoevolutionResult: Coevolution results
    """

Selection Methods

def tournament_selection(
    self,
    population: List[Meme],
    tournament_size: int = 3,
    num_parents: int = 2
) -> List[Meme]:
    """
    Tournament selection for parent memes.

    Args:
        population: Current population
        tournament_size: Size of tournament
        num_parents: Number of parents to select

    Returns:
        List[Meme]: Selected parent memes
    """

def roulette_wheel_selection(
    self,
    population: List[Meme],
    num_parents: int = 2
) -> List[Meme]:
    """
    Roulette wheel selection based on fitness.

    Args:
        population: Current population
        num_parents: Number of parents to select

    Returns:
        List[Meme]: Selected parent memes
    """

def rank_selection(
    self,
    population: List[Meme],
    selection_pressure: float = 2.0,
    num_parents: int = 2
) -> List[Meme]:
    """
    Rank-based selection.

    Args:
        population: Current population
        selection_pressure: Selection pressure parameter
        num_parents: Number of parents to select

    Returns:
        List[Meme]: Selected parent memes
    """

Example:

# Configure different selection methods
evolver.selection_method = "tournament"
evolver.tournament_size = 5

# Multi-objective evolution
objectives = [
    lambda m: m.calculate_fitness(),           # Primary fitness
    lambda m: m.novelty_score(),              # Novelty objective
    lambda m: 1.0 - m.complexity             # Simplicity objective
]

mo_result = evolver.multi_objective_evolution(
    initial_population=initial_memes,
    objectives=objectives,
    generations=15
)

print(f"Pareto front size: {len(mo_result.pareto_front)}")

Genetic Operators

Crossover Operations

def semantic_crossover(
    self,
    parent1: Meme,
    parent2: Meme,
    method: str = "weighted_average"
) -> Tuple[Meme, Meme]:
    """
    Perform semantic crossover between memes.

    Args:
        parent1: First parent meme
        parent2: Second parent meme
        method: Crossover method

    Returns:
        Tuple[Meme, Meme]: Two offspring memes
    """

def content_crossover(
    self,
    parent1: Meme,
    parent2: Meme,
    crossover_point: Optional[float] = None
) -> Tuple[Meme, Meme]:
    """
    Perform content-based crossover.

    Args:
        parent1: First parent meme
        parent2: Second parent meme
        crossover_point: Crossover position (0.0 to 1.0)

    Returns:
        Tuple[Meme, Meme]: Two offspring memes
    """

def uniform_crossover(
    self,
    parent1: Meme,
    parent2: Meme,
    swap_probability: float = 0.5
) -> Tuple[Meme, Meme]:
    """
    Perform uniform crossover.

    Args:
        parent1: First parent meme
        parent2: Second parent meme
        swap_probability: Probability of swapping each element

    Returns:
        Tuple[Meme, Meme]: Two offspring memes
    """

Mutation Operations

def semantic_mutation(
    self,
    meme: Meme,
    mutation_strength: float = 0.1
) -> Meme:
    """
    Apply semantic mutation to meme.

    Args:
        meme: Meme to mutate
        mutation_strength: Strength of mutation

    Returns:
        Meme: Mutated meme
    """

def content_mutation(
    self,
    meme: Meme,
    mutation_type: str = "synonym_replacement"
) -> Meme:
    """
    Apply content-based mutation.

    Args:
        meme: Meme to mutate
        mutation_type: Type of content mutation

    Returns:
        Meme: Mutated meme
    """

def structural_mutation(
    self,
    meme: Meme,
    structure_changes: List[str]
) -> Meme:
    """
    Apply structural mutations to meme.

    Args:
        meme: Meme to mutate
        structure_changes: List of structural changes

    Returns:
        Meme: Mutated meme
    """

Example:

# Custom crossover and mutation
parent1 = evolved_memes[0]
parent2 = evolved_memes[1]

# Semantic crossover
child1, child2 = evolver.semantic_crossover(
    parent1, parent2, method="attention_weighted"
)

# Content mutation
mutated_child = evolver.content_mutation(
    child1, mutation_type="paraphrase"
)

print(f"Parent 1: {parent1.content[:50]}...")
print(f"Parent 2: {parent2.content[:50]}...")
print(f"Child: {child1.content[:50]}...")
print(f"Mutated: {mutated_child.content[:50]}...")

EvolutionParameters Class

Configuration container for evolution parameters.

Parameter Groups

class EvolutionParameters:
    def __init__(
        self,
        # Basic parameters
        population_size: int = 20,
        generations: int = 5,

        # Genetic operators
        mutation_rate: float = 0.25,
        crossover_rate: float = 0.75,
        elitism_ratio: float = 0.1,

        # Selection parameters
        selection_method: str = "tournament",
        tournament_size: int = 3,
        selection_pressure: float = 2.0,

        # Convergence parameters
        convergence_threshold: float = 0.001,
        max_stagnation: int = 10,
        target_fitness: Optional[float] = None,

        # Diversity parameters
        diversity_pressure: float = 0.0,
        niching_enabled: bool = False,
        niche_radius: float = 0.1,

        # Performance parameters
        parallel_evaluation: bool = True,
        batch_size: int = 10,
        memory_limit: Optional[str] = None
    ) -> None:
        """Initialize evolution parameters."""

Parameter Validation

def validate_parameters(self) -> List[str]:
    """
    Validate parameter values.

    Returns:
        List[str]: List of validation errors (empty if valid)
    """

def optimize_for_dataset(
    self,
    dataset_size: int,
    available_memory: str,
    time_budget: int
) -> None:
    """
    Optimize parameters for specific dataset and constraints.

    Args:
        dataset_size: Size of meme dataset
        available_memory: Available memory (e.g., "4GB")
        time_budget: Time budget in seconds
    """

def adaptive_adjustment(
    self,
    generation: int,
    fitness_history: List[float],
    diversity_history: List[float]
) -> None:
    """
    Adaptively adjust parameters during evolution.

    Args:
        generation: Current generation number
        fitness_history: Historical fitness values
        diversity_history: Historical diversity values
    """

Example:

from qmemetic_ai.core.evolution import EvolutionParameters

# Create optimized parameters
params = EvolutionParameters(
    population_size=50,
    generations=30,
    mutation_rate=0.2,
    crossover_rate=0.85,
    selection_method="rank",
    diversity_pressure=0.3,
    parallel_evaluation=True
)

# Validate parameters
errors = params.validate_parameters()
if errors:
    print(f"Parameter errors: {errors}")

# Optimize for dataset
params.optimize_for_dataset(
    dataset_size=1000,
    available_memory="8GB",
    time_budget=3600  # 1 hour
)

# Use parameters with evolver
evolver = GeneticEvolver(**params.to_dict())

Fitness Functions

Built-in Fitness Functions

class FitnessFunctions:
    """Collection of built-in fitness functions."""

    @staticmethod
    def content_quality(meme: Meme) -> float:
        """Evaluate content quality and coherence."""

    @staticmethod
    def semantic_richness(meme: Meme) -> float:
        """Evaluate semantic richness and complexity."""

    @staticmethod
    def novelty_fitness(meme: Meme, population: List[Meme]) -> float:
        """Evaluate novelty relative to population."""

    @staticmethod
    def diversity_fitness(meme: Meme, population: List[Meme]) -> float:
        """Promote population diversity."""

    @staticmethod
    def domain_relevance(meme: Meme, domain_keywords: List[str]) -> float:
        """Evaluate relevance to specific domain."""

    @staticmethod
    def multi_objective_fitness(
        meme: Meme,
        objectives: List[Callable],
        weights: List[float]
    ) -> float:
        """Weighted combination of multiple objectives."""

Custom Fitness Functions

def create_custom_fitness(
    weights: Dict[str, float],
    constraints: Optional[Dict[str, Any]] = None
) -> Callable[[Meme], float]:
    """
    Create custom fitness function with specified weights.

    Args:
        weights: Weights for different fitness components
        constraints: Optional constraints to enforce

    Returns:
        Callable: Custom fitness function
    """

def adaptive_fitness(
    base_fitness: Callable,
    adaptation_rate: float = 0.1
) -> Callable[[Meme, int], float]:
    """
    Create adaptive fitness function that changes over generations.

    Args:
        base_fitness: Base fitness function
        adaptation_rate: Rate of fitness adaptation

    Returns:
        Callable: Adaptive fitness function
    """

Example:

# Built-in fitness functions
content_fitness = FitnessFunctions.content_quality(meme)
novelty_fitness = FitnessFunctions.novelty_fitness(meme, population)

# Custom weighted fitness
custom_fitness = create_custom_fitness(
    weights={
        "quality": 0.4,
        "novelty": 0.3,
        "relevance": 0.2,
        "complexity": 0.1
    },
    constraints={
        "min_length": 10,
        "max_length": 500,
        "required_keywords": ["AI", "research"]
    }
)

# Use custom fitness
evolver.fitness_function = custom_fitness
result = evolver.evolve(initial_memes, generations=15)

Evolution Monitoring

EvolutionTracker Class

class EvolutionTracker:
    """Track and analyze evolution progress."""

    def __init__(self):
        self.generation_history = []
        self.fitness_history = []
        self.diversity_history = []
        self.operator_statistics = {}

    def record_generation(
        self,
        generation: int,
        population: List[Meme],
        fitness_stats: Dict[str, float],
        diversity_metrics: Dict[str, float]
    ) -> None:
        """Record generation statistics."""

    def analyze_convergence(self) -> Dict[str, Any]:
        """Analyze convergence patterns."""

    def plot_evolution_progress(self) -> Any:
        """Create evolution progress plots."""

    def export_statistics(self, file_path: str) -> None:
        """Export evolution statistics to file."""

Real-time Monitoring

def monitor_evolution(
    evolver: GeneticEvolver,
    callback_frequency: int = 1
) -> EvolutionMonitor:
    """
    Set up real-time evolution monitoring.

    Args:
        evolver: Evolver to monitor
        callback_frequency: Callback every N generations

    Returns:
        EvolutionMonitor: Monitoring interface
    """

class EvolutionMonitor:
    """Real-time evolution monitoring interface."""

    def on_generation_complete(
        self,
        generation: int,
        population: List[Meme],
        statistics: Dict[str, Any]
    ) -> None:
        """Called when generation completes."""

    def on_evolution_complete(
        self,
        result: EvolutionResult
    ) -> None:
        """Called when evolution completes."""

    def get_live_statistics(self) -> Dict[str, Any]:
        """Get current evolution statistics."""

Example:

# Set up evolution tracking
tracker = EvolutionTracker()
monitor = monitor_evolution(evolver, callback_frequency=2)

# Custom monitoring callback
def custom_callback(gen, pop, stats):
    print(f"Generation {gen}: Best fitness = {stats['best_fitness']:.3f}")
    if stats['diversity'] < 0.1:
        print("Warning: Population diversity low!")

monitor.on_generation_complete = custom_callback

# Run monitored evolution
result = evolver.evolve(initial_memes, generations=20)

# Analyze results
convergence_analysis = tracker.analyze_convergence()
evolution_plot = tracker.plot_evolution_progress()

Specialized Evolution Algorithms

Island Model Evolution

class IslandEvolution:
    """Island model for parallel evolution."""

    def __init__(
        self,
        num_islands: int = 4,
        migration_rate: float = 0.1,
        migration_interval: int = 5,
        topology: str = "ring"
    ):
        self.num_islands = num_islands
        self.migration_rate = migration_rate
        self.migration_interval = migration_interval
        self.topology = topology

    def evolve_islands(
        self,
        initial_populations: List[List[Meme]],
        generations: int = 10
    ) -> List[List[Meme]]:
        """
        Evolve multiple islands in parallel.

        Args:
            initial_populations: Starting populations for each island
            generations: Number of generations

        Returns:
            List[List[Meme]]: Final populations from all islands
        """

    def migrate_individuals(
        self,
        populations: List[List[Meme]],
        generation: int
    ) -> List[List[Meme]]:
        """Handle migration between islands."""

Memetic Algorithms

class MemeticAlgorithm(GeneticEvolver):
    """Memetic algorithm combining evolution with local search."""

    def __init__(
        self,
        local_search_method: str = "hill_climbing",
        local_search_probability: float = 0.5,
        local_search_iterations: int = 10,
        **kwargs
    ):
        super().__init__(**kwargs)
        self.local_search_method = local_search_method
        self.local_search_probability = local_search_probability
        self.local_search_iterations = local_search_iterations

    def local_search(
        self,
        meme: Meme,
        iterations: int
    ) -> Meme:
        """
        Apply local search to improve meme.

        Args:
            meme: Meme to improve
            iterations: Number of local search steps

        Returns:
            Meme: Improved meme
        """

    def evolve_with_local_search(
        self,
        initial_population: List[Meme],
        generations: int = 5
    ) -> EvolutionResult:
        """Evolve with integrated local search."""

Example:

# Island model evolution
island_evolution = IslandEvolution(
    num_islands=6,
    migration_rate=0.15,
    migration_interval=3
)

# Create island populations
island_pops = [
    [engine.create_meme(f"Island {i} idea {j}") for j in range(10)]
    for i in range(6)
]

# Evolve islands
final_islands = island_evolution.evolve_islands(
    initial_populations=island_pops,
    generations=15
)

# Memetic algorithm
memetic = MemeticAlgorithm(
    population_size=20,
    local_search_method="simulated_annealing",
    local_search_probability=0.7
)

memetic_result = memetic.evolve_with_local_search(
    initial_population=initial_memes,
    generations=10
)

Performance Optimization

Parallel Evolution

class ParallelEvolver(GeneticEvolver):
    """Parallel implementation of genetic evolution."""

    def __init__(
        self,
        num_workers: int = 4,
        evaluation_batch_size: int = 20,
        **kwargs
    ):
        super().__init__(**kwargs)
        self.num_workers = num_workers
        self.evaluation_batch_size = evaluation_batch_size

    def parallel_fitness_evaluation(
        self,
        population: List[Meme]
    ) -> List[float]:
        """Evaluate fitness in parallel."""

    def parallel_genetic_operations(
        self,
        population: List[Meme],
        num_offspring: int
    ) -> List[Meme]:
        """Perform genetic operations in parallel."""

Memory-Efficient Evolution

class MemoryEfficientEvolver(GeneticEvolver):
    """Memory-efficient evolution for large populations."""

    def __init__(
        self,
        checkpoint_frequency: int = 10,
        disk_cache_size: str = "1GB",
        **kwargs
    ):
        super().__init__(**kwargs)
        self.checkpoint_frequency = checkpoint_frequency
        self.disk_cache_size = disk_cache_size

    def streaming_evolution(
        self,
        meme_generator: Iterator[Meme],
        generations: int = 5
    ) -> EvolutionResult:
        """Evolve using streaming meme generation."""

    def checkpoint_evolution(
        self,
        checkpoint_path: str,
        generation: int,
        population: List[Meme]
    ) -> None:
        """Save evolution checkpoint."""

Example:

# Parallel evolution
parallel_evolver = ParallelEvolver(
    num_workers=8,
    evaluation_batch_size=50,
    population_size=200
)

parallel_result = parallel_evolver.evolve(
    initial_population=large_population,
    generations=30
)

# Memory-efficient evolution
memory_evolver = MemoryEfficientEvolver(
    checkpoint_frequency=5,
    disk_cache_size="2GB"
)

# Stream large datasets
def meme_stream():
    for i in range(10000):
        yield engine.create_meme(f"Streaming meme {i}")

streaming_result = memory_evolver.streaming_evolution(
    meme_generator=meme_stream(),
    generations=20
)

Integration Examples

With Entanglement Networks

# Evolution-guided entanglement
evolved_memes = evolver.evolve(initial_memes, generations=10)
network = entangler.create_network(evolved_memes)

# Use network properties for fitness
def network_fitness(meme):
    degree = network.get_degree(meme)
    centrality = network.get_centrality(meme)
    clustering = network.get_local_clustering(meme)

    return 0.4 * degree + 0.3 * centrality + 0.3 * clustering

# Evolve with network-based fitness
network_evolved = evolver.evolve(
    evolved_memes,
    fitness_function=network_fitness,
    generations=5
)

With Cognitive Models

# Cognitive-driven evolution
from qmemetic_ai.cognitive.models import CognitiveFingerprint

user_profile = CognitiveFingerprint(
    user_id="researcher_001",
    preferences={"complexity": 0.8, "novelty": 0.7}
)

def personalized_fitness(meme):
    base_fitness = meme.calculate_fitness()
    user_fit = user_profile.calculate_fit_score(meme)
    return 0.6 * base_fitness + 0.4 * user_fit

# Personalized evolution
personalized_result = evolver.evolve(
    initial_memes,
    fitness_function=personalized_fitness,
    generations=15
)

For complete integration examples, see the Engine API and Entanglement API documentation.