OrGAN Modules

solver

Main module for training and testing of the OrGAN.

class organ.solver.Solver(config)

Class for training and testing the OrGAN model.

build_model()

Create neural models (generator, discriminator, and approximator).

build_tensorboard()

Tensorboard logging initialization.

generate(batch_size: int = 1, ctx=None)

Generate a batch of samples.

Параметры:

• batch_size (int) – Number of samples to generate.

• ctx – Context for the samples to be generated. May be optional.

generate_valid(n: int, ctx=None, max_generate: int = 1000)

Generate valid organizations.

Параметры:

• n (int) – The number of valid organizations to generate.

• ctx (np.ndarray) – Condition (context) features, (n_features, ).

• max_generate (int) – Maximal number of instances to generate. If the underlying model accuracy is low, it may take too much time to generate the required number of valid organizations. This parameter helps to control the process and stop generation even if the required count isn’t achieved.

Результат:

The list of organizations, containing not more than n instances of Organization class.

Тип результата:

list

gradient_penalty(y, x)

Gradient penalty.

(L2_norm(dy/dx) - 1)**2

label2onehot(labels, dim)

Transform labels into one-hot encoded vectors.

Given tensor with integer values labels is extended by one dimensions, in which these labels are converted into one-hot codes.

Параметры:

• labels (torch.tensor (int64)) – Tensor with non-negative integer labels.

• dim (int) – Number of categories in labels tensor. This number becomes the size of the new dimension of the output tensor. The specified number must be greater than the max value of labels.

Результат:

Real-valued tensor, consisting of zeros and ones.

Тип результата:

torch.tensor (float)

load_pretrained()

Load pretrained models.

postprocess(inputs, method, temperature=1.0)

Postprocessing by one of the differentiable discretization methods.

The method is used to transform matrices, describing edges of a graph (without activations) to a representation, where an edge can have only one type (or be marked as absent). In other words, the representation is transformed into one, consisting of ones and zeroes (almost).

Параметры:

• inputs (torch.tensor, tuple [torch.tensor], list [torch.tensor]) – Input tensors to transform.

• method (str) – Transformation type: soft_gumbel, hard_gumbel, softmax.

• temperature (float) – Transformation parameter.

Результат:

The list of output tensors, with transformation applied to the last dimension. If inputs was one tensor, the result is still a list, though one-element.

Тип результата:

list [torch.tensor]

postprocess_nodes(nodes_logits)

Transforms a list of node logits into richer form.

Most code assumes, that the set of graph nodes is described by tensor vertexes x node_types. However, in the case of organization structures it turns out that a node and a node type are mostly synonyms (there can be at most one node of a given type). Therefore, generator returns only logits of presence of certain types of nodes, and this method transforms these logits into batch of vertex x node_types tensors, placing the values on diagonal and complementing the probability of node absence.

Параметры:

nodes_logits (pytorch.tensor) – Batch of logits for node presence, batch x vertexes.

Результат:

Batch of specifications batch x vertexes x nodes.

Тип результата:

torch.tensor

print_network(model, name)

Print model description.

Параметры:

• model (torch.Module) – Model to print.

• name (str) – Model name (only for readability purposes).

reset_grad()

Reset gradients of all optimizers.

restore_model(resume_iters)

Load models from a savepoint.

Load the state of all models (generator, discriminator, and approximator) from a savepoint, located at model_save_dir.

Параметры:

resume_iters (int) – Iteration number, to specify a model savepoint.

reward(orgs)

Structural reward.

The method calculates a vector of structural reward values for the given batch of organization descriptions. The definition of structural reward can be project-specific (the list of metrics is defined in self.metric) and relies on various metrics defined in org_model passed to the constructor.

Параметры:

orgs (list) – A list of organization specifications.

Результат:

Batch of reward values.

Тип результата:

numpy.ndarray, shape (batch_size, 1)

sample_z(batch_size)

Form samples from the input distribution of the generator.

test()

Model testing.

train()

Training cycle.

update_lr(g_lr, d_lr)

Sets learning rate constants (for all the models).

Параметры:

• g_lr (float) – Learning rate for the generator (and approximator).

• d_lr (float) – Learning rate for the discriminator.

