Inheritance diagram for psyclone.psyGen.CodedKern:

[legend]

Collaboration diagram for psyclone.psyGen.CodedKern:

Public Member Functions
def	__init__ (self, KernelArguments, call, parent=None, check=True)

def	get_kernel_schedule (self)

def	opencl_options (self)

def	set_opencl_options (self, options)

def	__str__ (self)

def	module_name (self)

def	dag_name (self)

def	module_inline (self)

def	module_inline (self, value)

def	node_str (self, colour=True)

def	lower_to_language_level (self)

def	incremented_arg (self)

def	ast (self)

def	rename_and_write (self)

def	modified (self)

def	modified (self, value)

Public Member Functions inherited from psyclone.psyGen.Kern
def	__init__ (self, parent, call, name, ArgumentsClass, check=True)

def	args (self)

def	reference_accesses (self, var_accesses)

def	is_reduction (self)

def	reduction_arg (self)

def	reprod_reduction (self)

def	local_reduction_name (self)

def	zero_reduction_variable (self, parent, position=None)

def	reduction_sum_loop (self, parent)

def	arg_descriptors (self)

def	arg_descriptors (self, obj)

def	arguments (self)

def	name (self)

def	name (self, value)

def	is_coloured (self)

def	iterates_over (self)

def	local_vars (self)

def	gen_code (self, parent)

Public Attributes
	arg_descriptors

	modified

	name

Detailed Description

Class representing a call to a PSyclone Kernel with a user-provided
implementation. The kernel may or may not be in-lined.

:param type KernelArguments: the API-specific sub-class of \
                             :py:class:`psyclone.psyGen.Arguments` to \
                             create.
:param call: Details of the call to this kernel in the Algorithm layer.
:type call: :py:class:`psyclone.parse.algorithm.KernelCall`.
:param parent: the parent of this Node (kernel call) in the Schedule.
:type parent: sub-class of :py:class:`psyclone.psyir.nodes.Node`.
:param bool check: whether to check for consistency between the \
    kernel metadata and the algorithm layer. Defaults to True.

Definition at line 1337 of file psyGen.py.

Member Function Documentation

◆ ast()

def psyclone.psyGen.CodedKern.ast ( self )

Generate and return the fparser2 AST of the kernel source.

:returns: fparser2 AST of the Fortran file containing this kernel.
:rtype: :py:class:`fparser.two.Fortran2003.Program`

Definition at line 1569 of file psyGen.py.

     def ast(self):
         '''
         Generate and return the fparser2 AST of the kernel source.
  
         :returns: fparser2 AST of the Fortran file containing this kernel.
         :rtype: :py:class:`fparser.two.Fortran2003.Program`
         '''
         from fparser.common.readfortran import FortranStringReader
         from fparser.two import parser
         # If we've already got the AST then just return it
         if self._fp2_ast:
             return self._fp2_ast
         # Use the fparser1 AST to generate Fortran source
         fortran = self._module_code.tofortran()
         # Create an fparser2 Fortran2008 parser
         my_parser = parser.ParserFactory().create(std="f2008")
         # Parse that Fortran using our parser
         reader = FortranStringReader(fortran)
         self._fp2_ast = my_parser(reader)
         return self._fp2_ast
  

References psyclone.psyGen.CodedKern._fp2_ast, and psyclone.psyGen.CodedKern._module_code.

Here is the caller graph for this function:

◆ dag_name()

def psyclone.psyGen.CodedKern.dag_name ( self )

:returns: the name to use in the DAG for this node.
:rtype: str

Definition at line 1445 of file psyGen.py.

     def dag_name(self):
         '''
         :returns: the name to use in the DAG for this node.
         :rtype: str
         '''
         _, position = self._find_position(self.ancestor(Routine))
         return f"kernel_{self.name}_{position}"
  

References psyclone.psyir.nodes.node.Node._find_position(), and psyclone.psyir.nodes.node.Node.ancestor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_kernel_schedule()

