Abstract Base Nodes

Node

class pysigma.graphical.basic_nodes.Node(name, device='cpu')[source]

The base class for all nodes in PySigma graphical architecture.

Declares common attributes between FactorNode and VariableNode, for example a flag indicating whether this node has reach quiescence, i.e., whether no new message shall be sent via adjacent links in current cycle. During construction of the graph, its instance should be passed to NetworkX methods to instantiate a node.

Parameters

  • name (str) – Name of the node.

  • device (str) – The device on which the node should be processing the messages. Defaults to ‘cpu’

name
device
visited

Indicates whether this node has been visited at all, i.e., compute() method being called at the current cycle. Default to False at the start of the cycle.

Type

bool

in_linkdata

List of incoming linkdata.

Type

list of LinkData

out_linkdata

List of outgoing linkdata.

Type

list of LinkData

log

Internal log

Type

dict

pretty_log

Pretty log for beautiful front-end visualization.

Type

dict

property quiescence

Indicates whether this node has reached quiescence state, and no further message update computations, i.e., compute(), is necessary at the decision phase of the current cognitive cycle. This property thus plays an important role in deciding the node traversing schedule of the graphical architecture.

The default behavior is to check whether any incoming linkdata contains a new unread message. If so, it is decided that this node has breached quiescence and should carry out compute(), otherwise this nodes stays quiesced.

This property should be overridden by subclass that desires a different quiescence checking behavior. For example for certain nodes, compute() may only be called once all incoming linkdata contain new messages, not any, and for other nodes their quiescence states depend only on whether compute() has ever been called within the current decision phase.

Adding linkdata connecting to this node.

abstract compute()[source]

Compute method to be called to propagate messages during decision phases.

Note that super() must be called within compute() method in any child class, because all abstract node-level statistics logging is taken care of herein.

The default quiescence behavior for compute() is to return directly if self.quiescence is True, without logging anything or performing any further computation. Note that such behavior may or may not be desired by child node class.

reset_state()[source]

Clears and resets the node’s message propagation statistics to prepare logging for the imminent decision phase computation.

Note

This method should be called prior to the first call to compute() at every cognitive cycle.

Factor Node

class pysigma.graphical.basic_nodes.FactorNode(name, device='cpu')[source]

Factor node abstract base class.

Guarantees that all incident nodes are variable nodes.

Add a linkdata connecting to a variable node

Parameters

linkdata (LinkData) – The incident linkdata to be registered.

Variable Node

class pysigma.graphical.basic_nodes.VariableNode(name, rel_var_list, param_var=None, index_var_list=None, ran_var_list=None, **kwargs)[source]

Variable node abstract base class.

Guarantees that all incident nodes are factor nodes

Parameters

  • name (str) – Name of this variable node.

  • rel_var_list (iterable of Variable) – Iterable of relational variables. Corresponds to the batch dimensions. Used to check b_shape attribute of incoming messages.

  • param_var (Variable, optional) – The parameter variable. Corresponds to the parameter dimension. Used to check p_shape attribute of incoming messages.

  • index_var_list (iterable of Variable, optional) – Iterable of indexing variables. Corresponds to the sample dimensions. Used to check s_shape attribute of incoming messages. Must specify if ran_var_list is specified.

  • ran_var_list (iterable of Variable, optional) – Iterable of random variables. Corresponds to the event dimensions. Used to check e_shape attribute of incoming messages. Must specify if index_var_list is specified.

rel_vars

Tuple of relational variables, specified by rel_var_list.

Type

tuple of Variable

param_var

Parameter variable, specified by param_var. Defaults to None if param_var is not specified.

Type

Variable

index_vars

Tuple of indexing variables, specified by index_var_list. Defaults to None if index_var_list is not specified.

Type

tuple of Variable

ran_vars

Tuple of random variables, specified by ran_var_list. Default sto None if ran_var_list is not specified.

Type

tuple of Variable

b_shape

Batch dimension sizes. Inferred from rel_vars.

Type

torch.Size

p_shape

Parameter dimension sizes. Inferred from param_var. Defaults to torch.Size([]).

Type

torch.Size

s_shape

Sample dimension sizes. Inferred from index_vars. Defaults to torch.Size([]).

Type

