.. Copyright 2017-2021 Lawrence Livermore National Security, LLC and other
   Hatchet Project Developers. See the top-level LICENSE file for details.

   SPDX-License-Identifier: MIT

***************
Getting Started
***************

Prerequisites
=============

Hatchet has the following minimum requirements, which must be installed before Hatchet is run:

#. Python 2 (2.7) or 3 (3.5 - 3.8)
#. matplotlib
#. pydot
#. numpy, and
#. pandas

Hatchet is available on `GitHub <https://github.com/hatchet/hatchet>`_.


Installation
============

You can get hatchet from its `GitHub repository
<https://github.com/hatchet/hatchet>`_ using this command:

.. code-block:: console

  $ git clone https://github.com/hatchet/hatchet.git

This will create a directory called ``hatchet``.

Install and Build Hatchet
-------------------------

To build hatchet and update your PYTHONPATH, run the following shell script
from the hatchet root directory:

.. code-block:: console

  $ source ./install.sh

Note: The ``source`` keyword is required to update your PYTHONPATH environment
variable. It is not necessary if you have already manually added the hatchet
directory to your PYTHONPATH.

Alternatively, you can install hatchet using pip:

.. code-block:: console

  $ pip install hatchet

Check Installation
------------------

After installing hatchet, you should be able to import hatchet when running the Python interpreter in interactive mode:

.. code-block:: console

  $ python
  Python 3.7.4 (default, Jul 11 2019, 01:08:00)
  [Clang 10.0.1 (clang-1001.0.46.4)] on darwin
  Type "help", "copyright", "credits" or "license" for more information.
  >>>

Typing ``import hatchet`` at the prompt should succeed without any error
messages:

.. code-block:: console

  >>> import hatchet
  >>>


Supported data formats
======================

Currently, hatchet supports the following data formats as input:

* `HPCToolkit <http://hpctoolkit.org/index.html>`_ database: This is generated
  by using ``hpcprof-mpi`` to post-process the raw measurements directory
  output by HPCToolkit.
* Caliper `Cali <http://llnl.github.io/Caliper/OutputFormats.html#cali>`_ file:
  This is the format in which caliper outputs raw performance data by default.
* Caliper `Json-split
  <http://llnl.github.io/Caliper/OutputFormats.html#json-split>`_ file: This is
  generated by either running cali-query on the raw caliper data or by enabling
  the mpireport service when using caliper.
* `DOT <https://www.graphviz.org/doc/info/lang.html>`_ format: This is
  generated by using `gprof2dot <https://github.com/jrfonseca/gprof2dot>`_ on
  ``gprof`` or ``callgrind`` output.
* String literal: Hatchet can read as input a list of dictionaries that
  represents a graph.
* List: Hatchet can also read a list of lists that represents a graph.

For more details on the different input file formats, refer to the
:doc:`User Guide <user_guide>`.
