diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml index 3719e6e..413426d 100644 --- a/.github/workflows/mkdocs.yml +++ b/.github/workflows/mkdocs.yml @@ -2,7 +2,6 @@ name: mkdocs-deployment on: push: branches: - - master - main # paths: # - 'docs/**' diff --git a/CHANGELOG.md b/CHANGELOG.md index ed13a4f..8b25184 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] - _No changes yet_ +### Fixed +- mkdocs is now configured correctly for the new project structure + ## [0.2.0] - 2024-10-22 ### Added diff --git a/docs/assets/airfoil.png b/docs/assets/airfoil.png deleted file mode 100644 index f0ee4c9..0000000 Binary files a/docs/assets/airfoil.png and /dev/null differ diff --git a/docs/assets/car.png b/docs/assets/car.png deleted file mode 100644 index ee9f0b0..0000000 Binary files a/docs/assets/car.png and /dev/null differ diff --git a/docs/assets/cavity.gif b/docs/assets/cavity.gif deleted file mode 100644 index 7cd9bdd..0000000 Binary files a/docs/assets/cavity.gif and /dev/null differ diff --git a/docs/assets/logo-transparent.png b/docs/assets/logo-transparent.png deleted file mode 100644 index 27c8568..0000000 Binary files a/docs/assets/logo-transparent.png and /dev/null differ diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg deleted file mode 100644 index 9efe499..0000000 --- a/docs/assets/logo.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - diff --git a/docs/base.md b/docs/base.md deleted file mode 100644 index 7b848bd..0000000 --- a/docs/base.md +++ /dev/null @@ -1 +0,0 @@ -::: src.base.LBMBase \ No newline at end of file diff --git a/docs/boundary_conditions.md b/docs/boundary_conditions.md deleted file mode 100644 index 3c0d3a8..0000000 --- a/docs/boundary_conditions.md +++ /dev/null @@ -1,18 +0,0 @@ -::: src.boundary_conditions.BoundaryCondition - -::: src.boundary_conditions.BounceBack - -::: src.boundary_conditions.BounceBackMoving - -::: src.boundary_conditions.BounceBackHalfway - -::: src.boundary_conditions.EquilibriumBC - -::: src.boundary_conditions.DoNothing - -::: src.boundary_conditions.ZouHe - -::: src.boundary_conditions.Regularized - -::: src.boundary_conditions.ExtrapolationOutflow - diff --git a/docs/index.md b/docs/index.md index 54e9bbb..5a74c0d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,63 +1,139 @@ +[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![GitHub star chart](https://img.shields.io/github/stars/Autodesk/XLB?style=social)](https://star-history.com/#Autodesk/XLB)

- +

-# XLB: A Hardware-Accelerated Differentiable Lattice Boltzmann Simulation Framework based on JAX for Physics-based Machine Learning +# XLB: A Differentiable Massively Parallel Lattice Boltzmann Library in Python for Physics-Based Machine Learning -XLB (Accelerated LB) is a fully differentiable 2D/3D Lattice Boltzmann Method (LBM) solver 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. +🎉 **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! +XLB can now be installed via pip: `pip install xlb`. + +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. + +## Getting Started +To get started with XLB, you can install it using pip: +```bash +pip install xlb +``` + +To install the latest development version from source: + +```bash +pip install git+https://github.com/Autodesk/XLB.git +``` + +The changelog for the releases can be found [here](https://github.com/Autodesk/XLB/blob/main/CHANGELOG.md). + +For examples to get you started please refer to the [examples](https://github.com/Autodesk/XLB/tree/main/examples) folder. + +## Accompanying Paper + +Please refer to the [accompanying paper](https://doi.org/10.1016/j.cpc.2024.109187) for benchmarks, validation, and more details about the library. + +## Citing XLB + +If you use XLB in your research, please cite the following paper: + +``` +@article{ataei2024xlb, + title={{XLB}: A differentiable massively parallel lattice {Boltzmann} library in {Python}}, + author={Ataei, Mohammadmehdi and Salehipour, Hesam}, + journal={Computer Physics Communications}, + volume={300}, + pages={109187}, + year={2024}, + publisher={Elsevier} +} +``` ## Key Features -- **Integration with JAX Ecosystem:** The solver 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. -- **Scalability:** XLB is capable of scaling on distributed multi-GPU systems, enabling the execution of large-scale simulations with billions of voxels. +- **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. +- **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. +- **Differentiable LBM Kernels:** XLB provides differentiable LBM kernels that can be used in differentiable physics and deep learning applications. +- **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. - **Support for Various LBM Boundary Conditions and Kernels:** XLB supports several LBM boundary conditions and collision kernels. -- **User-Friendly Interface:** Written entirely in Python, XLB emphasizes a highly accessible interface that allows users to extend the solver with ease and quickly set up and run new simulations. -- **Leverages JAX Array and Shardmap:** The solver 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. +- **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. +- **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. - **Platform Versatility:** The same XLB code can be executed on a variety of platforms including multi-core CPUs, single or multi-GPU systems, TPUs, and it also supports distributed runs on multi-GPU systems or TPU Pod slices. +- **Visualization:** XLB provides a variety of visualization options including in-situ on GPU rendering using [PhantomGaze](https://github.com/loliverhennigh/PhantomGaze). -## Documentation -The documentation can be found [here](https://autodesk.github.io/XLB/) (in preparation) ## Showcase -The following examples showcase the capabilities of XLB:

