<commit_before>.. _usage:

Basic Usage
===========

Futhark contains several code generation backends.  Each is provided
as a full standalone compiler binary.  For example, ``futhark-c``
compiles a Futhark program by translating it to sequential C code,
while ``futhark-pyopencl`` generates Python and the PyOpenCL library.
The different compilers all contain the same frontend and optimisation
pipeline - only the code generator is different.  They all provide
roughly the same command line interface, but there may be minor
differences and quirks due to characteristics of the specific
backends.

There are two main ways of compiling a Futhark program: to an
executable, and to a library.  Executables can be run immediately, but
are useful mostly for testing and benchmarking.  Libraries can be
integrated with non-Futhark code.

Compiling to Executable
-----------------------

A Futhark program is stored in a file with the extension ``.fut``.  It
can be compiled to an executable program as follows::

  $ futhark-c prog.fut

This makes use of the ``futhark-c`` compiler, but any other will work
as well.  The result is an executable binary called ``prog``.  If we
had used ``futhark-py`` instead of ``futhark-c``, the ``prog`` file
would instead have contained Python code, along with a `shebang`_ for
easy execution.  In general, when compiling file ``foo.fut``, the
result will be written to a file ``foo`` (i.e. the extension will be
stripped off).  This can be overridden using the ``-o`` option.

When a Futhark program is run, execution starts at the function named
``main``.  An alternative entry point can be indicated by using the
``-e`` option.  All entry point functions must be declared
appropriately in the program (see :ref:`entry-points`).  If the entry
point takes any parameters, these will be read from standard input in
a subset of the Futhark syntax.  A binary input format is also
supported; see :ref:`binary-data-format`.

Only a subset of all Futhark values can be passed to an executable.
Specifically, only primitives and arrays of primitive types are
supported.  In particular, nested tuples and arrays of tuples are not
permitted.  Non-nested tuples are supported are supported as simply
flat values.  This restriction is not present for Futhark programs
compiled to libraries.  If an entry point *returns* any such value,
its printed representation is unspecified.  As a special case, an
entry point is allowed to return a flat tuple.

Instead of compiling, there is also an interpreter, ``futharki``.  Be
aware that it is very slow, and does not produce better error messages
than the compiler.  **Note:** If you run ``futharki`` without any
options, you will see something that looks deceptively like a `REPL`_,
but it is not yet finished, and only marginally useful in its present
state.

Compiling to Library
--------------------

While compiling a Futhark program to an executable is useful for
testing, it is not suitable for production use.  Instead, a Futhark
program should be compiled into a reusable library in some target
language, enabling integration into a larger program.  At the moment,
this work has only been done for the ``futhark-py`` and
``futhark-pyopencl`` backends, and only the latter of these generates
code of sufficient performance to be worthwhile.

We can use ``futhark-pyopencl`` to translate the program
``futlib.fut`` into a Python module ``futlib.py`` with the following
command::

  futhark-pyopencl --library futlib.fut

This will create a file ``futlib.py``, which contains Python code that
defines a class named ``futlib``.  This class defines one method for
each entry point function (see :ref:`entry-points`) in the Futhark
program.  After the class has been instantiated, these methods can be
invoked to run the corresponding Futhark function.  The reason for why
the module does does not expose functions directly, is that some
complicated initialisation and stateful bookkeeping may be necessary
for sophisticated backends, such as PyOpenCL.

.. _shebang: https://en.wikipedia.org/wiki/Shebang_%28Unix%29
.. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop<commit_msg>More usage documentation.<commit_after>.. _usage:

Basic Usage
===========

Futhark contains several code generation backends.  Each is provided
as a full standalone compiler binary.  For example, ``futhark-c``
compiles a Futhark program by translating it to sequential C code,
while ``futhark-pyopencl`` generates Python and the PyOpenCL library.
The different compilers all contain the same frontend and optimisation
pipeline - only the code generator is different.  They all provide
roughly the same command line interface, but there may be minor
differences and quirks due to characteristics of the specific
backends.

There are two main ways of compiling a Futhark program: to an
executable (by using ``--executable``, which is the default), and to a
library (``--library``).  Executables can be run immediately, but are
useful mostly for testing and benchmarking.  Libraries can be called
from non-Futhark code.

Compiling to Executable
-----------------------

