Skip to content

Commit 7f0c19d

Browse files
Malmahrouqi3Malmahrouqi3
committed
Merge remote-tracking branch 'upstream/master' into refactor
2 parents dcfc3e0 + 5e8f116 commit 7f0c19d

File tree

322 files changed

+26013
-5634
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

322 files changed

+26013
-5634
lines changed

‎.cursor/rules/mfc-agent-rules.mdc‎

Lines changed: 126 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,27 @@ alwaysApply: true
44
---
55

66
# 0 Purpose & Scope
7-
Consolidated guidance for the MFC exascale, many-physics solver.
8-
Written primarily for Fortran/Fypp; the OpenACC and style sections matter only when
9-
`.fpp` / `.f90` files are in view.
7+
Consolidated guidance for the MFC exascale, many-physics solver.
8+
Written primarily for Fortran/Fypp; the GPU and style sections matter only when `.fpp` / `.f90` files are in view.
109

1110
---
1211

1312
# 1 Global Project Context (always)
14-
- **Project**: *MFC* is modern Fortran 2008+ generated with **Fypp**.
15-
- Sources `src/`, tests `tests/`, examples `examples/`.
16-
- Most sources are `.fpp`; CMake transpiles them to `.f90`.
17-
- **Fypp macros** live in `src/<subprogram>/include/` you should scan these first.
18-
`<subprogram>` ∈ {`simulation`,`common`,`pre_process`,`post_process`}.
19-
- Only `simulation` (+ its `common` calls) is GPU-accelerated via **OpenACC**.
20-
- Assume free-form Fortran 2008+, `implicit none`, explicit `intent`, and modern
21-
intrinsics.
22-
- Prefer `module … contains … subroutine foo()`; avoid `COMMON` blocks and
23-
file-level `include` files.
24-
- **Read the full codebase and docs *before* changing code.**
25-
Docs: <https://mflowcode.github.io/documentation/md_readme.html> and the respository root `README.md`.
13+
- **Project**: *MFC* is modern Fortran 2008+ generated with **Fypp**.
14+
- Sources `src/`, tests `tests/`, examples `examples/`.
15+
- Most sources are `.fpp`; CMake transpiles them to `.f90`.
16+
- **Fypp macros** live in `src/<subprogram>/include/` you should scan these first.
17+
`<subprogram>` ∈ {`simulation`,`common`,`pre_process`,`post_process`}.
18+
- Only `simulation` (+ its `common` calls) is GPU-accelerated via **OpenACC** or **OpenMP**.
19+
- Assume free-form Fortran 2008+, `implicit none`, explicit `intent`, and modern intrinsics.
20+
- Prefer `module … contains … subroutine foo()`; avoid `COMMON` blocks and file-level `include` files.
21+
- **Read the full codebase and docs *before* changing code.**
22+
- Docs: <https://mflowcode.github.io/documentation/md_readme.html> and the repository root `README.md`.
2623

2724
### Incremental-change workflow
28-
1. Draft a step-by-step plan.
29-
2. After each step, build:
25+
26+
1. Draft a step-by-step plan.
27+
2. After each step, build:
3028
```bash
3129
./mfc.sh build -t pre_process simulation -j $(nproc)
3230
```
@@ -49,34 +47,131 @@ Written primarily for Fortran/Fypp; the OpenACC and style sections matter only w
4947
* Subroutine → `s_<verb>_<noun>` (e.g. `s_compute_flux`)
5048
* Function → `f_<verb>_<noun>`
5149
* Private helpers stay in the module; avoid nested procedures.
52-
* **Size limits**: subroutine ≤ 500 lines, helper ≤ 150, function ≤ 100,
53-
module/file ≤ 1000.
54-
* ≤ 6 arguments per routine; otherwise pass a derived-type “params” struct.
50+
* **Size limits**: subroutine ≤ 500 lines, helper ≤ 150, function ≤ 100, module/file ≤ 1000.
51+
* ≤ 6 arguments per routine; otherwise pass a derived-type "params" struct.
5552
* No `goto` (except unavoidable legacy); no global state (`COMMON`, `save`).
56-
* Every variable: `intent(in|out|inout)` + appropriate `dimension` / `allocatable`
57-
/ `pointer`.
53+
* Every variable: `intent(in|out|inout)` + appropriate `dimension` / `allocatable` / `pointer`.
5854
* Use `s_mpi_abort(<msg>)` for errors, not `stop`.
59-
* Mark OpenACC-callable helpers that are called from OpenACC parallel loops immediately after declaration:
55+
* Mark GPU-callable helpers that are called from GPU parallel loops immediately after declaration:
6056
```fortran
6157
subroutine s_flux_update(...)
62-
!$acc routine seq
58+
$:GPU_ROUTINE(function_name='s_flux_update', parallelism='[seq]')
6359
...
6460
end subroutine
6561
```
6662

