Введение¶

Установка¶

Рекомендуемый способ использования библиотеки - копирование содержимого папки organ репозитория в свой проект. Убедиесь, что используемое окружение соответствует требованиям бибилиотеки. Для этого необходимо выполнить следующую команду:

$ pip install -r requirements.txt

Корневой каталог репозитория OrGAN содержит набор скриптов (в первую очередь, main.py). Если нужно только обучить генератор организационных структур с использованием своих образцов, то, скорее всего, программирование не потребуется и имеющихся скриптов будет достаточно. В этом случае просто склонируйте репозиторий, создайте виртуальное окружение и установите зависимости:

$ git clone https://gitlab.actcognitive.org/itmo-sai-code/organ.git organ
$ cd organ
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt

Затем, можно указать обучаоющий набор конфигураций и запустить скрипт обучения.

Быстрый старт¶

Есть два способа использования библиотеки OrGAN. При отсутствии каких-либо специфических требований для генерируемых организационных структур имеющихся скриптов (например, main.py) будет достаточно. С использованием параметров командной строки можно контролировать основные требования к генерируемым конфигурациям, архитектурам используемых нейронных сетей и процессу обучения. Быстрый старт рассчитан на подобный сценарий.

Предполагаем, что библиотека OrGAN успешно проинсталлирована согласно инструкциями раздела Установка.

Основная идея библиотеки OrGAN заключается в том, что он можен генерировать структуры схожие c используемыми при обучении (предположительно, созданными экспертами). Это значит, что для использования библиотеки необходимо подготовить обучающий набор организационных структур. Для упрощения демонстрации в репозиторий включены два набора (сценарий конфигурирования логистического отдела и сценарий конфигурирования административного отдела). Однако, поскольку как правило обучающие наборы в области организационных структур весьма малы, перед обучением модели необходимо дополнить обучающее множество:

$ python augment_dataset.py demo_logistics 1000 demo_data/logistics data

Данный скрипт создаст 1000 образцов организационных структур в папке data, формат обучающего множества описан в Data.

Затем, можно начинать обучения посредством запуска main.py:

$ python main.py --rules demo_logistics

Скрипт будет время от времения выводить информацию о качестве генерируемых образцов.

Сценарии использования¶

Только скрипт¶

Данный сценарий не требует программирования (по крайней мере, обучение OrGAN), однако, он ограничен только использованием лишь предварительно определенных ограничений на организационные структуры и не позволяет использовать свои ограничения.

Сценарий имеет следующий вид:

Подготовьте набор (обучающее множество) реальных примеров организационных структур согласно спецификации формата данных (см. Data).
Если количество образцов меньше нескольких тысяч, дополните обучающее множество с использованием скрипта augment_dataset.py.
Обучите OrGAN. Если обучающее множество помещено в папку data, обучение может быть выполнено посредством выполнения следующего скрипта:
$ python main.py --rules=generic

Необходимо заметить, что обучающий скрипт main.py запускается с аргументом „–rules=generic“. Это значит, что есть только общие требования к организационным структурам (например, связь может существовать только между существующими элементами). Также можно использовать команды main.py для управления процессами обучения и вывода (см. python main.py --help для списка команд).

Поскольку общие требования в большинстве случаев являются слишком общими, сгенерированные только с их использованием конфигурации могут далеко не всегда быть действительно полезными. В таком случае следует определить свои ограничения (и метрики) дял своих организационных структур с использованием сценария Program-Level, однако он требует программирования.

Уровень программирования¶

Все специфические требования к организационным структурам связаны понятием „Модель организационной структуры“ („Organization structure model“). Данная модель представлена классом Python, определяющим следующие методы:

validness(org) -> bool, определяющей допустимость организационной
metrics(org) -> dict, возвращающей словарь метрик оценки качества организационной структуры и
необязательный soft_constraints(nodes, edges, features, condition) -> tensor, который может реализовывать дифференцируемые ограничения.

