*******************************
Running Custom Graph Algorithms
*******************************

This section explains the API's ability to compile and run custom algorithms. The APIs for built-in algorithms can be
found in our :ref:`Analyst <analyst>` API section.

Compiling Custom Algorithms
---------------------------

PGX allows users to implement custom graph algorithms with the Green-Marl DSL. PGX then compiles the given graph algorithm, so that it may be executed.
The following are the :class:`PgxSession` methods used to compile custom algorithms:

.. code-block:: python
    :linenos:

    session.compile_program(path, overwrite=False)
    session.compile_program_code(code, overwrite=False)

The Green-Marl code to compile can either be assigned directly (``code``) or via a file path.
This method returns a :class:`CompiledProgram` instance that contains a method to run the compiled algorithm as well as signature information.

Running Algorithms
------------------

The following generic method in :class:`CompiledProgram` is used to run compiled algorithms:

.. code-block:: python
    :linenos:

    program.run(*argv)

Fundamentally, the method invokes the compiled algorithm with the given arguments (``args``). 

.. note::

    The given ``args`` must match the signature of the graph algorithm. Otherwise, PGX throws a type mismatch exception to the client.
 
The above method returns a ``Dict`` object, which contains not only the return value of the algorithm, but also other information
such as exception status and execution time.