FLiT Configuration File

The FLiT configuration file is called flit-config.toml. It is written in the TOML specification.

Here I have an example configuration file. I will go through it section by section. If you want to see the full configuration file, it is at the end of this page.

Note: this is not just an example configuration file, it also contains all of the default values too. When your project gets initialized using flit init, that configuration file will also contain the default values. You are welcome to delete or comment out the values, which will cause the default values to be used.

[host]
flit_path = '/usr/bin/flit'
config_dir = '/usr/share/flit/config'

When you initialize your project with flit init, these fields will be populated with values corresponding to the values on your machine:

flit_path: will be initialized to the path of the flit.py script or its symbolic link
config_dir: directory containing default configuration values. Either the one installed (if using flit from an install) or the one from the flit repository (if running directly from a git clone).

Note: if these fields are omitted, then the values of the current machine and flit executable will be used instead. This is useful if you intend to run your tests on multiple machines and if you want to allow using different paths for the flit executable and configuration.

The flit_path variable is put into the generated Makefile so that it can update itself.

[database]
type = 'sqlite3'
filepath = 'results.sqlite'

Above we specify the information for the database. We only support SQLite3 databases currently. Therefore, there exists only one valid value for type, which is sqlite3. If you have need of using something other than SQLite3, please submit an issue.

The filepath field can be relative or absolute and specifies where to store results for a full flit run.

[run]
timing = true
timing_loops = -1
timing_repeats = 3
enable_mpi = false

Here we have information about how to execute the tests. More specifically some options that control the timing. You can turn timing off entirely, or you can change the defaults of the timing if you find it is taking too long to run with the default timing procedure.

These options are only for the full run done by either calling flit make or make run. Some of these options may be used by flit bisect as well, but not the timing ones since flit bisect does not care so much about timing.

timing: false means to turn off the timing feature. The full test run will be much faster with this option. This is related to the --timing and --no-timing flags from the test executable.
timing_loops: The number of loops to run before averaging. For values less than zero, the amount of loops to run will be automatically determined. This is the same as the --timing-loops option flag from the test executable.
timing_repeats: How many times to repeat timing. The minimum timing value will be kept. This is the same as the --timing-repeats option flag from test executable.
enable_mpi: Turns on compiling and running tests with MPI support. See the MPI Support page for more information.

A note about MPI: FLiT requires the tests to be deterministic. If the tests employ MPI, it is the test creator's responsibility to ensure that the test produces identical results every time.

[dev_build]
compiler_name = 'g++'
optimization_level = '-O2'
switches = '-funsafe-math-optimizations'

The [dev_build] section describes the developer build, or the configurations for the make dev target from the autogenerated Makefile (which generates the devrun test executable).

compiler_name: A name matching the name field from the [[compiler]] array section. This will pull in the settings from that compiler for the developer build.
optimization_level: The optimization level to use in compiling devrun
switches: Additional flags to use in compiling devrun

The purpose of the developer build is to try out the tests that you have developed without committing yourself to a full FLiT run. True, that can also be done with the gtrun executable (seen below), but it may be helpful to experiment with a build that contains higher optimizations, such as when you are searching for inputs that demonstrate variability with a particular flag.

For the generated devrun executable, you can call

./devrun --help

to see the options available, such as only running a particular test or outputting debugging information.

[ground_truth]
compiler_name = 'g++'
optimization_level = '-O0'
switches = ''

The [ground_truth] build is intended to be the baseline for all other compilations. Here, you should place the compilation that you trust, as it will become a comparison for all other test results.

The fields here are synonymous with those in the [dev_build]

This configuration specifies the compilation of the gtrun executable created from the make gt target in the autogenerated Makefile. The compiled gtrun executable has the exact same command-line interface as the devrun executable.