После определения такого класса можно передать имя класса в качестве аргумента скрипту обучения:

$ python main.py --rules=module.CustomOrgStructureModelClass

Проиллюстрируем процесс создания упрощенной пользовательской модели организационной структуры. Создадим модуль Python hornsnhooves.py в корневой папке репозитория и определим в нем класс HNHStructureModel. Как было указано ранее, данный класс должен реализовывать несколько методов.

Начнем с самого важного - validness(org). Данный метод может выполнять любые проверки организационной структуры (например, можно вызывать внешние системы, выполнять моделирование или люьбые другие действия, которые могут быть необходимы для проверки того, что организационная структура org является допустимой. Однако, необходимо заметить, что данный метод вызывается для каждой конфигурации (как существующей, так и сгенерированной), так что его необходимо сделать максимально эффективным.

Параметр данного метода org является (в данной версии библиотеки) кортежем - парой двух матриц - одна описывает вершины конфигурации соответствует типу вершины на каждой позиции, 0 - если позиция пуста) а вторая - связи между вершинами (тип свзязи для каждой пары позиций вершин, 0 - если связи нет).

Примечание

Данное поведение может быть изменено в последующих релизах.

Например, можно потребовать, чтобы допустимые конфигурации содержали не менее 3-х элементов и содержали либо вершину типа 1 или типа 2 (или обе). Тогда описание допустимости будет выглядеть слеюующим образом:

def validness(self, org):
    nodes, edges = org
    return (nodes != 0).sum() >= 3 and \
        (nodes[1] != 0 or nodes[2] != 0)

Then, we must define a set of metrics for organization structures. These metrics will be printed during the training process. Typically, such metrics characterize the validness and quality of the structure, so one of the metrics for HNHStructureModel might directly correspond to validness and another just show the organization size:

def metrics(self, org):
    return {'validness': self.validness(org),
            'size': (org[0] != 0).sum()}

Наконец, можно добавить несколько дифференцируемых ограничений на организационные структуры. Генератор будет штрафоваться за нарушение этих ограничений, так что они скорее всего рано или поздно будут удовлетворены, хотя это и не гарантируется. Поскольку данные ограничения должны быть дифференцируемыми, интерфейс функции soft_constraints() несколько отличен. Она должна принимать на вход представление организационной структуры во внутреннем формате (пара тензоров pytorch), а также может использовать только дифференцируемые функции (обычно, представленные в библиотеке pytorch). OrGAN определяет набор функций для помощи при реализации функции soft_constraints() - см. описание модуля organ.structure.constraints для получения полного списка. В качестве примера можно потребовать, чтобы связи были симметричными и соединяли только существующие вершины:

def soft_constraints(self, nodes, edges, *ignored):
    return 0.1 * organ.structure.constraints.edge_consistent(nodes, edges) + \
           0.1 * organ.structure.constraints.edge_symmetric(edges)

Примечание

Обычно требуется, чтобы набор допустимых структур был подмножеством структур, удовлетворяющих нечетким ограничениям. В данном примере это требование не представлено, но на практике вполне вероятно.

Обычно, данная функция должна возвращать неотрицательно значение штрафа для структур описанныз тензорами nodes (вершины) и edges (связи). Штраф должен быть нулевым, если требование выполняется.

TiNGLe¶

Для наиболее требовательных пользователей и сценариев использования библиотеки OrGAN включает библиотеку Tiny Neural Graph Library (TiNGLe), предоставлюящую набор абстракций и средств для программирования (сверточных) графовых нейронных сетей и их использования в качестве собственных аппроксиматоров и дискриминаторов в рамках OrGAN.

The TiNGLe supports graphs having several types of nodes and edges, and uses graph representation most convenient for the generation process, representing graph connectivity by an adjacency matrix (and the presense of an edge is not binary, it can be on the continuum from zero to one, which is important for gradient flow). Conceptually, the library follows message passing framework for graph neural networks and is based on the ideas, described in https://distill.pub/2021/gnn-intro/. More precidely, a graph is represented using the following components:

