Финальыне правки: инструкция по установке, ссылки на примеры кода.

Author: gsvgit

README.md

@@ -1,7 +1,27 @@
 # PageRankBenchmark
-Stand for PageRank algorithm benchmark
+Демонстрация использования алгоритма "PageRank" на графе со сложными атрибутами вершин и ребёр.
+# Руководство к запуску
+## Установка зависимостей
+```bash
+sudo apt install ccache
+sudo apt install ninja-build
+```
+
+## Сборка проекта
+```bash
+git clone https://github.com/SparseLinearAlgebra/PageRankBenchmark.git
+cd PageRankBenchmark
+git submodule init
+git submodule update —recursive
+make build
+```
 
+## Запуск примера
+```
+./build/main
+```
 # Минимальный пример
+Полный код разбираемого примера можно увидеть в [файле](./src/main.c).
 
 Цель примера --- показать, как в рамках GraphBLAS можно работать со сложными атрибутами вершин и рёбер графа.
 
@@ -17,7 +37,7 @@ Stand for PageRank algorithm benchmark
 
 Пусть будут следующие типы карт: МИР, VISA, MASTERCARD.
 
-При этом рёбра типа "Перевод" в качестве атрибутов сожержат общую сумму и "количество транзакций".
+При этом рёбра типа "Перевод" в качестве атрибутов содержат общую сумму и "количество транзакций".
 Рёбра типа "Владеет" не имеют атрибутов.
 
 Для примера возьмём следующий граф.
