Skip to content

References and command line

The bibliography of the implemented methods, the packaged data, and the modules of the command line.

dispatchatlas.references

The bibliography of the methods, benchmarks, and statistics DispatchAtlas implements.

Solvers and benchmark families cite their sources by key, for example SolverInfo.references = ("kolisch1996serial",). The entries live in TOML files under dispatchatlas/data/references, one file per area, and are merged here. Keys follow <first author><year><first title word>. to_bibtex() exports entries as BibTeX, so users can cite what they use.

Reference dataclass

Reference(key: str, authors: str, year: int, title: str, venue: str, doi: str | None = None, url: str | None = None)

One bibliography entry.

Attributes:

Name Type Description
key str

Citation key.

authors str

Author list as printed, for example "R. Kolisch".

year int

Publication year.

title str

Title of the work.

venue str

Journal, proceedings, or publisher, with volume and pages.

doi str | None

Digital object identifier without the https://doi.org/ prefix.

url str | None

Stable URL, for works without a DOI.

link: str | None

A resolvable link to the work.

bibtex

bibtex() -> str

Return the entry as one BibTeX entry, keyed by its citation key.

A venue of the form Journal volume(number):pages, which the bibliography uses for journal articles, gives an @article with those fields. Any other venue, such as proceedings, a book, or a report, has no common structure and becomes the howpublished field of a @misc. Authors become Surname, Initials names joined by and, with a surname of several words braced so BibTeX keeps it whole; a list ending in (eds.) becomes the editor field. The title is braced to keep its capitalisation, and the LaTeX special characters of the text fields are escaped.

bibliography cached

bibliography() -> MappingProxyType[str, Reference]

Return every bibliography entry, keyed by citation key.

reference

reference(key: str) -> Reference

Return the entry with the given key.

Raises:

Type Description
ConfigError

If the key is unknown.

cite

cite(source: str) -> str

Render a citation from a key, a DOI, or a URL.

Keys resolve to the full entry. DOIs (doi:... or 10....) and URLs are returned as links.

to_bibtex

to_bibtex(keys: Iterable[str] | None = None) -> str

Return BibTeX entries, each followed by a blank line.

Parameters:

Name Type Description Default
keys Iterable[str] | None

Citation keys, in the order to write them. Defaults to the whole bibliography, sorted by key.

None

Raises:

Type Description
ConfigError

If a key is unknown.

dispatchatlas.data

Data files shipped with DispatchAtlas, such as the bibliography.

dispatchatlas.cli

The dispatchatlas command line.

Every command is a thin layer over the public library API: it parses its arguments, calls the library, and prints the result. The commands:

dispatchatlas [--version] [--debug] [--quiet] COMMAND ...
    version                              package, Python, and optional backends
    solvers list [--family F]            registered solvers
    solvers show ID                      metadata, parameters, features, citations
    benchmarks list | show ID            benchmark families
    benchmarks generate ID [--seed N] [--set KEY=VALUE ...] [--output FILE]
    suites list | show ID                published instance suites
    suites load ID INSTANCE [--directory D] [--output FILE]
    catalogs list | show NAME            named instance sets
    catalogs build NAME --output DIR [--seed N] [--overwrite]
    solve PROBLEM --solver ID [--set KEY=VALUE ...] [limits] [--seed N] [--output FILE]
    check PROBLEM [SCHEDULE]             validate a problem, and a schedule against it
    campaign validate | estimate | run | check | replay
    processes launch | watch | list | end | rows-check | rows-repair
    analyze CAMPAIGN_DIR --output DIR [analysis options]
    references [KEY ...] [--format text|bibtex]

Results go to standard output, as text or, with --json, as JSON. Log messages and errors go to standard error. The exit code is 0 on success, 1 when the requested operation fails, 2 on a usage error, and 130 when the command is interrupted.

build_parser

build_parser() -> ArgumentParser

Return the parser of the whole command line.

main

main(argv: Sequence[str] | None = None) -> int

Run the command line and return its exit code.

Parameters:

Name Type Description Default
argv Sequence[str] | None

The arguments after the program name. Defaults to sys.argv[1:].

None

Returns:

Type Description
int

0 on success, 1 when the requested operation fails, 2 on a usage

int

error, and 130 when the command is interrupted.

dispatchatlas.cli.version

dispatchatlas version: the versions of the package, Python, and optional backends.

register

register(commands: Commands) -> None

Add the version command.

dispatchatlas.cli.solvers

dispatchatlas solvers: the registered solvers and their metadata.

register

register(commands: Commands) -> None

Add the solvers list and solvers show commands.

dispatchatlas.cli.benchmarks

dispatchatlas benchmarks: the benchmark families and their generators.

register

register(commands: Commands) -> None

Add the benchmarks list, show, and generate commands.

dispatchatlas.cli.suites

dispatchatlas suites: published benchmark suites and their instances.

register

register(commands: Commands) -> None

Add the suites list, show, and load commands.

dispatchatlas.cli.catalogs

dispatchatlas catalogs: named instance sets, written to disk with a manifest.

register

register(commands: Commands) -> None

Add the catalogs list, show, and build commands.

dispatchatlas.cli.solve

dispatchatlas solve: run one solver on one problem and check its schedule.

register

register(commands: Commands) -> None

Add the solve command.

dispatchatlas.cli.check

dispatchatlas check: validate a problem, and a schedule against it.

register

register(commands: Commands) -> None

Add the check command.

dispatchatlas.cli.campaign

dispatchatlas campaign: validate, estimate, run, check, and replay experiment campaigns.

register

register(commands: Commands) -> None

Add the campaign validate, estimate, run, check, and replay commands.

dispatchatlas.cli.processes

dispatchatlas processes: launch, watch, list, and end processes; check rows files.

register

register(commands: Commands) -> None

Add the processes command group.

dispatchatlas.cli.analyze

dispatchatlas analyze: the analysis bundle of a campaign.

register

register(commands: Commands) -> None

Add the analyze command.

dispatchatlas.cli.references

dispatchatlas references: the bibliography, as text or BibTeX, to cite what you use.

register

register(commands: Commands) -> None

Add the references command.