psyclone.parse.algorithm.Parser Class Reference

Public Member Functions
def	__init__ (self, api="", invoke_name="invoke", kernel_paths=None, line_length=False)
def	parse (self, alg_filename)
def	invoke_info (self, alg_parse_tree)
def	create_invoke_call (self, statement)
def	create_kernel_call (self, argument)
def	create_builtin_kernel_call (self, kernel_name, args)
def	create_coded_kernel_call (self, kernel_name, args)
def	update_arg_to_module_map (self, statement)
def	check_invoke_label (self, argument)

Detailed Description

Supports the parsing of PSyclone conformant algorithm code within a
file and extraction of relevant information for any 'invoke' calls
contained within the code.

:param str api: the PSyclone API to use when parsing the code.
:param str invoke_name: the expected name of the invocation calls in the \
    algorithm code.
:param kernel_paths: the paths to search for kernel source files \
    (if different from the location of the algorithm source). \
    Defaults to None.
:type kernel_paths: list of str or NoneType
:param bool line_length: a logical flag specifying whether we care \
    about line lengths being longer than 132 characters. If so, \
    the input (algorithm and kernel) code is checked to make sure \
    that it conforms and an error raised if not. The default is \
    False.

For example:

>>> from psyclone.parse.algorithm import Parser
>>> parser = Parser(api="gocean1.0")
>>> ast, info = parser.parse(SOURCE_FILE)

Definition at line 114 of file algorithm.py.

Member Function Documentation

check_invoke_label()

def psyclone.parse.algorithm.Parser.check_invoke_label	(		self,
			argument
	)

Takes the parse tree of an invoke argument containing an invoke
label. Raises an exception if this label has already been used
by another invoke in the same algorithm code. If all is well
it returns the label as a string.

:param argument: Parse tree of an invoke argument. This \
should contain a "name=xxx" argument.
:type argument: :py:class:`fparser.two.Actual_Arg_Spec`
:returns: the label as a string.
:rtype: str
:raises ParseError: if this label has already been used by \
another invoke in this algorithm code.

Definition at line 497 of file algorithm.py.

    def check_invoke_label(self, argument):
        '''Takes the parse tree of an invoke argument containing an invoke
        label. Raises an exception if this label has already been used
        by another invoke in the same algorithm code. If all is well
        it returns the label as a string.
 
        :param argument: Parse tree of an invoke argument. This \
        should contain a "name=xxx" argument.
        :type argument: :py:class:`fparser.two.Actual_Arg_Spec`
        :returns: the label as a string.
        :rtype: str
        :raises ParseError: if this label has already been used by \
        another invoke in this algorithm code.
 
        '''
        invoke_label = get_invoke_label(argument, self._alg_filename)
        if invoke_label in self._unique_invoke_labels:
            raise ParseError(
                f"Found multiple named invoke()'s with the same "
                f"label ('{invoke_label}') when parsing {self._alg_filename}")
        self._unique_invoke_labels.append(invoke_label)
        return invoke_label
 
# pylint: enable=too-many-arguments
# pylint: enable=too-many-instance-attributes
 
# Section 2: Support functions
 
 

References psyclone.parse.algorithm.Parser._alg_filename, and psyclone.parse.algorithm.Parser._unique_invoke_labels.

Here is the caller graph for this function:

create_builtin_kernel_call()

def psyclone.parse.algorithm.Parser.create_builtin_kernel_call	(		self,
			kernel_name,
			args
	)

Takes the builtin kernel name and a list of Arg objects which
capture information about the builtin call arguments and
returns a BuiltinCall instance with content specific to the
particular API (as specified in self._api).

:param str kernel_name: the name of the builtin kernel being \
called
:param args: a list of 'Arg' instances containing the required \
information for the arguments being passed from the algorithm \
layer. The list order is the same as the argument order.
:type arg: list of :py:class:`psyclone.parse.algorithm.Arg`
:returns: a BuiltInCall instance with information specific to \
the API.
:rtype: :py:class:`psyclone.parse.algorithm.BuiltInCall`
:raises ParseError: if the builtin is specified in a use \
statement in the algorithm layer

