PAPI Low Level API

This module binds the PAPI Low Level API.

Despite our desire to stay as close as possible as the original C API, we had to make a lot of change to make this API more pythonic. If you are used to the C API, please read carefully this documentation.

Simple example:

from pypapi import papi_low as papi
from pypapi import events

papi.library_init()

evs = papi.create_eventset()
papi.add_event(evs, events.PAPI_FP_OPS)

papi.start(evs)

# Do some computation here

result = papi.stop(evs)
print(result)

papi.cleanup_eventset(evs)
papi.destroy_eventset(evs)

Note

This binding is currently very partial, there is a lot of missing function. If you need one of the missing functions, please fill an issue on Github.

pypapi.papi_low.accum(eventSet, values)

Adds the counters of the indicated event set into the array values. The counters are zeroed and continue counting after the operation.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • values (list(int)) – A list to hold the counter values of the counting events.

Return type:

list(int)

Raises:
pypapi.papi_low.add_event(eventSet, eventCode)

Add single PAPI preset or native hardware event to an event set.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • eventCode (int) – A defined event such as PAPI_TOT_INS (from Events).

Raises:
pypapi.papi_low.add_events(eventSet, eventCodes)

Add list of PAPI preset or native hardware events to an event set.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • eventCodes (list(int)) – A list of defined events (from Events).

Raises:
pypapi.papi_low.add_named_event(eventSet, eventName)

Add an event by name to a PAPI event set.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • eventName (str) – Name of a defined event

Raises:
pypapi.papi_low.assign_eventset_component(eventSet, component)

Assign a component index to an existing but empty eventset.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • component (int) – An integer identifier for a component. By convention, component 0 is always the cpu component.

Raises:
pypapi.papi_low.attach(eventSet, pid)

Attach specified event set to a specific process or thread id.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • pid (int) – A process id.

Raises:
pypapi.papi_low.cleanup_eventset(eventSet)

Remove all PAPI events from an event set and turns off profiling and overflow for all events in the EventSet. This can not be called if the EventSet is not stopped.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:

Warning

If the user has set profile on an event with the call, then when destroying the EventSet the memory allocated by will not be freed. The user should turn off profiling on the Events before destroying the EventSet to prevent this behavior.

pypapi.papi_low.create_eventset()

Create a new empty PAPI event set. The user may then add hardware events to the event set by calling add_event() or similar routines.

Returns:

the event set handle.

Return type:

int

Raises:

Note

PAPI-C uses a late binding model to bind EventSets to components. When an EventSet is first created it is not bound to a component. This will cause some API calls that modify EventSet options to fail. An EventSet can be bound to a component explicitly by calling assign_eventset_component() or implicitly by calling add_event() or similar routines.

pypapi.papi_low.destroy_eventset(eventSet)

Deallocates memory associated with an empty PAPI event set.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:

  • PapiInvalidValueError – One or more of the arguments is invalid. Attempting to destroy a non-empty event set or passing in a null pointer to be destroyed.

  • PapiNoEventSetError – The event set specified does not exist.

  • PapiIsRunningError – The event set is currently counting events.

  • PapiBugError – Internal error, please send mail to the developers.

Warning

If the user has set profile on an event with the call, then when destroying the EventSet the memory allocated by will not be freed. The user should turn off profiling on the Events before destroying the EventSet to prevent this behavior.

pypapi.papi_low.detach(eventSet)

Detach specified event set from a previously specified process or thread id.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:
pypapi.papi_low.disable_component(component)

Disables the specified component.

Parameters:

component (int) – component index of component to be disabled

Returns:

component index

Return type:

int

Raises:
pypapi.papi_low.disable_component_by_name(componentName)

Disables the named component.

Parameters:

componentName (str) – name of the component to disable.

Returns:

component index

Return type:

int

Raises:
pypapi.papi_low.enum_cmp_event(component)

Enumerate PAPI preset or native events for a given component.

Parameters:

component (int) – Specifies the component to search in.

Returns:

