{"id":18978247,"url":"https://github.com/autodesk/xlb","last_synced_at":"2025-05-15T14:04:57.792Z","repository":{"id":164038356,"uuid":"636368696","full_name":"Autodesk/XLB","owner":"Autodesk","description":"XLB: Accelerated Lattice Boltzmann (XLB) for Physics-based ML","archived":false,"fork":false,"pushed_at":"2025-05-05T18:47:07.000Z","size":75219,"stargazers_count":349,"open_issues_count":12,"forks_count":45,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-10T20:46:06.716Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Autodesk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-04T17:36:58.000Z","updated_at":"2025-05-09T10:34:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"b57e26c1-a7d1-4c41-9fd0-76035aefe0f0","html_url":"https://github.com/Autodesk/XLB","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2FXLB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2FXLB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2FXLB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2FXLB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Autodesk","download_url":"https://codeload.github.com/Autodesk/XLB/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355334,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T15:32:45.335Z","updated_at":"2025-05-15T14:04:52.776Z","avatar_url":"https://github.com/Autodesk.png","language":"Python","readme":"[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![GitHub star chart](https://img.shields.io/github/stars/Autodesk/XLB?style=social)](https://star-history.com/#Autodesk/XLB)\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/logo-transparent.png\" alt=\"\" width=\"300\"\u003e\n\u003c/p\u003e\n\n# XLB: A Differentiable Massively Parallel Lattice Boltzmann Library in Python for Physics-Based Machine Learning\n\n🎉 **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! \nXLB can now be installed via pip: `pip install xlb`.\n\nXLB 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.\n\n## Getting Started\nTo get started with XLB, you can install it using pip. There are different installation options depending on your hardware and needs:\n\n### Basic Installation (CPU-only)\n```bash\npip install xlb\n```\n\n### Installation with CUDA support (for NVIDIA GPUs)\nThis installation is for the JAX backend with CUDA support:\n```bash\npip install \"xlb[cuda]\"\n```\n\n### Installation with TPU support\nThis installation is for the JAX backend with TPU support:\n```bash\npip install \"xlb[tpu]\"\n```\n\n### Notes:\n- For Mac users: Use the basic CPU installation command as JAX's GPU support is not available on MacOS\n- The NVIDIA Warp backend is included in all installation options and supports CUDA automatically when available\n- The installation options for CUDA and TPU only affect the JAX backend\n\nTo install the latest development version from source:\n\n```bash\npip install git+https://github.com/Autodesk/XLB.git\n```\n\nThe changelog for the releases can be found [here](https://github.com/Autodesk/XLB/blob/main/CHANGELOG.md).\n\nFor examples to get you started please refer to the [examples](https://github.com/Autodesk/XLB/tree/main/examples) folder.\n\n## Accompanying Paper\n\nPlease refer to the [accompanying paper](https://doi.org/10.1016/j.cpc.2024.109187) for benchmarks, validation, and more details about the library.\n\n## Citing XLB\n\nIf you use XLB in your research, please cite the following paper:\n\n```\n@article{ataei2024xlb,\n  title={{XLB}: A differentiable massively parallel lattice {Boltzmann} library in {Python}},\n  author={Ataei, Mohammadmehdi and Salehipour, Hesam},\n  journal={Computer Physics Communications},\n  volume={300},\n  pages={109187},\n  year={2024},\n  publisher={Elsevier}\n}\n```\n\n## Key Features\n- **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.\n- **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.\n- **Differentiable LBM Kernels:** XLB provides differentiable LBM kernels that can be used in differentiable physics and deep learning applications.\n- **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.\n- **Support for Various LBM Boundary Conditions and Kernels:** XLB supports several LBM boundary conditions and collision kernels.\n- **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.\n- **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.\n- **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.\n- **Visualization:** XLB provides a variety of visualization options including in-situ on GPU rendering using [PhantomGaze](https://github.com/loliverhennigh/PhantomGaze).\n\n## Showcase\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/wind_turbine.gif\" alt=\"Wind Turbine Simulation\" width=\"800\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Simulation of a wind turbine based on the immersed boundary method.\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/airfoil.gif\" width=\"800\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  On GPU in-situ rendering using \u003ca href=\"https://github.com/loliverhennigh/PhantomGaze\"\u003ePhantomGaze\u003c/a\u003e library (no I/O). Flow over a NACA airfoil using KBC Lattice Boltzmann Simulation with ~10 million cells.\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/car.png\" alt=\"\" width=\"500\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=https://www.epc.ed.tum.de/en/aer/research-groups/automotive/drivaer \u003e DrivAer model \u003c/a\u003e in a wind-tunnel using KBC Lattice Boltzmann Simulation with approx. 317 million cells\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/building.png\" alt=\"\" width=\"700\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Airflow in to, out of, and within a building (~400 million cells)\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/XLB_diff.png\" alt=\"\" width=\"900\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nThe 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)\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/autodesk/xlb/main/assets/cavity.gif\" alt=\"\" width=\"500\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Lid-driven Cavity flow at Re=100,000 (~25 million cells)\n\u003c/p\u003e\n\n## Capabilities \n\n### LBM\n\n- BGK collision model (Standard LBM collision model)\n- KBC collision model (unconditionally stable for flows with high Reynolds number)\n\n### Machine Learning\n\n- Easy integration with JAX's ecosystem of machine learning libraries\n- Differentiable LBM kernels\n- Differentiable boundary conditions\n\n### Lattice Models\n\n- D2Q9\n- D3Q19\n- D3Q27 (Must be used for KBC simulation runs)\n\n### Compute Capabilities\n- Single GPU support for the Warp backend with state-of-the-art performance\n- Distributed Multi-GPU support using the JAX backend\n- Mixed-Precision support (store vs compute)\n- Out-of-core support (coming soon)\n\n### Output\n\n- Binary and ASCII VTK output (based on PyVista library)\n- In-situ rendering using [PhantomGaze](https://github.com/loliverhennigh/PhantomGaze) library\n- [Orbax](https://github.com/google/orbax)-based distributed asynchronous checkpointing\n- Image Output\n- 3D mesh voxelizer using trimesh\n\n### Boundary conditions\n\n- **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.\n\n- **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.\n\n- **Half-Way Bounceback BC:** Similar to the Full-Way Bounceback BC, in this boundary condition, the velocity of the fluid populations is partially reflected back to the fluid side of the boundary, resulting in a non-zero fluid velocity at the boundary.\n\n- **Do Nothing BC:** In this boundary condition, the fluid populations are allowed to pass through the boundary without any reflection or modification.\n\n- **Zouhe BC:** This boundary condition is used to impose a prescribed velocity or pressure profile at the boundary.\n- **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.\n- **Extrapolation Outflow BC:** A type of outflow boundary condition that uses extrapolation to avoid strong wave reflections.\n\n- **Interpolated Bounceback BC:** Interpolated bounce-back boundary condition for representing curved boundaries.\n\n## Roadmap\n\n### Work in Progress (WIP)\n*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.*\n\n - 🌐 **Grid Refinement:** Implementing adaptive mesh refinement techniques for enhanced simulation accuracy.\n\n - 💾 **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).\n\n\n- ⚡ **Multi-GPU Acceleration using [Neon](https://github.com/Autodesk/Neon) + Warp:** Using Neon's data structure for improved scaling.\n\n- 🗜️ **GPU Accelerated Lossless Compression and Decompression**: Implementing high-performance lossless compression and decompression techniques for larger-scale simulations and improved performance.\n\n- 🌡️ **Fluid-Thermal Simulation Capabilities:** Incorporating heat transfer and thermal effects into fluid simulations.\n\n- 🎯 **Adjoint-based Shape and Topology Optimization:** Implementing gradient-based optimization techniques for design optimization.\n\n- 🧠 **Machine Learning Accelerated Simulations:** Leveraging machine learning to speed up simulations and improve accuracy.\n\n- 📉 **Reduced Order Modeling using Machine Learning:** Developing data-driven reduced-order models for efficient and accurate simulations.\n\n\n### Wishlist\n*Contributions to these features are welcome. Please submit PRs for the Wishlist items.*\n\n- 🌊 **Free Surface Flows:** Simulating flows with free surfaces, such as water waves and droplets.\n\n- 📡 **Electromagnetic Wave Propagation:** Simulating the propagation of electromagnetic waves.\n\n- 🛩️ **Supersonic Flows:** Simulating supersonic flows.\n\n- 🌊🧱 **Fluid-Solid Interaction:** Modeling the interaction between fluids and solid objects.\n\n- 🧩 **Multiphase Flow Simulation:** Simulating flows with multiple immiscible fluids.\n\n- 🔥 **Combustion:** Simulating combustion processes and reactive flows.\n\n- 🪨 **Particle Flows and Discrete Element Method:** Incorporating particle-based methods for granular and particulate flows.\n\n- 🔧 **Better Geometry Processing Pipelines:** Improving the handling and preprocessing of complex geometries for simulations.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautodesk%2Fxlb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautodesk%2Fxlb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautodesk%2Fxlb/lists"}