dace.transformation package

Subpackages

Submodules

Passes and Pipelines

API for SDFG analysis and manipulation Passes, as well as Pipelines that contain multiple dependent passes.

class dace.transformation.pass_pipeline.FixedPointPipeline(*args, **kwargs)

Bases: Pipeline

A special type of Pipeline that applies its Pass objects in repeated succession until they all stop modifying the SDFG (i.e., by returning None).

See:

Pipeline

CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Applies the pipeline to the SDFG in repeated succession until the SDFG is no longer modified.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Dict[str, Any]]

Returns:

A dictionary of {Pass subclass name: return value} for applied passes, or None if no Passes were applied in the context of this pipeline.

properties()
class dace.transformation.pass_pipeline.Modifies(value)

Bases: Flag

Specifies which elements of an SDFG have been modified by a Pass/Transformation. This is used when deciding whether to rerun certain Passes for SDFG analysis. Note that this is a Python Flag, which means values such as Memlets | Symbols are allowed.

AccessNodes = 16

Access nodes’ existence or properties were modified

Descriptors = 1

Data descriptors (e.g., arrays, streams) and their properties were modified

Edges = 264

Any edge (memlet or inter-state) was modified

Everything = 511

Modification to arbitrary parts of SDFGs (nodes, edges, or properties)

InterstateEdges = 8

Contents (conditions/assignments) or existence of inter-state edges were modified

Memlets = 256

Memlets’ existence, contents, or properties were modified

NestedSDFGs = 128

SDFG nesting structure or properties of NestedSDFG nodes were modified

Nodes = 240

Modification of any dataflow node (contained in an SDFG state) was made

Nothing = 0

Nothing was modified

Scopes = 32

Scopes (e.g., Map, Consume, Pipeline) or associated properties were created/removed/modified

States = 4

The number of SDFG states and their connectivity (not their contents) were modified

Symbols = 2

Symbols were modified

Tasklets = 64

Tasklets were created/removed or their contents were modified

class dace.transformation.pass_pipeline.Pass(*args, **kwargs)

Bases: object

An SDFG analysis or manipulation that registers as part of the SDFG history. Classes that extend Pass can be used for optimization purposes, to collect data on an entire SDFG, for cleanup, or other uses. Pattern-matching transformations, as well as the SDFG simplification process, extend Pass. Passes may depend on each other through a Pipeline object, which will ensure dependencies are met and that passes do not run redundantly.

A Pass is defined by one main method: apply_pass. This method receives the SDFG to manipulate/analyze, as well as the previous Pipeline results, if run in the context of a pipeline. The other three, pipeline-related methods are: * depends_on: Which other passes this pass requires * modifies: Which elements of the SDFG does this Pass modify (used to avoid re-applying when unnecessary) * should_reapply: Given the modified elements of the SDFG, should this pass be rerun?

Seealso:

Pipeline

CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Any]

Returns:

Some object if pass was applied, or None if nothing changed.

depends_on()

If in the context of a Pipeline, which other Passes need to run first.

Return type:

Set[Union[Type[Pass], Pass]]

Returns:

A set of Pass subclasses or objects that need to run prior to this Pass.

static from_json(json_obj, context=None)
Return type:

Pass

modifies()

Which elements of the SDFG (e.g., memlets, state structure) are modified by this pass, if run successfully.

Return type:

Modifies

Returns:

A Modifies set of flags of modified elements.

properties()
report(pass_retval)

Returns a user-readable string report based on the results of this pass.

Parameters:

pass_retval (Any) – The return value from applying this pass.

Return type:

Optional[str]

Returns:

A string with the user-readable report, or None if nothing to report.

should_reapply(modified)

In the context of a Pipeline, queries whether this Pass should be rerun after other passes have run and modified the SDFG.

Parameters:

modified (Modifies) – Flags specifying which elements of the SDFG were modified.

Return type:

bool

Returns:

True if this Pass should be rerun when the given elements are modified.

classmethod subclasses_recursive()

Returns all subclasses of this class, including subclasses of subclasses.

Return type:

Set[Type[Pass]]

to_json(parent=None)
Return type:

Dict[str, Any]

class dace.transformation.pass_pipeline.Pipeline(*args, **kwargs)

Bases: Pass

A pass pipeline contains multiple, potentially dependent Pass objects, and applies them in order. Each contained pass may depend on other (e.g., analysis) passes, which the Pipeline avoids rerunning depending on which elements were modified by applied passes. An example of a built-in pipeline is the SimplifyPass, which runs multiple complexity reduction passes and may reuse data across them. Prior results of applied passes are contained in the pipeline_results argument to apply_pass, which can be used to access previous return values of Passes.

A Pipeline in itself is a type of a Pass, so it can be arbitrarily nested in another Pipelines. Its dependencies and modified elements are unions of the contained Pass objects.

Creating a Pipeline can be performed by instantiating the object with a list of Pass objects, or by extending the pipeline class (e.g., if pipeline order should be modified). The return value of applying a pipeline is a dictionary whose keys are the Pass subclass names and values are the return values of each pass. Example use:

my_simplify = Pipeline([ScalarToSymbolPromotion(integers_only=False), ConstantPropagation()])
results = my_simplify.apply_pass(sdfg, {})
print('Promoted scalars:', results['ScalarToSymbolPromotion'])
CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Dict[str, Any]]

Returns:

Some object if pass was applied, or None if nothing changed.

apply_subpass(sdfg, p, state)

Apply a pass from the pipeline. This method is meant to be overridden by subclasses.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • p (Pass) – The pass to apply.

  • state (Dict[str, Any]) – The pipeline results state.

Return type:

Optional[Any]

Returns:

The pass return value.

depends_on()

If in the context of a Pipeline, which other Passes need to run first.

Return type:

Set[Type[Pass]]

Returns:

A set of Pass subclasses or objects that need to run prior to this Pass.

iterate_over_passes(sdfg)

Iterates over passes in the pipeline, potentially multiple times based on which elements were modified in the pass. Note that this method may be overridden by subclasses to modify pass order.

Parameters:

sdfg (SDFG) – The SDFG on which the pipeline is currently being applied

Return type:

Iterator[Pass]

modifies()

Which elements of the SDFG (e.g., memlets, state structure) are modified by this pipeline, if run successfully. Computed as the union of all modified elements of each pass in the pipeline.

Return type:

Modifies

Returns:

A Modifies set of flags of modified elements.

passes

List of passes that this pipeline contains

properties()
should_reapply(modified)

In the context of a Pipeline, queries whether this Pass should be rerun after other passes have run and modified the SDFG.

Parameters:

modified (Modifies) – Flags specifying which elements of the SDFG were modified.

Return type:

bool

Returns:

True if this Pass should be rerun when the given elements are modified.

to_json(parent=None)
Return type:

Dict[str, Any]

class dace.transformation.pass_pipeline.ScopePass(*args, **kwargs)

Bases: Pass

A specialized Pass type that applies to each scope (e.g., Map, Consume, Pipeline) separately. Such a pass is realized by implementing the apply method, which accepts a scope entry node and its parent SDFG state.

See:

Pass

CATEGORY: str = 'Helper'
apply(scope, state, pipeline_results)

Applies this pass on the given scope.

Parameters:

  • scope (EntryNode) – The entry node of the scope to apply the pass to.

  • state (SDFGState) – The parent SDFG state of the given scope.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Any]

Returns:

Some object if pass was applied, or None if nothing changed.

apply_pass(sdfg, pipeline_results)

Applies the pass to the scopes of the given SDFG by calling apply on each scope entry node.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Dict[EntryNode, Optional[Any]]]

Returns:

A dictionary of {entry node: return value} for visited scopes with a non-None return value, or None if nothing was returned.

properties()
class dace.transformation.pass_pipeline.StatePass(*args, **kwargs)

Bases: Pass

A specialized Pass type that applies to each SDFG state separately. Such a pass is realized by implementing the apply method, which accepts a single state.

See:

Pass

CATEGORY: str = 'Helper'
apply(state, pipeline_results)

Applies this pass on the given state.

Parameters:

  • state (SDFGState) – The SDFG state to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Any]

Returns:

Some object if pass was applied, or None if nothing changed.

apply_pass(sdfg, pipeline_results)

Applies the pass to states of the given SDFG by calling apply on each state.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Dict[SDFGState, Optional[Any]]]

Returns:

A dictionary of {state: return value} for visited states with a non-None return value, or None if nothing was returned.

properties()
class dace.transformation.pass_pipeline.VisitorPass(*args, **kwargs)

Bases: Pass

A simple type of Pass that provides a Python visitor object on an SDFG. Used for either analyzing an SDFG or modifying properties of existing elements (rather than their graph structure). Applying a visitor pass on an SDFG would call visit_<ElementType> methods on the SDFG elements with the element, its parent, and previous pipeline results, if in the context of a Pipeline.

For example:

class HasWriteConflicts(VisitorPass):
    def __init__(self):
        self.found_wcr = False

    def visit_Memlet(self, memlet: dace.Memlet, parent: dace.SDFGState, pipeline_results: Dict[str, Any]):
        if memlet.wcr:
            self.found_wcr = True

            # If a value is returned, a dictionary key will be filled with the visited object and the value
            return memlet.wcr

wcr_checker = HasWriteConflicts()
memlets_with_wcr = wcr_checker.apply_pass(sdfg, {})
print('SDFG has write-conflicted memlets:', wcr_checker.found_wcr)
print('Memlets:', memlets_with_wcr)
CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Visits the given SDFG recursively, calling defined visit_* methods for each element.

Parameters:

  • sdfg (SDFG) – The SDFG to recursively visit.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Dict[Any, Any]]

Returns:

A dictionary of {element: return value} for visited elements with a non-None return value, or None if nothing was returned.

generic_visit(element, parent, pipeline_results)

A default method that is called for elements that do not have a special visitor.

Parameters:

  • element (Any) – The element to visit.

  • parent (Any) – The parent of the visited element (e.g., SDFGState for dataflow elements, SDFG for SDFGStates).

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Any

properties()

Transformations

This file contains classes that describe data-centric transformations.

All transformations extend the TransformationBase class. There are three built-in types of transformations in DaCe:

  • Pattern-matching Transformations (extending PatternTransformation): Transformations that require a certain subgraph structure to match. Within this abstract class, there are two sub-classes:

    • SingleStateTransformation: Patterns are limited to a single SDFG state.

    • MultiStateTransformation: Patterns are given on a subgraph of an SDFG state machine.

    A pattern-matching must extend at least one of those two classes.

  • Subgraph Transformations (extending SubgraphTransformation): Transformations that can operate on arbitrary subgraphs.

  • Library node expansions (extending ExpandTransformation): An internal class used for tracking how library nodes are expanded.

class dace.transformation.transformation.ExpandTransformation(*args, **kwargs)

Bases: PatternTransformation

Base class for transformations that simply expand a node into a subgraph, and thus needs only simple matching and replacement functionality. Subclasses only need to implement the method “expansion”.

This is an internal interface used to track the expansion of library nodes.

apply(state, sdfg, *args, **kwargs)

Applies this transformation instance on the matched pattern graph.

Parameters:

sdfg – The SDFG to apply the transformation to.

Returns:

A transformation-defined return value, which could be used to pass analysis data out, or nothing.

can_be_applied(graph, expr_index, sdfg, permissive=False)

Returns True if this transformation can be applied on the candidate matched subgraph.