A Futhark program is stored in a file with the extension ``.fut``.  It
can be compiled to an executable program as follows::

  $ futhark-c prog.fut

This makes use of the ``futhark-c`` compiler, but any other will work
as well.  The compiler will automatically invoke ``gcc`` to produce an
executable binary called ``prog``.  If we had used ``futhark-py``
instead of ``futhark-c``, the ``prog`` file would instead have
contained Python code, along with a `shebang`_ for easy execution.  In
general, when compiling file ``foo.fut``, the result will be written
to a file ``foo`` (i.e. the extension will be stripped off).  This can
be overridden using the ``-o`` option.  For more details on specific
compilers, see their individual manual pages.

.. _shebang: https://en.wikipedia.org/wiki/Shebang_%28Unix%29

Executables generated by the various Futhark compilers share a common
command-line interface, but may also individually support more
options.  When a Futhark program is run, execution starts at one of
its *entry points*.  By default, the entry point named ``main`` is
run.  An alternative entry point can be indicated by using the ``-e``
option.  All entry point functions must be declared appropriately in
the program (see :ref:`entry-points`).  If the entry point takes any
parameters, these will be read from standard input in a subset of the
Futhark syntax.  A binary input format is also supported; see
:ref:`binary-data-format`.  The result of the entry point is printed
to standard output.

Only a subset of all Futhark values can be passed to an executable.
Specifically, only primitives and arrays of primitive types are
supported.  In particular, nested tuples and arrays of tuples are not
permitted.  Non-nested tuples are supported are supported as simply
flat values.  This restriction is not present for Futhark programs
compiled to libraries.  If an entry point *returns* any such value,
its printed representation is unspecified.  As a special case, an
entry point is allowed to return a flat tuple.

Instead of compiling, there is also an interpreter, ``futharki``.  Be
aware that it is very slow, and does not produce better error messages
than the compiler.  **Note:** If you run ``futharki`` without any
options, you will see something that looks deceptively like a `REPL`_,
but it is not yet finished, and only marginally useful in its present
state.

.. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop

Executable Options
^^^^^^^^^^^^^^^^^^

All generated executables support the following options.

  ``-t FILE``

    Print the time taken to execute the program to the indicated file,
    an integral number of microseconds.  The time taken to perform tup
    or teardown, including reading the input or writing the sult, is
    not included in the measurement.  See the documentation r specific
    compilers to see exactly what is measured.

  ``-r RUNS``

    Run the specified entry point the given number of times (plus a
    warmup run).  The program result is only printed once, after the
    last run.  If combined with ``-t``, one measurement is printed per
    run.  This is a good way to perform benchmarking.

  ``-D``

    Print debugging information on standard error.  Exactly what is
    printed, and how it looks, depends on which Futhark compiler is
    used.  This option may also enable more conservative (and slower)
    execution, such as frequently synchronising to check for errors.

  ``-b``

    Print the result using the binary data format
    (:ref:`binary-data-format`).  For large outputs, this is
    significantly faster and takes up less space.

The following options are supported by executables generated by
``futhark-opencl`` and ``futhark-pyopencl``:

  ``-p PLATFORM``

    Pick the first OpenCL platform whose name contains the given
    string.  The special string ``#k``, where ``k`` is an integer, can
    be used to pick the *k*-th platform, numbered from zero.

  ``-d DEVICE``

    Pick the first OpenCL device whose name contains the given string.
    The special string ``#k``, where ``k`` is an integer, can be used
    to pick the *k*-th device, numbered from zero.

  ``--dump-opencl FILE``

    Dump the embedded OpenCL program to the indicated file.  May
    useful if you want to see what is actually being executed.

  ``--load-opencl FILE``

    Instead of using the embedded OpenCL program, load it from the
    indicated file.  This is extremely unlikely to result in succesful
    execution unless this file is the result of a previous call to
    ``--dump-opencl`` (perhaps lightly modified).

There is rarely a need to use both ``-p`` and ``-d``.  For example, to
run on the first available NVIDIA GPU, ``-p NVIDIA`` is sufficient, as
there is likely only a single device associated with this platform.
On \*nix (including macOS), the ```clinfo``
<https://github.com/Oblomov/clinfo>_` tool (available in many package
managers) can be used to determine which OpenCL platforms and devices
are available on a given system.  On Windows, `CPU-z
<https://www.cpuid.com/softwares/cpu-z.html>_` can be used.

