{"id":23187954,"url":"https://github.com/satfra/diffrg","last_synced_at":"2025-07-30T15:08:39.181Z","repository":{"id":268469480,"uuid":"863993660","full_name":"satfra/DiFfRG","owner":"satfra","description":"The Discretization Framework for functional Renormalization Group flows","archived":false,"fork":false,"pushed_at":"2025-02-06T13:59:51.000Z","size":3663,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-06T14:39:03.498Z","etag":null,"topics":["arxiv","c-plus-plus","computational-physics","functional-renormalization-group","high-energy-physics","mathematica","numerical-hydrodynamics"],"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/satfra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-27T09:44:38.000Z","updated_at":"2025-02-06T13:59:54.000Z","dependencies_parsed_at":"2024-12-17T00:55:45.676Z","dependency_job_id":"781ce31a-ddcd-4481-8d44-cded269cd086","html_url":"https://github.com/satfra/DiFfRG","commit_stats":null,"previous_names":["satfra/diffrg"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satfra%2FDiFfRG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satfra%2FDiFfRG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satfra%2FDiFfRG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/satfra%2FDiFfRG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/satfra","download_url":"https://codeload.github.com/satfra/DiFfRG/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238120794,"owners_count":19419834,"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":["arxiv","c-plus-plus","computational-physics","functional-renormalization-group","high-energy-physics","mathematica","numerical-hydrodynamics"],"created_at":"2024-12-18T11:11:33.985Z","updated_at":"2025-07-30T15:08:39.170Z","avatar_url":"https://github.com/satfra.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![arXiv](https://img.shields.io/badge/arXiv-2412.13043-b31b1b.svg?style=for-the-badge)](https://arxiv.org/abs/2412.13043)\n[![Doxygen](https://img.shields.io/badge/doxygen-2C4AA8?style=for-the-badge\u0026logo=c%2B%2B\u0026logoColor=white)](https://satfra.github.io/DiFfRG/cpp/index.html)\n[![Wolfram](https://img.shields.io/badge/wolfram_doc-cf1c10?style=for-the-badge\u0026logo=wolfram)](https://satfra.github.io/DiFfRG/wolfram/html/guide/DiFfRG.html)\n[![Python](https://img.shields.io/badge/python_doc-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54)](https://satfra.github.io/DiFfRG/python/index.html)\n\n# DiFfRG - A Discretization Framework for functional Renormalization Group flows\n\nDiFfRG is a set of tools for the discretization of flow equations arising in the functional Renormalization Group (fRG).\nIt supports the setup and calculation of large systems of flow equations allowing for complex combinations of vertex and derivative expansions.\n\nFor spatial discretizations, i.e. discretizations of field space mostly used for derivative expansions, DiFfRG makes different finite element (FE) methods available. These include:\n- Continuous Galerkin FE\n- Discontinuos Galerkin FE\n- Direct discontinuous Galerkin FE\n- Local discontinuous Galerkin FE (including derived finite volume (FV) schemes)\n\nThe FEM methods included in DiFfRG are built upon the [deal.ii](https://www.dealii.org/) finite element library, which is highly parallelized and allows for great performance and flexibility.\nPDEs consisting of RG-time dependent equations, as well as stationary equations can be solved together during the flow, allowing for techniques like flowing fields in a very accessible way.\n\nBoth explicit and implicit timestepping methods are available and allow thus for efficient RG-time integration in the symmetric and symmetry-broken regime.\n\nWe also include a set of tools for the evaluation of integrals and discretization of momentum dependencies.\n\nFor an overview, please see the [accompanying paper](https://arxiv.org/abs/2412.13043), the ***[tutorial page](https://satfra.github.io/DiFfRG/cpp/TutorialTOC.html)*** in the [documentation](https://satfra.github.io/DiFfRG/cpp/index.html) and the examples in `Examples/`. \n\nThis library has been developed within the [fQCD Collaboration](https://fQCD-Collaboration.github.io).\n\n## Citation\n\nIf you use DiFfRG in your scientific work, please cite the corresponding paper:\n```\n@article{Sattler:2024ozv,\n    author = \"Sattler, Franz R. and Pawlowski, Jan M.\",\n    title = \"{DiFfRG: A Discretisation Framework for functional Renormalisation Group flows}\",\n    eprint = \"2412.13043\",\n    archivePrefix = \"arXiv\",\n    primaryClass = \"hep-ph\",\n    month = \"12\",\n    year = \"2024\"\n}\n```\n\n## Requirements\n\nTo compile and run this project, there are very few requirements which you can easily install using your package manager on Linux or MacOS:\n\n- [git](https://git-scm.com/) for external requirements and to clone this repository.\n- [CMake](https://www.cmake.org/) for the build systems of DiFfRG, deal.ii and other libraries.\n- [GNU Make](https://www.gnu.org/software/make/) or another generator of your choice.\n- A compiler supporting at least the C++20 standard. This project is only tested using the [GCC](https://gcc.gnu.org/) compiler suite, as well as with `AppleClang`, but in principle, ICC or standard Clang should also work.\n- LAPACK and BLAS in some form, e.g. [OpenBlas](https://www.openblas.net/).\n- The GNU Scientific Library [GSL](https://www.gnu.org/software/gsl/). If not found by DiFfRG, it will try to install it by itself.\n- [Doxygen](https://www.doxygen.org/) and [graphviz](https://www.graphviz.org/download/) to build the documentation.\n\nThe following requirements are optional:\n- [Python](https://www.python.org/) is used in the library for visualization purposes. Furthermore, adaptive phase diagram calculation is implemented as a python routine.\n- [ParaView](https://www.paraview.org/), a program to visualize and post-process the vtk data saved by DiFfRG when treating FEM discretizations.\n- [CUDA](https://developer.nvidia.com/cuda-toolkit) for integration routines on the GPU, which gives a huge speedup for the calculation of fully momentum dependent flow equations (10 - 100x). In case you wish to use CUDA, make sure you have a compiler available on your system compatible with your version of `nvcc`, e.g. `g++`\u003c=13.2 for CUDA 12.5\n\nAll other requirements are bundled and automatically built with DiFfRG.\nThe framework has been tested with the following systems:\n\n#### Arch Linux\n```bash\n$ pacman -S git cmake gcc blas-openblas blas64-openblas paraview python doxygen graphviz gsl\n```\nFor a CUDA-enabled build, additionally install\n```bash\n$ pacman -S cuda\n```\n\n#### Rocky Linux\n```bash\n$ dnf --enablerepo=devel install -y gcc-toolset-12 cmake git openblas-devel doxygen doxygen-latex python3 python3-pip gsl-devel patch\n$ scl enable gcc-toolset-12 bash\n```\n\nThe second line is necessary to switch into a shell where `g++-12` is available\n\n#### Ubuntu\n```bash\n$ apt-get update\n$ apt-get install git cmake libopenblas-dev paraview build-essential python3 doxygen libeigen3-dev graphviz libgsl-dev\n```\nFor a CUDA-enabled build, additionally \n```bash\n$ apt-get install cuda\n```\n\n#### MacOS\nFirst, install xcode and homebrew, then run\n```bash\n$ brew install cmake doxygen paraview eigen graphviz gsl\n```\n\n#### Windows\n\nIf using Windows, instead of running the project directly, it is recommended to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/setup/environment) and then go through the installation as if on Linux (e.g. Arch or Ubuntu).\n\n#### Docker and other container runtime environments\n\nAlthough a native install should be unproblematic in most cases, the setup with CUDA functionality may be daunting. Especially on high-performance clusters, and also depending on the packages available for  chosen distribution, it may be much easier to work with the framework inside a container.\n\nThe specific choice of runtime environment is up to the user, however we provide a small build script to create docker container in which DiFfRG will be built.\nTo do this, you will need `docker`, `docker-buildx` and the [NVIDIA container toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#) in case you wish to create a CUDA-compatible image.\n\nFor a CUDA-enabled build, run\n```build\n$ bash setup_docker.sh -c 12.5.1 -j8\n```\nin the above, you may want to replace the version `12.5.1` with another version you can find on [docker hub at nvidia/cuda ](https://hub.docker.com/r/nvidia/cuda/tags).\nAlternatively, for a CUDA-less build, run simply\n```build\n$ bash setup_docker.sh -j8\n```\n\nIf using other environments, e.g. [ENROOT](https://github.com/NVIDIA/enroot), the preferred approach is simply to build an image on top of the [CUDA images by NVIDIA](https://hub.docker.com/r/nvidia/cuda/tags). Optimal compatibility is given using `nvidia/cuda:12.5.1-devel-rockylinux`. Proceed with the installation setup for  Rocky Linux above.\n\nFor example, with ENROOT a DiFfRG image can be built by following these steps:\n```bash\n$ enroot import docker://nvidia/cuda:12.5.1-devel-rockylinux9\n$ enroot create --name DiFfRG nvidia+cuda+12.5.1-devel-rockylinux9.sqsh\n$ enroot start --root --rw -m ./:/DiFfRG_source DiFfRG bash\n```\nAfterwards, one proceeds with the above Rocky Linux setup.\n\n## Setup\n\nIf all requirements are met, you can clone the git to a directory of your choice,\n```bash\n$ git clone https://github.com/satfra/DiFfRG.git\n```\nand start the build after switching to the git directory.\n```bash\n$ cd DiFfRG\n$ bash -i  build.sh -j8 -i /opt/DiFfRG\n```\nThe `build_DiFfRG.sh` bash script will build and setup the DiFfRG project and all its requirements. This can take up to half an hour as the deal.ii library is quite large.\nThis script has the following options:\n-  `-c`              Use CUDA when building the DiFfRG library.\n-  `-i \u003cdirectory\u003e`  Set the installation directory for the library.\n-  `-j \u003cthreads\u003e`    Set the number of threads passed to make and git fetch.\n-  `--help`          Display this information.\n\nDepending on your amount of CPU cores, you should adjust the `-j` parameter which indicates the number of threads used in the build process. Note that choosing this too large may lead to extreme RAM usage, so tread carefully.\n\nAs soon as the build has finished, you can find a full install of the library in the `DiFfRG_install` subdirectory.\n\nIf you have changes to the library code, you can update the library by running\n```bash\n$ bash -i update_DiFfRG.sh -c -j8 -i /opt/DiFfRG\n```\nwhere once again the `-j` parameter should be adjusted to your amount of CPU cores.\nThe `update_DiFfRG.sh` script takes the following optional arguments:\n- `-c`               Use CUDA when building the DiFfRG library.\n- `-i \u003cdirectory\u003e`   Set the installation directory for the library.\n- `-j \u003cthreads\u003e`     Set the number of threads passed to make and git fetch.\n- `-m`               Install the Mathematica package locally.\n- `--help`           Display this information.\n\n## Getting started with simulating fRG flows\n\nFor an overview, please see the ***[tutorial page](https://satfra.github.io/DiFfRG/cpp/TutorialTOC.html)*** in the [documentation](https://satfra.github.io/DiFfRG/cpp/index.html). A local documentation is also always built automatically when running the setup script, but can also be built manually by running\n```bash\n$ make documentation\n```\ninside the `DiFfRG_build` directory. You can find then a code reference in the top directory.\n\nAll backend code is contained in the DiFfRG directory.\n\nSeveral simulations are defined in the Applications directory, which can be used as a starting point for your own simulations.\n\n# Tips and FAQ\n\n## Logfiles and install issues\n\nDuring building and installing DiFfRG, logs are created at every step. You may find the logs for the setup of external dependencies in `external/logs` and the logs for the build of DiFfRG itself in `logs/`.\n\nIf DiFfRG fails to build on your machine, first check the appropriate logfile. If DiFfRG proves to be incompatible with your machine, please open an Issue on GitHub [here](https://github.com/satfra/DiFfRG/issues), or alternatively send an email to the author (see the [publication](https://arxiv.org/abs/2412.13043)).\n\n\n## Contributing\n\nDiFfRG is a work in progress. If you find some feature missing, a bug, or some other kind of improvement, you can get involved in the further development of DiFfRG. \n\nThanks to the collaborative nature of GitHub, you can simply fork the project and work on a private copy on your own GitHub account. Feel also encouraged to open an [issue](https://github.com/satfra/DiFfRG/issues), or if you already have a (partially) ready contribution, open a [pull request](https://github.com/satfra/DiFfRG/pulls).\n\n\n## Configuration files\n\nA DiFfRG simulation requires you to provide a valid `parameters.json` file in the execution path, or alternatively provide another JSON-file using the `-p` flag (see below).\n\nTo generate a \"stock\" `parameters.json` in the current folder, you can call any DiFfRG application as\n```bash\n$ ./my_simulation --generate-parameter-file\n```\nBefore usage, don't forget to put in the parameters you defined in your own simulation!\n\n\n## Progress output\n\nTo monitor the progress of the simulation, one can set the `verbosity` parameter either in the parameter file,\n```json\n{\n  \"output\": {\n    \"verbosity\": 1\n  },\n}\n```\nor from the CLI,\n```bash\n$ ./my_simulation -si /output/verbosity=1\n```\n\n\n## Modifying parameters from the CLI\n\nAny DiFfRG simulation using the `DiFfRG::ConfigurationHelper` class can be asked to give some syntax pertaining to the configuration:\n```bash\n$ ./my_simulation --help\nThis is a DiFfRG simulation. You can pass the following optional parameters:\n  --help                      shows this text\n  --generate-parameter-file   generates a parameter file with some default values\n  -p                          specifiy a parameter file other than the standard parameter.json\n  -sd                         overwrite a double parameter. This should be in the format '-s physical/T=0.1'\n  -si                         overwrite an integer parameter. This should be in the format '-s physical/Nc=1'\n  -sb                         overwrite a boolean parameter. This should be in the format '-s physical/use_sth=true'\n  -ss                         overwrite a string parameter. This should be in the format '-s physical/a=hello'\n```\ne.g.\n```bash\n$ ./my_simulation -sd /physical/Lambda=1.0\n```\n\n## Timestepper choice\n\nIn general, the `IDA` timestepper from the `SUNDIALS`-suite has proven to be the optimal choice for any fRG-flow with convexity restoration. Additionally, this solver allows for out-of-the-box solving of additional algebraic systems, which is handy for more complicated fRG setups.\n\nIf solving purely variable-dependent systems, one of the `Boost` time steppers, `Boost_RK45`, `Boost_RK78` or `Boost_ABM`. The latter is especially excellent for extremely large systems which have no extremely fast dynamics, but lacks adaptive timestepping. In practice, choosing `Boost_ABM` over one of the RK steppers may speed up a Yang-Mills simulation with full momentum dependences by more than a factor of 10.\n\nFor systems with both spatial discretisations and variables, consider one of the implicit-explicit mixtures, `SUNDIALS_IDA_Boost_RK45`,  `SUNDIALS_IDA_Boost_RK78` or `SUNDIALS_IDA_Boost_ABM`.\n\n# Other Libraries used\n\nThe following third-party libraries are utilised by DiFfRG. They are automatically built and installed DiFfRG during the build process.\n\n- The main backend for field-space discretization is [deal.II](https://www.dealii.org/), which provides the entire FEM-machinery as well as many other utility components.\n- For performant and convenient calculation of Jacobian matrices we use the [autodiff](https://github.com/autodiff/autodiff) library, which implements automatic forward and backwards differentiation in C++ and also in CUDA.\n- Time integration relies heavily on the [SUNDIALS](https://computing.llnl.gov/projects/sundials) suite, specifically on the IDAs solver.\n- [Rapidcsv](https://github.com/d99kris/rapidcsv) for quick processing of .csv files.\n- [Catch2](https://github.com/catchorg/Catch2) for unit testing.\n- [RMM](https://github.com/rapidsai/rmm), a memory manager for CUDA, which is used for GPU-accelerated loop integrations.\n- [QMC](https://github.com/mppmu/qmc) for adaptive Quasi-Monte-Carlo integration.\n- [spdlog](https://github.com/gabime/spdlog) for logging.\n- [Doxygen Awesome](https://github.com/jothepro/doxygen-awesome-css) for a modern doxygen theme.\n- [Boost](https://www.boost.org/) provides explicit time-stepping and various math algorithms.\n- [Eigen](https://eigen.tuxfamily.org/) for some linear-algebra related tasks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatfra%2Fdiffrg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsatfra%2Fdiffrg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatfra%2Fdiffrg/lists"}