Parameters:

  • graph (OrderedMultiDiConnectorGraph) – SDFGState object if this transformation is single-state, or SDFG object otherwise.

  • expr_index (int) – The list index from PatternTransformation.expressions that was matched.

  • sdfg – If graph is an SDFGState, its parent SDFG. Otherwise should be equal to graph.

  • permissive (bool) – Whether transformation should run in permissive mode.

Returns:

True if the transformation can be applied.

static expansion(node, parent_state, parent_sdfg, *args, **kwargs)
classmethod expressions()

Returns a list of Graph objects that will be matched in the subgraph isomorphism phase. Used as a pre-pass before calling can_be_applied.

See:

PatternTransformation.can_be_applied

static from_json(json_obj, context=None)
Return type:

ExpandTransformation

match_to_str(graph)

Returns a string representation of the pattern match on the candidate subgraph. Used when identifying matches in the console UI.

static postprocessing(sdfg, state, expansion)
properties()
to_json(parent=None)
Return type:

Dict[str, Any]

class dace.transformation.transformation.MultiStateTransformation(*args, **kwargs)

Bases: PatternTransformation, ABC

Base class for pattern-matching transformations that find matches within an SDFG state machine. New transformations that extend this class must contain static PatternNode-annotated fields that represent the nodes in the pattern graph, and use them to implement at least three methods:

  • expressions: A method that returns a list of graph patterns (SDFG objects) that match this transformation.

  • can_be_applied: A method that, given a subgraph candidate, checks for additional conditions whether it can be transformed.

  • apply: A method that applies the transformation on the given SDFG.

For example:

class MyTransformation(MultiStateTransformation):
    state_a = PatternNode(SDFGState)
    state_b = PatternNode(SDFGState)

    @classmethod
    def expressions(cls):
        return [node_path_graph(cls.state_a, cls.state_b)]

For more information and optimization opportunities, see the respective methods’ documentation.

See:

PatternNode

abstract can_be_applied(graph, expr_index, sdfg, permissive=False)

Returns True if this transformation can be applied on the candidate matched subgraph.

Parameters:

  • graph (SDFG) – SDFG object in which the match was found.

  • candidate – A mapping between node IDs returned from PatternTransformation.expressions and the nodes in graph.

  • expr_index (int) – The list index from PatternTransformation.expressions that was matched.

  • sdfg (SDFG) – The SDFG in which the match was found (equal to graph).

  • permissive (bool) – Whether transformation should run in permissive mode.

Return type:

bool

Returns:

True if the transformation can be applied.

abstract classmethod expressions()

Returns a list of SDFG subgraphs that will be matched in the subgraph isomorphism phase. Used as a pre-pass before calling can_be_applied.

Return type:

List[SubgraphView]

properties()
class dace.transformation.transformation.PatternNode(nodeclass)

Bases: Generic[T]

Static field wrapper of a node or an SDFG state that designates it as part of a subgraph pattern. These objects are used in subclasses of PatternTransformation to represent the subgraph patterns.

Example use:

class MyTransformation(SingleStateTransformation):
    some_map_node = PatternNode(nodes.MapEntry)
    array = PatternNode(nodes.AccessNode)

The two nodes can then be used in the transformation static methods (e.g., expressions, can_be_applied) to represent the nodes, and in the instance methods to point to the nodes in the parent SDFG.

class dace.transformation.transformation.PatternTransformation(*args, **kwargs)

Bases: TransformationBase

Abstract class for pattern-matching transformations. Please extend either SingleStateTransformation or MultiStateTransformation.

See:

SingleStateTransformation

See:

MultiStateTransformation

Seealso:

PatternNode

annotates_memlets()

Indicates whether the transformation annotates the edges it creates or modifies with the appropriate memlets. This determines whether to apply memlet propagation after the transformation.

Return type:

bool

apply(graph, sdfg)

Applies this transformation instance on the matched pattern graph.

Parameters:

sdfg (SDFG) – The SDFG to apply the transformation to.

Return type:

Optional[Any]

Returns:

A transformation-defined return value, which could be used to pass analysis data out, or nothing.

apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Any]

Returns:

Some object if pass was applied, or None if nothing changed.

apply_pattern(append=True, annotate=True)

Applies this transformation on the given SDFG, using the transformation instance to find the right control flow graph object (based on control flow graph ID), and applying memlet propagation as necessary.

Parameters:

  • append (bool) – If True, appends the transformation to the SDFG transformation history.

  • annotate (bool) – If True, applies memlet propagation as necessary.

Return type:

Optional[Any]

Returns:

A transformation-defined return value, which could be used to pass analysis data out, or nothing.

classmethod apply_to(sdfg, options=None, expr_index=0, verify=True, annotate=True, permissive=False, save=True, **where)

Applies this transformation to a given subgraph, defined by a set of nodes. Raises an error if arguments are invalid or transformation is not applicable.

The subgraph is defined by the where dictionary, where each key is taken from the PatternNode fields of the transformation. For example, applying MapCollapse on two maps can pe performed as follows:

` MapCollapse.apply_to(sdfg, outer_map_entry=map_a, inner_map_entry=map_b) `

Parameters:

  • sdfg (SDFG) – The SDFG to apply the transformation to.

  • options (Optional[Dict[str, Any]]) – A set of parameters to use for applying the transformation.

  • expr_index (int) – The pattern expression index to try to match with.

  • verify (bool) – Check that can_be_applied returns True before applying.

  • annotate (bool) – Run memlet propagation after application if necessary.

  • permissive (bool) – Apply transformation in permissive mode.

  • save (bool) – Save transformation as part of the SDFG file. Set to False if composing transformations.

  • where (Union[Node, SDFGState]) – A dictionary of node names (from the transformation) to nodes in the SDFG or a single state.

can_be_applied(graph, expr_index, sdfg, permissive=False)

Returns True if this transformation can be applied on the candidate matched subgraph.

