Run an app locally#

Goal#

Execute a PlayMolecule app on the current machine, using Docker or Apptainer as the container runtime.

Minimal example#

from playmolecule.apps import proteinprepare

ed = proteinprepare(outdir="out", pdbid="3ptb")
ed.run()

When ed.run() returns, the job is done. ed.status is JobStatus.COMPLETED (or JobStatus.ERROR).

What run() does#

  1. Asks the active execution backend (local, by default) to run the app.

  2. The local backend invokes docker run or apptainer run against the cached image, bind-mounting the run directory into the container.

  3. Stdout/stderr stream to your terminal.

  4. The function returns when the container exits.

For the conceptual picture, see Architecture.

Quiet down logs#

ed.run(verbose=False)

verbose=False suppresses live output but still writes everything to the job’s log file at outdir/run_<id>.log (a sibling of the run directory, not inside it).

Set the container runtime#

Docker is the default. Switch to Apptainer for HPC nodes that can’t run Docker:

export PM_RUNTIME=apptainer

See Switch between Docker and Apptainer for the full picture.

Run the same ed somewhere else#

ed.run(...) re-uses the same prepared inputs. If run() errored once, you can fix the issue (e.g., adjust a file in outdir/) and call run() again without rebuilding the job.

To submit the same ed to SLURM instead:

ed.run(queue="slurm", partition="normalCPU", ncpu=1, ngpu=0)

See Run an app on SLURM.

One-shot syntax#

If you don’t need the ed handle:

proteinprepare(outdir="out", pdbid="3ptb").run()

Drop the binding when running interactively. Keep it whenever you need to check status, batch jobs, or inspect inputs.

Gotchas#

  • The first time you call an app, the container image must be pulled — that’s a one-time multi-hundred-MB download. If the pull fails, check docker login / gcloud auth configure-docker for the registry (see Install apps for a cluster).

  • outdir must be writable by the user running the Python script. Docker’s UID-mapping quirks are out of scope here, but if you see permission errors in the output files, run docker info and check your storage driver.

  • Setting PM_BLOCKING=1 makes the call block until the job finishes even when running through the HTTP backend — useful for scripts, never useful for interactive work.

See also#