organ.solver.compliance_loss(expected_nodes, generated_nodes)

Compliance loss.

Checks if generated nodes match the expected ones.

Параметры:

• expected_nodes (tuple) – A pair of node specification and the mask.

• generated_nodes (torch.tensor) – Generated nodes specification.

Тип результата:

Loss value.

models

Neural models OrGAN is built of.

This module defines several flavours of basic generator and discriminator neural networks.

You can as well define your own generator and discriminator architectures.

Both generator and discriminator must be PyTorch modules (derive from torch.nn.Module).

Generator’s forward() method has to accept two positional parameters:

• condition (torch.tensor of shape (batch, cond_dim) or None) with input condition (requirements to the sample to be generated). If a generator model doesn’t support conditional generation it may ignore this parameter;

• x (torch.tensor of shape (batch, z_dim)) with input noise.

and return a 3-tuple:

• edges specification (batch, nodes, nodes, edge_types);

• nodes specification (batch, nodes, node_types);

• optional node parameters (batch, nodes, node_features).

Discriminator’s forward() method has to accept following parameters:

• edges (torch.tensor of shape (batch, nodes, nodes, edge_types)) - adjacency matrices;

• nodes (torch.tensor of shape (batch, nodes, node_types)) - types of nodes;

• node_params (torch.tensor of shape (batch, nodes, node_features) or None) - parameters of each node. If the discriminator doesn’t support parameters it may ignore this parameter;

• condition (torch.tensor of shape (batch, condition_features) or None) - condition, under which the graph was generated. If the discriminator doesn’t support conditional generation it may ignore this parameter;

• activation - an activation function to apply to the results.

class organ.models.CPDiscriminator(conv_dim, fc_dim, cond_encoder_dim, n_node_types, n_edge_types, n_cond_features, n_node_features, dropout)

Conditional parametric discriminator for OrGAN.

Discriminator receives a graph (described by edges, nodes, node features and condition), applies a series of graph convolutions and fully connected layers to obtain a single number (characterizing the graph as a whole, e.g., its consistency or verisimilitude).

forward(adj, nodes, node_params, cond, activation=None)

Forward pass.

Параметры:

• adj (torch.tensor) – Adjacency matrices, batch x vertexes x vertexes x edges.

• nodes (torch.tensor) – Nodes specification, batch x vertexes x nodes.

• node_params (torch.tensor) – Node parameter values, batch x vertexes x node_features.

• cond (torch.tensor) – Condition, batch x cond_features.

• activation (Callable) – Activation function for the last layer.

class organ.models.CPGenerator(conv_dims, edge_conv_dims, param_dims, z_dim, cond_dim, nodes, edge_types, node_features, dropout)

Conditional parametric generator.

forward(cond, z)

Forward pass.

class organ.models.CompletionGenerator(conv_dims, edge_conv_dims, z_dim, node_types, edge_types, dropout)

Structure completion generator.

forward(nodes, edges, nodes_mask, edges_mask, z)

Forward pass.

Параметры:

• nodes (torch.tensor) – The specification of existing nodes, (batch, node_types, node_types)

• edges (torch.tensor) – The specification of existing edges, (batch, node_types, node_types, edge_types)

• nodes_mask (torch.tensor) – The mask defining the presence of which nodes should be conserved in the output, (batch, node_types)

• edges_mask (torch.tensor) – The mask defining the presence of which nodes should be conserved in the output, (batch, node_types, node_types)

• z (torch.tensor) – Noise vector.

class organ.models.Discriminator(conv_dim, m_dim, b_dim, dropout)

Discriminator for OrGAN.

Discriminator receives a graph (described by edges and nodes), applies a series of graph convolutions and fully connected layers to obtain a single number (characterizing graph as a whole, e.g., its consistency or verisimilitude).

Примечание

This discriminator does NOT support conditional generation and parametric organizations. For such full-fledged disciminator see CPDiscriminator.

forward(adj, nodes, ignored, ignored_, activation=None)

Forward pass.

Параметры:

• adj (torch.tensor) – Adjacency matrices, batch x vertexes x vertexes x edges.

• nodes (torch.tensor) – Nodes specification, batch x vertexes x nodes.