dictionary of PRESET and NATIVE events.

Return type:

dict

pypapi.papi_low.enum_event()

Enumerate PAPI preset or native events.

Returns:

dictionary of PRESET and NATIVE events.

Return type:

dict

pypapi.papi_low.epc(event=0)

Simplified call to get arbitrary events per cycle, real and processor time.

Parameters:

event (int) – event code to be measured (from Events, default: PAPI_TOT_INS).

Return type:

structs.EPC

Raises:
pypapi.papi_low.event_code_to_name(eventCode)

Convert a numeric hardware event code to a name.

Parameters:

eventCode (int) – The numeric code for the event.

Returns:

the event name

Return type:

str

Raises:
pypapi.papi_low.event_name_to_code(eventName)

Convert a name to a numeric hardware event code.

Parameters:

eventName (str) – A string containing the event name as listed in PAPI_presets or discussed in PAPI_native.

Returns:

the event code.

Return type:

int

Raises:
pypapi.papi_low.flips_rate(event)

Simplified call to get Mflips/s (floating point instruction rate), real and processor time.

Parameters:

event (int) –

one of the three presets in Constants:

Return type:

structs.Flips

Raises:
pypapi.papi_low.flops_rate(event)

Simplified call to get Mflops/s (floating point operation rate), real and processor time.

Parameters:

event (int) –

one of the three presets in Constants:

Return type:

structs.Flops

Raises:
pypapi.papi_low.get_component_index(componentName)

Returns the component index for the named component.

Parameters:

componentName (int) – name of component to find index for

Returns:

component index

Return type:

int

Raises:

PapiNoComponentError – component does not exist

pypapi.papi_low.get_component_info(component)

Get information about a specific software component.

Returns:

component information

Return type:

COMPONENT_info

pypapi.papi_low.get_dmem_info()

Get information about the dynamic memory usage of the current program.

Returns:

dynamic memory usage information

Return type:

DMEM_info

Raises:
pypapi.papi_low.get_event_component(eventCode)

Return component an event belongs to.

Parameters:

eventCode (int) – EventCode for which we want to know the component index.

Returns:

component index

Return type:

int

Raises:

PapiNoComponentError – component does not exist

pypapi.papi_low.get_event_info(eventCode)

Get the event’s name and description info.

Parameters:

eventCode (int) – event code (preset or native).

Returns:

event information

Return type:

EVENT_info

Raises:

  • PapiInvalidValueError – One or more of the arguments is invalid.

  • PapiNotPresetError – The PAPI preset mask was set, but the hardware event specified is not a valid PAPI preset.

  • PapiNoEventError – The PAPI preset is not available on the underlying hardware. This function fills the event information into a structure. In Fortran, some fields of the structure are returned explicitly. This function works with existing PAPI preset and native event codes.

pypapi.papi_low.get_eventset_component(eventSet)

Returns index for component an EventSet is assigned to.

Parameters:

eventSet (int) – EventSet for which we want to know the component index.

Returns:

component index

Return type:

int

Raises:
pypapi.papi_low.get_executable_info()

Get the executable’s address space info.

Returns:

executable information

Return type:

EXECUTABLE_info

Raises:

PapiInvalidValueError – One or more of the arguments is invalid.

pypapi.papi_low.get_hardware_info()

Get information about the system hardware. In C, this function returns a pointer to a structure containing information about the hardware on which the program runs. In Fortran, the values of the structure are returned explicitly.

Returns:

hardware information

Return type:

HARDWARE_info

Raises:

PapiInvalidValueError – One or more of the arguments is invalid.

pypapi.papi_low.get_real_cyc()

Get real time counter value in clock cycles. Returns the total real time passed since some arbitrary starting point. The time is returned in clock cycles. This call is equivalent to wall clock time.

Returns:

total real time passed since some arbitrary starting point

Return type:

ctypes.c_longlong

pypapi.papi_low.get_real_nsec()

Returns total number of nanoseconds since some arbitrary starting point.

Return type:

ctypes.c_longlong

