daitum-configuration

Builder library for the Daitum platform’s model-configuration JSON.

A ConfigurationBuilder composes an algorithm, a model configuration (decision variables, objectives, constraints), data sources, schedule, and report/model properties; ConfigurationBuilder.write_to_file() emits model-configuration.json.

class ConfigurationBuilder

Builder for a complete model configuration.

Use set_* methods to attach the algorithm, model configuration, schedule, and model property; use add_* methods to register data sources and report properties; call write_to_file() to emit model-configuration.json.

set_algorithm(algorithm)

Set the top-level algorithm. Mutually exclusive with a schedule.

Return type:

ConfigurationBuilder

set_model_configuration(model_configuration)

Set the ModelConfiguration (decision variables, objectives, constraints).

Return type:

ConfigurationBuilder

set_schedule_configuration(schedule_configuration)

Set a multi-step schedule. Mutually exclusive with a single algorithm.

Return type:

ConfigurationBuilder

set_solution_view_allowed(solution_view_allowed)

Set whether the solution-view feature is permitted for this model.

Return type:

ConfigurationBuilder

set_solution_view_enabled(solution_view_enabled)

Set whether the solution view is enabled by default when allowed.

Return type:

ConfigurationBuilder

add_report_property(key, report_property)

Register a ReportProperty under the given key.

Return type:

ConfigurationBuilder

set_model_property(calculate_on_load=True, calculation_enabled=True, ignore_formula=False, import_options=None, overlay_config=None)

Construct and attach a ModelProperty from the given flags and configurations.

Return type:

ConfigurationBuilder

add_excel_transform(name, config)

Register an Excel-transform data source and return its DataSource wrapper for further customisation (e.g. set_post_optimise).

Return type:

DataSource

add_model_transform(name, config)

Register a model-transform data source. See add_excel_transform() for the return value.

Return type:

DataSource

add_data_store(name, config)

Register a data-store data source. See add_excel_transform() for the return value.

Return type:

DataSource

add_batched_data_source(name, config)

Register a batched data source bundling other data sources. See add_excel_transform() for the return value.

Return type:

DataSource

add_report_data_source(name, report_name)

Register a data source that feeds rows from a previously-run report. See add_excel_transform() for the return value.

Return type:

DataSource

add_external_model_data_source(name)

Register a data source that runs the model’s configured external evaluator. Input, parameter, and output mappings are declared on ExternalModelConfiguration. See add_excel_transform() for the return value.

Return type:

DataSource

add_distance_matrix(name, config)

Register a distance-matrix data source. See add_excel_transform() for the return value.

Return type:

DataSource

add_set_features(name, config)

Register a feature-flag data source. See add_excel_transform() for the return value.

Return type:

DataSource

add_geo_location(name, config)

Register a geocoding data source. See add_excel_transform() for the return value.

Return type:

DataSource

write_to_file(model_directory)

Serialise this configuration into model-configuration.json under model_directory, creating the directory if it does not exist.

Return type:

None

class GeneticAlgorithm(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, mutation_rate=(1 / NUM_VARIABLES), recombinator_rate=0.8, population_size=NUM_VARIABLES, elitism=1, mutation=<factory>, recombinator=RecombinatorType.UNIFORM_CROSSOVER, n_point_cuts=None, selection=<factory>, comparator=None, tiebreaker=False, distance_metric=DistanceMetricType.EUCLIDEAN_DISTANCE, sample_count=0, sampling_method=SamplingMethodType.UNIFORM_RANDOM)

Population-based evolutionary algorithm.

mutation_rate: float | NumericExpression | Parameter | Calculation = (1 / NUM_VARIABLES)

Probability of mutating an offspring (0–1).

recombinator_rate: float | NumericExpression | Parameter | Calculation = 0.8

Probability of applying crossover (0–1).

population_size: int | NumericExpression | Parameter | Calculation = NUM_VARIABLES

Number of individuals in the population.

elitism: int | NumericExpression | Parameter | Calculation = 1

Number of top individuals copied unchanged into the next generation.

mutation: Mutation

Mutation operator.

recombinator: RecombinatorType = 'Uniform crossover'

Crossover strategy.

n_point_cuts: int | NumericExpression | Parameter | Calculation | None = None

Number of crossover points; auto-set for N-point crossover.

selection: Selection

Selection operator.

comparator: ComparatorType | None = None

Optional solution comparator for multi-objective runs.

tiebreaker: bool = False

Apply a diversity-aware tiebreaker on equal objective values.

distance_metric: DistanceMetricType = 'Euclidean distance'

Distance metric for diversity-aware operators.

sample_count: int | NumericExpression | Parameter | Calculation = 0

Initial-sample count for sampling-based seeding.

sampling_method: SamplingMethodType = 'Uniform random'

Initial-population sampling method.

property key: str

The algorithm key emitted as algorithmKey in the serialised output.

class RecombinatorType(*values)

Crossover strategies for combining parent solutions.

UNIFORM_CROSSOVER = 'Uniform crossover'

N_POINT_CROSSOVER = 'N-point crossover'

class ComparatorType(*values)

Solution-comparison strategy for multi-objective optimisation.

LEXICOGRAPHIC_COMPARATOR = 'Lexicographic comparator'

WEIGHTED_OBJECTIVE_COMPARATOR = 'Weighted objective lexicographic comparator'

SAMPLE_WEIGHTED_OBJECTIVE_COMPARATOR = 'Weighted objective online lexicographic comparator'

USER_WEIGHTED_OBJECTIVE_COMPARATOR = 'User weighted objective comparator'

LEXICOGRAPHIC_ONLINE_WEIGHTED_OBJECTIVE_COMPARATOR = 'Lexicographic online weighted objective comparator'

