Quantum experiments on a classical simulator have an awkward habit: the answer depends on software versions, random seeds and how much memory the machine can spare. If a colleague cannot reproduce your plot, you lose a week arguing about whose laptop is odd. Packaging the experiment in a container removes most of that argument, and the care you take while doing it is what the Ops Atlas calls ContainerOps. In plain terms, it is looking after single containers, their images and where they are stored, below the level of large schedulers. Follow the nine steps below on any simple simulation script and you will end up with something repeatable.
A note before we begin. The Atlas coined the label itself and no certification exists for it. The practices, though, are sound, and the source worth keeping open is the Atlas page that describes ContainerOps.
Step 1: Write down what the experiment needs
Before touching a build file, list the language version, each library and its version, the command that runs the simulation and the files it reads and writes. This is your recipe card. A simulator’s memory use typically doubles with each additional qubit it models, so also note the largest circuit you plan to run and the memory it will need.
Step 2: Build in two stages
A multi-stage build uses a first stage to install compilers and download packages, then copies only the finished result into a small second stage. The simulation image ends up without build tools, which makes it smaller and leaves less for anyone to misuse. The Atlas points to a bare static base image of about 2 MiB to show how little a last stage can hold. A scripting-language simulator will be bigger, yet the principle survives.
Step 3: Pin the base image by digest
Name your starting image by its digest, the content fingerprint, and not by a moving label such as latest. Now the same build file produces the same foundation next month. To avoid freezing fixes, set up a bot to propose updates to that pin, and test each proposal against a small reference circuit with a known result.
That reference circuit is your regression test: a tiny circuit whose outcome you already know, which tells you whether the machinery behaves before you scale up. It pairs naturally with the kind of problem framing in the article about how quantum methods attack difficult optimisation puzzles.
Step 4: Run as an ordinary user
Add a dedicated user with a numeric ID to the build file and switch to it before the start command. The Atlas uses 65532 as an example. Drop all Linux capabilities in the run settings and, where the program allows it, mount the root filesystem read-only. Give the simulation a single writable directory for its output.
If the program fails because it tried to write somewhere else, you have learned something about its habits. Fix the path rather than reaching for administrator rights.
Step 5: Set memory and process limits
This step matters more for simulations than for most programs. A circuit one qubit larger can need twice the memory, so a careless run can push the host into swapping or trigger a kill. Always set a memory limit and a process limit, as the Atlas advises. If a run is stopped for exceeding it, you will see exit code 137, which is 128 plus the forced-kill signal 9.
Be gentler with CPU caps. Numerical libraries often start one worker per processor they believe exists, and inside a container the usual processor-count call can report the host’s total rather than your allowance. Set the thread count explicitly in an environment variable, so a two-CPU allowance does not become thirty-two workers fighting for time.
Step 6: Teach it to stop politely
Long simulations are exactly the jobs you may need to interrupt. A stop request first delivers a polite termination signal and then, once Compose’s default ten-second grace has elapsed, a forced kill. Write the start command in exec form so your program gets that signal directly, and add a handler that writes a checkpoint of the current state before exiting. If the experiment spawns helper processes, add the init option too.
Step 7: Decide where output and logs go
Simulations produce two kinds of output that need different homes: results you want to keep and chatter you only need for a while. Treat them separately from the start, because mixing them is how a results folder ends up buried under log files.
Mount a volume for results so they outlive the container, and write logs to standard output. Remember that the default json-file log driver does not rotate, so a chatty simulation can fill the disk. Set a maximum file size and file count for the logs.
Step 8: Describe the run in a Compose file
A short Compose file lets collaborators start the whole thing with one command. Include the image reference by digest, the user, the limits, the volume and the environment variables for the seed and thread count. Anyone who reads that file knows exactly how the experiment was run, which is half of reproducibility.
If your team later wants to run many experiments at once, that is the point to think about platform tooling. Our easy roadmap for platform engineering beginners explains where that journey leads, but nothing in this walk-through requires it.
Step 9: Record the digest with the result
When the run finishes, save the image digest, the seed and the Compose file alongside the output. Six months from now, a reviewer asks how a figure was produced, and you can start the exact same build. This habit is the cheapest part of the process and the most often skipped.
An example run, described in words
Imagine a twenty-qubit experiment. You note that the memory estimate is a few gigabytes, set the container limit a little above that and fix the thread count at four. You start the run through Compose, interrupt it halfway to test the checkpoint, restart it and confirm that the output matches an uninterrupted run. Only then do you scale up the circuit, one qubit at a time, watching memory and the throttle counters as you go.
Common problems and quick fixes
- The run stops at the same moment every time. Check memory first. Raise the limit or reduce the circuit size.
- Results differ between two machines. Check whether the image is referenced by tag and not by digest, and whether the seed is fixed.
- Stopping takes ten seconds then fails. The start command is probably in shell form.
- The disk fills overnight. Look at log rotation and at output volume size.
What you have after nine steps
You now have an experiment that travels: one image, one digest, one Compose file, one reference circuit and a note of what it needs. The cost was an afternoon, and the gain is that your next collaborator spends their time on physics rather than on installing packages. Start with the smallest circuit you have, work through the steps once and adjust them to your own workload.