def psyclone.psyGen.CodedKern.get_kernel_schedule ( self )

Returns a PSyIR Schedule representing the kernel code. The Schedule
is just generated on first invocation, this allows us to retain
transformations that may subsequently be applied to the Schedule.

:returns: Schedule representing the kernel code.
:rtype: :py:class:`psyclone.psyir.nodes.KernelSchedule`

Reimplemented in psyclone.gocean1p0.GOKern, and psyclone.domain.lfric.lfric_kern.LFRicKern.

Definition at line 1377 of file psyGen.py.

     def get_kernel_schedule(self):
         '''
         Returns a PSyIR Schedule representing the kernel code. The Schedule
         is just generated on first invocation, this allows us to retain
         transformations that may subsequently be applied to the Schedule.
  
         :returns: Schedule representing the kernel code.
         :rtype: :py:class:`psyclone.psyir.nodes.KernelSchedule`
         '''
         from psyclone.psyir.frontend.fparser2 import Fparser2Reader
         if self._kern_schedule is None:
             astp = Fparser2Reader()
             self._kern_schedule = astp.generate_schedule(self.name, self.ast)
             # TODO: Validate kernel with metadata (issue #288).
         return self._kern_schedule
  

Here is the call graph for this function:

Here is the caller graph for this function:

◆ incremented_arg()

def psyclone.psyGen.CodedKern.incremented_arg ( self )

 Returns the argument that has INC access. Raises a
FieldNotFoundError if none is found.

:rtype: str
:raises FieldNotFoundError: if none is found.
:returns: a Fortran argument name.

Definition at line 1551 of file psyGen.py.

     def incremented_arg(self):
         ''' Returns the argument that has INC access. Raises a
         FieldNotFoundError if none is found.
  
         :rtype: str
         :raises FieldNotFoundError: if none is found.
         :returns: a Fortran argument name.
         '''
         for arg in self.arguments.args:
             if arg.access == AccessType.INC:
                 return arg
  
         raise FieldNotFoundError(f"Kernel {self.name} does not have an "
                                  f"argument with "
                                  f"{AccessType.INC.api_specific_name()} "
                                  f"access")
  

References psyclone.psyGen.Kern.arguments(), and psyclone.psyir.nodes.call.Call.arguments().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lower_to_language_level()

def psyclone.psyGen.CodedKern.lower_to_language_level ( self )

In-place replacement of CodedKern concept into language level
PSyIR constructs. The CodedKern is implemented as a Call to a
routine with the appropriate arguments.

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

Definition at line 1500 of file psyGen.py.

     def lower_to_language_level(self):
         '''
         In-place replacement of CodedKern concept into language level
         PSyIR constructs. The CodedKern is implemented as a Call to a
         routine with the appropriate arguments.
  
         :returns: the lowered version of this node.
         :rtype: :py:class:`psyclone.psyir.node.Node`
  
         '''
         symtab = self.ancestor(InvokeSchedule).symbol_table
  
         if not self.module_inline:
             # If it is not module inlined then make sure we generate the kernel
             # file (and rename it when necessary).
             self.rename_and_write()
             # Then find or create the imported RoutineSymbol
             try:
                 # Limit scope to this Invoke, since a kernel with the same name
                 # may have been inlined from another invoke in the same file,
                 # but we have it here marked as "not module-inlined"
                 rsymbol = symtab.lookup(self._name, scope_limit=symtab.node)
             except KeyError:
                 csymbol = symtab.find_or_create(
                         self._module_name,
                         symbol_type=ContainerSymbol)
                 rsymbol = symtab.new_symbol(
                         self._name,
                         symbol_type=RoutineSymbol,
                         # And allow shadowing in case it is also inlined with
                         # the same name by another invoke
                         shadowing=True,
                         interface=ImportInterface(csymbol))
         else:
             # If its inlined, the symbol must exist
             try:
                 rsymbol = self.scope.symbol_table.lookup(self._name)
             except KeyError as err:
                 raise GenerationError(
                     f"Cannot generate this kernel call to '{self.name}' "
                     f"because it is marked as module-inlined but no such "
                     f"subroutine exists in this module.") from err
  
         # Create Call to the rsymbol with the argument expressions as children
         # of the new node
         call_node = Call.create(rsymbol, self.arguments.psyir_expressions())
  
         # Swap itself with the appropriate Call node
         self.replace_with(call_node)
         return call_node
  

