Advanced Optimizer Control

When default settings produce premature convergence or poor search quality, these controls give you finer-grained command over the evolutionary process. They are optional — the defaults are conservative and work well for most searches. Add them one at a time when telemetry shows the optimizer needs them.

Prerequisites

Completed Basic Usage
Familiar with Understanding Cross-Validation

When to Use These Controls

Check pd.DataFrame(search.history) after a run. Add controls if you see:

Symptom	Likely cause	Remedy
`unique_individual_ratio` drops to near 0 in a few generations	Population collapsed	Enable `diversity_control`
`genotype_diversity` is low while score still improves	Slow convergence, not stuck	Let it run or increase `population_size`
`stagnation_generations` grows for 5+ generations	Local optimum	Enable `diversity_control`, fitness sharing, or local search
Multiple high-scoring but similar candidates	Single dominant region	Enable `fitness_sharing` to keep multiple niches alive
Final solution is good but nearby configs might be better	Under-exploited region	Enable `local_search`

Configuration Objects

Advanced settings live in OptimizationConfig. All parameters are disabled (or set to low-impact defaults) unless explicitly changed.

python

from sklearn_genetic import OptimizationConfig

Full Example: Hyperparameter Search

python

import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score, roc_auc_score
from sklearn.model_selection import StratifiedKFold, train_test_split

from sklearn_genetic import (
    EvolutionConfig,
    GASearchCV,
    OptimizationConfig,
    PopulationConfig,
    RuntimeConfig,
)
from sklearn_genetic.schedules import ExponentialAdapter, InverseAdapter
from sklearn_genetic.space import Categorical, Integer

X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.25, stratify=y, random_state=42
)

cv = StratifiedKFold(n_splits=4, shuffle=True, random_state=42)

param_grid = {
    "n_estimators": Integer(50, 250),
    "max_depth": Integer(2, 20),
    "min_samples_split": Integer(2, 20),
    "min_samples_leaf": Integer(1, 10),
    "max_features": Categorical(["sqrt", "log2", None]),
    "criterion": Categorical(["gini", "entropy", "log_loss"]),
}

crossover_schedule = InverseAdapter(
    initial_value=0.8,
    end_value=0.6,
    adaptive_rate=0.05,
)
mutation_schedule = ExponentialAdapter(
    initial_value=0.1,
    end_value=0.25,
    adaptive_rate=0.08,
)

search = GASearchCV(
    estimator=RandomForestClassifier(random_state=42, n_jobs=1),
    param_grid=param_grid,
    cv=cv,
    scoring="roc_auc",
    evolution_config=EvolutionConfig(
        population_size=24,
        generations=18,
        crossover_probability=crossover_schedule,
        mutation_probability=mutation_schedule,
        tournament_size=3,
        elitism=True,
        keep_top_k=4,
    ),
    population_config=PopulationConfig(initializer="smart"),
    runtime_config=RuntimeConfig(n_jobs=-1, parallel_backend="auto", verbose=True),
    optimization_config=OptimizationConfig(
        # Diversity control
        diversity_control=True,
        diversity_threshold=0.18,
        diversity_stagnation_generations=4,
        diversity_mutation_boost=1.8,
        random_immigrants_fraction=0.15,
        # Fitness sharing
        fitness_sharing=True,
        sharing_radius=0.25,
        sharing_alpha=1.0,
        # Local search
        local_search=True,
        local_search_top_k=2,
        local_search_steps=4,
        local_search_radius=0.08,
    ),
)

search.fit(X_train, y_train)

y_pred = search.predict(X_test)
y_proba = search.predict_proba(X_test)[:, 1]

print(search.best_params_)
print("Accuracy:", accuracy_score(y_test, y_pred))
print("ROC AUC:", roc_auc_score(y_test, y_proba))

Reading Optimizer Telemetry

After fitting, convert history to a DataFrame to diagnose the search:

python

history = pd.DataFrame(search.history)

columns = [
    "gen",
    "fitness_best",
    "fitness_max",
    "unique_individual_ratio",
    "genotype_diversity",
    "stagnation_generations",
    "mutation_probability",
    "diversity_control_triggered",
    "random_immigrants",
    "duplicate_replacements",
    "fitness_sharing_applied",
    "mean_niche_count",
    "max_niche_count",
    "local_refinements",
]

print(history[columns])
print(search.fit_stats_)

Key telemetry fields:

