Skip to content

Commit 94dc519

Browse files
Malmahrouqi3Malmahrouqi3
authored
Merge branch 'master' into rdma_mpi
2 parents 3d32ff1 + 565178a commit 94dc519

File tree

154 files changed

+6279
-4276
lines changed

Some content is hidden

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

154 files changed

+6279
-4276
lines changed

‎.fortls.json‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
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+
],
18+
"include_dirs": [
19+
"src/common/include/",
20+
"src/simulation/include/",
21+
"src/pre_process/include/",
22+
"src/post_process/include/"
23+
],
24+
"pp_suffixes": [".fpp"],
25+
"pp_defs": {
26+
"MFC": 1,
27+
"MFC_DOUBLE_PRECISION": 1
28+
},
29+
"lowercase_intrinsics": true,
30+
"debug_log": false,
31+
"disable_diagnostics": true,
32+
"use_signature_help": true,
33+
"variable_hover": true,
34+
"hover_signature": true,
35+
"enable_code_actions": true,
36+
"mod_dirs": [
37+
"build/pre_process/",
38+
"build/simulation/",
39+
"build/post_process/",
40+
"build/common/"
41+
],
42+
"ext_mod_dirs": [
43+
"/usr/include/",
44+
"/usr/local/include/",
45+
"/opt/homebrew/include/"
46+
],
47+
"implicit_external_mods": [
48+
"mpi",
49+
"m_thermochem",
50+
"hipfort",
51+
"hipfort_check",
52+
"hipfort_hipfft",
53+
"cutensorex",
54+
"silo_f9x",
55+
"m_model"
56+
],
57+
"disable_diagnostics_for_external_modules": true,
58+
"max_line_length": 132,
59+
"symbol_skip_mem": [
60+
"mpi_*"
61+
],
62+
"disable_var_diagnostics": true,
63+
"disable_fypp": false,
64+
"fypp_strict": false,
65+
"error_suppression_list": [
66+
"include-not-found",
67+
"mod-not-found",
68+
"var-masking",
69+
"declared-twice",
70+
"no-matching-declaration",
71+
"invalid-parent",
72+
"parsing-error",
73+
"fypp-error",
74+
"preprocessor-error",
75+
"syntax-error",
76+
"semantic-error",
77+
"type-error",
78+
"undefined-variable",
79+
"line-too-long"
80+
],
81+
"incremental_sync": false,
82+
"debug_parser": false,
83+
"skip_parse_errors": true,
84+
"disable_parser": [
85+
"src/post_process/m_data_output.fpp",
86+
"src/pre_process/include/ExtrusionHardcodedIC.fpp",
87+
"src/pre_process/m_checker.fpp",
88+
"src/pre_process/include/2dHardcodedIC.fpp",
89+
"src/pre_process/include/3dHardcodedIC.fpp",
90+
"src/simulation/m_qbmm.fpp",
91+
"src/common/m_variables_conversion.fpp",
92+
"src/simulation/m_global_parameters.fpp"
93+
]
94+
}

‎.fortlsrc‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
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_DOUBLE_PRECISION": 1
30+
},
31+
"lowercase_intrinsics": true,
32+
"debug_log": true,
33+
"disable_diagnostics": false,
34+
"use_signature_help": true,
35+
"variable_hover": true,
36+
"hover_signature": true,
37+
"enable_code_actions": true,
38+
"mod_dirs": [
39+
"build/pre_process/",
40+
"build/simulation/",
41+
"build/post_process/",
42+
"build/common/"
43+
],
44+
"ext_mod_dirs": [
45+
"/usr/include/",
46+
"/usr/local/include/",
47+
"/opt/homebrew/include/"
48+
],
49+
"implicit_external_mods": [
50+
"mpi",
51+
"m_thermochem",
52+
"m_variables_conversion",
53+
"hipfort",
54+
"hipfort_check",
55+
"hipfort_hipfft",
56+
"cutensorex",
57+
"silo_f9x",
58+
"m_model"
59+
],
60+
"disable_diagnostics_for_external_modules": true,
61+
"max_line_length": -1,
62+
"max_comment_line_length": -1,
63+
"symbol_skip_mem": [
64+
"mpi_*"
65+
],
66+
"disable_var_diagnostics": false,
67+
"disable_fypp": false,
68+
"fypp_strict": false,
69+
"error_suppression_list": [
70+
"include-not-found",
71+
"mod-not-found",
72+
"module-not-found",
73+
"declared-twice",
74+
"no-matching-declaration",
75+
"invalid-parent",
76+
"parsing-error",
77+
"fypp-error",
78+
"preprocessor-error",
79+
"implicit-type"
80+
],
81+
"incremental_sync": false,
82+
"debug_parser": false,
83+
"skip_parse_errors": true,
84+
"disable_parser": [
85+
"src/post_process/m_data_output.fpp",
86+
"src/pre_process/include/ExtrusionHardcodedIC.fpp",
87+
"src/pre_process/m_checker.fpp",
88+
"src/pre_process/include/2dHardcodedIC.fpp",
89+
"src/pre_process/include/3dHardcodedIC.fpp",
90+
"src/simulation/m_qbmm.fpp",
91+
"src/common/m_variables_conversion.fpp",
92+
"src/simulation/m_global_parameters.fpp",
93+
"**/m_nvtx*",
94+
"**/syscheck.fpp"
95+
]
96+
}