class MutationType(*values)

Mutation strategy used to perturb individual solutions.

GAUSSIAN_MUTATION = 'Gaussian mutation'

UNIFORM_MUTATION = 'Uniform mutation'

class SelectionType(*values)

Strategy for selecting individuals from the population.

TOURNAMENT_SELECTION = 'Tournament selection'

FAST_TOURNAMENT_SELECTION = 'Fast tournament selection'

RANDOM_SELECTION = 'Random selection'

class DistanceMetricType(*values)

Distance metric used for diversity-aware operators.

EUCLIDEAN_DISTANCE = 'Euclidean distance'

HAMMING_DISTANCE = 'Manhattan distance'

class SamplingMethodType(*values)

Method used to generate the initial population.

UNIFORM_RANDOM = 'Uniform random'

LATIN_HYPERCUBE = 'Latin Hypercube'

class Mutation(name, parameters)

A mutation operator: a MutationType plus its operator-specific parameters.

name: MutationType

parameters: dict[str, Any]

classmethod mutation(name=None, variation_range=None)

Construct a Mutation with default operator parameters.

Parameters:

• name (MutationType | None) – Mutation strategy. Defaults to UNIFORM_MUTATION.

• variation_range (float | NumericExpression | None) – Variation magnitude for uniform mutation. Must be non-negative.

Return type:

Mutation

class Selection(name, parameters)

A selection operator: a SelectionType plus its operator-specific parameters.

name: SelectionType

parameters: dict[str, Any]

classmethod selection(name=None, pool_size=None)

Construct a Selection with default operator parameters.

Parameters:

• name (SelectionType | None) – Selection strategy. Defaults to FAST_TOURNAMENT_SELECTION.

• pool_size (int | NumericExpression | None) – Tournament pool size. Must be at least 2.

Return type:

Selection

class CMAESAlgorithm(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, population_size=NUM_VARIABLES, consistency_check=False, cc=4 / NUM_VARIABLES, cs=2 / NUM_VARIABLES, damps=1 + 2 / NUM_VARIABLES, ccov=1 / NUM_VARIABLES, ccovsep=1 / NUM_VARIABLES * NUM_VARIABLES, sigma=0.5, diagonal_iterations=NUM_VARIABLES)

Covariance Matrix Adaptation Evolution Strategy.

population_size: int | NumericExpression | Parameter | Calculation = NUM_VARIABLES

Number of candidate solutions per generation.

consistency_check: bool = False

Enable internal consistency assertions.

cc: float | NumericExpression | Parameter | Calculation = (4 / NUM_VARIABLES)

Covariance-matrix cumulation constant.

cs: float | NumericExpression | Parameter | Calculation = (2 / NUM_VARIABLES)

Step-size cumulation constant.

damps: float | NumericExpression | Parameter | Calculation = (1 + (2 / NUM_VARIABLES))

Damping factor for step-size control.

ccov: float | NumericExpression | Parameter | Calculation = (1 / NUM_VARIABLES)

Learning rate for the covariance-matrix update.

ccovsep: float | NumericExpression | Parameter | Calculation = (1 / (NUM_VARIABLES * NUM_VARIABLES))

Learning rate for the separable update.

sigma: float | NumericExpression | Parameter | Calculation = 0.5

Initial step size.

diagonal_iterations: int | NumericExpression | Parameter | Calculation = NUM_VARIABLES

Iterations using the diagonal-only update before the full update.

property key: str

The algorithm key emitted as algorithmKey in the serialised output.

class SteepestDynamicLocalSearch(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, allow_neutral_walks=False, integer_step_size=10, decimal_step_size=0.1, integer_step_change=1, integer_lowest_step=1, decimal_step_change=0.001, decimal_lowest_step=0.001)

Steepest Descent local search with a dynamic step-size schedule.

Each iteration perturbs every decision variable by ±``step_size`` and accepts the best neighbour. integer_step_size applies to integer-typed variables; decimal_step_size applies to real-typed variables. When an iteration finds no improvement the step shrinks toward ..._lowest_step by ..._step_change; once at the lowest step with no further improvement the search terminates (subject to the base stopping criteria inherited from Algorithm).

allow_neutral_walks permits accepting equal-objective neighbours, letting the search drift across plateaus.

allow_neutral_walks: bool = False

Accept neighbours with equal objective value (plateau drift).

integer_step_size: int | NumericExpression | Parameter | Calculation = 10

Initial perturbation magnitude for integer-typed variables.

decimal_step_size: float | NumericExpression | Parameter | Calculation = 0.1

Initial perturbation magnitude for real-typed variables.

integer_step_change: int | NumericExpression | Parameter | Calculation = 1

Amount by which the integer step is reduced after a non-improving iteration.

integer_lowest_step: int | NumericExpression | Parameter | Calculation = 1

Floor below which the integer step will not shrink.

decimal_step_change: float | NumericExpression | Parameter | Calculation = 0.001

Amount by which the decimal step is reduced after a non-improving iteration.

decimal_lowest_step: float | NumericExpression | Parameter | Calculation = 0.001

Floor below which the decimal step will not shrink.

property key: str

The algorithm key emitted as algorithmKey in the serialised output.

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

class ConstraintType(*values)

Constraint operator.

Values:

EQUALITY: The expression must equal the bound. INEQUALITY: The expression must lie within the lower/upper bounds.

EQUALITY = 'equality'

INEQUALITY = 'inequality'

class DVType(*values)

Domain of a decision variable.

Values:

RANGE: Discrete integer in a contiguous range. LIST: Discrete integer drawn from an allowed list. REAL: Continuous floating-point value.