Definition at line 401 of file algorithm.py.

    def create_builtin_kernel_call(self, kernel_name, args):
        '''Takes the builtin kernel name and a list of Arg objects which
        capture information about the builtin call arguments and
        returns a BuiltinCall instance with content specific to the
        particular API (as specified in self._api).
 
        :param str kernel_name: the name of the builtin kernel being \
        called
        :param args: a list of 'Arg' instances containing the required \
        information for the arguments being passed from the algorithm \
        layer. The list order is the same as the argument order.
        :type arg: list of :py:class:`psyclone.parse.algorithm.Arg`
        :returns: a BuiltInCall instance with information specific to \
        the API.
        :rtype: :py:class:`psyclone.parse.algorithm.BuiltInCall`
        :raises ParseError: if the builtin is specified in a use \
        statement in the algorithm layer
 
        '''
        if kernel_name.lower() in self._arg_name_to_module_name:
            raise ParseError(
                f"A built-in cannot be named in a use statement but "
                f"'{kernel_name}' is used from module "
                f"'{self._arg_name_to_module_name[kernel_name.lower()]}' in "
                f"file {self._alg_filename}")
 
        return BuiltInCall(BuiltInKernelTypeFactory(api=self._api).create(
            self._builtin_name_map.keys(), self._builtin_defs_file,
            name=kernel_name.lower()), args)
 

References psyclone.configuration.Config._api, psyclone.parse.algorithm.Parser._api, psyclone.parse.algorithm.Parser._arg_name_to_module_name, and psyclone.parse.algorithm.Parser._builtin_defs_file.

Here is the caller graph for this function:

create_coded_kernel_call()

def psyclone.parse.algorithm.Parser.create_coded_kernel_call	(		self,
			kernel_name,
			args
	)

Takes a coded kernel name and a list of Arg objects which
capture information about the coded call arguments and
returns a KernelCall instance with content specific to the
particular API (as specified in self._api).

:param str kernel_name: the name of the coded kernel being \
called
:param args: a list of 'Arg' instances containing the required \
information for the arguments being passed from the algorithm \
layer. The list order is the same as the argument order.
:type arg: list of :py:class:`psyclone.parse.algorithm.Arg`
:returns: a KernelCall instance with information specific to \
the API.
:rtype: :py:class:`psyclone.parse.algorithm.KernelCall`
:raises ParseError: if the kernel is not specified in a use \
statement in the algorithm layer

Definition at line 431 of file algorithm.py.

    def create_coded_kernel_call(self, kernel_name, args):
        '''Takes a coded kernel name and a list of Arg objects which
        capture information about the coded call arguments and
        returns a KernelCall instance with content specific to the
        particular API (as specified in self._api).
 
        :param str kernel_name: the name of the coded kernel being \
        called
        :param args: a list of 'Arg' instances containing the required \
        information for the arguments being passed from the algorithm \
        layer. The list order is the same as the argument order.
        :type arg: list of :py:class:`psyclone.parse.algorithm.Arg`
        :returns: a KernelCall instance with information specific to \
        the API.
        :rtype: :py:class:`psyclone.parse.algorithm.KernelCall`
        :raises ParseError: if the kernel is not specified in a use \
        statement in the algorithm layer
 
        '''
        try:
            module_name = self._arg_name_to_module_name[kernel_name.lower()]
        except KeyError as info:
            message = (
                f"kernel call '{kernel_name.lower()}' must either be named in "
                f"a use statement (found "
                f"{list(self._arg_name_to_module_name.values())}) or be a "
                f"recognised built-in (one of "
                f"'{list(self._builtin_name_map.keys())}' for "
                f"this API)")
            raise ParseError(message) from info
 
        modast = get_kernel_ast(module_name, self._alg_filename,
                                self._kernel_paths, self._line_length)
        return KernelCall(module_name,
                          KernelTypeFactory(api=self._api).create(
                              modast, name=kernel_name), args)
 

