Running on another computer¶
Long runs (many rays, third-octave bands, the wave solver up to 250 or 500 Hz, big
coverage maps, outdoor scenes over kilometres) can run on a computer with more cores or
a GPU: a server you reach over SSH, a rented GPU machine, or a job on a cloud service
such as Hugging Face Jobs. The scene goes there as a pack, one zip file; a container
image runs the command line on the GPU there; the results come back as the same files
simulate and map write here.
Nothing in acoustic_spaces uploads anything: you choose where a pack goes, and it holds everything needed to rebuild the scene (its model, materials and positions). Send it only where you would send the drawings themselves.
Packs¶
acoustic-spaces pack hall/scene.yaml hall.zip
writes the scene and every file it names: its model, terrain, buildings map, material
libraries and coefficient files, directivity files, the WAV files sources play, the
scene’s recording file and HRTFs, with the files those name in turn (a .gltf model’s
buffers and images, a loudspeaker array’s element data). It lists what went in and their
sizes. Files under the scene’s folder keep their place relative to it; files elsewhere
go under external/<their folder>/. The scene file in the pack names them all
relatively, so the pack runs wherever it is unpacked. The editor does the same from
File > Pack for another computer, also for a scene not yet saved. The zip is written
as hall.zip.part and takes the name only once it is complete, so a pack that fails
leaves an earlier hall.zip as it was.
A scene with problems (a listener outside the room, surfaces without a material) is not
packed, as simulate would not run it either; warnings are shown. A file that names one
outside its own folder (../shared/element.csv in an array’s YAML) cannot keep its
place in a pack: move that file next to it. A file whose name holds : or \, which
Windows refuses and unpacking refuses everywhere, is not packed, nor are two files, or a
file and a folder, whose names macOS or Windows take for one: names that differ only in
case (on macOS also straße and strasse), or in the way a letter is encoded (é as one
character, or as e and an accent, which macOS alone takes for one). Rename them.
Every command that reads a scene takes a pack in its place: simulate, map,
validate, inspect, calibrate, walkthrough, export, view, animate and
tune, with the same options.
acoustic-spaces simulate hall.zip --out results --bands third_octave # on the other computer
The pack is unpacked into a temporary folder for the command and removed after it,
once the folder is found to have room for it. pack.json in it records the version
that wrote it and a SHA-256 of every file, which each file is checked against before it
takes its name, so a damaged pack is refused, and a pack written by another version
runs with a warning:
results can differ between versions, so for numbers to compare, run the same version on
both computers. Runs of a pack give the same results, bit for bit, as runs of the scene
file on the same computer.
The container image¶
The repository’s Dockerfile builds an image with the command line, the gpu and
sofa extras, the Vulkan loader and Mesa’s Vulkan drivers, on Ubuntu 24.04. It runs
headless: the wave solver and the late rays reach the GPU through Vulkan (wgpu), with no
display. Build it from a checkout:
docker build -t acoustic-spaces .
docker build -t acoustic-spaces --build-arg EXTRAS=gpu,sofa,ifc . # packs with IFC models
Its entry point is acoustic-spaces, so the container takes a command and its options;
without one it runs info. First check that it finds the GPU:
docker run --rm --gpus all acoustic-spaces info
GPU: should name the card, (Vulkan, DiscreteGPU). With llvmpipe ... (Vulkan, CPU),
Mesa’s software driver, or none, the GPU’s Vulkan driver does not reach the container
and every run takes the CPU:
NVIDIA: the host needs the NVIDIA driver and the NVIDIA Container Toolkit, and the container the driver’s graphics capability, which holds its Vulkan part. The image asks for it (
NVIDIA_DRIVER_CAPABILITIES=compute,utility,graphics); a service that setscomputealone, as many CUDA images do, leaves Vulkan out. Older toolkits mount the library without telling the Vulkan loader where it is; the image’sacoustic-spacescommand finds it and writes that file itself.AMD and Intel: Mesa’s drivers are in the image; pass the GPU’s device nodes with
--device /dev/driand, where they belong to therendergroup,--group-add "$(getent group render | cut -d: -f3)".
On the CPU, runs take every core (simulation.performance.threads: 0), the same as
here. Device auto times the CPU against the GPU on the machine it runs on (see
Simulation); a container keeps no timings between runs, so each run
times anew, unless the scene or the options name cpu or gpu, or the cache folder
(/tmp/cache) is a volume that acoustic-spaces tune filled once.
Run a pack with the current folder mounted as /work, the container’s working folder,
writing as your own user:
docker run --rm --gpus all -v "$PWD:/work" --user "$(id -u):$(id -g)" \
acoustic-spaces simulate hall.zip --out results
A server over SSH¶
On any machine you reach over SSH (your own, or one rented by the hour with a GPU), build the image there from a checkout, or send it from here:
docker save acoustic-spaces | ssh server docker load
scp hall.zip server:jobs/
ssh server 'cd jobs && docker run --rm --gpus all -v "$PWD:/work" \
--user "$(id -u):$(id -g)" acoustic-spaces simulate hall.zip --out hall-results'
scp -r server:jobs/hall-results .
Without Docker, install acoustic_spaces on the server as here (with the gpu extra,
and a Vulkan driver for its GPU) and run the pack the same way.
Hugging Face Jobs¶
Jobs run a container on Hugging
Face’s hardware, CPUs or NVIDIA GPUs from a T4 to an H200, paid by the minute from the
account’s credit (hf jobs hardware lists them and their prices). They take a public
image or the image a Docker Space builds; a private Space keeps the image private. With
the hf command (pip install -U huggingface_hub, then hf auth login), once:
hf repos create <user>/acoustic-spaces --type space --space-sdk docker --private
mkdir space && git archive HEAD | tar -x -C space
printf -- '---\ntitle: acoustic-spaces\nsdk: docker\n---\n\n' | cat - README.md > space/README.md
hf upload <user>/acoustic-spaces space . --type space
The Space builds the image from the Dockerfile; it then shows a runtime error, as it
serves no web page, which does not matter: Jobs only take its image. Upload again after
updating the checkout, and Jobs take the new build. Then, for each run:
mkdir -p jobs && cp hall.zip jobs/
hf jobs run --flavor l4x1 --timeout 2h -v ./jobs:/jobs:rw \
hf.co/spaces/<user>/acoustic-spaces \
acoustic-spaces simulate /jobs/hall.zip --out /jobs/results
The folder jobs is copied to a storage bucket of the account and mounted in the job,
which writes the results there; the command prints how to sync the bucket’s folder back
when the job starts. Check the GPU first with a short job running acoustic-spaces info;
a job stops at its timeout (30 minutes unless --timeout says otherwise) and is billed
while it starts and runs.