Inheritance diagram for psyclone.psyad.transformations.assignment_trans.AssignmentTrans:

[legend]

Collaboration diagram for psyclone.psyad.transformations.assignment_trans.AssignmentTrans:

[legend]

Public Member Functions
def	apply (self, node, options=None)

def	validate (self, node, options=None)

def	__str__ (self)

def	name (self)

Public Member Functions inherited from psyclone.psyad.transformations.adjoint_trans.AdjointTransformation
def	__init__ (self, active_variables)

Detailed Description

Implements a transformation to translate a Tangent-Linear
assignment to its Adjoint form.

Definition at line 56 of file assignment_trans.py.

Member Function Documentation

◆ apply()

def psyclone.psyad.transformations.assignment_trans.AssignmentTrans.apply	(	self,
		node,
		options = `None`
	)

Apply the Assignment transformation to the specified node. The node
must be a valid tangent-linear assignment. The assignment is
replaced with its adjoint version.

:param node: an Assignment node.
:type node: :py:class:`psyclone.psyir.nodes.Assignment`
:param options: a dictionary with options for transformations.
:type options: Optional[Dict[str, Any]]

Reimplemented from psyclone.psyGen.Transformation.

Definition at line 61 of file assignment_trans.py.

     def apply(self, node, options=None):
         '''Apply the Assignment transformation to the specified node. The node
         must be a valid tangent-linear assignment. The assignment is
         replaced with its adjoint version.
  
         :param node: an Assignment node.
         :type node: :py:class:`psyclone.psyir.nodes.Assignment`
         :param options: a dictionary with options for transformations.
         :type options: Optional[Dict[str, Any]]
  
         '''
         self.validate(node, options)
  
         # Split the RHS of the assignment into [-]<term> +- <term> +- ...
         rhs_terms = self._split_nodes(
             node.rhs, [BinaryOperation.Operator.ADD,
                        BinaryOperation.Operator.SUB])
  
         deferred_inc = []
         sym_maths = SymbolicMaths.get()
         for rhs_term in rhs_terms:
  
             # Find the active var in rhs_term if one exists (we may
             # find 0.0), storing it in 'active_var' and if so replace
             # it with lhs_active_var storing the modified term in
             # 'new_rhs_term'. Also determine whether this is an
             # increment, storing the result in 'increment'.
             increment = False
             active_var = None
             new_rhs_term = rhs_term.copy()
             for ref in new_rhs_term.walk(Reference):
                 if ref.symbol not in self._active_variables:
                     continue
                 active_var = ref
                 # Identify whether this reference on the RHS matches the
                 # one on the LHS - if so we have an increment.
                 if node.is_array_assignment and isinstance(ref, ArrayMixin):
                     # TODO #1537 - we can't just do `sym_maths.equal` if we
                     # have an array range because the SymbolicMaths class does
                     # not currently support them.
                     # Since we have already checked (in validate) that any
                     # references to the same symbol on the RHS have the same
                     # range, this is an increment if the symbols match.
                     if node.lhs.symbol is ref.symbol:
                         increment = True
                 else:
                     if sym_maths.equal(ref, node.lhs):
                         increment = True
                 if ref.parent:
                     ref.replace_with(node.lhs.copy())
                 else:
                     new_rhs_term = node.lhs.copy()
                 break
  
             # Work out whether the binary operation for this term is a
             # '+' or a '-' and return it in 'rhs_operator'.
             rhs_operator = BinaryOperation.Operator.ADD
             previous = rhs_term
             candidate = rhs_term.parent
             while not isinstance(candidate, Assignment):
                 if (isinstance(candidate, BinaryOperation) and
                     candidate.operator == BinaryOperation.Operator.SUB and
                         candidate.children[1] is previous):
                     # Rules: + + -> +; - - -> +; + - -> -; - + -> -
                     # If the higher level op is + then there is no
                     # change to the existing op. If it is - then
                     # we flip the op i.e. - => + and + => -.
                     if rhs_operator == BinaryOperation.Operator.SUB:
                         rhs_operator = BinaryOperation.Operator.ADD
                     else:
                         rhs_operator = BinaryOperation.Operator.SUB
                 previous = candidate
                 candidate = candidate.parent
  
             if not active_var:
                 # This is an expression without an active variable
                 # (which must be 0.0, otherwise validation will have
                 # rejected it). There is therefore nothing to output.
                 continue
  
             if increment:
                 # The output of an increment needs to be deferred as
                 # other terms must be completed before the LHS TL
                 # active variable is modified. Save the rhs term
                 # and its associated operator.
                 deferred_inc.append((new_rhs_term, rhs_operator))
             else:
                 # Output the adjoint for this term
                 rhs = BinaryOperation.create(
                     rhs_operator, active_var.copy(), new_rhs_term)
                 assignment = Assignment.create(active_var.copy(), rhs)
                 node.parent.children.insert(node.position, assignment)
  
         if (len(deferred_inc) == 1 and
                 isinstance(deferred_inc[0][0], Reference)):
             # No need to output anything as the adjoint is A = A.
             pass
         elif deferred_inc:
             # Output the adjoint for all increment terms in a single line.
             rhs, _ = deferred_inc.pop(0)
             for term, operator in deferred_inc:
                 rhs = BinaryOperation.create(operator, rhs, term)
             assignment = Assignment.create(node.lhs.copy(), rhs)
             node.parent.children.insert(node.position, assignment)
         else:
             # The assignment is not an increment. The LHS active
             # variable needs to be zero'ed.
             assignment = Assignment.create(
                 node.lhs.copy(), Literal("0.0", REAL_TYPE))
             node.parent.children.insert(node.position, assignment)
  
         # Remove the original node
         node.detach()
  

