The Graph class#

Aliases#

halerium.core.Graph

halerium.core.graph.Graph

class Graph(name, frame=None)#

The halerium Graph class.

Graphs are structures that can contain other graphs, entities as well as (static) variables.

Graphs are designed to describe a (sub-process) that can have input and output entities. Within a graph, sub-graphs can be connected by linking their input and output entities.

Similarly to Entities Graphs are building blocks of hierarchical models with each Graph providing its own scope/namespace. However, in contrast to Entities the contents of a Graph are not directly accessible from outside of the Graph. The interfacing with a Graph therefore happens by linking the to its inputs or from its outputs.

Parameters:

name (str) – The name of the graph.
frame – The frame for name injection.

__enter__()#

Enter scope.

The __enter__ method is not to be used directly. Instead the user is to utilize python’s with statement to enter the context of the scopetor.

Entering the context of the scopetor makes it the current scope. All instances of Graph, Entity, Variable, StaticVariable or Operator created in the context will be children of the scopetor.

Returns:: self – The scopetor itself.
Return type:: Scopetor

__exit__(exc_type, exc_val, exc_tb)#

Exit scope.

The __exit__ method is not to be used directly. Instead the user is to utilize python’s with statement to enter and exit the context of the scopetor.

Parameters:

exc_type – The exception type.
exc_val – The exception value.
exc_tb – The traceback.

Return type:

None.

accept(visitor)#

Accept visitor.

Parameters:: visitor – The visitor to accept.
Returns:: The result of the visit.
Return type:: result

property children#

Children.

A dictionary of all children of the scopetor.

copy(name=None, strict=True)#

Copy.

Returns a copy of the self. Constructed in the current scope.

Parameters:

name (str, optional) – The name of the copy. The default is the name of the copied instance.
strict (bool, optional) – If True the scopetor has to be self-contained. If False not self-contained parts are left out and will be set to None in the copied instance. The default is True.

Returns:

copy_of_self – The copied instance.

Return type:

Graph, Entity or Variable

deep_scope()#

This method created a DeepScope instance that allows for direct scoping into grandchildren.

Example:

``` g = Graph(“g”) with g:

g1 = Graph(“g1”) with g1:

g2 = Graph(“g2”)

with g.g1.g2.deep_scope():: pass

```

Returns:: A DeepScope instance that allows for deep scoping of self.
Return type:: DeepScope

dump_dict(strict=True)#

Convert scopetor to specification dict. A specification dict is dictionary that contains only JSON-compatible standard types (list, dict, string, float) and fully specifies all properties of the scopetor.

Parameters:: strict (bool, optional) – If True the scopetor has to be self-contained. If False not self-contained parts are left out and will be set to None in the specification. The default is True.
Returns:: specification – A dictionary containing the specifications for self and all its (grand-)children.
Return type:: dict

dump_file(fp, strict=True)#

Serialize the scopetor into a JSON formatted stream to fp.

Parameters:

fp (filename or file-like object) – If a string is provided a file with that name is created. Otherwise a file-like object (supporting .write()) is expected to which the serialized specification is written.
strict (bool, optional) – If True the scopetor has to be self-contained. If False not self-contained parts are left out and will be set to None in the specification. The default is True.

Return type:

None.

dump_string(strict=True)#

Serialize scopetor into a JSON formatted str.

Parameters:: strict (bool, optional) – If True the scopetor has to be self-contained. If False not self-contained parts are left out and will be set to None in the specification. The default is True.
Returns:: serialized_spec – The serialized JSON formatted str containing the specifications for self and all its (grand-)children.
Return type:: str

property entities#: A container with all the Entity instances in children. The container behaves like a dictionary.

classmethod from_specification(specification=None, file=None, overwrite_name=None, frame=None)#

Create a scopetor instance from a (serialized) specification or from a file containing a serialized specification. Optionally, the top-level name can be replaced.

Parameters:

specification (dict or str, optional) – Can be either a specification dict or a serialized specification dict in a JSON formatted string or file-like object supporting .read().
file (file-handle or file name, optional) – Can be either a file-like object supporting .read() or a file path to a file containing a JSON formatted string of a specification. Will be ignored if specification is provided.
overwrite_name (str, optional) – If provided, the top-level name of the scopetor will be replaced. Names of children are not affected, only their global names. The default is None.
frame (optional,) – If provided, the scopetor instance will try to register its name in the frame’s namespace

Returns:

A scopetor instance.

Return type:

