Conditional Subgraph Nodes

Expansion / Summarization Factor Node

class pysigma.graphical.alpha_beta_nodes.ESFN(name, sum_op=None, **kwargs)

Expansion / Summarization Factor Node

This node should be connected to two DVNs that share the same set of random variables but perhaps different relational variables, with the DVN on the outward propagation side having a set of relational variables that is a subset of the set of relational variables of the DVN on the inward propagation side. The task of this node is to manipulate the incoming message’s batch dimensions so that they align with the relational variable dimensions of the target DVN. Specifically:

• For the inward propagation, since the target DVN may include relational variables that do not present in the source DVN, this procedure consists of expansion of the message’s batch dimensions to make space for these missing relational variables, as well as permutation of the expanded dimensions so that they are in the same order as demanded by the target DVN.

• For the outward propagation, it’s the exact opposite. Summarization across the message batch dimensions associated with those un-referenced relational variables is first carried out, followed by the same permutation procedure.

The summarization step can be thought of as a search or optimization problem, for which one finds a single distribution instance that best “summarizes” the behaviors of an entire (finite) space of distribution instances, where the dimensions of the space are spanned by the un-referenced relational variables. The semantics of such summarization can vary depending on the use case. The default summarization procedure implements the semantics of “combining” distributions, i.e.:

p(x) = p_1(x) * p_2(x) * ... * p_k(x)

but a custom summarization procedure can also be declared using the sum_op argument to implement other semantics.

Parameters

• name (str) – Name of this node

• sum_op (Summarization, optional) – The summarization operation functor to be called during outward propagation. Defaults to None, in which case the “combination” semantic is implemented.

sum_op

inward_compute(in_ld, out_ld)

Expands and permutes the incoming message’s relational variable dimensions to match the target outgoing relational variable dimensions.

Raises

AssertionError – If the set of source DVN’s relational variables is not a subset of the set of target DVN’s relational variables.

outward_compute(in_ld, out_ld)

Summarizes over incoming message’s un-referenced relational variable dimensions and permute to match the target outgoing relational variable dimensions.

The summarization semantic is defined by the sum_op specified during initialization. If sum_op is None, uses default summarization semantic defined at the Message level.

Raises

AssertionError – If the set of source DVN’s relational variables is not a subset of the set of target DVN’s relational variables.

Relational Mapping Factor Node

class pysigma.graphical.alpha_beta_nodes.RMFN(name, arg2var, var2arg, arg2var_map, **kwargs)

Relation Variable Mapping Node

Converts predicate arguments from and to pattern variables. Applies relational variable’s VariableMap (if specified) by manipulating message batch dimensions. This node can thus implements the semantic of inner-pattern relational variable matching.

Mappings between the source relational arguments and target relational variables as well as that from source relational arguments to VariableMap instances need to be provided.

Parameters

• name (str) – Name of this node

• arg2var (dict) – Dictionary mapping predicate relational argument Variable instance to pattern relational variable Variable instance.

• var2arg (dict) – Dictionary mapping pattern relational variable Variable instance to LIST of predicate relational argument Variable instances. The list length would be longer than 1 if the relational variable is being referenced by multiple arguments.

• arg2var_map (dict) – Dictionary mapping predicate relational argument Variable instance to a VariableMap instance if one is specified for this argument. If an argument is not associated with a VariableMap, it should not appear in this dictionary.

arg2var

var2arg

arg2var_map

arg_set

The set of predicate argument Variable instances. Obtained from the keys of arg2var.

Type

set

var_set

The set of pattern variable Variable instances. Obtained from the keys of var2arg.

Type

set

arg2var_map_tuple

Obtained from arg2var_map. Mapping from predicate argument to the mapping dictionary (if a VariableMap is specified).

Type

dict

arg2var_map_inv_tuple

Obtained from arg2var_map. Mapping from predicate argument to the INVERSE mapping dictionary (if a VariableMap is specified).

Type

dict

inward_compute(in_ld, out_ld)

Inward computation. Converts predicate relational arguments to pattern relational variables. Applies mappings to relational variable’s values, if specified.

For inward direction, we are assuming this is used in condition or condact patterns. Accordingly, the inverse mapping should be used to map predicate arguments to pattern variables.

Will check anyway if domain and image of the inverse map agree with the size range of the predicate argument and pattern variable respectively. However to be user friendly this should be checked beforehand by compiler.

