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:
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)isCLUSTER:PATHand round-trips throughmq.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 localopen()by mistake. transfer(destination, *options)makesdestinationa 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 deeprglobon 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.