6763
---
6864

69-
# 3 OpenACC Programming Guidelines (for kernels)
65+
# 3 File & Module Structure
7066

71-
Wrap tight loops with
67+
- **File Naming**:
68+
- `.fpp` files: Fypp preprocessed files that get translated to `.f90`
69+
- Modules are named with `m_` prefix followed by feature name: `m_helper_basic`, `m_viscous`
70+
- Primary program file is named `p_main.fpp`
71+
72+
- **Module Layout**:
73+
- Start with Fypp include for macros: `#:include 'macros.fpp'`
74+
- Header comments using `!>` style documentation
75+
- `module` declaration with name matching filename
76+
- `use` statements for dependencies
77+
- `implicit none` statement
78+
- `private` declaration followed by explicit `public` exports
79+
- `contains` section
80+
- Implementation of subroutines and functions
81+
82+
---
83+
84+
# 4 Fypp Macros
85+
86+
- **Fypp Directives**:
87+
- Start with `#:` (e.g., `#:include`, `#:def`, `#:enddef`)
88+
- Macros defined in `include/*.fpp` files
89+
- Used for code generation, conditional compilation, and GPU offloading
90+
91+
---
7292

93+
# 5 FYPP Macros for GPU Acceleration Programming Guidelines (for GPU kernels)
94+
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
73100
```fortran
74-
!$acc parallel loop gang vector default(present) reduction(...)
101+
$:GPU_PARALLEL_FOR(private='[...]', copy='[...]')
75102
```
76-
* Add `collapse(n)` to merge nested loops when safe.
77-
* Declare loop-local variables with `private(...)`.
103+
* Add `collapse=n` to merge nested loops when safe.
104+
* Declare loop-local variables with `private='[...]'`.
78105
* Allocate large arrays with `managed` or move them into a persistent
79-
`!$acc enter data` region at start-up.
106+
`$:GPU_ENTER_DATA(...)` region at start-up.
80107
* **Do not** place `stop` / `error stop` inside device code.
81-
* Must compile with Cray `ftn` and NVIDIA `nvfortran` for GPU offloading; also build CPU-only with
108+
* Must compile with Cray `ftn` or NVIDIA `nvfortran` for GPU offloading; also build CPU-only with
82109
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+
---
120+
121+
# 6 Documentation Style
122+
123+
- **Subroutine/Function Documentation**:
124+
```fortran
125+
!> This procedure <description>
126+
!! @param param_name Description of the parameter
127+
!! @return Description of the return value (for functions)
128+
```
129+
which conforms to the Doxygen Fortran format.
130+
131+
# 7 Error Handling
132+
133+
- **Assertions**:
134+
- Use the fypp `ASSERT` macro for validating conditions
135+
- Example: `@:ASSERT(predicate, message)`
136+
137+
- **Error Reporting**:
138+
- Use `s_mpi_abort(error_message)` for error termination, not `stop`
139+
- No `stop` / `error stop` inside device code
140+
141+
# 8 Memory Management
142+
143+
- **Allocation/Deallocation**:
144+
- Use fypp macro `@:ALLOCATE(var1, var2)` macro for device-aware allocation
145+
- Use fypp macro `@:DEALLOCATE(var1, var2)` macro for device-aware deallocation
146+
147+
# 9. Additional Observed Patterns
148+
149+
- **Derived Types**:
150+
- Extensive use of derived types for encapsulation
151+
- Use pointers within derived types (e.g., `pointer, dimension(:,:,:) => null()`)
152+
- Clear documentation of derived type components
153+
154+
- **Pure & Elemental Functions**:
155+
- Use `pure` and `elemental` attributes for side-effect-free functions
156+
- Combine them for operations on arrays (`pure elemental function`)
157+
158+
- **Precision Handling**:
159+
- Use `wp` (working precision) parameter from `m_precision_select`
160+
- Never hardcode precision with `real*8` or similar
161+
162+
- **Loop Optimization**:
163+
- Favor array operations over explicit loops when possible
164+
- Use `collapse=N` directive to optimize nested loops
165+
166+
# 10. Fortran Practices to Avoid
167+
168+
- **Fixed Format**: Only free-form Fortran is used
169+
- No column-position dependent code
170+
171+
- **Older Intrinsics**: Avoid outdated Fortran features like:
172+
- `equivalence` statements
173+
- `data` statements (use initialization expressions)
174+
- Character*N (use `character(len=N)` instead)
175+
176+
- **Using same variable for multiple purposes**: Maintain single responsibility
177+
- Each variable should have one clear purpose

