graphs

Full Documentation for hippynn.graphs package. Click here for a summary page.

Graph objects in hipppynn. This package allows definitions of interfaces for torch modules. The interfaces allow dynamic reprogramming of control flow between pytorch modules.

Index Types (i.e. Molecule, Atom, Pair) track the physical basis for a tensor. Automatic index type conversion can be performed between compatible types.

Furthermore, “parent expansions” allow for flexible signatures for node creation which attempt to hide book-keeping from the end-user.

class GraphModule(required_inputs, nodes_to_compute)

Bases: Module

extra_repr()

Set the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

forward(*input_values)

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

get_module(node)

node_from_name(name)

print_structure(suppress=True)

Pretty-print the structure of the nodes and links comprising this graph.

class IdxType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Atoms = 'Atoms'

MolAtom = 'MolAtom'

MolAtomAtom = 'MolAtomAtom'

Molecules = 'Molecules'

NotFound = 'NOT FOUND'

Pair = 'Pair'

QuadMol = 'QuadMol'

QuadPack = 'QuadPack'

Scalar = 'Scalar'

class Predictor(inputs, outputs, return_device=device(type='cpu'), model_device=None, requires_grad=False, name=None)

Bases: object

The predictor is a dressed-up GraphModule which gives access to the outputs of individual nodes.

In many cases you may simply want to use the from_graph method to generate a predictor.

The predictor will take the model graph, convert the output nodes into a padded index state, and build a new graph for these operations.

add_output(node)

apply_to_database(db, **kwargs)

Note: kwargs are passed to self.__call__, e.g. the batch_size parameter.

classmethod from_graph(graph, additional_outputs=None, **kwargs)

Construct a new predictor from an existing GraphModule.

Parameters:

• graph – graph to create predictor for. The predictor makes a shallow copy of this graph. e.g. it may move parameters from that graph to the model_device.

• additional_outputs – List of additional nodes to include in outputs

• kwargs – passed to __init__

Returns:

predictor instance

predict_all(node_values)

predict_batched(node_values, batch_size)

to(*args, **kwargs)

wrap_outputs(out_dict)

property inputs

property model_device

property outputs

compute_evaluation_order(all_nodes)

Computes the evaluation order for forward computation.

Parameters:

all_nodes – The nodes to compute

Returns:

outputs_list, inputs_list Outputs list is the node to evaluate next, which is fed the inputs in the corresponding entry of inputs_list

copy_subgraph(required_nodes, assume_inputed, tag=None)

Copy a subgraph for the required nodes. Doesn’t copy the modules. Returns copies of the specified nodes, linked implicitly to copies of their parents.

If assume_inputted is not empty, this will result in partially disconnected nodes. As such, we recommend running check_link_consistency after you have finished your graph-level operations.

Parameters:

• required_nodes – output nodes of the computation

• assume_inputed – nodes whose parents we will not include in the copy (these will be left dangling)

• tag – a string to preprend to the resulting node’s names.

Returns:

new_required, new_subgraph new_required: a list containing the new copies of required_nodes in the new subgraph.

new_subgraph: a list containing new copies of all nodes in the subgraph.

find_relatives(node_or_nodes, constraint_key, why_desc='<purpose not specified>')

Parameters:

• node_or_nodes – a node or iterable of nodes to start the search.

• constraint_key –

  1. callable to filter nodes by or

  2. type spec to be used with isinstance.

• why_desc – If a node cannot be found satisfying the constraint, raise an error with this message.

Returns:

set of nodes related to this node that obey a constraint

find_unique_relative(node_or_nodes, constraint, why_desc='<purpose not specified>')

Look for a unique parent or child node type in the graph connected to the starting node.

Parameters:

• node_or_nodes – a node or iterable of nodes to start the search.

• constraint –

  1. callable to filter nodes by or

  2. type to be used with isinstance.

• why_desc – specification of error message

Returns:

Node compatible with constraint.

Note

If no node is found, a NodeNotFoundError is rasied. If more than one node is found, a NodeambiguityError is raised.

get_connected_nodes(node_set)

Recursively return nodes connected to the specified node_set.

Parameters:

node_set – iterable collection of nodes (list, tuple, set,…)

Returns:

set of nodes with some relationship to the input set.

get_subgraph(required_nodes)

Get the subgraph associated with some target (required) nodes.

Parameters:

required_nodes – the nodes to compute

Returns:

a list of nodes involved in the computation of the required nodes.

make_ensemble(models, *, targets: List[str] = 'auto', inputs: List[str] = 'auto', prefix: str = 'ensemble_', quiet=False) → Tuple[GraphModule, Tuple[Dict[str, int], Dict[str, int]]]

Make an ensemble out of a set of models. The ensemble graph can then be used with a predictor, ase graph, or etc.

The selected nodes to ensemble are classed by the db_name associated with the nodes.

When using “auto” mode for inputs and outputs:

• The input to the ensemble will be the combined inputs for all models in the ensemble.

• The output of the ensemble will be the combined outputs for all models.

Otherwise, the set of ensemble inputs is explicitly specified, and errors may occur if the requested set of inputs and outputs is not available.

The result ensemble graph has several outputs, each of which has .mean, .std, and .all attributes which reflect the statistics of the models in the ensemble.

Note that it is not required that all models have the same sets of inputs and outputs.

If a desired node is automatically ensembled, it probably does not have a db_name. A remedy for this is to load the graphs with hippynn.graphs.ensemble.get_graphs, then find the requested nodes in the graphs and assign them the db_name. Then pass these graphs to make_ensemble.

For more information on the models parameter, see the get_graphs() function.

Parameters:

• models – list containing str, node, or graphmodule, or str to glob for model directories.

• targets – list of db_name strings or the string ‘auto’, which will attempt to infer.

• inputs – list of db_name strings of the string ‘auto’, which will attempt to infer.

• prefix – specifies the prefix for the db_name of created ensemble nodes.

• quiet – whether to print information about the constructed ensemble.

Returns:

ensemble GraphModule, (intput_info, output_info)

replace_node(old_node, new_node, disconnect_old=False)

Parameters:

• old_node – Node to replace

• new_node – Node to insert

• disconnect_old – If True, remove the old node connections from the graph.

Replaces the children of old node with new node. Effectively, this just means going to the children and swapping out their parents to point to the new node. Ignores the children of old node that are parents of the new node in order to prevent cycles in the graph.

If disconnect_old, remove references to the old node – it will become unusable.

Warning

This function changes the graph structure in-place. As such, if this function raises an error, it may result in a corrupted graph state.

Warning

This function will try to coerce index states where possible. If the index types of the nodes are not listed, the index state will not be modified. If they are incompatible, this means that the graph will not function correctly.

Returns:

None

Subpackages

• indextransformers
• indextypes
• nodes

Submodules

• ensemble module
• gops module
• graph module
• predictor module
• viz module