Welcome to Intel® Advisor Python API Documentation!

This module provides access to Intel Advisor results, collected while running the Intel Advisor analysis.

Getting Started

Before you begin, configure the environment:

1. Add path to the pythonapi directory into PYTHONPATH environment variable, or use advixe-vars.* scripts to set up product environment variables automatically. The scripts reside in the Advisor installation directory root

2. Create a new project or open an existing project. These actions are similar to those in the Advisor GUI.

   2.a. You can create a project using the create_project().

   >>> project = advisor.create_project(sys.argv[1])
   

   2.b. If project already exists, you can open a project using the the open_project().

   >>> project = advisor.open_project(sys.argv[1])
   

3. Run the required collection using the Project.collect() method. The following collections are available:

   • advisor.SURVEY

   • advisor.TRIPCOUNTS

   • advisor.MAP

   • advisor.DEPENDENCIES

   • advisor.ROOFLINE

   • advisor.Experimental.ROOFLINE

     >>> res = project.collect(advisor.SURVEY, sys.argv[1])
     

   This action is similar to those in the Advisor GUI and the Advisor Command Line. After collection you do not need to reopen the project.

4. Load the result using the Project.load() method. The following reports are available:

• advisor.SURVEY

• advisor.MAP

• advisor.DEPENDENCIES

• advisor.ALL

  >>> survey = project.load(advisor.SURVEY)
  

If you use the advisor.ALL report type, the Python API will load all available data and merge it into survey bottom-up rows. To check traits and recommendatioins, use advisor.ALL too.

Accessing Data

To access data, use row iterators:

• DataModel.bottomup if advisor.SURVEY or advisor.ALL is loaded
• DataModel.topdown if advisor.SURVEY or advisor.ALL is loaded
• DataModel.map if advisor.MAP is loaded
• DataModel.dependencies if advisor.DEPENDENCIES is loaded

Data Keys and Values

You can access each data row (survey, map, or dependencies) as an associative array.

Print data row as string:

>>> for row in survey.bottomup:
>>>     print(row)

Get all row keys and values:

>>> for key in row:
...     print(key, row[key])

Survey Data

Each Hotspot row has Hotspot.parent attribute and Hotspot.children, Hotspot.assembly, Hotspot.sync iterators and Hotspot.basic_blocks iterators.

Bottom-up is flat, parent and children are empty for all rows.

To print the top-down tree, do the following:

>>> for row in survey.topdown:
...     stack = [(row, 0)]
...     while stack:
...         v, level = stack.pop()
...         for c in v.get_children():
...             stack.append((c, level + 1))
...             print('-' * level + v['function_call_sites_and_loops'])

Hotspot.assembly iterator contains assembly for given row with additional info on arguments and instruction class.

Hotspot.basic_blocks iterator contains basic blocks for given row with additional info. Hotspot.basic_blocks_lite iterator contains basic blocks for given row without additional info.

Get the required instruction mix information using the Hotspot.get_instruction_mix() method. The following types are available:

• advisor.MixType.STATIC_SELF for exclusive (self) statically calculated instruction mix, the same as Hotspot.static_self_mix
• advisor.MixType.DYNAMIC_SELF for exclusive (self) dynamically calculated instruction mix, the same as Hotspot.dynamic_self_mix
• advisor.MixType.DYNAMIC_SELF_AGGREGATED for exclusive (self) dynamically calculated instruction mix including top-down connected metrics, the same as Hotspot.dynamic_self_mix
• advisor.MixType.DYNAMIC_TOTAL_AGGREGATED for inclusive (total) dynamically calculated instruction mix including top-down connected metrics, the same as Hotspot.dynamic_total_mix

Hotspot.sync iterator contains rows from another dataset, corresponding to this row. For example, if row is from bottom-up then row.sync is an iterator over all entries of this row in top-down.

Joined Survey and Refinement Data

If you load advisor.ALL report survey, map, and dependencies data will be available thru the DataModel.bottomup iterator.

Each Hotspot row has keys for map and dependencies analysis values:

>>> for row in data.bottomup:
...     print(row['loop_carries_dependencies'])

You can access map and dependencies sites using the Hotspot.map and Hotspot.dependencies iterators:

>>> for row in data.bottomup:
...     for site in row.map:
...         for problem in site.problems:
...             print(problem)

Map and Dependencies Data

Each Map and Dependencies Site row has the Site.problems iterator.

