psyclone.domain.common

A package module for domain/common.

Submodules

• psyclone.domain.common.algorithm
  • Submodules
    • psyclone.domain.common.algorithm.psyir
      • Classes
        • AlgorithmInvokeCall
          • AlgorithmInvokeCall.create()
          • AlgorithmInvokeCall.create_psylayer_symbol_root_names()
          • AlgorithmInvokeCall.node_str()
        • KernelFunctor
          • KernelFunctor.create()
  • Classes
    • AlgorithmInvokeCall
      • AlgorithmInvokeCall.create()
      • AlgorithmInvokeCall.create_psylayer_symbol_root_names()
      • AlgorithmInvokeCall.node_str()
    • KernelFunctor
      • KernelFunctor.create()
• psyclone.domain.common.driver_creator
• psyclone.domain.common.psylayer
  • Submodules
    • psyclone.domain.common.psylayer.psyloop
  • Classes
    • PSyLoop
      • PSyLoop.args_filter()
      • PSyLoop.dag_name
      • PSyLoop.field
      • PSyLoop.field_name
      • PSyLoop.field_space
      • PSyLoop.has_inc_arg()
      • PSyLoop.iteration_space
      • PSyLoop.kernel
      • PSyLoop.loop_type
      • PSyLoop.node_str()
      • PSyLoop.unique_fields_with_halo_reads()
      • PSyLoop.unique_modified_args()
      • PSyLoop.valid_loop_types
• psyclone.domain.common.transformations
  • Submodules
    • psyclone.domain.common.transformations.alg_invoke_2_psy_call_trans
      • Classes
        • AlgInvoke2PSyCallTrans
          • AlgInvoke2PSyCallTrans.apply()
          • AlgInvoke2PSyCallTrans.get_arguments()
          • AlgInvoke2PSyCallTrans.remove_imported_symbols()
          • AlgInvoke2PSyCallTrans.validate()
    • psyclone.domain.common.transformations.alg_trans
      • Classes
        • AlgTrans
          • AlgTrans.apply()
          • AlgTrans.validate()
    • psyclone.domain.common.transformations.kernel_module_inline_trans
    • psyclone.domain.common.transformations.raise_psyir_2_alg_trans
      • Classes
        • RaisePSyIR2AlgTrans
          • RaisePSyIR2AlgTrans.apply()
          • RaisePSyIR2AlgTrans.validate()
  • Classes
    • AlgInvoke2PSyCallTrans
      • AlgInvoke2PSyCallTrans.apply()
      • AlgInvoke2PSyCallTrans.get_arguments()
      • AlgInvoke2PSyCallTrans.remove_imported_symbols()
      • AlgInvoke2PSyCallTrans.validate()
    • AlgTrans
      • AlgTrans.apply()
      • AlgTrans.validate()
    • KernelModuleInlineTrans
      • KernelModuleInlineTrans.apply()
      • KernelModuleInlineTrans.validate()
    • RaisePSyIR2AlgTrans
      • RaisePSyIR2AlgTrans.apply()
      • RaisePSyIR2AlgTrans.validate()

Classes

• DriverCreator: This class provides the functionality common to all driver creations.

class psyclone.domain.common.DriverCreator(region_name=None)

This class provides the functionality common to all driver creations. The driver is created as follows:

1. A file container is created and the (empty) driver program is added.

2. All symbols from the read_kernel_data_mod are added to the symbol table, and a psy_data symbol is created that handles the reading of data from the kernel data file.

3. The command line handler is added to the driver. It is responsible for handling command line parameters for the driver specifying the kernel data file to read (and if nothing is specified to use the default, which is the name used in the extraction without MPI rank attached).

4. A copy of the kernel that is being instrumented is created, so that it can be modified without affecting the actual code creation if PSyclone.

5. The method verify_and_cleanup_psyir is called with the copied kernel as parameter. The base implementation checks that no structure accesses are in the code (which are not supported - the structures used by the domain-specific code have already been replaced since the extracted region has been lowered). This can be overwritten by domain-specific implementation. For example, in LFRic calls to set_dirty and set_clean are removed (since they are irrelevant) first.

6. The read-in code is added, using the read_write information which is used when extracting the data. This ensures that the extraction and driver are matching.

7. The copy of the kernel is added.

8. All modules required by the kernel are imported.

9. A call to handle_precision_symbols is made, allowing domain-specific derived classes to add precision related symbols as required (see lfric_extract_driver_creator.py), or to replace precision symbols (see extract_driver_creator.py).

10. Add the code that will compare the results, i.e. comparing all output variables computed in the kernel with the post values stored in the kernel data file.

Parameters:

region_name (Optional[tuple[str, str]]) – Suggested region name.

Inheritance

static add_call(program, name, args)

This function creates a call to the subroutine of the given name, providing the arguments. The call will be added to the program and the corresponding RoutineSymbol to its symbol table (if not already present).

Parameters:

• program (Routine) – the PSyIR Routine to which any code must be added.

• name (str) – name of the subroutine to call.

• args (list[Node]) – list of all arguments for the call.

Raises:

TypeError – if there is a symbol with the specified name defined that is not a RoutineSymbol.

static add_read_call(program, name_lit, sym, read_var)

This function creates a call to the subroutine that read fields from the data file.

Parameters:

• program (Routine) – the PSyIR Routine to which any code must be added.

• name_lit (Literal) – the name of the field in the data file.

• sym (DataSymbol) – the symbol to store the read data.

• read_var (str) – the method name to read the data.

