Skip to content

Files and logs

Each submission writes default stdout and stderr beneath <project_root>/.molq/jobs/<run_id>/ on the target. Shell writes its original launch and exit receipts there too. Slurm arrays use a separate subdirectory for each element. Log and receipt lifetime follows the project.

The host can read ranges through logs.read or copy a full log with the existing rsync transfer. Use a named artifact manifest to download selected user outputs. Observing a completed job leaves all files on the target.

Read job output

import json

chunk = job.logs(stream="stdout", offset=0, limit=65536)
print(json.dumps(chunk, ensure_ascii=False))
next_offset = chunk["next_offset"]

Use stream="stderr" for errors. Read subsequent chunks from next_offset. Each read is bounded to 256 KiB and checks the job reference's identity.

job.logs() reads the allocation's native output paths. Copy a redirected stdout or stderr file back with transfer.

Transfer files

molq transfer is rsync syntax. Operands are CLUSTER:PATH or a local path, read the way rsync reads HOST:PATH: a colon before the first slash names a registered cluster. Options go to rsync unchanged and nothing is implied, so write -a and --delete yourself. A trailing slash means what it means to rsync.

molq transfer --transfer-deadline 600 -av --exclude build/ ./inputs/ hpc:/shared/project/inputs/
molq transfer -a hpc:runs/run_01/out.xyz .

CLUSTER:relative is relative to that login's home. A local path is resolved against the shell's working directory, and it names the serve host's filesystem; with a remote --endpoint, that is the serve machine. One rsync run copies between a local path and one SSH cluster, or within one host. Two distinct SSH clusters require explicit local staging, as with rsync. -e/--rsh, --rsync-path, -M/--remote-option and daemon options belong to the cluster transport and are rejected. The result carries rsync's stdout under output, bounded to 1 MiB. --transfer-deadline SECONDS sets MolQ's total copy limit from 1 to 3600 seconds (default 90). rsync's own --timeout still controls its I/O timeout. In Python, set timeout= on the transfer and allow at least 15 extra seconds on Molq(timeout=...) for long transfers.

A destination handle keeps the same copy:

local.transfer("/home/you/project/", hpc, "/scratch/you/project/", "-a", "--exclude=build/")

In Python, each option is one word with its value attached (--exclude=build/).

Cluster paths

mq.Path is a POSIX path that also names its cluster. Path arithmetic keeps the cluster; I/O goes through the serve process.

import molq as mq

run = mq.Path("hpc:/scratch/you/run_01")
log = run / "out.log"              # Path('hpc:/scratch/you/run_01/out.log')
if log.exists():
    print(log.read_text())
for xyz in run.glob("frames/*.xyz"):
    print(xyz.name, xyz.stat().st_size)
(run / "input.json").write_text("{}")
run.transfer(mq.Path("results/run_01"), "-a")

A path without a cluster is local and uses pathlib. The methods follow pathlib: exists, is_file, is_dir, is_symlink, stat, iterdir, glob, rglob, read_text, read_bytes, write_text, write_bytes, mkdir, touch, unlink, rmdir, rename, replace. Precondition failures raise the matching FileNotFoundError, FileExistsError, NotADirectoryError, IsADirectoryError or OSError; other failures raise MolqError.

  • str(path) is CLUSTER:PATH and round-trips through mq.Path; as_posix() is the path on its host. Pickling keeps the cluster.
  • A cluster path has no os.fspath, so it cannot reach a local open() by mistake.
  • transfer(destination, *options) makes destination a copy of the path. A directory is copied as its contents, SRC/ DEST/ in rsync terms.
  • stat() returns mode, uid, gid, size and whole-second mtime; the other fields are zero. Writes create missing parent directories. A write larger than 256 KiB is staged beside the file and renamed into place. Each listed directory costs one RPC, so a deep rglob on a cluster is slow.
  • Paths use one process-wide Molq() unless you bind a client: mq.Path("hpc:/scratch", molq=client). Derived paths keep it.

Scoped application access

Bind paths to the application's own client and allowed root:

with mq.Molq(timeout=3610) as client:
    root = mq.Path("hpc:/scratch/team/workspace", molq=client,
                   root="/scratch/team/workspace")
    page = root.list_page(with_stat=True, limit=256)
    batch = root.read_many([(root / "workspace.json").as_posix()])
    root.transfer(mq.Path("downloads/workspace", molq=client), "-a", timeout=3600)

list_page returns entries and next_after. Pass after=page["next_after"] for the next page. read_many accepts destination paths, up to 128 per call, with 256 KiB per file and 512 KiB total raw content. Each item has data or an error; a capacity error never means a truncated success. Root constraints are checked on the destination, including symlinks inside directory transfers. They constrain operations and do not create a separate user permission system.

For an existing SSH alias that needs a verification response, call client.cluster("hpc").authenticate(code). The response is used once through a private temporary helper and is never persisted. Key-based file operations work directly; they do not require a pre-existing master. Authentication rejection, connection timeout and an unreachable destination have separate error kinds.