Parameters:

  • graph (Union[SDFG, SDFGState]) – SDFGState object if this transformation is single-state, or SDFG object otherwise.

  • expr_index (int) – The list index from PatternTransformation.expressions that was matched.

  • sdfg (SDFG) – If graph is an SDFGState, its parent SDFG. Otherwise should be equal to graph.

  • permissive (bool) – Whether transformation should run in permissive mode.

Return type:

bool

Returns:

True if the transformation can be applied.

cfg_id

Object property of type int

expr_index

Object property of type int

classmethod expressions()

Returns a list of Graph objects that will be matched in the subgraph isomorphism phase. Used as a pre-pass before calling can_be_applied.

See:

PatternTransformation.can_be_applied

Return type:

List[SubgraphView]

static from_json(json_obj, context=None)
Return type:

PatternTransformation

match_to_str(graph)

Returns a string representation of the pattern match on the candidate subgraph. Used when identifying matches in the console UI.

Return type:

str

print_match(sdfg)

Returns a string representation of the pattern match on the given SDFG. Used for printing matches in the console UI.

Return type:

str

properties()
setup_match(sdfg, cfg_id, state_id, subgraph, expr_index, override=False, options=None)

Sets the transformation to a given subgraph pattern.

Parameters:

  • cfg_id (int) – A unique ID of the SDFG.

  • state_id (int) – The node ID of the SDFG state, if applicable. If transformation does not operate on a single state, the value should be -1.

  • subgraph (Dict[PatternNode, int]) – A mapping between node IDs returned from PatternTransformation.expressions and the nodes in graph.

  • expr_index (int) – The list index from PatternTransformation.expressions that was matched.

  • override (bool) – If True, accepts the subgraph dictionary as-is (mostly for internal use).

  • options (Optional[Dict[str, Any]]) – An optional dictionary of transformation properties

Raises:

  • TypeError – When transformation is not subclass of PatternTransformation.

  • TypeError – When state_id is not instance of int.

  • TypeError – When subgraph is not a dict of {PatternNode: int}.

Return type:

None

state_id

Object property of type int

classmethod subclasses_recursive(all_subclasses=False)

Returns all subclasses of this class, including subclasses of subclasses.

Parameters:

all_subclasses (bool) – Include all subclasses (e.g., including ExpandTransformation).

Return type:

Set[Type[PatternTransformation]]

property subgraph
to_json(parent=None)
Return type:

Dict[str, Any]

class dace.transformation.transformation.SingleStateTransformation(*args, **kwargs)

Bases: PatternTransformation, ABC

Base class for pattern-matching transformations that find matches within a single SDFG state. New transformations that extend this class must contain static PatternNode fields that represent the nodes in the pattern graph, and use them to implement at least three methods:

  • expressions: A method that returns a list of graph patterns (SDFGState objects) that match this transformation.

  • can_be_applied: A method that, given a subgraph candidate, checks for additional conditions whether it can be transformed.

  • apply: A method that applies the transformation on the given SDFG.

For example:

class MyTransformation(SingleStateTransformation):
    node_a = PatternNode(nodes.AccessNode)
    node_b = PatternNode(nodes.MapEntry)

    @classmethod
    def expressions(cls):
        return [node_path_graph(cls.node_a, cls.node_b)]

For more information and optimization opportunities, see the respective methods’ documentation.

See:

PatternNode

abstract can_be_applied(graph, expr_index, sdfg, permissive=False)

Returns True if this transformation can be applied on the candidate matched subgraph.

Parameters:

  • graph (SDFGState) – SDFGState object in which the match was found.

  • candidate – A mapping between node IDs returned from PatternTransformation.expressions and the nodes in graph.

  • expr_index (int) – The list index from PatternTransformation.expressions that was matched.

  • sdfg (SDFG) – The parent SDFG of the matched state.

  • permissive (bool) – Whether transformation should run in permissive mode.

Return type:

bool

Returns:

True if the transformation can be applied.

abstract classmethod expressions()

Returns a list of SDFG state subgraphs that will be matched in the subgraph isomorphism phase. Used as a pre-pass before calling can_be_applied.

Return type:

List[StateSubgraphView]

properties()
class dace.transformation.transformation.SubgraphTransformation(*args, **kwargs)

Bases: TransformationBase

Base class for transformations that apply on arbitrary subgraphs, rather than matching a specific pattern.

Subclasses need to implement the can_be_applied and apply operations, as well as registered with the subclass registry. See the PatternTransformation class docstring for more information.

apply(sdfg)

Applies the transformation on the given subgraph.

Parameters:

sdfg (SDFG) – The SDFG that includes the subgraph.

apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Optional[Any]

Returns:

Some object if pass was applied, or None if nothing changed.

classmethod apply_to(sdfg, *where, verify=True, **options)

Applies this transformation to a given subgraph, defined by a set of nodes. Raises an error if arguments are invalid or transformation is not applicable.

To apply the transformation on a specific subgraph, the where parameter can be used either on a subgraph object (SubgraphView), or on directly on a list of subgraph nodes, given as Node or SDFGState objects. Transformation properties can then be given as keyword arguments. For example, applying SubgraphFusion on a subgraph of three nodes can be called in one of two ways:

# Subgraph
SubgraphFusion.apply_to(
    sdfg, SubgraphView(state, [node_a, node_b, node_c]))

# Simplified API: list of nodes
SubgraphFusion.apply_to(sdfg, node_a, node_b, node_c)
Parameters:

  • sdfg (SDFG) – The SDFG to apply the transformation to.

  • where (Union[Node, SDFGState, SubgraphView]) – A set of nodes in the SDFG/state, or a subgraph thereof.

  • verify (bool) – Check that can_be_applied returns True before applying.

  • options (Any) – A set of parameters to use for applying the transformation.

