NAME

       futhark-profile - profile Futhark programs

SYNOPSIS

       futhark profile JSONFILES

DESCRIPTION

       This  tool  produces  human-readable  profiling  information  based on information collected with futhark
       bench. Futhark has basic support for profiling. The system can collect  information  about  the  run-time
       behaviour of the program, and connects it as best it is able to the program source code.  This works best
       for  the  GPU backends, and not at all for the sequential backends. The collected information can then be
       used to estimate the source of inefficiencies.

USAGE

       The first step is to run futhark bench on your program, while passing --profile  and  --json.  This  will
       produce  a  JSON file containing runtime measurements, as well as collected profiling information. If you
       neglect to pass --profile, the profiling information will be missing. The information in the JSON file is
       complete, but it is difficult for humans to read.

       The next step is to run futhark profile on the JSON file.  For a JSON file prog.json, this will create  a
       top  level  directory  prog.prof that contains files with human-readable profiling information.  A set of
       files will be created for each benchmark dataset.  If the original invocation of futhark  bench  included
       multiple  programs, then futhark profile will create subdirectories for each program (although all inside
       the same top level directory).

       You can pass multiple JSON files to futhark profile. Each will produce a distinct top level directory.

   Files produced
       Supposing a dataset foo, futhark profile will produce the following files in the top level directory.

       • foo.log: the running log produced  during  execution.  Contains  many  details  on  dynamic  behaviour,
         depending on the exact backend.

       • foo.summary:  a  summary  of  memory usage and cost centres. For the GPU backends, the cost centres are
         kernel executions and memory copies.

       • foo.timeline: a list of all recorded profiling events, in the order in which they occurred, along  with
         their runtime and other available information, most importantly the source locations.

       The log file is often too verbose to be useful, but the summary and timeline should be inspected, even if
       the latter is sometimes fairly large.

   Technicalities
       The  profiling  information,  including  the  log,  is collected from a final run performed after all the
       measured runs.  Profiling information is not collected during the runs that  contribute  to  the  runtime
       measurement  reported  by futhark bench.  However, enabling profiling may still affect performance, as it
       changes the behaviour of the run time system.

   Raw reports
       Alternatively, the JSON file passed to futhark profile may also be a raw profiling report as produced  by
       the  C  API  function futhark_context_report().  A directory is still created, but it will only contain a
       single set of files, and it will not contain a log.

EXAMPLES

       This shows the sequence of commands one might use to profile the program LocVolCalib.fut, which has three
       datasets associated with it, using the hip backend:

          $ futhark bench --backend=hip --profile --json result.json LocVolCalib.fut
          $ futhark profile result.json
          $ tree result.prof/
          result.prof/
          ├── LocVolCalib-data_large.in.log
          ├── LocVolCalib-data_large.in.summary
          ├── LocVolCalib-data_medium.in.log
          ├── LocVolCalib-data_medium.in.summary
          ├── LocVolCalib-data_small.in.log
          └── LocVolCalib-data_small.in.summary

BUGS

       Only the C-based backends currently support profiling.

       The c backend does not actually record useful profiling information.

SEE ALSO

       futhark-bench

COPYRIGHT

       2013-2020, DIKU, University of Copenhagen

0.25.32                                           Aug 22, 2025                                FUTHARK-PROFILE(1)