pypapi.papi_low.get_real_usec()

Get real time counter value in microseconds. This function returns the total real time passed since some arbitrary starting point. The time is returned in microseconds. This call is equivalent to wall clock time.

Returns:

total real time passed since some arbitrary starting point

Return type:

ctypes.c_longlong

pypapi.papi_low.get_shared_lib_info()

Get address info about the shared libraries used by the process. In C, this function returns a pointer to a structure containing information about the shared library used by the program. There is no Fortran equivalent call.

Returns:

shared libraries information

Return type:

SHARED_LIB_info

pypapi.papi_low.get_virt_cyc()

Get virtual time counter value in clock cycles

Returns:

virtual time counter value in clock cycles

Return type:

ctypes.c_longlong

pypapi.papi_low.get_virt_nsec()

Get virtual time counter values in nanoseconds.

Returns:

virtual time counter value in nanoseconds

Return type:

c_longlong

pypapi.papi_low.get_virt_usec()

Get virtual time counter values in microseconds.

Returns:

virtual time counter value in microseconds

Return type:

c_longlong

pypapi.papi_low.ipc()

Simplified call to get instructions per cycle, real and processor time.

Return type:

structs.IPC

Raises:
pypapi.papi_low.is_initialized()

Returns the initialized state of the PAPI library.

Returns:

the initialized state of the PAPI library (one of the PAPI Initialization Constants).

Return type:

int

pypapi.papi_low.library_init(version=100663296)

Initializes the PAPI library.

Parameters:

version (int) – upon initialization, PAPI checks the argument against the internal value of PAPI_VER_CURRENT when the library was compiled. This guards against portability problems when updating the PAPI shared libraries on your system (optional, default: pypapi.consts.PAPI_VER_CURRENT).

Raises:

Warning

If you don’t call this before using any of the low level PAPI calls, your application could core dump.

pypapi.papi_low.list_events(eventSet)

List the events that are members of an event set

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Returns:

the list of events.

Return type:

list(int)

Raises:
pypapi.papi_low.list_threads()

List the registered thread ids.

list_threads() returns to the caller a list of all thread IDs known to PAPI. This call assumes an initialized PAPI library

Returns:

the list of threads.

Return type:

list(ctypes.c_ulonglong)

Raises:

PapiInvalidValueError – Internal argument is invalid.

pypapi.papi_low.lock(lock)

Locks one of two mutex variables defined in papi.h.

lock() grabs access to one of the two PAPI mutex variables. This function is provided to the user to have a platform independent call to a (hopefully) efficiently implemented mutex.

Parameters:

lock (int) – an integer value specifying one of the two user locks: PAPI_USR1_LOCK or PAPI_USR2_LOCK.

Returns:

There is no return value for this call. Upon return from PAPI_lock the current thread has acquired exclusive access to the specified PAPI mutex.

pypapi.papi_low.multiplex_init()

Initializes multiplex support in the PAPI library.

multiplex_init() enables and initializes multiplex support in the PAPI library. Multiplexing allows a user to count more events than total physical counters by time sharing the existing counters at some loss in precision. Applications that make no use of multiplexing do not need to call this routine.

pypapi.papi_low.num_cmp_hwctrs(component)

Returns the number of hardware counters for the specified component.

num_cmp_hwctrs() returns the number of counters present in the specified component. By convention, component 0 is always the cpu. On some components, especially for CPUs, the value returned is a theoretical maximum for estimation purposes only. It might not be possible to easily create an EventSet that contains the full number of events. This can be due to a variety of reasons:

  1. CPUs (especially Intel and POWER) have the notion of fixed counters that can only measure one thing, usually cycles.

  2. Some CPUs have very explicit rules about which event can run in which counter. In this case it might not be possible to add a wanted event even if counters are free.

  3. Some CPUs halve the number of counters available when running with SMT (multiple CPU threads) enabled.

  4. Some operating systems “steal” a counter to use for things such as NMI Watchdog timers.

