Inheritance diagram for psyclone.domain.lfric.lfric_loop.LFRicLoop:

Collaboration diagram for psyclone.domain.lfric.lfric_loop.LFRicLoop:

Public Member Functions
def	__init__ (self, loop_type="", **kwargs)

def	lower_to_language_level (self)

def	node_str (self, colour=True)

def	load (self, kern)

def	set_lower_bound (self, name, index=None)

def	set_upper_bound (self, name, index=None)

def	upper_bound_name (self)

def	upper_bound_halo_depth (self)

def	update_halo_exchanges (self)

def	create_halo_exchanges (self)

def	start_expr (self)

def	stop_expr (self)

def	gen_code (self, parent)

def	gen_mark_halos_clean_dirty (self, parent)

def	independent_iterations (self, test_all_variables=False, signatures_to_ignore=None, dep_tools=None)

Public Member Functions inherited from psyclone.domain.common.psylayer.psyloop.PSyLoop
def	__eq__ (self, other)

def	dag_name (self)

def	valid_loop_types (self)

def	loop_type (self)

def	loop_type (self, value)

def	field_space (self)

def	field_space (self, my_field_space)

def	field_name (self)

def	field (self)

def	field_name (self, my_field_name)

def	iteration_space (self)

def	iteration_space (self, it_space)

def	kernel (self)

def	kernel (self, kern)

def	__str__ (self)

def	has_inc_arg (self)

def	unique_modified_args (self, arg_type)

def	unique_fields_with_halo_reads (self)

def	args_filter (self, arg_types=None, arg_accesses=None, unique=False)

Public Attributes
	loop_type

	variable

Public Attributes inherited from psyclone.domain.common.psylayer.psyloop.PSyLoop
	loop_type

	field

	field_name

	field_space

	iteration_space

	kernel

Detailed Description

The LFRic-specific PSyLoop class. This passes the LFRic-specific
loop information to the base class so it creates the one
we require.  Creates LFRic-specific loop bounds when the code is
being generated.

:param str loop_type: the type (iteration space) of this loop.
:param kwargs: additional keyword arguments provided to the PSyIR node.
:type kwargs: unwrapped dict.

:raises InternalError: if an unrecognised loop_type is specified.

Definition at line 58 of file lfric_loop.py.

Member Function Documentation

◆ create_halo_exchanges()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.create_halo_exchanges ( self )

Add halo exchanges before this loop as required by fields within
this loop. To keep the logic simple we assume that any field
that accesses the halo will require a halo exchange and then
remove the halo exchange if this is not the case (when
previous writers perform sufficient redundant computation). It
is implemented this way as the halo exchange class determines
whether it is required or not so a halo exchange needs to
exist in order to find out. The appropriate logic is coded in
the _add_halo_exchange helper method. In some cases a new halo
exchange will replace an existing one. In this situation that
routine also removes the old one.

Definition at line 704 of file lfric_loop.py.

     def create_halo_exchanges(self):
         '''Add halo exchanges before this loop as required by fields within
         this loop. To keep the logic simple we assume that any field
         that accesses the halo will require a halo exchange and then
         remove the halo exchange if this is not the case (when
         previous writers perform sufficient redundant computation). It
         is implemented this way as the halo exchange class determines
         whether it is required or not so a halo exchange needs to
         exist in order to find out. The appropriate logic is coded in
         the _add_halo_exchange helper method. In some cases a new halo
         exchange will replace an existing one. In this situation that
         routine also removes the old one.
  
         '''
         for halo_field in self.unique_fields_with_halo_reads():
             # for each unique field in this loop that has its halo
             # read (including annexed dofs), find the previous update
             # of this field
             prev_arg_list = halo_field.backward_write_dependencies()
             if not prev_arg_list:
                 # field has no previous dependence so create new halo
                 # exchange(s) as we don't know the state of the fields
                 # halo on entry to the invoke
                 self._add_halo_exchange(halo_field)
             else:
                 # field has one or more previous dependencies
                 if len(prev_arg_list) > 1:
                     # field has more than one previous dependencies so
                     # should be a vector
                     if halo_field.vector_size <= 1:
                         raise GenerationError(
                             f"Error in create_halo_exchanges. Expecting field "
                             f"'{halo_field.name}' to be a vector as it has "
                             f"multiple previous dependencies")
                     if len(prev_arg_list) != halo_field.vector_size:
                         raise GenerationError(
                             f"Error in create_halo_exchanges. Expecting a "
                             f"dependence for each vector index for field "
                             f"'{halo_field.name}' but the number of "
                             f"dependencies is '{halo_field.vector_size}' and "
                             f"the vector size is '{len(prev_arg_list)}'.")
                     for arg in prev_arg_list:
                         # Avoid circular import
                         # pylint: disable=import-outside-toplevel
                         from psyclone.dynamo0p3 import LFRicHaloExchange
                         if not isinstance(arg.call, LFRicHaloExchange):
                             raise GenerationError(
                                 "Error in create_halo_exchanges. Expecting "
                                 "all dependent nodes to be halo exchanges")
                 prev_node = prev_arg_list[0].call
                 # Avoid circular import
                 # pylint: disable=import-outside-toplevel
                 from psyclone.dynamo0p3 import LFRicHaloExchange
                 if not isinstance(prev_node, LFRicHaloExchange):
                     # previous dependence is not a halo exchange so
                     # call the add halo exchange logic which
                     # determines whether a halo exchange is required
                     # or not
                     self._add_halo_exchange(halo_field)
  

