OrGAN Modules¶

solver¶

Main module for training and testing of the OrGAN.

class organ.solver.Solver(config)[source]¶

Class for training and testing the OrGAN model.

build_model()[source]¶: Create neural models (generator, discriminator, and approximator).

build_tensorboard()[source]¶: Tensorboard logging initialization.

generate(batch_size: int = 1, ctx=None)[source]¶

Generate a batch of samples.

Parameters:

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)[source]¶

Generate valid organizations.

Parameters:

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.

Returns:

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

Return type:

list

gradient_penalty(y, x)[source]¶

Gradient penalty.

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

label2onehot(labels, dim)[source]¶

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.

Parameters:

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.

Returns:

Real-valued tensor, consisting of zeros and ones.

Return type:

torch.tensor (float)

load_pretrained()[source]¶: Load pretrained models.

postprocess(inputs, method, temperature=1.0)[source]¶

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).

Parameters:

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.

Returns:

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.

Return type:

list [torch.tensor]

postprocess_nodes(nodes_logits)[source]¶

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.

Parameters:: nodes_logits (pytorch.tensor) – Batch of logits for node presence, batch x vertexes.
Returns:: Batch of specifications batch x vertexes x nodes.
Return type:: torch.tensor

print_network(model, name)[source]¶

Print model description.

Parameters:

model (torch.Module) – Model to print.
name (str) – Model name (only for readability purposes).

reset_grad()[source]¶: Reset gradients of all optimizers.

restore_model(resume_iters)[source]¶

Load models from a savepoint.

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

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

reward(orgs)[source]¶

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.

Parameters:: orgs (list) – A list of organization specifications.
Returns:: Batch of reward values.
Return type:: numpy.ndarray, shape (batch_size, 1)

sample_z(batch_size)[source]¶: Form samples from the input distribution of the generator.

test()[source]¶: Model testing.

train()[source]¶: Training cycle.

update_lr(g_lr, d_lr)[source]¶

Sets learning rate constants (for all the models).

Parameters:

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

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)[source]¶

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)[source]¶

Forward pass.

Parameters:

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)[source]¶

Conditional parametric generator.

forward(cond, z)[source]¶: Forward pass.

class organ.models.Discriminator(conv_dim, m_dim, b_dim, dropout)[source]¶

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).

Note

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

forward(adj, nodes, ignored, ignored_, activation=None)[source]¶

Forward pass.

Parameters:

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)[source]¶

Generator that creates edges based on types of nodes.

Note

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

forward(_, x)[source]¶: Forward pass.

class organ.models.FCBlock(input_dim, hidden_dims, output_dim, activation, dropout=0.0)[source]¶

A fully-connected block.

forward(input)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

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)[source]¶

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)[source]¶

Forward pass.

Note

Output values are not bounded, activation is not applied.

Parameters:: x (torch.tensor) – Input tensor of batch x z_dim.
Returns:: 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.
Return type:: 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.

Warning

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)[source]¶

Edge convolution layer.

forward(nodes, adj)[source]¶

Forward pass.

Parameters:

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).

Returns:

New node representations (batch x nodes x out_dim).

Return type:

torch.tensor

class organ.layers.GraphAggregation(in_features, out_features, m_dim, dropout)[source]¶

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.

Warning

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)[source]¶

Forward pass.

Parameters:

input (torch.tensor) – Concatenated nodes representation batch x n_nodes x (in_features + m_dim).
activation (Callable) – Activation function for the aggregated representation.

Returns:

Aggregated (global) graph representation batch x out_features

Return type:

torch.tensor

class organ.layers.GraphConvolution(in_features, out_feature_list, b_dim, dropout)[source]¶

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)[source]¶: Forward pass.

organ.layers.cartesian(x)[source]¶

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.

Parameters:: x (torch.tensor) – Batch of vertex descriptions (…, vertexes, k).
Returns:: Resulting tensors of the shape (…, vertexes, vertexes, k).
Return type:: pytorch.tensor, pytorch.tensor

structure.constraints¶

Some generic differentiable constraints on structures.

organ.structure.constraints.edge_consistent(nodes, edges)[source]¶

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

Parameters:

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.

Returns:

Penalty for edge inconsistence.

Return type:

float

organ.structure.constraints.edge_symmetric(edges)[source]¶

Penalizes non-symmetric edges.

Parameters:: edges (torch.tensor) – Batch of edge descriptions (batch, nodes, nodes, edge_types).
Returns:: Penalty for non-symmetric adjecency matrix.
Return type:: float

utils¶

Functions and classes for organization metrics calculation.

class organ.utils.MetricsAggregator(org_model)[source]¶

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)[source]¶

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)[source]¶: Estimates egde validness for multiple organizations.

node_validness_scores(orgs)[source]¶: 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:

Functions to implement collection and aggragation steps for various kinds of message passing.
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)[source]¶

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)[source]¶: Forward pass.

class organ.tingle.GNNBlock(global_module=None, nodes_module=None, edges_module=None)[source]¶

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

forward(global_repr, node_types, nodes, edge_types, edges)[source]¶: Forward pass.

class organ.tingle.GraphSequential(*args)[source]¶

forward(gl, nt, n, et, e)[source]¶

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

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)[source]¶

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)[source]¶: Forward pass.

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

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)[source]¶: Forward pass.

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

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}))\]

Parameters:

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.

Returns:

Nodes representation.

Return type:

torch.tensor (batch x nodes)

organ.tingle.ve_collect_aggregate(nodes, agg='sum')[source]¶

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

Parameters:

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).

Returns:

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

Return type:

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)[source]¶

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

Parameters:

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.

