{"id":18870328,"url":"https://github.com/rlguy/gridfluidsim3d","last_synced_at":"2025-04-04T22:08:20.540Z","repository":{"id":29977782,"uuid":"33524830","full_name":"rlguy/GridFluidSim3D","owner":"rlguy","description":"A PIC/FLIP fluid simulation based on the methods found in Robert Bridson's \"Fluid Simulation for Computer Graphics\"","archived":false,"fork":false,"pushed_at":"2017-10-24T18:32:35.000Z","size":1358,"stargazers_count":795,"open_issues_count":1,"forks_count":98,"subscribers_count":53,"default_branch":"master","last_synced_at":"2025-03-28T21:08:33.577Z","etag":null,"topics":["animation","fluid-simulation","simulation"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rlguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-07T05:54:12.000Z","updated_at":"2025-03-23T14:33:38.000Z","dependencies_parsed_at":"2022-08-02T01:09:37.151Z","dependency_job_id":null,"html_url":"https://github.com/rlguy/GridFluidSim3D","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlguy%2FGridFluidSim3D","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlguy%2FGridFluidSim3D/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlguy%2FGridFluidSim3D/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlguy%2FGridFluidSim3D/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rlguy","download_url":"https://codeload.github.com/rlguy/GridFluidSim3D/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"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":["animation","fluid-simulation","simulation"],"created_at":"2024-11-08T05:19:43.845Z","updated_at":"2025-04-04T22:08:20.514Z","avatar_url":"https://github.com/rlguy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GridFluidSim3d\n\nThis program is an implementation of a PIC/FLIP liquid fluid simulation written in C++11 based on methods described in Robert Bridson's \"Fluid Simulation for Computer Graphics\" textbook. The fluid simulation program outputs the surface of the fluid as a sequence of triangle meshes stored in the Stanford .PLY file format which can then be imported into your renderer of choice.\n\nVisit [http://rlguy.com/gridfluidsim/](http://rlguy.com/gridfluidsim/) for more information about the program.\n\n## Gallery\n\nThe following screencaps are of animations that were simulated within the program and rendered using [Blender](http://www.blender.org). Animations created with the fluid simulation program can be viewed on [YouTube](https://www.youtube.com/rlguyportfolio).\n\n[![alt tag](http://rlguy.com/gridfluidsim/images/fluid_text-github.jpg)](http://rlguy.com/gridfluidsim/images/fluid_text.jpg)\n\n[![alt tag](http://rlguy.com/gridfluidsim/images/bunny-github.jpg)](http://rlguy.com/gridfluidsim/images/bunny.jpg) [![alt tag](http://rlguy.com/gridfluidsim/images/splash-github.jpg)](http://rlguy.com/gridfluidsim/images/splash.jpg)\n\n[![alt tag](http://rlguy.com/gridfluidsim/images/diffuse-github.jpg)](http://rlguy.com/gridfluidsim/images/diffuse.jpg) [![alt tag](http://rlguy.com/gridfluidsim/images/diffuse_inflow-github.jpg)](http://rlguy.com/gridfluidsim/images/diffuse_inflow.jpg)\n\n[![alt tag](http://rlguy.com/gridfluidsim/images/diffuse_particles-github.jpg)](http://rlguy.com/gridfluidsim/images/diffuse_particles.jpg) [![alt tag](http://rlguy.com/gridfluidsim/images/river_rapids-github.jpg)](http://rlguy.com/gridfluidsim/images/river_rapids.jpg)\n\n[![alt tag](http://rlguy.com/gridfluidsim/images/lego_river-github.jpg)](http://rlguy.com/gridfluidsim/images/lego_river.jpg) [![alt tag](http://rlguy.com/gridfluidsim/images/lego_sphere-github.jpg)](http://rlguy.com/gridfluidsim/images/lego_sphere.jpg)\n\n[![alt tag](http://rlguy.com/gridfluidsim/images/orbit-github.jpg)](http://rlguy.com/gridfluidsim/images/orbit.jpg) [![alt tag](http://rlguy.com/gridfluidsim/images/warped_gravity-github.jpg)](http://rlguy.com/gridfluidsim/images/warped_gravity.jpg)\n\n## Features\nBelow is a list of features implemented in the simulator.\n\n* Isotropic and anisotropic particle to mesh conversion\n* Spray, bubble, and foam particle simulation\n* 'LEGO' brick surface reconstruction\n* Save and load state of a simulation\n* GPU accelerated fourth-order Runge-Kutta integration using OpenCL\n* GPU accelerated velocity advection using OpenCL\n* Python bindings\n\n## Dependencies\n\nThere are three dependencies that are required to build this program:\n\n1. OpenCL headers (can be found at [khronos.org](https://www.khronos.org/registry/cl/))\n2. An OpenCL SDK specific to your GPU vender (AMD, NVIDIA, Intel, etc.)\n3. A compiler that supports C++11\n\n## Installation\n\nThis program uses the [CMake](https://cmake.org/) utility to generate the appropriate solution, project, or Makefiles for your system. The following commands can be executed in the root directory of the project to generate a build system for your machine:\n\n```\nmkdir build \u0026\u0026 cd build\ncmake ..\n```\n\nThe first line creates a new directory named ```build``` and changes the working directory to the newly created build directory. The second line runs the CMake utility and passes it the parent directory which contains the ```CMakeLists.txt``` file.\n\nThe type of build system generated by CMake can be specified with the ```-G [generator]``` parameter. For example:\n\n```\ncmake .. -G \"MinGW Makefiles\"\n```\n\nwill generate Makefiles for the MinGW compiler which can then be built using the [GNU Make](https://www.gnu.org/software/make/) utility with the command ```make```. A list of CMake generators can be found [here](https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html).\n\nOnce successfully built, the program will be located in the ```build/fluidsim/``` directory with the following directory structure:\n\n```\nfluidsim\n│   fluidsim.a      - Runs program configured in main.cpp     \n│\n└───output          - Stores data output by the simulation program\n│   └───bakefiles       - meshes\n│   └───logs            - logfiles\n│   └───savestates      - simulation save states\n│   └───temp            - temporary files created by the simulation program\n│    \n└───pyfluid         - The pyfluid Python package\n    └───examples        - pyfluid example usage\n    └───lib             - C++ library files\n```\n\n## Configuring the Fluid Simulator\n\nThe fluid simulator can be configured by manipulating a FluidSimulation object in the function ```main()``` located in the file [src/main.cpp](src/main.cpp). After building the project, the fluid simulation exectuable will be located in the ```fluidsim/``` directory. Example configurations are located in the [src/examples/cpp/](src/examples/cpp) directory. Some documentation on the public methods for the FluidSimulation class is provided in the [fluidsimulation.h](src/fluidsimulation.h) header.\n\nA fluid simulation can also be configured and run within a Python script by importing the ```pyfluid``` package, which will be located in the ```fluidsim/``` directory after building the project. Example scripts are located in the [src/examples/python/](src/examples/python) directory.\n\nThe following two sections will demonstrate how to program a simple \"Hello World\" simulation using either C++ or Python.\n\n### Hello World (C++)\n\nThis is a very basic example of how to use the FluidSimulation class to run a simulation. The simulation in this example will drop a ball of fluid in the center of a cube shaped fluid domain. This example is relatively quick to compute and can be used to test if the simulation program is running correctly.\n\nThe fluid simulator performs its computations on a 3D grid, and because of this the simulation domain is shaped like a rectangular prism. The FluidSimulation class can be initialized with four parameters: the number of grid cells in each direction x, y, and z, and the width of a grid cell.\n\n```c++\nint xsize = 32;\nint ysize = 32;\nint zsize = 32;\ndouble cellsize = 0.25;\nFluidSimulation fluidsim(xsize, ysize, zsize, cellsize);\n```\n\nWe want to add a ball of fluid to the center of the fluid domain, so we will need to get the dimensions of the domain by calling `getSimulationDimensions` and passing it pointers to store the width, height, and depth values. Alternatively, the dimensions can be calculated by multiplying the cell width by the corresponding number of cells in a direction (e.g. `width = dx*isize`).\n\n```c++\ndouble width, height, depth;\nfluidsim.getSimulationDimensions(\u0026width, \u0026height, \u0026depth);\n```\n\nNow that we have the dimensions of the simulation domain, we can calculate the center, and add a ball of fluid by calling `addImplicitFluidPoint` which takes the x, y, and z position and radius as parameters. \n\n```c++\ndouble centerx = width / 2;\ndouble centery = height / 2;\ndouble centerz = depth / 2;\ndouble radius = 6.0;\nfluidsim.addImplicitFluidPoint(centerx, centery, centerz, radius);\n```\n\nAn important note to make about `addImplicitFluidPoint` is that it will not add a sphere with the specified radius, it will add a sphere with half of the specified radius. An implicit fluid point is represented as a field of values on the simulation grid. The strength of the field values are 1 at the point center and falls off towards 0 as distance from the point increases. When the simulation is initialized, fluid particles will be created in regions where the field values are greater than `0.5`. This means that if you add a fluid point with a radius of `6.0`, the ball of fluid in the simulation will actually be of radius `3.0` since field values will be less than `0.5` at a distance greater than half of the specified radius.\n\nThe FluidSimulation object now has a domain containing some fluid, but the current simulation will not be very interesting as there are no forces acting upon the fluid. We can add the force of gravity by making a call to `addBodyForce` which takes three values representing a force vector as parameters. We will set the force of gravity to point downwards with a value of `25.0`.\n\n```c++\ndouble gx = 0.0;\ndouble gy = -25.0;\ndouble gz = 0.0;\nfluidsim.addBodyForce(gx, gy, gz);\n```\n\nNow we have a simulation domain with some fluid, and a force acting on the fluid. Before we run the simulation, a call to `initialize` must be made. Note that any calls to `addImplicitFluidPoint ` must be made before `initialize` is called.\n\n```c++\nfluidsim.initialize();\n```\n\nWe will now run the simulation for a total of 30 animation frames at a rate of 30 frames per second by repeatedly making calls to the `update` function. The `update` function advances the state of the simulation by a specified period of time. To update the simulation at a rate of 30 frames per second, each call to `update` will need to be supplied with a time value of `1.0/30.0.` Each call to update will generate a triangle mesh that represents the fluid surface. The mesh files will be saved in the ```output/bakefiles/``` directory as a numbered sequence of files stored in the Stanford .PLY file format.\n\n```c++\ndouble timestep = 1.0 / 30.0;\nint numframes = 30;\nfor (int i = 0; i \u003c numframes; i++) {\n    fluidsim.update(timestep);\n}\n```\n\nAs this loop runs, the program should output simulation stats and timing metrics to the terminal. After the loop completes, the ```output/bakefiles/``` directory should contain 30 .PLY triangle meshes numbered in sequence from 0 to 29: `000000.ply, 000001.ply, 000002.ply, ..., 000028.ply, 000029.ply`.\n\nIf you open the `000029.ply` mesh file in a 3D modelling package such as [Blender](http://www.blender.org), the mesh should look similar to [this image](http://rlguy.com/gridfluidsim/images/hello_world_frame30.jpg).\n\nThe fluid simulation in this example is quick to compute, but of low quality due to the low resolution of the simulation grid. The quality of this simulation can be improved by increasing the simulation dimensions while decreasing the cell size. For example, try simulating on a grid of resolution `64 x 64 x 64` with a cell size of `0.125`, or even better, on a grid of resolution `128 x 128 x 128` with a cell size of `0.0625`.\n\n### Hello World (Python)\n\nThe following Python script will run the equivalent simulation described in the previous section.\n\n```python\nfrom pyfluid import FluidSimulation\n\nfluidsim = FluidSimulation(32, 32, 32, 0.25)\n\nwidth, height, depth = fluidsim.get_simulation_dimensions()\nfluidsim.add_implicit_fluid_point(width / 2, height / 2, depth / 2, 6.0)\nfluidsim.add_body_force(0.0, -25.0, 0.0)\nfluidsim.initialize();\n\nfor i in range(30):\n    fluidsim.update(1.0 / 30)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlguy%2Fgridfluidsim3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frlguy%2Fgridfluidsim3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlguy%2Fgridfluidsim3d/lists"}