• ignored – Ignored.

• activation (Callable) – Activation function for the last layer.

class organ.models.EdgeAwareGenerator(conv_dims, edge_conv_dims, z_dim, vertexes, edges, dropout)

Generator that creates edges based on types of nodes.

Примечание

This generator does NOT support conditional generation and parametric organizations. For such full-fledged generator see CPGenerator.

forward(_, x)

Forward pass.

class organ.models.FCBlock(input_dim, hidden_dims, output_dim, activation, dropout=0.0)

A fully-connected block.

forward(input)

Defines the computation performed at every call.

Should be overridden by all subclasses.

Примечание

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class organ.models.SimpleGenerator(conv_dims, z_dim, vertexes, edges, dropout)

Generator network for OrGAN.

Generator is a non-linear neural transformation from an input vector (consisting of z_dim features) to a graph, describing an organization structure.

The generator is built of several fully connected layers, making a series of transformations, followed by «forking» the representation into nodes description and adjacency matrix:

        Input (batch x z_dim)
                   |
Fully connected (FC) layers (tanh, dropout)
          |                 |
    FC layer for       FC layer for
        edges             nodes
   (no activation)    (no activation)

forward(_, x)

Forward pass.

Примечание

Output values are not bounded, activation is not applied.

Параметры:

x (torch.tensor) – Input tensor of batch x z_dim.

Результат:

A tuple, consisting of edges specification (batch x vertexes x vertexes x edges) and nodes specification (batch x vertexes). It is assumed, that a vertex of certain type can be placed only in certain position (overall, vertex type is equivalent to its position), therefore, it is enough to form only presence of a node in certain position, its type is known automatically.

Тип результата:

tuple

layers

Definition of neural network layers, used in the generative adversarial network OrGAN.

The module includes the definition of graph convolution layer, graph aggregation (to aggregate several node representations into one vector), and edge convolution.

Предупреждение

This module is deprecated and in future releases it will be replaced by the Tiny Neural Graph Library (organ.tingle).

class organ.layers.EdgeConvolution(node_dim, out_dim, edge_types)

Edge convolution layer.

forward(nodes, adj)

Forward pass.

Параметры:

• nodes (torch.tensor) – Batch of nodes representations (batch x nodes x node_dim).

• adj (torch.tensor) – Adjacency matrix (batch x edge_types x nodes x nodes).

Результат:

New node representations (batch x nodes x out_dim).

Тип результата:

torch.tensor

class organ.layers.GraphAggregation(in_features, out_features, m_dim, dropout)

Aggregation of node descriptions.

The layer aggregates nodes descriptions into a global graph representation vector. The implemented aggregation is done in the following way. There are two representations of the nodes (n_nodes x in_features and n_nodes x m_dim). They are concetenated (outside this class), and after that several non-linear transformations are applied to the result of this concatenation, so that in is mapped into new feature space (out_features), the results are multiplied and then summed for all the nodes.

It is used in the following way: during graph convolution new node representations are obtained for each node. This representation is concatenated with the original one (outside this class) and then is transformed into one vector using this class.

Предупреждение

TODO (hatter): I think, this class is not very logical - the constructor receives the dimensions of two (aggregated) representations, but forward() receives only one (concatenated) tensor. One should either do concatenation, or construct a layer with the concatenated dimension size.

forward(input, activation)

Forward pass.

Параметры:

• input (torch.tensor) – Concatenated nodes representation batch x n_nodes x (in_features + m_dim).

• activation (Callable) – Activation function for the aggregated representation.

Результат:

Aggregated (global) graph representation batch x out_features

Тип результата:

torch.tensor

class organ.layers.GraphConvolution(in_features, out_feature_list, b_dim, dropout)

Graph convolution layer.