Note that domain should be a subset of predicate argument size range, but image should be exactly equal to the pattern variable size range

The computations to be carried out can be summarized in three steps: map/broaden, diagonalize, & permute

outward_compute(in_ld, out_ld)

Outward computation. Converts pattern relational variables to predicate relational arguments. Applies mappings to relational variable’s values, if specified.

For outward direction, we are assuming this is used in action or condact patterns. Accordingly, the original forward mapping should be used to map pattern variables to predicate arguments.

Will check anyway if domain and image of the forward map agree with the size range of the predicate argument and pattern variable respectively. However to be user friendly this should be checked beforehand by compiler.

Note that image of the map should be a subset of predicate argument size range, but its domain should be exactly equal to the pattern variable size range.

The computations to be carried out can be summarized in three steps: un-diagonalize, map/narrow, & permute

Concatenation, Marginalization, & Transformation Factor Node

class pysigma.graphical.alpha_beta_nodes.CMTN(name, args2var, var2trans, preemptive=False, **kwargs)

Concatenation, Marginalization, & Transformation Node

Transforms the joint predicate pattern messages from and to a list of univariate pattern element messages representative of the events of each of the referenced pattern random variables.

By default, outgoing messages that consists of only particles contents will be marked with a special attribute preemptive == True. Alternatively, a preemptive attribute can be set at the node level during the initialization of this node, in which case when set to True the outgoing message will always be marked with preemptive == True.

Marking a message with preemptive == True indicates that the event particle values of this message should be taken as the universal event values for the corresponding pattern variable during this cognitive cycle. Any other predicate pattern that references this pattern variable should be forced to adopt this list of event values. Therefore, at most one CNTN among all those that reference the same pattern variable can send preemptive messages, otherwise an exception will be raised.

Parameters

• name (str) – Name of this node

• args2var (dict) – The dictionary mapping either a single predicate random argument Variable instance, or a tuple of predicate random argument Variable instances, to a single pattern random variable Variable instance.

• var2trans (dict) – The dictionary mapping a pattern random variable Variable instance to a Transform instance, if a transformation is declared for this pattern variable. Accordingly, for each pattern element declared in the predicate pattern, there must be a corresponding FVN connected to this CMTN.

• preemptive (bool, optional) – Whether the outgoing messages to all downstream nodes will always be marked with preemptive == True. Defaults to False.

args2var

var2trans

preemptive

add_link(linkdata)

Some additional checks for CMTN

inward_compute(in_ld_list, out_ld_list)

For each pattern element in the predicate pattern, generate a univariate message that is representative of the marginal events of the associated pattern variable. Sends this message to the FVN that corresponds to this pattern element.

The above message generation step is done by the following procedure:

1. Marginalize over any un-referenced predicate arguments

2. For each random pattern element:

   1. Compute the outgoing message’s particles component:

      1. marginalize the message over all other predicate random arguments that are not referenced by this pattern element.

      2. If this pattern element references multiple predicate random arguments in a list, then concatenate these dimensions. The resulting message should consist of a single event dimension.

      3. If a transformation is declared on the associated pattern random variable, then apply the INVERSE of the transformation on the message.

   2. Annotate the outgoing message’s parameter component (if included in incoming message):

      1. Annotate the message with param_event_mismatch == False label to indicate the particles above approximates the same distribution the parameters are encoding, only if there is only one pattern element, and it references all predicate random arguments in the correct order (the original order when these arguments were declared)

      2. In any other case, annotate the message with event_space=True label.

   3. If the message do not contain parameters components, or if self.preemptive == True, annotate the outgoing message with special attribute preemptive == True. Otherwise, annotate with preemptive == False.

   3. Send this message to the corresponding outgoing linkdata

outward_compute(in_ld_list, out_ld_list)

Filter Variable Node

class pysigma.graphical.alpha_beta_nodes.FVN(name, **kwargs)

Filter Variable Node

Compares incoming message’s particle values against the constraints declared for the random variable. Filters out the particles if they do not meet the constraints, and raise an exception in this case if the message does not contain parameters.

Parameters

preemptive (bool, optional) – If True, the outgoing message will always be marked with the special attribute preemptive == True. Defaults to False.

ran_var

The single random variable this FVN is representing.

Type

Variable

val_constraints

The value constraints extracted from ran_var.

Type

set of torch.distributions.constraints.Constraint

add_link(linkdata)

FVN only admits one incoming link, but can admit multiple outgoing links

