Algorithms

Every algorithm inherits from the abstract Algorithm, which provides the parameters common to every solver — evaluation budget, time limits, stopping criteria, restart count, and PRNG seed.

Numeric algorithm parameters accept either a plain number or a NumericExpression, which lets values scale with the problem size at runtime.

Algorithm base

Abstract Algorithm base class for optimisation solver configurations.

Subclasses define their own key and parameter dict; common stopping criteria (evaluation budget, time limits, restart count, PRNG seed) live on the base. Numeric parameters accept a plain number, a NumericExpression, or a model Parameter/Calculation.

class Algorithm(log_info=False, evaluations=100000, max_evaluations_without_improvement=10000, max_time_without_improvement=300, min_improvement=1e-06, max_restart_count=0, prng_seed=None, time_limit=60)

Abstract base for optimisation algorithm configurations.

log_info: bool = False

Whether the solver emits per-iteration progress logs.

evaluations: int | NumericExpression | Parameter | Calculation = 100000

Maximum total evaluations before the run terminates.

max_evaluations_without_improvement: int | NumericExpression | Parameter | Calculation = 10000

Stop after this many consecutive evaluations with no improvement.

max_time_without_improvement: int | NumericExpression | Parameter | Calculation = 300

Stop after this many seconds with no improvement.

min_improvement: float | NumericExpression | Parameter | Calculation = 1e-06

Smallest objective change counted as an improvement.

max_restart_count: int | NumericExpression | Parameter | Calculation = 0

Maximum number of restarts after stagnation.

prng_seed: int | None = None

Optional fixed seed for deterministic runs.

time_limit: int | NumericExpression | Parameter | Calculation = 60

Hard wall-clock limit in seconds.

abstract property key: str

The algorithm key emitted as algorithmKey in the serialised output.

build()

Serialise to the {algorithmKey, parameters} shape.

Return type:

dict[str, Any]

NumericExpression

Symbolic numeric expression that may depend on the NUM_VARIABLES variable.

Use this where an algorithm parameter should scale with the problem dimension; the NUM_VARIABLES token is replaced at runtime with the number of decision variables.

class NumericExpression(value)

Symbolic numeric value supporting +, -, *, / operators.

Wraps a numeric literal or an expression in the special variable NUM_VARIABLES. Operators return a new NumericExpression, so expressions compose naturally:

evals = 100_000 * NumericExpression("NUM_VARIABLES")
rate  = 1 / NumericExpression("NUM_VARIABLES")

NUM_VARIABLES: str = 'NUM_VARIABLES'

to_string()

Return the underlying expression string.

Return type:

str

is_float()

Return True if the expression is a float literal.

Return type:

bool

is_integer()

Return True if the expression is an integer literal.

Return type:

bool

is_expression()

Return True if the expression contains a variable rather than a numeric literal.

Return type:

bool

classmethod from_str(expr)

Construct from a numeric or NUM_VARIABLES string.

Return type:

NumericExpression

classmethod from_number(num)

Construct from an int or float literal.

Return type:

NumericExpression

classmethod variable(name)

Construct from a variable name. Currently only NUM_VARIABLES is supported.

Return type:

NumericExpression