Skip to content

Running Simulations

After being built, GUERNICA can be minimally run with:

bash ./guernica [-o output_dir] [-i file_name.cfg] [--overwrite]

Command-line arguments

GUERNICA supports the following command-line arguments.

-i <file_name>

Input file name.

  • The file must be located at configs/<name>.
  • The default input file is configs/input.cfg.

Example:

bash ./guernica -i test.cfg

-o <output_dir> or --output <output_dir>

Output directory name.

  • All outputs are written to runs/<name>.
  • The output directory name must be unique unless --overwrite is included.
  • The default output directory is run, so outputs are written to runs/run.

Examples:

bash ./guernica -o case1 ./guernica --output case1

--overwrite

Overwrite an existing output directory.

  • This flag does not take any additional argument.
  • If -o is not provided, this overwrites runs/run.

Example:

bash ./guernica -o case1 --overwrite

Resume behavior

If resume = true is set under [time] in the input file, resume settings take precedence over the command line.

In that case:

  • -o / --output are ignored.
  • --overwrite is effectively forced to false.
  • The output directory is taken from resume_directory under [time].
  • If resume_directory is not specified, the default is runs/run.

Example:

ini [time] resume = true resume_directory = runs/my_previous_run

With the above input settings, a command such as

bash ./guernica -o something_else --overwrite

will still resume from runs/my_previous_run.

Common usage examples

Run with defaults:

bash ./guernica

Run with a specific input file:

bash ./guernica -i example.cfg

Run with a specific output directory:

bash ./guernica -o example_run

Run with both a specific input file and output directory:

bash ./guernica -i example.cfg -o example_run

Overwrite an existing output directory:

bash ./guernica -i example.cfg -o example_run --overwrite

Selecting a CUDA device

When running multiple simulations on different CUDA devices, it is often useful to specify which GPU a given simulation should use.

This can be done by prepending the command with CUDA_VISIBLE_DEVICES=<num>:

bash CUDA_VISIBLE_DEVICES=0 ./guernica -o run0 CUDA_VISIBLE_DEVICES=1 ./guernica -o run1

Running in the background

To run a simulation in the background, it is useful to use nohup:

bash nohup ./guernica [-o output_dir] [-i file_name.cfg] [--overwrite] &

For example:

bash nohup ./guernica -i example.cfg -o example_run --overwrite &

Since GUERNICA writes outputs to a log file in the output directory, it is not strictly necessary to additionally redirect output when using nohup. For that reason, a command such as

bash nohup ./guernica > output.log 2>&1 &

is usually unnecessary.

Profiling with Nsight Systems

To profile a simulation and evaluate GPU efficiency, use nsys:

bash nsys profile -o prof --trace=cuda,osrt --sample=none --force-overwrite=true ./guernica [-o output_dir] [-i file_name.cfg] [--overwrite]

Notes

  • This writes profiling output to files such as prof.nsys-rep.
  • --force-overwrite=true allows existing profiling outputs with the same base name to be overwritten.

Example:

bash nsys profile -o prof --trace=cuda,osrt --sample=none --force-overwrite=true ./guernica -i example.cfg -o profile_run --overwrite

Converting profiling output to text

Once the simulation is complete, profiling details can be written to a text file with:

bash nsys stats prof.nsys-rep > prof.txt

This writes the profiling summary to prof.txt.

Opening the Nsight Systems GUI

Profiling results can also be viewed with the GUI:

bash nsys-ui prof.nsys-rep

Profiling and simulation output

When profiling, it can be useful to set

ini [output] profile = 1

in the input file.

This prevents writing results at intermediate time steps controlled by vis_steps, which helps avoid profiling interference from repeated output writes. Final results are still saved, and that final write is included in the profiling.