Andy Porter

Please could @TeranIvy and/or @tommbendall (or someone else?) take a look at the updated documentation that this PR introduces. Once we're happy with that, I'll proceed to implementation.

Tagging @stevemullerworth so he can join the fun too :-)

The good news: the integration tests pass. Bad news:  i.e. the performance of NEMO with OMP offload and OMP CPU threading has taken a big hit.

I've diffed the generated OMP code with that from master and the only differences are in a comment where we don't sort the order of 'impure' routine names. Perhaps the...

I re-ran the NEMO tests and got:  so it may just be machine noise. I'll check the generated OMP-offload code against that from master too.

The only diffs between master and this branch in the generated OMP-offoad version of NEMO4 are: ``` $ diff psycloned-openmp_gpu{,-2027} diff psycloned-openmp_gpu/icbdyn.f90 psycloned-openmp_gpu-2027/icbdyn.f90 111c111 < pt%lon = icb_utl_bilin_x(glamt,pt%xi,pt%yj) --- >...

Unfortunately, my tightening-up of checks on the types of expressions appearing in array-indices now means that the WHERE handling is refusing some code that is/was OK, e.g.: WHERE( picefr(:,:) >...

> @arporter The WHERE branch has been merged, so this PR can probably continue now. Also note that a `"lbclnk.f90", # TODO #2685: effective shape bug` was added to examples/nemo/scripts/omp_cpu_trans.py...

I have some indirect coverage changes that I need to address: 

Indirect coverage changes all fixed. For one of them, I've taken the liberty of marking the bit of code with a no-cover pragma and a TODO for #1858 as that...