[[compiler]]
binary = 'g++'
name = 'g++'
type = 'gcc'
fixed_compile_flags = ''
fixed_link_flags = ''
optimization_levels = [
  '-O0',
  '-O1',
  '-O2',
  '-O3',
]
switches_list = [
  '-fassociative-math',
  '-fcx-fortran-rules',
  '-fcx-limited-range',
  '-fexcess-precision=fast',
  '-ffinite-math-only',
  '-ffloat-store',
  '-ffp-contract=on',
  '-fmerge-all-constants',
  '-fno-trapping-math',
  '-freciprocal-math',
  '-frounding-math',
  '-fsignaling-nans',
  '-funsafe-math-optimizations',
  '-mavx',
  '-mavx2 -mfma',
  '-mfpmath=sse -mtune=native',
  ''
]

Here we specify the first compiler.

binary: The executable for this compiler. The one seen above is a simple name and will use the executable g++ from the system PATH. You can alternatively specify an absolute path or a relative path. If you specify a relative path, it will be relative to the directory containing flit-config.toml, which is the top-level directory for your FLiT tests.
name: A human-readable unique name for this compiler. This could be something like gcc-7.4. It is used in the [dev_build] and [ground_truth] sections to refer to this compiler.
type: The type of compiler. The supported types are gcc, clang and intel. If you need an additional type supported, please submit an issue.
fixed_compile_flags: Compile flags to use specifically with this compiler. These flags will be used in all compilations with this compiler. Here, we didn't specify any, but we could. For example, to use LLVM's libc++ library instead of GCC's libstdc++, you could use the value '-nostdinc++ -I<libcxx-install-prefix>/include/c++/v1'.
fixed_link_flags: Link flags to use specifically with this compiler. These flags will be used in all compilations with this compiler. Here, we didn't specify any, but we could. For example, to use LLVM's libc++ library instead of GCC's libstdc++, you could use the value '-nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc'.
optimization_levels: List of optimization levels to search over. You may remove from or add to this list. If you omit this list, the default list will be used (which is the same as the one shown here). The defaults are specific to the type of compiler. See below for the default list for the other supported compilers.
switches_list: List of switches to search over. You may remove from or add to this list. If you omit this list, the default list will be used (which is the same as the one shown here). The defaults are specific to the type of compiler. See below for the default list for the other supported compilers.

Note that the section has two square brackets around it instead of one. This indicates that it is an array and subsequent instances of [[compiler]] will add to that array.

If the [[compiler]] section is omitted, then the default values will be used which includes the one from above named g++ and the following two:

[[compiler]]
binary = 'clang++'
name = 'clang++'
type = 'clang'
fixed_compile_flags = ''
fixed_link_flags = ''
optimization_levels = [
  '-O0',
  '-O1',
  '-O2',
  '-O3',
]
switches_list = [
  '-fassociative-math',
  '-fexcess-precision=fast',
  '-fexcess-precision=standard',
  '-ffinite-math-only',
  '-ffloat-store',
  '-ffp-contract=on',
  '-fmerge-all-constants',
  '-fno-trapping-math',
  '-freciprocal-math',
  '-frounding-math',
  '-fsignaling-nans',
  '-fsingle-precision-constant',
  '-funsafe-math-optimizations',
  '-march=core-avx2',
  '-mavx',
  '-mavx2 -mfma',
  '-mfpmath=sse -mtune=native',
  ''
]

[[compiler]]
binary = 'icpc'
name = 'icpc'
type = 'intel'
fixed_compile_flags = ''
fixed_link_flags = ''
optimization_levels = [
  '-O0',
  '-O1',
  '-O2',
  '-O3',
]
switches_list = [
  '--use_fast_math',
  '-fcx-limited-range',
  '-ffloat-store',
  '-fma',
  '-fmerge-all-constants',
  '-fp-model fast=1',
  '-fp-model fast=2',
  '-fp-model=double',
  '-fp-model=except',
  '-fp-model=extended',
  '-fp-model=precise',
  '-fp-model=source',
  '-fp-model=strict',
  '-fp-port',
  '-frounding-math',
  '-fsingle-precision-constant',
  '-ftz',
  '-march=core-avx2',
  '-mavx',
  '-mavx2 -mfma',
  '-mfpmath=sse -mtune=native',
  '-mp1',
  '-no-fma',
  '-no-ftz',
  '-no-prec-div',
  '-prec-div',
  ''
]