The only sure way to see if events will fit is to attempt adding events to an EventSet, and doing something sensible if an error is generated. library_init() must be called in order for this function to return anything greater than 0.

Parameters:

component (int) – An integer identifier for a component. By convention, component 0 is always the cpu component.

Returns:

On success, this function returns a value greater than zero. A zero result usually means the library has not been initialized.

Return type:

int

pypapi.papi_low.num_components()

Get the number of components available on the system.

Returns:

Number of components available on the system. Query the library for a component count.

Return type:

int

pypapi.papi_low.num_events(eventSet)

Returns the number of events in an event set.

num_events() returns the number of preset and/or native events contained in an event set. The event set should be created by create_eventset.

Parameters:

eventSet (int) – an integer handle for a PAPI event set created by create_eventset.

Returns:

On success, this function returns the positive number of events in the event set.

Return type:

int

Raises:
pypapi.papi_low.perror(msg)

Produces a string on standard error, describing the last library error.

Parameters:

msg (str) – Optional message to print before the string describing the last error message. The routine perror() produces a message on the standard error output, describing the last error encountered during a call to PAPI. If s is not NULL, s is printed, followed by a colon and a space. Then the error message and a new-line are printed

pypapi.papi_low.query_event(eventCode)

Query if PAPI event exists.

Parameters:

eventCode (int) – a defined event such as PAPI_TOT_INS.

Raises:
pypapi.papi_low.query_named_event(eventName)

Query if a named PAPI event exists.

Parameters:

eventName (str) – a defined event such as PAPI_TOT_INS.

Raises:
pypapi.papi_low.rate_stop()

Stops a running event set of a rate function.

Raises:
pypapi.papi_low.read(eventSet)

Copies the counters of the indicated event set into the provided array. The counters continue counting after the read and are not reseted.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Return type:

list(int)

Raises:
pypapi.papi_low.register_thread()

Notify PAPI that a thread has ‘appeared’.

Raises:

  • PapiNoMemoryError – Space could not be allocated to store the new thread information.

  • PapiSystemError – A system or C library call failed inside PAPI, see the errno variable.

  • PapiComponentError – Hardware counters for this thread could not be initialized.

pypapi.papi_low.remove_event(eventSet, eventCode)

Removes a hardware event from a PAPI event set.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • eventCode (int) – A defined event such as PAPI_TOT_INS or a native event. (from Events).

Raises:
pypapi.papi_low.remove_events(eventSet, eventCodes)

Removes an list of hardware events from a PAPI event set.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • eventCodes (int) – A list of defined event (from Events).

Raises:
pypapi.papi_low.remove_named_event(eventSet, eventName)

Removes a named hardware event from a PAPI event set.

A hardware event can be either a PAPI Preset or a native hardware event code. For a list of PAPI preset events, see PAPI_presets or run the papi_avail utility in the PAPI distribution. PAPI Presets can be passed to query_event() to see if they exist on the underlying architecture. For a list of native events available on the current platform, run papi_native_avail in the PAPI distribution.

Parameters:

  • eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

  • eventName (str) – defined event such as PAPI_TOT_INS or a native event.

Raises:
pypapi.papi_low.reset(eventSet)

Reset the hardware event counts in an event set.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:
pypapi.papi_low.set_cmp_domain(domain, component)

Set the default counting domain for new event sets bound to the specified component.

Sets the default counting domain for all new event sets in all threads, and requires an explicit component argument. Event sets that are already in existence are not affected. To change the domain of an existing event set, please see set_opt(). The reader should note that the domain of an event set affects only the mode in which the counter continues to run. Counts are still aggregated for the current process, and not for any other processes in the system. Thus when requesting PAPI_DOM_KERNEL, the user is asking for events that occur on behalf of the process, inside the kernel.

Parameters:

  • domain (int) –

    one of the following constants as defined in Constants:

    Individual components can decode low order bits for more meaning.

  • component (int) – An integer identifier for a component. By convention, component 0 is always the cpu component.

Raises:
pypapi.papi_low.set_cmp_granularity(granularity, component)

