Skip to content

Queue

The queue lets you hand mliport several calculations and walk away. A local scheduler runs them for you, gives each job its own GPU lease so two jobs don't trample one card, tracks status and handles cancellation.

.venv-mace/bin/mliport queue submit tasks.json
.venv-mace/bin/mliport queue start
.venv-mace/bin/mliport jobs
.venv-mace/bin/mliport queue stop

queue start launches a background scheduler and returns right away. Poll mliport jobs (or queue status) until your jobs are done or failed, then stop the scheduler. The TUI's Run screen submits through the same helper as the CLI, so jobs from either behave identically.

The task file

A task file is one JSON object with a tasks list. calc_type is one of sp, opt, md or neb, and the paths must exist:

{
  "max_concurrent": 1,
  "tasks": [
    {
      "name": "lgps-sp",
      "calc_type": "sp",
      "structure": "/data/LGPS.vasp",
      "model": "/data/mace-omat-0-medium.model",
      "model_type": "mace",
      "task": "bulk",
      "device": "cuda",
      "output_dir": "/data/runs/lgps-sp"
    },
    {
      "name": "uma-md-800K",
      "calc_type": "md",
      "python": "/data/mliport/.venv/bin/python",
      "structure": "/data/LGPS.vasp",
      "model": "/data/uma-s-1p2.pt",
      "model_type": "uma",
      "task": "omat",
      "device": "cuda",
      "options": {"ensemble": "NVT", "temperature": 800, "steps": 50000}
    }
  ]
}

Run options go in options. An optional python runs that one task in another backend's environment, so a single queue can mix engines. The model path and the backend must always be explicit.

Controlling the scheduler

Command Option Meaning
queue submit the task file enqueue every task in it
queue start --max-concurrent N how many jobs may run at once (default 1, for a single GPU)
queue start --max-jobs-per-gpu N how many jobs may share one physical GPU (default 1, an exclusive lease); raise it only for small systems that fit in GPU memory together
queue start --poll SECONDS scheduler poll interval (default 5)
queue start --foreground run the scheduler in the foreground (Ctrl-C stops it)
queue status pending, running and finished jobs with their device lease
queue stop stop the background scheduler
queue pause / queue resume optional job id pause or resume one pending job, or all pending dispatch

kill and clean work on individual job records.

Where things go

The job registry lives under MLIPORT_JOBS_DIR (a user-level directory by default). Each job also gets its normal run directory with run.log and mliport_results.json, and the physical GPU lease is recorded per job.

What happens when things go wrong

A job that cannot get a device stays pending; it does not squeeze onto a GPU beyond --max-jobs-per-gpu. A crash or an exception marks the job failed with its reason and releases the lease. A scheduler that is restarted recovers stale claims. The queue turns CUDA_VISIBLE_DEVICES into the leased physical GPU, so don't override it inside a job.

Queue order does not change the science, but jobs in one queue share a configuration surface. For transport or NEB campaigns, keep the model identity, timestep and save interval in the task spec so the resulting records stay comparable.