can_be_applied(sdfg, subgraph)

Tries to match the transformation on a given subgraph, returning True if this transformation can be applied.

Parameters:

  • sdfg (SDFG) – The SDFG that includes the subgraph.

  • subgraph (SubgraphView) – The SDFG or state subgraph to try to apply the transformation on.

Return type:

bool

Returns:

True if the subgraph can be transformed, or False otherwise.

cfg_id

ID of CFG to transform

static from_json(json_obj, context=None)
Return type:

SubgraphTransformation

get_subgraph(sdfg)
Return type:

SubgraphView

properties()
setup_match(subgraph, cfg_id=None, state_id=None)

Sets the transformation to a given subgraph.

Parameters:

  • subgraph (Union[Set[int], SubgraphView]) – A set of node (or state) IDs or a subgraph view object.

  • cfg_id (Optional[int]) – A unique ID of the CFG.

  • state_id (Optional[int]) – The node ID of the SDFG state, if applicable. If transformation does not operate on a single state, the value should be -1.

state_id

ID of state to transform subgraph within, or -1 to transform the SDFG

classmethod subclasses_recursive()

Returns all subclasses of this class, including subclasses of subclasses.

Parameters:

all_subclasses – Include all subclasses (e.g., including ExpandTransformation).

Return type:

Set[Type[PatternTransformation]]

subgraph

Subgraph in transformation instance

subgraph_view(sdfg)
Return type:

SubgraphView

to_json(parent=None)
class dace.transformation.transformation.TransformationBase(*args, **kwargs)

Bases: Pass

Base class for graph rewriting transformations. An instance of a TransformationBase object represents a match of the transformation (i.e., including a specific subgraph candidate to apply the transformation to), as well as properties of the transformation, which may affect if it can apply or not.

A Transformation can also be seen as a Pass that, when applied, operates on the given subgraph.

See:

PatternTransformation

See:

SubgraphTransformation

See:

ExpandTransformation

modifies()

Which elements of the SDFG (e.g., memlets, state structure) are modified by this pass, if run successfully.

Returns:

A Modifies set of flags of modified elements.

should_reapply(_)

In the context of a Pipeline, queries whether this Pass should be rerun after other passes have run and modified the SDFG.

Parameters:

modified – Flags specifying which elements of the SDFG were modified.

Return type:

bool

Returns:

True if this Pass should be rerun when the given elements are modified.

dace.transformation.helpers module

Transformation helper API.

dace.transformation.helpers.are_subsets_contiguous(subset_a, subset_b, dim=None)
Return type:

bool

dace.transformation.helpers.can_run_state_on_fpga(state)

Checks if state can be executed on FPGA. Used by FPGATransformState and HbmTransform.

dace.transformation.helpers.constant_symbols(sdfg)

Returns a set of symbols that will never change values throughout the course of the given SDFG. Specifically, these are the input symbols (i.e., not defined in a particular scope) that are never set by interstate edges.

Parameters:

sdfg (SDFG) – The input SDFG.

Return type:

Set[str]

Returns:

A set of symbol names that remain constant throughout the SDFG.

dace.transformation.helpers.contained_in(state, node, scope)

Returns true if the specified node is contained within the scope opened by the given entry node (including through nested SDFGs).

Return type:

bool

dace.transformation.helpers.extract_map_dims(sdfg, map_entry, dims)

Helper function that extracts specific map dimensions into an outer map.

Parameters:

  • sdfg (SDFG) – The SDFG where the map resides.

  • map_entry (MapEntry) – Map entry node to extract.

  • dims (List[int]) – A list of dimension indices to extract.

Return type:

Tuple[MapEntry, MapEntry]

Returns:

A 2-tuple containing the extracted map and the remainder map.

dace.transformation.helpers.find_contiguous_subsets(subset_list, dim=None)

Finds the set of largest contiguous subsets in a list of subsets.

Parameters:

  • subsets – Iterable of subset objects.

  • dim (Optional[int]) – Check for contiguity only for the specified dimension.

Return type:

Set[Subset]

Returns:

A list of contiguous subsets.

dace.transformation.helpers.find_sdfg_control_flow(sdfg)

Partitions the SDFG to subgraphs that can be nested independently of each other. The method does not nest the subgraphs but alters the SDFG; (1) interstate edges are split, (2) scope source/sink states that belong to multiple scopes are duplicated (see _copy_state).

Parameters:

sdfg (SDFG) – The SDFG to be partitioned.

Return type:

Dict[SDFGState, Set[SDFGState]]

Returns:

The found subgraphs in the form of a dictionary where the keys are the start state of the subgraphs and the values are the sets of SDFGStates contained withing each subgraph.

dace.transformation.helpers.get_internal_scopes(state, entry, immediate=False)

Returns all internal scopes within a given scope, including if they reside in nested SDFGs.

Parameters:

  • state (SDFGState) – State in which entry node resides.

  • entry (EntryNode) – The entry node to start from.

  • immediate (bool) – If True, only returns the scopes that are immediately nested in the map.

Return type:

List[Tuple[SDFGState, EntryNode]]

dace.transformation.helpers.get_parent_map(state, node=None)

Returns the map in which the state (and node) are contained in, or None if it is free.

Parameters:

  • state (SDFGState) – The state to test or parent of the node to test.

  • node (Optional[Node]) – The node to test (optional).

Return type:

Optional[Tuple[EntryNode, SDFGState]]

Returns:

A tuple of (entry node, state) or None.

dace.transformation.helpers.gpu_map_has_explicit_threadblocks(state, entry)

Returns True if GPU_Device map has explicit thread-block maps nested within.

Return type:

bool

dace.transformation.helpers.is_symbol_unused(sdfg, sym)

Checks for uses of symbol in an SDFG, and if there are none returns False.