‎.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+

‎.github/copilot-instructions.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# GitHub Copilot Instructions – Pull-Request Reviews for MFC
2+
3+
These instructions guide **GitHub Copilot Code Review** and **Copilot Chat** when they evaluate pull requests in this repository.
4+
5+
---
6+
7+
## 1 Project Context (always include)
8+
9+
* **Project:** MFC (exascale many-physics solver) written in **modern Fortran 2008+**, generated with **Fypp**.
10+
* **Directory layout:**
11+
* Sources in `src/`, tests in `tests/`, examples in `examples/`.
12+
* Most source files are templated `.fpp`; CMake transpiles them to `.f90`.
13+
* **Fypp macros** are in `src/<subprogram>/include/`, where `<subprogram>` is `simulation`, `common`, `pre_process`, or `post_process`. Review these first.
14+
* Only `simulation` (plus its `common` dependencies) is GPU-accelerated with **OpenACC**.
15+
16+
> **Copilot, when reviewing:**
17+
> * Treat the codebase as free-form Fortran 2008+ with `implicit none`, explicit `intent`, and standard intrinsics.
18+
> * Prefer `module … contains … subroutine foo()` over legacy constructs; flag uses of `COMMON`, file-level `include`, or other global state.
19+
20+
---
21+
22+
## 2 Incremental-Change Workflow
23+
24+
Copilot, when reviewing:
25+
* Encourage small, buildable commits
26+
27+
---
28+
29+
## 3 Style & Naming Conventions (*.fpp / *.f90)
30+
31+
| Element | Rule |
32+
|---------|------|
33+
| Indentation | 2 spaces; continuation lines align beneath &. |
34+
| Case | Lower-case keywords & intrinsics (do, end subroutine, …). |
35+
| Modules | m_<feature> (e.g. m_transport). |
36+
| Public subroutines | s_<verb>_<noun> (s_compute_flux). |
37+
| Public functions | f_<verb>_<noun>. |
38+
| Routine size | subroutine ≤ 500 lines, helper ≤ 150, function ≤ 100, file ≤ 1000. |
39+
| Arguments | ≤ 6; else use a derived-type params struct. |
40+
| Forbidden | goto (except legacy), COMMON, save globals. |
41+
| Variables | Every arg has explicit intent; use dimension/allocatable/pointer as appropriate. |
42+
| Errors | Call s_mpi_abort(<msg>), never stop or error stop. |
43+
44+
Copilot, when reviewing:
45+
* Flag violations of any cell above.
46+
* Suggest refactors when size or argument limits are exceeded.
47+
* Ensure private helpers stay inside their defining module and avoid nested procedures.
48+
49+
---
50+
51+
## 4 OpenACC Guidelines (for GPU kernels)
52+
53+
Wrap tight loops:
54+
55+
```fortran
56+
!$acc parallel loop gang vector default(present) reduction(...)
57+
```
58+
59+
* Add collapse(n) when safe.
60+
* Declare loop-local variables with private(...).
61+
* Allocate large arrays with managed or move them into a persistent !$acc enter data region at start-up.
62+
* Avoid stop/error stop inside device code.
63+
* Code must compile with Cray ftn, NVIDIA nvfortran, GNU gfortran, and Intel ifx/ifort.
64+
65+
---
66+
67+
## 5 Review Checklist (what Copilot should verify)
68+
69+
1. Buildability: PR includes build instructions or CI passes the staged build.
70+
2. Tests: Focused tests are added/updated.
71+
3. Style compliance: All rules in §3 are satisfied.
72+
4. Module hygiene: No new global state; proper namespacing.
73+
5. Performance: GPU code follows §4; no large host/device transfers in hot loops.
74+
6. Documentation: Updated in-code comments and, when needed, README or docs site.
75+
7. Regressions: No changes to outputs of golden tests without clear justification.

0 commit comments

Comments
 (0)