MAP and Performance Reports variables

This table provides a reference to environment variables you can use for Arm® MAP and Arm® Performance Reports, with guidance on requirements and best practices for using them.

Variable	Description
`ALLINEA_SAMPLER_INTERVAL`	Takes a sample in each 20ms period, which gives a default sampling rate of 50Hz. The 50Hz sampling rate automatically decreases as the run proceeds to ensure a constant number of samples are taken. For more information, see `ALLINEA_SAMPLER_NUM_SAMPLES`. If your program runs for a very short period of time, you might benefit by decreasing the initial sampling interval. For example, `ALLINEA_SAMPLER_INTERVAL=1` sets an initial sampling rate of 1000Hz, or once per millisecond. Higher sampling rates are not supported. Arm recommends that you avoid increasing the sampling frequency from the default if there are many threads or very deep stacks in the target program. Increasing the sampling frequency might not allow enough time to complete one sample before the next sample starts. Note Custom values for `ALLINEA_SAMPLER_INTERVAL` can be overwritten by values set from the combination of `ALLINEA_SAMPLER_INTERVAL_PER_THREAD` and the expected number of threads (from `OMP_NUM_THREADS`). For more information, see `ALLINEA_SAMPLER_INTERVAL_PER_THREAD`.
`ALLINEA_SAMPLER_INTERVAL_PER_THREAD`	To keep overhead low, this imposes a minimum sampling interval based on the number of threads. By default, this is 2 milliseconds per thread. For 11 or more threads, the initial sampling interval increases to more than 20ms. To adjust the minimum per-thread sample time, set `ALLINEA_SAMPLER_INTERVAL_PER_THREAD` in milliseconds. Arm recommends that you avoid lowering this value from the default if there are many threads. Lowering this value might not allow enough time to complete one sample before the next sample starts. Note Whether OpenMP is enabled or disabled, the final script or scheduler values set for `OMP_NUM_THREADS` are used to calculate the sampling interval per thread (`ALLINEA_SAMPLER_INTERVAL_PER_THREAD`). When you configure your job for submission, check whether the final submission script, scheduler, or the Arm® MAP user interface has a default value for `OMP_NUM_THREADS`. Custom values for `ALLINEA_SAMPLER_INTERVAL` are overwritten by values set from the combination of `ALLINEA_SAMPLER_INTERVAL_PER_THREAD` and the expected number of threads (from `OMP_NUM_THREADS`).
`ALLINEA_MPI_WRAPPER`	To use a specific wrapper library, set `ALLINEA_MPI_WRAPPER=<path of shared object>`. Arm® MAP and Arm® Performance Reports include several precompiled wrappers. If your MPI is supported, they automatically select and use the appropriate wrapper. To manually compile a wrapper specifically for your system, set `ALLINEA_WRAPPER_COMPILE=1` and `MPICC`, and run `<MAP-installation-directory>/map/wrapper/build_wrapper`. Running `build_wrapper` generates the wrapper library `~/.allinea/wrapper/libmap_sampler_pmpi_<hostname>.so` with symlinks. Symlinks are generated for these files: ~/.allinea/wrapper/libmap-_sampler-_pmpi-_<_hostname>_.so.1 ~/.allinea/wrapper/libmap-_sampler-_pmpi-_<_hostname>_.so.1.0 ~/.allinea/wrapper/libmap-_sampler-_pmpi-_<_hostname>_.so.1.0.0 Note To prevent unauthorized users modifying sensitive files and directories, and introducing unsafe code into your environment, ensure that you assign only the minimum permissions that are required, and avoid group or world-writable permissions.
`ALLINEA_WRAPPER_COMPILE`	To instruct Arm® MAP and Arm® Performance Reports to fall back to create and compile a just-in-time wrapper, set `ALLINEA_WRAPPER_COMPILE=1`. To generate a just-in-time wrapper, an appropriate compiler must be available on the machine where Arm® Forge is running, or on the remote host when using remote connect. Arm® MAP and Arm® Performance Reports attempt to auto detect your MPI compiler. However, Arm recommends that you set the `MPICC` environment variable to the path to the correct compiler.
`ALLINEA_MPIRUN`	The path of mpirun, mpiexec, or equivalent. If set, `ALLINEA_MPIRUN` has higher priority than the path set in the user interface and the `mpirun` found in `PATH`.
`ALLINEA_SAMPLER_NUM_SAMPLES`	By default, Arm® MAP and Arm® Performance Reports collect 1000 samples per process. To avoid generating too much data on long runs, the sampling rate automatically decreases as the run progresses, to ensure that only 1000 evenly spaced samples are stored. To adjust the sampling rate, set `ALLINEA_SAMPLER_NUM_SAMPLES=<positive integer>`. Note Arm recommends that you leave this value at the default setting. Higher values are not generally beneficial, and add extra memory overheads while running your code. Consider that with 512 processes, the default setting already collects half a million samples over the job, and the effective sampling rate can be very high indeed.
`ALLINEA_KEEP_OUTPUT_LINES`	Specifies the number of lines of program output to record in `.map` files. Setting to `0` removes the line limit restriction. However, Arm recommends that you avoid setting `ALLINEA_KEEP_OUTPUT_LINES=0` because it can result in very large `.map` files if the profiled program produces a lot of output. To learn more, see Restrict output.
`ALLINEA_KEEP_OUTPUT_LINE_LENGTH`	The maximum line length for program output that is recorded in `.map` files. Lines that contain more characters than the line length limit are truncated. Setting this to `0` removes the line length restriction. However, Arm recommends that you avoid doing setting `ALLINEA_KEEP_OUTPUT_LINE_LENGTH=0` because it can result in very large `.map` files if the profiled program produces a lot of output per line. To learn more, see Restrict output.
`ALLINEA_PRESERVE_WRAPPER`	To gather data from MPI calls, Arm® MAP generates a wrapper to the chosen MPI implementation. See Prepare a program for profiling. By default, the generated code and shared objects are deleted when Arm® MAP no longer needs them. To prevent Arm® MAP and Arm® Performance Reports from deleting these files, set `ALLINEA_PRESERVE_WRAPPER=1`. Note If you use remote launch, this variable must be exported in the remote script. See Remote connections dialog.
`ALLINEA_SAMPLER_NO_TIME_MPI_CALLS`	Set this to prevent Arm® MAP and Arm® Performance Reports from timing the time spent in MPI calls.
`ALLINEA_SAMPLER_TRY_USE_SMAPS`.	To allow Arm® MAP and Arm® Performance Reports to use `/proc/[pid]/smaps` to gather memory usage data, set `ALLINEA_SAMPLER_TRY_USE_SMAPS`. Note `ALLINEA_SAMPLER_TRY_USE_SMAPS` significantly slows down sampling.
`MPICC`	To create the MPI wrapper and Arm® Performance Reports attempt to use `MPICC`. If `MPICC` fails, Arm® MAP and Arm® Performance Reports search for a suitable MPI compiler command in `PATH`. If the MPI compiler used to compile the target binary is not in `PATH` (or if there are multiple MPI compilers in `PATH`), set `MPICC`.