Field	Meaning
`unique_individual_ratio`	Fraction of distinct individuals. Low → population collapsed
`genotype_diversity`	Average per-gene diversity. Low → structurally similar candidates
`stagnation_generations`	Generations since `fitness_best` last improved
`diversity_control_triggered`	Whether diversity control fired this generation
`random_immigrants`	Number of random candidates injected
`duplicate_replacements`	Duplicate offspring replaced before evaluation
`fitness_sharing_applied`	Whether niche-aware selection was active
`mean_niche_count` / `max_niche_count`	Crowding during selection
`local_refinements`	Neighbor candidates evaluated by local search (usually non-zero only in the final row)

Feature Selection Example

The same controls work with GAFeatureSelectionCV. In feature selection, local_search_radius controls the fraction of feature bits flipped when creating local neighbors.

python

from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import StratifiedKFold, train_test_split

from sklearn_genetic import (
    EvolutionConfig,
    GAFeatureSelectionCV,
    OptimizationConfig,
    PopulationConfig,
    RuntimeConfig,
)
from sklearn_genetic.schedules import ExponentialAdapter

X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.25, stratify=y, random_state=42
)

cv = StratifiedKFold(n_splits=4, shuffle=True, random_state=42)

selector = GAFeatureSelectionCV(
    estimator=RandomForestClassifier(random_state=42, n_jobs=1),
    cv=cv,
    scoring="roc_auc",
    max_features=18,
    evolution_config=EvolutionConfig(
        population_size=30,
        generations=16,
        crossover_probability=0.8,
        mutation_probability=ExponentialAdapter(
            initial_value=0.1, end_value=0.25, adaptive_rate=0.08
        ),
        keep_top_k=4,
    ),
    population_config=PopulationConfig(initializer="smart"),
    runtime_config=RuntimeConfig(n_jobs=-1, parallel_backend="auto", verbose=True),
    optimization_config=OptimizationConfig(
        diversity_control=True,
        diversity_threshold=0.2,
        diversity_stagnation_generations=4,
        random_immigrants_fraction=0.15,
        fitness_sharing=True,
        sharing_radius=0.2,
        local_search=True,
        local_search_top_k=2,
        local_search_steps=5,
        local_search_radius=0.1,
    ),
)

selector.fit(X_train, y_train)

print("Selected features:", selector.best_features_)
print("Test score:", selector.score(X_test, y_test))

Recommended Workflow

Start simple and add controls based on telemetry:

Default run — use PopulationConfig(initializer="smart"), crossover_probability=0.8, mutation_probability=0.1. Inspect history.
If diversity collapses early — enable OptimizationConfig(diversity_control=True).
If one candidate family dominates — enable fitness_sharing=True.
If the final region looks close but not fully refined — enable local_search=True.
If stagnation persists — add adaptive schedules: slowly increase mutation over generations.

Tuning Guidelines

Parameter	Practical starting range	Notes
`diversity_threshold`	0.1–0.3	Higher triggers earlier
`diversity_mutation_boost`	1.5–2.5	Too high = next generation is random
`random_immigrants_fraction`	0.05–0.2	Larger helps rugged spaces; may slow convergence
`sharing_radius`	0.15–0.35	Smaller = only penalize very similar candidates
`local_search_radius`	0.05–0.15	Larger = behaves more like an extra mutation phase
`local_search_steps`	1–5	Each step = extra CV calls

Practical Notes

Fitness sharing only changes temporary selection pressure; it does not alter best_score_, cv_results_, or raw cross-validation scores.
Local search evaluates extra candidates after the genetic search completes, so it can improve final quality but increases total runtime.
Always keep a final holdout set separate from the CV folds for honest model assessment.

Next Steps

Adaptive Schedules — schedule mutation and crossover rates over generations
Troubleshooting — diagnose convergence problems using fit_stats_ and history
Config Objects API — full parameter reference for OptimizationConfig

Advanced Optimizer Control ​

Prerequisites ​

When to Use These Controls ​

Configuration Objects ​

Full Example: Hyperparameter Search ​

Reading Optimizer Telemetry ​

Feature Selection Example ​

Recommended Workflow ​

Tuning Guidelines ​

Practical Notes ​

Next Steps ​

Advanced Optimizer Control

Prerequisites

When to Use These Controls

Configuration Objects

Full Example: Hyperparameter Search

Reading Optimizer Telemetry

Feature Selection Example

Recommended Workflow

Tuning Guidelines

Practical Notes

Next Steps