static add_result_tests(program, output_symbols)

Adds tests to check that all output variables have the expected value.

Parameters:

• program (Routine) – the program to which the tests should be added.

• output_symbols (list[tuple[Symbol, Symbol]]) – a list containing all output variables of the executed code. Each entry in the list is a 2-tuple, containing first the symbol that was computed when executing the kernels, and then the symbol containing the expected values that have been read in from a file.

static collect_all_required_modules(file_container)

Collects recursively all modules used in the file container. It returns a dictionary, with the keys being all the (directly or indirectly) used modules.

Parameters:

file_container (FileContainer) – the FileContainer for which to collect all used modules.

Return type:

dict[str, set[str]]

Returns:

a dictionary, with the required module names as key, and as value a set of all modules required by the key module.

create(nodes, read_write_info, prefix, postfix, region_name)

This function uses the PSyIR to create a stand-alone driver that reads in a previously created file with kernel input and output information, and calls the kernels specified in the ‘nodes’ PSyIR tree with the parameters from the file. The nodes are consecutive nodes from the PSyIR tree. It returns the file container which contains the driver.

Parameters:

• nodes (list[Node]) – a list of nodes.

• read_write_info (ReadWriteInfo) – information about all input and output parameters.

• prefix (str) – the prefix to use for each PSyData symbol, e.g. ‘extract’ as prefix will create symbols extract_psydata.

• postfix (str) – a postfix that is appended to an output variable to create the corresponding variable that stores the output value from the kernel data file. The caller must guarantee that no name clashes are created when adding the postfix to a variable and that the postfix is consistent between extract code and driver code (see ‘ExtractTrans.determine_postfix()’).

• region_name (tuple[str, str]) – an optional name to use for this PSyData area, provided as a 2-tuple containing a location name followed by a local name. The pair of strings should uniquely identify a region.

Return type:

FileContainer

Returns:

the program PSyIR for a stand-alone driver.

get_driver_as_string(nodes, read_write_info, prefix, postfix, region_name, writer=<psyclone.psyir.backend.fortran.FortranWriter object>)

This function uses the create() function to get the PSyIR of a stand-alone driver, and then uses the provided language writer to create a string representation in the selected language (defaults to Fortran). All required modules will be inlined in the correct order, i.e. each module will only depend on modules inlined earlier, which will allow compilation of the driver. No other dependencies (except system dependencies like NetCDF) are required for compilation.

Parameters:

• nodes (list[Node]) – a list of nodes.

• read_write_info (ReadWriteInfo) – information about all input and output parameters.

• prefix (str) – the prefix to use for each PSyData symbol, e.g. ‘extract’ as prefix will create symbols extract_psydata.

• postfix (str) – a postfix that is appended to an output variable to create the corresponding variable that stores the output value from the kernel data file. The caller must guarantee that no name clashes are created when adding the postfix to a variable and that the postfix is consistent between extract code and driver code (see ‘ExtractTrans.determine_postfix()’).

• region_name (tuple[str, str]) – an optional name to use for this PSyData area, provided as a 2-tuple containing a location name followed by a local name. The pair of strings should uniquely identify a region.

• language_writer – a backend visitor to convert PSyIR representation to the selected language. It defaults to the FortranWriter.

Return type:

str

Returns:

the driver in the selected language.

abstractmethod handle_precision_symbols(symbol_table)

This method is called to allow DSL-specific changes of type information. E.g. it might replace DSL-specific integer types with generic declarations, or add additional import statements to make the required types available.

Parameters:

symbol_table (SymbolTable) – the SymbolTable of the driver.

Return type:

None

static import_modules(program)

This function adds all the import statements required for the actual kernel calls. It finds all calls in the PSyIR tree and checks for calls with a ImportInterface. Any such call will get a ContainerSymbol added for the module, and a RoutineSymbol with an import interface pointing to this module.

Parameters:

program (Routine) – the PSyIR Routine to which any code must be added.

verify_and_cleanup_psyir(extract_region)

This method is called to verify that no unsupported language features are used. The base implementation checks for StructureReferences (except for ones used in a call, which some DLSs use, e.g. set_dirty in LFRic)

Parameters:

extract_region (Node) – the node with the extracted region.

Raises:

ValueError – if a StructureReference outside of a call is found.

Return type:

None

write_driver(nodes, read_write_info, prefix, postfix, region_name, writer=<psyclone.psyir.backend.fortran.FortranWriter object>)

This function uses the get_driver_as_string() function to get a a stand-alone driver, and then writes this source code to a file. The file name is derived from the region name: “driver-“+module_name+”_”+region_name+”.F90”

Parameters:

• nodes (list[Node]) – a list of nodes containing the body of the driver routine.

• read_write_info (ReadWriteInfo) – information about all input and output parameters.

• prefix (str) – the prefix to use for each PSyData symbol, e.g. ‘extract’ as prefix will create symbols extract_psydata.

• postfix (str) – a postfix that is appended to an output variable to create the corresponding variable that stores the output value from the kernel data file. The caller must guarantee that no name clashes are created when adding the postfix to a variable and that the postfix is consistent between extract code and driver code (see ‘ExtractTrans.determine_postfix()’).

• region_name (tuple[str, str]) – an optional name to use for this PSyData area, provided as a 2-tuple containing a location name followed by a local name. The pair of strings should uniquely identify a region.

• writer (LanguageWriter) – a backend visitor to convert PSyIR representation to the selected language. It defaults to the FortranWriter.

Return type:

None