variopt

variopt is a typed optimization package for structured search spaces, canonical candidates, and explicit execution boundaries.

See CHANGELOG.md for user-visible changes, docs/reference/stability.md for the public-API stability policy, and docs for the user-facing guide.

Quickstart

from variopt import IntegerSpace, OptimizationDirection, Problem, Study
from variopt.algorithms.population import CSAOptimizer
from variopt.evaluators import SequentialEvaluator


def square(candidate: int) -> float:
    return float(candidate * candidate)


space = IntegerSpace(-10, 10)

problem = Problem(
    space=space,
    objective=square,
    direction=OptimizationDirection.MINIMIZE,
)

optimizer = CSAOptimizer.from_space_defaults(
    space=space,
    bank_capacity=8,
    random_state=0,
)

study = Study(
    problem=problem,
    run_method=optimizer,
    evaluator=SequentialEvaluator[int, int](),
)

result, final_state = study.optimize(max_evaluations=40)

best = result.best_observation
print(f"best candidate: {best.candidate}, value: {best.value}")

Study.optimize(...) is the scalar optimization convenience path and returns a RunResult. When a problem uses a non-scalar EvaluationProtocol, use Study.run(...) instead to get a generic RunReport.

Problem accepts either a typed scalar callable or an explicit Objective implementation. Prefer a picklable, importable module-level function when the problem may cross a process or MPI boundary; lambdas, closures, bound methods, and stateful callable objects are not guaranteed to be portable across every evaluator backend.

Evaluator Backends

For batch-parallel local execution, use the joblib-backed evaluator included in the core install:

from variopt.evaluators import JoblibEvaluator

study = Study(
    problem=problem,
    run_method=optimizer,
    evaluator=JoblibEvaluator[int, int](
        backend="threading",
        n_jobs=4,
    ),
)

For MPI-backed batch execution, install the optional mpi extra (pip install "variopt[mpi]") and use MpiEvaluator.

Synchronous SequentialEvaluator and JoblibEvaluator can also execute eligible bounded local-search episodes per proposal. See Evaluator-Owned Local-Search Episodes for dispatch, hard-budget, failure, reproducibility, and performance guidance.

Documentation

The full documentation is organized as:

• Getting Started — installation, introduction, and quickstart
• Tutorials — worked end-to-end examples
• How-To Guides — task-oriented guidance for choosing optimizers, evaluators, presets, and local-search methods
• Concepts — the model behind the API: spaces, problems, execution models, and algorithm families
• Reference — API surface, presets, checkpointing, glossary, and stability policy

Key Entry Points

Goal	Start here
Smallest runnable example	Quickstart
End-to-end walkthrough	First Optimization Run
Structured (record/tuple/array) spaces	Structured Spaces
Pick an optimizer family	Choose an Optimizer
CSA preset and profile customization	Customize an Optimizer Profile
Local-search kernel guidance	Local Optimization Methods
Parallel bounded local search	Evaluator-Owned Local-Search Episodes
Candidate refinement provenance	Candidate Refinement
Non-scalar / multi-objective patterns	Canonical Usage Patterns
Public API reference	API Surface