References psyclone.parse.algorithm.Parser._alg_filename, psyclone.configuration.Config._api, psyclone.parse.algorithm.Parser._api, psyclone.parse.algorithm.Parser._arg_name_to_module_name, psyclone.parse.algorithm.Parser._kernel_paths, psyclone.line_length.FortLineLength._line_length, and psyclone.parse.algorithm.Parser._line_length.

Here is the caller graph for this function:

create_invoke_call()

def psyclone.parse.algorithm.Parser.create_invoke_call	(		self,
			statement
	)

Takes the part of a parse tree containing an invoke call and
returns an InvokeCall object which captures the required
information about the invoke.

:param statement: Parse tree of the invoke call.
:type statement: :py:class:`fparser.two.Fortran2003.Call_Stmt`
:returns: An InvokeCall object which contains relevant \
information about the invoke call.
:rtype: :py:class:`psyclone.parse.algorithm.InvokeCall`
:raises ParseError: if more than one invoke argument contains \
'name=xxx'.
:raises ParseError: if an unknown or unsupported invoke \
argument is found.

Definition at line 323 of file algorithm.py.

    def create_invoke_call(self, statement):
        '''Takes the part of a parse tree containing an invoke call and
        returns an InvokeCall object which captures the required
        information about the invoke.
 
        :param statement: Parse tree of the invoke call.
        :type statement: :py:class:`fparser.two.Fortran2003.Call_Stmt`
        :returns: An InvokeCall object which contains relevant \
        information about the invoke call.
        :rtype: :py:class:`psyclone.parse.algorithm.InvokeCall`
        :raises ParseError: if more than one invoke argument contains \
        'name=xxx'.
        :raises ParseError: if an unknown or unsupported invoke \
        argument is found.
 
        '''
        # Extract argument list.
        argument_list = statement.items[1].items
 
        invoke_label = None
        kernel_calls = []
 
        for argument in argument_list:
 
            if isinstance(argument, Actual_Arg_Spec):
                # This should be the invoke label.
                if invoke_label:
                    raise ParseError(
                        f"algorithm.py:Parser():create_invoke_call: An invoke "
                        f"must contain one or zero 'name=xxx' arguments but "
                        f"found more than one in: {statement} in file "
                        f"{self._alg_filename}")
                invoke_label = self.check_invoke_label(argument)
 
            elif isinstance(
                    argument, (Data_Ref, Part_Ref, Structure_Constructor)):
                # This should be a kernel call.
                kernel_call = self.create_kernel_call(argument)
                kernel_calls.append(kernel_call)
 
            else:
                # Unknown and/or unsupported argument type
                raise ParseError(
                    f"algorithm.py:Parser():create_invoke_call: Expecting "
                    f"argument to be of the form 'name=xxx' or a Kernel call "
                    f"but found '{argument}' in file '{self._alg_filename}'.")
 
        return InvokeCall(kernel_calls, name=invoke_label)
 

References psyclone.parse.algorithm.Parser.check_invoke_label(), and psyclone.parse.algorithm.Parser.create_kernel_call().

Here is the call graph for this function:

Here is the caller graph for this function:

create_kernel_call()

def psyclone.parse.algorithm.Parser.create_kernel_call	(		self,
			argument
	)

Takes the parse tree of an invoke argument containing a
reference to a kernel or a builtin and returns the kernel or
builtin object respectively which contains the required
information.

:param argument: Parse tree of an invoke argument. This \
    should contain a kernel name and associated arguments.
:type argument: :py:class:`fparser.two.Fortran2003.Part_Ref` or \
    :py:class:`fparser.two.Fortran2003.Structure_Constructor`

:returns: A builtin or coded kernel call object which contains \
    relevant information about the Kernel.
:rtype: :py:class:`psyclone.parse.algorithm.KernelCall` or \
    :py:class:`psyclone.parse.algorithm.BuiltInCall`

