futhark-profile - profile Futhark programs

       Only the C-based backends currently support profiling.

       The c backend does not actually record useful profiling information.

       2013-2020, DIKU, University of Copenhagen

0.25.27                                           Mar 02, 2025                                FUTHARK-PROFILE(1)

       This  tool  produces  human-readable  profiling  information  based on information collected with futharkbench.  Futhark has only rudimentary support for profiling.  While the  system  can  collect  information
       about  the  run-time  behaviour  of  the  program,  there  is  currently  no automatic way to connect the
       information to the program source code.  However, the collected  information  can  still  be  useful  for
       estimating the source of inefficiencies.

       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

       futhark-profile - profile Futhark programs

futhark-bench

       futhark profile JSONFILES

       The  first  step  is  to run futharkbench 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 futharkprofile on the JSON file.  For a JSON file prog.json, this will create a
       topleveldirectoryprog.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 futharkbench included
       multiple programs, then futharkprofile will create subdirectories for each program (although all  inside
       the same top level directory).

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

   Filesproduced
       Supposing a dataset foo, futharkprofile 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

   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 futharkbench.  However, enabling profiling may still affect performance,  as  it
       changes the behaviour of the run time system.

   Rawreports
       Alternatively,  the  JSON  can  also  contain  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.