引导程序

本文档是为 TuGraph 的用户设计的引导程序，用户在阅读详细的文档之前，应该首先阅读该文档，对 TuGraph 的图计算运行流程有一个大致的了解，之后再阅读详细文档会更加方便。引导程序是基于 Tugraph 的一个简单的bfs(宽度优先搜索)程序实例，我们将重点介绍其使用方式。

目录

• 1. TuGraph-图分析引擎介绍
• 2. Procedure 编译与运行
• 3. Embed 编译及运行
• 4. Standalone 编译与运行

1. TuGraph-图分析引擎介绍

TuGraph的图分析引擎，面向的场景主要是全图/全量数据分析类的任务。借助TuGraph的 C++ / Python 图分析引擎 API ，用户可以对不同数据来源的图数据快速导出一个待处理的复杂子图，然后在该子图上运行诸如PageRank、LPA、WCC等迭代式图算法，最后根据运行结果做出相应的对策。

在TuGraph中，导出和计算过程均可以通过在内存中并行处理的方式进行加速，从而达到近乎实时的处理分析，和传统方法相比，即避免了数据导出落盘的开销，又能使用紧凑的图数据结构获得计算的理想性能。

TuGraph图计算系统社区版内置6个算法，商业版内置了25种算法，用户几乎不需要自己实现具体的图计算过程。其详细介绍可参考algorithms.md。

根据数据来源及实现不同，可分为Procedure、Embed和Standalone三种运行方式，均继承于OlapBase API，OlapBase API接口文档可参考olapbase-api.md。

其中Procedure和Embed的数据来源是图数据库中预加载的db数据，可以分别编译生成TuGraph-Web加载使用的.so文件和后台终端使用的embed文件，输入的图数据均通过db的加载形式，其接口文档可参考olapondb-api.md。
Standalone用于编译生成standalone文件，区别于前者，该文件的输入图数据通过txt、二进制、ODPS文件的形式加载，其接口文档可参考olapondisk-api.md。

2. Procedure 编译与运行

该种方式主要用于TuGraph-web界面进行可视化加载及运行。使用方法如下：

C++:

在TuGraph/plugins目录下执行 bash make_so.sh bfs 即可在TuGraph/plugins目录下得到bfs.so文件，将该文件以插件形式上传至TuGraph-web，输入参数后即可执行。

Python:

在TuGraph-web的前端将python文件以插件形式上传，输入参数后即可执行。

示例：
在TuGraph/plugins编译.so算法文件
bash make_so.sh bfs

将bfs.so（或TuGraph/plugins/cython/bfs.py）文件以插件形式加载至TuGraph-web后，输入如下json参数：

{
    "root_id":"0",
    "label":"node",
    "field":"id"
}

即可得到返回结果如下。

result:"{“core_cost”:0.013641119003295898,
“found_vertices”:3829,
“num_edges”:88234,
“num_vertices”:4039,
“output_cost”:8.821487426757813e-06,
“prepare_cost”:0.03479194641113281,
“total_cost”:0.04844188690185547}"

输出内容解释如下：

• num_edges: 表示该图数据的边数量
• num_vertices: 表示该图数据顶点的数量
• prepare_cost: 表示预处理阶段所需要的时间。预处理阶段的工作：加载参数、图数据加载、索引初始化等。
• core_cost: 表示算法运行所需要的时间。
• found_vertices: 表示查找到顶点的个数。
• output_cost: 表示算法结果写回db所需要的时间。
• total_cost: 表示执行该算法整体运行时间。

make_so.sh文件介绍：该文件用于将TuGraph-OLAP所涉及到的图算法文件编译成一个可供TuGraph-web使用的.so文件。

3. Embed 编译及运行

该种方式主要用于TuGraph在后台程序中对预加载的db图数据进行算法分析。其使用方法如下：
在TuGraph/plugins目录下对embed_main.cpp文件完善，补充数据名称、输入参数、数据路径等信息，示例如下：

C++:

#include <iostream>
#include "lgraph/lgraph.h"
#include "lgraph/olap_base.h"
using namespace std;

extern "C" bool Process(lgraph_api::GraphDB &db, const std::string &request, std::string &response);

int main(int argc, char **argv) {
    // db_path表示预加载图数据存放的路径
    std::string db_path = "../fb_db/";
    if (argc > 1)
        db_path = argv[1];
    lgraph_api::Galaxy g(db_path);
    g.SetCurrentUser("admin", "73@TuGraph");
    // 指定图数据的名称
    lgraph_api::GraphDB db = g.OpenGraph("fb_db");
    std::string resp;
    // 以json形式输入算法参数
    bool r = Process(db, "{\"root_id\":\"0\", \"label\":\"node\",\"field\":\"id\"}", resp);
    cout << r << endl;
    cout << resp << endl;
    return 0;
}

