(closes #3216) Allow specifying explicit private variables for parallel regions

[sergisiso]

Currently we have Loop.explictly_private_symbols to force a different result than the automatic sharing attributes provide. However it is not possible to do the same with parallel regions. To fix this I moved this attribute to the SharingAttributeMixin. It makes more sense here as it is being set and used by the same class (better encapsulation) and can be used by ALL subclases adding sharing attribute clauses.

There was also the problem that users didn't find out this capability easily. This can be improved by adding a transformation option, as this is the documentation that people is looking at while transforming code.

So when LFRic_atm scripts currently do:

# set some symbols to be PRIVATE
mark_explicit_privates(loop, symbols_to_add)

OMPParallelLoopTrans(omp_schedule="dynamic").apply(
    loop, options=opts
)

can be:

OMPParallelLoopTrans(omp_schedule="dynamic").apply(
    loop, force_private=symbols_to_add, **opts
)

The transformation option logs (but doesn't fail) for symbols not found, to have the same behaviour as mark_explicit_privates.

[sergisiso]

@MetBenjaminWent may want to be aware of /test these changes

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.95%. Comparing base (ee25f8a) to head (074797f).
⚠️ Report is 27 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3275   +/-   ##
=======================================
  Coverage   99.95%   99.95%           
=======================================
  Files         376      376           
  Lines       53485    53504   +19     
=======================================
+ Hits        53463    53482   +19     
  Misses         22       22           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sergisiso]

@arporter @LonelyCat124 This is ready for a first look

[LonelyCat124]

I'm not going to review this today, just having a quick look at it now - is it worth having an example showing how to use this? We had people in NG-Arch using explicit private on Loop nodes which will no longer function and an example/docs to explain how to use this new functionality on the Directives (which is currently likely to be quite common) might be useful? @sergisiso

[sergisiso]

When merging the NG-Arch tickets its use has been standarised to the "mark_explicit_privates" from the LFRic psyclone_tools.py that I show in my top comment, so it is a one-line change. But I agree regarding the example/more docs comment.

[sergisiso]

I added and example as suggested (currently in nemo/eg8, but we could move it to the psyir folder once there is no conflict with @LonelyCat124 current changes).

The documentation is now part of the Transformation options. This is done on purpose to make it more discoverable, it is what people will probably open. And it is automatically inherited to all subclasses through kwargs:

@LonelyCat124 @arporter This is ready to review again

[LonelyCat124]

@sergisiso This mostly looks ok to me, I've not done all the local stuff yet - couple of copyright dates need updating but I'll do a final review once we can run integration with a local lfric_atm/core

[LonelyCat124]

Copyright date should just be 2026 right? Since its a new file

[LonelyCat124]

Copyright year.

[LonelyCat124]

Can you update this to use type hints instead of the doc :type:?

[LonelyCat124]

What happened to the dry_run option here? I guess its not needed because we no longer modify the tree, only affect some local variables to the transformation and resultant directive>