{"id":13474102,"url":"https://github.com/LatticeQCD/SIMULATeQCD","last_synced_at":"2025-03-26T21:30:28.137Z","repository":{"id":37860299,"uuid":"413830658","full_name":"LatticeQCD/SIMULATeQCD","owner":"LatticeQCD","description":"SIMULATeQCD is a multi-GPU Lattice QCD framework that makes it easy for physicists to implement lattice QCD formulas while still providing competitive performance.","archived":false,"fork":false,"pushed_at":"2025-03-13T13:26:38.000Z","size":23212,"stargazers_count":32,"open_issues_count":41,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-13T14:31:07.362Z","etag":null,"topics":["cuda","gpu","hip","hpc","lattice","lattice-qcd","mpi","parallel","physics"],"latest_commit_sha":null,"homepage":"https://latticeqcd.github.io/SIMULATeQCD/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LatticeQCD.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}},"created_at":"2021-10-05T13:31:33.000Z","updated_at":"2025-01-30T14:58:13.000Z","dependencies_parsed_at":"2024-01-10T20:01:41.350Z","dependency_job_id":"1e550cea-d90e-445e-9745-d40e5496d3ef","html_url":"https://github.com/LatticeQCD/SIMULATeQCD","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LatticeQCD%2FSIMULATeQCD","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LatticeQCD%2FSIMULATeQCD/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LatticeQCD%2FSIMULATeQCD/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LatticeQCD%2FSIMULATeQCD/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LatticeQCD","download_url":"https://codeload.github.com/LatticeQCD/SIMULATeQCD/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245738468,"owners_count":20664282,"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":["cuda","gpu","hip","hpc","lattice","lattice-qcd","mpi","parallel","physics"],"created_at":"2024-07-31T16:01:09.541Z","updated_at":"2025-03-26T21:30:28.131Z","avatar_url":"https://github.com/LatticeQCD.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# SIMULATeQCD\n\n\n[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://latticeqcd.github.io/SIMULATeQCD)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/LatticeQCD/SIMULATeQCD/commits/main)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7994982.svg)](https://doi.org/10.5281/zenodo.7994982)\n\n\n\n*a SImple MUlti-GPU LATtice code for QCD calculations*\n\n\nSIMULATeQCD is a multi-GPU Lattice QCD framework that makes it easy for physicists to implement lattice QCD formulas while still providing\ncompetitive performance. \n\n## How to Build \n\nThere are two possible ways to build SIMULATeQCD. If you are running on your own laptop or desktop and have an NVIDIA GPU,\nwe recommend that you use the [container build](#compile-using-container). The container will automatically grab all software you need.\nIf you are running on an HPC system or want to use AMD, we recommmend you [compile manually](#compile-manually) and ensure that all needed\nsoftware already exists on the system you're using.\nThis README attempts to give a succinct overview of how to build and use SIMULATeQCD. If you run into problems building, first\nplease have a look at the [Getting Started](https://latticeqcd.github.io/SIMULATeQCD/01_gettingStarted/gettingStarted.html) section of the **[documentation](https://latticeqcd.github.io/SIMULATeQCD)**.\n\n### Download SIMULATeQCD\n\nYou will need to install [`git-lfs`](https://git-lfs.github.com/) before continuing or you will need to use a git client which natively supports it.\nThis is needed for downloading configurations used in the unit tests. Then run \n```shell\ngit clone https://github.com/LatticeQCD/SIMULATeQCD.git -b v1.2.0\n```\n\n### Compile Using Container\n\nTo build using the container, you need to have `podman` properly configured on your system.  \nYou can find more detailed instructions about the container in the [Getting Started](https://latticeqcd.github.io/SIMULATeQCD/01_gettingStarted/gettingStarted.html) section of the documentation.\nTo run the container you need an NVIDIA GPU.\n\nTo build the code, you then simply\n\n1. Update [config.yml](./podman-build/config.yml) with any settings you would like to use for your build. This includes your target output directory.\n   1. You can run `\u003cwhere_you_downloaded\u003e/simulate_qcd.sh list` to get a list of possible build targets.\n   2. If you want to change where the code outputs to, you need to update OUTPUT_DIRECTORY in [config.yml](./podman-build/config.yml). It will create a folder called build in the specified folder.\n2. Run `chmod +x ./simulate_qcd.sh \u0026\u0026 ./simulate_qcd.sh build`\n\n### Compile Manually\n\nThe following software is required to manually compile SIMULATeQCD:\n\n- `cmake` (Some versions have the \"--phtread\" compiler bug. Versions that definitely work are [3.14.6](https://gitlab.kitware.com/cmake/cmake/tree/v3.14.6) or [3.19.2](https://gitlab.kitware.com/cmake/cmake/-/tree/v3.19.2?ref_type=tags).)\n- `C++` compiler with `C++17` support.\n- `MPI` (e.g. `openmpi-4.0.4`).\n- `CUDA Toolkit` version 11+. \n- `pip install -r requirements.txt` to build the documentation.\n\nTo setup the compilation, create a folder outside of the code directory (e.g. `../buildSIMULATeQCD/`) and **from there** call the following example script: \n```shell\ncmake ../SIMULATeQCD/ \\\n-DARCHITECTURE=\"80\" \\\n-DUSE_GPU_AWARE_MPI=ON \\\n-DUSE_GPU_P2P=ON \\\n```\nHere, it is assumed that your source code folder is called `SIMULATeQCD`. \nYou can set the path to CUDA by setting the `cmake` parameter `-DCUDA_TOOLKIT_ROOT_DIR:PATH`.\n`-DARCHITECTURE` sets the GPU architecture (i.e. [compute capability](https://en.wikipedia.org/wiki/CUDA#GPUs_supported) version without the decimal point). For example use \"70\" for Volta or \"80\" for Ampere.\nInside the build folder, you can now begin to use `make` to compile your executables, e.g.\n```shell\nmake NameOfExecutable\n```\nIf you would like to speed up the compiling process, add the option `-j`, which will compile in parallel using all available CPU threads. You can also specify the number of threads manually using, for example, `-j 4`.\n\nPopular production-ready executables are:\n```Shell\nrhmc             # generate HISQ configurations\ngenerateQuenched # generate quenched gauge configurations using HB and OR\ngradientFlow     # Apply Wilson/Zeuthen flow and measure various observables\ngaugeFixing      # Gauge fixing\n```\nExample parameter files for the above executables can be found in `parameter/applications/`.\nIn the [documentation](https://latticeqcd.github.io/SIMULATeQCD/03_applications/applications.html) you will find more information on how to execute these programs.\n\n## Example: Plaquette action computation\n\nHere we showcase a snippet of code. It is not important that you understand all details: We just\nwant to emphasize that these two blocks are roughly all that is required to compute the plaquette\nat every site for every orientation. These blocks take care of periodic BCs, GPU parallelization,\nand communication between neighboring GPUs behind the scenes.\nSee this [Full code example](https://github.com/LatticeQCD/SIMULATeQCD/blob/main/src/examples/main_plaquette.cu)\nfor a more detailed understanding.\n\n```C++\ntemplate\u003cclass floatT, bool onDevice, size_t HaloDepth\u003e\nstruct CalcPlaq {\n  SU3Accessor\u003cfloatT\u003e gaugeAccessor;\n  CalcPlaq(Gaugefield\u003cfloatT,onDevice,HaloDepth\u003e \u0026gauge) : gaugeAccessor(gauge.getAccessor()){}\n  __device__ __host__ floatT operator()(gSite site) {\n    floatT result = 0;\n    for (int nu = 1; nu \u003c 4; nu++) {\n      for (int mu = 0; mu \u003c nu; mu++) {\n        result += tr_d(gaugeAccessor.template getLinkPath\u003cAll, HaloDepth\u003e(site, mu, nu, Back(mu), Back(nu)));\n      }\n    }\n    return result;\n  }\n};\n\n(... main ...)\ngauge.updateAll()\nlatticeContainer.template iterateOverBulk\u003cAll, HaloDepth\u003e(CalcPlaq\u003cfloatT, HaloDepth\u003e(gauge))\nlatticeContainer.reduce(plaq, elems);\n```\n\n\n## Documentation\n\nPlease check out [the documentation](https://latticeqcd.github.io/SIMULATeQCD) to learn how to use SIMULATeQCD in detail,\nincluding how to make contributions, details for installation, and to see what kinds of modules and applications are\nalready available.\n\n## Getting help and bug report\nOpen an [issue](https://github.com/LatticeQCD/SIMULATeQCD/issues), if...\n- you have troubles compiling/running the code.\n- you have questions on how to implement your own routine.\n- you have found a bug.\n- you have a feature request.\n\nIf none of the above cases apply, you may also send an email to lukas.mazur(at)uni-paderborn(dot)de\nor clarke(dot)davida(at)gmail.com.\n\n\n## Contributors\n\n[L. Mazur](https://github.com/lukas-mazur), \n[S. Ali](https://github.com/Sajidali1031), \n[L. Altenkort](https://github.com/luhuhis), \n[D. Bollweg](https://github.com/dbollweg), \n[D. A. Clarke](https://github.com/clarkedavida), \n[G. Curell](https://github.com/grantcurell/),\n[H. Dick](https://github.com/redweasel),\n[J. Goswami](https://github.com/jishnuxx),\n[O. Kaczmarek](https://github.com/olaf-kaczmarek),\n[J. Kim](https://github.com/kimjangho1120),\n[R. Larsen](https://github.com/RasmusNL),\n[M. Neumann](https://github.com/mneumann177),\n[M. Rodekamp](https://github.com/Marcel-Rodekamp), \n[H. Sandmeyer](https://github.com/hsandmeyer), \n[C. Schmidt](https://github.com/schmidt74), \n[P. Scior](https://github.com/philomat), \n[H.-T. Shu](https://github.com/haitaoshu)\n\n## Citing SIMULATeQCD\n\nIf you are using this code in your research please cite:\n\n- *L. Mazur, Topological aspects in lattice QCD, Ph.D. thesis, Bielefeld University (2021), [https://doi.org/10.4119/unibi/2956493](https://doi.org/10.4119/unibi/2956493)*\n- *L. Mazur, D.Bollweg, D. A. Clarke, L. Altenkort et al., SIMULATeQCD: A simple multi-GPU lattice code for QCD calculations, [https://arxiv.org/abs/2306.01098](https://arxiv.org/abs/2306.01098)*\n\n## Acknowledgments\n- This work is supported by the U.S. Department of Energy, Office of Science within the framework of Scientific Discovery through Advance Computing (SciDAC).\n- We acknowledge support by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) through the CRC-TR 211\n'Strong-interaction matter under extreme conditions'– project number 315477589 – TRR 211.\n- This work was partly performed in the framework of the PUNCH4NFDI consortium supported by DFG fund \"NFDI 39/1\", Germany.\n- We would also like to acknowedge enlightening technical discussions with the ILDG team, in particular H. Simma.\n- The authors gratefully acknowledge computing time provided to them on the high-performance computers Noctua2 at the NHR Center PC2. These are funded by the Federal Ministry of Education and Research and the state governments participating on the basis of the resolutions of the GWK for the national highperformance computing at universities (www.nhr-verein.de/unsere-partner).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLatticeQCD%2FSIMULATeQCD","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLatticeQCD%2FSIMULATeQCD","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLatticeQCD%2FSIMULATeQCD/lists"}