Definition at line 372 of file algorithm.py.

    def create_kernel_call(self, argument):
        '''Takes the parse tree of an invoke argument containing a
        reference to a kernel or a builtin and returns the kernel or
        builtin object respectively which contains the required
        information.
 
        :param argument: Parse tree of an invoke argument. This \
            should contain a kernel name and associated arguments.
        :type argument: :py:class:`fparser.two.Fortran2003.Part_Ref` or \
            :py:class:`fparser.two.Fortran2003.Structure_Constructor`
 
        :returns: A builtin or coded kernel call object which contains \
            relevant information about the Kernel.
        :rtype: :py:class:`psyclone.parse.algorithm.KernelCall` or \
            :py:class:`psyclone.parse.algorithm.BuiltInCall`
 
        '''
        kernel_name, args = get_kernel(argument, self._alg_filename,
                                       self._arg_type_defns)
        if kernel_name.lower() in self._builtin_name_map:
            # This is a builtin kernel
            kernel_call = self.create_builtin_kernel_call(
                kernel_name, args)
        else:
            # This is a coded kernel
            kernel_call = self.create_coded_kernel_call(
                kernel_name, args)
        return kernel_call
 

References psyclone.parse.algorithm.Parser._alg_filename, psyclone.parse.algorithm.Parser._arg_type_defns, psyclone.parse.algorithm.Parser.create_builtin_kernel_call(), and psyclone.parse.algorithm.Parser.create_coded_kernel_call().

Here is the call graph for this function:

Here is the caller graph for this function:

invoke_info()

def psyclone.parse.algorithm.Parser.invoke_info	(		self,
			alg_parse_tree
	)

Takes an fparser2 representation of a PSyclone-conformant algorithm
code as input and returns an object containing information
about the 'invoke' calls in the algorithm file and any
associated kernels within the invoke calls. Also captures the
type and precision of every variable declaration within the
parse tree.

:param alg_parse_tree: the fparser2 representation of the \
    algorithm code.
:type: :py:class:`fparser.two.Fortran2003.Program`

:returns: an object holding details of the algorithm \
    code and the invokes found within it.
:rtype: :py:class:`psyclone.parse.FileInfo`

:raises ParseError: if a program, module, subroutine or \
    function is not found in the fparser2 tree.
:raises InternalError: if the fparser2 tree representing the \
    type declaration statements is not in the expected form.
:raises NotImplementedError: if the algorithm code contains \
    two different datatypes with the same name.

