pymetaheuristic 5.5.2__py3-none-any.whl

pymetaheuristic/__init__.py

@@ -0,0 +1,162 @@
+"""Public package for pymetaheuristic."""
+
+from .src.api import create_optimizer, get_algorithm_info, list_algorithms, optimize
+from .src.callbacks import Callback, CallbackList, EarlyStopping, HistoryRecorder, ProgressPrinter
+from .src.cooperation import cooperative_optimize, replay_cooperative_result
+from .src.graphs import (
+    compare_convergence,
+    plot_benchmark_summary,
+    plot_collaboration_network,
+    plot_convergence,
+    plot_function,
+    plot_function_1d,
+    plot_function_2d,
+    plot_function_3d,
+    plot_function_contour,
+    plot_function_nd,
+    plot_function_surface,
+    plot_island_dynamics,
+    plot_population_snapshot,
+)
+from .src.orchestration import orchestrated_optimize
+from .src.reference import (
+    ARGUMENT_REFERENCE,
+    search_reference,
+    print_reference,
+    print_root_exports,
+)
+from .src.schemas import (
+    ActionOutcome,
+    ActionSpec,
+    AgentSnapshot,
+    CollaborativeConfig,
+    DecisionPlan,
+    OrchestratedCooperativeResult,
+    OrchestrationSpec,
+    OrchestratorSnapshot,
+    RulesConfig,
+)
+from .src.test_functions import FUNCTIONS, get_test_function
+from .src.actions import estimate_action_cost
+from .src.telemetry import (
+    convergence_data,
+    export_history_csv,
+    export_island_telemetry_csv,
+    export_population_snapshots_json,
+    export_replay_manifest_json,
+    summarize_cooperative_result,
+    summarize_result,
+)
+from .src.termination import Termination
+from .src.viz import (
+    plot_diversity_chart,
+    plot_diversity_comparison,
+    plot_explore_exploit_chart,
+    plot_global_best_chart,
+    plot_run_dashboard,
+    plot_runtime_chart,
+)
+from .src.utils import (
+    AVAILABLE_CHAOTIC_MAPS,
+    AVAILABLE_INIT_STRATEGIES,
+    AVAILABLE_REPAIR_STRATEGIES,
+    AVAILABLE_TRANSFER_FUNCTIONS,
+    AckleyProblem,
+    BinaryAdapter,
+    BinaryVar,
+    CategoricalVar,
+    ChaoticMap,
+    FloatVar,
+    FunctionalProblem,
+    IntegerVar,
+    PermutationVar,
+    Problem,
+    RastriginProblem,
+    RosenbrockProblem,
+    SphereProblem,
+    ZakharovProblem,
+    apply_transfer,
+    binarize,
+    build_problem_spec,
+    chaotic_init_function,
+    chaotic_population,
+    chaotic_sequence,
+    decode_position,
+    encode_position,
+    full_array,
+    get_init_function,
+    get_repair_function,
+    get_test_problem,
+    lhs_population,
+    levy_flight,
+    limit,
+    limit_inverse,
+    obl_population,
+    rand,
+    reflect,
+    sobol_population,
+    sstf_01, sstf_02, sstf_03, sstf_04,
+    uniform_population,
+    vstf_01, vstf_02, vstf_03, vstf_04,
+    wang,
+)
+from .src.tuner import BenchmarkRunner, HyperparameterTuner
+from .src.io import (
+    load_checkpoint,
+    load_result,
+    result_from_json,
+    result_to_json,
+    save_checkpoint,
+    save_result,
+)
+
+__version__ = "5.5.2"
+
+__all__ = [
+    "FUNCTIONS",
+    "ActionOutcome", "ActionSpec", "AgentSnapshot",
+    "ARGUMENT_REFERENCE",
+    "Callback", "CallbackList", "EarlyStopping", "HistoryRecorder", "ProgressPrinter",
+    "CollaborativeConfig", "DecisionPlan",
+    "OrchestratedCooperativeResult", "OrchestrationSpec",
+    "OrchestratorSnapshot", "RulesConfig",
+    "compare_convergence", "cooperative_optimize", "replay_cooperative_result",
+    "convergence_data",
+    "create_optimizer", "estimate_action_cost",
+    "export_history_csv", "export_island_telemetry_csv",
+    "export_population_snapshots_json", "export_replay_manifest_json",
+    "get_algorithm_info", "get_test_function", "get_test_problem",
+    "list_algorithms", "optimize", "orchestrated_optimize",
+    "plot_benchmark_summary", "plot_collaboration_network",
+    "plot_convergence", "plot_function",
+    "plot_function_1d", "plot_function_2d", "plot_function_3d",
+    "plot_function_contour", "plot_function_nd", "plot_function_surface",
+    "plot_island_dynamics", "plot_population_snapshot",
+    "print_reference", "print_root_exports", "search_reference",
+    "summarize_cooperative_result", "summarize_result",
+    "Termination",
+    "plot_diversity_chart", "plot_diversity_comparison",
+    "plot_explore_exploit_chart", "plot_global_best_chart",
+    "plot_run_dashboard", "plot_runtime_chart",
+    "BinaryVar", "CategoricalVar", "FloatVar", "IntegerVar", "PermutationVar",
+    "build_problem_spec", "decode_position", "encode_position",
+    "AVAILABLE_CHAOTIC_MAPS", "ChaoticMap", "chaotic_population", "chaotic_sequence",
+    "AVAILABLE_TRANSFER_FUNCTIONS", "BinaryAdapter", "apply_transfer", "binarize",
+    "vstf_01", "vstf_02", "vstf_03", "vstf_04",
+    "sstf_01", "sstf_02", "sstf_03", "sstf_04",
+    "AVAILABLE_REPAIR_STRATEGIES", "get_repair_function", "limit", "limit_inverse",
+    "rand", "reflect", "wang",
+    "AVAILABLE_INIT_STRATEGIES", "get_init_function", "uniform_population",
+    "lhs_population", "obl_population", "sobol_population", "chaotic_init_function",
+    "Problem", "FunctionalProblem", "SphereProblem", "RastriginProblem",
+    "AckleyProblem", "RosenbrockProblem", "ZakharovProblem", "full_array",
+    "levy_flight",
+    "HyperparameterTuner", "BenchmarkRunner",
+    "load_checkpoint", "load_result",
+    "result_from_json", "result_to_json",
+    "save_checkpoint", "save_result",
+]
+
+from . import src  # noqa: E402
+examples = src.examples
+reference = src.reference

