gamer-project · ChunYen-Chen · Feb 20, 2025 · Feb 20, 2025 · Feb 20, 2025 · Feb 28, 2025
diff --git a/.github/ISSUE_TEMPLATE/1-bug.yml b/.github/ISSUE_TEMPLATE/1-bug.yml
@@ -0,0 +1,119 @@
+name: 🐞 Bug Report
+description: File a bug report
+labels: ["triage"]
+
+body:
+
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+
+        This issue tracker is for reporting bugs and issues found in the GAMER project.
+        If you are looking for help with GAMER, please check out the [GAMER Slack](https://join.slack.com/t/gamer-project/shared_invite/enQtNTUwMDA5ODAwMTMzLTc3ZWY2MWE2YTlmMDI0MTQ4M2JjOTg2NmU4OWVkOGY1ZTI3MmY5NjUxOTk1ZjM5ZjNjOGViMGY3ZGExMDdiYzU).
+
+        Please fill out the following form with as much detail as possible to help us diagnose and resolve the issue efficiently.
+
+  - type: textarea
+    id: issue_content
+    attributes:
+      label: 🔎 What happened?
+      description: Explain the problem and expected behavior.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce_step
+    attributes:
+      label: 📃 Steps to reproduce
+      description: Please provide detailed steps to help us reproduce the issue.
+      placeholder: |
+        e.g.,
+        1. Copy the shocktube test problem from `example/Hydro/Riemann/*`.
+        2. Build GAMER with CXXFLAG -g -O0 in the machine configuration file.
+        3. Run `./gamer`, and a segmentation fault occurs.
+    validations:
+      required: true
+
+  - type: input
+    id: commit_hash
+    attributes:
+      label: ⌚ Commit hash
+      description: Please provide the commit hash of the version you are using by running `git rev-parse HEAD`. If you are not using the public `main` branch, also include the repository link and branch name.
+      placeholder: e.g., 2f1ceb7ceb6249f0252d58cdc0269383631bdd68 or 2f1ceb7
+    validations:
+      required: true
+
+  - type: input
+    id: config_cmd
+    attributes:
+      label: 🔧 Configuration command
+      description: Please provide the configuration command you used to generate the `Makefile`. Alternatively, copy and paste the contents of `Makefile.log`.
+      placeholder: e.g., python configure.py --fftw=FFTW2 --gravity=true --gpu=true
+
+  - type: textarea
+    id: files_modified
+    attributes:
+      label: 🔨 Source files modified
+      description: Please provide a list of source files you have modified, if any.
+      placeholder: e.g., src/Hydro/Gravity/Init_TestProb_Hydro_Gravity.cpp
+
+  - type: dropdown
+    id: operation_system
+    attributes:
+      label: 💻 Operating system
+      description: Please specify the OS of your machine. If your OS is not listed, please select "Other" and specify it in the "Additional information" section.
+      multiple: false
+      options:
+        - linux (x86)
+        - linux (ARM)
+        - macOS (Intel)
+        - macOS (Apple silicon)
+        - Windows (x86)
+        - Windows (ARM)
+        - Other (Please specify)
+
+  - type: textarea
+    id: machine
+    attributes:
+      label: 💾 Machine configuration file
+      description: Please provide the contents of the machine configuration file you used under `gamer/configs`. If you used a built-in configuration, simply specify its name (e.g., `spock_intel.config`).
+      placeholder: |
+        e.g.,
+        # NTU-spock
+        CUDA_PATH       /software/cuda/12.1
+        FFTW2_PATH      /software/fftw/2.1.5-intel-2023.1.0-openmpi-4.1.5-ucx_mt
+        FFTW3_PATH      /software/fftw/3.3.10-intel-2023.1.0-openmpi-4.1.5-ucx_mt
+        MPI_PATH        /software/openmpi/4.1.5-ucx_mt-intel-2023.1.0
+        ...
+
+        # compilers
+        CXX     icpc
+        CXX_MPI mpicxx
+        ...
+
+  - type: checkboxes
+    id: labels
+    attributes:
+      label: 🔖 Related topics
+      description: Select relevant topics (you may choose more than one).
+      options:
+        - label: Hydro
+        - label: MHD
+        - label: FDM
+        - label: AMR
+        - label: Gravity
+        - label: Particle
+        - label: Parallelization
+        - label: GPU
+        - label: Memory
+        - label: YT
+        - label: Tool
+        - label: Docs
+        - label: Other
+
+  - type: textarea
+    id: additional_info
+    attributes:
+      label: 💬 Additional information
+      description: Please provide any additional information that may help diagnose the issue (e.g., screenshots, stdout/stderr, and `Record__Note`).
diff --git a/.github/ISSUE_TEMPLATE/2-feature.yml b/.github/ISSUE_TEMPLATE/2-feature.yml
@@ -0,0 +1,62 @@
+name: 💪 Feature Request
+description: Suggest a new feature
+labels: ["triage"]
+
+body:
+
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature!
+
+        Please fill out the following form to help us better understand your request.
+
+  - type: textarea
+    id: feature_description
+    attributes:
+      label: 💭 Proposed feature
+      description: Provide a clear and concise description of the feature you are suggesting.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: 🔆 Use case
+      description: Describe where this feature would be applied.
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: 💡 Motivation
+      description: Explain why this feature is needed and how it benefits the project.
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional_info
+    attributes:
+      label: 💬 Additional information
+      description: Provide any additional information or context that may be helpful.
+
+  - type: checkboxes
+    id: labels
+    attributes:
+      label: 🔖 Related topics
+      description: Select relevant topics (you may choose more than one).
+      options:
+        - label: Hydro
+        - label: MHD
+        - label: FDM
+        - label: AMR
+        - label: Gravity
+        - label: Particle
+        - label: Parallelization
+        - label: GPU
+        - label: Memory
+        - label: YT
+        - label: Tool
+        - label: Docs
+        - label: Other
diff --git a/.github/ISSUE_TEMPLATE/3-assign-task.yml b/.github/ISSUE_TEMPLATE/3-assign-task.yml
@@ -0,0 +1,48 @@
+name: 🐟 Assign Task
+description: Assign a new set of tasks (Dev Team Only)
+
+body:
+
+  - type: markdown
+    attributes:
+      value: |
+        🐟🐟🐟🐟🐟🐟🐟🐟🐟|| DEV TEAM ONLY ||🐟🐟🐟🐟🐟🐟🐟🐟🐟
+        This is a template for the development team to assign a new set of tasks.
+        If you are not a member of the team, please do not use this template.
+        🐟🐟🐟🐟🐟🐟🐟🐟🐟|| DEV TEAM ONLY ||🐟🐟🐟🐟🐟🐟🐟🐟🐟
+
+  - type: textarea
+    id: goal
+    attributes:
+      label: 🎯 Goals
+    validations:
+      required: true
+
+  - type: textarea
+    id: task
+    attributes:
+      label: 📋 Mandatory tasks
+      value: |
+        - [ ] Task 1
+        - [ ] Task 2
+        - [ ] Task 3
+    validations:
+      required: true
+
+  - type: textarea
+    id: opt_task
+    attributes:
+      label: Optional tasks
+      value: |
+        - [ ] Task A
+        - [ ] Task B
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: References
+
+  - type: textarea
+    id: note
+    attributes:
+      label: Supplementary info
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: ❓ General help or Question
+    url: https://join.slack.com/t/gamer-project/shared_invite/enQtNTUwMDA5ODAwMTMzLTc3ZWY2MWE2YTlmMDI0MTQ4M2JjOTg2NmU4OWVkOGY1ZTI3MmY5NjUxOTk1ZjM5ZjNjOGViMGY3ZGExMDdiYzU
+    about: Join our Slack for discussion
diff --git a/configs/eureka_gnu.config b/configs/eureka_gnu.config
@@ -8,6 +8,7 @@ GRACKLE_PATH
 GSL_PATH        /software/gsl/default
 LIBYT_PATH
 CUFFTDX_PATH    /software/cuFFTDx/default
+HYPRE_PATH
 
 # compilers
 CXX     g++

diff --git a/configs/eureka_intel.config b/configs/eureka_intel.config
@@ -8,6 +8,7 @@ GRACKLE_PATH
 GSL_PATH        /software/gsl/default
 LIBYT_PATH
 CUFFTDX_PATH    /software/cuFFTDx/default
+HYPRE_PATH
 
 # compilers
 CXX     icpc

diff --git a/configs/spock_intel.config b/configs/spock_intel.config
@@ -8,6 +8,7 @@ GRACKLE_PATH
 GSL_PATH        /software/gsl/2.6-intel-2023.1.0
 LIBYT_PATH
 CUFFTDX_PATH    /software/cuFFTDx/22.11
+HYPRE_PATH
 
 # compilers
 CXX     icpc

diff --git a/configs/template.config b/configs/template.config
@@ -10,6 +10,7 @@ GRACKLE_PATH    /path/to/grackle
 GSL_PATH        /path/to/gsl
 LIBYT_PATH      /path/to/libyt
 CUFFTDX_PATH    /path/to/cufftdx
+HYPRE_PATH
 
 # 2. Compiler type
 CXX     icpc                    # Serial compiler

diff --git a/doc/wiki/Developing-with-VS-Code.md b/doc/wiki/Developing-with-VS-Code.md
@@ -0,0 +1,66 @@
+This guide provides step-by-step instructions for setting up and using Visual Studio Code (VS Code) to develop the GAMER codebase.
+
+## Setup
+
+### Prerequisites
+
+- **Quick Start**: Follow the [[Quick Start | Quick-Start]] guide to download GAMER and complete at least one [[demo | Quick-Start:-1D-Shock-Tube]].
+- **Visual Studio Code**: Download and install VS Code from [https://code.visualstudio.com/](https://code.visualstudio.com/).
+- **C/C++ Extension**: Install the "C/C++" extension from the VS Code Marketplace.
+
+### Setting Up the Workspace
+
+1. **Launch VS Code**.
+2. **Open the GAMER Project Folder**:
+   - Go to `File` > `Open Folder...`.
+   - Select your GAMER project directory.
+
+> [!TIP]
+> When using remote-SSH, open the directory as an absolute path to avoid [this issue](https://github.com/microsoft/vscode-cpptools/issues/4818).
+
+### Configuring VS Code for GAMER
+
+Run the following script from the root directory of the GAMER project:
+```bash
+sh tool/vscode/copy_to_vscode.sh
+```
+This script copies the necessary configuration files to the `.vscode` directory, integrating GAMER with VS Code.
+
+## Developing with VS Code
+
+Before running the tasks below, **set the working directory** by selecting `Terminal` > `Run Task...` > `set-working-bin` and entering the name of the working directory under `bin/` where the input files are located.
+
+### Configuring GAMER
+
+Select `Terminal` > `Run Task...` > `config-GAMER` to configure GAMER using the `generate_make.sh` script in your working directory.
+
+### Building GAMER
+
+After configuring GAMER with [configure.py](https://github.com/gamer-project/gamer/wiki/Installation%3A-Configure.py) or `generate_make.sh`, select `Terminal` > `Run Task...` > `build-GAMER` to start the build process. This updates the macros and enables IntelliSense highlighting.
+
+> [!TIP]
+> To configure and build GAMER in one step, select `Terminal` > `Run Build Task...` or press `Ctrl + Shift + B` to run `config-GAMER` and `build-GAMER` sequentially.
+
+### Debugging GAMER
+
+To start debugging, select `Run` > `Start Debugging` or press `F5`. After entering the working directory, the debugger will launch. See the [official documentation](https://code.visualstudio.com/docs/editor/debugging) to learn more about debugging in VS Code.
+
+> [!IMPORTANT]
+> Ensure the compiler flags in `Makefile` are set to `-g -O0` for debugging. (TBD: Add an argument to `configure.py` to set these flags.)
+
+> [!NOTE]
+> If `gdb` is not supported on macOS, you can set up `lldb` as the debugger. Ensure [`lldb-mi`](https://github.com/lldb-tools/lldb-mi) is installed, then select `Terminal` > `Run Task...` > `updated_mac_launch`. This updates the debugger path in `launch.json` to your `lldb-mi` installation.
+> For manual setup or additional details, refer to the [official documentation](https://code.visualstudio.com/docs/cpp/launch-json-reference).
+
+### Cleaning the Working Directory
+
+Select `Terminal` > `Run Task...` > `clean-work-dir` to clean the working directory using the `clean.sh` script in your working directory.
+
+## Understanding Configuration Files
+
+The following configuration files are copied to the `.vscode` directory:
+- `c_cpp_properties.json`: Configures IntelliSense settings, including include paths and macros. See the [schema reference](https://code.visualstudio.com/docs/cpp/c-cpp-properties-schema-reference) and [IntelliSense documentation](https://code.visualstudio.com/docs/editor/intellisense) for details.
+- `launch.json`: Defines debugging configurations such as executable paths and arguments. See the [official documentation](https://code.visualstudio.com/docs/cpp/launch-json-reference) for more information.
+- `settings.json`: Specifies editor settings, such as indentation spaces and file types for extensions. See the [VS Code settings guide](https://code.visualstudio.com/docs/editor/settings) for details.
+- `tasks.json`: Defines build and auxiliary tasks. Learn more about [tasks in VS Code](https://code.visualstudio.com/docs/editor/tasks).
+- `gamercpp.natvis`: Customizes data structure visualizations in the debugger. Learn more about [customizing native object views](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2022).
diff --git a/doc/wiki/Home.md b/doc/wiki/Home.md
@@ -1,6 +1,6 @@
 **GAMER** is a **G**PU-accelerated **A**daptive **ME**sh **R**efinement
-code for astrophysics. It features extremely high performance and
-parallel scalability and supports a rich set of physics modules.
+code for astrophysics. It features high computational performance and
+strong parallel scalability, and supports a rich set of physics modules.
 
 ***
 
@@ -10,19 +10,22 @@ parallel scalability and supports a rich set of physics modules.
 * [Magnetohydrodynamics](https://iopscience.iop.org/article/10.3847/1538-4365/aac49e/meta)
 * [Special relativistic hydrodynamics](https://academic.oup.com/mnras/article/504/3/3298/6224873)
 * Self-gravity and external gravity
-* Particles
+* Particles and tracers
 * Chemistry and radiative processes with [GRACKLE](http://grackle.readthedocs.io/en/latest/index.html)
 * General equation of state
+* Passively advected scalars
+* Star formation
 * [Cosmic rays with anisotropic diffusion](https://iopscience.iop.org/article/10.3847/1538-4357/ad50c5#apjad50c5app2)
-* Fuzzy (Wave) dark matter: [Nature Physics paper](http://www.nature.com/nphys/journal/v10/n7/covers/index.html), [code paper](https://arxiv.org/abs/2411.17288)
+* Fuzzy dark matter (FDM): [Nature Physics paper](http://www.nature.com/nphys/journal/v10/n7/covers/index.html), [code paper](https://arxiv.org/abs/2411.17288)
 
 ### Other Features
 * Adaptive mesh refinement
 * Adaptive timestep
-* Hybrid MPI/OpenMP/GPU parallelization (also support a CPU-only mode)
+* Hybrid MPI/OpenMP/GPU parallelization (also supports a CPU-only mode)
 * Load balancing with Hilbert space-filling curve
 * Bitwise reproducibility
-* [HDF5](https://support.hdfgroup.org/HDF5) output
+* Simple compilation using `configure.py` and machine files
+* [HDF5](https://www.hdfgroup.org/solutions/hdf5/) output
 * Data analysis with [yt](http://yt-project.org)
 * In situ Python analysis with [libyt](https://github.com/yt-project/libyt)
 * Source-term interface
@@ -37,6 +40,7 @@ parallel scalability and supports a rich set of physics modules.
 * Mailing list: [GAMER Google Group](https://groups.google.com/forum/#!forum/gamer-amr)
 * Live chat: [GAMER Slack](https://join.slack.com/t/gamer-project/shared_invite/enQtNTUwMDA5ODAwMTMzLTc3ZWY2MWE2YTlmMDI0MTQ4M2JjOTg2NmU4OWVkOGY1ZTI3MmY5NjUxOTk1ZjM5ZjNjOGViMGY3ZGExMDdiYzU)
 * Code papers:
+[GAMER-1](https://iopscience.iop.org/article/10.1088/0067-0049/186/2/457),
 [GAMER-2](https://academic.oup.com/mnras/article/481/4/4815/5106358) <a name="CODE_PAPER"></a>,
 [GAMER-MHD](http://iopscience.iop.org/article/10.3847/1538-4365/aac49e/meta) <a name="MHD_PAPER"></a> ,
 [GAMER-SR](https://academic.oup.com/mnras/article/504/3/3298/6224873) <a name="SR_PAPER"></a>,