In the original MolGAN paper (https://arxiv.org/pdf/1805.11973.pdf) it is proposed to use Relational GCN, (https://arxiv.org/pdf/1703.06103.pdf), however, this class implements a usual GCN. Difference is following:

• parameters of the graph convoltion are the same for all edge types (in R-GCN they may be different);

• in R-GCN components, corresponding to different kinds of edges are normalized (the paper discusses several types of such normalization), it is not done here.

In practice, this class implements a block, consisting of two convolutions (referred to as hidden and output).

forward(input, adj, activation=None)

Forward pass.

organ.layers.cartesian(x)

Obtain descriptions for each pair of indices.

Calculates two n x n tensors with node descriptions - the first one corresponds to the row node, the second one to the column node. Based on this pair, one can implement various ways of aggregating the representations of nodes, incident to one edge - concatenate, subtract, etc.

Параметры:

x (torch.tensor) – Batch of vertex descriptions (…, vertexes, k).

Результат:

Resulting tensors of the shape (…, vertexes, vertexes, k).

Тип результата:

pytorch.tensor, pytorch.tensor

structure.constraints

Some generic differentiable constraints on structures.

organ.structure.constraints.edge_consistent(nodes, edges)

Penalizes edges incident to non-existing nodes.

The constraint that the function is enforcing is \(y_{ij} <= x_i * x_j\), where \(x_i, x_j\) is presence of a node in respective locations, and \(y_{ij}\) is presence of an edge.

As a penalty, this is transformed to:

\[ReLU(y_{ij} - x_i * x_j)\]

Параметры:

• nodes (torch.tensor) – Batch of node descriptions (batch, nodes, f). Assumes that sum across the last dimension is 1 and node type 0 is the absence of a node.

• edges (torch.tensor) – Batch of edge descriptions (batch, nodes, nodes, edge_types). Assumes that the sum across the last dimension is 1 and edge type 0 is the absence of an edge.

Результат:

Penalty for edge inconsistence.

Тип результата:

float

organ.structure.constraints.edge_symmetric(edges)

Penalizes non-symmetric edges.

Параметры:

edges (torch.tensor) – Batch of edge descriptions (batch, nodes, nodes, edge_types).

Результат:

Penalty for non-symmetric adjecency matrix.

Тип результата:

float

utils

Functions and classes for organization metrics calculation.

class organ.utils.MetricsAggregator(org_model)

Collects and aggragates validity and quality metrics of the generated organization structures.

Organizations are defined by a tuple: - Numpy vector of node types, - Numpy matrix of edge types.

class organ.utils.OrganizationMetrics(org_model)

Utility functions to calculate organization quality and validity metrics.

Organizations are defined by a tuple: - vector of node types, - matrix of edge types.

edge_validness_scores(orgs)

Estimates egde validness for multiple organizations.

node_validness_scores(orgs)

Estimates node validness for multiple organizations.

TiNGLe

Tiny Neural Graph Library (TiNGLe).

This module defines a set of abstractions and functions to program graph neural networks (and graph convolutional networks), primarily to be used as the approximator and the discriminator in OrGAN. The necessity to create this library (instead of using, e.g., PyG) is that most existing neural graph libraries assume there is a strictly defined set of edges (and the graph is represented using this set). However, it is not the case in OrGAN, where graph edges are created by the generator, and the presence of an edge is not strictly binary (it is necessary to allow gragient flow to the generator).

The TiNGLe uses graph representation most convenient for the generation process, representing the graph connectivity by an adjacency matrix. 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:

• global representation (one vector, describing graph as a whole);

• nodes representation. In TiNGLe it is assumed, that a node can have a type, besides, it can also have some set of features, so:

  • node types (batch x nodes x node_types);

  • node features (batch x nodes x N_F);

• edges representation. Edges can also be of multiple types, however, between a pair of nodes it is not possible to have more than one edge:

  • edge types (batch x edge_types x nodes x nodes ). In this representation, 0 means that there is no edge of the respective type, and 1 - that there is. However, other values are also possible - they are interpreted as a «power» of connection and are used during the propagation through (or from) the respective edge.

  • edge representation (one for all types of edges) (batch x nodes x nodes x V_F).

The library is based on the message passing framework, specifically, message massing implemented in TiNGLe consists of the following steps:

• collection. At this step, the library identifies relevant components (depending on the message type). Any usage of the edge data is multiplied by a «strength» of this connection;

• aggregation. It is a mechanism to obtain one representation from several vectors identified during the collection step. Aggragation can be two-staged: aggregation of components (passed) via one type of edges and further aggregation across several types of edges. Two-staged aggregation occurs in V-V message passing. The simplest aggragation type is summation, some types of message passing, e.g., V-E allow concatenation, because each edge has exactly two incident nodes;

• merge. Merging the aggregated data with the existing component representation. The simplest kinds are replacement and concatenation. Some of the merging strategies are possible only for certain messages.

The library defines two types of tools:

1. Functions to implement collection and aggragation steps for various kinds of message passing.

2. Classes and «orchestration» tools to compose the architecture of a complete graph neural network.

As a result, one can build graph neural networks in the following way:

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)),
])

