diff --git a/README.md b/README.md index acfaa0df..ff7502b3 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,55 @@ [![Build Status](https://github.com/huiyuxie/TrixiGPU.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/huiyuxie/TrixiGPU.jl/actions/workflows/CI.yml?query=branch%3Amain) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) -**TrixiGPU.jl** is a component package of the [**Trixi.jl**](https://github.com/trixi-framework/Trixi.jl) ecosystem and provides GPU acceleration support for solving hyperbolic partial differential equations (PDEs). This package was initialized through the [**Google Summer of Code**](https://summerofcode.withgoogle.com/archive/2023/projects/upstR7K2) program in 2023 and is still under development. +**TrixiGPU.jl** is a component package of the [**Trixi.jl**](https://github.com/trixi-framework/Trixi.jl) ecosystem and provides GPU acceleration support for solving hyperbolic partial differential equations (PDEs). This package was initialized through the [**Google Summer of Code**](https://summerofcode.withgoogle.com/archive/2023/projects/upstR7K2) program in 2023 and is under active development and testing. The acceleration focus of this package is currently on the semidiscretization part (with plans to extend to other parts) of the PDE solvers, and [**CUDA.jl**](https://github.com/JuliaGPU/CUDA.jl) is our primary support (will expand to more types of GPUs using [**AMDGPU.jl**](https://github.com/JuliaGPU/AMDGPU.jl), [**OneAPI.jl**](https://github.com/JuliaGPU/oneAPI.jl), and [**Metal.jl**](https://github.com/JuliaGPU/Metal.jl) in the future). -Please check the progress of our development [**here**](https://github.com/users/huiyuxie/projects/2). +The complete documentation for this project (and now is available as a package) can be accessed here [**GSoC**](https://huiyuxie.github.io/gsoc23/). Please note that this package is intended to be part of the [**trixi-framework**](https://github.com/trixi-framework) orgnization in the end. Due to constrained GPU resources and ease of development, it is now under a temporary organization. + +# Package Installation +The package is now in pre-release status and will be registered once the initial release version is published. We want to make sure most key features are ready and optimizations are done before we roll out the first release. + +## Users +Users who are interested now can install the package by running the following command in the Julia REPL: +```julia +julia> using Pkg; Pkg.add(url="https://github.com/czha/TrixiGPU.jl.git") +``` +Then the package can be used with the following simple command: +```julia +julia> using TrixiGPU +``` +This package serves as a support package, so it is recommended to these packages together: +```julia +julia> using Trixi, TrixiGPU, OrdinaryDiffEq +``` + +## Developers +Developers can start their development by first forking and cloning the repository to their terminal. + +Then enter the Julia REPL in the package directory, activate and instantiate the environment by running the following command: +```julia +julia> using Pkg; Pkg.activate("."); Pkg.instantiate() +``` + +Please note that GPU-related tests are run locally rather than on CI remotely due to constrained resources. Once the repository is ready to be transferred back to the organization, we are going to set up JuliaGPU CI infrastructure to run tests on a system with a GPU using [**JuliaGPU Buildkite**](https://github.com/JuliaGPU/buildkite). + +# Supported Mesh and Solver Types +Our current focus is on the semidiscretization of PDEs. The table below shows the status of this work across different mesh types and solvers. Looking ahead, we plan to extend parallelization to include mesh initialization and callbacks on the GPU. + +| Mesh Type | Spatial Dimension | Solver Type | Status | +|--------------------|-------------------|-------------|----------------| +| `TreeMesh` | 1D, 2D, 3D | `DGSEM` | ✅ Supported | +| `StructuredMesh` | 1D, 2D, 3D | `DGSEM` | 🛠️ In Development| +| `UnstructuredMesh` | 2D | `DGSEM` | 🟡 Planned | +| `P4estMesh` | 2D, 3D | `DGSEM` | 🟡 Planned | +| `DGMultiMesh` | 1D, 2D, 3D | `DGMulti` | 🟡 Planned | + +# Example of PDE Semidiscretization on GPU +Let's take a look at a simple example to see how to use **TrixiGPU.jl** to run the simulation on the GPU (now only CUDA-compatible). -# Example of Semidiscretization on GPU ```julia -# Take 1D Linear Advection Equation as an example +# Take 1D linear advection equation as an example using Trixi, TrixiGPU using OrdinaryDiffEq @@ -28,7 +68,7 @@ coordinates_max = 1.0 mesh = TreeMesh(coordinates_min, coordinates_max, initial_refinement_level = 4, - n_cells_max = 30_000) # set maximum capacity of tree data structure + n_cells_max = 30_000) semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition_convergence_test, solver) @@ -59,22 +99,11 @@ sol = solve(ode, CarpenterKennedy2N54(williamson_condition = false), summary_callback() ``` -# Supported Mesh and Solver Types -Our current focus is on the semidiscretization of PDEs. The table below shows the status of this work across different mesh types and solvers. Looking ahead, we plan to extend parallelization to include mesh initialization and callbacks on the GPU. - -| Mesh Type | Spatial Dimension | Solver Type | Status | -|--------------------|-------------------|-------------|----------------| -| `TreeMesh` | 1D, 2D, 3D | `DGSEM` | ✅ Supported | -| `StructuredMesh` | 1D, 2D, 3D | `DGSEM` | 🛠️ In Development| -| `UnstructuredMesh` | 2D | `DGSEM` | 🟡 Planned | -| `P4estMesh` | 2D, 3D | `DGSEM` | 🟡 Planned | -| `DGMultiMesh` | 1D, 2D, 3D | `DGMulti` | 🟡 Planned | - # GPU Kernels to be Implemented Kernels left to be implemented on `TreeMesh` with `DGSEM`: - 1D Kernels: 1) `calc_volume_integral!` - `volume_integral::VolumeIntegralShockCapturingHG` - 2D Kernels: 1) `calc_volume_integral!` - `volume_integral::VolumeIntegralShockCapturingHG`, 2) `calc_mortar_flux!`- `nonconservative_terms::True` - 3D Kernels: 1) `calc_volume_integral!` - `volume_integral::VolumeIntegralShockCapturingHG`, 2) `calc_mortar_flux!` - `nonconservative_terms::True` -# Show Your Support! -We always welcome new people to join us, please feel free to contribute. Also, if you find this package interesting and inspiring, please give it a star. Thanks! +# Show Your Support +We always welcome new contributors to join us in future development. Please feel free to reach out if you would like to get involved!