Parameters:

  • sdfg (SDFG) – The SDFG to search.

  • sym (str) – The symbol to test.

Return type:

bool

Returns:

True if the symbol can be removed, False otherwise.

dace.transformation.helpers.make_map_internal_write_external(sdfg, state, map_exit, access, sink)

Any writes to the Access node access that occur inside the Map with exit node map_exit are redirected to the Access node sink that is outside the Map. This method will remove, if possible, access and replace it with a transient.

Parameters:

  • sdfg (SDFG) – The SDFG in which the Access node resides.

  • state (SDFGState) – The State in which the Access node resides.

  • map_exit (MapExit) – The exit node of the Map.

  • access (AccessNode) – The Access node being written inside the Map.

  • sink (AccessNode) – The Access node to be written outside the Map.

dace.transformation.helpers.nest_sdfg_control_flow(sdfg, components=None)

Partitions the SDFG to subgraphs and nests them.

Parameters:

  • sdfg (SDFG) – The SDFG to be partitioned.

  • components – An existing partition of the SDFG.

dace.transformation.helpers.nest_sdfg_subgraph(sdfg, subgraph, start=None)

Nests an SDFG subgraph (SDFGStates and InterstateEdges).

Parameters:

  • sdfg (SDFG) – The SDFG containing the subgraph.

  • subgraph (SubgraphView) – The SubgraphView description of the subgraph.

  • start (Optional[SDFGState]) – The start state of the subgraph.

Return type:

SDFGState

Returns:

The SDFGState containing the NestedSDFG node (containing the nested SDFG subgraph).

dace.transformation.helpers.nest_state_subgraph(sdfg, state, subgraph, name=None, full_data=False)

Turns a state subgraph into a nested SDFG. Operates in-place.

Parameters:

  • sdfg (SDFG) – The SDFG containing the state subgraph.

  • state (SDFGState) – The state containing the subgraph.

  • subgraph (SubgraphView) – Subgraph to nest.

  • name (Optional[str]) – An optional name for the nested SDFG.

  • full_data (bool) – If True, nests entire input/output data.

Return type:

NestedSDFG

Returns:

The nested SDFG node.

Raises:

  • KeyError – Some or all nodes in the subgraph are not located in this state, or the state does not belong to the given SDFG.

  • ValueError – The subgraph is contained in more than one scope.

dace.transformation.helpers.offset_map(sdfg, state, entry, dim, offset, negative=True)

Offsets a map parameter and its contents by a value.

Parameters:

  • sdfg (SDFG) – The SDFG in which the map resides.

  • state (SDFGState) – The state in which the map resides.

  • entry (MapEntry) – The map entry node.

  • dim (int) – The map dimension to offset.

  • offset (Union[Basic, SymExpr]) – The value to offset by.

  • negative (bool) – If True, offsets by -offset.

dace.transformation.helpers.permute_map(map_entry, perm)

Permutes indices of a map according to a given list of integers.

dace.transformation.helpers.reconnect_edge_through_map(state, edge, new_node, keep_src)

Reconnects an edge through a map scope, removes old edge, and returns the two new edges.

Parameters:

  • state (SDFGState) – The state in which the edge and map reside.

  • edge (MultiConnectorEdge[Memlet]) – The edge to reconnect and remove.

  • new_node (Union[EntryNode, ExitNode]) – The scope (map) entry or exit to reconnect through.

  • keep_src (bool) – If True, keeps the source of the edge intact, otherwise keeps destination of edge.

Return type:

Tuple[MultiConnectorEdge[Memlet], MultiConnectorEdge[Memlet]]

Returns:

A 2-tuple of (incoming edge, outgoing edge).

dace.transformation.helpers.redirect_edge(state, edge, new_src=None, new_dst=None, new_src_conn=None, new_dst_conn=None, new_data=None, new_memlet=None)

Redirects an edge in a state. Choose which elements to override by setting the keyword arguments.

Parameters:

  • state (SDFGState) – The SDFG state in which the edge resides.

  • edge (MultiConnectorEdge[Memlet]) – The edge to redirect.

  • new_src (Optional[Node]) – If provided, redirects the source of the new edge.

  • new_dst (Optional[Node]) – If provided, redirects the destination of the new edge.

  • new_src_conn (Optional[str]) – If provided, renames the source connector of the edge.

  • new_dst_conn (Optional[str]) – If provided, renames the destination connector of the edge.

  • new_data (Optional[str]) – If provided, changes the data on the memlet of the edge, and the entire associated memlet tree.

  • new_memlet (Optional[Memlet]) – If provided, changes only the memlet of the new edge.

Return type:

MultiConnectorEdge[Memlet]

Returns:

The new, redirected edge.

Note:

new_data and new_memlet cannot be used at the same time.

dace.transformation.helpers.replace_code_to_code_edges(sdfg)

Adds access nodes between all code->code edges in each state.

Parameters:

sdfg (SDFG) – The SDFG to process.

dace.transformation.helpers.replicate_scope(sdfg, state, scope)

Replicates a scope subgraph view within a state, reconnecting all external edges to the same nodes.

Parameters:

  • sdfg (SDFG) – The SDFG in which the subgraph scope resides.

  • state (SDFGState) – The SDFG state in which the subgraph scope resides.

  • scope (ScopeSubgraphView) – The scope subgraph to replicate.

Return type:

ScopeSubgraphView

Returns:

A reconnected replica of the scope.

dace.transformation.helpers.scope_tree_recursive(state, entry=None)

Returns a scope tree that includes scopes from nested SDFGs.

Parameters:

  • state (SDFGState) – The state that contains the root of the scope tree.

  • entry (Optional[EntryNode]) – A scope entry node to set as root, otherwise the state is the root if None is given.

Return type:

ScopeTree

dace.transformation.helpers.simplify_state(state, remove_views=False)