References psyclone.dynamo0p3.DynKernelArgument._module_name, psyclone.parse.algorithm.ParsedCall._module_name, psyclone.parse.algorithm.KernelCall._module_name, psyclone.psyGen.CodedKern._module_name, psyclone.psyGen.Argument._module_name, psyclone.psyir.nodes.psy_data_node.PSyDataNode._module_name, psyclone.domain.common.algorithm.psyir.AlgorithmInvokeCall._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.GridArg._name, psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._name, psyclone.dynamo0p3.DynFuncDescriptor03._name, psyclone.expression.NamedArg._name, psyclone.gocean1p0.GOKernelGridArgument._name, psyclone.gocean1p0.GOStencil._name, psyclone.nemo.NemoInvoke._name, psyclone.nemo.NemoPSy._name, psyclone.parse.algorithm.FileInfo._name, psyclone.parse.algorithm.InvokeCall._name, psyclone.parse.kernel.KernelProcedure._name, psyclone.parse.kernel.KernelType._name, psyclone.parse.module_info.ModuleInfo._name, psyclone.psyGen.PSy._name, psyclone.psyGen.Invoke._name, psyclone.psyGen.Kern._name, psyclone.psyGen.Argument._name, psyclone.psyir.nodes.container.Container._name, psyclone.psyir.nodes.routine.Routine._name, psyclone.psyir.symbols.symbol.Symbol._name, psyclone.psyir.nodes.node.Node.ancestor(), psyclone.psyGen.Kern.arguments(), psyclone.psyir.nodes.call.Call.arguments(), psyclone.psyGen.CodedKern.module_inline(), psyclone.psyGen.CodedKern.rename_and_write(), psyclone.psyir.nodes.node.Node.replace_with(), psyclone.psyir.nodes.node.Node.scope(), and psyclone.psyir.symbols.symbol_table.SymbolTable.scope().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ modified() [1/2]

def psyclone.psyGen.CodedKern.modified ( self )

:returns: Whether or not this kernel has been modified (transformed).
:rtype: bool

Definition at line 1776 of file psyGen.py.

     def modified(self):
         '''
         :returns: Whether or not this kernel has been modified (transformed).
         :rtype: bool
         '''
         return self._modified
  

References psyclone.psyGen.CodedKern._modified.

Here is the caller graph for this function:

◆ modified() [2/2]

def psyclone.psyGen.CodedKern.modified	(	self,
		value
	)

Setter for whether or not this kernel has been modified.

:param bool value: True if kernel modified, False otherwise.

Definition at line 1784 of file psyGen.py.

     def modified(self, value):
         '''
         Setter for whether or not this kernel has been modified.
  
         :param bool value: True if kernel modified, False otherwise.
         '''
         self._modified = value
  
  

References psyclone.psyGen.CodedKern._modified.

Here is the caller graph for this function:

◆ module_inline() [1/2]

def psyclone.psyGen.CodedKern.module_inline ( self )

:returns: whether or not this kernel is being module-inlined.
:rtype: bool

Definition at line 1454 of file psyGen.py.

     def module_inline(self):
         '''
         :returns: whether or not this kernel is being module-inlined.
         :rtype: bool
         '''
         return self._module_inline
  

References psyclone.psyGen.CodedKern._module_inline.

Here is the caller graph for this function:

◆ module_inline() [2/2]

