*******************************
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)
    program = 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.

.. code-block:: python
    :linenos:

    code = "proc program1(graph g; map<vertex, vertex> m) {" \
        + "  for(v: g.nodes) {" \
        + "    m[v] = v;" \
        + "  }" \
        + "}"
    path = self.pgx_test_resources + "/graph_diameter.gm"
    # label_end: example
    # The following are the PgxSession methods used to compile custom algorithms:
    # label_start: compiling_custom_algorithms
    session.compile_program(path, overwrite=False)
    program = session.compile_program_code(code, overwrite=False)
    # label_end: compiling_custom_algorithms
    # Running algorithms
    graph = session.read_graph_with_properties(self.cfg_tiny_het_graph)
    map = graph.create_map("vertex", "vertex")
    program.run(graph, map)