Definition at line 207 of file algorithm.py.

    def invoke_info(self, alg_parse_tree):
        '''Takes an fparser2 representation of a PSyclone-conformant algorithm
        code as input and returns an object containing information
        about the 'invoke' calls in the algorithm file and any
        associated kernels within the invoke calls. Also captures the
        type and precision of every variable declaration within the
        parse tree.
 
        :param alg_parse_tree: the fparser2 representation of the \
            algorithm code.
        :type: :py:class:`fparser.two.Fortran2003.Program`
 
        :returns: an object holding details of the algorithm \
            code and the invokes found within it.
        :rtype: :py:class:`psyclone.parse.FileInfo`
 
        :raises ParseError: if a program, module, subroutine or \
            function is not found in the fparser2 tree.
        :raises InternalError: if the fparser2 tree representing the \
            type declaration statements is not in the expected form.
        :raises NotImplementedError: if the algorithm code contains \
            two different datatypes with the same name.
 
        '''
        # Find the first program, module, subroutine or function in the
        # parse tree. The assumption here is that the first is the one
        # that is required. See issue #307.
        container_name = None
        for child in alg_parse_tree.content:
            if isinstance(child, (Main_Program, Module, Subroutine_Subprogram,
                                  Function_Subprogram)):
                container_name = str(child.content[0].items[1])
                break
 
        if not container_name:
            # Nothing relevant found.
            raise ParseError(
                "algorithm.py:parser:parse: Program, module, function or "
                "subroutine not found in fparser2 parse tree.")
 
        self._unique_invoke_labels = []
        self._arg_name_to_module_name = OrderedDict()
        # Dict holding a 2-tuple consisting of type and precision
        # information for each variable declared in the algorithm
        # file, indexed by variable name.
        self._arg_type_defns = {}
        invoke_calls = []
 
        # Find all invoke calls and capture information about
        # them. Also find information about use statements and find
        # all declarations within the supplied parse
        # tree. Declarations will include the definitions of any
        # components of derived types that are defined within the
        # code.
        for statement in walk(alg_parse_tree.content,
                              types=(Type_Declaration_Stmt,
                                     Data_Component_Def_Stmt,
                                     Use_Stmt, Call_Stmt)):
            if isinstance(statement,
                          (Type_Declaration_Stmt, Data_Component_Def_Stmt)):
                # Capture datatype information for the variable
                spec = statement.children[0]
                if isinstance(spec, Declaration_Type_Spec):
                    # This is a type declaration
                    my_type = spec.children[1].string.lower()
                    my_precision = None
                elif isinstance(spec, Intrinsic_Type_Spec):
                    # This is an intrinsic declaration
                    my_type = spec.children[0].lower()
                    my_precision = None
                    if isinstance(spec.children[1], Kind_Selector):
                        my_precision = \
                            spec.children[1].children[1].string.lower()
                else:
                    raise InternalError(
                        f"Expected first child of Type_Declaration_Stmt or "
                        f"Data_Component_Def_Stmt to be Declaration_Type_Spec "
                        f"or Intrinsic_Type_Spec but found "
                        f"'{type(spec).__name__}'")
                for decl in walk(statement.children[2], (
                        Entity_Decl, Component_Decl)):
                    # Determine the variables names. Note that if a
                    # variable declaration is a component of a derived
                    # type, its name is stored 'as is'. This means
                    # that e.g. real :: a will clash with a
                    # derived-type definition if the latter has a
                    # component named 'a' and their datatypes differ.
                    my_var_name = decl.children[0].string.lower()
                    if my_var_name in self._arg_type_defns and (
                            self._arg_type_defns[my_var_name][0] != my_type or
                            self._arg_type_defns[my_var_name][1] !=
                            my_precision):
                        raise NotImplementedError(
                            f"The same symbol '{my_var_name}' is used for "
                            f"different datatypes, "
                            f"'{self._arg_type_defns[my_var_name][0]}, "
                            f"{self._arg_type_defns[my_var_name][1]}' and "
                            f"'{my_type}, {my_precision}'. This is not "
                            f"currently supported.")
                    # Store the variable name and information about its type
                    self._arg_type_defns[my_var_name] = (my_type, my_precision)
 
            if isinstance(statement, Use_Stmt):
                # found a Fortran use statement
                self.update_arg_to_module_map(statement)
 
            if isinstance(statement, Call_Stmt):
                # found a Fortran call statement
                call_name = str(statement.items[0])
                if call_name.lower() == self._invoke_name.lower():
                    # The call statement is an invoke
                    invoke_call = self.create_invoke_call(statement)
                    invoke_calls.append(invoke_call)
 
        return FileInfo(container_name, invoke_calls)
 

References psyclone.parse.algorithm.Parser._arg_name_to_module_name, psyclone.parse.algorithm.Parser._arg_type_defns, psyclone.alg_gen.Alg._invoke_name, psyclone.parse.algorithm.Parser._invoke_name, psyclone.parse.algorithm.Parser._unique_invoke_labels, psyclone.parse.algorithm.Parser.create_invoke_call(), and psyclone.parse.algorithm.Parser.update_arg_to_module_map().

Here is the call graph for this function:

Here is the caller graph for this function:

parse()

def psyclone.parse.algorithm.Parser.parse	(		self,
			alg_filename
	)

