Quokka

https://quokka-astro.github.io/quokka/
Admin
Quokka is a two-moment radiation hydrodynamics code using the piecewise-parabolic method with...
Tokens:24,563
Snippets:236
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Build Tools and Dependencies

Source: https://quokka-astro.github.io/quokka/installation

Commands to install CMake, Ninja, and Python dependencies using Homebrew, pip, or uv.

```bash
# Homebrew
brew install open-mpi cmake ninja

# Pip
python3 -m pip install cmake ninja numpy matplotlib --user

# uv
uv tool install cmake ninja
uv pip install numpy matplotlib
```

--------------------------------

### Install yt-studio for Web Visualization

Source: https://quokka-astro.github.io/quokka/postprocessing

Installs the yt-studio tool, which provides a web-based interface and Python API for visualizing Quokka simulation data.

```bash
pip install git+https://github.com/chongchonghe/yt-studio.git
```

--------------------------------

### Install Custom yt Frontend for Quokka

Source: https://quokka-astro.github.io/quokka/postprocessing

Installs a specialized fork of the yt analysis library that includes a Quokka frontend. This enables the use of yt functions for processing Quokka simulation data.

```bash
pip install "yt[quokka] @ git+https://github.com/chongchonghe/yt.git"
```

--------------------------------

### Setup Local Git Repository for Quokka

Source: https://quokka-astro.github.io/quokka/contributing

Commands to clone the repository, configure upstream remotes, and set the local development branch to track the upstream version.

```bash
git clone --branch development git@github.com:<myGithubUsername>/quokka.git
cd Quokka
git remote add upstream git@github.com:quokka-astro/quokka.git
git remote set-url --push upstream git@github.com:<myGithubUsername>/quokka.git
git fetch upstream
git branch -u upstream/development
```

--------------------------------

### Implement Reflecting Boundary Conditions

Source: https://quokka-astro.github.io/quokka/mhd_module

Example of applying reflecting boundary conditions for magnetic field components using AMReX types as required by the Quokka MHD module.

```cpp
amrex::BCType::reflect_even
```

--------------------------------

### Verify macOS Development Environment

Source: https://quokka-astro.github.io/quokka/installation

Scripts to verify C++ compiler functionality, install Xcode tools, and validate MPI installations on macOS.

```bash
cat > /tmp/cpp.cpp <<'EOF'
#include <iostream>
int main(){ std::cout << "C++ works\n"; }
EOF
clang++ /tmp/cpp.cpp -o /tmp/cpp && /tmp/cpp

xcode-select --install

mpicxx --version

cat > /tmp/mpi_cpp.cpp <<'EOF'
#include <mpi.h>
#include <iostream>
int main(int argc,char**argv){
  MPI_Init(&argc,&argv);
  int r; MPI_Comm_rank(MPI_COMM_WORLD,&r);
  std::cout<<"Hello from C++ rank "<<r<<"\n";
  MPI_Finalize();
  return 0;
}
EOF
mpicxx /tmp/mpi_cpp.cpp -o /tmp/mpi_cpp && /tmp/mpi_cpp
```

--------------------------------

### Manage Git Branches and Updates

Source: https://quokka-astro.github.io/quokka/contributing

Standard commands for updating the local development branch, creating new feature branches, and staging changes for commit.

```bash
git checkout development
git pull
git checkout -b <branch_name>
git add <file_I_created> <and_file_I_modified>
```

--------------------------------

### Doxygen documentation block format

Source: https://quokka-astro.github.io/quokka/contributing

Developers should use Doxygen-style comment blocks preceding namespaces, classes, and functions. These blocks must include a brief description and parameter definitions using the \param tag.

```cpp
/**
 * \brief A one line description.
 *
 * \param[in] variable A short description of the variable.
 * \param[inout] data The value of data is read and changed.
 *
 * A longer description can be included here.
 */

void MyFunction (int variable, MultiFab& data){
    ...
}
```

--------------------------------

### Launch Amrvis Browser Container

Source: https://quokka-astro.github.io/quokka/postprocessing

Starts a Docker or Apptainer container to browse Quokka plotfiles via a browser-based X11 interface. The script requires a path to the plotfiles directory and provides a local URL for access.

```bash
./launch_amrvis_browser.sh /path/to/plotfiles
```

--------------------------------

### Commit and Push Changes

Source: https://quokka-astro.github.io/quokka/contributing

Commands to commit local changes with a descriptive message and push them to the remote fork, including synchronization with the upstream development branch.

```bash
git commit -m "This is a 50-char description to explain my work"
git push -u origin <branch_name>
git pull upstream development
```

--------------------------------

### Implement Initial Conditions in C++

Source: https://quokka-astro.github.io/quokka/developing_problem_generators

This C++ code snippet shows the implementation of `setInitialConditionsOnGrid`, a crucial routine for defining the initial state of a problem. It is invoked during `setInitialConditions()` and is responsible for populating the cell-centered state arrays for each patch. The example demonstrates filling a sawtooth profile by iterating over the grid provided by the `quokka::grid` struct.

```cpp
void setInitialConditionsOnGrid(const quokka::grid& grid, real* state)
{
    // ... implementation to populate state arrays ...
    // Example: filling a sawtooth profile
    for (int i = 0; i < grid.nx; ++i) {
        state[i] = ...; // Calculate initial condition value
    }
}

```