References psyclone.domain.lfric.lfric_loop.LFRicLoop._add_halo_exchange(), psyclone.gocean1p0.GOLoop._add_halo_exchange(), and psyclone.domain.common.psylayer.psyloop.PSyLoop.unique_fields_with_halo_reads().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gen_code()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.gen_code	(	self,
		parent
	)

 Call the base class to generate the code and then add any
required halo exchanges.

:param parent: an f2pygen object that will be the parent of \
    f2pygen objects created in this method.
:type parent: :py:class:`psyclone.f2pygen.BaseGen`

Definition at line 838 of file lfric_loop.py.

     def gen_code(self, parent):
         ''' Call the base class to generate the code and then add any
         required halo exchanges.
  
         :param parent: an f2pygen object that will be the parent of \
             f2pygen objects created in this method.
         :type parent: :py:class:`psyclone.f2pygen.BaseGen`
  
  
         '''
         # pylint: disable=too-many-statements, too-many-branches
         # Check that we're not within an OpenMP parallel region if
         # we are a loop over colours.
         if self._loop_type == "colours" and self.is_openmp_parallel():
             raise GenerationError("Cannot have a loop over colours within an "
                                   "OpenMP parallel region.")
  
         super().gen_code(parent)
         # TODO #1010: gen_code of this loop calls the PSyIR lowering version,
         # but that method can not currently provide sibiling nodes because the
         # ancestor is not PSyIR, so for now we leave the remainder of the
         # gen_code logic here instead of removing the whole method.
  
         if not (Config.get().distributed_memory and
                 self._loop_type != "colour"):
             # No need to add halo exchanges so we are done.
             return
  
         # Set halo clean/dirty for all fields that are modified
         if not self.unique_modified_args("gh_field"):
             return
  
         if self.ancestor((ACCRegionDirective, OMPRegionDirective)):
             # We cannot include calls to set halos dirty/clean within OpenACC
             # or OpenMP regions. This is handled by the appropriate Directive
             # class instead.
             # TODO #1755 can this check be made more general (e.g. to include
             # Extraction regions)?
             return
  
         parent.add(CommentGen(parent, ""))
         if self._loop_type != "null":
             prev_node_name = "loop"
         else:
             prev_node_name = "kernel"
         parent.add(CommentGen(parent, f" Set halos dirty/clean for fields "
                               f"modified in the above {prev_node_name}"))
         parent.add(CommentGen(parent, ""))
  
         self.gen_mark_halos_clean_dirty(parent)
  
         parent.add(CommentGen(parent, ""))
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop._loop_type, psyclone.gocean1p0.GOLoop._loop_type, psyclone.psyir.nodes.node.Node.ancestor(), psyclone.domain.common.psylayer.psyloop.PSyLoop.gen_mark_halos_clean_dirty(), psyclone.domain.lfric.lfric_loop.LFRicLoop.gen_mark_halos_clean_dirty(), psyclone.psyir.nodes.node.Node.is_openmp_parallel(), and psyclone.domain.common.psylayer.psyloop.PSyLoop.unique_modified_args().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gen_mark_halos_clean_dirty()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.gen_mark_halos_clean_dirty	(	self,
		parent
	)

Generates the necessary code to mark halo regions for all modified
fields as clean or dirty following execution of this loop.

:param parent: the node in the f2pygen AST to which to add content.
:type parent: :py:class:`psyclone.f2pygen.BaseGen`

Reimplemented from psyclone.domain.common.psylayer.psyloop.PSyLoop.

