Document PSyKAl design and rules/guidance for writing kernels for users

[TeranIvy]

It seems that it is not completely clear to users, developers and reviewers of LFRic Core and Apps how to approach PSyKAl design and writing kernels. This PR adds this information in a practical guidance.

• Rules for types of kernels used in LFRic (some existing documentation is https://code.metoffice.gov.uk/trac/lfric/wiki/PSycloneTool/DevelopmentTips#KernRules and https://github.com/stfc/PSyclone/blob/master/tutorial/practicals/LFRic/building_code/1_simple_kernels/LFRic_kernel_structure.md).
• Rules and practical examples on how to determine PSyclone metadata for the type of arguments passed to kernels.
• Use of PSyclone-based tools to write a kernel (e.g. psyclone-kern and psyclone commands).
• Rules on passing arguments (Algorithm -> PSy layer -> Kernel) and what is allowed to call a kernel.
• Tips and tricks (e.g. access metadata and Fortran intent, how nlayers is determined).
• Handling missing PSyclone functionality via PSyKAl-lite code and raising PSyclone issues.

[TeranIvy]

Note to myself on what to add regarding determining nlayers: The current PSyclone rule is to take nlayers from a field writer regardless of the metadata order as the looping limits are determined from the field writers. This is why if there are continuous and discontinuous writers in the same kernel, PSyclone will give precedence to continuous writers for both looping limits (as they go into the halos so they are covering owned and halo cells) and nlayers. PSyclone issue stfc/PSyclone#868 will add functionality for passing different number of layers.

Update: Well, my assumptions were incorrect. PSyclone seems to determine nlayers from the first field in a kernel call for a single invoke, and the first field in the first kernel or built-in call for grouped calls in joint invokes. I opened stfc/PSyclone#2636 to clarify or/and document this.

[TeranIvy]

Other suggested topics:

• How to use PSyclone optimisation script.
• How PSyclone works in the LFRic build system.

Summary of "bare minimum" that a developer needs to be familiar with how to write kernels and calls to kernels from algorithms.

[stevemullerworth]

I have reviewed the current state of the documentation. Several of the items in the list are now covered, noting that in some cases only a brief overview is given as there are references to the PSyclone documentation which should be the main source of documentation for those developing complex kernels.

The following item is still not covered (I don't think).

• Use of PSyclone-based tools to write a kernel (e.g. psyclone-kern and psyclone commands).

As much of the issue is covered, I am going to move this issue to a later milestone.