class organ.tingle.EV(merge='cat', **kwargs)

E-V pooling.

For each node, collects and aggregates information from the incident edges, then merges with the existing node representation.

forward(global_repr, node_types, nodes, edge_types, edges)

Forward pass.

class organ.tingle.GNNBlock(global_module=None, nodes_module=None, edges_module=None)

Plain GNN block, performing independent transformations on the selected graph components.

forward(global_repr, node_types, nodes, edge_types, edges)

Forward pass.

class organ.tingle.GraphSequential(*args)

forward(gl, nt, n, et, e)

Defines the computation performed at every call.

Should be overridden by all subclasses.

Примечание

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class organ.tingle.VE(merge='cat', apply_to_types=False, **kwargs)

V-E pooling.

For each edge, collects and aggregates information from the incident nodes, then merges with the existing edge representation.

forward(global_repr, node_types, nodes, edge_types, edges)

Forward pass.

class organ.tingle.VV(merge='cat', apply_to_types=False, **kwargs)

V-V pooling.

For each node, collects information from all adjacent nodes (using each edge type), aggregates and merges to the new node representation.

forward(global_repr, node_types, nodes, edge_types, edges)

Forward pass.

organ.tingle.ev_collect_aggregate(edge_types, edges, agg='sum', *, outbound=True, smoothing_eps=1e-06, edge_weights=None)

Collection and aggregation for ev-message passing.

Collects all edges incident to a node and aggregates them (adjacency value determines weight of an edge).

if outbound == True:

\[v_i = EGDE\_AGG_k(edge\_weights_k * AGG_j(e_{ij} * E_{kij}))\]

if outbound == False:

\[v_i = EGDE\_AGG_k(edge\_weights_k * AGG_j(e_{ji} * E_{kji}))\]

Параметры:

• edge_types (torch.tensor (batch x edge_types x nodes x nodes)) – Adjacency matrix.

• edges (torch.tensor (batch x nodes x nodes x edge_repr)) – Edge representation.

• agg (str) – Node representations aggregation strategy. Can be „sum“ (summation) or „avg“ (the sum is divided by the total weight of the contributing edges).

• outbound (Bool) – Aggregation should be for outbound edges. False means that the aggregation is across the inbound edges of a node.

• smoothing_eps (float) – Important for the aggregation strategy „avg“ to avoid accidental division by zero.

• edge_weights (torch.tensor (edge_types, )) – Edge type weights for the «second stage» aggregation.

Результат:

Nodes representation.

Тип результата:

torch.tensor (batch x nodes)

organ.tingle.ve_collect_aggregate(nodes, agg='sum')

Collection and aggregation for ve-message passing.

For each edge the function collects the representations of the incident nodes and aggregates them using the specified strategy. As a result, there is a new representation for each edge (and each edge type). According to the general principles of the library, edge weigts are applied only for «outbound» information, so it is not the case here.

\[e_{ij} = AGG(v_i, v_j)\]

Параметры:

• nodes (torch.tensor (batch x nodes x node_repr)) – Nodes representation.

• agg (str) – Node representation aggregation strategy. Can be „sum“ (summation), „avg“ (arithmetic average), „subtract“ (subtraction), or „cat“ (concatenation).

Результат:

Edge representation. This tensor describes a full graph (there is a representation for each pair of nodes).

Тип результата:

torch.tensor (batch x nodes x nodes x k)

organ.tingle.vv_collect_aggregate(nodes, edges, agg='sum', *, add_loops=False, smoothing_eps=1e-06, edge_weights=None)

Collection and aggregation for vv-message passing.

