GraphAlg Tutorial

README.md

@@ -1,9 +1,11 @@
 # GraphAlg: A Embeddable Language for Writing Graph Algorithm in Linear Algebra
 This repository contains code related to the GraphAlg language:
 - `codemirror-lang-graphalg`: Language Support for Codemirror
-- `compiler/`: The GraphAlg compiler
+- `compiler/`: The GraphAlg compiler.
+  Includes the parser, lowering to GraphAlg Core, high-level optimizations, and a reference backend for executing algorithms.
 - `playground/`: The GraphAlg online playground
 - `spec/`: The GraphAlg Language Specification
+- `tutorial/`: A tutorial for new GraphAlg users
 
 ## Building
 This assumes you are using the provided [devcontainer](https://containers.dev/) development environment.

_config.yml

@@ -42,6 +42,7 @@ exclude:
   - package-lock.json
   - package.json
   - README.md
+  - thirdparty
 
 sass:
   quiet_deps: true # https://github.com/just-the-docs/just-the-docs/issues/1541

index.md

@@ -7,7 +7,60 @@ nav_order: 1
 # The GraphAlg Language
 GraphAlg is a language for graph algorithms designed to be embedded into databases.
 
-{: .warning-title }
-> This website is under construction
->
-> We are working on an introduction to the language along with an interactive playground. In anticipation of that, you may be interested to read the [language specification](./spec).
+{:
+    data-ga-func="PageRank"
+    data-ga-arg-0="
+        11, 11, i1;
+        1, 2;
+        2, 1;
+        3, 0;
+        3, 1;
+        4, 1;
+        4, 3;
+        5, 1;
+        5, 4;
+        6, 1;
+        6, 4;
+        7, 1;
+        7, 4;
+        8, 1;
+        8, 4;
+        9, 4;
+        10, 4;"
+    data-ga-result-render="vertex-property"
+}
+```graphalg
+func withDamping(degree:int, damping:real) -> real {
+    return cast<real>(degree) / damping;
+}
+
+func PageRank(graph: Matrix<s, s, bool>) -> Vector<s, real> {
+    damping = real(0.85);
+    iterations = int(10);
+    n = graph.nrows;
+    teleport = real(0.15) / cast<real>(n);
+
+    d_out = reduceRows(cast<int>(graph));
+    d = apply(withDamping, d_out, damping);
+
+    pr = Vector<real>(n);
+    pr[:] = real(1.0) / cast<real>(n);
+
+    for i in int(0):iterations {
+        w = pr (./) d;
+        pr[:] = teleport;
+        pr += cast<real>(graph).T * w;
+    }
+
+    return pr;
+}
+```
+
+Are you new to GraphAlg?
+Write your first GraphAlg program and learn more about the language using the interactive [tutorial](./tutorial).
+
+You can experiment with GraphAlg in our [Playground](./playground), or use a [system with GraphAlg support](./integration/available).
+
+For a detailed overview of the GraphAlg language, see the [language specification](./spec).
+
+<script src="/playground/editor.bundle.js"></script>

integration/available.md

@@ -0,0 +1,21 @@
+---
+title: Available Integrations
+layout: page
+parent: Integrating
+nav_order: 1
+---
+
+# Available GraphAlg Integrations
+The following systems allow running GraphAlg programs.
+
+## AvantGraph
+[AvantGraph](https://avantgraph.io/) is a Graph Data Management System developed by the [TU Eindhoven Database group](https://www.tue.nl/en/research/research-groups/data-science/data-and-artificial-intelligence/database-group) that also develops GraphAlg.
+GraphAlg algorithms can be embedded in Cypher queries.
+Queries and algorithms are optimized and executed together in a unified query pipeline, allowing for optimizations that cross the boundary between query and algorithm.
+
+## GraphAlg Playground
+The [GraphAlg Playground](../playground) is an online platfrom for experimenting with GraphAlg.
+It provides:
+- An interactive editor with syntax highlighting and integrated error diagnostics
+- A fully-featured GraphAlg compiler, running locally in the browser
+- a WebAssembly backend to run GraphAlg programs in the browser

integration/index.md

@@ -0,0 +1,11 @@
+---
+title: Integrating
+layout: page
+nav_order: 5
+---
+
+# Integrating GraphAlg
+GraphAlg is designed to be integrated into existing systems, particularly Database Management Systems.
+If you are a (prospective) GraphAlg user looking for a way to run GraphAlg programs, see the [available GraphAlg integrations](./available).
+
+Are you a system developer and you want an easy way to let users run custom algorithms in your system, see our [guide to integrating GraphAlg in a new system](./new_integration).

integration/new_integration.md

@@ -0,0 +1,39 @@
+---
+title: Developing a New Integration
+layout: page
+parent: Integrating
+nav_order: 2
+---
+
+# Integrating GraphAlg into Existing Systems
+GraphAlg is specifically designed to be integrated into existing systems.
+The GraphAlg [compiler](https://github.com/wildarch/graphalg/tree/main/compiler) source code is freely available under a permissive license.
+The compiler can be integrated into other systems as a C++ library.
+Below we describe the three main integration points you can use depending on the properties of the target system.
+
+## Integrating The Reference Backend
+To minimize the required porting effort you can use the full compiler including the reference backend.
+An example of this approach is the [GraphAlg Playground](https://github.com/wildarch/graphalg/tree/main/playground) (see the [C++ component](https://github.com/wildarch/graphalg/tree/main/playground/cpp) in particular).
+An important caveat is that the reference is only designed to handle very small example-sized graphs.
+It will be slow and use a lot of memory if you try to use it with a larger graph (>100 nodes or edges).
+
+## Integrating From Relational Algebra
+If your system uses a relational algebra representation internally, or something akin to it, you can leverage the [conversion to relational algebra](../spec/core/relalg).
+If your system supports common arithmetic operations and aggregator functions, you only need to implement suitable a loop operator.
+All other GraphAlg operations can be converted into standard relational algebra operations.
+
+{: .note-title }
+> Example integration
+>
+> This approach is used by [AvantGraph](https://avantgraph.io/), but source code for this integration is not publicly available (yet).
+> When this code becomes freely available, or if another integration using the same approach becomes available, we will link to that here.
+
+## Integrating From GraphAlg Core
+The [Core language](../spec/core) has only a small number of high-level [operations](../spec/core/operations) that need to be implemented.
+This may be a more suitable integration point if your system does not target relational algebra.
+To do this you should use the provided [parser]() and run the [pipeline](https://github.com/wildarch/graphalg/blob/main/compiler/src/graphalg/GraphAlgToCorePipeline.cpp) to lower to GraphAlg Core.
+
+{: .note-title }
+> Example integration
+>
+> We do not currently have an example integration for this approach, although a GraphBLAS backend is planned that would use this strategy.

playground/binding.mjs

@@ -24,7 +24,7 @@ export function loadPlaygroundWasm() {
     let bindings = new PlaygroundWasmBindings();
     playgroundWasmFactory({
         locateFile: function (path, prefix) {
-            return playgroundWasm;
+            return prefix + playgroundWasm;
         },
     }).then((instance) => {
         bindings.ga_new = instance.cwrap('ga_new', 'number', []);