- + +

+

+ On GPU in-situ rendering using PhantomGaze library (no I/O). Flow over a NACA airfoil using KBC Lattice Boltzmann Simulation with ~10 million cells. +

+ + +

+ +

+

+ DrivAer model in a wind-tunnel using KBC Lattice Boltzmann Simulation with approx. 317 million cells +

+ +

+

- Lid-driven Cavity flow at Re=100,000 (~25 million voxels) + Airflow in to, out of, and within a building (~400 million cells)

- +

- DrivAer model in a wind-tunnel using KBC Lattice Boltzmann Simulation with approx. 317 million voxels +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)

+
+

- +

- Flow over a NACA airfoil using KBC Lattice Boltzmann Simulation with approx. 100 million voxels + Lid-driven Cavity flow at Re=100,000 (~25 million cells)

## Capabilities ### LBM + - BGK collision model (Standard LBM collision model) - KBC collision model (unconditionally stable for flows with high Reynolds number) +### Machine Learning + +- Easy integration with JAX's ecosystem of machine learning libraries +- Differentiable LBM kernels +- Differentiable boundary conditions + ### Lattice Models + - D2Q9 - D3Q19 - D3Q27 (Must be used for KBC simulation runs) +### Compute Capabilities +- Single GPU support for the Warp backend with state-of-the-art performance +- Distributed Multi-GPU support using the JAX backend +- Mixed-Precision support (store vs compute) +- Out-of-core support (coming soon) + ### Output + - Binary and ASCII VTK output (based on PyVista library) +- In-situ rendering using [PhantomGaze](https://github.com/loliverhennigh/PhantomGaze) library +- [Orbax](https://github.com/google/orbax)-based distributed asynchronous checkpointing - Image Output - 3D mesh voxelizer using trimesh ### Boundary conditions + - **Equilibrium BC:** In this boundary condition, the fluid populations are assumed to be in at equilibrium. Can be used to set prescribed velocity or pressure. - **Full-Way Bounceback BC:** In this boundary condition, the velocity of the fluid populations is reflected back to the fluid side of the boundary, resulting in zero fluid velocity at the boundary. @@ -70,43 +146,46 @@ The following examples showcase the capabilities of XLB: - **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. - **Extrapolation Outflow BC:** A type of outflow boundary condition that uses extrapolation to avoid strong wave reflections. -### Compute Capabilities -- Distributed Multi-GPU support -- JAX shard-map and JAX Array support -- Mixed-Precision support (store vs compute) +- **Interpolated Bounceback BC:** Interpolated bounce-back boundary condition for representing curved boundaries. -## Installation Guide +## Roadmap -To use XLB, you must first install JAX and other dependencies using the following commands: +### Work in Progress (WIP) +*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.* -```bash -# Please refer to https://github.com/google/jax for the latest installation documentation + - 🌐 **Grid Refinement:** Implementing adaptive mesh refinement techniques for enhanced simulation accuracy. -pip install --upgrade pip + - 💾 **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). -# For CPU run -pip install --upgrade "jax[cpu]" -# For GPU run +- ⚡ **Multi-GPU Acceleration using [Neon](https://github.com/Autodesk/Neon) + Warp:** Using Neon's data structure for improved scaling. -# CUDA 12 and cuDNN 8.8 or newer. -pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html +- 🗜ī¸ **GPU Accelerated Lossless Compression and Decompression**: Implementing high-performance lossless compression and decompression techniques for larger-scale simulations and improved performance. -# CUDA 11 and cuDNN 8.6 or newer. -pip install --upgrade "jax[cuda11_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html +- 🌡ī¸ **Fluid-Thermal Simulation Capabilities:** Incorporating heat transfer and thermal effects into fluid simulations. -# Run dependencies -pip install jmp pyvista numpy matplotlib Rtree trimesh jmp -``` +- đŸŽ¯ **Adjoint-based Shape and Topology Optimization:** Implementing gradient-based optimization techniques for design optimization. -Run an example: -```bash -git clone https://github.com/Autodesk/XLB -cd XLB -export PYTHONPATH=. -python3 examples/cavity2d.py -``` -## Citing XLB -Accompanying publication coming soon: +- 🧠 **Machine Learning Accelerated Simulations:** Leveraging machine learning to speed up simulations and improve accuracy. + +- 📉 **Reduced Order Modeling using Machine Learning:** Developing data-driven reduced-order models for efficient and accurate simulations. + + +### Wishlist +*Contributions to these features are welcome. Please submit PRs for the Wishlist items.* + +- 🌊 **Free Surface Flows:** Simulating flows with free surfaces, such as water waves and droplets. + +- 📡 **Electromagnetic Wave Propagation:** Simulating the propagation of electromagnetic waves. + +- 🛩ī¸ **Supersonic Flows:** Simulating supersonic flows. + +- 🌊🧱 **Fluid-Solid Interaction:** Modeling the interaction between fluids and solid objects. + +- 🧩 **Multiphase Flow Simulation:** Simulating flows with multiple immiscible fluids. + +- đŸ”Ĩ **Combustion:** Simulating combustion processes and reactive flows. + +- đŸĒ¨ **Particle Flows and Discrete Element Method:** Incorporating particle-based methods for granular and particulate flows. -**M. Ataei, H. Salehipour**. XLB: Hardware-Accelerated, Scalable, and Differentiable Lattice Boltzmann Simulation Framework based on JAX. TBA +- 🔧 **Better Geometry Processing Pipelines:** Improving the handling and preprocessing of complex geometries for simulations. diff --git a/docs/lattice.md b/docs/lattice.md deleted file mode 100644 index ca1fcb5..0000000 --- a/docs/lattice.md +++ /dev/null @@ -1,7 +0,0 @@ -::: src.lattice.Lattice - -::: src.lattice.LatticeD2Q9 - -::: src.lattice.LatticeD3Q19 - -::: src.lattice.LatticeD3Q27 \ No newline at end of file diff --git a/docs/models.md b/docs/models.md deleted file mode 100644 index 3adf3fd..0000000 --- a/docs/models.md +++ /dev/null @@ -1,5 +0,0 @@ -::: src.models.BGKSim - -::: src.models.KBCSim - -::: src.models.AdvectionDiffusionBGK \ No newline at end of file diff --git a/docs/utils.md b/docs/utils.md deleted file mode 100644 index 79637ed..0000000 --- a/docs/utils.md +++ /dev/null @@ -1,13 +0,0 @@ -::: src.utils.downsample_field - -::: src.utils.save_image - -::: src.utils.save_fields_vtk - -::: src.utils.live_volume_randering - -::: src.utils.save_BCs_vtk - -::: src.utils.rotate_geometry - -::: src.utils.voxelize_stl diff --git a/mkdocs.yml b/mkdocs.yml index 9ff371a..70af718 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,7 +30,7 @@ repo_url: https://github.com/Autodesk/XLB edit_uri: edit/master/docs/ watch: -- ./src/ +- ./xlb/ # Can be used to add a meta tag to the HTML header site_description: 'Documentation for project XLB' @@ -147,10 +147,4 @@ extra_javascript: - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js nav: - - XLB's home: index.md - - XLB API: - - XLB base: base.md - - XLB models: models.md - - XLB lattice: lattice.md - - XLB utils: utils.md - - XLB boundary conditions: boundary_conditions.md \ No newline at end of file + - XLB's home: index.md \ No newline at end of file