Running QHG

In this document we describe the various ways to run QHG.

Description of Options

When calling QHG without any options,

QHGMain

you will be presented with a list of possible options. To get detailed information about an option, use the --help= option:

QHGMain --help=read-config

The same information can be found in the code documentation QHGMain.

Running with Explicit Options

The basic way to run QHG is to list all options after the QHGMain.

QHGMain -data-dirs=${QHG4_DIR}/tutorial_data/grids/   \
     --events='write|grid+geo+pop:sapiens@20000' \
     --grid=ico32s.qdf   --log-file=tutorial_02.log  \
     --num-iters=200     --output-dir=output/tutorial_02 \
     --output-prefix=tut --pops='tut_OldAgeDie.xml:tut_OldAgeDie.dat' \
     --shuffle=92244 --start-time=0

This command could be on one line only - for better readbility it has been spread over several lines.

It is very useful to capture the standard output to see additional information:

QHGMain -data-dirs=... ... --start-time=0 > SimOutput.out

Using a Configuration File

Since in normal use cases there are a lot of options, it might be useful to use a configuration file. A configuration file is a simple text file containing all the options, one per line, for example

--data-dirs=${QHG4_DIR}/tutorial_data/grids/
--events='write|grid+geo+pop:sapiens@20000'
--grid=ico32s.qdf
--log-file=tutorial_02.log
--num-iters=200
--output-dir=output/tutorial_02
--output-prefix=tut
--pops='tut_OldAgeDie.xml:tut_OldAgeDie.dat'
--shuffle=92244
--start-time=0

Then you can call QHG like this:

QHGMain --read-config=my_config.cfg > SimOutput.out

Any options you explicitly add on the command line will override the ones in the configuration file. For instance,

QHGMain --read-config=my_config.cfg --num-iters=600 > SimOutput.out

This will run the simulation with the options defined in my_config.cfg, except for --num_iters which will be set to 600.

Working with Plugins

For this you will have to compile QHG like this:

DYNAMIC_POPS=1 OPT=1 OUT=QHGMainDyn make clean QHGMain

(The “OUT=QHGMainDyn” will cause the compiled application to be renamed to “QHGMainDyn”. And you will have to have make some plugins,too (if you have not built them already). For example

SHORT=tut_08 OPT=1 OUT=~/my_so_dir make plugina

This will build the so-files for the plugin and save them in the specified directory.

To run:

QHGMainDyn --read-config=my_config.cfg --dyn-pops --so-dirs=~/my_so_dir > SimOutput.out

Exploiting parallelism

Time-critical parts of QHG4’s code are parallelized wirh OpenMP. The use of parallelsm noticeably speeds up QHG.

To run a simulation with 8 threads:

Note that above a certain number of threads additional threads will not yield any increase in performance. This limit is hardware dependent.