Running programs
shapescript run [--python PY] [--] program [args…] runs program with PY -m shapescript program args… (see Debugging): a Python file, which runs as python program.py would but can import .ss files without shapescript.install(), or a .ss file, which is imported and whose fn main() is called. sys.argv is [program, args…]. The Python is --python, else $SHAPESCRIPT_PYTHON, else python3 (python on Windows), as for shapescript export. The command’s exit code is the program’s.
Running on Modal
With --modal GPU, the program runs in a container on Modal, with that GPU, instead of here; the guide is docs/modal.md. Nothing in the program changes. The command needs the modal package in that Python (pip install modal) and a Modal account (modal setup); without the package it says so and exits 2.
GPU is Modal’s name for a GPU type, in any case: T4, L4, A10G, A100, A100-80GB, L40S, H100, H200, B200 and others, with :N for N of them, 1 to 8, as in H100:3. Inside the container, devices cuda[0] (and cuda[0 1 2] with three GPUs) is available. A program that declares devices cpu or cpu[…] runs on the CPU, and one that declares devices mps runs on the CPU too, since Modal’s machines are Linux; both print a warning that the GPU is unused.
The container has the local Python version, torch, numpy and einops at the local versions (Linux builds, with CUDA), and this version of ShapeScript: from PyPI when it is published there, else built from the source checkout the local one was built from. --pip REQ installs another package, or another version of those three, and --shapescript says which ShapeScript: a Linux x86_64 wheel, a source checkout, or a pip requirement. The first run builds this image, which takes minutes; Modal keeps it for later runs.
The program’s folder, or --project DIR, is uploaded to the same absolute path in the container, without .git, .venv, venv, __pycache__, *.pyc, target, node_modules and tools’ caches, nor what matches an --exclude GLOB (a pattern without / matches any file or folder name, one with / a path in the folder). More than --max-upload MB (500) of it is an error that names its largest entries. The program runs in the same working directory as the command, so relative paths, __file__ and tracebacks are the local ones: a ShapeScript error raised in the container names the local .ss file and line.
What the program prints is streamed back as it prints it, its stdout to stdout and its stderr to stderr; Modal’s progress and the image’s build log go to stderr. When the program ends, the files it created or changed in its folder, or in the working directory when that contains its folder, come back to the same paths here; files it deleted are kept here. The exit code is the program’s.
| Option | |
|---|---|
--timeout DURATION | How long the program may run: 600, 10m or 2h, from 10 seconds to 24 hours. The default is an hour. At the timeout the program is stopped, its files still come back, and the command exits 124. |
--env KEY, --env KEY=VALUE | Gives the program the environment variable, with its value here or VALUE. Unset here without =VALUE is an error. |
--secret NAME | Gives the program the variables of the Modal secret NAME. |
--exclude GLOB, --project DIR, --max-upload MB | What is uploaded, as above. |
--pip REQ, --shapescript WHEEL|DIR|REQ | What is installed, as above. |
Ctrl-C stops the program and its container, and the command exits 130; the files it wrote don’t come back. A .ss program is compiled here before anything starts, so its errors cost nothing, and so is a devices line that asks for more CUDA devices than the GPUs: devices cuda[0 1 2] with --modal T4 is an error that suggests --modal T4:3.