Returns:

Nodes representation.

Return type:

torch.tensor (batch x nodes)

demo¶

class organ.demo.LogisticsDepartmentModel[source]¶

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

metrics(org) → dict[source]¶

Returns a dict with relevant metric values.

Parameters:: org (Configuration) – Organization structure configuration.
Returns:: metrics and functions for their evaluation.
Return type:: dict

validness(org) → bool[source]¶

Checks structure validness.

Parameters:: org (Configuration) – Organization structure configuration.
Returns:: True if the configuration is valid, False otherwise.
Return type:: bool

class organ.demo.LogisticsDepartmentOrganizationStructureModel[source]¶

SCSP demo model class for the logistics department scenario.

check_children(top_level_nodes, node_list, force_nodes=False)[source]¶

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

Parameters:

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.

Returns:

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

Return type:

tuple

check_nodes(nodes) → bool[source]¶

Checks node types validity.

Parameters:: nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).
Returns:: Returns True if the structure contains valid set of nodes.
Return type:: bool

check_org_unit_feasibility(nodes, load, unit_id, min_person, max_person, min_orgunit, req_orgunit, logging=False)[source]¶

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

Parameters:

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.

Returns:

True if the validations successful, False otherwise.

Return type:

bool

check_paramater_feasibility(nodes, staff, logging=False, ctx=None)[source]¶

Checks parameter validity.

Parameters:

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:

Returns True if the parameters are valid.

Return type:

bool

check_relations(nodes, relations)[source]¶

Checks relations validity.

Parameters:

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.

Returns:

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)[source]¶

Checks structure uniqueness compared to the training set.

Parameters:

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.

Returns:

True if the configuration is unique, False otherwise.

Return type:

bool

convert_values2persons(nodes, load, min_person, max_person)[source]¶

Convert load values to staff quantity.

Parameters:

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.

Returns:

list of staff quantities.

Return type:

list

generate_augmentation(base_nodes, base_edges, base_staff, logging=False, max_iterations=100)[source]¶

Generate augmentation.

Parameters:

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.

Returns:

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

Return type:

tuple

generate_key_values(nodes, logging=False)[source]¶

Generation of random key values for model parameters.

Parameters:

nodes (list) – List of model nodes.
logging (bool) – Enable/disable logging..

Returns:

list of generated key values.

Return type:

list

generate_values(nodes, v, logging=False)[source]¶

Generation of augmented model parameters.

Parameters:

nodes (list) – List of model nodes.
v (list) – Key values for parameter generation.
logging (bool) – Enable/disable logging.

Returns:

list of generated model parameter values.

Return type:

list

overlap(first, last, another_first, another_last) → bool[source]¶

Checks if two intervals intersect.

Parameters:

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:

Returns True if the intervals intersect.

Return type:

bool

pack_to_ctx(v)[source]¶

Pack list of load values for all nodes to context.

Parameters:: v (list) – List of load values for all nodes.
Returns:: context (key parameters).
Return type:: list

unpack_ctx(ctx)[source]¶

Unpack context to list of load values for all nodes.

Parameters:: ctx (list) – context.
Returns:: list of load values for all nodes.
Return type:: list

class organ.demo.ManagementModel[source]¶

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

metrics(org) → dict[source]¶

Returns a dict with relevant metric values.

Parameters:: org (Configuration) – Organization structure configuration.
Returns:: metrics and functions for their evaluation.
Return type:: dict

soft_constraints(nodes, edges, params, ctx)[source]¶

Soft constraints for this scenario.

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

Parameters:

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).

Returns:

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

Return type:

torch.tensor

validness(org) → bool[source]¶

Checks structure validness.

Parameters:: org (Configuration) – Organization structure configuration.
Returns:: True if the configuration is valid, False otherwise.
Return type:: bool

class organ.demo.ManagementStructureModel[source]¶

SCSP demo model class, describing administration and sales scenario.

check_children(top_level_nodes, node_list, force_nodes=False)[source]¶

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

Parameters:

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.

Returns:

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

Return type:

tuple

check_nodes(nodes) → bool[source]¶

Checks node types validity.

Parameters:: nodes (List, numpy.array) – The list of node types for each vertex (length must be ==`self.MAX_NODES_PER_GRAPH`).
Returns:: Returns True if the structure contains valid set of nodes.
Return type:: bool

check_paramater_feasibility(nodes, staff, ctx)[source]¶

Checks parameter validity.

Parameters:

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:

Returns True if the parameters are valid.

Return type:

bool

check_relations(nodes, relations)[source]¶

Checks relations validity.

Parameters:

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.

Returns:

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)[source]¶

Checks structure uniqueness compared to the training set.

Parameters:

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.

Returns:

True if the configuration is unique, False otherwise.

Return type:

bool

generate_augmentation(base_nodes, base_edges, base_staff, logging=False, max_iterations=100)[source]¶

Generate augmentation.

Parameters:

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.

Returns:

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

Return type:

tuple

generate_key_values(nodes, logging=False)[source]¶

Generation of random key values for model parameters.

Parameters:

nodes (list) – List of model nodes.
logging (bool) – Enable/disable logging..

Returns:

list of generated key values.

Return type:

list

generate_values(nodes, v, logging=False)[source]¶

Generation of augmented model parameters.

Parameters:

nodes (list) – List of model nodes.
v (list) – Key values for parameter generation.
logging (bool) – Enable/disable logging.

Returns:

list of generated model parameter values.

Return type:

list

OrGAN

Navigation

Related Topics

OrGAN Modules¶

solver¶

models¶

layers¶

structure.constraints¶

utils¶

TiNGLe¶

demo¶