torch.Size

e_shape

Event dimension sizes. Inferred from ran_vars. Defaults to torch.Size([]).

Type

torch.Size

Register the LinkData connecting a factor node to this variable node.

Checks that the preset message shape specified in linkdata agrees with the inferred message shape at this variable node.

Parameters

linkdata (LinkData) – The incident linkdata to be registered.

Raises

AssertionError – If the linkdata to be added does not impose the same message shape restriction as this variable node does.

Alpha Factor Node

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

Abstract base class for any factor node belonging to an alpha subgraph.

Captures the commonalities of all alpha subgraph nodes:

  • Topology: an alpha node accepts up to two pairs of incoming and outgoing linkdata, with one pair propagating messages inward toward the Gamma Factor Node, and the other pair propagating messages outward toward the predicate Working Memory Variable Node.

  • Admissible variable nodes: an alpha node treats the relational variables and manipulates messages’ batch dimensions only, and leaves untouched the random variables and corresponding event dimensions. Therefore, incident variable nodes should have the same tuple of random variables.

  • Compute pattern: an alpha node computes outgoing messages for each pair of linkdata individually. In other words, for instance, the outgoing message to an inward outgoing link is solely dependent on the message received from the inward incoming link. Accordingly, the compute() method is subdivided into an inward_compute() and an outward_compute() method.

  • Quiescence state: an alpha node as a whole reaches quiescence if and only if all incoming linkdata do not contain new message. However, for the two subdivided method inward_compute() and outward_compute(), each of them should only be carried out if its incoming linkdata of interest contains new message.

An alpha factor node admits at least one but no more than two pairs of incoming and outgoing linkdata. The incident variable nodes should have the same tuple of random variables. Furthermore, a "direction" key-ed attribute should be included in the linkdata’s optional attribute map with value "inward" or "outward" to indicate the message propagation direction of the linkdata. The two pairs of linkdata should have different message propagation directions.

Parameters

linkdata (LinkData) – The linkdata to be registered. Must specify a "direction" attribute in its optional attribute map linkdata.attr.

compute()

Carries out inward_compute() and outward_compute() individually if their corresponding incoming linkdata contains new message.

abstract inward_compute(in_ld, out_ld)

Inward message computation. To be implemented by child class.

abstract outward_compute(in_ld, out_ld)

Outward message computation. To be implemented by child class.

Beta Factor Node

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

Abstract base class for nodes belonging to the beta subgraph of a conditional.

Captures the commonalities of beta subgraph nodes:

  • Topology: a beta node is typically connected to up to two pairs of lists of incoming and outgoing links, with each pair designated a unique message propagation direction. In other words, contrast to an alpha node, a beta node for example may be connected to multiple inward incoming links. However, the message propagation directions of the links are well grouped in that, if there is inward incoming link, then there must be a inward outgoing link.

  • Admissible variable nodes: a beta factor node treats the random variables only, and leave untouched the relational variables that should have been processed by alpha factor nodes. Thus, incident variable nodes should have the same tuple of relational variables.

  • Compute pattern: similar to an alpha factor node. However, since there may be multiple incoming links with same message propagation direction, each subdivided compute method, i.e., inward_compute() and outward_compute(), would be executed if all of its incoming linkdata contain new messages.

  • Quiescence state: similar to an alpha factor node. inward_compute() and outward_compute() will only be carried out if all of their corresponding incoming linkdata contain new messages.

A Beta Factor Node admits at least one but no more than two pairs of lists of incoming and outgoing linkdata. The incident variable nodes should have the same tuple of random variables. Furthermore, a "direction" key-ed attribute should be included in the linkdata’s optional attribute map with value "inward" or "outward" to indicate the message propagation direction of the linkdata. The two pairs of linkdata should have different message propagation directions.

Parameters

linkdata (LinkData) – The linkdata to be registered. Must specify a "direction" attribute in its optional attribute map linkdata.attr.

compute()

Carries out inward_compute() and outward_compute() separately only if all their corresponding incoming linkdata contains new message.

abstract inward_compute(in_ld_list, out_ld_list)

Inward message computation. To be implemented by child class.

abstract outward_compute(in_ld_list, out_ld_list)

Outward message computation. To be implemented by child class.