For each node and each edge type the function collects adjacent node representations (respecting the edge weight) and aggregates them according to agg strategy. Then, it also aggregates the resulting vectors along edge types (summing with optional weights).

\[v_i = EGDE\_AGG_k(edge\_weights_k * (AGG_j(E_{kij} * v_j) + add\_loops * v_i))\]

Параметры:

• nodes (torch.tensor (batch x nodes x node_repr)) – Nodes representations.

• edges (torch.tensor (batch x edge_types x nodes x nodes)) – Adjacency matrices.

• agg (str) – The strategy to aggragate nodes representations, obtained via one edge type. Can be either „sum“ (summation) or „avg“ (then the sum is divided by the sum of edge weights).

• add_loops (Bool) – If loops should be added to each of the edge types.

• smoothing_eps (float) – Important for the aggregation strategy „avg“ to avoid accidental division by zero.

• edge_weights (torch.tensor (edge_types, )) – Optional edge type weights.

Результат:

Nodes representation.

Тип результата:

torch.tensor (batch x nodes)

demo

class organ.demo.LogisticsDepartmentModel

An adapter, defining methods to use organization structure model for logistics scenario during OrGAN training.

metrics(org) → dict

Returns a dict with relevant metric values.

Параметры:

org (Configuration) – Organization structure configuration.

Результат:

metrics and functions for their evaluation.

Тип результата:

dict

validness(org) → bool

Checks structure validness.

Параметры:

org (Configuration) – Organization structure configuration.

Результат:

True if the configuration is valid, False otherwise.

Тип результата:

bool

class organ.demo.LogisticsDepartmentOrganizationStructureModel

SCSP demo model class for the logistics department scenario.

check_children(top_level_nodes, node_list, force_nodes=False)

Recursive function for checking correctness of model’s node structure.

Параметры:

• top_level_nodes (list) – List of top level nodes.

• node_list (list) – List of child nodes.

• force_nodes (bool) – Flag indicating that child models are mandatory.

Результат:

Boolean flag of the model structure correctness, txtual description of the problem (empty the model structure is valid).

Тип результата:

tuple

check_nodes(nodes) → bool

Checks node types validity.

Параметры:

nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).

Результат:

Returns True if the structure contains valid set of nodes.

Тип результата:

bool

check_org_unit_feasibility(nodes, load, unit_id, min_person, max_person, min_orgunit, req_orgunit, logging=False)

Checking the feasibility of the staff quantity of an organisational unit.

Параметры:

• nodes (list) – Model’s nodes.

• load (numeric) – Expected load of the node to be checked.

• unit_id (int) – The node to be checked.

• min_person (numeric) – Allowed minimum load for a person.

• max_person (numeric) – Allowed maximum load for a person.

• min_orgunit (numeric) – Allowed minimum load for a dedicated organisational unit.

• req_orgunit (numeric) – Minimum load for that requaires a dedicated organisational unit.

• logging (bool) – Enable/disable logging.

Результат:

True if the validations successful, False otherwise.

Тип результата:

bool

check_paramater_feasibility(nodes, staff, logging=False, ctx=None)

Checks parameter validity.

Параметры:

• nodes (List, numpy.array) – The list of node.

• staff (List, numpy.array) – The list of parameters.

• logging (bool) – Enable/disable logging.

• ctx (list) – context.

Результат:

Returns True if the parameters are valid.

Тип результата:

bool

check_relations(nodes, relations)

Checks relations validity.

Параметры:

• nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).

• relations (numpy.ndarray (n, n)) – Relation type matrix.

Результат:

• bool – Returns True if all the set of edges is valid and consistent with the nodes.

• diff – Boolean matrix of edge validness (True for valid edges).

check_uniqueness(ground_truth_nodes, ground_truth_edges, ground_truth_staff, ground_truth_ctx, nodes, edges, staff, ctx)

Checks structure uniqueness compared to the training set.

Параметры:

• ground_truth_nodes (List, numpy.array) – Nodes of the training set configurations.

• ground_truth_edges (List, numpy.array) – Edges of the training set configurations.

• ground_truth_staff (List, numpy.array) – Staff quantities of the training set configurations.