RANGE = 'range'

LIST = 'list'

REAL = 'real'

class Priority(*values)

Lexicographic priority for an objective or constraint.

LOW = 'LOW'

MEDIUM = 'MEDIUM'

HIGH = 'HIGH'

class MetricCombinationRule(*values)

Rule for combining a metric across multiple stochastic trials.

MIN = 'MIN'

MAX = 'MAX'

MEAN = 'MEAN'

PVALUE_MAX = 'PVALUE_MAX'

PVALUE_MIN = 'PVALUE_MIN'

class StochasticConfiguration(runs, p, disable_evaluator_caching)

Configures the solver to run multiple evaluations per candidate solution.

Parameters:

• runs (int) – Number of evaluations per candidate.

• p (float) – Confidence level used by the p-value-based combination rules.

• disable_evaluator_caching (bool) – When True, force fresh evaluation each run instead of using the evaluator’s cache.

metric_rules: dict[str, MetricCombinationRule]

add_metric_rule(key, metric_rule)

Register a per-metric MetricCombinationRule.

Return type:

StochasticConfiguration

class ModelConfiguration

Decision variables, objectives, constraints, and solver-level flags for one model.

set_disable_seed_solution(disable_seed_solution)

Disable the seed solution loaded from input data.

Return type:

ModelConfiguration

set_calculated_seed(calculated_seed)

Enable computing the seed solution from formulas instead of input data.

Return type:

ModelConfiguration

set_validation_enabled(validation_enabled)

Enable or disable validators on the input data.

Return type:

ModelConfiguration

set_profiling(profiling)

Enable solver-side performance profiling.

Return type:

ModelConfiguration

set_hide_objective_when_infeasible(hide_objective_when_infeasible)

Hide objective values from the UI when the solution is infeasible.

Return type:

ModelConfiguration

set_stochastic_configuration(stochastic_configuration)

Attach a StochasticConfiguration for multi-trial evaluation.

Return type:

ModelConfiguration

set_external_configuration(custom_evaluator_version, custom_evaluator_key, external_configuration)

Route evaluation through an external evaluator with the given version, key, and ExternalModelConfiguration mappings.

Return type:

ModelConfiguration

add_decision_variable(dv, dv_table=None, dv_type=DVType.RANGE)

Register a decision variable.

Parameters:

• dv (Parameter | Field) – A model Parameter (model-level DV) or a DataField (per-row DV).

• dv_table (Table | None) – The DataTable for a per-row DV. None for a model-level DV.

• dv_type (DVType) – DVType controlling the variable’s domain.

Return type:

DecisionVariable

Returns:

The new DecisionVariable; chain .set_min(...) and .set_max(...) to bound it.

add_objective(objective, maximise=False, priority=Priority.HIGH, weight=1.0, name=None)

Register an Objective.

Parameters:

• objective (Calculation | Parameter) – Numeric Calculation to optimise.

• maximise (bool) – Direction of optimisation. Defaults to minimise.

• priority (Priority) – Lexicographic Priority for multi-objective runs.

• weight (float) – Objective weight when combining via a weighted comparator.

• name (str | None) – Optional display name.

Return type:

Objective

add_constraint(constraint)

Register a Constraint over a numeric calculation.

Returns the new Constraint; chain .set_type(...) and .set_lower_bound(...)/.set_upper_bound(...) to configure it.

Return type:

Constraint

add_scenario_output(name, scenario_output_value, scenario_output_table=None)

Register a ScenarioOutput exposed in scenario comparison.

Raises:

ValueError – If name or the resolved cell reference duplicates an existing scenario output.

Return type:

ScenarioOutput

class ModelImportOptions

Default import behaviour applied to every data source on the model.

Construct with default flags, then customise via the chained set_* methods.

set_match_column_count(match_column_count)

Reject imports whose column count differs from the target.

Return type:

ModelImportOptions

set_expected_column_count(expected_column_count)

Set the column count enforced when match_column_count is True.

Return type:

ModelImportOptions

set_match_column_headers(match_column_headers)

Reject imports whose column headers differ from the target.

Return type:

ModelImportOptions

set_preserve_ordering(preserve_ordering)

Preserve source row order in the target.

Return type:

ModelImportOptions

set_match_existing_rows(match_existing_rows)

Match incoming rows against existing rows by key_column.

Return type:

ModelImportOptions

set_clear_sheet(clear_sheet)

Clear the sheet before writing imported rows.

Return type:

ModelImportOptions

set_reset_decisions(reset_decisions)

Reset decision-variable values on matched rows.

Return type:

ModelImportOptions

set_close_on_success(close_on_success)

Auto-close the import dialog on successful import.

Return type:

ModelImportOptions

set_skip_pre_processors(skip_pre_processors)

Skip configured pre-processors during import.

Return type:

ModelImportOptions

set_key_column(key_column)

Set the column used to match incoming rows against existing ones.

Return type:

ModelImportOptions

set_locale_key(locale_key)

Set the locale used to parse incoming numbers, dates, and currency.

Return type:

ModelImportOptions

set_sync_key(sync_key)

Set the per-user synchronisation key used by generate_sync_key().

Return type:

ModelImportOptions

get_sync_key()

Return the sync key, or an empty string if unset or whitespace.

Return type:

str

generate_sync_key(user)

Build a per-user sync key in the form "<user_id>/<sync_key>".

Parameters:

user – Object exposing an id attribute.

Return type:

str

class OverlayConfig(show_decision_overlay=False, show_lock_overlay=False, show_objective_overlay=False, show_constraint_overlay=False)

Toggles for spreadsheet overlays that surface solver state in the UI.