Each Problem row has the Problem.observations iterator (empty for MAP result).

>>> for site in data.dependencies:
...     print(site)
...     for problem in site.problems:
...         print(problem)
...         for observation in problem.observations:
...             print(observation)

API Reference

advisor.open_project(project_path, mpi_rank=-1)

Opens the Intel Advisor project

Parameters:

• project_path (str) – absolute or relative path to project directory
• mpi_rank (int) – MPI rank to open. If -1 (default) and there are several MPI ranks in the project then rank with lowest number is selected.

Returns:

Project instance

class advisor.Project

Project class is used to load results (Project.load() method), to select loops for deeper analysis (Project.mark_up_* methods) and to collect data (Project.collect() method, Project.collect_ex() method).

collect(collection_type, app_path, collection_args=None, app_args=None, stdout=None, stderr=None, dry_run=False)

Run the project collection.

Required args:

collection_type: type of advisor collection (advisor.SURVEY|advisor.TRIPCOUNTS|advisor.MAP|advisor.DEPENDENCIES|advisor.ROOFLINE) app_path: absolute or relative path to binary file

Optional args:

collection_args: list of collection arguments, for example: [‘delete-tripcounts’, ‘callstack-flops’]. Default value is None. app_args: list of application arguments. Default value is None. stdout: stdout has arguments like subprocess.Popen.stdout: None|subprocess.PIPE|subprocess.STDOUT|open(path_to_log_file, ‘w’). Default value is None. stderr: stderr has arguments like subprocess.Popen.stderr: None|subprocess.PIPE|subprocess.STDOUT|open(path_to_log_file, ‘w’). Default value is None.

Returned value: tuple: return_code, stdout_data, stderr_data

Examples

>>> res = project.collect(advisor.SURVEY, '/home/main')

collect_ex(collection_string, stdout=None, stderr=None, dry_run=False)

Run the project collection.

Required args:

collection_string: collection string for execution through the advixe-cl (without specifying advixe-cl and ‘collect’ option), for example: ‘survey -project-dir home/new_test – /home/main’

Optional args:

stdout: stdout has arguments like subprocess.Popen.stdout: None|subprocess.PIPE|subprocess.STDOUT|open(path_to_log_file, ‘w’). Default value is None. stderr: stderr has arguments like subprocess.Popen.stderr: None|subprocess.PIPE|subprocess.STDOUT|open(path_to_log_file, ‘w’). Default value is None.

Returned value: tuple: return_code, stdout_data, stderr_data

Examples

>>> res = project.collect('survey -project-dir home/new_test -- /home/main')

is_snapshot

load(result_type)

Loads specified results

Parameters:result_type – result type to load, may be advisor.SURVEY, advisor.MAP, advisor.DEPENDENCIES, advisor.ALL. Result types can be combined, for example advisor.ALL is equal to advisor.SURVEY | advisor.MAP | advisor.DEPENDENCIES. Returns:DataModel instance.

mark_up_append(loops)

Append specified loops to the selection.

Parameters:loops – one Hotspot row or iterator over Hotspot rows

Examples

>>> rows = list(survey.bottomup)
>>> project.mark_up_select(rows[0:2])
>>> project.mark_up_append(rows[2])

mark_up_clear()

Removes all loops from the selection

mark_up_len

Number of selected loops.

Examples

>>> project.select(rows[:3])
>>> project.mark_up_len
3

mark_up_remove(loops)

Remove specified loops from the selection.

Parameters:loops – one Hotspot row or iterator over Hotspot rows

Examples

>>> rows = list(survey.bottomup)
>>> project.mark_up_select(rows)
>>> project.mark_up_remove(rows[0:2])

mark_up_select(loops)

Clear previous selection and select specified loops.

Parameters:loops – one Hotspot row or iterator over Hotspot rows

Examples

>>> rows = list(survey.bottomup)[:3]
>>> project.mark_up_select(rows)

system_info

Provides information about system and CPU on machine where project was created or last result was collected.

Returns:dictionary with system information.

class advisor.DataModel

Main class to work with the loaded data

Contains the following row iterators:

• DataModel.bottomup
• DataModel.topdown
• DataModel.map
• DataModel.dependencies

bottomup

Equivalent of DataModel.bottomup_flat

bottomup_flat

Iterator over Hotspot bottom-up rows in flat mode without virtual loops.

bottomup_full

Iterator over Hotspot bottom-up rows.

compare(DataModel)

