smpirun(1)

📦
version 4.1 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 smpirun — like, the manual page, bestie 💅

okay so you found smpirun(1) from the General Commands Manual and honestly? iconic. let's get into it. 🦋

✨ NAME ✨

smpirun — run your MPI programs inside the SimGrid simulator. no actual cluster required, we're just vibing in simulation land 💖

🌸 SYNOPSIS 🌸

smpirun [SMPI OPTIONS]… -platform <platform.xml> -hostfile <hostfile>
program [SIMULATION OPTIONS] [PROGRAM OPTIONS]

🎀 DESCRIPTION 🎀

so basically, smpirun runs MPI programs that you compiled with smpicc, but on top of the simulator. that's the whole thing. that's the moment. 👑

like, it takes your hostfile, generates a deployment file from it if it needs one, and then launches the simulation with all the right arguments. it's designed to be easy for regular MPI users — no cap, that's literally the goal. it's giving "just works" energy. ✨

👑 MANDATORY PARAMETERS 👑

these are not optional bestie. you need these. periodt.

  • -platform <platform.xml> — the XML file that describes the platform you wanna deploy your program on. pls go read the online documentation for the deets. 📄
  • -hostfile, -machinefile <hostfile> — the hostfile, listing every single machine that's in use. yes both spellings work, they're the same thing. 🫶

🔥 SMPI OPTIONS 🔥

sm pirun itself accepts some optional parameters — and heads up, do not mix these up with the configuration options in the next section, they're a different vibe entirely. 🙈

  • -help — prints the usage plus a lil summary of all the available options.
  • -keep-temps — do not remove the generated files after execution. they stay. they live here now. 💀
  • -wrapper <command> — use command to run the program (like "valgrind", "gdb --args", "rr record"). you usually wanna pair this with the -foreground option too, so the child gets a TTY. 🧚
  • -gdb — run within GDB. it's equivalent to -wrapper "gdb --args" -keep-temps. slay.
  • -lldb — run within LLDB. equivalent to -wrapper "lldb --" -keep-temps.
  • -vgdb — run within Valgrind+GDB. equivalent to -wrapper "valgrind --vgdb=yes --vgdb-error=0" -keep-temps.
  • -foreground — run the child process in the foreground. this gives the child process access to the TTY. 🖥️
  • -map — display which machine each process rank is mapped onto. so you know who's where.
  • -np <numprocs> — use that many processes. by default you get the same number of processes as there are hosts in the hostfile. math is math. 🍓
  • -no-privatize — disables the privatization of global variables, which is activated by default. > ⚠️ this should only be necessary if you use dynamic libraries — but honestly you should probably link statically instead of disabling this. and do not link statically against SimGrid, only against the other libraries. fr fr, read that twice.
  • -trace — activate the trace mechanism if it's available. equivalent to --cfg=tracing:yes --cfg=tracing/smpi:yes.
  • -trace-ti — activate time independent tracing.
  • -trace-comment <comment> — put a comment at the top of the trace file.
  • -trace-comment-file <file> — insert the content of file at the head of the trace file, as a comment.
  • -trace-grouped — group MPI processes by location.
  • -trace-resource — trace resource utilization.
  • -trace-file <tracefile> — name of the tracefile.
  • -replay <tracefile> — replay a trace instead of actually executing an application.
  • -quiet — reduce output verbosity. this one's useful for making tests reproducible. 🌈
  • -version — displays the SimGrid version (the human readable one).
  • -git-version — displays the git hash of SimGrid.

🌟 SIMULATION OPTIONS 🌟

you can change so many simulation parameters right from the command line by passing --cfg=parameter:value after the program name. the full list of existing parameters and what they mean lives at https://simgrid.org/doc/latest/Configuring_SimGrid.html — go look, there's a lot. 💜

here are some options commonly used with SMPI:

  • --cfg=smpi/cpu-threshold:XXX — only simulate computation chunks that last more than XXX seconds.
  • --cfg=smpi/simulate-computation:no — disable the simulation of all computation chunks (which are still executed on the host machine, fyi).

🫶 AUTHORS 🫶

The SimGrid team. (the whole squad, love them)

Copyright (c) 2014-2025. The SimGrid Team. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the terms of GNU LGPL (v2.1) license.

⭐ SEE ALSO ⭐

smpicc(1) smpicxx(1) smpiff(1) smpif90(1)

and that's the whole page, bestie — this was smpirun(1) from the General Commands Manual, and yes the footer says smpirun(1) again because the manpage format is nothing if not consistent. 💅✨

📦 where this page comes from