Definition at line 891 of file lfric_loop.py.

     def gen_mark_halos_clean_dirty(self, parent):
         '''
         Generates the necessary code to mark halo regions for all modified
         fields as clean or dirty following execution of this loop.
  
         :param parent: the node in the f2pygen AST to which to add content.
         :type parent: :py:class:`psyclone.f2pygen.BaseGen`
  
         '''
         # Set halo clean/dirty for all fields that are modified
         fields = self.unique_modified_args("gh_field")
  
         sym_table = self.ancestor(InvokeSchedule).symbol_table
  
         # First set all of the halo dirty unless we are
         # subsequently going to set all of the halo clean
         for field in fields:
             # Avoid circular import
             # pylint: disable=import-outside-toplevel
             from psyclone.dynamo0p3 import HaloWriteAccess
             # The HaloWriteAccess class provides information about how the
             # supplied field is accessed within its parent loop
             hwa = HaloWriteAccess(field, sym_table)
             if not hwa.max_depth or hwa.dirty_outer:
                 # output set dirty as some of the halo will not be set to clean
                 if field.vector_size > 1:
                     # the range function below returns values from 1 to the
                     # vector size which is what we require in our Fortran code
                     for index in range(1, field.vector_size+1):
                         parent.add(CallGen(parent, name=field.proxy_name +
                                            f"({index})%set_dirty()"))
                 else:
                     parent.add(CallGen(parent, name=field.proxy_name +
                                        "%set_dirty()"))
             # Now set appropriate parts of the halo clean where
             # redundant computation has been performed.
             if hwa.literal_depth:
                 # halo access(es) is/are to a fixed depth
                 halo_depth = hwa.literal_depth
                 if hwa.dirty_outer:
                     halo_depth -= 1
                 if halo_depth > 0:
                     if field.vector_size > 1:
                         # The range function below returns values from 1 to the
                         # vector size, as required in our Fortran code.
                         for index in range(1, field.vector_size+1):
                             parent.add(CallGen(
                                 parent, name=f"{field.proxy_name}({index})%"
                                 f"set_clean({halo_depth})"))
                     else:
                         parent.add(CallGen(
                             parent, name=f"{field.proxy_name}%set_clean("
                             f"{halo_depth})"))
             elif hwa.max_depth:
                 # halo accesses(s) is/are to the full halo
                 # depth (-1 if continuous)
                 halo_depth = sym_table.lookup_with_tag(
                     "max_halo_depth_mesh").name
  
                 if hwa.dirty_outer:
                     # a continuous field iterating over cells leaves the
                     # outermost halo dirty
                     halo_depth += "-1"
                 if field.vector_size > 1:
                     # the range function below returns values from 1 to the
                     # vector size which is what we require in our Fortran code
                     for index in range(1, field.vector_size+1):
                         call = CallGen(parent,
                                        name=f"{field.proxy_name}({index})%"
                                        f"set_clean({halo_depth})")
                         parent.add(call)
                 else:
                     call = CallGen(parent, name=f"{field.proxy_name}%"
                                    f"set_clean({halo_depth})")
                     parent.add(call)
  

References psyclone.psyir.nodes.node.Node.ancestor(), and psyclone.domain.common.psylayer.psyloop.PSyLoop.unique_modified_args().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ independent_iterations()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.independent_iterations	(	self,
		test_all_variables = `False`,
		signatures_to_ignore = `None`,
		dep_tools = `None`
	)

This function is an LFRic-specific override of the default method
in the Loop class. It allows domain-specific rules to be applied when
determining whether or not loop iterations are independent.

:param bool test_all_variables: if True, it will test if all variable
    accesses are independent, otherwise it will stop after the first
    variable access is found that isn't.
:param signatures_to_ignore: list of signatures for which to skip
    the access checks.
:type signatures_to_ignore: Optional[
    List[:py:class:`psyclone.core.Signature`]]
:param dep_tools: an optional instance of DependencyTools so that the
    caller can access any diagnostic messages detailing why the loop
    iterations are not independent.
:type dep_tools: Optional[
    :py:class:`psyclone.psyir.tools.DependencyTools`]

:returns: True if the loop iterations are independent, False otherwise.
:rtype: bool