Sets the default counting granularity for eventsets bound to the specified component.

Sets the default counting granularity for all new event sets, and requires an explicit component argument. Event sets that are already in existence are not affected. To change the granularity of an existing event set, please see set_opt(). The reader should note that the granularity of an event set affects only the mode in which the counter continues to run.

Parameters:

  • granularity (int) –

    one of the following constants as defined in Constants:

  • component (int) – An integer identifier for a component. By convention, component 0 is always the cpu component.

Raises:
pypapi.papi_low.set_debug(level)

Set the current debug level for error output from PAPI.

Parameters:

level (int) –

one of the constants shown in the table below and defined in the consts.py file. The possible debug levels for debugging are:

Raises:

PapiInvalidValueError – The debug level is invalid. The current debug level is used by both the internal error and debug message handler subroutines.

pypapi.papi_low.set_domain(domain)

Set the default counting domain for new event sets bound to the cpu component.

Sets the default counting domain for all new event sets created by create_eventset() in all threads. This call implicitly sets the domain for the cpu component (component 0) and is included to preserve backward compatibility.

Parameters:

domain (int) –

one of the following constants as defined in Constants:

Raises:

PapiInvalidValueError – One or more of the arguments is invalid.

pypapi.papi_low.set_granularity(granularity)

Sets the default counting granularity for eventsets bound to the cpu component.

Sets the default counting granularity for all new event sets created by create_eventset. This call implicitly sets the granularity for the cpu component (component 0) and is included to preserve backward compatibility.

Parameters:

granularity (int) –

one of the following constants as defined in Constants:

Raises:

PapiInvalidValueError – One or more of the arguments is invalid.

pypapi.papi_low.set_multiplex(eventSet)

Converts a standard event set to a multiplexed event set.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:
pypapi.papi_low.set_opt(*args)

Warning

Not implemented in the Python bindings. Will raise NotImplementedError.

pypapi.papi_low.shutdown()

Finishes using PAPI and free all related resources.

pypapi.papi_low.start(eventSet)

Starts counting all of the hardware events contained in the EventSet. All counters are implicitly set to zero before counting.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:
pypapi.papi_low.state(eventSet)

Returns the counting state of the specified event set.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Returns:

the initialized state of the PAPI library (one of the PAPI State Constants).

Return type:

int

Raises:
pypapi.papi_low.stop(eventSet)

Stops counting hardware events in an event set and return current values.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Return type:

list(int)

Raises:
pypapi.papi_low.strerror(errCode)

Returns a string describing the PAPI error code.

Returns:

Error string. If None is returned, errCode is invalid.

Return type:

str

pypapi.papi_low.thread_id()

Get the thread identifier of the current thread.

Returns:

a valid thread identifier.

Return type:

ctypes.c_ulonglong

Raises:
pypapi.papi_low.unlock(lock)

Unlocks one of the mutex variables.

Parameters:

lock (int) – an integer value specifying one of the two user locks: PAPI_USR1_LOCK or PAPI_USR2_LOCK.

pypapi.papi_low.unregister_thread()

Notify PAPI that a thread has ‘disappeared’.

Raises:

  • PapiNoMemoryError – Space could not be allocated to store the new thread information.

  • PapiSystemError – A system or C library call failed inside PAPI, see the errno variable.

  • PapiComponentError – Hardware counters for this thread could not be initialized.

pypapi.papi_low.write(eventSet)

Write counter values into counters.

Parameters:

eventSet (int) – An integer handle for a PAPI Event Set as created by create_eventset().

Raises:

  • PapiNoEventSetError – The EventSet specified does not exist.

  • PapiComponentError – write() is not implemented for this architecture.

  • PapiSystemError – The EventSet is currently counting events and the component could not change the values of the running counters. write() writes the counter values provided in the array values into the event set EventSet. The virtual counters managed by the PAPI library will be set to the values provided. If the event set is running, an attempt will be made to write the values to the running counters. This operation is not permitted by all components and may result in a run-time error.