You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Added Oliver to contributor list, added CHANGELOG, updated README, added PR template. (#78)
* Added Oliver as a main contributor
* Added changelogs and updated readme.md file. The address of assets are also changed to be absolute so that they show up correctly on PyPi
* Added info on how to install the latest version
* Added pull request template
* Removed the example and shorten the description
Thank you for your contribution! Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies that are required for this change.
5
+
-->
6
+
7
+
8
+
## Type of change
9
+
10
+
<!-- Please select the options that are relevant. -->
11
+
-[ ] Bug fix (non-breaking change which fixes an issue)
12
+
-[ ] New feature (non-breaking change which adds functionality)
13
+
-[ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
14
+
-[ ] Documentation update
15
+
16
+
## How Has This Been Tested?
17
+
18
+
<!-- Please describe the tests that you ran to verify your changes. Provide instructions so others can reproduce. Include details of your test environment, and the test cases you ran.
19
+
20
+
- [ ] Test A
21
+
- [ ] Test B
22
+
-->
23
+
-[ ] All pytest tests pass
24
+
25
+
<!-- To run the tests, execute the following command from the root of the repository:
26
+
27
+
```bash
28
+
pytest
29
+
```
30
+
-->
31
+
32
+
33
+
## Linting and Code Formatting
34
+
35
+
Make sure the code follows the project's linting and formatting standards. This project uses **Ruff** for linting.
36
+
37
+
To run Ruff, execute the following command from the root of the repository:
38
+
39
+
```bash
40
+
ruff check .
41
+
```
42
+
43
+
<!-- You can also fix some linting errors automatically using Ruff:
# XLB: A Differentiable Massively Parallel Lattice Boltzmann Library in Python for Physics-Based Machine Learning
8
8
9
-
XLB is a fully differentiable 2D/3D Lattice Boltzmann Method (LBM) library that leverages hardware acceleration. It's built on top of the [JAX](https://github.com/google/jax) library and is specifically designed to solve fluid dynamics problems in a computationally efficient and differentiable manner. Its unique combination of features positions it as an exceptionally suitable tool for applications in physics-based machine learning.
9
+
🎉 **Exciting News!** 🎉 XLB version 0.2.0 has been released, featuring a complete rewrite of the library and introducing support for the NVIDIA Warp backend!
10
+
XLB can now be installed via pip: `pip install xlb`.
11
+
12
+
XLB is a fully differentiable 2D/3D Lattice Boltzmann Method (LBM) library that leverages hardware acceleration. It supports [JAX](https://github.com/google/jax) and [NVIDIA Warp](https://github.com/NVIDIA/warp) backends, and is specifically designed to solve fluid dynamics problems in a computationally efficient and differentiable manner. Its unique combination of features positions it as an exceptionally suitable tool for applications in physics-based machine learning. With the new Warp backend, XLB now offers state-of-the-art performance for even faster simulations.
13
+
14
+
## Getting Started
15
+
To get started with XLB, you can install it using pip:
16
+
```bash
17
+
pip install xlb
18
+
```
19
+
20
+
To install the latest development version from source:
The changelog for the releases can be found [here](https://github.com/Autodesk/XLB/blob/main/CHANGELOG.md).
27
+
28
+
For examples to get you started please refer to the [examples](https://github.com/Autodesk/XLB/tree/main/examples) folder.
10
29
11
30
## Accompanying Paper
12
31
@@ -29,9 +48,10 @@ If you use XLB in your research, please cite the following paper:
29
48
```
30
49
31
50
## Key Features
51
+
-**Multiple Backend Support:** XLB now includes support for multiple backends including JAX and NVIDIA Warp, providing *state-of-the-art* performance for lattice Boltzmann simulations. Currently, only single GPU is supported for the Warp backend.
32
52
-**Integration with JAX Ecosystem:** The library can be easily integrated with JAX's robust ecosystem of machine learning libraries such as [Flax](https://github.com/google/flax), [Haiku](https://github.com/deepmind/dm-haiku), [Optax](https://github.com/deepmind/optax), and many more.
33
53
-**Differentiable LBM Kernels:** XLB provides differentiable LBM kernels that can be used in differentiable physics and deep learning applications.
34
-
-**Scalability:** XLB is capable of scaling on distributed multi-GPU systems, enabling the execution of large-scale simulations on hundreds of GPUs with billions of cells.
54
+
-**Scalability:** XLB is capable of scaling on distributed multi-GPU systems using the JAX backend, enabling the execution of large-scale simulations on hundreds of GPUs with billions of cells.
35
55
-**Support for Various LBM Boundary Conditions and Kernels:** XLB supports several LBM boundary conditions and collision kernels.
36
56
-**User-Friendly Interface:** Written entirely in Python, XLB emphasizes a highly accessible interface that allows users to extend the library with ease and quickly set up and run new simulations.
37
57
-**Leverages JAX Array and Shardmap:** The library incorporates the new JAX array unified array type and JAX shardmap, providing users with a numpy-like interface. This allows users to focus solely on the semantics, leaving performance optimizations to the compiler.
@@ -42,29 +62,29 @@ If you use XLB in your research, please cite the following paper:
On GPU in-situ rendering using <ahref="https://github.com/loliverhennigh/PhantomGaze">PhantomGaze</a> library (no I/O). Flow over a NACA airfoil using KBC Lattice Boltzmann Simulation with ~10 million cells.
<a href=https://www.epc.ed.tum.de/en/aer/research-groups/automotive/drivaer > DrivAer model </a> in a wind-tunnel using KBC Lattice Boltzmann Simulation with approx. 317 million cells
The stages of a fluid density field from an initial state to the emergence of the "XLB" pattern through deep learning optimization at timestep 200 (see paper for details)
@@ -73,7 +93,7 @@ The stages of a fluid density field from an initial state to the emergence of th
Lid-driven Cavity flow at Re=100,000 (~25 million cells)
@@ -99,7 +119,8 @@ The stages of a fluid density field from an initial state to the emergence of th
99
119
- D3Q27 (Must be used for KBC simulation runs)
100
120
101
121
### Compute Capabilities
102
-
- Distributed Multi-GPU support
122
+
- Single GPU support for the Warp backend with state-of-the-art performance
123
+
- Distributed Multi-GPU support using the JAX backend
103
124
- Mixed-Precision support (store vs compute)
104
125
- Out-of-core support (coming soon)
105
126
@@ -125,50 +146,19 @@ The stages of a fluid density field from an initial state to the emergence of th
125
146
-**Regularized BC:** This boundary condition is used to impose a prescribed velocity or pressure profile at the boundary. This BC is more stable than Zouhe BC, but computationally more expensive.
126
147
-**Extrapolation Outflow BC:** A type of outflow boundary condition that uses extrapolation to avoid strong wave reflections.
127
148
128
-
-**Interpolated Bounceback BC:** Interpolated bounce-back boundary condition due to Bouzidi for a lattice Boltzmann method simulation.
129
-
130
-
## Installation Guide
131
-
132
-
To use XLB, you must first install JAX and other dependencies using the following commands:
Please refer to https://github.com/google/jax for the latest installation documentation. The following table is taken from [JAX's Github page](https://github.com/google/jax).
| Google TPU |`pip install -U "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html`|
142
-
| AMD GPU | Use [Docker](https://hub.docker.com/r/rocm/jax) or [build from source](https://jax.readthedocs.io/en/latest/developer.html#additional-notes-for-building-a-rocm-jaxlib-for-amd-gpus). |
143
-
| Apple GPU | Follow [Apple's instructions](https://developer.apple.com/metal/jax/). |
144
-
145
-
**Note:** We encountered challenges when executing XLB on Apple GPUs due to the lack of support for certain operations in the Metal backend. We advise using the CPU backend on Mac OS. We will be testing XLB on Apple's GPUs in the future and will update this section accordingly.
*Note: Some of the work-in-progress features can be found in the branches of the XLB repository. For contributions to these features, please reach out.*
164
155
165
-
- 🚀 **Warp Backend:** Achieving state-of-the-art performance by leveraging the [Warp](https://github.com/NVIDIA/warp) framework in combination with JAX.
- ⚡ **Multi-GPU Acceleration using [Neon](https://github.com/Autodesk/Neon) + Warp:** Using Neon's data structure for improved scaling.
158
+
- 💾 **Out-of-Core Computations:** Enabling simulations that exceed available GPU memory, suitable for CPU+GPU coherent memory models such as NVIDIA's Grace Superchips (coming soon).
159
+
170
160
171
-
-💾**Out-of-Core Computations:** Enabling simulations that exceed available GPU memory, suitable for CPU+GPU coherent memory models such as NVIDIA's Grace Superchips.
161
+
-⚡**Multi-GPU Acceleration using [Neon](https://github.com/Autodesk/Neon) + Warp:** Using Neon's data structure for improved scaling.
172
162
173
163
- 🗜️ **GPU Accelerated Lossless Compression and Decompression**: Implementing high-performance lossless compression and decompression techniques for larger-scale simulations and improved performance.
0 commit comments