Definition at line 967 of file lfric_loop.py.

                                dep_tools=None):
         '''
         This function is an LFRic-specific override of the default method
         in the Loop class. It allows domain-specific rules to be applied when
         determining whether or not loop iterations are independent.
  
         :param bool test_all_variables: if True, it will test if all variable
             accesses are independent, otherwise it will stop after the first
             variable access is found that isn't.
         :param signatures_to_ignore: list of signatures for which to skip
             the access checks.
         :type signatures_to_ignore: Optional[
             List[:py:class:`psyclone.core.Signature`]]
         :param dep_tools: an optional instance of DependencyTools so that the
             caller can access any diagnostic messages detailing why the loop
             iterations are not independent.
         :type dep_tools: Optional[
             :py:class:`psyclone.psyir.tools.DependencyTools`]
  
         :returns: True if the loop iterations are independent, False otherwise.
         :rtype: bool
  
         '''
         # pylint: disable=import-outside-toplevel
         from psyclone.psyir.tools import DependencyTools, DTCode
         if not dep_tools:
             dtools = DependencyTools()
         else:
             dtools = dep_tools
  
         if self.loop_type in ["null", "colours"]:
             # We know we can't parallelise these loops. ("null" means there
             # is no actual loop and "colours" is the *outer* loop over the
             # different colours used - it is the inner, "colour" loop over
             # cells of a single colour which can be parallelised.)
             return False
  
         try:
             stat = dtools.can_loop_be_parallelised(
                 self, test_all_variables=test_all_variables,
                 signatures_to_ignore=signatures_to_ignore)
             if stat:
                 return True
         except (InternalError, KeyError):
             # LFRic still has symbols that don't exist in the symbol_table
             # until the gen_code() step, so the dependency analysis raises
             # errors in some cases.
             # TODO #1648 - when a transformation colours a loop we must
             # ensure "last_[halo]_cell_all_colours" is added to the symbol
             # table.
             return True
  
         # The generic DA says that this loop cannot be parallelised. However,
         # we use domain-specific information to qualify this.
         if self.loop_type == "colour":
             # This loop is either over cells of a single colour.
             # According to LFRic rules this is safe to parallelise.
             return True
  
         if self.loop_type == "dof":
             # The generic DA can't see the PSyIR of this Builtin (because it
             # hasn't been lowered to language level) so we use
             # domain-specific knowledge about its properties.
             if self.kernel.is_reduction:
                 dtools._add_message(
                     f"Builtin '{self.kernel.name}' performs a reduction",
                     DTCode.WARN_SCALAR_REDUCTION)
                 return False
             return True
  
         if self.loop_type == "":
             # We can parallelise a non-coloured loop if it only updates
             # quantities on discontinuous function spaces. If an LFRic kernel
             # updates quantities on a continuous function space then it must
             # have at least one argument with GH_INC access. Therefore, we
             # can simply check whether or not it has such an argument in order
             # to infer the continuity of the space.
             if self.has_inc_arg():
                 dtools._add_message(
                     f"Kernel '{self.kernel.name}' performs an INC update",
                     DTCode.ERROR_WRITE_WRITE_RACE)
                 return False
             return True
  
         raise InternalError(f"independent_iterations: loop of type "
                             f"'{self.loop_type}' is not supported.")
  
  
 # ---------- Documentation utils -------------------------------------------- #
 # The list of module members that we wish AutoAPI to generate
 # documentation for. (See https://psyclone-ref.readthedocs.io)

References psyclone.domain.common.psylayer.psyloop.PSyLoop.has_inc_arg(), psyclone.domain.common.psylayer.psyloop.PSyLoop.kernel, psyclone.domain.common.psylayer.psyloop.PSyLoop.loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop.loop_type, psyclone.gocean1p0.GOLoop.loop_type, and psyclone.psyir.nodes.loop.Loop.loop_type().

Here is the call graph for this function:

◆ load()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.load	(	self,
		kern
	)

Load the state of this Loop using the supplied Kernel
object. This method is provided so that we can individually
construct Loop objects for a given kernel call.

:param kern: Kernel object to use to populate state of Loop
:type kern: :py:class:`psyclone.domain.lfric.LFRicKern`

:raises GenerationError: if the field updated by the kernel has an \
    unexpected function space or if the kernel's 'operates-on' is \
    not consistent with the loop type.