глобальное представление (один вектор, описывающий весь граф);
представление вершин. В TiNGLe предполагается, что вершина может быть определенного типа, а также иметь набор свойств, так что:
- типы вершин (размер батча x число вершин x число типов вершин);
- свойства вершин (размер батча x число вершин x число свойств (N_F))
представление связей. Связи могут быть нескольких типов, но между одной парой вершин нельзя определить более одной связи:
- типы связей (размер батча x число типов связей x число вершин x число вершин). В данном представлении 0 означает отсутствие связи соответствующего типа, а 1 - наличие таковой. Однако, другие значения также возможны. Они интерпретируются как «сила» связи и используются во время распространения через (или из) соответствующей связи.
- представление связи (одно для всех типов связей (размер батча x число вершин x число вершин x V_F).

Библиотека определяет два вида инструментов:

Функции для реализации шагов сбора и агрегирования для различных видов передачи сообщений.
Классы и инструменты «оркестровки» для создания архитектуры полной графовой нейронной сети.

В результат можно создать нейронную сеть следующим образом:

gn = torch.nn.ModuleList([
    VV(merge='replace', apply_to_types=True),
    GNNBlock(nodes_module=torch.nn.Linear(2, 4)),
    VV(merge='replace'),
    GNNBlock(nodes_module=torch.nn.Linear(4, 2)),
])

Более подробная информация о библиотеке TiNGLe и ее API представлены в ее документации.

Данные¶

В натоящей версии библиотека OrGAN использует бинарные наборы данных. Однако в дальнейшем планируется предоставить средства перевода данных из популярных форматов описания графов в данное представление. Помощь в создании таких средств приветствуется.

Каждая организационная структура описываеься графом. Его вершины соответствуют элемантам организационной структуры, а ребра - связям между ними.

Набор данных состоит из нескольких файлов с фиксированными именами, находящимися в одной папке:

data_nodes.npy - целочисленная матрица NumPy (n, f) с описанием вершин,
data_edges.npy - целочисленная NumPy матрица (n, f, f) с описанием связей,
data_staff.npy - матрица Numpy (n, f) типа float, описывающая параметры вершин,
data_cond.npy - матрица Numpy (n, f) типа float, описывающая входные значения (condition values) - организационный контекст, используемый для генерации конфигураций,
data_meta.pkl - фойл pickle, содержащий словарь с описанием набора данных.

Все файлы .npy имеют стандартный формат NumPy binary. В описаннии выше, n является числом элементов наьбора данных, f - числом типов вершин (и в то же время максимальным числом вершин, так как предполагается, что организационная структура содержит не более одной вершины каждого типа).

i-я позиция описания вершин может содержать либо contain*i*, либо 0. Ноль в позиции i означает, что вершины типа i в графе нет.

Аналогично, каждое значение многомерного массива в data_edges.npy кодирует связь между двумя вершинами, где 0 означает отсутствие связи. Необходимо отметить, что согласно данному формату не может быть более одной связи (например, связей разного типа) между парой вершин.

В файле параметров каждой вершине соответствует одно значение (например, соответствующее масштабу данной вершины).

Словарь описания набора данных, содержащий следующие ключи:

для X в („train“, „validation, or „test“):
- X_idx - список индекстов подмножеств,
- X_count - число образцов в X_idx,
- X_counter - должен быть нулевым,
node_num_types - число типов вершин (включая тип 0), должно быть (f - 1),
edge_num_types - число типов связей (включая тип 0),
vertexes - должен быть равен node_num_types,
features_per_node - число свойств для вершин,
condition_dim - число свойств, определающих организационный контекст (параметры целевой конфигурации организационной структуры).

OrGAN

Навигация

Related Topics