‎.fortlsrc‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
{
2+
"source_dirs": [
3+
"src/",
4+
"src/common/",
5+
"src/simulation/",
6+
"src/pre_process/",
7+
"src/post_process/"
8+
],
9+
"excl_paths": [
10+
"benchmarks/",
11+
"examples/",
12+
"tests/",
13+
"misc/",
14+
"src/pre_process/include/2dHardcodedIC.fpp",
15+
"src/pre_process/include/3dHardcodedIC.fpp",
16+
"src/pre_process/include/ExtrusionHardcodedIC.fpp",
17+
"**/m_nvtx*",
18+
"**/syscheck.fpp"
19+
],
20+
"include_dirs": [
21+
"src/common/include/",
22+
"src/simulation/include/",
23+
"src/pre_process/include/",
24+
"src/post_process/include/"
25+
],
26+
"pp_suffixes": [".fpp"],
27+
"pp_defs": {
28+
"MFC": 1,
29+
"MFC_SINGLE_PRECISION": 1,
30+
"MFC_OPENACC": 1,
31+
"MFC_MPI": 1
32+
},
33+
"lowercase_intrinsics": true,
34+
"debug_log": false,
35+
"disable_diagnostics": false,
36+
"use_signature_help": true,
37+
"variable_hover": true,
38+
"hover_signature": true,
39+
"enable_code_actions": true,
40+
"mod_dirs": [
41+
"build/pre_process/",
42+
"build/simulation/",
43+
"build/post_process/",
44+
"build/common/"
45+
],
46+
"ext_mod_dirs": [
47+
"/usr/include/",
48+
"/usr/local/include/",
49+
"/opt/homebrew/include/"
50+
],
51+
"implicit_external_mods": [
52+
"mpi",
53+
"m_thermochem",
54+
"m_variables_conversion",
55+
"hipfort",
56+
"hipfort_check",
57+
"hipfort_hipfft",
58+
"cutensorex",
59+
"silo_f9x",
60+
"m_model"
61+
],
62+
"disable_diagnostics_for_external_modules": true,
63+
"max_line_length": -1,
64+
"max_comment_line_length": -1,
65+
"disable_var_diagnostics": false,
66+
"disable_fypp": false,
67+
"fypp_strict": false,
68+
"incremental_sync": false,
69+
"debug_parser": true,
70+
"skip_parse_errors": true,
71+
"disable_parser": [
72+
"src/post_process/m_data_output.fpp",
73+
"src/pre_process/include/ExtrusionHardcodedIC.fpp",
74+
"src/pre_process/m_checker.fpp",
75+
"src/pre_process/include/2dHardcodedIC.fpp",
76+
"src/pre_process/include/3dHardcodedIC.fpp",
77+
"src/simulation/m_qbmm.fpp",
78+
"src/common/m_variables_conversion.fpp",
79+
"src/simulation/m_global_parameters.fpp",
80+
"**/m_nvtx*",
81+
"**/syscheck.fpp"
82+
]
83+
}