@@ -26,7 +46,6 @@ Stand for PageRank algorithm benchmark
 
 Хотим выбрать по некоторому критерию пользователей и их карты, а затем для анализа переводов хотим посчитать PageRank на подграфе, заданном переводами между отобранными картами.
 Выбрать хотим все карты системы "МИР", которыми владеют люди старше заданного возраста. Покажем, как это можно сделать, используя матрично-векторные операции, в частности [GraphBLAS](https://github.com/GraphBLAS).
-Полный код разбираемого примера мрожно увидеть в файле [!!!!](!!!!).
 
 GraphBLAS позволяет в качестве атрибутов использовать пользовательские типы (фиксированных размеров), потому объявим необходимый нам набор типов.
 ```c
@@ -68,9 +87,9 @@ typedef struct
 ```
 
 Граф представлен как набор матриц и векторов: по одной матрице на каждый тип рёбер и по одному вектору на каждый тип вершин.
-Матрицы и вектора в большинстве случаев будут разреженными и мы будем использовать символ '$.$' для обозначения отсутсвующего элемента.
+Матрицы и вектора в большинстве случаев будут разреженными и мы будем использовать символ '$.$' для обозначения отсутствующего элемента.
 Считаем при этом, что все вершины, вне зависимости от типа, занумерованы с 0 подряд (id вершин на рисунке).
-Таким образом, нам понядобятся две матрицы:
+Таким образом, нам понадобятся две матрицы:
 
 $$
 \texttt{TX-Edges}=
@@ -124,7 +143,7 @@ $$
 Скажем, нас будут интересовать пользователи старше 30 лет. 
 Для этого в GraphBLAS есть функция ```Select```, которая фильтрует коллекции, используя функцию-предикат принимаемую в качестве аргумента.
 
-Так как нам предстоит работать с пользовательскими типами, то предётся написать собственный предикат.
+Так как нам предстоит работать с пользовательскими типами, то придётся написать собственный предикат.
 
 ```c
 void check_user_age(bool *z, const User *x, GrB_Index _i, GrB_Index _j, const uint8_t *y)
@@ -136,7 +155,7 @@ void check_user_age(bool *z, const User *x, GrB_Index _i, GrB_Index _j, const ui
 Два дополнительных параметра типа ```GrB_Index``` позволяют, при необходимости, использовать в фильтре координаты рассматриваемого элемента.
 
 Для того, чтобы выбрать карты, принадлежащие выбранным пользователям, нам необходимо получить "концы" рёбер типа Owns, исходящие из выбранных пользователей. 
-Чтобы сделать это, выполним один шаг обхода в ширину, который в терминах линейной алгебры выражается через умноженеи вектора текущих вершин на матрицу смежности.
+Чтобы сделать это, выполним один шаг обхода в ширину, который в терминах линейной алгебры выражается через умножение вектора текущих вершин на матрицу смежности.
 Текущие вершины в нашем случае --- выбранные пользователи.
 То есть нам необходимо вычислить следующее произведение.
 
@@ -178,7 +197,7 @@ $$
 
 Мы получили не совсем карты, но вектор, который указывает, какие карты нас интересуют. 
 Вспомним, что мы хотим взять только карты "МИР". 
-Для этого снова будем использовать Select, а полученный вектор $\texttt{Filtered-Cards}$ будем использовать как маску, чтобы дополнительно тфильтровать результат.
+Для этого снова будем использовать Select, а полученный вектор $\texttt{Filtered-Cards}$ будем использовать как маску, чтобы дополнительно отфильтровать результат.
 
 
 Чтобы получить переводы только между отобранными картами, воспользуемся тем фактом, что выбор исходящих рёбер, инцидентных заданному множеству вершин --- это умножение матрицы смежности на диагональную матрицу, в которой ненулевые элементы на местах интересующих нас вершин, слева.
@@ -261,14 +280,14 @@ $$
 
 В качестве конкретных реализаций для $+$ можно взять логическое "И", а в качестве $*$ операцию $\textit{second}$ (вернуть второй элемент из пары).
 
-Для $\otimes_2$ ситуация аналогияная,
-Необходимо только проследить за тем, в какие моменты надо брать первый элемент из пары, а в какие вотрой, чтобы в результате получилась матрица с элементами типа $\texttt{EdgeTX}$
+Для $\otimes_2$ ситуация аналогичная,
+Необходимо только проследить за тем, в какие моменты надо брать первый элемент из пары, а в какие второй, чтобы в результате получилась матрица с элементами типа $\texttt{EdgeTX}$
 
 Подграф готов. 
-Теперь неорбходимо сконструировать матрицу, по которой непосредственно будем считать PageRank. 
+Теперь необходимо сконструировать матрицу, по которой непосредственно будем считать PageRank. 
 Сейчас метки рёбер --- структуры, хранящие информацию о переводах, а мы хотим получить одно число.
 При этом важно, чтобы сумма весов всех исходящих рёбер была равна единице.
-Для примера действовать будем следующим образом: возьмём "средний размер транзакции" (вычислим как $\frac{\textit{Sum}}{\textit{Count}}$), поделим на 1000 (на всякий случай, чтобы избежать слишком больших знчений) и затем построчно примерним Softmax.
+Для примера действовать будем следующим образом: возьмём "средний размер транзакции" (вычислим как $\frac{\textit{Sum}}{\textit{Count}}$), поделим на 1000 (на всякий случай, чтобы избежать слишком больших значений) и затем построчно применим Softmax.
 Иными словами, будем использовать идею функции Softmax, которая задаётся следующим образом.
 
 $$
@@ -283,10 +302,10 @@ $$
 $$
 
 Вычисления построим следующим образом. Сперва выполним редукцию по колонкам с использованием функции $f$: таким образом получим знаменатель дроби.
-После этого сконструируем две квадратные матрицы: в одной нулевой столбец --- это получанный вектор, а остальные нули, в другой --- нулевая строка --- единицы, остальное --- нули. 
+После этого сконструируем две квадратные матрицы: в одной нулевой столбец --- это полученный вектор, а остальные нули, в другой --- нулевая строка --- единицы, остальное --- нули. 
 Перемножим эти две матрицы, использую исходную матрицу $\texttt{Filtered-Transactions}$ в качестве маски. 
 Таким образом получим матрицу, в которой знаменатель стоит на необходимых местах. 
-Также нам нужна будет матрица, содержащая числители дробей (получается поэлементным примерением соответствующей функции к  $\texttt{Filtered-Transactions}$)
+Также нам нужна будет матрица, содержащая числители дробей (получается поэлементным применением соответствующей функции к  $\texttt{Filtered-Transactions}$)
 После чего поэлементно поделим эти две матрицы.
 
-Далее на полученной матрице запускаем [классический алгоритм PageRank](!!!) (правда, без "телепортации" в несвязанные вершины), который в терминах линейной алгебры реалищуется по определению: итеративное умножение исходной матрицы на вектор.
+Далее на полученной матрице запускаем [классический алгоритм PageRank](./src/main.c#L190) (правда, без "телепортации" в несвязанные вершины), который в терминах линейной алгебры реализуется по определению: итеративное умножение исходной матрицы на вектор.