保存后在TuGraph/plugins目录下执行 bash make_so.sh bfs 即可在TuGraph/plugins/cpp目录下的到bfs_procedure文件，
bash make_embed.sh bfs

在TuGraph/plugins文件夹下执行
./cpp/bfs_procedure
即可得到返回结果。

Input: {“root_id”:“0”, “label”:“node”,“field”:“id”}
found_vertices = 3829
{“core_cost”:0.025603055953979492,
“found_vertices”:3829,
“num_edges”:88234,
“num_vertices”:4039,
“output_cost”:9.059906005859375e-06,
“prepare_cost”:0.056738853454589844,
“total_cost”:0.0823509693145752}

其中Input表示输入的参数，其余参数解释同上。

Python：

在TuGraph/plugins文件夹下执行
bash make_cython_so.sh bfs
或在TuGraph/plugins/cython文件夹下执行
python3 setup.py build_ext -i
得到bfs.so后，在Python中import bfs可使用，如TuGraph/plugins/embed_main.py所示

# TuGraph/plugins/embed_main.py
from lgraph_db_python import *

import bfs as python_plugin

if __name__ == "__main__":
    galaxy = PyGalaxy("../build/output/lgraph_db")
    galaxy.SetCurrentUser("admin", "73@TuGraph")
    db = galaxy.OpenGraph("default", False)
    res = python_plugin.Process(db, "{\"root_id\":\"0\", \"label\":\"node\",\"field\":\"id\"}".encode('utf-8'))
    print(res)
    del db
    del galaxy

# shell
python3 embed_main.py

输出结果与C++相同。

4. Standalone 编译与运行

该文件主要用于在终端处直接加载图数据，并运行打印输出结果。使用方法如下：
在TuGraph/build目录下执行 make bfs_standalone (需要在g++默认include路径中包含boost/sort/sort.hpp)即可得到bfs_standalone文件,该文件生成于TuGraph/build/output/algo文件夹下。
运行：在TuGraph/build目录下执行./output/algo/bfs_standalone -–type [type] –-input_dir [input_dir] --id_mapping [id_mapping] -–vertices [vertices] --root [root] –-output_dir [output_dir]
即可运行。

• [type]：表示输入图文件的类型来源，包含text文本文件、BINARY_FILE二进制文件和ODPS源。
• [input_dir]：表示输入图文件的文件夹路径，文件夹下可包含一个或多个输入文件。TuGraph在读取输入文件时会读取[input_dir]下的所有文件，要求[input_dir]下只能包含输入文件，不能包含其它文件。参数不可省略。
• [id_mapping]：当读入边表时，是否对输入数据做id映射，使达到符合算法运行的形式。1为需要做id映射，0为不需要做。该过程会消耗一定时间。参数可省略，默认值为0。
• [vertices]：表示图的顶点个数，为0时表示用户希望系统自动识别顶点数量；为非零值时表示用户希望自定义顶点个数，要求用户自定义顶点个数需大于最大的顶点ID。参数可省略，默认值为0。
• [root]：表示进行bfs的起始顶点id。参数不可省略。
• [output_dir]：表示输出数据保存的文件夹路径，将输出内容保存至该文件中，参数不可省略。

示例：

C++:

在TuGraph/build编译standalone算法程序

make bfs_standalone

在TuGraph/build/output目录下运行text源文件

    ./output/algo/bfs_standalone --type text --input_dir ../test/integration/data/algo/fb_unweighted --root 0

得到运行结果：

prepare_cost = 0.10(s)
core_cost = 0.02(s)
found_vertices = 3829
output_cost = 0.00(s)
total_cost = 0.11(s)
DONE.

结果参数解释同上。

对于新的算法，运行时不了解该算法的所需参数时，可通过./output/algo/bfs_standalone -h进行查阅对应参数。

Python:

Python语言的bfs拓展编译过程与embed模式无区别，在运行时通过Standalone接口调用，示例如下：

# TuGraph/plugins/standalone_main.py
import bfs as python_plugin

if __name__ == "__main__":
    python_plugin.Standalone(input_dir=
                             "../test/integration/data/algo/fb_unweighted",
                             root=0)

# shell
python3 standalone_main.py

至此，通过TuGraph对上图进行bfs运算的过程已经完成。