def psyclone.psyGen.CodedKern.module_inline	(	self,
		value
	)

Setter for whether or not to module-inline this kernel.

:param bool value: whether or not to module-inline this kernel.

Definition at line 1462 of file psyGen.py.

     def module_inline(self, value):
         '''
         Setter for whether or not to module-inline this kernel.
  
         :param bool value: whether or not to module-inline this kernel.
         '''
         if value is not True:
             raise TypeError(
                 f"The module inline parameter only accepts the type boolean "
                 f"'True' since module-inlining is irreversible. But found:"
                 f" '{value}'.")
         # Do the same to all kernels in this invoke with the same name.
         # This is needed because gen_code/lowering would otherwise add
         # an import with the same name and shadow the module-inline routine
         # symbol.
         # TODO 1823: The transformation could have more control about this by
         # giving an option to specify if the module-inline applies to a
         # single kernel, the whole invoke or the whole algorithm.
         my_schedule = self.ancestor(InvokeSchedule)
         for kernel in my_schedule.walk(Kern):
             if kernel is self:
                 self._module_inline = value
             elif kernel.name == self.name and kernel.module_inline != value:
                 kernel.module_inline = value
  

Here is the call graph for this function:

Here is the caller graph for this function:

◆ module_name()

def psyclone.psyGen.CodedKern.module_name ( self )

:returns: The name of the Fortran module that contains this kernel
:rtype: string

Definition at line 1437 of file psyGen.py.

     def module_name(self):
         '''
         :returns: The name of the Fortran module that contains this kernel
         :rtype: string
         '''
         return self._module_name
  

References psyclone.dynamo0p3.DynKernelArgument._module_name, psyclone.parse.algorithm.ParsedCall._module_name, psyclone.parse.algorithm.KernelCall._module_name, psyclone.psyGen.CodedKern._module_name, psyclone.psyGen.Argument._module_name, and psyclone.psyir.nodes.psy_data_node.PSyDataNode._module_name.

Here is the caller graph for this function:

◆ node_str()

def psyclone.psyGen.CodedKern.node_str	(	self,
		colour = `True`
	)

 Returns the name of this node with (optional) control codes
to generate coloured output in a terminal that supports it.

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

:returns: description of this node, possibly coloured.
:rtype: str

Reimplemented from psyclone.psyGen.Kern.

Definition at line 1487 of file psyGen.py.

     def node_str(self, colour=True):
         ''' Returns the name of this node with (optional) control codes
         to generate coloured output in a terminal that supports it.
  
         :param bool colour: whether or not to include colour control codes.
  
         :returns: description of this node, possibly coloured.
         :rtype: str
         '''
         return (self.coloured_name(colour) + " " + self.name + "(" +
                 self.arguments.names + ") " + "[module_inline=" +
                 str(self._module_inline) + "]")
  

Here is the call graph for this function:

Here is the caller graph for this function:

◆ opencl_options()

def psyclone.psyGen.CodedKern.opencl_options ( self )

:returns: dictionary of OpenCL options regarding the kernel.
:rtype: dictionary

Definition at line 1394 of file psyGen.py.

     def opencl_options(self):
         '''
         :returns: dictionary of OpenCL options regarding the kernel.
         :rtype: dictionary
         '''
         return self._opencl_options
  

References psyclone.psyGen.CodedKern._opencl_options.

◆ rename_and_write()

def psyclone.psyGen.CodedKern.rename_and_write ( self )

Writes the (transformed) AST of this kernel to file and resets the
'modified' flag to False. By default (config.kernel_naming ==
"multiple"), the kernel is re-named so as to be unique within
the kernel output directory stored within the configuration
object. Alternatively, if config.kernel_naming is "single"
then no re-naming and output is performed if there is already
a transformed copy of the kernel in the output dir. (In this
case a check is performed that the transformed kernel already
present is identical to the one that we would otherwise write
to file. If this is not the case then we raise a GenerationError.)

