Added GPU debugging and update cursor rules

[prathi-wind]

User description

Description

Added documentation for debugging help with GPUs
Updated cursor rules to use the new GPU macros instead of OpenACC

Fixes #(issue) [optional]

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Something else

Scope

• This PR comprises a set of related changes with a common goal

If you cannot check the above box, please split your PR into multiple PRs that each have a common goal.

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.
Provide instructions so we can reproduce.
Please also list any relevant details for your test configuration

• Test A
• Test B

Test Configuration:

• What computers and compilers did you use to test this:

Checklist

• I have added comments for the new code
• I added Doxygen docstrings to the new code
• I have made corresponding changes to the documentation (docs/)
• I have added regression tests to the test suite so that people can verify in the future that the feature is behaving as expected
• I have added example cases in examples/ that demonstrate my new feature performing as expected.
  They run to completion and demonstrate "interesting physics"
• I ran ./mfc.sh format before committing my code
• New and existing tests pass locally with my changes, including with GPU capability enabled (both NVIDIA hardware with NVHPC compilers and AMD hardware with CRAY compilers) and disabled
• This PR does not introduce any repeated code (it follows the DRY principle)
• I cannot think of a way to condense this code and reduce any introduced additional line count

If your code changes any code source files (anything in src/simulation)

To make sure the code is performing as expected on GPU devices, I have:

• Checked that the code compiles using NVHPC compilers
• Checked that the code compiles using CRAY compilers
• Ran the code on either V100, A100, or H100 GPUs and ensured the new feature performed as expected (the GPU results match the CPU results)
• Ran the code on MI200+ GPUs and ensure the new features performed as expected (the GPU results match the CPU results)
• Enclosed the new feature via nvtx ranges so that they can be identified in profiles
• Ran a Nsight Systems profile using ./mfc.sh run XXXX --gpu -t simulation --nsys, and have attached the output file (.nsys-rep) and plain text results to this PR
• Ran a Rocprof Systems profile using ./mfc.sh run XXXX --gpu -t simulation --rsys --hip-trace, and have attached the output file and plain text results to this PR.
• Ran my code using various numbers of different GPUs (1, 2, and 8, for example) in parallel and made sure that the results scale similarly to what happens if you run without the new code/feature

---

PR Type

Documentation, Enhancement

---

Description

• Added comprehensive GPU debugging documentation

• Updated cursor rules to use FYPP macros

• Replaced OpenACC directives with GPU macros

• Added debugging tools for Cray and NVHPC compilers

---

Diagram Walkthrough

flowchart LR
  A["Old OpenACC directives"] --> B["FYPP GPU macros"]
  C["Missing GPU debugging docs"] --> D["Comprehensive debugging guide"]
  E["Cursor rules"] --> F["Updated macro guidelines"]

Loading

File Walkthrough

	Relevant files
Configuration changes	mfc-agent-rules.mdc Update cursor rules for FYPP GPU macros                                    .cursor/rules/mfc-agent-rules.mdc Updated GPU acceleration guidelines to use FYPP macros instead of OpenACC directives Changed !$acc routine seq to $:GPU_ROUTINE macro syntax Replaced !$acc parallel loop with $:GPU_PARALLEL_FOR macro Updated section title to reference FYPP macros for GPU acceleration +10/-8
Documentation	gpuDebugging.md Add comprehensive GPU debugging guide                                        docs/documentation/gpuDebugging.md Added comprehensive GPU debugging documentation with 155 lines Documented compiler-agnostic and OpenMP debugging tools Included Cray compiler debugging options and environment variables Added NVHPC compiler debugging tools for OpenACC and OpenMP Provided links to official compiler documentation +155/-0  readme.md Add GPU debugging link to documentation index                        docs/documentation/readme.md Added link to new GPU debugging documentation +1/-0

---

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Formatting Issue There is a malformed markdown link on line 152 with an extra space between the closing bracket and opening parenthesis that will break the link rendering. - [LLVM & OpenMP Docs] (https://openmp.llvm.org/design/Runtimes.html) - NVHPC is built on top of LLVM

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Fix markdown link syntax The markdown link syntax is incorrect with an extra space between the text and URL. This will prevent the link from rendering properly. docs/documentation/gpuDebugging.md [152] -- [LLVM & OpenMP Docs] (https://openmp.llvm.org/design/Runtimes.html) +- [LLVM & OpenMP Docs](https://openmp.llvm.org/design/Runtimes.html) Suggestion importance[1-10]: 5 __ Why: The suggestion correctly fixes a markdown syntax error (a space between link text and URL), which will ensure the link renders correctly.	Low
	Fix typo in section title There's a typo in "Pogramming" which should be "Programming". This affects the readability and professionalism of the documentation. .cursor/rules/mfc-agent-rules.mdc [69] -# 3 FYPP Macros for GPU acceleration Pogramming Guidelines (for kernels) +# 3 FYPP Macros for GPU acceleration Programming Guidelines (for kernels) Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies and fixes a typo ("Pogramming") in a documentation heading, which improves readability and professionalism.	Low
Update

[sbryngelson]

-O{0,1,2,3}

[sbryngelson]

minor fixes