Takes a PSyclone conformant algorithm file as input and outputs a
parse tree of the code contained therein and an object
containing information about the 'invoke' calls in the
algorithm file and any associated kernels within the invoke
calls. If the NEMO API is being used then the parsed code is
returned without any additional information about the code.

:param str alg_filename: The file containing the algorithm code.

:returns: 2-tuple consisting of the fparser2 parse tree of the \
    algorithm code and an object holding details of the \
    algorithm code and the invokes found within it, unless it \
    is the NEMO API, where the first entry of the tuple is \
    None and the second is the fparser2 parse tree of the \
    code.
:rtype: (:py:class:`fparser.two.Fortran2003.Program`, \
    :py:class:`psyclone.parse.FileInfo`) or (NoneType, \
    :py:class:`fparser.two.Fortran2003.Program`)

Definition at line 173 of file algorithm.py.

    def parse(self, alg_filename):
        '''Takes a PSyclone conformant algorithm file as input and outputs a
        parse tree of the code contained therein and an object
        containing information about the 'invoke' calls in the
        algorithm file and any associated kernels within the invoke
        calls. If the NEMO API is being used then the parsed code is
        returned without any additional information about the code.
 
        :param str alg_filename: The file containing the algorithm code.
 
        :returns: 2-tuple consisting of the fparser2 parse tree of the \
            algorithm code and an object holding details of the \
            algorithm code and the invokes found within it, unless it \
            is the NEMO API, where the first entry of the tuple is \
            None and the second is the fparser2 parse tree of the \
            code.
        :rtype: (:py:class:`fparser.two.Fortran2003.Program`, \
            :py:class:`psyclone.parse.FileInfo`) or (NoneType, \
            :py:class:`fparser.two.Fortran2003.Program`)
 
        '''
        self._alg_filename = alg_filename
        if self._line_length:
            # Make sure the code conforms to the line length limit.
            check_line_length(alg_filename)
        alg_parse_tree = parse_fp2(alg_filename)
 
        if self._api == "nemo":
            # For this API we just parse the NEMO code and return the resulting
            # fparser2 AST with None for the Algorithm AST.
            return None, alg_parse_tree
 
        return alg_parse_tree, self.invoke_info(alg_parse_tree)
 

References psyclone.parse.algorithm.Parser._alg_filename, psyclone.configuration.Config._api, psyclone.parse.algorithm.Parser._api, psyclone.line_length.FortLineLength._line_length, psyclone.parse.algorithm.Parser._line_length, and psyclone.parse.algorithm.Parser.invoke_info().

Here is the call graph for this function:

update_arg_to_module_map()

def psyclone.parse.algorithm.Parser.update_arg_to_module_map	(		self,
			statement
	)

Takes a use statement and adds its contents to the internal
arg_name_to_module_name map. This map associates names
specified in the 'only' list with the corresponding use name.

:param statement: A use statement
:type statement: :py:class:`fparser.two.Fortran2003.Use_Stmt`
:raises InternalError: if the statement being passed is not an \
fparser use statement.

Definition at line 468 of file algorithm.py.

    def update_arg_to_module_map(self, statement):
        '''Takes a use statement and adds its contents to the internal
        arg_name_to_module_name map. This map associates names
        specified in the 'only' list with the corresponding use name.
 
        :param statement: A use statement
        :type statement: :py:class:`fparser.two.Fortran2003.Use_Stmt`
        :raises InternalError: if the statement being passed is not an \
        fparser use statement.
 
        '''
        # make sure statement is a use
        if not isinstance(statement, Use_Stmt):
            raise InternalError(
                f"algorithm.py:Parser:update_arg_to_module_map: Expected "
                f"a use statement but found instance of "
                f"'{type(statement)}'.")
 
        use_name = str(statement.items[2])
 
        # Extract 'only' list.
        if statement.items[4]:
            only_list = statement.items[4].items
        else:
            only_list = []
 
        for item in only_list:
            self._arg_name_to_module_name[str(item).lower()] = use_name
 

References psyclone.parse.algorithm.Parser._arg_name_to_module_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/parse/algorithm.py