compute()

Filters particles if the particle values do not meet the pre-specified value constraints of the random random variables.

Raises

ValueError – If the message being filtered does not contain parameters; this means the outgoing message would be None had we sent out the filtered message.

Event Aggregation Factor Node

class pysigma.graphical.alpha_beta_nodes.EAFN(name, ran_var, **kwargs)

Event Aggregation Factor Node

An EAFN aggregates, for a represented conditional pattern random variable, a universal list of event particle values that should be adopted and evaluated by all predicate patterns who reference this pattern variable. In other words, the particles message sent by this node can be viewed as an augmented list of particles that both necessarily meets the value constraint of this pattern variable and sufficiently covers the important regions in the event space of each predicate pattern prior distribution.

Connected from Filter Variable Nodes, an EAFN expects incoming messages to contain at least either particles or parameters, preferably both. In addition, messages should be marked with a boolean attribute preemptive. A message with preemptive == True indicates its list of event particle values will be taken directly as the final universal list of event particle values, ignoring all other messages. An EAFN therefore expects to receive only one preemptive message, otherwise an exception will be raised. If all messages are not preemptive, then the lists of event values from all of them (if applicable, i.e., if said message contains particles) will be taken and concatenated to form the universal list.

Parameters

• name (str) – Name of this node.

• ran_var (Variable) – The pattern random variable this EAFN is representing.

name

ran_var

e_shape

The event shape. Inffered from ran_var.

Type

torch.Size

add_link(linkdata)

All connected variable node should only represent one single random variable, and it must be self.ran_var.

inward_compute(in_ld_list, out_ld_list)

In no incoming message is preemptive, then aggregate particle event values and log sampling densities. Otherwise, take the particle event values and log sampling densities form the preemptive message. If there are more than one preemptive message, raise an exception.

Outgoing message will be an identity Particles message.

Raises

ValueError – If found multiple preemptive messages.

outward_compute(in_ld_list, out_ld_list)

Outward message computation. To be implemented by child class.

Event Resolution Factor Node

class pysigma.graphical.alpha_beta_nodes.ERFN(name, ks, args2var, var2trans, **kwargs)

Event Resolution Factor Node

An ERFN receives messages containing the universal event values determined by EAFN for each of the pattern variable referenced by the represented predicate pattern, as well as another one message that is the original unprocessed message sent by the alpha subgraph terminal node (ESFN), whose event values are unprocessed. This node then proceeds to compare the universal event values of each pattern variable against the original event values of the associated predicate arguments from the unprocessed message. If all such comparisons are equal, then the original message would be sent, otherwise the universal event values will be taken as the surrogate particle values in place of the original ones, followed by a step of importance re-weighting to yield an augmented message.

Parameters

• ks (KnowledgeServer) – The KnowledgeServer instance for the represented predicate pattern.

• args2var (dict) – The dictionary mapping either a single predicate random argument Variable instance, or a tuple of predicate random argument Variable instances, to a single pattern random variable Variable instance.

• var2trans (dict) – The dictionary mapping a pattern random variable Variable instance to a Transform instance, if a transformation is declared for this pattern variable. Accordingly, for each pattern element declared in the predicate pattern, there must be a corresponding FVN connected to this CMTN.

ks

args2var

var2trans

add_link(linkdata)

ERFN admits only one outgoing linkdata connecting to a DVN with full predicate arguments as random variables.

ERFN can admit multiple incoming linkdata, but each must be labeled with a boolean special attribute "original". Each of the original==False linkdata must connect to a DVN that is one-to-one corresponding to one of the pattern variable referenced by the represented predicate pattern. On the other hand, only one original==True linkdata can be admitted, and it must be a DVN with full predicate arguments as random variables, similar to the outgoing DVN node.

inward_compute(in_ld_list, out_ld_list)

The following procedure is carried out:

1. For each pattern element (args & var pair in self.args2var):

   1. Gather the universal event values of the pattern variable from corresponding incoming linkdata

   2. If a transformation is declared on this pattern element, then apply the FORWARD (inverse of inverse) transformation on the universal event values

   3. Save the (transformed) event values as part of the surrogate particles.

2. Retrieve the message parameter from the “original” message

3. Use the surrogate particles to create an augmented Particles message, combine with original parameters, and perform importance re-weighting. Send the resulting message

outward_compute(in_ld_list, out_ld_list)

Beta Join Factor Node

Gamma Factor Node