Compiling to Library
--------------------

While compiling a Futhark program to an executable is useful for
testing, it is not suitable for production use.  Instead, a Futhark
program should be compiled into a reusable library in some target
language, enabling integration into a larger program.  Four of the
Futhark compilers support this: ``futhark-c``, ``futhark-opencl``,
``futhark-py``, and ``futhark-pyopencl``.

General Concerns
^^^^^^^^^^^^^^^^

Futhark entry points are mapped to some form of function or method in
the target language.  Generally, an entry point taking *n* parameters
will result in a function taking *n* parameters.  Extra parameters may
be added to pass in context data, or *out*-parameters for writing the
result, for target languages that do not support multiple return
values from functions.

Not all Futhark types can be mapped cleanly to the target language.
Arrays of tuples are the most common case.  In such cases, *opaque
types* are used in the generated code.  Values of these types cannot
be directly inspected, but can be passed back to Futhark entry points.

Generating C
^^^^^^^^^^^^

A Futhark program ``futlib.fut`` can be compiled to reusable C code
using either::

  $ futhark-c --library futlib.fut

Or::

  $ futhark-c --library futlib.fut

This produces two files in the current directory: ``futlib.c`` and
``futlib.h``.  If we wish (and are on a Unix system), we can then
compile ``futlib.c`` to a shared library like this::

  $ gcc dotprod.c -o libdotprod.so -fPIC -shared

However, details of how to link the generated code with other C code
is highly system-dependent, and outside the scope of this manual.

The generated header file (here, ``futlib.h``) specifies the API, and
is intended to be human-readable.  The basic usages revolves around
creating a *configuration object*, which can then be used to obtain a
*context object*, which must be passed whenever entry points are
call.ed

The configuration object is created using the following function::

  struct futhark_context_config *futhark_context_config_new();

Depending on the backend, various functions are generated to modify
the configuration.  The following is always available::

  void futhark_context_config_set_debugging(struct futhark_context_config *cfg,
                                            int flag);

A configuration object can be used to create a context with the
following function::

  struct futhark_context *futhark_context_new(struct futhark_context_config *cfg);

Memory management is entirely manual.  Deallocation functions are
provided for all types defined in the header file.  Everything
returned by an entry point must be manually deallocated

Generating Python
^^^^^^^^^^^^^^^^^

The ``futhark-py`` and ``futhark-pyopencl`` compilers both support
generating reusable Python code, although the latter of these
generates code of sufficient performance to be worthwhile.  The
following mentions options and parameters only available for
``futhark-pyopencl``.

We can use ``futhark-pyopencl`` to translate the program
``futlib.fut`` into a Python module ``futlib.py`` with the following
command::

  $ futhark-pyopencl --library futlib.fut

This will create a file ``futlib.py``, which contains Python code that
defines a class named ``futlib``.  This class defines one method for
each entry point function (see :ref:`entry-points`) in the Futhark
program.  The methods take one parameter for each parameter in the
corresponding entry point, and return a tuple containing a value for
every value returned by the entry point.  For entry points returning a
single (non-tuple) value, just that value is returned (that is,
single-element tuples are not returned).

After the class has been instantiated, these methods can be invoked to
run the corresponding Futhark function.  The constructor for the class
takes various keyword parameters:

  ``interactive=BOOL``

    If ``True`` (the default is ``False``), show a menu of available
    OpenCL platforms and devices, and use the one chosen by the user.

  ``platform_pref=STR``

    Use the first platform that contains the given string.  Similar to
    the ``-p`` option for executables.

  ``device_pref=STR``

    Use the first device that contains the given string.  Similar to
    the ``-d`` option for executables.

Futhark arrays are mapped to either the Numpy ``ndarray`` type or the
```pyopencl.array`` <https://documen.tician.de/pyopencl/array.html>_`
type.  Scalars are mapped to Numpy scalar types.
{'fraction_non_alphanumeric': 0.07666779546224178, 'fraction_numerical': 0.0018963765662038605, 'mean_word_length': 4.09348051052087, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 7, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6667421', 'n_tokens_mistral': 4032, 'n_tokens_neox': 3901, 'n_words': 2100}