Do not worry if you do not have all of the compilers on your system, they will be silently ignored if they are not found in the PATH. This is to allow you to use the default values safely.

Full Configuration File

Combining all of the above sections together, here is the full example (and default) configuration file:

[host]
flit_path = '/usr/bin/flit'
config_dir = '/usr/share/flit/config'

[database]
type = 'sqlite'
filepath = 'results.sqlite'

[run]
timing = true
timing_loops = -1
timing_repeats = 3
enable_mpi = false

[dev_build]
compiler_name = 'g++'
optimization_level = '-O2'
switches = '-funsafe-math-optimizations'

[ground_truth]
compiler_name = 'g++'
optimization_level = '-O0'
switches = ''

[[compiler]]
binary = 'g++'
name = 'g++'
type = 'gcc'
fixed_compile_flags = ''
fixed_link_flags = ''
optimization_levels = [
  '-O0',
  '-O1',
  '-O2',
  '-O3',
]
switches_list = [
  '-fassociative-math',
  '-fcx-fortran-rules',
  '-fcx-limited-range',
  '-fexcess-precision=fast',
  '-ffinite-math-only',
  '-ffloat-store',
  '-ffp-contract=on',
  '-fmerge-all-constants',
  '-fno-trapping-math',
  '-freciprocal-math',
  '-frounding-math',
  '-fsignaling-nans',
  '-funsafe-math-optimizations',
  '-mavx',
  '-mavx2 -mfma',
  '-mfpmath=sse -mtune=native',
  ''
]

[[compiler]]
binary = 'clang++'
name = 'clang++'
type = 'clang'
fixed_compile_flags = ''
fixed_link_flags = ''
optimization_levels = [
  '-O0',
  '-O1',
  '-O2',
  '-O3',
]
switches_list = [
  '-fassociative-math',
  '-fexcess-precision=fast',
  '-fexcess-precision=standard',
  '-ffinite-math-only',
  '-ffloat-store',
  '-ffp-contract=on',
  '-fmerge-all-constants',
  '-fno-trapping-math',
  '-freciprocal-math',
  '-frounding-math',
  '-fsignaling-nans',
  '-fsingle-precision-constant',
  '-funsafe-math-optimizations',
  '-march=core-avx2',
  '-mavx',
  '-mavx2 -mfma',
  '-mfpmath=sse -mtune=native',
  ''
]

[[compiler]]
binary = 'icpc'
name = 'icpc'
type = 'intel'
fixed_compile_flags = ''
fixed_link_flags = ''
optimization_levels = [
  '-O0',
  '-O1',
  '-O2',
  '-O3',
]
switches_list = [
  '--use_fast_math',
  '-fcx-limited-range',
  '-ffloat-store',
  '-fma',
  '-fmerge-all-constants',
  '-fp-model fast=1',
  '-fp-model fast=2',
  '-fp-model=double',
  '-fp-model=except',
  '-fp-model=extended',
  '-fp-model=precise',
  '-fp-model=source',
  '-fp-model=strict',
  '-fp-port',
  '-frounding-math',
  '-fsingle-precision-constant',
  '-ftz',
  '-march=core-avx2',
  '-mavx',
  '-mavx2 -mfma',
  '-mfpmath=sse -mtune=native',
  '-mp1',
  '-no-fma',
  '-no-ftz',
  '-no-prec-div',
  '-prec-div',
  ''
]

Prev | Table of Contents | Next

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

flit-configuration-file.md

flit-configuration-file.md

FLiT Configuration File

Full Configuration File

Files

flit-configuration-file.md

Latest commit

History

flit-configuration-file.md

File metadata and controls

FLiT Configuration File

Full Configuration File