1- ----
2- - description: Full MFC project rules – consolidated for Agent Mode
3- - alwaysApply: true
4- ----
1+ ---
2+ description: Full MFC project rules – consolidated for Agent Mode
3+ alwaysApply: true
4+ ---
55
66# 0 Purpose & Scope
77Consolidated guidance for the MFC exascale, many-physics solver.
@@ -19,7 +19,7 @@ Written primarily for Fortran/Fypp; the GPU and style sections matter only when
1919- Assume free-form Fortran 2008+, `implicit none`, explicit `intent`, and modern intrinsics.
2020- Prefer `module … contains … subroutine foo()`; avoid `COMMON` blocks and file-level `include` files.
2121- **Read the full codebase and docs *before* changing code.**
22- - Docs: <https://mflowcode.github.io/documentation/md_readme.html> and the respository root `README.md`.
22+ - Docs: <https://mflowcode.github.io/documentation/md_readme.html> and the repository root `README.md`.
2323
2424### Incremental-change workflow
2525
@@ -62,27 +62,7 @@ Written primarily for Fortran/Fypp; the GPU and style sections matter only when
6262
6363---
6464
65- # 3 FYPP Macros for GPU acceleration Pogramming Guidelines (for GPU kernels)
66-
67- Do not directly use OpenACC or OpenMP directives directly.
68- Instead, use the FYPP macros contained in src/common/include/parallel_macros.fpp
69-
70- Wrap tight loops with
71-
72- ```fortran
73- $:GPU_PARALLEL_FOR(private='[...]', copy='[...]')
74- ```
75- * Add `collapse=n` to merge nested loops when safe.
76- * Declare loop-local variables with `private='[...]'`.
77- * Allocate large arrays with `managed` or move them into a persistent
78- `$:GPU_ENTER_DATA(...)` region at start-up.
79- * **Do not** place `stop` / `error stop` inside device code.
80- * Must compile with Cray `ftn` and NVIDIA `nvfortran` for GPU offloading; also build CPU-only with
81- GNU `gfortran` and Intel `ifx`/`ifort`.
82-
83- ---
84-
85- # 4 File & Module Structure
65+ # 3 File & Module Structure
8666
8767- **File Naming**:
8868 - `.fpp` files: Fypp preprocessed files that get translated to `.f90`
@@ -99,25 +79,44 @@ $:GPU_PARALLEL_FOR(private='[...]', copy='[...]')
9979 - `contains` section
10080 - Implementation of subroutines and functions
10181
102- # 5 Fypp Macros and GPU Acceleration
82+ ---
83+
84+ # 4 Fypp Macros
10385
104- ## Use of Fypp
10586- **Fypp Directives**:
10687 - Start with `#:` (e.g., `#:include`, `#:def`, `#:enddef`)
10788 - Macros defined in `include/*.fpp` files
10889 - Used for code generation, conditional compilation, and GPU offloading
10990
110- ## Some examples
91+ ---
11192
112- Documentation on how to use the Fypp macros for GPU offloading is available at https://mflowcode.github.io/documentation/md_gpuParallelization.html
93+ # 5 FYPP Macros for GPU Acceleration Programming Guidelines (for GPU kernels)
11394
114- Some examples include:
115- - `$:GPU_ROUTINE(parallelism='[seq]')` - Marks GPU-callable routines
116- - `$:GPU_PARALLEL_LOOP(collapse=N)` - Parallelizes loops
117- - `$:GPU_LOOP(parallelism='[seq]')` - Marks sequential loops
118- - `$:GPU_UPDATE(device='[var1,var2]')` - Updates device data
119- - `$:GPU_ENTER_DATA(copyin='[var]')` - Copies data to device
120- - `$:GPU_EXIT_DATA(delete='[var]')` - Removes data from device
95+ - Do not use OpenACC or OpenMP directives directly.
96+ - Instead, use the FYPP macros contained in `src/common/include/parallel_macros.fpp`
97+ - Documentation on how to use the Fypp macros for GPU offloading is available at https://mflowcode.github.io/documentation/md_gpuParallelization.html
98+
99+ Wrap tight loops with
100+ ```fortran
101+ $:GPU_PARALLEL_FOR(private='[...]', copy='[...]')
102+ ```
103+ * Add `collapse=n` to merge nested loops when safe.
104+ * Declare loop-local variables with `private='[...]'`.
105+ * Allocate large arrays with `managed` or move them into a persistent
106+ `$:GPU_ENTER_DATA(...)` region at start-up.
107+ * **Do not** place `stop` / `error stop` inside device code.
108+ * Must compile with Cray `ftn` or NVIDIA `nvfortran` for GPU offloading; also build CPU-only with
109+ GNU `gfortran` and Intel `ifx`/`ifort`.
110+
111+ - Example GPU macros include the below, among others:
112+ - `$:GPU_ROUTINE(parallelism='[seq]')` - Marks GPU-callable routines
113+ - `$:GPU_PARALLEL_LOOP(collapse=N)` - Parallelizes loops
114+ - `$:GPU_LOOP(parallelism='[seq]')` - Marks sequential loops
115+ - `$:GPU_UPDATE(device='[var1,var2]')` - Updates device data
116+ - `$:GPU_ENTER_DATA(copyin='[var]')` - Copies data to device
117+ - `$:GPU_EXIT_DATA(delete='[var]')` - Removes data from device
118+
119+ ---
121120
122121# 6 Documentation Style
123122
@@ -136,7 +135,7 @@ which conforms to the Doxygen Fortran format.
136135 - Example: `@:ASSERT(predicate, message)`
137136
138137- **Error Reporting**:
139- - Use `s_mpi_abort(<msg> )` for error termination, not `stop`
138+ - Use `s_mpi_abort(error_message )` for error termination, not `stop`
140139 - No `stop` / `error stop` inside device code
141140
142141# 8 Memory Management
0 commit comments