Metadata-Version: 1.1
Name: cubex
Version: 0.1
Summary: CUBE .cubex library parser
Home-page: http://github.com/marshallward/cubex
Author: Marshall Ward
Author-email: cubex@marshallward.org
License: UNKNOWN
Description: =====
        cubex
        =====
        
        ``cubex`` is a Python module for analysing CUBE (.cubex) profiles.
        
        
        Quick start guide
        =================
        
        ``cubex`` is still a work in progress, but it is currently useable and the
        following instructions should help you get started.
        
        To create a new ``Cube`` object, open a new file.
        
        .. code:: python
        
           >> import cubex
           >> prof = cubex.open('profile.cubex')
        
        Use the ``show_metrics()`` function to list the available metrics.
        
        .. code:: python
        
           >>> prof.show_metrics()
           bytes_sent
           visits
           time
           ...
        
        By default, ``cubex`` does not load all available metrics into memory.  To load
        the desired metric, say ``time``, use the ``read_data()`` function.
        
        .. code:: python
        
           >> prof.read_data('time')
        
        The ``Cube`` stores the call tree in a list, ``prof.calltrees``.  For most
        programs, this will consist of a single entry.  For profiles containing
        multiple executables (MPMD), each program's calltree will be an element in the
        list.
        
        The call tree can be printed using the ``print_calltree()`` function inside the
        profile's calltree.
        
        .. code:: python
        
           >> prof.calltrees[0].print_tree()
        
        This displays each node of the call tree, indented by depth, and labeled with
        its corresponding region.
        
        At this point, it helps if the user has some intuitive feel for the call tree
        in the profile.  (And if anyone has feedback on how to improve this, please
        submit feedback.)
        
        Having said that, if one knows the function (or "region" in CUBE parlance) of
        interest, then the data is accessed with the ``region`` property.
        
        .. code:: python
        
           >> prof.regions[reg].cnodes
           [<cubex.calltree.CallTree object at 0x7f4437892f90>,
            <cubex.calltree.CallTree object at 0x7f4437539f10>,
            ...
           ]
        
        This returns a list of each node (actually subtree) in the call tree where this
        function was called.
        
        To distinguish between ``cnodes``, one can inspect its call tree (using
        ``print_tree()``) or inspect its parent node.
        
        .. code:: python
        
           >> cnode = prof.regions[reg].cnodes[0]
           >> cnode.parent.region.name
           'function_name_calling_cnode_'
        
        One can also inspect the node index (``cnode.idx``) although this requires some
        knowledge of the tree itself, which can be checked using the CUBE graphical
        browser.
        
        Finally, to get the metric values at the target ``cnode``, access its
        ``metrics`` property.
        
        .. code:: python
        
           >> prof.regions[reg].cnodes[0].metrics['time']
           (496.59532077590507, 291.106782542039, 496.5975198073004, ...)
        
        This returns a list of the time measured in each computational unit, such as an
        MPI rank or OpenMP thread.
        
        
        Notes
        -----
        
        * Region names follow C conventions.  Fortran programs will typically convert
          any function names to lower case and will append a ``_`` to the end of the
          function name.  For example,  a function named ``GET_LAPLACIAN`` will be
          stored as ``get_laplacian_``.
        
          This is the usual convention, but other compilers may deviate from thisj
          so it's recommended that you inspect the regions before accessing them.
        
        * Currently only Score-P output is supported in the ``main`` branch.  Scalasca
          output is slightly different and currently does not work as well in
          ``cubex``.
        
          We have some internal versions that do work, but are not yet user-friendly
          and would need a bit of a cleanup before releasing publicly.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Utilities