Returns a networkx MultiDiGraph object that contains all the access nodes and corresponding edges of an SDFG state. The removed code nodes and map scopes are replaced by edges that connect their ancestor and succesor access nodes.

Parameters:

state (SDFGState) – The input SDFG state.

Return type:

MultiDiGraph

Returns:

The MultiDiGraph object.

dace.transformation.helpers.split_interstate_edges(sdfg)

Splits all inter-state edges into edges with conditions and edges with assignments. This procedure helps in nested loop detection.

Parameters:

sdfg (SDFG) – The SDFG to split

Note:

Operates in-place on the SDFG.

Return type:

None

dace.transformation.helpers.state_fission(sdfg, subgraph, label=None)

Given a subgraph, adds a new SDFG state before the state that contains it, removes the subgraph from the original state, and connects the two states.

Parameters:

subgraph (SubgraphView) – the subgraph to remove.

Return type:

SDFGState

Returns:

the newly created SDFG state.

dace.transformation.helpers.state_fission_after(sdfg, state, node, label=None)
Return type:

SDFGState

dace.transformation.helpers.tile(sdfg, map_entry, divides_evenly, skew, **tile_sizes)

Helper function that tiles a Map scope by the given sizes, in the given order.

Parameters:

  • sdfg (SDFG) – The SDFG where the map resides.

  • map_entry (MapEntry) – The map entry node to tile.

  • divides_evenly (bool) – If True, skips pre/postamble for cases where the map dimension is not a multiplier of the tile size.

  • skew (bool) – If True, skews the tiled map to start from zero. Helps compilers improve performance in certain cases.

  • tile_sizes (Union[Basic, SymExpr]) – An ordered dictionary of the map parameter names to tile and their respective tile size (which can be symbolic expressions).

dace.transformation.helpers.unsqueeze_memlet(internal_memlet, external_memlet, preserve_minima=False, use_src_subset=False, use_dst_subset=False, internal_offset=None, external_offset=None)

Unsqueezes and offsets a memlet, as per the semantics of nested SDFGs. :type internal_memlet: Memlet :param internal_memlet: The internal memlet (inside nested SDFG) before modification. :type external_memlet: Memlet :param external_memlet: The external memlet before modification. :type preserve_minima: bool :param preserve_minima: Do not change the subset’s minimum elements. :type use_src_subset: bool :param use_src_subset: If both sides of the memlet refer to same array, prefer source subset. :type use_dst_subset: bool :param use_dst_subset: If both sides of the memlet refer to same array, prefer destination subset. :type internal_offset: Optional[Tuple[int]] :param internal_offset: The internal memlet’s data descriptor offset. :type external_offset: Optional[Tuple[int]] :param external_offset: The external memlet’s data descriptor offset. :rtype: Memlet :return: Offset Memlet to set on the resulting graph.

dace.transformation.passes.pattern_matching module

Contains functions related to pattern matching in transformations.

class dace.transformation.passes.pattern_matching.PatternApplyOnceEverywhere(*args, **kwargs)

Bases: PatternMatchAndApplyRepeated

A pass pipeline that applies all given transformations once, in every location that their pattern matched. If match condition becomes False (e.g., as a result of applying a transformation), the transformation is not applied on that location.

CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Dict[str, List[Any]]

Returns:

Some object if pass was applied, or None if nothing changed.

properties()
class dace.transformation.passes.pattern_matching.PatternMatchAndApply(*args, **kwargs)

Bases: Pass

Applies a list of pattern-matching transformations in sequence. For every given transformation, matches the first pattern in the SDFG and applies it.

CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Dict[str, List[Any]]

Returns:

Some object if pass was applied, or None if nothing changed.

depends_on()

If in the context of a Pipeline, which other Passes need to run first.

Return type:

Set[Type[Pass]]

Returns:

A set of Pass subclasses or objects that need to run prior to this Pass.

modifies()

Which elements of the SDFG (e.g., memlets, state structure) are modified by this pass, if run successfully.

Return type:

Modifies

Returns:

A Modifies set of flags of modified elements.

permissive

Whether to apply in permissive mode, i.e., apply in more cases where it may be unsafe.

print_report

Whether to show debug prints (or None to use configuration file).

progress

Whether to show progress printouts (or None to use configuration file).

properties()
should_reapply(modified)

In the context of a Pipeline, queries whether this Pass should be rerun after other passes have run and modified the SDFG.

Parameters:

modified (Modifies) – Flags specifying which elements of the SDFG were modified.

Return type:

bool

Returns:

True if this Pass should be rerun when the given elements are modified.

states

If not None, only applies transformations to the given states.

transformations

The list of transformations to apply

validate

If True, validates the SDFG after all transformations have been applied.

validate_all

If True, validates the SDFG after each transformation applies.

class dace.transformation.passes.pattern_matching.PatternMatchAndApplyRepeated(*args, **kwargs)

Bases: PatternMatchAndApply

A fixed-point pipeline that applies a list of pattern-matching transformations in repeated succession until no more transformations match. The order in which the transformations are applied is configurable (through order_by_transformation).

CATEGORY: str = 'Helper'
apply_pass(sdfg, pipeline_results)

Applies the pass to the given SDFG.

Parameters:

  • sdfg (SDFG) – The SDFG to apply the pass to.

  • pipeline_results (Dict[str, Any]) – If in the context of a Pipeline, a dictionary that is populated with prior Pass results as {Pass subclass name: returned object from pass}. If not run in a pipeline, an empty dictionary is expected.

Return type:

Dict[str, List[Any]]

Returns:

Some object if pass was applied, or None if nothing changed.

order_by_transformation

Whether or not to order by transformation.

properties()
dace.transformation.passes.pattern_matching.collapse_multigraph_to_nx(graph)

Collapses a directed multigraph into a networkx directed graph.