Definition at line 198 of file lfric_loop.py.

     def load(self, kern):
         '''
         Load the state of this Loop using the supplied Kernel
         object. This method is provided so that we can individually
         construct Loop objects for a given kernel call.
  
         :param kern: Kernel object to use to populate state of Loop
         :type kern: :py:class:`psyclone.domain.lfric.LFRicKern`
  
         :raises GenerationError: if the field updated by the kernel has an \
             unexpected function space or if the kernel's 'operates-on' is \
             not consistent with the loop type.
  
         '''
         self._kern = kern
  
         self._field = kern.arguments.iteration_space_arg()
         self._field_name = self._field.name
         self._field_space = self._field.function_space
  
         if self.loop_type == "null" and kern.iterates_over != "domain":
             raise GenerationError(
                 f"A LFRicLoop of type 'null' can only contain a kernel that "
                 f"operates on the 'domain' but kernel '{kern.name}' operates "
                 f"on '{kern.iterates_over}'.")
         self._iteration_space = kern.iterates_over  # cell_columns etc.
  
         # Loop bounds
         self.set_lower_bound("start")
         const = LFRicConstants()
         if isinstance(kern, LFRicBuiltIn):
             # If the kernel is a built-in/pointwise operation
             # then this loop must be over DoFs
             if Config.get().api_conf("dynamo0.3").compute_annexed_dofs \
                and Config.get().distributed_memory \
                and not kern.is_reduction:
                 self.set_upper_bound("nannexed")
             else:
                 self.set_upper_bound("ndofs")
         else:
             if Config.get().distributed_memory:
                 if self._field.is_operator:
                     # We always compute operators redundantly out to the L1
                     # halo
                     self.set_upper_bound("cell_halo", index=1)
                 elif (self.field_space.orig_name in
                       const.VALID_DISCONTINUOUS_NAMES):
                     # Iterate to ncells for all discontinuous quantities,
                     # including any_discontinuous_space
                     self.set_upper_bound("ncells")
                 elif (self.field_space.orig_name in
                       const.CONTINUOUS_FUNCTION_SPACES):
                     # Must iterate out to L1 halo for continuous quantities
                     # unless the only arguments that are updated all have
                     # 'GH_WRITE' access. The only time such an access is
                     # permitted for a field on a continuous space is when the
                     # kernel is implemented such that any writes to a given
                     # shared dof are guaranteed to write the same value. There
                     # is therefore no need to iterate into the L1 halo in order
                     # to get correct values for annexed dofs.
                     if not kern.all_updates_are_writes:
                         self.set_upper_bound("cell_halo", index=1)
                     else:
                         self.set_upper_bound("ncells")
                 elif (self.field_space.orig_name in
                       const.VALID_ANY_SPACE_NAMES):
                     # We don't know whether any_space is continuous or not
                     # so we have to err on the side of caution and assume that
                     # it is. Again, if the only arguments that are updated have
                     # 'GH_WRITE' access then we can relax this condition.
                     if not kern.all_updates_are_writes:
                         self.set_upper_bound("cell_halo", index=1)
                     else:
                         self.set_upper_bound("ncells")
                 else:
                     raise GenerationError(
                         f"Unexpected function space found. Expecting one of "
                         f"{const.VALID_FUNCTION_SPACES} but found "
                         f"'{self.field_space.orig_name}'")
             else:  # sequential
                 self.set_upper_bound("ncells")
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._field, psyclone.domain.lfric.arg_index_to_metadata_index.ArgIndexToMetadataIndex._field(), psyclone.domain.lfric.lfric_loop.LFRicLoop._field, psyclone.domain.lfric.metadata_to_arguments_rules.MetadataToArgumentsRules._field(), psyclone.psyGen.HaloExchange._field, psyclone.domain.common.psylayer.psyloop.PSyLoop._field_name, psyclone.domain.lfric.lfric_loop.LFRicLoop._field_name, psyclone.domain.common.psylayer.psyloop.PSyLoop._field_space, psyclone.domain.lfric.lfric_loop.LFRicLoop._field_space, psyclone.gocean1p0.GOLoop._field_space, psyclone.domain.common.psylayer.psyloop.PSyLoop._iteration_space, psyclone.domain.lfric.lfric_loop.LFRicLoop._iteration_space, psyclone.gocean1p0.GOLoop._iteration_space, psyclone.domain.common.psylayer.psyloop.PSyLoop._kern, psyclone.domain.lfric.arg_ordering.ArgOrdering._kern, psyclone.domain.lfric.lfric_loop.LFRicLoop._kern, psyclone.domain.common.psylayer.psyloop.PSyLoop.field_space, psyclone.gocean1p0.GOLoop.field_space, psyclone.domain.common.psylayer.psyloop.PSyLoop.loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop.loop_type, psyclone.gocean1p0.GOLoop.loop_type, psyclone.psyir.nodes.loop.Loop.loop_type(), psyclone.domain.lfric.lfric_loop.LFRicLoop.set_lower_bound(), and psyclone.domain.lfric.lfric_loop.LFRicLoop.set_upper_bound().

Here is the call graph for this function:

◆ lower_to_language_level()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.lower_to_language_level ( self )

In-place replacement of DSL or high-level concepts into generic
PSyIR constructs. This function replaces a LFRicLoop with a PSyLoop
and inserts the loop boundaries into the new PSyLoop, or removes
the loop node in case of a domain kernel. Once TODO #1731 is done
(which should fix the loop boundaries, which atm rely on index of
the loop in the schedule, i.e. can change when transformations are
applied), this function can likely be removed.

:returns: the lowered version of this node.
:rtype: :py:class:`psyclone.psyir.node.Node`

