{"id":48319555,"url":"https://github.com/mladenivkovic/hydro-playground","last_synced_at":"2026-04-05T00:36:50.899Z","repository":{"id":212494324,"uuid":"731628667","full_name":"mladenivkovic/hydro-playground","owner":"mladenivkovic","description":"A simple unigrid 2D hydrodynamics solver in C++, intended as a playground for single-node optimization and parallelism","archived":false,"fork":false,"pushed_at":"2025-08-27T09:15:03.000Z","size":1001,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-27T18:24:49.305Z","etag":null,"topics":["cfd","cpp","finite-volume-methods","hydrodynamics","optimization"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mladenivkovic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-14T14:05:42.000Z","updated_at":"2025-04-28T23:48:18.000Z","dependencies_parsed_at":"2025-02-15T01:18:47.978Z","dependency_job_id":"b3370eec-310b-47e4-b640-8300eb1cc8cc","html_url":"https://github.com/mladenivkovic/hydro-playground","commit_stats":null,"previous_names":["mladenivkovic/hydro-playground"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mladenivkovic/hydro-playground","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mladenivkovic%2Fhydro-playground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mladenivkovic%2Fhydro-playground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mladenivkovic%2Fhydro-playground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mladenivkovic%2Fhydro-playground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mladenivkovic","download_url":"https://codeload.github.com/mladenivkovic/hydro-playground/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mladenivkovic%2Fhydro-playground/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31420402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cfd","cpp","finite-volume-methods","hydrodynamics","optimization"],"created_at":"2026-04-05T00:36:50.162Z","updated_at":"2026-04-05T00:36:50.888Z","avatar_url":"https://github.com/mladenivkovic.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"hydro-playground\n================\n\n\n`hydro-playground` is a simple C++ toy code solving finite volume hydrodynamics in 2D on a uniform\ngrid. The main goal is to have simple working code as a playground for developments in terms of\nacceleration, optimisation, and parallelisation.\n\n\nIt is based on the [mesh-hydro](https://github.com/mladenivkovic/mesh-hydro) code, which is a\nplayground to learn about and experiment with numerical methods to solve hyperbolic conservation\nlaws, in particular the advection equation and the Euler equations of ideal gases.\n\n\nContents\n----------------------------\n\n- `./examples`: Some ready-to-go example simulations.\n- `./python_module`: A git submodule containing the\n  [mesh_hydro_utils](https://github.com/mladenivkovic/mesh_hydro_utils) python module. It contains\n  convenience functions to generate initial conditions, plot ICs and outputs, and a Riemann solver.\n  Note that you need to install it first for it to work. Instructions are given\n  [below](#Getting-And-Installing-The-Python-Module).\n- `./src`: contains the actual software.\n- `./doc`: Documentation of the code and theory on the equations being solved.\n- `./tests`: Unit tests and functional tests.\n\n\n\nGetting Started\n---------------\n\n### Requirements\n\n- `git` to obtain the code.\n- A good old C++ compiler. Code is written in C++20 standard.\n- `cmake` 3.21 or above\n- (optional) `python 3` with `numpy` and `matplotlib` for plotting outputs and generating initial\n  conditions. Additionally with `sphinx` to build the parallelisation documentation.\n- (optional) LaTeX to create the TeX files. I hard-coded the `pdflatex` command in the scripts. It\n  doesn't require any fancy LaTeX packages.\n\n\n\n### Getting The Code\n\nYou can get the code from the github repository:\n\n```\ngit clone https://github.com/mladenivkovic/hydro-playground.git\n```\n\nfor `https` protocol or\n\n```\ngit clone git@github.com:mladenivkovic/hydro-playground.git\n```\n\nfor `ssh`.\n\n\n\n\n### Getting And Installing The Python Module\n\nThe entire python module is stored within this repository as a git submodule of its\n[own repository](https://github.com/mladenivkovic/mesh_hydro_utils).\n\nOnce you've cloned the hydro-playground repository, you'll also need to tell git to grab the\nsubmodules using\n\n```\ngit submodule init\ngit submodule update\n```\n\nWhen completed successfully, the directory `./python_module` should now contain some files. We now\nneed to install this python module.\n\nThe easiest way is to navigate into the directory and install it locally using e.g. `pip`:\n\n```\ncd python_module\npip install -e .\n```\n\nAlternatively (***albeit very discouraged***), you can add the directory\n`./python_module/mesh_hydro_utils` to your `$PYTHONPATH`.\n\n\n\n\n### Getting the Documentation\n\nCheck the documentation in `doc/tex/documentation`. You can build it using the provided `Makefile`:\n\n```\ncd hydro_playground/doc/tex/documentation\nmake\n```\n\nThat should leave you with the resulting `documentation.pdf` file.\n\nAlternately, you can run the latex compile command by hand:\n\n```\ncd hydro_playground/doc/tex/documentation\npdflatex -jobname=documentation documentation.tex\n```\n\nor open the main TeX document, `hydro_playground/doc/tex/documentation/documentation.tex` with your\nfavourite TeX IDE/Editor.\n\n\n\nThere is also documentation on parallelisation strategies and paradigms in `hydro_playgournd/doc/rtd`.\nYou can build `html` or `latex-pdf` outputs using:\n\n```\ncd doc/rtd\nmake html                      # to make html documentation\nfirefox build/html/index.html  # to view the resulting documentation using firefox\n```\n\nfor `html` outputs, or\n\n```\ncd doc/rtd\nmake latexpdf                                           # to make latex pdf documentation\nokular build/latex/hydro_playground_paralleisation.pdf  # to view the resulting documentation using okular\n```\n\n\n\n### Building the Project\n\nWe build the project using `cmake`:\n\n```\ncd hyrdo_playground\nmkdir build\ncd build\ncmake ..\ncmake --build .\n```\n\nor, if you prefer:\n\n```\ncd hyrdo_playground\ncmake -B build\ncmake --build build\n```\n\nThat should leave you with an executable file `hydro` in the directory `hydro_playground/build/`.\n\n\n\n\n### Build Options\n\nYou can pass build options to `cmake` by giving it a list of command line arguments beginning with\n`-D` at build time, e.g.\n\n```\ncd hyrdo_playground\nmkdir build\ncd build\ncmake .. -DOPTION1 -DOPTION2 ...\ncmake --build .\n```\n\nor, if you prefer:\n\n```\ncd hyrdo_playground\ncmake -B build -DOPTION1 -DOPTION2 ...\ncmake --build build\n```\n\n\nCurrently available build options are:\n\n- `-DBUILD_TYPE=` [`Release`, `RelWithDebInfo`, `Debug`] : (Default = `Release`)\n  - Build type of the project.\n  - `Release`: Enables aggressive compiler optimisation. This is the default mode.\n  - `RelWithDebInfo`: Release mode, but with debugging symbols attached. Also activates some light\n    debugging checks.\n  - `Debug`: Turns compiler optimisation off and enables extensive debugging checks.\n\n- `-DPRECISION=` [`SINGLE`, `DOUBLE`]: (Default=`DOUBLE`)\n  - Set precision for floating point variables.\n  - `SINLGE`: Single-precision floats.\n  - `DOUBLE`: Double-precision floats (Default)\n\n- `-DTERMINAL_COLORS=ON`: Enable coloured output to `stdout` and `stderr` on terminals.\n\n- `-DSOLVER=` [`MUSCL`, `GODUNOV`]: (Default=`MUSCL`)\n  - Select hydrodynamics solver.\n  - `MUSCL`: MUSCL-Hancock solver (second order accurate)\n  - `GODUNOV`: Godunov solver (first order accurate)\n\n- `-DRIEMANN=` [`HLLC`, `EXACT`]: (Default=`HLLC`)\n  - Select Riemann solver.\n  - `HLLC`: Harten-Lax-van Leer with central wave (approximate solver)\n  - `EXACT`: Exact Riemann solver.\n\n- `-DLIMITER=` [`MINMOD`, `VANLEER`]: (Default = `VANLEER`):\n  - Select slope limiter for MUSCL-Hancock solver.\n  - `MINMOD`: Minmod limiter.\n  - `EXACT`: Exact Riemann solver.\n\n\n\n\n### Running an Example\n\nOnce you've compiled the code following the steps in the previous sections\n([download](#obtaining-the-code) and [install](#building-the-project)), you're ready to run your\nfirst example.\n\nA successful compilation will leave you with an executable `hydro_playground/build/hydro`. To\nactually run the code, you need to provide it with two mandatory command line arguments: A\nsimulation parameter file ([see below for format specification](#parameter-file)) and an initial\nconditions file ([see below for format specifications](#initial-conditions)).\n\nYou can specify them as follows:\n\n```\n./hydro --ic-file \u003cic_file\u003e --param-file \u003cparam_file\u003e\n```\n\nor\n\n```\n./hydro --ic-file=\u003cic_file\u003e --param-file=\u003cparam_file\u003e\n```\n\nwhere `\u003cic_file\u003e` is the path to the [initial conditions](#initial-conditions) file you want to use,\nand `\u003cparam_file\u003e` is the path to the [parameter file](#parameter-file) you want to use.\n\nYou may want to look into the `hydro_playground/examples` directory for some ready-to-go examples.\n\n\n\n\n\nFile Format Specifications\n----------------------------\n\n\n### Parameter File\n\n#### Talking Parameters\n\n| name          |  default value    | type  | description                                                                   |\n|---------------|-------------------|-------|-------------------------------------------------------------------------------|\n| `verbose`     | = 0               | `int` | How talkative the code should be. 0 = quiet, 1 = talky, 2 = no secrets, 3 = debugging        |\n|               |                   |       |                                                                               |\n| `nstep_log`   | = 0               | `int` | Write log messages only ever `nstep_log` steps. If 0, will write every step.  |\n|               |                   |       |                                                                               |\n\n\n\n#### Simulation Parameters\n\n| name              |  default value    | type  | description                                                                   |\n|-------------------|-------------------|-------|-------------------------------------------------------------------------------|\n| `nx`              | = 0               | `int` | Number of cells to use if you're running with a two-state type IC file. Otherwise, it needs to be specified in the initial conditions.  If you're not using a two-state IC, the value will be overwritten by the value given in the IC file.  |\n|                   |                   |       |                                                                               |\n| `ccfl`            | = 0.9             |`float`| Courant factor; `dt = ccfl * dx / vmax`                                       |\n|                   |                   |       |                                                                               |\n| `nsteps`          | = 0               | `int` | Up to how many steps to do. If = 0, run until `t \u003e= tmax`                     |\n|                   |                   |       |                                                                               |\n| `tmax`            | = 0.              |`float`| Up to which time to simulate. If `nsteps` is given, will stop running if `nsteps` steps are reached before `tmax` is.     |\n|                   |                   |       |                                                                               |\n| `boundary`        | = 0               | `int` | Boundary conditions  0: periodic. 1: reflective. 2: transmissive. This sets the boundary conditions for all walls. |\n|                   |                   |       |                                                                               |\n| `boxsize`         | = 1.              |`float`| Size of the simulation box in each dimension. Currently unused.               |\n|                   |                   |       |                                                                               |\n| `replicate`       | = 0               | `int` | When running with [arbitrary-type initial conditions](#arbitrary-type-ics), replicate (= copy-paste) the initial conditions this many times in each dimension. This is not used for the [two-state type ICs](#two-state-type-ics) because there you can simply specify the `nx` parameter as you wish. |\n|                   |                   |       |                                                                               |\n\n\n\n#### Output Parameters\n\n\n| name          |  default value    | type    | description                                                                   |\n|---------------|-------------------|---------|-------------------------------------------------------------------------------|\n| `foutput`     | = 0               | `int`   | Frequency of writing outputs in number of steps. If = 0, will only write initial and final steps.  |\n|               |                   |         |                                                                               |\n| `dt_out`      | = 0               |`float`  | Frequency of writing outputs in time intervals. Code will always write initial and final steps as well.  |\n|               |                   |         |                                                                               |\n\u003c!--\n| `toutfile`    | None              |`string` | File name containing desired times (in code units) of output. Syntax of the file: One float per line with increasing value.  |\n|               |                   |         |                                                                               |\n--\u003e\n| `basename`    | None              |`string` | Basename for outputs.  If not given, a basename will be generated based on compilation parameters and IC filename.       |\n|               |                   |         |                                                                               |\n| `write_replications` | false      | `bool`  | If `replicate \u003e 1`, setting this to true will write the entire content of the box, including all replications. |\n|               |                   |         |                                                                               |\n\n\n\u003c!---\n#### Source Term Parameters\n\nThe source term related options will only take effect if the code has been compiled to add source terms.\n\n\n| name              |  default value    | type   | description                                                                   |\n|-------------------|-------------------|--------|-------------------------------------------------------------------------------|\n| `src_const_acc_x` | = 0               | `float`| constant acceleration in x direction for constant source terms                |\n|                   |                   |        |                                                                               |\n| `src_const_acc_y` | = 0               | `float`| constant acceleration in y direction for constant source terms                |\n|                   |                   |        |                                                                               |\n| `src_const_acc_r` | = 0               | `float`| constant acceleration in radial direction for radial source terms             |\n|                   |                   |        |                                                                               |\n--\u003e\n\n\n\n\n\n\n### Initial Conditions\n\nIn contrast to [mesh-hydro](https://github.com/mladenivkovic/mesh-hydro), `hydro-playground` only\nruns 2D examples, and hence only uses 2D initial conditions.\n\n- The program reads two types of IC files.\n- In any case, they're expected to be formatted text.\n- In both IC file types, lines starting with `//` or `/*` will be recognized as comments and\n  skipped. Empty lines are skipped as well.\n- Some example python scripts that generate initial conditions are given in\n  `./python_module/scripts/IC`. Note that for the directory `./python_module/`\n  to contain any files, you first need to initialize the submodule. See the instructions\n  [above](#Getting-And-Installing-The-Python-Module).\n\n\n#### Two-state Type ICs\n\nYou can use a Riemann-problem two-state initial condition file as follows:\n\n```\nfiletype = two-state\nrho_L   = \u003cfloat\u003e\nv_L     = \u003cfloat\u003e\np_L     = \u003cfloat\u003e\nrho_R   = \u003cfloat\u003e\nv_R     = \u003cfloat\u003e\np_R     = \u003cfloat\u003e\n```\n\nThe line\n```\nfiletype = two-state\n```\n\n**must** be the first non-comment non-empty line, followed by `rho_L`, `v_L`, `p_L`, `rho_R`, `v_R`,\n`p_R`.\n\nThe discontinuity between the changes will be in the middle along the `x`-axis. Fluid velocity in `y`\ndirection will be set to zero, `v_L` and `v_R` will be set as `v_x`.\n\nNote: For \"historical\" reasons, the velocities can also be specified as `u_L` and `u_R` instead of\n`v_L` and `v_R`, respectively.\n\n\n\n\n#### Arbitrary Type ICs\n\nYou can provide an individual value for density, velocity, and pressure for each cell. The IC file\nformat is:\n\nThe lines\n```\nfiletype = arbitrary\nnx = \u003cint\u003e\nndim = \u003cint\u003e\n```\n\n**must** be the first non-comment non-empty lines, in that order. `ndim` **must** be 2, as\n`hydro-plaground` only runs in 2D.\n\nThe IC format is as follows:\n\n\n```\nfiletype = arbitrary\nnx = \u003cinteger, number of cells in any dimension\u003e\nndim = 2\n\u003cdensity in cell (0, 0)\u003e       \u003cx velocity in cell (0, 0)\u003e      \u003cy velocity in cell (0, 0)\u003e        \u003cpressure in cell (0, 0)\u003e\n\u003cdensity in cell (1, 0)\u003e       \u003cx velocity in cell (1, 0)\u003e      \u003cy velocity in cell (1, 0)\u003e        \u003cpressure in cell (1, 0)\u003e\n                                     .\n                                     .\n                                     .\n\u003cdensity in cell (nx-1, 0)\u003e     \u003cx velocity cell (nx-1, 0)\u003e     \u003cy velocity in cell (nx-1, 0)\u003e     \u003cpressure in cell (nx-1, 0)\u003e\n\u003cdensity in cell (0, 1)\u003e        \u003cx velocity in cell (0, 1)\u003e     \u003cy velocity in cell (0, 1)\u003e        \u003cpressure in cell (0, 1)\u003e\n\u003cdensity in cell (1, 1)\u003e        \u003cx velocity in cell (1, 1)\u003e     \u003cy velocity in cell (1, 1)\u003e        \u003cpressure in cell (1, 1)\u003e\n                                     .\n                                     .\n                                     .\n\u003cdensity in cell (nx-1, 1)\u003e     \u003cx velocity cell (nx-1, 1)\u003e     \u003cy velocity in cell (nx-1, 1)\u003e     \u003cpressure in cell (nx-1, nx-1)\u003e\n                                     .\n                                     .\n                                     .\n\u003cdensity in cell (0, nx-1)\u003e     \u003cx velocity in cell (0, nx-1)\u003e  \u003cy velocity in cell (0, nx-1)\u003e     \u003cpressure in cell (0, nx-1)\u003e\n\u003cdensity in cell (1, nx-1)\u003e     \u003cx velocity in cell (1, nx-1)\u003e  \u003cy velocity in cell (1, nx-1)\u003e     \u003cpressure in cell (1, nx-1)\u003e\n                                     .\n                                     .\n                                     .\n\u003cdensity in cell (nx-1, nx-1)\u003e  \u003cx velocity cell (nx-1, nx-1)\u003e  \u003cy velocity in cell (nx-1, nx-1)\u003e  \u003cpressure in cell (nx-1, nx-1)\u003e\n```\n\n`cell (0, 0)` is the lower left corner of the box. First index is x direction, second is y. All\nvalues for density, velocity, and pressure must be floats. You can put comments and empty lines\nwherever you feel like it.\n\n\n\n\n\n\n\n\n### Output Files\n\n\nIf no `basename` is given in the parameter file, the output file name will be generated as follows:\n\n```\noutput_XXXX.out\n```\n\nwhere `XXXX` is the snapshot/output number.\n\n\nThe output files are written in plain text, and their content should be self-explanatory:\n\n\n```\n# ndim =  2\n# nx =    \u003cnumber of cells used\u003e\n# t =     \u003ccurrent time, float\u003e\n# nsteps =  \u003ccurrent step of the simulation\u003e\n#            x            y          rho          v_x          v_y            p\n\u003cx value of cell (0, 0)\u003e \u003cy value of cell (0, 0)\u003e \u003cdensity in cell (0, 0)\u003e \u003cx velocity in cell (0, 0)\u003e \u003cy velocity in cell (0, 0)\u003e \u003cpressure in cell (0, 0)\u003e\n\u003cx value of cell (1, 0)\u003e \u003cy value of cell (1, 0)\u003e \u003cdensity in cell (1, 0)\u003e \u003cx velocity in cell (1, 0)\u003e \u003cy velocity in cell (1, 0)\u003e \u003cpressure in cell (1, 0)\u003e\n                                                 .\n                                                 .\n                                                 .\n\u003cx value of cell (nx-1, 0)\u003e \u003cy value of cell (nx-1, 0)\u003e \u003cdensity in cell (nx-1, 0)\u003e \u003cx velocity cell (nx-1, 0)\u003e \u003cy velocity in cell (nx-1, 0)\u003e \u003cpressure in cell (nx-1, 0)\u003e\n\u003cx value of cell (0, 1)\u003e \u003cy value of cell (0, 1)\u003e \u003cdensity in cell (0, 1)\u003e \u003cx velocity in cell (0, 1)\u003e \u003cy velocity in cell (0, 1)\u003e \u003cpressure in cell (0, 1)\u003e\n\u003cx value of cell (1, 1)\u003e \u003cy value of cell (1, 1)\u003e \u003cdensity in cell (1, 1)\u003e \u003cx velocity in cell (1, 1)\u003e \u003cy velocity in cell (1, 1)\u003e \u003cpressure in cell (1, 1)\u003e\n                                                 .\n                                                 .\n                                                 .\n\u003cx value of cell (nx-1, 1)\u003e \u003cy value of cell (nx-1, 1)\u003e \u003cdensity in cell (nx-1, 1)\u003e \u003cx velocity cell (nx-1, 1)\u003e \u003cy velocity in cell (nx-1, 1)\u003e \u003cpressure in cell (nx-1, nx-1)\u003e\n                                                 .\n                                                 .\n                                                 .\n\u003cx value of cell (0, nx-1)\u003e \u003cy value of cell (0, nx-1)\u003e \u003cdensity in cell (0, nx-1)\u003e \u003cx velocity in cell (0, nx-1)\u003e \u003cy velocity in cell (0, nx-1)\u003e \u003cpressure in cell (0, nx-1)\u003e\n\u003cx value of cell (1, nx-1)\u003e \u003cy value of cell (1, nx-1)\u003e \u003cdensity in cell (1, nx-1)\u003e \u003cx velocity in cell (1, nx-1)\u003e \u003cy velocity in cell (1, nx-1)\u003e \u003cpressure in cell (1, nx-1)\u003e\n                                                 .\n                                                 .\n                                                 .\n\u003cx value of cell (nx-1, nx-1)\u003e \u003cy value of cell (nx-1, nx-1)\u003e \u003cdensity in cell (nx-1, nx-1)\u003e \u003cx velocity cell (nx-1, nx-1)\u003e \u003cy velocity in cell (nx-1, nx-1)\u003e \u003cpressure in cell (nx-1, nx-1)\u003e\n```\n\n\n\n\n\n\n\n\nVisualisation\n--------------------\n\nSome basic scripts to visualize ICs and outputs are given in the `./python_module/scripts/plotting`\ndirectory. See the `README.md` in the `./python_module/scripts` directory for more details. Note\nthat for the directory `./python_module/` to contain any files, you first need to initialize the\nsubmodule. See the instructions [above](#Getting-And-Installing-The-Python-Module).\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmladenivkovic%2Fhydro-playground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmladenivkovic%2Fhydro-playground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmladenivkovic%2Fhydro-playground/lists"}