Visible to Intel only — GUID: GUID-AE18BAAC-94F4-4C0B-8D58-1444EA413370
Visible to Intel only — GUID: GUID-AE18BAAC-94F4-4C0B-8D58-1444EA413370
collect.py Options
Depending on options specified, collect basic data, do markup, and collect refinement data. By default, execute all steps. For any step besides markup, you must specify an application argument.
Usage
advisor-python <APM>/collect.py <project-dir> [--options] -- <target> [target-options]
Options
The following table describes options that you can use with the collect.py script. The target application to analyze and application options, if any, must be preceded by two dashes and a space.
Option |
Description |
---|---|
<project-dir> |
Required. Specify the path to the Intel® Advisor project directory. |
-h --help |
Show all script options. |
-v <verbose> --verbose <verbose> |
Specify output verbosity level:
NOTE:
This option affects the console output, but does not affect logs and report results.
|
-c {basic, refinement, full} --collect {basic, refinement, full} |
Specify the type of data to collect for an application:
NOTE:
For --collect full, make sure to use --data-reuse-analysis and --track-memory-objects for the Performance modeling with analyze.py or advisor --collect=projection.
For --collect basic, make sure to use the --track-memory-objects for the Performance modeling with analyze.py or advisor --collect=projection. |
--config <config> |
Specify a configuration file by absolute path or name. If you choose the latter, the model configuration directory is searched for the file first, then the current directory. You can specify several configurations by using the option more than once. |
--data-reuse-analysis | --no-data-reuse-analysis (default) |
Estimate data reuse between offloaded regions. Disabling can decrease analysis overhead.
IMPORTANT:
--collect basic and --collect full overwrite this option. To add the data reuse analysis results to the Offload Modeling report, make sure to use the --data-reuse-analysis option for the Performance modeling with analyze.py or advisor --collect=projection.
|
--data-transfer (default) | --no-data-transfer |
Analyze data transfer.
NOTE:
Disabling can decrease analysis overhead.
|
--dry-run |
Show the Intel® Advisor CLI commands for advisor appropriate for the specified configuration. No actual collection is performed. |
--enable-edram |
Enable eDRAM modeling in the memory hierarchy model.
IMPORTANT:
Make sure to use this option with both collect.py and analyze.py.
|
--enable-slm |
Enable SLM modeling in the memory hierarchy model.
IMPORTANT:
Make sure to use this option with both collect.py and analyze.py.
|
--executable-of-interest <executable-name> |
Specify the executable process name to profile if it is not the same as the application to run. Use this option if you run your application via script or other binary.
NOTE:
Specify the name only, not the full path.
|
--flex-cachesim <cache-configuration> |
Use flexible cache simulation to model cache data for several target devices. The flexible cache simulation allows you to change a device for an analysis without recollecting data. By default, when no configuration is set, cache data is simulated for all supported target platforms. You can also specify a list of cache configurations separated with a forward slash in the format <size_of_level1>:<size_of_level2>:<size_of_level3>. For each memory level size, specify a unit of measure as b - bytes, k- kilobytes, or m - megabytes. For example, 8k:512k:8m/24k:1m:8m/32k:1536k:8m. |
--gpu (recommended) | --profile-gpu | --analyze-gpu-kernels-only |
Model performance only for code regions running on a GPU. Use one of the three options.
IMPORTANT:
Make sure to specify this option for both collect.py and analyze.py.
NOTE:
This is a preview feature. --analyze-gpu-kernels-only is deprecated and will be removed in futire releases.
|
--no-profile-jit (default) |
Disable JIT function analysis. |
-m [{all, generic, regions, omp, icpx -fsycl, daal, tbb}] --markup [{all, generic, regions, omp, icpx -fsycl, daal, tbb}] |
Mark up loops after survey or other data collection. Use this option to limit the scope of further collections by selecting loops according to a provided parameter:
omp, icpx -fsycl, or generic selects loops in the project so that the corresponding collection can be run without loop selection options. You can specify several parameters in a comma-separated list. Loops are selected if they fit any of specified parameters. |
--model-system-calls (default) | --no-model-system-calls |
Analyze regions with system calls inside. The actual presence of system calls inside a region may reduce model accuracy. |
--mpi-rank <mpi-rank> |
Specify a MPI rank to analyze if multiple ranks are analyzed. |
--no-cache-sources |
Disable keeping source code cache within a project. |
--no-cachesim |
Disable cache simulation during collection. The model assumes 100% hit rate for cache.
NOTE:
Usage decreases analysis overhead.
|
--no-stacks |
Run data collection without collecting data distribution over stacks. You can use this option to reduce overhead at the potential expense of accuracy. |
-o <output-dir> --out-dir <output-dir> |
Specify the directory to put all generated files into. By default, results are saved in <advisor-project>/e<NNN>/pp<MMM>/data.0. If you specify an existing directory or absolute path, results are saved in specified directory. The new directory is created if it does not exist. If you only specify the directory <name>, results are stored in <advisor-project>/e<NNN>/pp<MMM>/<name>.
NOTE:
If you use this options, you might not be able to open the analysis results in the Intel Advisor GUI.
|
-p <output-name-prefix> --out-name-prefix <output-name-prefix> |
Specify a string to add to the beginning output result filenames.
NOTE:
If you use this options, you might not be able to open the analysis results in the Intel Advisor GUI.
|
--set-parameter <CLI-config> |
Specify a single-line configuration parameter to modify in a format "<group>.<parameter>=<new-value>". For example: "min_required_speed_up=0", "scale.Tiles_per_process=0.5". You can use this option more than once to modify several parameters.
IMPORTANT:
Make sure to use this option for both collect.py and analyze.py with the same value.
|
--track-heap-objects | --no-track-heap-objects |
Deprecated. Use --track-memory-objects. |
--track-memory-objects (default) | --no-track-memory-objects |
Attribute heap-allocated objects to the analyzed loops that accessed the objects.
IMPORTANT:
This option is always enabled with --collect basic and --collect full. To add the data reuse analysis results to the Offload Modeling report, make sure to use also the --track-memory-objects option for the Performance modeling with analyze.py or advisor --collect=projection.
|
--track-stack-accesses (default) | --no-track-stack-accesses |
Track accesses to stack memory.
IMPORTANT:
This option is always enabled with --collect basic and --collect full. To add the data reuse analysis results to the Offload Modeling report, make sure to use also the --track-memory-objects option for the Performance modeling with analyze.py or advisor --collect=projection.
|
Examples
Collect full data on myApplication with default configuration and save the project to the ./advi directory.
advisor-python $APM/collect.py ./advi_results -- ./myApplication
Collect refinement data for OpenMP* and SYCL loops on myApplication with a custom configuration file config.toml and save the project to the ./advi directory.
advisor-python $APM/collect.py ./advi_results --collect refinement --markup [omp,icpx -fsycl] --config ./config.toml -- ./myApplication
Get commands appropriate for a custom configuration specified in the config.toml file to collect data separately with advisor. The commands are ready to copy and paste.
advisor-python $APM/collect.py ./advi_results --dry-run --config ./config.toml