Quickstart

This guide walks through configuring an optimisation run for a small daitum-model model. It assumes you have already defined the model itself — see Quickstart for that.

Installation

daitum-configuration is published on PyPI:

pip install daitum-configuration

To pin a specific version:

pip install daitum-configuration==1.0.0

It is also bundled in the daitum-core meta-package alongside daitum-model and daitum-ui — see the top-level Quickstart.

Source: github.com/daitumapi/daitum-core.

A minimal configuration

The ConfigurationBuilder is the entry point. It composes a ModelConfiguration (decision variables, objectives, constraints) with an Algorithm and writes the result to model-configuration.json:

import daitum_model.formulas as f
from daitum_model import DataType, ModelBuilder

model = ModelBuilder()

# A data table whose Quantity field is the decision variable.
items = model.add_data_table("Items")
items.set_key_column("Name")
items.add_data_field("Name", DataType.STRING)
unit_cost = items.add_data_field("Unit Cost", DataType.DECIMAL)
quantity = items.add_data_field("Quantity", DataType.INTEGER)
min_qty = items.add_data_field("Min Qty", DataType.INTEGER)
max_qty = items.add_data_field("Max Qty", DataType.INTEGER)
items.add_calculated_field("Row Cost", unit_cost * quantity)

# Model-level totals and a user-editable budget.
total_cost = model.add_calculation(
    "TOTAL_COST", f.SUM(items["Row Cost"]), model_level=True
)
budget = model.add_parameter("BUDGET", DataType.DECIMAL, 10_000.0, model_level=True)

from daitum_configuration import (
    ConfigurationBuilder,
    DVType,
    ModelConfiguration,
    Priority,
    VariableNeighbourhoodSearch,
)

model_cfg = ModelConfiguration()

# Per-row decision variable: quantity bounded by the Min/Max Qty fields.
(
    model_cfg.add_decision_variable(quantity, dv_table=items, dv_type=DVType.RANGE)
    .set_min(min_qty)
    .set_max(max_qty)
)

# Minimise total cost.
model_cfg.add_objective(total_cost, maximise=False, priority=Priority.HIGH, name="Cost")

# Hard constraint: total spend must not exceed the budget.
model_cfg.add_constraint(total_cost).set_upper_bound(budget).set_name("Budget")

config = ConfigurationBuilder()
config.set_algorithm(VariableNeighbourhoodSearch())
config.set_model_configuration(model_cfg)

# Emit model-configuration.json into ./output.
config.write_to_file("output")

Decision-variable bounds may be supplied in two ways. When dv_table is supplied (a per-row variable), pass Field references to set_min/set_max so each row uses its own bound. For a model-level Parameter decision variable, pass plain numeric literals or another Parameter/Calculation.

Where to next