pymetaheuristic/src/__init__.py

@@ -0,0 +1,162 @@
+"""Core implementation package for pymetaheuristic."""
+
+from . import (
+    actions,
+    api,
+    callbacks,
+    controllers,
+    cooperation,
+    engines,
+    examples,
+    execution,
+    graphs,
+    io,
+    orchestration,
+    reference,
+    schemas,
+    telemetry,
+    termination,
+    test_functions,
+    tuner,
+    utils,
+    viz,
+)
+
+from .api import create_optimizer, get_algorithm_info, list_algorithms, optimize
+from .callbacks import Callback, CallbackList, EarlyStopping, HistoryRecorder, ProgressPrinter
+from .cooperation import cooperative_optimize, replay_cooperative_result
+from .io import (
+    load_checkpoint,
+    load_result,
+    result_from_json,
+    result_to_json,
+    save_checkpoint,
+    save_result,
+)
+from .orchestration import orchestrated_optimize
+from .reference import (
+    ARGUMENT_REFERENCE,
+    search_reference,
+    print_reference,
+    print_root_exports,
+)
+from .schemas import (
+    ActionOutcome,
+    ActionSpec,
+    AgentSnapshot,
+    CollaborativeConfig,
+    DecisionPlan,
+    OrchestratedCooperativeResult,
+    OrchestrationSpec,
+    OrchestratorSnapshot,
+    RulesConfig,
+)
+from .telemetry import (
+    convergence_data,
+    export_history_csv,
+    export_island_telemetry_csv,
+    export_population_snapshots_json,
+    export_replay_manifest_json,
+    summarize_cooperative_result,
+    summarize_result,
+)
+from .termination import Termination
+from .test_functions import FUNCTIONS, get_test_function
+from .actions import estimate_action_cost
+from .tuner import BenchmarkRunner, HyperparameterTuner
+from .utils import (
+    AVAILABLE_CHAOTIC_MAPS,
+    AVAILABLE_INIT_STRATEGIES,
+    AVAILABLE_REPAIR_STRATEGIES,
+    AVAILABLE_TRANSFER_FUNCTIONS,
+    AckleyProblem,
+    BinaryAdapter,
+    BinaryVar,
+    CategoricalVar,
+    ChaoticMap,
+    FloatVar,
+    FunctionalProblem,
+    IntegerVar,
+    PermutationVar,
+    Problem,
+    RastriginProblem,
+    RosenbrockProblem,
+    SphereProblem,
+    ZakharovProblem,
+    apply_transfer,
+    binarize,
+    build_problem_spec,
+    chaotic_init_function,
+    chaotic_population,
+    chaotic_sequence,
+    decode_position,
+    encode_position,
+    full_array,
+    get_init_function,
+    get_repair_function,
+    get_test_problem,
+    lhs_population,
+    levy_flight,
+    limit,
+    limit_inverse,
+    obl_population,
+    rand,
+    reflect,
+    sobol_population,
+    sstf_01, sstf_02, sstf_03, sstf_04,
+    uniform_population,
+    vstf_01, vstf_02, vstf_03, vstf_04,
+    wang,
+)
+from .viz import (
+    plot_diversity_chart,
+    plot_diversity_comparison,
+    plot_explore_exploit_chart,
+    plot_global_best_chart,
+    plot_run_dashboard,
+    plot_runtime_chart,
+)
+
+__all__ = [
+    "FUNCTIONS",
+    "ActionOutcome", "ActionSpec", "AgentSnapshot",
+    "ARGUMENT_REFERENCE",
+    "Callback", "CallbackList", "EarlyStopping", "HistoryRecorder", "ProgressPrinter", "callbacks",
+    "CollaborativeConfig", "DecisionPlan",
+    "OrchestratedCooperativeResult", "OrchestrationSpec",
+    "OrchestratorSnapshot", "RulesConfig",
+    "actions", "api", "controllers", "cooperation",
+    "cooperative_optimize", "convergence_data", "create_optimizer",
+    "engines", "estimate_action_cost", "examples", "execution",
+    "export_history_csv", "export_island_telemetry_csv",
+    "export_population_snapshots_json", "export_replay_manifest_json",
+    "get_algorithm_info", "get_test_function", "get_test_problem",
+    "graphs", "list_algorithms", "optimize", "orchestration",
+    "orchestrated_optimize", "print_reference", "print_root_exports",
+    "reference", "replay_cooperative_result",
+    "schemas", "search_reference",
+    "summarize_cooperative_result", "summarize_result",
+    "telemetry", "test_functions",
+    "Termination", "termination",
+    "plot_diversity_chart", "plot_diversity_comparison",
+    "plot_explore_exploit_chart", "plot_global_best_chart",
+    "plot_run_dashboard", "plot_runtime_chart", "viz",
+    "AVAILABLE_CHAOTIC_MAPS", "AVAILABLE_TRANSFER_FUNCTIONS",
+    "AVAILABLE_INIT_STRATEGIES", "AVAILABLE_REPAIR_STRATEGIES",
+    "BinaryVar", "CategoricalVar", "FloatVar", "IntegerVar", "PermutationVar",
+    "build_problem_spec", "decode_position", "encode_position", "utils",
+    "ChaoticMap", "chaotic_population", "chaotic_sequence",
+    "BinaryAdapter", "apply_transfer", "binarize",
+    "vstf_01", "vstf_02", "vstf_03", "vstf_04",
+    "sstf_01", "sstf_02", "sstf_03", "sstf_04",
+    "HyperparameterTuner", "BenchmarkRunner", "tuner",
+    "Problem", "FunctionalProblem", "SphereProblem", "RastriginProblem",
+    "AckleyProblem", "RosenbrockProblem", "ZakharovProblem", "full_array",
+    "get_init_function", "uniform_population", "lhs_population", "obl_population",
+    "sobol_population", "chaotic_init_function",
+    "get_repair_function", "limit", "limit_inverse", "rand", "reflect", "wang",
+    "levy_flight",
+    "io", "load_checkpoint", "load_result",
+    "result_from_json", "result_to_json",
+    "save_checkpoint", "save_result",
+]

