Documentation

Library manual

Reference for the self-contained C++20 divisible-load scheduling library that powers this portal. The library is usable on its own (from C++, the dls command line, or the JSON HTTP API) with no dependency on the web interface. This manual is a living document and will grow.

Overview

The engine is a header-light C++20 library with a uniform solver interface (makeSolver / availableSolvers), structured instance and solution types, and a thin C-ABI bridge (libdls_c.so) so any language can drive it. The same engine backs the CLI, the HTTP API and this portal, see the Knowledge base for the model and the Solver Studio to run it interactively.

Building the library

Two CMake builds: a full one with the HiGHS MILP engine, and a dependency-free one.

# full build (HiGHS MILP solvers + C-ABI binding)
$ cmake -B build-highs -DDLS_WITH_HIGHS=ON
$ cmake --build build-highs -j$(nproc)

# dependency-free build (in-house simplex, no external solver)
$ cmake -B build && cmake --build build

Command line

The dls tool reads an instance file and emits JSON.

# solve a star instance, JSON in / JSON out
$ dls solve --solver=auto --json instance.txt

# non-star topologies
$ dls solve --class=chain  chain.txt
$ dls solve --class=tree   tree.txt
$ dls solve --class=graph  graph.txt

HTTP API

JSON endpoints exposed by the portal's FastAPI layer (the contract the front-end uses).

Method	Endpoint	Purpose
GET	/api/solvers	List the solvers registered in this build.
POST	/api/solve	{ instance, solver, opts } → schedule with full Gantt timing.
POST	/api/pareto	{ instance, opts } → time-energy Pareto front.
POST	/api/map	{ opts } → isoefficiency / isoenergy 2-D sweep.
POST	/api/bench	{ solvers, opts } → portfolio comparison over random instances.
POST	/api/topology	{ klass, text } → chain / tree / graph load distribution.

Instance format

Line-oriented text. The star model first, then the non-star topology variants.

# star model, total load, then one row per processor
V 1000
# S      C     A     B       (startup, comm/unit, compute/unit, memory)
0.1   0.11  0.52  4000
0.2   0.21  0.22  5000
0.3   0.31  0.32  1500
# optional energy model per processor
#   power <idle> <startup> <network>   and   energy <a,b>...  (convex ε(α))

# chain : node <A> <C>            (node 0 = source, its C unused)
# tree  : node <A> <C> <parent>   (node 0 = root, parent -1)
# graph : node <A>  +  edge <u> <v> <rate>
V 100
node 0.20 0
node 0.30 0.10 0
node 0.25 0.12 0

Solver portfolio

This build registers … solvers. Full descriptions are in the Knowledge base.

Problem classes

Single load (star)

One divisible load distributed from a master to worker processors over a single-port network (the core model behind Solver Studio).

Linear chain / tree / graph

Non-star topologies where load relays through intermediate nodes; the graph solver picks the best rooted spanning tree. See the Studio “Topology” tab.

Multiple loads (MLSD)

Several divisible loads scheduled together on shared processors.

Map-reduce

A map phase followed by a reduce phase with precedence between them; closed-form exact scheduler.

Energy model

Optionally, each worker passes through four power states (idle, startup, networking and running) and its running energy ε(α) is a convex piecewise function of the chunk size. With an energy model on, the cost-minimising solvers minimise energy and the Time-Energy Pareto view exposes the trade-off. Details and symbols are in the Knowledge base.