Definition at line 119 of file lfric_loop.py.

     def lower_to_language_level(self):
         '''In-place replacement of DSL or high-level concepts into generic
         PSyIR constructs. This function replaces a LFRicLoop with a PSyLoop
         and inserts the loop boundaries into the new PSyLoop, or removes
         the loop node in case of a domain kernel. Once TODO #1731 is done
         (which should fix the loop boundaries, which atm rely on index of
         the loop in the schedule, i.e. can change when transformations are
         applied), this function can likely be removed.
  
         :returns: the lowered version of this node.
         :rtype: :py:class:`psyclone.psyir.node.Node`
  
         '''
         if self._loop_type != "null":
             # This is not a 'domain' loop (i.e. there is a real loop). First
             # check that there isn't any validation issues with the node.
             for child in self.loop_body.children:
                 child.validate_global_constraints()
  
             # Then generate the loop bounds, this needs to be done BEFORE
             # lowering the loop body because it needs kernel information.
             start = self.start_expr.copy()
             stop = self.stop_expr.copy()
             step = self.step_expr.copy()
  
             # Now we can lower the nodes in the loop body
             for child in self.loop_body.children:
                 child.lower_to_language_level()
  
             # Finally create the new lowered Loop and replace the domain one
             loop = Loop.create(self._variable, start, stop, step, [])
             loop.loop_body._symbol_table = \
                 self.loop_body.symbol_table.shallow_copy()
             loop.children[3] = self.loop_body.copy()
             self.replace_with(loop)
             lowered_node = loop
         else:
             # If loop_type is "null" we do not need a loop at all, just the
             # kernel in its loop_body
             for child in self.loop_body.children:
                 child.lower_to_language_level()
             # TODO #1010: This restriction can be removed when also lowering
             # the parent InvokeSchedule
             if len(self.loop_body.children) > 1:
                 raise NotImplementedError(
                     f"Lowering LFRic domain loops that produce more than one "
                     f"children is not yet supported, but found:\n "
                     f"{self.view()}")
             lowered_node = self.loop_body[0].detach()
             self.replace_with(lowered_node)
  
         return lowered_node
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop._loop_type, psyclone.gocean1p0.GOLoop._loop_type, psyclone.psyir.nodes.loop.Loop._variable, psyclone.psyir.nodes.loop.Loop.loop_body(), psyclone.psyir.nodes.while_loop.WhileLoop.loop_body(), psyclone.psyir.nodes.node.Node.replace_with(), psyclone.domain.lfric.lfric_loop.LFRicLoop.start_expr(), psyclone.psyir.nodes.loop.Loop.start_expr(), psyclone.psyir.nodes.loop.Loop.step_expr(), psyclone.domain.lfric.lfric_loop.LFRicLoop.stop_expr(), and psyclone.psyir.nodes.loop.Loop.stop_expr().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ node_str()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.node_str	(	self,
		colour = `True`
	)

 Creates a text summary of this loop node. We override this
method from the Loop class because, in Dynamo0.3, the function
space is now an object and we need to call orig_name on it. We
also include the upper loop bound as this can now be modified.

:param bool colour: whether or not to include control codes for colour.

:returns: text summary of this node, optionally with control codes \
          for colour highlighting.
:rtype: str

Reimplemented from psyclone.domain.common.psylayer.psyloop.PSyLoop.

Definition at line 172 of file lfric_loop.py.

     def node_str(self, colour=True):
         ''' Creates a text summary of this loop node. We override this
         method from the Loop class because, in Dynamo0.3, the function
         space is now an object and we need to call orig_name on it. We
         also include the upper loop bound as this can now be modified.
  
         :param bool colour: whether or not to include control codes for colour.
  
         :returns: text summary of this node, optionally with control codes \
                   for colour highlighting.
         :rtype: str
  
         '''
         if self._loop_type == "null":
             return f"{self.coloured_name(colour)}[type='null']"
  
         if self._upper_bound_halo_depth:
             upper_bound = (f"{self._upper_bound_name}"
                            f"({self._upper_bound_halo_depth})")
         else:
             upper_bound = self._upper_bound_name
         return (f"{self.coloured_name(colour)}[type='{self._loop_type}', "
                 f"field_space='{self._field_space.orig_name}', "
                 f"it_space='{self.iteration_space}', "
                 f"upper_bound='{upper_bound}']")
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop._loop_type, psyclone.gocean1p0.GOLoop._loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_halo_depth, and psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_name.

Here is the caller graph for this function:

◆ set_lower_bound()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.set_lower_bound	(	self,
		name,
		index = `None`
	)

 Set the lower bounds of this loop

Definition at line 280 of file lfric_loop.py.

     def set_lower_bound(self, name, index=None):
         ''' Set the lower bounds of this loop '''
         const = LFRicConstants()
         if name not in const.VALID_LOOP_BOUNDS_NAMES:
             raise GenerationError(
                 "The specified lower bound loop name is invalid")
         if name in ["inner"] + const.HALO_ACCESS_LOOP_BOUNDS and index < 1:
             raise GenerationError(
                 "The specified index '{index}' for this lower loop bound is "
                 "invalid")
         self._lower_bound_name = name
         self._lower_bound_index = index
  

References psyclone.domain.lfric.lfric_loop.LFRicLoop._lower_bound_index, and psyclone.domain.lfric.lfric_loop.LFRicLoop._lower_bound_name.

Here is the caller graph for this function:

◆ set_upper_bound()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.set_upper_bound	(	self,
		name,
		index = `None`
	)

Set the upper bound of this loop

:param name: A loop upper bound name. This should be a supported name.
:type name: String
:param index: An optional argument indicating the depth of halo
:type index: int