• ground_truth_ctx (List, numpy.array) – Contexts of the training set configurations.

• nodes (List, numpy.array) – Nodes of the checked configuration.

• edges (List, numpy.array) – Edges of the checked configuration.

• staff (List, numpy.array) – Staff quantiities of the checked configuration.

• ctx (List, numpy.array) – Context of the checked configuration.

Результат:

True if the configuration is unique, False otherwise.

Тип результата:

bool

convert_values2persons(nodes, load, min_person, max_person)

Convert load values to staff quantity.

Параметры:

• nodes (list) – List of model nodes.

• load (list) – Load per unit.

• min_person (numeric) – Allowed minimum load for a person.

• max_person (numeric) – Allowed maximum load for a person.

Результат:

list of staff quantities.

Тип результата:

list

generate_augmentation(base_nodes, base_edges, base_staff, logging=False, max_iterations=100)

Generate augmentation.

Параметры:

• base_nodes (List, numpy.array) – Nodes of the source configuration.

• base_nodes – Edges of the source configuration.

• base_staff (List, numpy.array) – The staff quantiities of the source configuration.

• logging (bool) – Enable/disable logging.

• max_iterations (int) – maximum number of iterations until a valid augmented configuration is generated.

Результат:

aug_nodes - augmented nodes, aug_edges - augmented edges, aug_staff - augmented staff, self.pack_to_ctx(v) - augmented context.

Тип результата:

tuple

generate_key_values(nodes, logging=False)

Generation of random key values for model parameters.

Параметры:

• nodes (list) – List of model nodes.

• logging (bool) – Enable/disable logging..

Результат:

list of generated key values.

Тип результата:

list

generate_values(nodes, v, logging=False)

Generation of augmented model parameters.

Параметры:

• nodes (list) – List of model nodes.

• v (list) – Key values for parameter generation.

• logging (bool) – Enable/disable logging.

Результат:

list of generated model parameter values.

Тип результата:

list

overlap(first, last, another_first, another_last) → bool

Checks if two intervals intersect.

Параметры:

• first (numeric) – Lower bound of the first interval

• last (numeric) – Upper bound of the first interval

• another_first (numeric) – Lower bound of the second interval

• another_last (numeric) – Upper bound of the second interval

Результат:

Returns True if the intervals intersect.

Тип результата:

bool

pack_to_ctx(v)

Pack list of load values for all nodes to context.

Параметры:

v (list) – List of load values for all nodes.

Результат:

context (key parameters).

Тип результата:

list

unpack_ctx(ctx)

Unpack context to list of load values for all nodes.

Параметры:

ctx (list) – context.

Результат:

list of load values for all nodes.

Тип результата:

list

class organ.demo.ManagementModel

An adapter, defining methods to use organization structure model for the administration and sales scenario during OrGAN training.

metrics(org) → dict

Returns a dict with relevant metric values.

Параметры:

org (Configuration) – Organization structure configuration.

Результат:

metrics and functions for their evaluation.

Тип результата:

dict

soft_constraints(nodes, edges, params, ctx)

Soft constraints for this scenario.

The function describes some relationships between node parameters, context, and organization structure to simplify the training of a generator.

Параметры:

• nodes (torch.tensor) – Nodes description in an „internal“ format: (batch, nodes, node_types). Value is the probability that a node of the specific type is located in a certain position. Zero-type corresponds to the absense of a node. Non-zero values can be only on the matrix diagonal or zeroth column.

• edges (torch.tensor) – Edges representation in an „internal“ format: (batch, nodes, nodes, edge_types).

• params (torch.tensor) – Node features: (batch, nodes, features_per_node).

• ctx (torch.tensor) – Generation context: (batch, context_features).

Результат:

Value tensor (0-dimensional). Non-negative loss for violation of the constraints.

Тип результата:

torch.tensor

validness(org) → bool

Checks structure validness.

Параметры:

org (Configuration) – Organization structure configuration.

Результат:

True if the configuration is valid, False otherwise.

Тип результата:

bool

class organ.demo.ManagementStructureModel

SCSP demo model class, describing administration and sales scenario.

check_children(top_level_nodes, node_list, force_nodes=False)