Parameters:

• show_decision_overlay (bool) – Highlight cells driven by decision variables.

• show_lock_overlay (bool) – Highlight cells locked at their seed value.

• show_objective_overlay (bool) – Highlight cells contributing to objectives.

• show_constraint_overlay (bool) – Highlight cells contributing to constraints.

class ReportExportFormat(*values)

File format produced when a report is exported.

XLSX = 'XLSX'

CSV = 'CSV'

JSON = 'JSON'

MSDOS = 'MSDOS'

class ReportData(required_sheets=None, requires_monte_carlo=False, requires_scenario_comparison=False)

Sheet and feature prerequisites for one report.

Parameters:

• required_sheets (set[str] | None) – Sheet names that must be present for the report to run.

• requires_monte_carlo (bool) – Whether the report depends on Monte Carlo output.

• requires_scenario_comparison (bool) – Whether the report depends on scenario comparison output.

build()

Serialise to a JSON-compatible dict (the required-sheets set becomes a list).

Return type:

dict[str, Any]

class StepType(*values)

Kind of node in a ScheduleConfiguration execution tree.

A StepConfiguration’s type determines whether it executes an algorithm (leaf) or composes child steps (container).

Values:

SINGLE: Leaf node — runs the algorithm registered under

algorithm_config_key against the current best solution. Carries no children.

SEQUENCE: Container — runs child steps one after another, each

seeded with the previous step’s best solution.

PARALLEL: Container — runs child steps concurrently from the same

seed and merges their results.

PARALLEL = 'PARALLEL'

SEQUENCE = 'SEQUENCE'

SINGLE = 'SINGLE'

class StepConfiguration(step_type, algorithm_config_key=None)

One node in a ScheduleConfiguration execution tree.

A step is either a leaf — StepType.SINGLE referencing an algorithm by key — or a container — StepType.PARALLEL or StepType.SEQUENCE — holding child steps. Containers may nest arbitrarily.

Subproblem and execution behaviour are configured via chained add_* / set_* methods after construction. Each maps to one subproblem feature:

• add_included_tag() — restrict the step to a subset of decision variables by tag (see DecisionVariable.set_tag_source).

• add_override_parameter() — set model parameter values for the duration of this step.

• set_split_values_key() — split the step into independent parallel subproblems based on a comma-separated model value.

• set_recalculate_ranges() — narrow decision-variable bounds based on current model state before executing this step.

• set_disabled_key() — skip the step when a model value equals "true".

• set_deferred() — delay step construction until just before execution; required when the configuration above depends on results of earlier steps.

All six fields and add_step return self for fluent chaining.

Parameters:

• step_type (StepType) – StepType of this node.

• algorithm_config_key (str | None) – Algorithm key resolved against ScheduleConfiguration.add_algorithm(). Required for SINGLE; forbidden for container types. Container children are appended via add_step().

Raises:

ValueError – If algorithm_config_key does not match step_type.

Example:

from daitum_configuration import StepConfiguration, StepType

# A SEQUENCE: per-day separable optimisation, then a full
# optimisation with narrowed ranges, then an optional refinement.
root = StepConfiguration(StepType.SEQUENCE)
root.add_step(
    StepConfiguration(StepType.SINGLE, algorithm_config_key="ga")
    .set_split_values_key("DayOfWeek")
    .add_included_tag("PerDay")
    .add_override_parameter("dailyOptimisation", "true")
)
root.add_step(
    StepConfiguration(StepType.SINGLE, algorithm_config_key="ga")
    .set_deferred(True)
    .set_recalculate_ranges(True)
)
root.add_step(
    StepConfiguration(StepType.SINGLE, algorithm_config_key="ls")
    .set_disabled_key("skipRefinement")
)

add_step(step_configuration)

Append a child step to this container.

Raises:

ValueError – If this node is StepType.SINGLE.

Return type:

StepConfiguration

add_included_tag(tag)

Append a tag to the variable filter for this step.

Only decision variables whose tags are all in included_tags are optimised; variables with no tags are always included. Excluded variables are held at their seed values. Adding the same tag twice is a no-op.

Variable tags are sourced via DecisionVariable.set_tag_source.

Return type:

StepConfiguration

add_override_parameter(key, value)

Add a model parameter override applied during this step.

key is a parameter name and value is a serialised model value. Overrides are applied before each evaluation in this step; the model is fully re-evaluated, so override targets need not lie on decision-dependent paths. Adding the same key twice replaces the previous value. Step-scoped overrides take precedence over ScheduleConfiguration.add_global_parameter.

Return type:

StepConfiguration

set_split_values_key(split_values_key)

Split this step into independent subproblems by model value.

split_values_key is a model reference returning a comma-separated string (for example "North,South,East,West"). One subproblem is run per value, with the value appended to included_tags so each subproblem optimises a disjoint slice of decision variables. Subproblem variable sets must not overlap.

Return type:

StepConfiguration

set_recalculate_ranges(recalculate_ranges)

Narrow decision-variable bounds from current model state.

When True, the platform reads each variable’s range fields against the current best solution and any applied parameter overrides, then builds the subproblem with the resulting bounds. The new bounds must be a subset of the original. Variables with empty new ranges are excluded; single-value ranges are fixed.

Commonly combined with set_deferred() so the recalculation happens after earlier steps have shaped the current best solution.

Return type:

StepConfiguration

set_disabled_key(disabled_key)

Conditionally skip this step based on a model value.

disabled_key is a model reference; when its serialised value equals "true" the step is replaced with an empty pass-through and the current best solution flows through unchanged.

Return type:

StepConfiguration

set_deferred(deferred)

Delay step construction until just before execution.