Definition at line 293 of file lfric_loop.py.

     def set_upper_bound(self, name, index=None):
         '''Set the upper bound of this loop
  
         :param name: A loop upper bound name. This should be a supported name.
         :type name: String
         :param index: An optional argument indicating the depth of halo
         :type index: int
  
         '''
         const = LFRicConstants()
         if name not in const.VALID_LOOP_BOUNDS_NAMES:
             raise GenerationError(
                 f"The specified upper loop bound name is invalid. Expected "
                 f"one of {const.VALID_LOOP_BOUNDS_NAMES} but found '{name}'")
         if name == "start":
             raise GenerationError("'start' is not a valid upper bound")
         # Only halo bounds and inner may have an index. We could just
         # test for index here and assume that index is None for other
         # types of bounds, but checking the type of bound as well is a
         # safer option.
         if name in (["inner"] + const.HALO_ACCESS_LOOP_BOUNDS) and \
            index is not None:
             if index < 1:
                 raise GenerationError(
                     f"The specified index '{index}' for this upper loop bound "
                     f"is invalid")
         self._upper_bound_name = name
         self._upper_bound_halo_depth = index
  

References psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_halo_depth, and psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_name.

Here is the caller graph for this function:

◆ start_expr()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.start_expr ( self )

:returns: the PSyIR for the lower bound of this loop.
:rtype: :py:class:`psyclone.psyir.Node`

Definition at line 765 of file lfric_loop.py.

     def start_expr(self):
         '''
         :returns: the PSyIR for the lower bound of this loop.
         :rtype: :py:class:`psyclone.psyir.Node`
  
         '''
         inv_sched = self.ancestor(Routine)
         sym_table = inv_sched.symbol_table
         loops = inv_sched.loops()
         posn = None
         for index, loop in enumerate(loops):
             if loop is self:
                 posn = index
                 break
         root_name = f"loop{posn}_start"
         lbound = sym_table.find_or_create_integer_symbol(root_name,
                                                          tag=root_name)
         self.children[0] = Reference(lbound)
         return self.children[0]
  

References psyclone.psyir.nodes.node.Node.ancestor(), psyclone.f2pygen.BaseGen.children(), psyclone.psyGen.InlinedKern.children, and psyclone.psyir.nodes.node.Node.children().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stop_expr()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.stop_expr ( self )

:returns: the PSyIR for the upper bound of this loop.
:rtype: :py:class:`psyclone.psyir.Node`

Definition at line 786 of file lfric_loop.py.

     def stop_expr(self):
         '''
         :returns: the PSyIR for the upper bound of this loop.
         :rtype: :py:class:`psyclone.psyir.Node`
  
         '''
         inv_sched = self.ancestor(Routine)
         sym_table = inv_sched.symbol_table
  
         if self._loop_type == "colour":
             # If this loop is over all cells of a given colour then we must
             # lookup the loop bound as it depends on the current colour.
             parent_loop = self.ancestor(Loop)
             colour_var = parent_loop.variable
  
             asym = self.kernel.last_cell_all_colours_symbol
             const = LFRicConstants()
  
             if self.upper_bound_name in const.HALO_ACCESS_LOOP_BOUNDS:
                 if self._upper_bound_halo_depth:
                     # TODO: #696 Add kind (precision) once the
                     # LFRicInvokeSchedule constructor has been extended to
                     # create the necessary symbols.
                     halo_depth = Literal(str(self._upper_bound_halo_depth),
                                          INTEGER_TYPE)
                 else:
                     # We need to go to the full depth of the halo.
                     root_name = "mesh"
                     if self.kernels()[0].is_intergrid:
                         root_name += f"_{self._field_name}"
                     depth_sym = sym_table.lookup_with_tag(
                         f"max_halo_depth_{root_name}")
                     halo_depth = Reference(depth_sym)
  
                 return ArrayReference.create(asym, [Reference(colour_var),
                                                     halo_depth])
             return ArrayReference.create(asym, [Reference(colour_var)])
  
         # This isn't a 'colour' loop so we have already set-up a
         # variable that holds the upper bound.
         loops = inv_sched.loops()
         posn = None
         for index, loop in enumerate(loops):
             if loop is self:
                 posn = index
                 break
         root_name = f"loop{posn}_stop"
         ubound = sym_table.find_or_create_integer_symbol(root_name,
                                                          tag=root_name)
         self.children[1] = Reference(ubound)
         return self.children[1]
  

References psyclone.domain.common.psylayer.psyloop.PSyLoop._loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop._loop_type, psyclone.gocean1p0.GOLoop._loop_type, psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_halo_depth, psyclone.psyir.nodes.node.Node.ancestor(), psyclone.f2pygen.BaseGen.children(), psyclone.psyGen.InlinedKern.children, psyclone.psyir.nodes.node.Node.children(), psyclone.domain.common.psylayer.psyloop.PSyLoop.kernel, psyclone.psyir.nodes.node.Node.kernels(), and psyclone.domain.lfric.lfric_loop.LFRicLoop.upper_bound_name().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ update_halo_exchanges()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.update_halo_exchanges ( self )