pymetaheuristic/src/actions.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+import math
+import random
+
+import numpy as np
+
+from .engines import CandidateRecord
+from .schemas import ActionSpec, ActionOutcome, DecisionPlan
+
+
+def select_candidates(engine, state, mode: str = "best", k: int = 1) -> list[CandidateRecord]:
+    k = max(1, int(k))
+    return list(engine.export_candidates(state, k=k, mode=mode))
+
+
+
+def perturb_candidates(
+    candidates: list[CandidateRecord],
+    sigma: float,
+    min_values: list[float],
+    max_values: list[float],
+    seed: int | None = None,
+) -> list[CandidateRecord]:
+    if not candidates:
+        return []
+    rng = np.random.default_rng(seed)
+    lo = np.asarray(min_values, dtype=float)
+    hi = np.asarray(max_values, dtype=float)
+    out: list[CandidateRecord] = []
+    for cand in candidates:
+        pos = np.asarray(cand.position, dtype=float)
+        eps = rng.normal(0.0, float(sigma), size=pos.shape)
+        new_pos = np.clip(pos + eps, lo, hi)
+        out.append(CandidateRecord(
+            position=new_pos.tolist(),
+            fitness=float(cand.fitness),
+            source_algorithm=cand.source_algorithm,
+            source_step=cand.source_step,
+            role=cand.role,
+            metadata=dict(cand.metadata or {}),
+        ))
+    return out
+
+
+
+def _random_candidate(problem, rng: random.Random) -> CandidateRecord:
+    pos = [rng.uniform(lo, hi) for lo, hi in zip(problem.min_values, problem.max_values)]
+    fit = float(problem.evaluate(pos))
+    return CandidateRecord(position=pos, fitness=fit, role="restart")
+
+
+
+def execute_decision_plan(
+    plan: DecisionPlan,
+    engines: dict[str, Any],
+    states: dict[str, Any],
+    objective: str,
+    seed: int | None = None,
+) -> tuple[dict[str, Any], list[ActionOutcome]]:
+    outcomes: list[ActionOutcome] = []
+    rng = random.Random(seed)
+
+    for action in plan.actions:
+        try:
+            if action.type == "wait":
+                outcomes.append(ActionOutcome(action=action, executed=True, status="applied", message="No action taken."))
+                continue
+
+            if action.type == "set_checkpoint":
+                outcomes.append(ActionOutcome(action=action, executed=True, status="applied", message="Checkpoint interval updated by runner."))
+                continue
+
+            target_engine = engines.get(action.target_label) if action.target_label else None
+            target_state = states.get(action.target_label) if action.target_label else None
+            source_engine = engines.get(action.source_label) if action.source_label else None
+            source_state = states.get(action.source_label) if action.source_label else None
+
+            if action.type in {"inject", "inject_perturbed", "restart_agent"} and (source_engine is None and not action.params.get("random_seed_receiver")):
+                outcomes.append(ActionOutcome(action=action, executed=False, status="skipped", message="Missing source engine."))
+                continue
+            if action.type in {"inject", "inject_perturbed", "rebalance", "reconfigure", "restart_agent"} and target_engine is None:
+                outcomes.append(ActionOutcome(action=action, executed=False, status="skipped", message="Missing target engine."))
+                continue
+
+            if action.type in {"inject", "inject_perturbed"}:
+                mode = action.source_mode or "best"
+                k = int(action.k or 1)
+                migrants = select_candidates(source_engine, source_state, mode=mode, k=k)
+                source_fit = migrants[0].fitness if migrants else None
+                if action.type == "inject_perturbed":
+                    sigma = float((action.perturbation or {}).get("sigma", 0.05))
+                    migrants = perturb_candidates(migrants, sigma=sigma, min_values=target_engine.problem.min_values, max_values=target_engine.problem.max_values, seed=seed)
+                before = target_state.best_fitness
+                if not target_engine.capabilities.supports_candidate_injection:
+                    outcomes.append(ActionOutcome(action=action, executed=False, status="skipped", message="Target engine does not support candidate injection.", source_fitness=source_fit, target_fitness_before=before, target_fitness_after=before))
+                    continue
+                states[action.target_label] = target_engine.inject_candidates(target_state, migrants, policy=action.replace_policy or "native")
+                after = states[action.target_label].best_fitness
+                outcomes.append(ActionOutcome(action=action, executed=True, status="applied", message="Candidates injected.", source_fitness=source_fit, target_fitness_before=before, target_fitness_after=after))
+                continue
+
+            if action.type == "rebalance":
+                before = target_state.best_fitness
+                if not target_engine.capabilities.supports_candidate_injection or not target_engine.capabilities.has_population:
+                    outcomes.append(ActionOutcome(action=action, executed=False, status="skipped", message="Target engine cannot rebalance population.", target_fitness_before=before, target_fitness_after=before))
+                    continue
+                fraction = float(action.params.get("fraction", 0.2))
+                try:
+                    pop = target_engine.get_population(target_state)
+                    n = max(1, int(math.ceil(len(pop) * fraction)))
+                except Exception:
+                    n = max(1, int(action.k or 1))
+                migrants = [_random_candidate(target_engine.problem, rng) for _ in range(n)]
+                states[action.target_label] = target_engine.inject_candidates(target_state, migrants, policy=action.replace_policy or "native")
+                after = states[action.target_label].best_fitness
+                outcomes.append(ActionOutcome(action=action, executed=True, status="applied", message=f"Population rebalanced with {n} random candidates.", target_fitness_before=before, target_fitness_after=after))
+                continue
+
+            if action.type == "reconfigure":
+                before = target_state.best_fitness
+                states[action.target_label] = target_engine.reconfigure(target_state, dict(action.params or {}))
+                after = states[action.target_label].best_fitness
+                outcomes.append(ActionOutcome(action=action, executed=True, status="applied", message="Engine reconfigured.", target_fitness_before=before, target_fitness_after=after))
+                continue
+
+            if action.type == "restart_agent":
+                before = target_state.best_fitness
+                seeds = []
+                if action.params.get("random_seed_receiver"):
+                    seeds = [_random_candidate(target_engine.problem, rng)]
+                else:
+                    seeds = select_candidates(source_engine, source_state, mode=action.source_mode or "best", k=int(action.k or 1))
+                if not target_engine.capabilities.supports_restart:
+                    msg = "Target engine does not support restart; downgraded to injection." if target_engine.capabilities.supports_candidate_injection else "Target engine does not support restart."
+                    if target_engine.capabilities.supports_candidate_injection:
+                        states[action.target_label] = target_engine.inject_candidates(target_state, seeds, policy=action.replace_policy or "native")
+                        after = states[action.target_label].best_fitness
+                        outcomes.append(ActionOutcome(action=action, executed=True, status="downgraded", message=msg, target_fitness_before=before, target_fitness_after=after))
+                    else:
+                        outcomes.append(ActionOutcome(action=action, executed=False, status="skipped", message=msg, target_fitness_before=before, target_fitness_after=before))
+                    continue
+                states[action.target_label] = target_engine.restart(target_state, seeds=seeds, preserve_best=bool(action.params.get("preserve_best", True)))
+                after = states[action.target_label].best_fitness
+                outcomes.append(ActionOutcome(action=action, executed=True, status="applied", message="Engine restarted.", target_fitness_before=before, target_fitness_after=after))
+                continue
+
+            outcomes.append(ActionOutcome(action=action, executed=False, status="skipped", message=f"Unsupported action: {action.type}"))
+        except Exception as exc:
+            outcomes.append(ActionOutcome(action=action, executed=False, status="failed", message=str(exc)))
+    return states, outcomes
+
+
+
+def outcome_to_dict(outcome: ActionOutcome) -> dict[str, Any]:
+    data = asdict(outcome)
+    data["action"] = asdict(outcome.action)
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Action-cost estimation
+# ---------------------------------------------------------------------------
+# Default evaluation-equivalent action cost table. The spec requires the
+# ordering:
+#     wait < inject ≤ inject_perturbed < rebalance ≤ reconfigure < restart_agent.
+# These are dimensionless units that sum with the 1/H_t weighting used by the
+# cost heuristics; they are intentionally small and monotonic, not tuned.
+_ACTION_COST_BASE: dict[str, float] = {
+    "wait": 0.0,
+    "set_checkpoint": 0.0,
+    "inject": 1.0,
+    "inject_perturbed": 1.0,
+    "rebalance": 5.0,
+    "reconfigure": 5.0,
+    "restart_agent": 20.0,
+}
+
+
+def estimate_action_cost(
+    action: ActionSpec,
+    snapshot: Any,
+    states: dict[str, Any] | None,
+    engines: dict[str, Any] | None,
+) -> float:
+    """Return an evaluation-equivalent cost estimate for ``action``.
+
+    Deterministic and conservative: the returned value is a pure function of
+    the ActionSpec's type and of the target engine's population size when
+    relevant. It is used by orchestration diagnostics and for comparing intervention intensity.
+
+    The ordering invariant required by the spec is preserved by the base
+    table ``_ACTION_COST_BASE``.
+    """
+    if action is None or action.type is None:
+        return 0.0
+    base = float(_ACTION_COST_BASE.get(action.type, 1.0))
+
+    # Scale rebalance / restart by the target population size when we have it
+    # so larger populations cost more. We cap the multiplier so a 200-strong
+    # population does not destroy the ordering.
+    if action.type in {"rebalance", "restart_agent"}:
+        mult = 1.0
+        try:
+            target_label = getattr(action, "target_label", None)
+            if target_label and engines and states and target_label in engines:
+                eng = engines[target_label]
+                st = states[target_label]
+                if eng.capabilities.has_population:
+                    try:
+                        pop = eng.get_population(st)
+                        n = max(1, int(len(pop)))
+                        # Cost grows with sqrt(n) and is capped at 4x for
+                        # very large populations.
+                        mult = min(4.0, max(1.0, math.sqrt(n / 20.0)))
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+        base *= float(mult)
+
+    if action.type in {"inject", "inject_perturbed"}:
+        k = int(action.k or 1)
+        base *= max(1.0, float(k) / 2.0)
+
+    return float(base)