Required when any of add_included_tag(), add_override_parameter(), set_split_values_key(), set_recalculate_ranges(), or set_disabled_key() depends on results produced by earlier steps. When deferred, the current best solution is passed in as the seed for evaluating those model references.

Return type:

StepConfiguration

class ScheduleConfiguration(schedule_root)

Multi-step optimisation schedule.

Pairs a named map of Algorithm instances with a StepConfiguration tree that references them by key. The tree is the execution plan; the map supplies the algorithms each StepType.SINGLE leaf invokes.

Algorithms are registered via add_algorithm(). The key argument is the same string that a SINGLE StepConfiguration passes as its algorithm_config_key. Schedule-wide parameter overrides are registered via add_global_parameter(); step-scoped overrides on individual steps take precedence (see StepConfiguration.add_override_parameter()).

Attach a built schedule to a ConfigurationBuilder with set_schedule_configuration() — mutually exclusive with set_algorithm().

Example:

from daitum_configuration import (
    GeneticAlgorithm,
    ScheduleConfiguration,
    StepConfiguration,
    StepType,
)

root = StepConfiguration(StepType.SINGLE, algorithm_config_key="ga")
schedule = (
    ScheduleConfiguration(root)
    .add_algorithm("ga", GeneticAlgorithm())
    .add_global_parameter("seed", "42")
)

Parameters:

schedule_root (StepConfiguration) – Root step of the execution tree. Required.

add_algorithm(key, algorithm)

Register an Algorithm under key.

key is the same string a SINGLE StepConfiguration passes as its algorithm_config_key to invoke this algorithm. Every algorithm_config_key referenced anywhere in the schedule tree must resolve to a key registered here. Adding the same key twice replaces the previous algorithm.

Return type:

ScheduleConfiguration

add_global_parameter(key, value)

Add a parameter override applied across every step in the schedule.

key is a parameter name and value is a serialised model value. Adding the same key twice replaces the previous value. Step-scoped overrides set via StepConfiguration.add_override_parameter() take precedence over these globals for the steps on which they’re set.

Return type:

ScheduleConfiguration

class ExcelTransformConfig(file_key, file_name, sheet_mapping)

Data source that imports rows from an Excel workbook.

Parameters:

• file_key (str) – Internal storage key identifying the workbook file.

• file_name (str) – Display-facing file name shown in the UI.

• sheet_mapping (list[tuple[str, str]]) – (source_sheet, target_sheet) pairs feeding model tables.

set_debug_file(debug_file)

Emit a debug copy of the imported workbook.

Return type:

ExcelTransformConfig

set_manual_sheet_names(manual_sheet_names)

Resolve sheet names manually rather than via the configured mapping.

Return type:

ExcelTransformConfig

set_import_object_references_as_keys(import_object_references_as_keys)

Treat object-reference cells as raw keys instead of resolved objects.

Return type:

ExcelTransformConfig

set_per_sheet_overrides(per_sheet_overrides)

Override import options per source sheet name.

Return type:

ExcelTransformConfig

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class ImportOptionOverrides(match_column_count=False, match_column_headers=False, match_existing_rows=False, preserve_ordering=False)

Per-sheet overrides for column matching, ordering, and row reconciliation.

Parameters:

• match_column_count (bool) – Reject the import if the column count differs.

• match_column_headers (bool) – Reject the import if column headers differ.

• match_existing_rows (bool) – Match incoming rows to existing rows by key.

• preserve_ordering (bool) – Preserve the source row order in the target.

set_clear_sheet(clear_sheet)

Clear the sheet before writing imported rows.

Return type:

ImportOptionOverrides

set_reset_decisions(reset_decisions)

Reset decision-variable values for any matched rows on import.

Return type:

ImportOptionOverrides

set_expected_column_count(expected_column_count)

Set the column count enforced when match_column_count is True.

Return type:

ImportOptionOverrides

set_key_column(key_column)

Set the column used to match incoming rows against existing ones.

Return type:

ImportOptionOverrides

class ModelTransform(model_builder)

Sub-model that produces output tables consumed by a ModelTransformConfig.

Parameters:

model_builder (ModelBuilder) – The sub-model whose tables are mapped onto target-model tables via add_output_table().

add_output_table(sub_model_table, model_table, field_mapping=None)

Route rows from sub_model_table into model_table.

Parameters:

• sub_model_table (Table) – Source table inside the sub-model.

• model_table (Table) – Destination table in the parent model.

• field_mapping (dict[str, str] | None) – Map of sub-model field id to parent-model field id. When omitted, fields with matching ids are auto-paired (data and combo fields only).

Return type:

ModelTransform

build()

Serialise to a JSON-compatible dict including the embedded sub-model.

Return type:

dict[str, Any]

class ModelTransformConfig(file_key, file_name, debug_file=False)

Data source that runs a secondary model and feeds its outputs back into the parent.

Inputs to the secondary model are registered via the add_*_input methods.

Parameters:

• file_key (str) – Storage key identifying the secondary-model file.

• file_name (str) – Display-facing file name for the secondary model.

• debug_file (bool) – Emit a debug copy of the transform inputs/outputs.

add_dynamic_values(timezone_key)

Inject current-time/date variants as inputs.

Parameters:

timezone_key (Parameter | Calculation | None) – Optional model named value of type STRING supplying an IANA timezone for non-UTC time variants.

Return type:

ModelTransformConfig

add_datastore_input(data_store_key, tables, model_filter=None, direct_data_pull=False)

Register a data-store input feeding the secondary model.

Return type:

ModelTransformConfig

add_datastore_interface_input(data_store_key, tables, model_filter=None, direct_data_pull=False)