Here is the call graph for this function:

◆ name()

def psyclone.psyad.transformations.assignment_trans.AssignmentTrans.name ( self )

:returns: the name of the transformation as a string.
:rtype: str

Reimplemented from psyclone.psyGen.Transformation.

Definition at line 408 of file assignment_trans.py.

     def name(self):
         '''
         :returns: the name of the transformation as a string.
         :rtype: str
  
         '''
         return type(self).__name__
  
  
 # =============================================================================
 # Documentation utils: The list of module members that we wish AutoAPI to
 # generate documentation for (see https://psyclone-ref.readthedocs.io).

Here is the caller graph for this function:

◆ validate()

def psyclone.psyad.transformations.assignment_trans.AssignmentTrans.validate	(	self,
		node,
		options = `None`
	)

Perform various checks to ensure that it is valid to apply the
AssignmentTrans transformation to the supplied PSyIR Node.

:param node: the node that is being checked.
:type node: :py:class:`psyclone.psyir.nodes.Assignment`
:param options: a dictionary with options for transformations.
:type options: Optional[Dict[str, Any]]

:raises TransformationError: if the node argument is not an \
    Assignment.
:raises TangentLinearError: if the assignment does not conform \
    to the required tangent-linear structure.

Reimplemented from psyclone.psyGen.Transformation.