Recursive function for checking correctness of model’s node structure.

Параметры:

• top_level_nodes (list) – List of top level nodes.

• node_list (list) – List of child nodes.

• force_nodes (bool) – Flag indicating that child models are mandatory.

Результат:

Boolean flag of the model structure correctness, txtual description of the problem (empty the model structure is valid).

Тип результата:

tuple

check_nodes(nodes) → bool

Checks node types validity.

Параметры:

nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).

Результат:

Returns True if the structure contains valid set of nodes.

Тип результата:

bool

check_paramater_feasibility(nodes, staff, ctx)

Checks parameter validity.

Параметры:

• nodes (List, numpy.array) – The list of node.

• staff (List, numpy.array) – The list of parameters.

• logging (bool) – Enable/disable logging.

• ctx (list) – context.

Результат:

Returns True if the parameters are valid.

Тип результата:

bool

check_relations(nodes, relations)

Checks relations validity.

Параметры:

• nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).

• relations (numpy.ndarray (n, n)) – Relation type matrix.

Результат:

• bool – Returns True if all the set of edges is valid and consistent with the nodes.

• diff – Boolean matrix of edge validness (True for valid edges).

check_uniqueness(ground_truth_nodes, ground_truth_edges, ground_truth_staff, ground_truth_ctx, nodes, edges, staff, ctx)

Checks structure uniqueness compared to the training set.

Параметры:

• ground_truth_nodes (List, numpy.array) – Nodes of the training set configurations.

• ground_truth_edges (List, numpy.array) – Edges of the training set configurations.

• ground_truth_staff (List, numpy.array) – Staff quantities of the training set configurations.

• ground_truth_ctx (List, numpy.array) – Contexts of the training set configurations.

• nodes (List, numpy.array) – Nodes of the checked configuration.

• edges (List, numpy.array) – Edges of the checked configuration.

• staff (List, numpy.array) – Staff quantiities of the checked configuration.

• ctx (List, numpy.array) – Context of the checked configuration.

Результат:

True if the configuration is unique, False otherwise.

Тип результата:

bool

generate_augmentation(base_nodes, base_edges, base_staff, logging=False, max_iterations=100)

Generate augmentation.

Параметры:

• base_nodes (List, numpy.array) – Nodes of the source configuration.

• base_nodes – Edges of the source configuration.

• base_staff (List, numpy.array) – The staff quantiities of the source configuration.

• logging (bool) – Enable/disable logging.

• max_iterations (int) – maximum number of iterations until a valid augmented configuration is generated.

Результат:

aug_nodes - augmented nodes, aug_edges - augmented edges, aug_staff - augmented staff, ctx - augmented context.

Тип результата:

tuple

generate_key_values(nodes, logging=False)

Generation of random key values for model parameters.

Параметры:

• nodes (list) – List of model nodes.

• logging (bool) – Enable/disable logging..

Результат:

list of generated key values.

Тип результата:

list

generate_values(nodes, v, logging=False)

Generation of augmented model parameters.

Параметры:

• nodes (list) – List of model nodes.

• v (list) – Key values for parameter generation.

• logging (bool) – Enable/disable logging.

Результат:

list of generated model parameter values.

Тип результата:

list

class organ.demo.SapSamEMStructureModel

Enterprise model from SAP-SAM dataset.

Built from Organigrams of the SAP Signavio Academic Models (SAP-SAM) dataset (https://github.com/signavio/sap-sam).

check_nodes(nodes) → bool

Checks node types validity.

Параметры:

nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).

Результат:

Returns True if the structure contains valid set of nodes.

Тип результата:

bool

check_relations(nodes, relations)

Checks relations validity.

Параметры:

• nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).

• relations (numpy.ndarray (n, n)) – Relation type matrix.

Результат:

• bool – Returns True if all the set of edges is valid and consistent with the nodes.

• diff – Boolean matrix of edge validness (True for valid edges).

generate_parametrized_model(logging=False)

Return pre-defined models.

Параметры:

logging (bool) – Enable/disable logging..

Результат:

generated nodes, relations.

Тип результата:

tuple

metrics(org) → dict

Returns a dict with relevant metric values.

validness(org) → bool

Checks structure validness.