Register a data-store-interface input feeding the secondary model.

Return type:

ModelTransformConfig

add_direct_upload_input(tables, missing_header_severity=ValidationSeverity.ERROR, unexpected_header_severity=ValidationSeverity.ERROR)

Register a direct-upload (CSV) input feeding the secondary model.

missing_header_severity and unexpected_header_severity control how header mismatches at upload time are surfaced; both default to ValidationSeverity.ERROR.

Return type:

ModelTransformConfig

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class ValidationSeverity(*values)

How a header-validation issue should be surfaced when running a model transform input.

Used on every ModelTransformInput for both the missing header and unexpected header checks.

ERROR = 'ERROR'

Treat as a hard error — block the file upload and surface in the validation dialog.

WARNING = 'WARNING'

Surface in the validation dialog but allow the import to proceed.

IGNORE = 'IGNORE'

Suppress entirely — neither block nor display.

class DataStoreConfig(data_store_key, tables)

Data source that reads rows from a stored dataset.

Apply a DataFilter via set_model_filter() to restrict which rows are imported.

Parameters:

• data_store_key (str) – Key of the data store to read from.

• tables (dict[str, str]) – Mapping from local model table name to the source table name.

set_model_filter(model_filter)

Apply a row-level DataFilter to narrow the rows pulled in.

Return type:

DataStoreConfig

set_debug_file(debug_file)

Emit a debug copy of the imported data.

Return type:

DataStoreConfig

set_using_interface(using_interface)

Read through the data store’s interface layer rather than directly.

Return type:

DataStoreConfig

set_direct_data_pull(direct_data_pull)

Bypass any caching layer and pull rows directly each import.

Return type:

DataStoreConfig

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class EqualityDataFilter(path, source_key, value=None)

Match rows whose value at path equals the value resolved from source_key.

Parameters:

• path (list[str]) – Field path within each source row (e.g. ["address", "country"]).

• source_key (Parameter | Calculation) – Model named value supplying the comparison value.

• value (str | None) – Optional literal value emitted alongside the resolved key.

property type: DataFilterType

The DataFilterType discriminator for this filter.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class InequalityDataFilter(path, lower_key, upper_key, lower=None, upper=None)

Match rows whose numeric value at path falls within a range.

Parameters:

• path (list[str]) – Field path within each source row.

• lower_key (float | Parameter | Calculation) – Lower bound source — a literal or model named value.

• upper_key (float | Parameter | Calculation) – Upper bound source — a literal or model named value.

• lower (float | None) – Optional literal lower-bound value emitted alongside the key.

• upper (float | None) – Optional literal upper-bound value emitted alongside the key.

property type: DataFilterType

The DataFilterType discriminator for this filter.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class RegexDataFilter(path, source_key, value=None)

Match rows whose value at path matches the regex resolved from source_key.

Parameters:

• path (list[str]) – Field path within each source row.

• source_key (Parameter | Calculation) – Model named value supplying the regex pattern.

• value (str | None) – Optional literal regex string emitted alongside the key.

property type: DataFilterType

The DataFilterType discriminator for this filter.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class SetDataFilter(path, source_keys, values=None)

Match rows whose value at path is in a set of values resolved from source_keys.

Parameters:

• path (list[str]) – Field path within each source row.

• source_keys (list[Parameter | Calculation]) – Model named values supplying the allowed values.

• values (set[str] | None) – Optional literal value set emitted alongside the keys.

property type: DataFilterType

The DataFilterType discriminator for this filter.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class WildcardDataFilter(path, source_key, value=None, case_sensitive=False)

Match rows whose value at path matches the glob pattern resolved from source_key.

Parameters:

• path (list[str]) – Field path within each source row.

• source_key (Parameter | Calculation) – Model named value supplying the glob pattern.

• value (str | None) – Optional literal pattern emitted alongside the key.

• case_sensitive (bool) – Whether matching is case sensitive.

property type: DataFilterType

The DataFilterType discriminator for this filter.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class BatchedDataSourceConfig(run_after_import_sheet=None)

A data source that runs other data sources in a configured order.

Parameters:

run_after_import_sheet (str | None) – Optional sheet name whose import triggers this batch.

add_data_source(data_source, order, batch_data_source_type=BatchDataSourceType.NONE_PARALLEL)

Add data_source to this batch with the given execution order and BatchDataSourceType.

Return type:

BatchedDataSourceConfig

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class DataSourceInfo(data_source, order, batch_data_source_type=BatchDataSourceType.NONE_PARALLEL)

One DataSource reference inside a BatchedDataSourceConfig.

Parameters:

• data_source (DataSource) – The data source to include in the batch.

• order (int) – Execution order within the batch (lower runs first).

• batch_data_source_type (BatchDataSourceType) – Position within any surrounding parallel block.

class BatchDataSourceType(*values)

Position of a batched-data-source step in a parallel block.

START_PARALLEL = 'START_PARALLEL'

First step of a parallel block.

NEXT_PARALLEL = 'NEXT_PARALLEL'

Subsequent step inside a parallel block.

END_PARALLEL = 'END_PARALLEL'

Final step of a parallel block.

NONE_PARALLEL = 'NONE_PARALLEL'

Sequential step (no parallel block).

class DistanceMatrixConfig(from_sheet_name, from_longitude_column, from_latitude_column, outputs)

Computes a matrix of distances/durations between origin and destination points.

Configure destinations via set_to_sheet(). By default the destination sheet is the same as the origin sheet (square matrix). Each entry in outputs defines where one metric is written.

Parameters:

• from_sheet_name (str) – Source sheet for origin rows.

• from_longitude_column (str) – Origin-row longitude column name.

