Bootstrap

Initializing an experiment with knit bootstrap.

Bootstrap an experiment

Initialize an experiment’s .knit/ directory before running any command.

APIs: bootstrap

Every experiment must be bootstrapped once before any other command runs. bootstrap creates the .knit/ directory next to your script — a small SQLite database that records runs, plus the tools Knit relies on (it installs sqlite3, jq, and knit-cypher-to-sql locally, symlinking the system copies of sqlite3/jq when they are already available):

$ ./exp.sh bootstrap

Run bootstrap again to update the configuration in place — it keeps the database, the tooling, and every recorded run (see Update configuration by re-running bootstrap). To start over instead, remove the .knit/ directory first. The remaining Bootstrap recipes cover the options that pin project settings, paths, the scheduler and launcher, and the provisioned tool versions.

Set the scheduler project and account

Record the batch-scheduler project and account jobs are submitted under.

APIs: bootstrap

On a shared cluster the batch scheduler charges each job to a project (or allocation) and, on some sites, an account. These are values your site assigns — not free-form labels — and Knit passes them to the scheduler when submitting jobs. Freeze them at bootstrap so every submission inherits them:

$ ./exp.sh bootstrap \
    --project PROJ-1234 \
    --account my-allocation

--project names the scheduler project used when submitting jobs; --account is the account/allocation the jobs are charged to. Leave them empty on a laptop or any machine with no batch scheduler.

Choose where setups and jobs live

Point the setup and job root directories at custom locations.

APIs: bootstrap

Knit creates each setup and each submitted job under a root directory. --setup-path and --job-path choose those roots (defaults: setups and jobs):

$ ./exp.sh bootstrap \
    --setup-path env \
    --job-path runs

Keep these paths relative — they resolve against the experiment root, so the experiment stays portable to another machine or user. An absolute path is honored but pins the experiment to this filesystem, and Knit warns when you pass one.

Select the batch scheduler

Pin the batch scheduler instead of auto-detecting it.

APIs: bootstrap

By default bootstrap auto-detects the batch scheduler. Pin it explicitly when detection guesses wrong, or to make the experiment self-documenting. --scheduler is one of auto, slurm, pbs, flux, local, none:

$ ./exp.sh bootstrap --scheduler slurm

Use --scheduler local to run jobs as plain local processes with no batch system. Use --scheduler none for a self-managed cluster (no scheduler) and pair it with --default-nodefile so a job can report its allocation:

$ ./exp.sh bootstrap --scheduler none --default-nodefile hosts.txt

Select the MPI launcher

Pin the MPI launcher instead of auto-detecting it.

APIs: bootstrap, knit_provides_launcher

By default bootstrap auto-detects the MPI launcher. --launcher is one of auto, openmpi, mpich, pals, flux, slurm, pbs, none. With auto an MPI-native launcher (openmpi, mpich, or pals) is detected from the environment; if none is found and a batch scheduler is present, auto falls back to that scheduler’s integrated launcher (slurm = srun, pbs = the PBS mpiexec wrapper, flux = flux run). Select slurm/pbs/flux explicitly to force the scheduler-integrated launcher even when an MPI-native one is present:

$ ./exp.sh bootstrap --launcher openmpi
$ ./exp.sh bootstrap --launcher slurm

Use --launcher none to declare the machine offers no integrated MPI launcher — a setup’s knit_provides_launcher then supplies one:

$ ./exp.sh bootstrap --launcher none

Set project-wide job defaults

Freeze default walltime and per-node core count for submitted jobs.

APIs: bootstrap

bootstrap can freeze project-wide defaults that every submission inherits unless a job overrides them. --default-walltime sets a wall-clock limit as HH:MM:SS; --default-cpus-per-node sets the core count used for whole-node allocation:

$ ./exp.sh bootstrap \
    --default-walltime 01:30:00 \
    --default-cpus-per-node 64

Left empty, walltime falls back to the selected queue’s profile default at submit time, and the per-node core count falls back to the machine profile or live detection.

Pin the Spack version

Provision a specific Spack (and package repo) git ref at bootstrap.

APIs: bootstrap

Knit provisions a private Spack automatically the first time a setup declares a Spack environment, defaulting to the latest Spack release. Pass --spack to pin a specific Spack git ref (a tag, branch, or commit) instead, and --spack-packages to pin the package repository ref:

$ ./exp.sh bootstrap \
    --spack v0.22.1 \
    --spack-packages v2024.11.0

Both take a git ref as their value; an empty value (the default) uses the latest release. Passing --spack also forces Spack to be provisioned now rather than lazily on first use.

Force building the bundled tools from source

Build sqlite/jq from source instead of symlinking the system copies.

APIs: bootstrap

By default bootstrap symlinks the system sqlite3 and jq when they are available, and only builds or downloads its own copy when they are missing. Force Knit to provision its own instead — for a pinned, reproducible toolchain independent of what the host happens to ship — with --ignore-system-sqlite and --ignore-system-jq:

$ ./exp.sh bootstrap \
    --ignore-system-sqlite \
    --ignore-system-jq

--ignore-system-sqlite builds SQLite from source; --ignore-system-jq downloads a jq binary. Either way the tool lands under .knit/ and is used in preference to any system copy.

Pin the knit-cypher-to-sql version

Provision a specific knit-cypher-to-sql release, or one from a custom URL.

APIs: bootstrap

bootstrap provisions knit-cypher-to-sql (the transpiler behind knit query) at a pinned default version. Override the version with --knit-cypher-to-sql-version, or point at a specific release tarball with --knit-cypher-to-sql-url:

$ ./exp.sh bootstrap --knit-cypher-to-sql-version 0.1.0

$ ./exp.sh bootstrap \
    --knit-cypher-to-sql-url https://example.com/knit-cypher-to-sql-0.1.0.tar.gz

An empty --knit-cypher-to-sql-version uses the pinned default; an empty --knit-cypher-to-sql-url derives the URL from the version.

Update configuration by re-running bootstrap

Re-run bootstrap to change settings in place without losing the database or runs.

APIs: bootstrap

bootstrap is re-runnable. Run it again on an already-bootstrapped experiment to update the configuration in place — it keeps the .knit/ database, the provisioned tooling, and every recorded run. Only the options you type change; every other setting keeps its stored value. So you can adjust one field long after the first bootstrap:

$ ./exp.sh bootstrap --default-cpus-per-node 128

A bare re-bootstrap with no options changes nothing and reports that there is nothing to update.

Some changes are constrained to protect recorded work. You can relocate a path (--setup-path / --job-path / --resource-path) only while it is empty of its kind — no user setup, no job, or no resource yet; otherwise Knit stops rather than strand existing rows. Changing the machine --profile is not supported yet. Re-provisioning a bundled tool (see Force building the bundled tools from source and Pin the knit-cypher-to-sql version) also happens here: a typed tool option that differs from the stored value rebuilds that tool.