Definition at line 228 of file assignment_trans.py.

     def validate(self, node, options=None):
         '''Perform various checks to ensure that it is valid to apply the
         AssignmentTrans transformation to the supplied PSyIR Node.
  
         :param node: the node that is being checked.
         :type node: :py:class:`psyclone.psyir.nodes.Assignment`
         :param options: a dictionary with options for transformations.
         :type options: Optional[Dict[str, Any]]
  
         :raises TransformationError: if the node argument is not an \
             Assignment.
         :raises TangentLinearError: if the assignment does not conform \
             to the required tangent-linear structure.
  
         '''
         # Check node argument is an assignment node
         if not isinstance(node, Assignment):
             raise TransformationError(
                 f"Node argument in assignment transformation should be a "
                 f"PSyIR Assignment, but found '{type(node).__name__}'.")
         assign = node
  
         # If there are no active variables then return
         assignment_active_var_names = [
             var.name for var in assign.walk(Reference)
             if var.symbol in self._active_variables]
         if not assignment_active_var_names:
             # No active variables in this assignment so the assignment
             # remains unchanged.
             return
  
         # The lhs of the assignment node should be an active variable
         if assign.lhs.symbol not in self._active_variables:
             # There are active vars on RHS but not on LHS
             raise TangentLinearError(
                 f"Assignment node '{assign.debug_string()}' has the following "
                 f"active variables on its RHS '{assignment_active_var_names}' "
                 f"but its LHS '{assign.lhs.name}' is not an active variable.")
  
         # Split the RHS of the assignment into <expr> +- <expr> +- <expr>
         rhs_terms = self._split_nodes(
             assign.rhs, [BinaryOperation.Operator.ADD,
                          BinaryOperation.Operator.SUB])
  
         # Check for the special case where RHS=0.0. This is really a
         # representation of multiplying an active variable by zero but
         # this is obviously not visible in the code. Use 'float' to
         # normalise different representations of 0.
         if (len(rhs_terms) == 1 and isinstance(rhs_terms[0], Literal) and
                 float(rhs_terms[0].value) == 0.0):
             return
  
         # Check each expression term. It must be in the form
         # A */ <expr> where A is an active variable.
         for rhs_term in rhs_terms:
  
             # When searching for references to an active variable we must
             # take care to exclude those cases where they are present as
             # arguments to the L/UBOUND intrinsics (as they will be when
             # array notation is used).
             active_vars = []
             lu_bound_ops = [IntrinsicCall.Intrinsic.LBOUND,
                             IntrinsicCall.Intrinsic.UBOUND]
             for ref in rhs_term.walk(Reference):
                 if (ref.symbol in self._active_variables and
                         not (isinstance(ref.parent, IntrinsicCall) and
                              ref.parent.intrinsic in lu_bound_ops)):
                     active_vars.append(ref)
  
             if not active_vars:
                 # This term must contain an active variable
                 raise TangentLinearError(
                     f"Each non-zero term on the RHS of the assignment "
                     f"'{assign.debug_string()}' must have an active variable "
                     f"but '{rhs_term.debug_string()}' does not.")
  
             if len(active_vars) > 1:
                 # This term can only contain one active variable
                 raise TangentLinearError(
                     f"Each term on the RHS of the assignment "
                     f"'{assign.debug_string()}' must not have more than one "
                     f"active variable but '{rhs_term.debug_string()}' has "
                     f"{len(active_vars)}.")
  
             if (isinstance(rhs_term, Reference) and rhs_term.symbol
                     in self._active_variables):
                 self._array_ranges_match(assign, rhs_term)
                 # This term consists of a single active variable (with
                 # a multiplier of unity) and is therefore valid.
                 continue
  
             # Ignore unary minus if it is the parent. unary minus does
             # not cause a problem when applying the transformation but
             # does cause a problem here in the validation when
             # splitting the term into expressions.
             if (isinstance(rhs_term, UnaryOperation) and
                     rhs_term.operator ==
                     UnaryOperation.Operator.MINUS):
                 rhs_term = rhs_term.children[0]
  
             # Split the term into <expr> */ <expr> */ <expr>
             expr_terms = self._split_nodes(
                 rhs_term, [BinaryOperation.Operator.MUL,
                            BinaryOperation.Operator.DIV])
  
             # One of the expression terms must be an active variable
             # or an active variable with a preceding + or -.
             for expr_term in expr_terms:
                 check_term = expr_term
                 if (isinstance(expr_term, UnaryOperation) and
                     expr_term.operator in [UnaryOperation.Operator.PLUS,
                                            UnaryOperation.Operator.MINUS]):
                     check_term = expr_term.children[0]
                 if (isinstance(check_term, Reference) and
                         check_term.symbol in self._active_variables):
                     active_variable = check_term
                     break
             else:
                 raise TangentLinearError(
                     f"Each term on the RHS of the assignment "
                     f"'{assign.debug_string()}' must be linear with respect "
                     f"to the active variable, but found "
                     f"'{rhs_term.debug_string()}'.")
  
             # The term must be a product of an active variable with an
             # inactive expression. Check that the active variable does
             # not appear in a denominator.
             candidate = active_variable
             parent = candidate.parent
             while not isinstance(parent, Assignment):
                 # Starting with the active variable reference, look up
                 # the tree for an ancestor divide operation until
                 # reaching the assignment node.
                 if (isinstance(parent, BinaryOperation) and
                     parent.operator == BinaryOperation.Operator.DIV and
                         parent.children[1] is candidate):
                     # Found a divide and the active variable is on its RHS
                     raise TangentLinearError(
                         f"In tangent-linear code an active variable cannot "
                         f"appear as a denominator but "
                         f"'{rhs_term.debug_string()}' was found in "
                         f"'{assign.debug_string()}'.")
                 # Continue up the PSyIR tree
                 candidate = parent
                 parent = candidate.parent
  
             # If the LHS of the assignment is an array range then we only
             # support accesses of the same variable on the RHS if they have
             # the same range.
             self._array_ranges_match(assign, active_variable)
  

References psyclone.psyad.adjoint_visitor.AdjointVisitor._active_variables, psyclone.psyad.transformations.adjoint_trans.AdjointTransformation._active_variables, psyclone.psyad.transformations.assignment_trans.AssignmentTrans._array_ranges_match(), and psyclone.psyad.transformations.assignment_trans.AssignmentTrans._split_nodes().

Here is the call graph for this function:

Here is the caller graph for this function:

The documentation for this class was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/psyclone-ref/checkouts/latest/src/psyclone/psyad/transformations/assignment_trans.py

Public Member Functions

Detailed Description

Member Function Documentation

◆ apply()

◆ name()

◆ validate()