:raises GenerationError: if config.kernel_naming == "single" and a \
                         different, transformed version of this \
                         kernel is already in the output directory.
:raises NotImplementedError: if the kernel has been transformed but \
                             is also flagged for module-inlining.

Definition at line 1607 of file psyGen.py.

     def rename_and_write(self):
         '''
         Writes the (transformed) AST of this kernel to file and resets the
         'modified' flag to False. By default (config.kernel_naming ==
         "multiple"), the kernel is re-named so as to be unique within
         the kernel output directory stored within the configuration
         object. Alternatively, if config.kernel_naming is "single"
         then no re-naming and output is performed if there is already
         a transformed copy of the kernel in the output dir. (In this
         case a check is performed that the transformed kernel already
         present is identical to the one that we would otherwise write
         to file. If this is not the case then we raise a GenerationError.)
  
         :raises GenerationError: if config.kernel_naming == "single" and a \
                                  different, transformed version of this \
                                  kernel is already in the output directory.
         :raises NotImplementedError: if the kernel has been transformed but \
                                      is also flagged for module-inlining.
  
         '''
         from psyclone.line_length import FortLineLength
  
         config = Config.get()
  
         # If this kernel has not been transformed we do nothing, also if the
         # kernel has been module-inlined, the routine already exist in the
         # PSyIR and we don't need to generate a new file with it.
         if not self.modified or self.module_inline:
             return
  
         # Remove any "_mod" if the file follows the PSyclone naming convention
         orig_mod_name = self.module_name[:]
         if orig_mod_name.lower().endswith("_mod"):
             old_base_name = orig_mod_name[:-4]
         else:
             old_base_name = orig_mod_name[:]
  
         # We could create a hash of a string built from the name of the
         # Algorithm (module), the name/position of the Invoke and the
         # index of this kernel within that Invoke. However, that creates
         # a very long name so we simply ensure that kernel names are unique
         # within the user-supplied kernel-output directory.
         name_idx = -1
         fdesc = None
         while not fdesc:
             name_idx += 1
             new_suffix = ""
  
             new_suffix += f"_{name_idx}"
             new_name = old_base_name + new_suffix + "_mod.f90"
  
             try:
                 # Atomically attempt to open the new kernel file (in case
                 # this is part of a parallel build)
                 fdesc = os.open(
                     os.path.join(config.kernel_output_dir, new_name),
                     os.O_CREAT | os.O_WRONLY | os.O_EXCL)
             except (OSError, IOError):
                 # The os.O_CREATE and os.O_EXCL flags in combination mean
                 # that open() raises an error if the file exists
                 if config.kernel_naming == "single":
                     # If the kernel-renaming scheme is such that we only ever
                     # create one copy of a transformed kernel then we're done
                     break
                 continue
  
         # Use the suffix we have determined to rename all relevant quantities
         # within the AST of the kernel code.
         self._rename_psyir(new_suffix)
  
         # Kernel is now self-consistent so unset the modified flag
         self.modified = False
  
         # If we reach this point the kernel needs to be written out into a
         # file using a PSyIR back-end. At the moment there is no way to choose
         # which back-end to use, so simply use the Fortran one (and limit the
         # line length).
         fortran_writer = FortranWriter(
             check_global_constraints=config.backend_checks_enabled)
         # Start from the root of the schedule as we want to output
         # any module information surrounding the kernel subroutine
         # as well as the subroutine itself.
         new_kern_code = fortran_writer(self.get_kernel_schedule().root)
         fll = FortLineLength()
         new_kern_code = fll.process(new_kern_code)
  
         if not fdesc:
             # If we've not got a file descriptor at this point then that's
             # because the file already exists and the kernel-naming scheme
             # ("single") means we're not creating a new one.
             # Check that what we've got is the same as what's in the file
             with open(os.path.join(config.kernel_output_dir,
                                    new_name), "r") as ffile:
                 kern_code = ffile.read()
                 if kern_code != new_kern_code:
                     raise GenerationError(
                         f"A transformed version of this Kernel "
                         f"'{self._module_name + '''.f90'''}' already exists "
                         f"in the kernel-output directory "
                         f"({config.kernel_output_dir}) but is not the "
                         f"same as the current, transformed kernel and the "
                         f"kernel-renaming scheme is set to "
                         f"'{config.kernel_naming}'. (If you wish to"
                         f" generate a new, unique kernel for every kernel "
                         f"that is transformed then use "
                         f"'--kernel-renaming multiple'.)")
         else:
             # Write the modified AST out to file
             os.write(fdesc, new_kern_code.encode())
             # Close the new kernel file
             os.close(fdesc)
  

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_opencl_options()