• from_latitude_column (str) – Origin-row latitude column name.

• outputs (list[OutputMatrix]) – One OutputMatrix per metric to produce.

set_to_sheet(to_sheet_name, to_longitude_column, to_latitude_column)

Set the destination sheet name and longitude/latitude columns.

Return type:

DistanceMatrixConfig

set_from_table_name(from_table_name)

Set the structured-table name for origin rows (alternative to a sheet name).

Return type:

DistanceMatrixConfig

set_to_table_name(to_table_name)

Set the structured-table name for destination rows.

Return type:

DistanceMatrixConfig

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class OutputMatrix(sheet_name, named_range, metric)

Where one metric of a DistanceMatrixConfig is written.

Parameters:

• sheet_name (str) – Target sheet name for the output matrix.

• named_range (str) – Named range within the sheet receiving the values.

• metric (Metric) – Which Metric this output records.

class Metric(*values)

Distance-matrix output metric.

DRIVING_DISTANCE = 'DRIVING_DISTANCE'

Driving distance along the route.

DRIVING_TIME = 'DRIVING_TIME'

Driving time along the route.

class GeoLocationConfig(sheet_name, address_column, longitude_column, latitude_column)

Geocodes address rows and writes longitude/latitude back into the same sheet.

Parameters:

• sheet_name (str) – Source sheet containing the address rows.

• address_column (str) – Column name supplying the free-text address.

• longitude_column (str) – Column receiving the geocoded longitude.

• latitude_column (str) – Column receiving the geocoded latitude.

set_table_name(table_name)

Use a structured table rather than a sheet for the source rows.

Return type:

GeoLocationConfig

set_preserve_existing_data(preserve)

Skip geocoding rows that already have coordinates.

Return type:

GeoLocationConfig

set_latitude_bounds(lower, upper)

Reject geocoded latitudes outside the given bounds.

Return type:

GeoLocationConfig

set_longitude_bounds(lower, upper)

Reject geocoded longitudes outside the given bounds.

Return type:

GeoLocationConfig

set_region(region)

Bias the geocoder towards a region (e.g., "AU").

Return type:

GeoLocationConfig

set_live_update(live_update)

Re-geocode immediately when the address column changes in the UI.

Return type:

GeoLocationConfig

set_run_on_data_import(run)

Run geocoding automatically as part of data import.

Return type:

GeoLocationConfig

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class SetFeaturesConfig(feature_settings=None)

Toggles named feature flags when the data source runs.

Parameters:

feature_settings (dict[str, bool] | None) – Map of feature key to enabled flag.

property type: DataSourceType

The DataSourceType discriminator for this configuration.

class VariableNeighbourhoodSearch(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, initial_mutation_rate=(1 / NUM_VARIABLES), minimum_mutation_rate=(1 / NUM_VARIABLES), maximum_mutation_rate=1.0, mutation_rate_tau=0.5, offspring_size=64, population_size=NUM_VARIABLES, mutation=<factory>, selection=<factory>)

Variable Neighbourhood Search — a (μ+λ) evolutionary algorithm with a self-adapting mutation rate.

Each individual carries its own mutation rate as part of its genome. When producing offspring, the rate is perturbed by a lognormal step:

\[\text{childRate} = \text{parentRate} \times \exp(\tau \cdot \mathcal{N}(0, 1))\]

where \(\tau\) is mutation_rate_tau. The result is clamped to [minimum_mutation_rate, maximum_mutation_rate], and the offspring inherits the new rate alongside the mutated genome. Larger \(\tau\) widens the per-generation step in log-space.

The population is (μ+λ): population_size is λ (total offspring per generation) and the number of parents μ is population_size / offspring_size. selection picks the μ parents each generation.

initial_mutation_rate: float | NumericExpression | Parameter | Calculation = (1 / NUM_VARIABLES)

Mutation rate used to seed each individual at the start of the run (0–1).

minimum_mutation_rate: float | NumericExpression | Parameter | Calculation = (1 / NUM_VARIABLES)

Lower clamp on per-individual mutation rate (0–1).

maximum_mutation_rate: float | NumericExpression | Parameter | Calculation = 1.0

Upper clamp on per-individual mutation rate (0–1).

mutation_rate_tau: float | NumericExpression | Parameter | Calculation = 0.5

Log-normal learning rate τ controlling the magnitude of per-offspring mutation-rate steps: childRate = parentRate × exp(τ × N(0, 1)). Must be non-negative; larger values widen the step distribution.

offspring_size: int | NumericExpression | Parameter | Calculation = 64

Offspring produced per parent each generation. Combined with population_size this fixes μ = population_size / offspring_size.

population_size: int | NumericExpression | Parameter | Calculation = NUM_VARIABLES

Total offspring per generation — λ in (μ+λ) notation.

mutation: Mutation

Mutation operator applied to offspring genomes.

selection: Selection

Parent-selection operator.

property key: str

The algorithm key emitted as algorithmKey in the serialised output.

class AdaptiveLargeNeighbourhoodSearch(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, candidates_per_iteration=1, segment_length=100, decay_factor=0.8, new_best_reward=33.0, improving_reward=9.0, accepted_reward=3.0, stagnation_limit=0, acceptance_criterion=<factory>)

Adaptive Large Neighbourhood Search (Ropke & Pisinger, 2006).

ALNS maintains a single incumbent solution and, each iteration, generates one or more candidate solutions by applying a destroy operator followed by a repair operator. Operators are drawn from user-supplied pools by weighted random selection; their weights are updated online based on the outcome of each iteration so that operators that recently produced good moves are picked more often.

Each iteration:

1. Select k destroy operators by weighted random sampling.