--------------------------------

### Interactive Rebase Commit Editing

Source: https://quokka-astro.github.io/quokka/contributing

Example of how to edit commit history during an interactive rebase. This demonstrates how to change 'pick' to 'drop' for commits that should be removed from the rebased branch, effectively cleaning up the commit history.

```git
pick 7451d9d commit message a
pick c4c2459 commit message b
pick 6fj3g90 commit message c

---

drop 7451d9d commit message a
drop c4c2459 commit message b
pick 6fj3g90 commit message c
```

--------------------------------

### Manage CMake Build Targets

Source: https://quokka-astro.github.io/quokka/installation

Instructions for listing available build targets and compiling specific test problems to optimize build times.

```bash
cmake --build . --target help
ninja -j6 test_hydro3d_blast
```

--------------------------------

### Configure MHD Runtime Parameters

Source: https://quokka-astro.github.io/quokka/mhd_module

This snippet demonstrates how to define essential runtime parameters for the MHD module in a Quokka configuration file. These settings control spatial reconstruction order, EMF computation schemes, and boundary conditions.

```text
reconstruction_order = 3
emf_reconstruction_order = 5
emf_compute_scheme = "Balsara2025"
emf_averaging_type = "Balsara2025"
artificial_viscosity_k = 0.1
quokka.bc = "periodic"
```

--------------------------------

### Generate VisIt Timeseries File

Source: https://quokka-astro.github.io/quokka/postprocessing

Creates a .visit file containing a list of plotfile headers, allowing VisIt to recognize and load a sequence of simulation snapshots as a single timeseries.

```bash
ls -1 plt*/Header | tee plotfiles.visit
```

--------------------------------

### Configure and Build for AMD GPUs

Source: https://quokka-astro.github.io/quokka/installation

Commands to identify GPU architecture and execute a CMake build for Quokka using the HIP backend with AMD compilers.

```bash
rocminfo | grep gfx

cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_CXX_COMPILER=amdclang++ \
         -DCMAKE_C_COMPILER=amdclang \
         -DAMReX_GPU_BACKEND=HIP \
         -DAMReX_GPU_ARCH=gfx1031 \
         -G Ninja
```

--------------------------------

### Member variable naming convention

Source: https://quokka-astro.github.io/quokka/contributing

All member variables within classes must be suffixed with an underscore character to distinguish them from local variables.

```cpp
amrex::Real variable_;
```

--------------------------------

### Delete Local and Remote Git Branches

Source: https://quokka-astro.github.io/quokka/contributing

Commands to delete a local Git branch after a pull request has been merged, and to delete the corresponding remote branch on your fork.

```git
git branch -D <branch_name>
git push origin --delete <branch_name>
```

--------------------------------

### Enforce curly braces for control flow blocks

Source: https://quokka-astro.github.io/quokka/contributing

Quokka coding standards require the use of curly braces for all control flow blocks, including single-statement loops and conditionals. This prevents ambiguity and improves code readability.

```cpp
for (int n=0; n<10; ++n) {
    Print() << "Like this!";
}

for (int n=0; n<10; ++n) { Print() << "Like this!"; }
```

--------------------------------

### Force Synchronous GPU Execution via Environment Variables

Source: https://quokka-astro.github.io/quokka/debugging

Sets environment variables to force the CPU to wait for GPU kernel completion. This is useful for debugging synchronization issues by ensuring sequential execution.

```bash
export CUDA_LAUNCH_BLOCKING=1
export HIP_LAUNCH_BLOCKING=1
```

--------------------------------

### Fix Accidental Commits in Development Branch

Source: https://quokka-astro.github.io/quokka/contributing

Steps to recover from accidentally committing to the development branch. This involves creating a new branch for the accidental commits, resetting the development branch, and then checking out the new branch to retain the lost commits.

```git
git checkout -b new_branch
git checkout development
git reset HEAD~2  # Here 2 is the number of commits you have accidentally committed in development
git checkout .
```

--------------------------------

### Test GPU Race Conditions with Bash Script

Source: https://quokka-astro.github.io/quokka/debugging

Runs a simulation twice with different synchronization settings to compare output files. It detects race conditions by verifying if the results are identical across synchronous and asynchronous runs.

```bash
./scripts/bash/test_gpu_race.sh -b ./build/src/FieldLoop/test_field_loop -i inputs/FieldLoop.toml -n 10
```

--------------------------------

### Rebase PR Branch to Upstream Development

Source: https://quokka-astro.github.io/quokka/contributing

A comprehensive procedure to fix a pull request branch that has diverged from the Quokka development branch. This involves fetching upstream changes, creating a temporary branch, resetting the local development branch, and then performing an interactive rebase to clean up the PR branch's history.

```git
git fetch upstream   # assuming upstream is the remote name for the official Quokka repo
git checkout -b xxx upstream/development  # replace xxx with whatever name you like
git branch -D development
git checkout -b development upstream/development
git checkout xxx
git merge yyy  # here yyy is your PR branch with unclean history
git rebase -i upstream/development
```

--------------------------------

### Execute clang-tidy via command line

Source: https://quokka-astro.github.io/quokka/howto_clang_tidy

Runs clang-tidy on specific source files using a build directory for configuration. This command targets all files within the specified directory.

```bash
clang-tidy src/particles/* -p ./build
```
Tokens:
Raw