In the output directed graph, each node is a number, which contains itself as node_data[‘node’], while each edge contains a list of the data from the original edges as its attribute (edge_data[0…N]).

Parameters:

graph (Union[MultiDiGraph, OrderedMultiDiGraph]) – Directed multigraph object to be collapsed.

Return type:

DiGraph

Returns:

Collapsed directed graph object.

dace.transformation.passes.pattern_matching.enumerate_matches(sdfg, pattern, node_match=<function type_or_class_match>, edge_match=None)

Returns a generator of subgraphs that match the given subgraph pattern.

Parameters:

  • sdfg (SDFG) – The SDFG to search in.

  • pattern (Graph) – A subgraph to look for.

  • node_match – An optional function to use for matching nodes.

  • node_match – An optional function to use for matching edges.

Return type:

Iterator[SubgraphView]

Returns:

Yields SDFG subgraph view objects.

dace.transformation.passes.pattern_matching.get_transformation_metadata(patterns, options=None)

Collect all transformation expressions and metadata once, for use when applying transformations repeatedly.

Parameters:

  • patterns (List[Type[PatternTransformation]]) – PatternTransformation type (or list thereof) to compute.

  • options (Optional[List[Dict[str, Any]]]) – An optional list of transformation parameter dictionaries.

Return type:

Tuple[List[Tuple[Type[PatternTransformation], int, DiGraph, Callable, Dict[str, Any]]], List[Tuple[Type[PatternTransformation], int, DiGraph, Callable, Dict[str, Any]]]]

Returns:

A tuple of inter-state and single-state pattern matching transformations.

dace.transformation.passes.pattern_matching.match_patterns(sdfg, patterns, node_match=<function type_match>, edge_match=None, permissive=False, metadata=None, states=None, options=None)

Returns a generator of Transformations that match the input SDFG. Ordered by SDFG ID.

Parameters:

  • sdfg (SDFG) – The SDFG to match in.

  • patterns (Union[Type[PatternTransformation], List[Type[PatternTransformation]]]) – PatternTransformation type (or list thereof) to match.

  • node_match (Callable[[Any, Any], bool]) – Function for checking whether two nodes match.

  • edge_match (Optional[Callable[[Any, Any], bool]]) – Function for checking whether two edges match.

  • permissive (bool) – Match transformations in permissive mode.

  • metadata (Optional[Tuple[List[Tuple[Type[PatternTransformation], int, DiGraph, Callable, Dict[str, Any]]], List[Tuple[Type[PatternTransformation], int, DiGraph, Callable, Dict[str, Any]]]]]) – Transformation metadata that can be reused.

  • states (Optional[List[SDFGState]]) – If given, only tries to match single-state transformations on this list.

  • options (Optional[List[Dict[str, Any]]]) – An optional iterable of transformation parameter dictionaries.

Returns:

A list of PatternTransformation objects that match.

dace.transformation.passes.pattern_matching.type_match(graph_node, pattern_node)

Checks whether the node types of the inputs match.

Parameters:

  • graph_node – First node (in matched graph).

  • pattern_node – Second node (in pattern subgraph).

Returns:

True if the object types of the nodes match, False otherwise.

Raises:

  • TypeError – When at least one of the inputs is not a dictionary or does not have a ‘node’ attribute.

  • KeyError – When at least one of the inputs is a dictionary, but does not have a ‘node’ key.

dace.transformation.passes.pattern_matching.type_or_class_match(node_a, node_b)

Checks whether node_a is an instance of the same type as node_b, or if either node_a/node_b is a type and the other is an instance of that type. This is used in subgraph matching to allow the subgraph pattern to be either a graph of instantiated nodes, or node types.

Parameters:

  • node_a – First node.

  • node_b – Second node.

Returns:

True if the object types of the nodes match according to the description, False otherwise.

Raises:

  • TypeError – When at least one of the inputs is not a dictionary or does not have a ‘node’ attribute.

  • KeyError – When at least one of the inputs is a dictionary, but does not have a ‘node’ key.

See:

enumerate_matches

dace.transformation.optimizer module

Contains classes and functions related to optimization of the stateful dataflow graph representation.

class dace.transformation.optimizer.Optimizer(sdfg, inplace=True)

Bases: object

Implements methods for optimizing a DaCe program stateful dataflow graph representation, by matching patterns and applying transformations on it.

get_pattern_matches(permissive=False, states=None, patterns=None, sdfg=None, options=None)

Returns all possible transformations for the current SDFG.

Parameters:

  • permissive – Consider transformations in permissive mode.

  • states – An iterable of SDFG states to consider when pattern matching. If None, considers all.

  • patterns – An iterable of transformation classes to consider when matching. If None, considers all registered transformations in PatternTransformation.

  • sdfg – If not None, searches for patterns on given SDFG.

  • options – An optional iterable of transformation parameters.

Return type:

Iterator[PatternTransformation]

Returns:

List of matching PatternTransformation objects.

See:

PatternTransformation.

optimization_space()

Returns the optimization space of the current SDFG

optimize()
set_transformation_metadata(patterns, options=None)

Caches transformation metadata for a certain set of patterns to match.

class dace.transformation.optimizer.SDFGOptimizer(sdfg, inplace=True)

Bases: Optimizer

optimize()

A command-line UI for applying patterns on the SDFG.

Returns:

An optimized SDFG object

dace.transformation.testing module

class dace.transformation.testing.TransformationTester(sdfg, depth=1, validate=True, generate_code=True, compile=False, print_exception=True, halt_on_exception=False)

Bases: Optimizer

An SDFG optimizer that consecutively applies available transformations up to a fixed depth.

optimize()
dace.transformation.testing.test_transformations_hook(sdfg)

Calls a command-line interface for interactive SDFG transformations on every DaCe program call.

Parameters:

sdfg (SDFG) – The current SDFG to optimize.

Module contents