‎.github/CONTRIBUTING.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Contributing to the MFC Codebase (Multi‑Component Flow Code)
2+
3+
**Multi‑Component Flow Code (MFC)** is an open‑source, high‑performance code for simulating compressible multi‑component, multi‑phase flows.
4+
We welcome contributions of all kinds—bug fixes, new features, documentation, tests, and issue triage—from both newcomers and experienced developers.
5+
This guide explains how to set up your environment, follow MFC's coding standards, and navigate the pull-request (PR) process so your work can be merged smoothly.
6+
7+
---
8+
9+
## 1. Setting Up Your Development Environment
10+
11+
1. **Fork and clone**
12+
```bash
13+
git clone https://github.com/<your‑user>/MFC.git
14+
cd MFC
15+
git remote add upstream https://github.com/MFlowCode/MFC.git
16+
```
17+
2. **Build MFC** – follow the [documentation](https://mflowcode.github.io/documentation/md_getting-started.html). For example:
18+
```bash
19+
./mfc.sh build -j 8 # parallel build with 8 threads
20+
```
21+
3. **Run the test suite** to verify your environment:
22+
```bash
23+
./mfc.sh test -j 8
24+
```
25+
26+
---
27+
28+
## 2. Development Workflow
29+
30+
| Step | Action | Notes |
31+
|------|--------|-------|
32+
| 1 | **Sync your fork**: `git checkout master && git pull upstream master` | Stay up‑to‑date to avoid merge conflicts. |
33+
| 2 | **Create a branch**: `git checkout -b feature/<short‑name>` | Keep each branch focused on one logical change. |
34+
| 3 | **Code, test, document** | Follow the guidelines in §3. |
35+
| 4 | **Format & lint**: `./mfc.sh format` | CI will re‑check; make it pass locally first. |
36+
| 5 | **Run tests**: `./mfc.sh test` | All existing and new tests must pass. |
37+
| 6 | **Commit** (see *Commit Messages* below) | Write clear, atomic commits. |
38+
| 7 | **Push** & open a **PR** | Be mindful: *every push triggers CI*. Bundle fixes together to avoid dozens of CI runs. |
39+
40+
### Commit Messages
41+
42+
- Start with a concise (≤50 chars) summary in imperative mood: `Fix out‑of‑bounds in EOS module`.
43+
- Add a blank line, then a detailed explanation.
44+
- Reference related issues or PRs, e.g., `Fixes #123`.
45+
46+
### Managing CI Runs
47+
48+
Each push to a branch with an open PR runs the full CI matrix (which can take hours).
49+
Plan your pushes—run tests locally and group changes—so the CI queue is not flooded.
50+
51+
---
52+
53+
## 3. Coding Guidelines and Best Practices
54+
55+
### 3.1 Style, Formatting & Linting
56+
MFC enforces a project‑wide Fortran style:
57+
- **Formatter**: `./mfc.sh format` auto‑formats your changes.
58+
- **Linter**: CI runs several linter checks that spot common Fortran-gotchas (implicit typing, shadowed variables, unused locals, etc.). Fix issues before pushing or the linter will often catch them.
59+
60+
### 3.2 Fypp Metaprogramming
61+
62+
MFC uses [**Fypp**](https://github.com/aradi/fypp), a lightweight Python-based preprocessor, to generate repetitive or accelerator-specific Fortran.
63+
Key points:
64+
- Fypp macros live in `include/` directories nested within `src/`.
65+
- Run `./mfc.sh format` to format the example case files and the source code.
66+
- When editing `.fpp`, maintain readability, prefer simple macros over deeply nested constructs.
67+
68+
### 3.3 Documentation
69+
70+
- Add or update Doxygen comments in source files.
71+
- Update Markdown docs under `docs/` if user‑facing behavior changes.
72+
- Provide a minimal example in `examples/` for each new feature when practical.
73+
74+
### 3.4 Testing
75+
76+
- Add regression tests that fail before your change and pass after.
77+
- Use `./mfc.sh test --generate` to create golden files for new cases.
78+
- Keep tests fast; favor small grids and short runtimes.
79+
80+
### 3.5 GPU & Performance
81+
82+
- Ensure code compiles for CPU *and* GPU targets (NVHPC for NVIDIA, Cray for AMD).
83+
- Profile critical kernels; avoid introducing bottlenecks.
84+
85+
---
86+
87+
## 4. Preparing Your Pull Request
88+
89+
1. **One PR = One logical change**. If you plan a follow‑up change, open an issue describing it and assign yourself for visibility.
90+
2. **Fill out the PR template**. Remove checkboxes that do **not** apply.
91+
3. **Describe testing** – list commands, compilers, and any profiling.
92+
4. **Link issues** – `Fixes #<id>` or `Part of #<id>`.
93+
5. **Ensure CI passes** before requesting review.
94+
95+
> **Tip** If your change is large, consider splitting it into smaller PRs. Document the intent in an issue so reviewers understand the overall roadmap.
96+
97+
---
98+
99+
## 5. Code Review & Merge
100+
101+
- Respond promptly to reviewer comments.
102+
- Push focused updates; each push re‑runs CI.
103+
- When all reviews are approved and CI is green, a maintainer will merge your PR.
104+
105+
---
106+
107+
## 6. Issue Triage
108+
109+
If you prefer helping with issue management:
110+
- Comment to clarify reproduction steps.
111+
- Label issues when you have triage rights.
112+
- Close fixed issues and reference the PR.
113+

0 commit comments

Comments
 (0)