pylikwid

Python interface for the C API of LIKWID (https://github.com/RRZE-HPC/likwid)

.. image:: https://travis-ci.com/RRZE-HPC/pylikwid.svg?branch=master :target: https://travis-ci.com/RRZE-HPC/pylikwid?branch=master

Installation

I added a setup.py script for the installation. It builds the C module and copies it to the proper destination.

::

$ git clone https://github.com/RRZE-HPC/pylikwid.git
$ cd pylikwid
# Build C interface
$ python setup.py build_ext -I <include path for likwid> -L <library path for likwid> -R <library path for likwid>
# Install module to the proper location
$ python setup.py install (--prefix=<where to install>)
# Testing
$ python -c "import pylikwid"
$ ./testlib.py

Functions

After import pylikwid you can call the following functions:

Marker API

• pylikwid.markerinit(): Initialize the Marker API of the LIKWID library. Must be called previous to all other functions.
• pylikwid.markerthreadinit(): Add the current thread to the Marker API. Since Python is commonly single-threaded simply call it directly after pylikwid.markerinit()
• rr = pylikwid.registerregion(regiontag): Register a region to the Marker API. This is an optional function to reduce the overhead of region registration at pylikwid.markerstartregion. If you don't call pylikwid.registerregion(regiontag), the registration is done at pylikwid.markerstartregion(regiontag). On success, 0 is return. If you havn't called pylikwid.markerinit(), a negative number is returned.
• err = pylikwid.markerstartregion(regiontag): Start measurements under the name regiontag. On success, 0 is return. If you havn't called pylikwid.markerinit(), a negative number is returned.
• err = pylikwid.markerstopregion(regiontag): Stop measurements under the name regiontag again. On success, 0 is return. If you havn't called pylikwid.markerinit(), a negative number is returned.
• num_events, events[], time, count = pylikwid.markergetregion(regiontag): Get the intermediate results of the region identified by regiontag. On success, it returns the number of events in the current group, a list with all the aggregated event results, the measurement time for the region and the number of calls.
• pylikwid.nextgroup(): Switch to the next event set in a round-robin fashion. If you have set only one event set on the command line, this function performs no operation.
• pylikwid.markerreset(regiontag): Reset the values stored using the region name regiontag. On success, 0 is returned.
• pylikwid.markerclose(): Close the connection to the LIKWID Marker API and write out measurement data to file. This file will be evaluated by likwid-perfctr.
• pylikwid.getprocessorid(): Returns the ID of the currently executing CPU
• pylikwid.pinprocess(cpuid): Pins the current process to the CPU given as cpuid.
• pylikwid.pinthread(cpuid): Pins the current thread to the CPU given as cpuid.

Topology

• pylikwid.inittopology(): Initialize the topology module (reads in system topology)

• infodict = pylikwid.getcpuinfo(): Return a dict with general information about the system (CPU model, CPU family, ...)

  • osname: Name of the CPU retrieved from the CPUID leafs
  • name: Name of the micro architecture
  • short_name: Short name of the micro architecture
  • family: ID of the CPU family
  • model: Vendor-specific model number of the CPU
  • stepping: Stepping (Revision) of the CPU
  • perf_version: Version number of the hardware performance monitoring capabilities
  • perf_num_ctr: Amount of general-purpose counter registers per hardware thread
  • perf_num_fixed_ctr: Amount of fixed-purpose counter registers per hardware thread
  • perf_width_ctr: Bit length of the counter registers
  • clock: CPU clock (only unequal to 0 if timer module is initialized)
  • turbo: Is turbo mode supported?
  • isIntel: Is it an Intel CPU?
  • supportUncore: Does the system have performance monitoring counters in the Uncore?
  • features: String with performance relevant CPU features (AVX, SSE, ...)
  • featureFlags: Bitmask for all available CPU features

• topodict = pylikwid.getcputopology(): Return a dict with the topology of the system. Here is a list of fields in the dict:

  • numSockets: Number of CPU sockets

  • numHWThreads: Number of hardware threads (physical + hyperthreading cores)

  • activeHWThreads: Number of active/usable hardware threads

  • numCoresPerSocket: Amount of hardware threads per CPU socket

  • numThreadsPerCore: Amount of hardware threads assembled in every physical CPU core

  • numCacheLevels: Amount of levels in cacheing hierarchy

  • cacheLevels: Dict with information about the cache levels, keys are the levels (1, 2, 3,...)

    • level: Level of the cache in the hierarchy
    • lineSize: Size of a cache line
    • sets: Amount of sets
    • inclusive: Is the cache inclusive or exclusive?`
    • threads: Amount of threads attached to the cache
    • associativity: Associativity of the cache
    • type: data (= data cache), unified = (data + instruction cache)
    • size: Size of the cache in bytes

  • threadPool: Dict with information about the hardware threads. Keys are the os-generated ID of the hardware thread

    • coreId: ID of the corresponding physical core
    • apicId: ID set by the operating system
    • threadId: ID of the hardware thread in the physical core
    • packageId: ID of the CPU socket hosting the hardware thread

• pylikwid.printsupportedcpus(): Prints all supported micro architecture names to stdout

• pylikwid.finalizetopology(): Delete all information in the topology module

NUMA

• numadict = pylikwid.initnuma(): Initialize the NUMA module and return the gathered values

  • numberOfNodes: Amount of NUMA nodes in the system

  • nodes: Dict holding the information about the NUMA domains. Keys are the NUMA domain IDs

    • id: ID of the NUMA domain (should be equal to dict key)
    • numberOfProcessors: Number of hardware threads attached to the NUMA domain
    • processors: List of all CPU IDs attached to the NUMA domain
    • freeMemory: Amount of free memory in the NUMA domain (in Kbytes)
    • totalMemory: Amount of total memory in the NUMA domain (in Kbytes)
    • numberOfDistances: How many distances to self/other NUMA domains
    • distances: List with distances, NUMA domain IDs are the destination indexes in the list

• pylikwid.finalizenuma(): Delete all information in the NUMA module

Affinity

• affdict = pylikwid.initaffinity(): Initialize the affinity domain module and return the gathered values

  • numberOfAffinityDomains: Amount of affinity domains

  • numberOfSocketDomains: Amount of CPU socket related affinity domains

  • numberOfNumaDomains: Amount of NUMA related affinity domains

  • numberOfCacheDomains: Amount of last level cache related affinity domains

  • numberOfProcessorsPerSocket: Amount of hardware threads per CPU socket

  • numberOfCoresPerCache: Amount of physical CPU cores per last level cache

  • numberOfProcessorsPerCache: Amount of hardware threads per last level cache

  • domains: Dict holding the information about the affinity domains

    • tag: Name of the affinity domain (N = node, SX = socket X, CY = cache Y, MZ = memory domain Z)
    • numberOfProcessors: Amount of hardware threads in the domain
    • numberOfCores: Amount of physical CPU cores in the domain
    • processorList: List holding the CPU IDs in the domain

• pylikwid.finalizeaffinity(): Delete all information in the affinity domain module

• pylikwid.cpustr_to_cpulist(): Transform a valid cpu string in LIKWID syntax into a list of CPU IDs

Timer

• pylikwid.getcpuclock(): Return the CPU clock
• t_start = pylikwid.startclock(): Start the clock and return the current timestamp
• t_end = pylikwid.stopclock(): Stop the clock and return the current timestamp
• t = pylikwid.getclock(t_start, t_end): Return the time in seconds between t_start and t_end
• c = pylikwid.getclockcycles(t_start, t_end): Return the amount of CPU cycles between t_start and t_end

Temperature

• pylikwid.inittemp(cpu): Initialize the temperature module for CPU cpu
• pylikwid.readtemp(cpu): Read the current temperature of CPU cpu

Energy

• pinfo = pylikwid.getpowerinfo(): Initializes the energy module and returns gathered information. If it returns None, there is no energy support

  • minFrequency: Minimal possible frequency of a CPU core

  • baseFrequency: Base frequency of a CPU core

  • hasRAPL: Are energy reading supported?

  • timeUnit: Time unit

  • powerUnit: Power unit

  • domains: Dict holding the information about the energy domains. Keys are PKG, PP0, PP1, DRAM

    • ID: ID of the energy domain
    • energyUnit: Unit to derive raw register counts to uJ
    • supportInfo: Is the information register available?
    • tdp: TDP of the domain (only if supportInfo == True)
    • minPower: Minimal power consumption by the domain (only if supportInfo == True