Graph, Entity, Variable, StaticVariable

classmethod from_template(template, name)#

Create a scopetor instance from a serialization.

Parameters:

template (Template object) – The serialization from which to create an instance.
name (str) – The name given to the instance.

Raises:

TypeError – If the serialization class does not match the scopetor class an exception is raised.

Returns:

The instanciated serialization.

Return type:

Graph, Entity, Variable, StaticVariable

get_all_variable_dependencies(include_links=True)#

Get all variable dependencies.

Get the dependencies of every variable in the scopetor.

Parameters:: include_links (bool, optional) – Whether a link between variables is seen as a dependency.
Returns:: dependencies – Every variable has its own key, value pair. The keys of the dict are global names of variables. The values are sets of global names of all variables whose values or moments are being used to calculate the distribution parameters of the variable specified in the key.
Return type:: dict

get_all_variables(include_self=True, included_types=None, excluded_types=None)#

Get all variables.

Get all variables in the scopetor, including the scopetor itself if it is a variable, too.

Parameters:

include_self (bool, optional) – Whether to consider self as part of the set of variables. The default is True.
included_types (type, tuple, optional) – Only variables matching one of the listed types will be included. The default is to include all kinds of (static and dynamic) variables.
excluded_types (type, tuple, optional) – Variables matching one of the listed types will be excluded. The default is to exclude no types.

Returns:

A set of all variable objects contained in the scopetor.

Return type:

variables

get_child_by_name(relative_or_absolute_name, name_is_relative=True)#

Get child by name.

Get a (grand-)child of the scopetor by its relative name. The relative name is assumed to be constructed with keep_self=False.

Parameters:

relative_or_absolute_name (str) – The absolute or relative name of the (grand-)child.
name_is_relative (bool) – whether the name is relative

Returns:

child – The python object corresponding to the relative name.

Return type:

Graph, Entity, Variable, StaticVariable

Raises:

KeyError – If child is not found.

get_children(depth=- 1, include_self=False, included_types=None, excluded_types=None)#

Get children.

Get all children up to a given depth-level. For example, with depth-level 2 the method returns all children and grand-children. With depth=-1 all contained scopees are returned, no matter how deep. With include_self=True, self will also be considered a child.

Parameters:

depth (int, optional) – The maximal depth of children, whose name are returned. A negative value corresponds to infinite depth. The default is -1.
include_self (bool, optional) – Whether to consider self as part of the list of children. The default is False.
included_types (type, tuple, optional) – Only children matching one of the listed types will be included. The default is to include Scopees.
excluded_types (type, tuple, optional) – Children matching one of the listed types will be excluded. The default is to exclude any Inputs, Outputs, or Link.

Returns:

A set of all collected children.

Return type:

children

get_children_names(depth=- 1, include_self=False, included_types=None, excluded_types=None)#

Get global names of children.

Get all children global names up to a given depth-level. For example, with depth-level 2 the method returns all children and grand-children. With depth=-1 the global names of all contained scopetors are returned, no matter how deep. With include_self=True, self will also be considered a child.

Parameters:

depth (int, optional) – The maximal depth of children, whose name are returned. A negative value corresponds to infinite depth. The default is -1.
include_self (bool, optional) – Whether to consider self as part of the set of children. The default is False.
included_types (type, tuple, optional) – Only children matching one of the listed types will be included. The default is to include Scopees.
excluded_types (type, tuple, optional) – Children matching one of the listed types will be excluded. The default is to exclude any Inputs, Outputs, or Link.

Returns:

The global names of the children.

Return type:

child_names

get_containing_class(scopetor_cls)#

Get the closest parent that is of a specific type.

Parameters:: scopetor_cls (scopetor subclass) – The scopetor subclass of which the next containing instance is to be found.
Raises:: ValueError – If no containing scopetor of type scopetor_cls is found, an error is raised.
Returns:: scope – The containing scopetor of type scopetor_cls.
Return type:: scopetor_cls

Examples

>>> from halerium.core import Graph, Entity
>>> g = Graph("g")
>>> with g:
>>>     e = Entity("e")
>>>     with e:
>>>         Entity("m")
>>> g.e.m.get_containing_class(Graph) is g
True
>>> assert g.e.m.get_containing_class(Entity) is g.e
True

get_relative_name(global_name, keep_self=False)#

Get relative name.

Get the relative name of a (grand-) child of the scopetor.

Example:

global_name of the scopetor: “a/b/c” global_name provided in argument: “a/b/c/d/e/f”

with keep_self = False we get relative_name = “d/e/f”

with keep_self = True we get relative_name = “c/d/e/f”

Parameters:

global_name (str) – The global name that is to be converted into a relative name.
keep_self (bool, optional) – Whether or not to keep the name of the scopetor as a prefix. The default is False.

Raises:

ValueError – The the global name cannot be located within the scopetor an expeption is raised.

Returns:

relative_name – The relative name extracted from the global name.

Return type:

str

get_template(name=None, strict=True)#

Get a serialization of self to create duplicates at will.

Parameters:

name (str, optional) – The name of the serialization. The default is None.
strict (bool, optional) – If True the scopetor has to be self-contained. If False not self-contained parts are left out and will be set to None in the template. The default is True.

Returns:

The templated version of self. Can be called to create an equivalent copy of self.

Return type:

Template

property global_name#

The global name of the scopee.

The global name is a chain of all parent names of this scopee separated by ‘/’ characters.

property graphs#: A container with all the Graph instances in children. The container behaves like a dictionary.

has_equivalent_scopee(scopee, compare_children=False)#

Whether there is an equivalent instance of scopee in the scopetor.

Parameters:

scopee (Scopee) – The scopee for which to find its equivalent in this Scopetor. A Graph, Entity, StaticVariable, or Variable instance.
compare_children (bool, optional) – Whether to compare children for equivalence test.

Returns:

has_scopee – Whether there is an equivalent scopee in this Scopetor.

Return type:

bool

is_child_of(scopetor, include_self=True)#

Whether is child of scopetor.

This method checks whether the scopee is a (grand-) child of a given scopetor.

Parameters:

scopetor (Scopetor) – The (possible) parent scopetor
include_self (bool) – If True, a.is_child_of(a) would return True. If False, a.is_child_of(a) would return False.

Returns:

Whether self is a (grand-)child of scopetor or not.

Return type:

bool

property links#: A container with all the Link instances in children. The container behaves like a dictionary.

property name#: The name of the scopee.

property operators#

register(child, frame=None)#

Registers a child with the scopetor.

It is not necessary for the user to call this method. It will be automatically called during the creation of any Graph, Entity, Variable, StaticVariable or Operator.

Parameters:

child (Scopee) – The child instance
frame (frame, optional) – a frame created with the inspect module. The child will be placed into the namespace of the frame. The default is None.

reset()#

Resets the scopetor.

The children container is emptied.

The children themselves will still hold references to the scopetor. So if they still exist as python variables or are contained in some user-managed structure this can lead to inconsistencies.

to_equivalent_scopee(scopee, compare_children=False, on_failure='raise')#

Find the equivalent instance of scopee in the scopetor.

This method helps finding equivalent scopees in e.g. a copy of the containing scopetor.

Parameters:

scopee (Scopee) – The scopee for which to return its equivalent in this Scopetor. A Graph, Entity, StaticVariable, or Variable instance.
compare_children (bool, optional) – Whether to compare children for equivalence test.
on_failure (str, None, optional) – How to react if no equivalent can be found.

Returns:

returns – The equivalent to scopee in this Scopetor.

Return type:

Scopee, None

to_equivalent_scopees(fetches, compare_children=False, on_failure='raise')#

Find the equivalent instances of fetches in the scopetor.

This method helps finding equivalent scopees in e.g. a copy of the containing scopetor.

Parameters:

fetches (list, dict, Scopee) – The Scopee(s) for which to return its equivalent in this Scopetor. A container of Graph, Entity, StaticVariable, or Variable instances. The container can be nested, e.g. a list of dicts or a dict with lists as values as long as the contained objects (for dicts its values that matter) are instances of appropriate classes.
compare_children (bool, optional) – Whether to compare children for equivalence test.
on_failure (str, None, optional) – How to react if no equivalent can be found. Possible values are: - ‘raise’: raise an exception (default), - ‘input’: return the input. - None: return None.

Returns:

The equivalent(s) to fetches in this Scopetor.

Return type:

returns

unregister(child, frame=None)#

Unregisters a child.

The child itself will still hold a reference to the scopetor. So if the child still exists as python variables or is contained in some user-managed structure this can lead to inconsistencies.

Parameters:

child (Scopee) – the child instance
frame (frame, optional) – a frame created with the inspect module. The default is None.

property variables#: A container with all the Variable and StaticVariable instances in children. The container behaves like a dictionary.