add and/or remove halo exchanges due to changes in the loops
bounds

Definition at line 675 of file lfric_loop.py.

     def update_halo_exchanges(self):
         '''add and/or remove halo exchanges due to changes in the loops
         bounds'''
         # this call adds any new halo exchanges that are
         # required. This is done by adding halo exchanges before this
         # loop for any fields in the loop that require a halo exchange
         # and don't already have one
         self.create_halo_exchanges()
         # Now remove any existing halo exchanges that are no longer
         # required. This is done by removing halo exchanges after this
         # loop where a field in this loop previously had a forward
         # dependence on a halo exchange but no longer does
         # pylint: disable=too-many-nested-blocks
         # Avoid circular import
         # pylint: disable=import-outside-toplevel
         from psyclone.dynamo0p3 import LFRicHaloExchange
         for call in self.kernels():
             for arg in call.arguments.args:
                 if arg.access in AccessType.all_write_accesses():
                     dep_arg_list = arg.forward_read_dependencies()
                     for dep_arg in dep_arg_list:
                         if isinstance(dep_arg.call, LFRicHaloExchange):
                             # found a halo exchange as a forward dependence
                             # ask the halo exchange if it is required
                             halo_exchange = dep_arg.call
                             required, _ = halo_exchange.required()
                             if not required:
                                 halo_exchange.detach()
  

References psyclone.domain.lfric.lfric_loop.LFRicLoop.create_halo_exchanges(), psyclone.gocean1p0.GOLoop.create_halo_exchanges(), and psyclone.psyir.nodes.node.Node.kernels().

Here is the call graph for this function:

◆ upper_bound_halo_depth()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.upper_bound_halo_depth ( self )

Returns the index of the upper loop bound. This is None if the upper
bound name is not in HALO_ACCESS_LOOP_BOUNDS.

:returns: the depth of the halo for a loops upper bound. If it \
    is None then a depth has not been provided. The depth value is \
    only valid when the upper-bound name is associated with a halo \
    e.g. 'cell_halo'.
:rtype: int

Definition at line 328 of file lfric_loop.py.

     def upper_bound_halo_depth(self):
         '''Returns the index of the upper loop bound. This is None if the upper
         bound name is not in HALO_ACCESS_LOOP_BOUNDS.
  
         :returns: the depth of the halo for a loops upper bound. If it \
             is None then a depth has not been provided. The depth value is \
             only valid when the upper-bound name is associated with a halo \
             e.g. 'cell_halo'.
         :rtype: int
  
         '''
         return self._upper_bound_halo_depth
  

References psyclone.domain.lfric.lfric_loop.LFRicLoop._add_field_component_halo_exchange(), psyclone.domain.common.psylayer.psyloop.PSyLoop._field_name, psyclone.domain.lfric.lfric_loop.LFRicLoop._field_name, psyclone.domain.common.psylayer.psyloop.PSyLoop._kern, psyclone.domain.lfric.arg_ordering.ArgOrdering._kern, psyclone.domain.lfric.lfric_loop.LFRicLoop._kern, psyclone.domain.lfric.lfric_loop.LFRicLoop._lower_bound_index, psyclone.domain.lfric.lfric_loop.LFRicLoop._lower_bound_name, psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_halo_depth, psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_name, psyclone.psyir.nodes.node.Node.ancestor(), psyclone.domain.common.psylayer.psyloop.PSyLoop.kernel, psyclone.f2pygen.BaseGen.parent(), psyclone.psyir.nodes.node.Node.parent(), psyclone.f2pygen.Directive.position(), psyclone.psyir.nodes.node.Node.position, and psyclone.psyir.nodes.node.Node.walk().

Here is the call graph for this function:

◆ upper_bound_name()

def psyclone.domain.lfric.lfric_loop.LFRicLoop.upper_bound_name ( self )

 Returns the name of the upper loop bound

Definition at line 323 of file lfric_loop.py.

     def upper_bound_name(self):
         ''' Returns the name of the upper loop bound '''
         return self._upper_bound_name
  

References psyclone.domain.lfric.lfric_loop.LFRicLoop._upper_bound_name.

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/domain/lfric/lfric_loop.py

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ create_halo_exchanges()

◆ gen_code()

◆ gen_mark_halos_clean_dirty()

◆ independent_iterations()

◆ load()

◆ lower_to_language_level()

◆ node_str()

◆ set_lower_bound()

◆ set_upper_bound()

◆ start_expr()

◆ stop_expr()

◆ update_halo_exchanges()

◆ upper_bound_halo_depth()

◆ upper_bound_name()