It compares two DataModels and returns RowMatchInfos result.

Parameters:to be compared with the current DataModel. (DataModel) – Returns:RowMatchInfos instance.

dependencies

Iterator over Dependencies Site rows.

get_bottomup_rows()

Equivalent of DataModel.bottomup_flat

get_cachesim_info(site_id)

Get cache simulator info for one site of collected MAP result.

Parameters:site_id – MAP site id Returns:CacheSimulatorInfo instance

get_column_descriptions()

Get all column descriptions.

get_dependencies()

Equivalent of DataModel.dependencies

get_full_bottomup()

Equivalent of DataModel.bottomup_full

get_gpu_rows(GpuDataType)

get_map()

Equivalent of DataModel.map

get_roofs(number_of_cores, RoofsStrategy)

Gets roofs calculated for a certain number of cores using a specific roof calculation strategy

Parameters:

• number_of_cores – a number of cores for which roofs are calculated
• RoofsStrategy – roof calculation strategy MULTI_THREAD: a strategy that calculates roofs by multi-threaded benchmarks, scales down them to the required number of cores SINGLE_THREAD: a strategy that calculates roofs by single-threaded benchmarks, scales up them to the required number of cores

Returns:

list of RoofItem instances.

Returns single-threaded and multi-threaded roofs. Equivalent of DataModel.roofs

get_topdown_rows()

Equivalent of DataModel.topdown

gpu

Iterator over GpuRow gpu rows.

map

Iterator over MAP Site rows.

memory_levels

metrics

Per program metrics, ProgramMetrics

roofs

Iterator over RoofItem rows.

set_memory_level(x)

topdown

Iterator over Hotspot top-down rows.

class advisor.Hotspot

assembly

Iterator over Hotspot assembly rows.

basic_blocks

Iterator over Hotspot basic blocks with additional info.

basic_blocks_lite

Iterator over Hotspot basic blocks without additional info.

children

Iterator over Hotspot children rows.

dependencies

Iterator over Site rows.

dynamic_self_mix

Iterator over InstructionMixLine for exclusive (self) dynamically calculated instruction mix data.

dynamic_total_mix

Iterator over InstructionMixLine for inclusive (aggregated) dynamically calculated instruction mix data including top-down connected metrics.

get_assembly()

Equivalent of Hotspot.assembly

get_basic_blocks()

Equivalent of Hotspot.basic_blocks

get_children()

Equivalent of Hotspot.chidren

get_custom_instruction_categories_mix()

Arguments are a dict of category name as a key with list related instruction types as a value, breakdown targets before custom categories, breakdown targets after

get_custom_instruction_mix()

Argument is a list of instruction mix breakdown targets in order of interest

get_dependencies()

Equivalent of Hotspot.dependencies

get_instruction_mix(slf, mix_type)

Get iterator for instruction mix of given type. Usually it is just one line, containing instructions breakdown for loop or function.

Parameters:mix_type – one of the constants from MixType Returns:InstructionMixIterator instance

get_map()

Equivalent of Hotspot.map

get_memory_objects()

Equivalent of Hotspot.memory_objects

get_parent()

Equivalent of Hotspot.parent

get_sync()

Equivalent of Hotspot.sync

get_traits()

has_fp_induction

has_openmp

has_reduction

has_simd

has_simd_reduction

is_bottomup

map

Iterator over Site rows.

memory_objects

Iterator over MemoryObjectsLine for accessed heap objects data.

parent

Hotspot parent row.

source

Source snippet

Provides full source and indexes where source for this row begins and ends. source.content[source.begin:source.end] provides snippet for this row.

static_self_mix

Iterator over InstructionMixLine for exclusive (self) statically calculated instruction mix data.

static_total_mix

Iterator over InstructionMixLine for inclusive (aggregated) statically calculated instruction mix data.

sync

Iterator over Hotspot rows from another dataset in pair (bottomup, topdown)corresponding to this row. If row is from the bottomup dataset then sync returns corresponding rows from the topdown and vice versa.

class advisor.Site

assembly

Contains MAP data associated with assembly lines

get_problems()

Equivalent of Site.problems

problems

Iterator over Problem rows.

class advisor.Problem

get_observations()

Equivalent of Problem.observations

observations

Iterator over Observation rows.

class advisor.ProgramMetrics

program_time

total_ai

total_gflops

total_nonzero_ai

total_nonzero_gflops

Indices and tables

• Index
• Search Page