Skip to main content

Controller Setup

The Atomiverse Controller is a background daemon you run on your own machine. It polls for pending jobs, runs them locally inside a container, and reports results back to Atomiverse.

Requirements​

  • Python 3.10 or newer
  • Docker or Apptainer installed on the machine (Apptainer is installed automatically on Linux if neither is present)
  • Outbound network access to atomiverse.com

Installation​

pip install https://atomiverse.com/packages/atomiverse-controller

Setup​

Run the interactive setup once:

atomiverse-controller setup

You will be asked for:

  • Runner key — create a Runner key on your Atomiverse Settings page. Workspace keys for the Python SDK will be rejected during controller setup.
  • Controller name — a short label for this machine, e.g. workstation or hpc-cluster
  • Runtime — Docker, Apptainer, or SLURM
  • Cores and memory — the maximum resources the controller can allocate to concurrent jobs (see Resource Limits below)

Settings are saved to ~/.atomiverse/controller.json.

After saving, the controller starts automatically in the background. There is no need to run a separate start command after setup.

Running the Controller​

If the controller is not running (e.g. after a reboot or manual stop), start it:

atomiverse-controller start

It runs in the background. You can check its status at any time:

atomiverse-controller status

List active jobs and resource usage:

atomiverse-controller list

This shows each running job with its resource allocation, plus a summary of occupied and free cores and memory.

View the logs:

atomiverse-controller logs

Stop it:

atomiverse-controller down

Once the controller is running, it appears automatically on your Settings page under Controllers, where you can see its status, live resource usage, and capacity.

Submitting Jobs to Your Controller​

From Python, pass the controller name you chose during setup as compute_target:

from atomiverse import JobFailedError, SinglePointEnergy
from atomiverse.levels import GFN2_XTB

job = SinglePointEnergy(
    atoms=molecule,
    level_of_theory=GFN2_XTB,
)

job.submit(compute_target="my-cluster")

try:
    print(job.require_result().energy)
except JobFailedError as exc:
    print(exc.failure.error)

Replace "my-cluster" with the name you gave during setup.

If the controller is busy and you want the SDK to keep retrying until there is space, submit with wait_for_capacity=True:

job.submit(
    compute_target="my-cluster",
    wait_for_capacity=True,
)

If you are also blocking until the job finishes, timeout caps the post-submission completion wait after the controller accepts the job:

job.submit(
    compute_target="my-cluster",
    wait_for_capacity=True,
    timeout=1800,
)

Before submitting large batches, inspect free capacity and estimate how many jobs will fit — see Estimating Controller Usage.

Resource Limits​

During setup the controller asks for max cores and max memory. These values control how many jobs the controller runs concurrently — the controller divides the configured cores by each job's core requirement to determine the number of available slots.

For local controllers (Docker or Apptainer without SLURM), these limits should match or stay below the machine's physical resources. The setup wizard warns you if the entered values exceed the detected hardware.

For SLURM controllers, the limits represent the total cluster resources you want the controller to use. Because SLURM dispatches work to compute nodes rather than the local machine, these values can (and usually should) exceed what the login node reports.

You can inspect the current resource usage at any time:

atomiverse-controller list

Runtime Options​

Docker​

The default. Works on any machine with Docker installed and no extra configuration needed.

Apptainer​

For environments where Docker is not available — common on HPC systems. Select Apptainer when running atomiverse-controller setup. The controller downloads and converts the worker image to Apptainer's SIF format automatically.

If neither Docker nor Apptainer is installed, the controller attempts to install Apptainer for you on Linux. It first tries the system package manager (apt or dnf) when passwordless sudo is available, then falls back to downloading the latest official binary release into ~/.local/bin.

SLURM​

For HPC clusters with a job scheduler. The controller submits each job as a SLURM batch job. Select SLURM during setup and provide your account and partition when prompted.

SLURM requires a container runtime

SLURM mode does not run jobs directly — it runs them inside a container on the allocated node. You must have a working Docker or Apptainer installation on the compute nodes. During setup, choose whether SLURM jobs use Docker or Apptainer as the container runtime.