dace.transformation package¶
Subpackages¶
- dace.transformation.auto package
- dace.transformation.dataflow package
- Submodules
- dace.transformation.dataflow.copy_to_device module
- dace.transformation.dataflow.double_buffering module
- dace.transformation.dataflow.gpu_transform module
- dace.transformation.dataflow.gpu_transform_local_storage module
- dace.transformation.dataflow.local_storage module
- dace.transformation.dataflow.map_collapse module
- dace.transformation.dataflow.map_expansion module
- dace.transformation.dataflow.map_fission module
- dace.transformation.dataflow.map_for_loop module
- dace.transformation.dataflow.map_fusion module
- dace.transformation.dataflow.map_interchange module
- dace.transformation.dataflow.mapreduce module
- dace.transformation.dataflow.matrix_product_transpose module
- dace.transformation.dataflow.merge_arrays module
- dace.transformation.dataflow.mpi module
- dace.transformation.dataflow.redundant_array module
- dace.transformation.dataflow.redundant_array_copying module
- dace.transformation.dataflow.stream_transient module
- dace.transformation.dataflow.strip_mining module
- dace.transformation.dataflow.tiling module
- dace.transformation.dataflow.vectorization module
- Module contents
- dace.transformation.interstate package
- Submodules
- dace.transformation.interstate.fpga_transform_sdfg module
- dace.transformation.interstate.fpga_transform_state module
- dace.transformation.interstate.gpu_transform_sdfg module
- dace.transformation.interstate.loop_detection module
- dace.transformation.interstate.loop_peeling module
- dace.transformation.interstate.loop_unroll module
- dace.transformation.interstate.sdfg_nesting module
- dace.transformation.interstate.state_elimination module
- dace.transformation.interstate.state_fusion module
- dace.transformation.interstate.transient_reuse module
- Module contents
- Available Passes
- dace.transformation.subgraph package
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
(passes: List[dace.transformation.pass_pipeline.Pass])¶ Bases:
dace.transformation.pass_pipeline.Pipeline
A special type of Pipeline that applies its ``Pass``es in repeated succession until they all stop modifying the SDFG (i.e., by returning None).
See: Pipeline -
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Dict[str, Any]]¶ Applies the pipeline to the SDFG in repeated succession until the SDFG is no longer modified. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.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.
-
-
class
dace.transformation.pass_pipeline.
Modifies
¶ Bases:
enum.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 asMemlets | 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
¶ 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 aPipeline
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 previousPipeline
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 -
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Any]¶ Applies the pass to the given SDFG. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: Some object if pass was applied, or None if nothing changed.
-
depends_on
() → Set[Union[Type[dace.transformation.pass_pipeline.Pass], dace.transformation.pass_pipeline.Pass]]¶ If in the context of a
Pipeline
, which other Passes need to run first. :return: A set of Pass subclasses or objects that need to run prior to this Pass.
-
modifies
() → dace.transformation.pass_pipeline.Modifies¶ Which elements of the SDFG (e.g., memlets, state structure) are modified by this pass, if run successfully. :return: A
Modifies
set of flags of modified elements.
-
should_reapply
(modified: dace.transformation.pass_pipeline.Modifies) → bool¶ In the context of a
Pipeline
, queries whether this Pass should be rerun after other passes have run and modified the SDFG. :param modified: Flags specifying which elements of the SDFG were modified. :return: True if this Pass should be rerun when the given elements are modified.
-
-
class
dace.transformation.pass_pipeline.
Pipeline
(passes: List[dace.transformation.pass_pipeline.Pass])¶ Bases:
dace.transformation.pass_pipeline.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 toapply_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'])
-
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Dict[str, Any]]¶ Applies the pass to the given SDFG. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: Some object if pass was applied, or None if nothing changed.
-
depends_on
() → Set[Type[dace.transformation.pass_pipeline.Pass]]¶ If in the context of a
Pipeline
, which other Passes need to run first. :return: A set of Pass subclasses or objects that need to run prior to this Pass.
-
iterate_over_passes
() → Iterator[dace.transformation.pass_pipeline.Pass]¶ 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.
-
modifies
() → dace.transformation.pass_pipeline.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: A
Modifies
set of flags of modified elements.
-
should_reapply
(modified: dace.transformation.pass_pipeline.Modifies) → bool¶ In the context of a
Pipeline
, queries whether this Pass should be rerun after other passes have run and modified the SDFG. :param modified: Flags specifying which elements of the SDFG were modified. :return: True if this Pass should be rerun when the given elements are modified.
-
-
class
dace.transformation.pass_pipeline.
ScopePass
¶ Bases:
dace.transformation.pass_pipeline.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 -
apply
(scope: dace.sdfg.nodes.EntryNode, state: dace.sdfg.state.SDFGState, pipeline_results: Dict[str, Any]) → Optional[Any]¶ Applies this pass on the given scope. :param scope: The entry node of the scope to apply the pass to. :param state: The parent SDFG state of the given scope. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: Some object if pass was applied, or None if nothing changed.
-
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Dict[dace.sdfg.nodes.EntryNode, Optional[Any]]]¶ Applies the pass to the scopes of the given SDFG by calling
apply
on each scope entry node. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of aPipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: A dictionary of {entry node: return value}
for visited scopes with a non-None return value, or None if nothing was returned.
-
-
class
dace.transformation.pass_pipeline.
StatePass
¶ Bases:
dace.transformation.pass_pipeline.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 -
apply
(state: dace.sdfg.state.SDFGState, pipeline_results: Dict[str, Any]) → Optional[Any]¶ Applies this pass on the given state. :param state: The SDFG state to apply the pass to. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: Some object if pass was applied, or None if nothing changed.
-
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Dict[dace.sdfg.state.SDFGState, Optional[Any]]]¶ Applies the pass to states of the given SDFG by calling
apply
on each state. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of aPipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: A dictionary of {state: return value}
for visited states with a non-None return value, or None if nothing was returned.
-
-
class
dace.transformation.pass_pipeline.
VisitorPass
¶ Bases:
dace.transformation.pass_pipeline.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 aPipeline
.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)
-
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Dict[Any, Any]]¶ Visits the given SDFG recursively, calling defined
visit_*
methods for each element. :param sdfg: The SDFG to recursively visit. :param pipeline_results: If in the context of aPipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.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: Any, parent: Any, pipeline_results: Dict[str, Any]) → Any¶ A default method that is called for elements that do not have a special visitor. :param element: The element to visit. :param parent: The parent of the visited element (e.g., SDFGState for dataflow elements, SDFG for SDFGStates). :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.
-
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.
- Pattern-matching Transformations (extending
Some transformations are included in the SDFG simplification pass. In order to declare a transformation as part
of the simplification pass, it should also extend the SimplifyPass
mixin.
-
class
dace.transformation.transformation.
ExpandTransformation
(*args, **kwargs)¶ Bases:
dace.transformation.transformation.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. :param sdfg: The SDFG to apply the transformation to. :return: A transformation-defined return value, which could be used
to pass analysis data out, or nothing.
-
can_be_applied
(graph: dace.sdfg.graph.OrderedMultiDiConnectorGraph, expr_index: int, sdfg, permissive: bool = False)¶ Returns True if this transformation can be applied on the candidate matched subgraph. :param graph: SDFGState object if this transformation is
single-state, or SDFG object otherwise.Parameters: - expr_index – 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 – Whether transformation should run in permissive mode.
Returns: True if the transformation can be applied.
-
static
expansion
(node: dace.sdfg.nodes.LibraryNode, parent_state: dace.sdfg.state.SDFGState, parent_sdfg: dace.sdfg.sdfg.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: Dict[str, Any], context: Dict[str, Any] = None) → dace.transformation.transformation.ExpandTransformation¶
-
match_to_str
(graph: dace.sdfg.graph.OrderedMultiDiConnectorGraph)¶ 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) → Dict[str, Any]¶
-
-
class
dace.transformation.transformation.
MultiStateTransformation
(*args, **kwargs)¶ Bases:
dace.transformation.transformation.PatternTransformation
,abc.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.
Seealso: PatternNode Note: Some transformations are included in the SDFG simplification pass. In order to declare a transformation as part of the simplification pass, it should also extend the SimplifyPass
mixin.-
can_be_applied
(graph: dace.sdfg.sdfg.SDFG, expr_index: int, sdfg: dace.sdfg.sdfg.SDFG, permissive: bool = False) → bool¶ Returns True if this transformation can be applied on the candidate matched subgraph. :param graph: SDFG object in which the match was found. :param candidate: A mapping between node IDs returned from
PatternTransformation.expressions
and the nodes ingraph
.Parameters: - expr_index – The list index from
PatternTransformation.expressions
that was matched. - sdfg – The SDFG in which the match was found (equal to
graph
). - permissive – Whether transformation should run in permissive mode.
Returns: True if the transformation can be applied.
- expr_index – The list index from
-
classmethod
expressions
() → List[dace.sdfg.graph.SubgraphView]¶ 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
.
-
properties
()¶
-
class
dace.transformation.transformation.
PatternNode
(nodeclass: Type[T])¶ Bases:
typing.Generic
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:
dace.transformation.transformation.TransformationBase
Abstract class for pattern-matching transformations. Please extend either
SingleStateTransformation
orMultiStateTransformation
.See: SingleStateTransformation See: MultiStateTransformation Seealso: PatternNode -
annotates_memlets
() → bool¶ 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.
-
apply
(graph: Union[dace.sdfg.sdfg.SDFG, dace.sdfg.state.SDFGState], sdfg: dace.sdfg.sdfg.SDFG) → Optional[Any]¶ Applies this transformation instance on the matched pattern graph. :param sdfg: The SDFG to apply the transformation to. :return: A transformation-defined return value, which could be used
to pass analysis data out, or nothing.
-
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Any]¶ Applies the pass to the given SDFG. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: Some object if pass was applied, or None if nothing changed.
-
apply_pattern
(append: bool = True, annotate: bool = True) → Optional[Any]¶ Applies this transformation on the given SDFG, using the transformation instance to find the right SDFG object (based on SDFG ID), and applying memlet propagation as necessary. :param sdfg: The SDFG (or an SDFG in the same hierarchy) to apply the
transformation to.Parameters: append – If True, appends the transformation to the SDFG transformation history. Returns: A transformation-defined return value, which could be used to pass analysis data out, or nothing.
-
classmethod
apply_to
(sdfg: dace.sdfg.sdfg.SDFG, options: Optional[Dict[str, Any]] = None, expr_index: int = 0, verify: bool = True, annotate: bool = True, permissive: bool = False, save: bool = 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 – The SDFG to apply the transformation to.
- options – A set of parameters to use for applying the transformation.
- expr_index – The pattern expression index to try to match with.
- verify – Check that can_be_applied returns True before applying.
- annotate – Run memlet propagation after application if necessary.
- permissive – Apply transformation in permissive mode.
- save – Save transformation as part of the SDFG file. Set to False if composing transformations.
- where – A dictionary of node names (from the transformation) to nodes in the SDFG or a single state.
-
can_be_applied
(graph: Union[dace.sdfg.sdfg.SDFG, dace.sdfg.state.SDFGState], expr_index: int, sdfg: dace.sdfg.sdfg.SDFG, permissive: bool = False) → bool¶ Returns True if this transformation can be applied on the candidate matched subgraph. :param graph: SDFGState object if this transformation is
single-state, or SDFG object otherwise.Parameters: - expr_index – 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 – Whether transformation should run in permissive mode.
Returns: True if the transformation can be applied.
-
expr_index
¶ Object property of type int
-
classmethod
expressions
() → List[dace.sdfg.graph.SubgraphView]¶ 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: Dict[str, Any], context: Dict[str, Any] = None) → dace.transformation.transformation.PatternTransformation¶
-
match_to_str
(graph: Union[dace.sdfg.sdfg.SDFG, dace.sdfg.state.SDFGState]) → str¶ Returns a string representation of the pattern match on the candidate subgraph. Used when identifying matches in the console UI.
-
print_match
(sdfg: dace.sdfg.sdfg.SDFG) → str¶ Returns a string representation of the pattern match on the given SDFG. Used for printing matches in the console UI.
-
properties
()¶
-
sdfg_id
¶ Object property of type int
-
setup_match
(sdfg: dace.sdfg.sdfg.SDFG, sdfg_id: int, state_id: int, subgraph: Dict[PatternNode, int], expr_index: int, override: bool = False, options: Optional[Dict[str, Any]] = None) → None¶ Sets the transformation to a given subgraph pattern.
Parameters: - sdfg_id – A unique ID of the SDFG.
- state_id – The node ID of the SDFG state, if applicable. If transformation does not operate on a single state, the value should be -1.
- subgraph – A mapping between node IDs returned from PatternTransformation.expressions and the nodes in graph.
- expr_index – The list index from PatternTransformation.expressions that was matched.
- override – If True, accepts the subgraph dictionary as-is (mostly for internal use).
- options – 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}.
-
state_id
¶ Object property of type int
-
classmethod
subclasses_recursive
(all_subclasses: bool = False) → Set[Type[dace.transformation.transformation.PatternTransformation]]¶ Returns all subclasses of this class, including subclasses of subclasses. :param all_subclasses: Include all subclasses (e.g., including
ExpandTransformation
).
-
subgraph
¶
-
to_json
(parent=None) → Dict[str, Any]¶
-
-
class
dace.transformation.transformation.
SimplifyPass
¶ Bases:
object
Mixin that includes the given PatternTransformation in the SDFG simplification pass. This transformation will be automatically applied throughout the SDFG in non-permissive mode as the graph is constructed, or when
sdfg.simplify()
is called.
-
class
dace.transformation.transformation.
SingleStateTransformation
(*args, **kwargs)¶ Bases:
dace.transformation.transformation.PatternTransformation
,abc.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.
Seealso: PatternNode Note: Some transformations are included in the SDFG simplification pass. In order to declare a transformation as part of the simplification pass, it should also extend the SimplifyPass
mixin.-
can_be_applied
(graph: dace.sdfg.state.SDFGState, expr_index: int, sdfg: dace.sdfg.sdfg.SDFG, permissive: bool = False) → bool¶ Returns True if this transformation can be applied on the candidate matched subgraph. :param graph: SDFGState object in which the match was found. :param candidate: A mapping between node IDs returned from
PatternTransformation.expressions
and the nodes ingraph
.Parameters: - expr_index – The list index from
PatternTransformation.expressions
that was matched. - sdfg – The parent SDFG of the matched state.
- permissive – Whether transformation should run in permissive mode.
Returns: True if the transformation can be applied.
- expr_index – The list index from
-
classmethod
expressions
() → List[dace.sdfg.state.StateSubgraphView]¶ 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
.
-
properties
()¶
-
class
dace.transformation.transformation.
SubgraphTransformation
(*args, **kwargs)¶ Bases:
dace.transformation.transformation.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: dace.sdfg.sdfg.SDFG)¶ Applies the transformation on the given subgraph. :param sdfg: The SDFG that includes the subgraph.
-
apply_pass
(sdfg: dace.sdfg.sdfg.SDFG, pipeline_results: Dict[str, Any]) → Optional[Any]¶ Applies the pass to the given SDFG. :param sdfg: The SDFG to apply the pass to. :param pipeline_results: If in the context of a
Pipeline
, a dictionary that is populated with prior Passresults as{Pass subclass name: returned object from pass}
. If not run in a pipeline, an empty dictionary is expected.Returns: Some object if pass was applied, or None if nothing changed.
-
classmethod
apply_to
(sdfg: dace.sdfg.sdfg.SDFG, *where, verify: bool = 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 – The SDFG to apply the transformation to.
- where – A set of nodes in the SDFG/state, or a subgraph thereof.
- verify – Check that can_be_applied returns True before applying.
- options – A set of parameters to use for applying the transformation.
-
can_be_applied
(sdfg: dace.sdfg.sdfg.SDFG, subgraph: dace.sdfg.graph.SubgraphView) → bool¶ Tries to match the transformation on a given subgraph, returning True if this transformation can be applied. :param sdfg: The SDFG that includes the subgraph. :param subgraph: The SDFG or state subgraph to try to apply the
transformation on.Returns: True if the subgraph can be transformed, or False otherwise.
-
static
from_json
(json_obj: Dict[str, Any], context: Dict[str, Any] = None) → dace.transformation.transformation.SubgraphTransformation¶
-
get_subgraph
(sdfg: dace.sdfg.sdfg.SDFG) → dace.sdfg.graph.SubgraphView¶
-
properties
()¶
-
sdfg_id
¶ ID of SDFG to transform
-
setup_match
(subgraph: Union[Set[int], dace.sdfg.graph.SubgraphView], sdfg_id: int = None, state_id: int = None)¶ Sets the transformation to a given subgraph.
Parameters: - subgraph – A set of node (or state) IDs or a subgraph view object.
- sdfg_id – A unique ID of the SDFG.
- state_id – 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
() → Set[Type[dace.transformation.transformation.PatternTransformation]]¶ Returns all subclasses of this class, including subclasses of subclasses. :param all_subclasses: Include all subclasses (e.g., including
ExpandTransformation
).
-
subgraph
¶ Subgraph in transformation instance
-
subgraph_view
(sdfg: dace.sdfg.sdfg.SDFG) → dace.sdfg.graph.SubgraphView¶
-
to_json
(parent=None)¶
-
-
class
dace.transformation.transformation.
TransformationBase
¶ Bases:
dace.transformation.pass_pipeline.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. :return: A
Modifies
set of flags of modified elements.
-
should_reapply
(_: dace.transformation.pass_pipeline.Modifies) → bool¶ In the context of a
Pipeline
, queries whether this Pass should be rerun after other passes have run and modified the SDFG. :param modified: Flags specifying which elements of the SDFG were modified. :return: True if this Pass should be rerun when the given elements are modified.
-
-
dace.transformation.transformation.
simplification_transformations
() → List[Type[dace.transformation.transformation.PatternTransformation]]¶ Returns: List of all registered simplification transformations.
dace.transformation.helpers module¶
Transformation helper API.
-
dace.transformation.helpers.
are_subsets_contiguous
(subset_a: dace.subsets.Subset, subset_b: dace.subsets.Subset, dim: int = None) → bool¶
-
dace.transformation.helpers.
constant_symbols
(sdfg: dace.sdfg.sdfg.SDFG) → Set[str]¶ 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. :param sdfg: The input SDFG. :return: A set of symbol names that remain constant throughout the SDFG.
-
dace.transformation.helpers.
contained_in
(state: dace.sdfg.state.SDFGState, node: dace.sdfg.nodes.Node, scope: dace.sdfg.nodes.EntryNode) → bool¶ Returns true if the specified node is contained within the scope opened by the given entry node (including through nested SDFGs).
-
dace.transformation.helpers.
extract_map_dims
(sdfg: dace.sdfg.sdfg.SDFG, map_entry: dace.sdfg.nodes.MapEntry, dims: List[int]) → Tuple[dace.sdfg.nodes.MapEntry, dace.sdfg.nodes.MapEntry]¶ Helper function that extracts specific map dimensions into an outer map. :param sdfg: The SDFG where the map resides. :param map_entry: Map entry node to extract. :param dims: A list of dimension indices to extract. :return: A 2-tuple containing the extracted map and the remainder map.
-
dace.transformation.helpers.
find_contiguous_subsets
(subset_list: List[dace.subsets.Subset], dim: int = None) → Set[dace.subsets.Subset]¶ Finds the set of largest contiguous subsets in a list of subsets. :param subsets: Iterable of subset objects. :param dim: Check for contiguity only for the specified dimension. :return: A list of contiguous subsets.
-
dace.transformation.helpers.
get_internal_scopes
(state: dace.sdfg.state.SDFGState, entry: dace.sdfg.nodes.EntryNode, immediate: bool = False) → List[Tuple[dace.sdfg.state.SDFGState, dace.sdfg.nodes.EntryNode]]¶ Returns all internal scopes within a given scope, including if they reside in nested SDFGs. :param state: State in which entry node resides. :param entry: The entry node to start from. :param immediate: If True, only returns the scopes that are immediately
nested in the map.
-
dace.transformation.helpers.
get_parent_map
(state: dace.sdfg.state.SDFGState, node: Optional[dace.sdfg.nodes.Node] = None) → Optional[Tuple[dace.sdfg.nodes.EntryNode, dace.sdfg.state.SDFGState]]¶ Returns the map in which the state (and node) are contained in, or None if it is free. :param state: The state to test or parent of the node to test. :param node: The node to test (optional). :return: A tuple of (entry node, state) or None.
-
dace.transformation.helpers.
gpu_map_has_explicit_threadblocks
(state: dace.sdfg.state.SDFGState, entry: dace.sdfg.nodes.EntryNode) → bool¶ Returns True if GPU_Device map has explicit thread-block maps nested within.
-
dace.transformation.helpers.
is_symbol_unused
(sdfg: dace.sdfg.sdfg.SDFG, sym: str) → bool¶ Checks for uses of symbol in an SDFG, and if there are none returns False. :param sdfg: The SDFG to search. :param sym: The symbol to test. :return: True if the symbol can be removed, False otherwise.
-
dace.transformation.helpers.
nest_state_subgraph
(sdfg: dace.sdfg.sdfg.SDFG, state: dace.sdfg.state.SDFGState, subgraph: dace.sdfg.graph.SubgraphView, name: Optional[str] = None, full_data: bool = False) → dace.sdfg.nodes.NestedSDFG¶ Turns a state subgraph into a nested SDFG. Operates in-place. :param sdfg: The SDFG containing the state subgraph. :param state: The state containing the subgraph. :param subgraph: Subgraph to nest. :param name: An optional name for the nested SDFG. :param full_data: If True, nests entire input/output data. :return: The nested SDFG node. :raise KeyError: Some or all nodes in the subgraph are not located in
this state, or the state does not belong to the given SDFG.Raises: ValueError – The subgraph is contained in more than one scope.
-
dace.transformation.helpers.
offset_map
(sdfg: dace.sdfg.sdfg.SDFG, state: dace.sdfg.state.SDFGState, entry: dace.sdfg.nodes.MapEntry, dim: int, offset: Union[sympy.core.basic.Basic, dace.symbolic.SymExpr], negative: bool = True)¶ Offsets a map parameter and its contents by a value. :param sdfg: The SDFG in which the map resides. :param state: The state in which the map resides. :param entry: The map entry node. :param dim: The map dimension to offset. :param offset: The value to offset by. :param negative: If True, offsets by
-offset
.
-
dace.transformation.helpers.
permute_map
(map_entry: dace.sdfg.nodes.MapEntry, perm: List[int])¶ Permutes indices of a map according to a given list of integers.
-
dace.transformation.helpers.
reconnect_edge_through_map
(state: dace.sdfg.state.SDFGState, edge: dace.sdfg.graph.MultiConnectorEdge[dace.memlet.Memlet][dace.memlet.Memlet], new_node: Union[dace.sdfg.nodes.EntryNode, dace.sdfg.nodes.ExitNode], keep_src: bool) → Tuple[dace.sdfg.graph.MultiConnectorEdge[dace.memlet.Memlet][dace.memlet.Memlet], dace.sdfg.graph.MultiConnectorEdge[dace.memlet.Memlet][dace.memlet.Memlet]]¶ Reconnects an edge through a map scope, removes old edge, and returns the two new edges. :param state: The state in which the edge and map reside. :param edge: The edge to reconnect and remove. :param new_node: The scope (map) entry or exit to reconnect through. :param keep_src: If True, keeps the source of the edge intact, otherwise
keeps destination of edge.Returns: A 2-tuple of (incoming edge, outgoing edge).
-
dace.transformation.helpers.
redirect_edge
(state: dace.sdfg.state.SDFGState, edge: dace.sdfg.graph.MultiConnectorEdge[dace.memlet.Memlet][dace.memlet.Memlet], new_src: Optional[dace.sdfg.nodes.Node] = None, new_dst: Optional[dace.sdfg.nodes.Node] = None, new_src_conn: Optional[str] = None, new_dst_conn: Optional[str] = None, new_data: Optional[str] = None, new_memlet: Optional[dace.memlet.Memlet] = None) → dace.sdfg.graph.MultiConnectorEdge[dace.memlet.Memlet][dace.memlet.Memlet]¶ Redirects an edge in a state. Choose which elements to override by setting the keyword arguments. :param state: The SDFG state in which the edge resides. :param edge: The edge to redirect. :param new_src: If provided, redirects the source of the new edge. :param new_dst: If provided, redirects the destination of the new edge. :param new_src_conn: If provided, renames the source connector of the edge. :param new_dst_conn: If provided, renames the destination connector of the
edge.Parameters: - new_data – If provided, changes the data on the memlet of the edge, and the entire associated memlet tree.
- new_memlet – If provided, changes only the memlet of the new edge.
Returns: The new, redirected edge.
Note: new_data
andnew_memlet
cannot be used at the same time.
-
dace.transformation.helpers.
replicate_scope
(sdfg: dace.sdfg.sdfg.SDFG, state: dace.sdfg.state.SDFGState, scope: dace.sdfg.scope.ScopeSubgraphView) → dace.sdfg.scope.ScopeSubgraphView¶ Replicates a scope subgraph view within a state, reconnecting all external edges to the same nodes. :param sdfg: The SDFG in which the subgraph scope resides. :param state: The SDFG state in which the subgraph scope resides. :param scope: The scope subgraph to replicate. :return: A reconnected replica of the scope.
-
dace.transformation.helpers.
scope_tree_recursive
(state: dace.sdfg.state.SDFGState, entry: Optional[dace.sdfg.nodes.EntryNode] = None) → dace.sdfg.scope.ScopeTree¶ Returns a scope tree that includes scopes from nested SDFGs. :param state: The state that contains the root of the scope tree. :param entry: A scope entry node to set as root, otherwise the state is
the root if None is given.
-
dace.transformation.helpers.
simplify_state
(state: dace.sdfg.state.SDFGState, remove_views: bool = False) → networkx.classes.multidigraph.MultiDiGraph¶ 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. :param state: The input SDFG state. :return: The MultiDiGraph object.
-
dace.transformation.helpers.
split_interstate_edges
(sdfg: dace.sdfg.sdfg.SDFG) → None¶ Splits all inter-state edges into edges with conditions and edges with assignments. This procedure helps in nested loop detection. :param sdfg: The SDFG to split :note: Operates in-place on the SDFG.
-
dace.transformation.helpers.
state_fission
(sdfg: dace.sdfg.sdfg.SDFG, subgraph: dace.sdfg.graph.SubgraphView, label: Optional[str] = None) → dace.sdfg.state.SDFGState¶ 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. :param subgraph: the subgraph to remove. :return: the newly created SDFG state.
-
dace.transformation.helpers.
tile
(sdfg: dace.sdfg.sdfg.SDFG, map_entry: dace.sdfg.nodes.MapEntry, divides_evenly: bool, skew: bool, **tile_sizes)¶ Helper function that tiles a Map scope by the given sizes, in the given order. :param sdfg: The SDFG where the map resides. :param map_entry: The map entry node to tile. :param divides_evenly: If True, skips pre/postamble for cases
where the map dimension is not a multiplier of the tile size.Parameters: - skew – If True, skews the tiled map to start from zero. Helps compilers improve performance in certain cases.
- tile_sizes – 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: dace.memlet.Memlet, external_memlet: dace.memlet.Memlet, preserve_minima: bool = False, use_src_subset: bool = False, use_dst_subset: bool = False) → dace.memlet.Memlet¶ Unsqueezes and offsets a memlet, as per the semantics of nested SDFGs. :param internal_memlet: The internal memlet (inside nested SDFG)
before modification.Parameters: - external_memlet – The external memlet before modification.
- preserve_minima – Do not change the subset’s minimum elements.
- use_src_subset – If both sides of the memlet refer to same array, prefer source subset.
- use_dst_subset – If both sides of the memlet refer to same array, prefer destination subset.
Returns: Offset Memlet to set on the resulting graph.
dace.transformation.pattern_matching module¶
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) → Iterator[dace.transformation.transformation.PatternTransformation]¶ Returns all possible transformations for the current SDFG. :param permissive: Consider transformations in permissive mode. :param states: An iterable of SDFG states to consider when pattern
matching. If None, considers all.Parameters: - 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.
Returns: List of matching
PatternTransformation
objects.See: PatternTransformation.
- patterns – An iterable of transformation classes to consider
when matching. If None, considers all registered
transformations in
-
optimization_space
()¶ Returns the optimization space of the current SDFG
-
optimize
()¶
-
set_transformation_metadata
(patterns: List[Type[dace.transformation.transformation.PatternTransformation]], options: Optional[List[Dict[str, Any]]] = None)¶ Caches transformation metadata for a certain set of patterns to match.
-
-
class
dace.transformation.optimizer.
SDFGOptimizer
(sdfg, inplace=True)¶ Bases:
dace.transformation.optimizer.Optimizer
-
optimize
()¶ A command-line UI for applying patterns on the SDFG. :return: An optimized SDFG object
-
dace.transformation.testing module¶
-
class
dace.transformation.testing.
TransformationTester
(sdfg: dace.sdfg.sdfg.SDFG, depth=1, validate=True, generate_code=True, compile=False, print_exception=True, halt_on_exception=False)¶ Bases:
dace.transformation.optimizer.Optimizer
An SDFG optimizer that consecutively applies available transformations up to a fixed depth.
-
optimize
()¶
-