def psyclone.psyGen.CodedKern.set_opencl_options	(	self,
		options
	)

Validate and store a set of options associated with the Kernel to
tune the OpenCL code generation.

:param options: a set of options to tune the OpenCL code.
:type options: dictionary of <string>:<value>

Definition at line 1401 of file psyGen.py.

     def set_opencl_options(self, options):
         '''
         Validate and store a set of options associated with the Kernel to
         tune the OpenCL code generation.
  
         :param options: a set of options to tune the OpenCL code.
         :type options: dictionary of <string>:<value>
  
         '''
         valid_opencl_kernel_options = ['local_size', 'queue_number']
  
         # Validate that the options given are supported
         for key, value in options.items():
             if key in valid_opencl_kernel_options:
                 if key == "local_size":
                     if not isinstance(value, int):
                         raise TypeError(
                             "CodedKern OpenCL option 'local_size' should be "
                             "an integer.")
                 if key == "queue_number":
                     if not isinstance(value, int):
                         raise TypeError(
                             "CodedKern OpenCL option 'queue_number' should be "
                             "an integer.")
             else:
                 raise AttributeError(
                     f"CodedKern does not support the OpenCL option '{key}'. "
                     f"The supported options are: "
                     f"{valid_opencl_kernel_options}.")
  
             self._opencl_options[key] = value
  

References psyclone.domain.common.algorithm.psyir.AlgorithmInvokeCall._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata._name, psyclone.domain.gocean.kernel.psyir.GOceanKernelMetadata.GridArg._name, psyclone.domain.lfric.kernel.lfric_kernel_metadata.LFRicKernelMetadata._name, psyclone.dynamo0p3.DynFuncDescriptor03._name, psyclone.expression.NamedArg._name, psyclone.gocean1p0.GOKernelGridArgument._name, psyclone.gocean1p0.GOStencil._name, psyclone.nemo.NemoInvoke._name, psyclone.nemo.NemoPSy._name, psyclone.parse.algorithm.FileInfo._name, psyclone.parse.algorithm.InvokeCall._name, psyclone.parse.kernel.KernelProcedure._name, psyclone.parse.kernel.KernelType._name, psyclone.parse.module_info.ModuleInfo._name, psyclone.psyGen.PSy._name, psyclone.psyGen.Invoke._name, psyclone.psyGen.Kern._name, psyclone.psyGen.Argument._name, psyclone.psyir.nodes.container.Container._name, psyclone.psyir.nodes.routine.Routine._name, psyclone.psyir.symbols.symbol.Symbol._name, and psyclone.psyGen.CodedKern._opencl_options.

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

/home/docs/checkouts/readthedocs.org/user_builds/psyclone-ref/checkouts/latest/src/psyclone/psyGen.py

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ ast()

◆ dag_name()

◆ get_kernel_schedule()

◆ incremented_arg()

◆ lower_to_language_level()

◆ modified() [1/2]

◆ modified() [2/2]

◆ module_inline() [1/2]

◆ module_inline() [2/2]

◆ module_name()

◆ node_str()

◆ opencl_options()

◆ rename_and_write()

◆ set_opencl_options()