2. Select k repair operators by weighted random sampling.

3. Generate k candidate solutions by applying each destroy/repair pair to a copy of the incumbent.

4. Evaluate the k candidates (in parallel when k > 1).

5. Decide whether to accept the best candidate via the configured AcceptanceCriterion.

6. Reward the operator pairs that produced this iteration’s candidates.

7. Every segment_length iterations, decay all operator weights by decay_factor.

The operator-reward schedule has three tiers:

• new_best_reward (\(\sigma_1\)) — the candidate became a new global best.

• improving_reward (\(\sigma_2\)) — the candidate improved on the current incumbent but is not a new global best.

• accepted_reward (\(\sigma_3\)) — the candidate did not improve but was accepted by the acceptance criterion (e.g. by SA).

Operator weights are then decayed each segment via:

\[w_{t+1} = \rho \cdot w_t\]

where \(\rho\) is decay_factor.

The destroy and repair operator pools, plus the solution representation, are defined inside the user’s external model implementation (see the platform ALNSExternalModel interface); only the algorithm-level controls are configured here.

candidates_per_iteration: int | NumericExpression | Parameter | Calculation = 1

Number of candidate solutions generated per iteration. k=1 runs sequentially; k>1 evaluates candidates in parallel.

segment_length: int | NumericExpression | Parameter | Calculation = 100

Iterations between operator weight decay steps.

decay_factor: float | NumericExpression | Parameter | Calculation = 0.8

weight multiplier applied per segment. Must be in (0, 1).

Type:

\(\rho\)

new_best_reward: float | NumericExpression | Parameter | Calculation = 33.0

reward applied to operators that produced a new global best.

Type:

\(\sigma_1\)

improving_reward: float | NumericExpression | Parameter | Calculation = 9.0

reward applied to operators that produced a candidate improving on the current incumbent (but not a new global best).

Type:

\(\sigma_2\)

accepted_reward: float | NumericExpression | Parameter | Calculation = 3.0

reward applied to operators that produced an accepted but non-improving candidate.

Type:

\(\sigma_3\)

stagnation_limit: int | NumericExpression | Parameter | Calculation = 0

Number of consecutive iterations without a new global best before triggering a soft restart. Set to 0 to disable. Requires perturb() to be implemented in the external model.

acceptance_criterion: AcceptanceCriterion

Acceptance criterion governing whether candidates replace the incumbent.

property key: str

The algorithm key emitted as algorithmKey in the serialised output.

class AcceptanceCriterion(name, parameters)

An ALNS acceptance criterion: a AcceptanceCriterionType plus its parameters.

Simulated Annealing accepts improving moves and probabilistically accepts worsening moves based on a temperature schedule. Greedy only accepts improving (or equal) moves.

name: AcceptanceCriterionType

parameters: dict[str, Any]

classmethod simulated_annealing(initial_temperature=None, cooling_rate=None)

Construct a Simulated Annealing acceptance criterion.

Parameters:

• initial_temperature (float | NumericExpression | None) – Starting temperature for the SA schedule. Must be positive. Defaults to 100.0.

• cooling_rate (float | NumericExpression | None) – Geometric cooling factor applied each iteration. Must be in (0, 1). Defaults to 0.9998.

Return type:

AcceptanceCriterion

classmethod greedy()

Construct a Greedy acceptance criterion (only improving moves are accepted).

Return type:

AcceptanceCriterion

class AcceptanceCriterionType(*values)

Strategy used to decide whether a candidate solution replaces the current one.

SIMULATED_ANNEALING = 'Simulated Annealing'

GREEDY = 'Greedy'

class ExternalModelConfiguration(requires_reload=True)

All input, parameter, and output mappings used by an external evaluator.

Parameters:

requires_reload (bool) – Whether the evaluator should be reloaded between runs.

add_input_data_mapping(mapping)

Register an InputDataMapping.

Return type:

ExternalModelConfiguration

add_parameter_mapping(mapping)

Register a ParameterMapping.

Return type:

ExternalModelConfiguration

add_output_data_mapping(mapping)

Register an OutputDataMapping.

Return type:

ExternalModelConfiguration

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class InputDataMapping(entity_name, table, column_mappings=None)

Map a model Table to an external-evaluator input entity.

Add per-column property mappings via add_column_mapping().

add_column_mapping(property_name, column)

Append a ColumnMapping linking property_name to column.

Return type:

InputDataMapping

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class OutputDataMapping(entity_name, table, column_mappings=None, key_column=None, preserve_order=False, clear_existing=True)

Extension of InputDataMapping that controls how outputs are written back.

Parameters:

• key_column (str | None) – Optional column on the target table used to match incoming rows; absent matches are inserted.

• preserve_order (bool) – Keep the row order produced by the evaluator.

• clear_existing (bool) – Clear the target table before writing outputs.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

class ParameterMapping(parameter_name, named_value)

Map a model Parameter or Calculation to an external evaluator parameter name.

build()

Serialise to a JSON-compatible dict.

Return type:

dict[str, Any]

Getting Started

• Quickstart
  • Installation
  • A minimal configuration
  • Where to next

API Reference

• Configuration Builder
  • ConfigurationBuilder
• Model Configuration
  • ModelConfiguration
• Algorithms
  • Algorithm base
  • NumericExpression
• Schedule
  • Step types
  • Subproblem and execution features
  • Complete example
  • JSON field reference
  • API reference
• Data Sources
  • Data source wrapper
  • Base configuration
• Model Properties
  • ModelProperty
  • ModelImportOptions
  • OverlayConfig
• Reports
  • ReportProperty
  • ReportData
  • ReportExportFormat