{"id":32659761,"url":"https://github.com/uva-trasgo/controllers","last_synced_at":"2026-05-12T23:37:57.786Z","repository":{"id":321632591,"uuid":"1081824648","full_name":"uva-trasgo/Controllers","owner":"uva-trasgo","description":"Read-only mirror of the official repository: https://gitlab.com/trasgo-group-valladolid/controllers. Controllers is a library written in C11 that provides a simplified way to program applications that can exploit heterogeneous computational platforms including accelerators and/or multi-core CPUs.","archived":false,"fork":false,"pushed_at":"2025-10-30T16:42:24.000Z","size":65892,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-30T18:31:06.149Z","etag":null,"topics":["cuda","heterogeneous-computing","heterogeneous-parallel-programming","hip","opencl","openmp"],"latest_commit_sha":null,"homepage":"https://trasgo.infor.uva.es/controller/","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/uva-trasgo.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T10:43:57.000Z","updated_at":"2025-10-23T12:37:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"49d40c94-d101-443d-85a3-1ed2e0d47ade","html_url":"https://github.com/uva-trasgo/Controllers","commit_stats":null,"previous_names":["uva-trasgo/controllers"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/uva-trasgo/Controllers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uva-trasgo%2FControllers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uva-trasgo%2FControllers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uva-trasgo%2FControllers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uva-trasgo%2FControllers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uva-trasgo","download_url":"https://codeload.github.com/uva-trasgo/Controllers/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uva-trasgo%2FControllers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282007156,"owners_count":26598240,"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","status":"online","status_checked_at":"2025-10-31T02:00:07.401Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cuda","heterogeneous-computing","heterogeneous-parallel-programming","hip","opencl","openmp"],"created_at":"2025-10-31T15:01:16.936Z","updated_at":"2026-05-12T23:37:57.779Z","avatar_url":"https://github.com/uva-trasgo.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Controllers library\n\nControllers is a C11 library implementing the Controller heterogeneous programming framework (also referred as _the Controller model_), as described by [Torres _et al._](https://doi.org/10.1016/j.jpdc.2023.04.009).\n\n[![Controllers's license](https://img.shields.io/gitlab/license/trasgo-group-valladolid%2Fcontrollers?style=flat\u0026color=dark-green)](./LICENSE.md)\n\n## Overview\n\nThe Controller model is a heterogeneous programming model that enables performance portability across different computing accelerators. Being a C11 library, it is compatible with any modern C/C++ compiler. It is also easily interoperable with other libraries and parallel programming models. The current implementation of the Controllers library supports the following computing accelerator architectures:\n * Multicore CPUs, using an OpenMP backend\n * NVIDIA GPUs, using a CUDA backend\n * AMD GPUs, using a HIP backend\n * Generic GPUs, using an OpenCL backend\n * Intel FPGAs, using another OpenCL backend\n\nThe Controller model allows multiple explicit implementation per computing kernel, with specialized versions for each type of device. It also allows compiling applications that leverage _almost_ any combination of the supported backends concurrently; linking all the defined kernel implementation together. Therefore, the compiled programs can target choose multiple different target devices at runtime. Kernel implementations are compiled with the backend's own vendor or native compiler, thus enabling the full range of capabilities of the technology.\n\n(Due to technical limitations of the CUDA and HIP headers, Controllers cannot currently support both backends at the same time. Nevertheless, any other combination of backends is allowed.)\n\nThe Controller model leverages dependence analysis on sequence of data transfers, host computation, and kernel execution operations, to automatically overlap them whenever possible. It maps the execution control directly to the coprocessor driver resources, avoiding the use of a full scheduler, or task-graph analisys techniques. This results in a highly efficient control system with minimal overhead.\n\n## Prerequisites\n\nControllers has some core dependencies, which are always required to use the library. Support for specific architectures might have some aditional dependencies.\n\nCore runtime dependencies:\n - MPI \u003e= 3.0\n - OpenMP \u003e= 4.0\n - hwloc \u003e= 1.11.0\n\nCompilation dependencies:\n - CMake \u003e= 3.20\n\nCUDA architecture dependencies:\n - CUDA \u003e= 9.0\n\nHIP architecture dependencies:\n - HIP \u003e= 6.1.0\n\nOpenCL GPU architecture dependencies:\n - OpenCL (1.2 or 2.0 depending on the features used)\n\nFPGA architecture dependencies:\n - Intel FPGA SDK for OpenCL\n\n## Compiling Controllers\n\nControllers uses CMake for compilation. The usual compilation flow is as follows:\n```\nmkdir -p build\ncd build\ncmake ..\nmake -j $(nproc)\n```\n\nA convenience compilation bash script, [`compile.sh`](./compile.sh), is also provided. For instructions on how to use it, execute it with the `-h` option:\n```\nbash compile.sh -h\n```\n\n### Configurable compilation options\n\nWhen compiling Controllers, the architecture support should be specified either by changing default values in CMake files, or by selecting them when running the `cmake` command. The values to change in the CMake files (`CMakeLists.txt`) are the following (change `OFF` to `ON` accordingly).\n```cmake\n# Architectures\noption(SUPPORT_CPU \"Support for the CPU architecture (OpenMP backend)\" OFF)\noption(SUPPORT_CUDA \"Support for the NVIDIA GPU architecture (CUDA backend)\" OFF)\noption(SUPPORT_HIP \"Support for the AMD GPU architecture (HIP backend)\" OFF)\noption(SUPPORT_OPENCL \"Support for the generic GPU architecture (OpenCL backend)\" OFF)\noption(SUPPORT_FPGA \"Support for the Intel FPGA architecture (Intel FPGA SDK for OpenCL backend)\" OFF)\n```\nTo change the options when running the command, do the following:\n```\ncmake -DSUPPORT_CUDA=ON ..\n```\n\nTo see the full list of configurable options and their default values run:\n```\nmkdir -p build\ncd build\ncmake -LH ..\n```\n\nThe `compile.sh` script allows specifying some of these options through command-line arguments when executing it. Refer to its help message (`bash compile.sh -h`) for more information.\n\n### Specifying paths to dependencies\n\nAdditionally, the installation paths for multiple dependencies can be manually specified in the `CMakeList.txt` file as hints to the CMake system. You should change the following values accordingly:\n```cmake\n# Dependencies' installation paths\nset(ROCM_PATH \"/opt/rocm\" CACHE PATH \"Path to ROCm installation\")\nset(OPENCL_PATH \"/usr/local/cuda\" CACHE PATH \"Path to OpenCL installation\")\nset(MAGMA_ROOT \"/opt/magma\" CACHE PATH \"Path to MAGMA installation\")\nset(FPGA_BOARD_PKG \"/opt/intelFPGA_pro/21.2/hld/board/de10_agilex\" CACHE PATH \"Path to FPGA board package\")\n```\n\n## Example programs\n\nThis repository provides multiple example programs that use the Controllers library for different kinds of tasks. \nThe examples can be found in the [`examples/`](./examples) directory. By default, they are always compiled alongside the library.\n\n**Tip:** If you want to develop your own programs using Controllers please refer to the provided examples.\n\nAfter compiling the example programs, they can be executed as follows (using one of the implementations of `Matrix_Add` as an example):\n```\n./build/examples/Matrix_Add/Matrix_Add_Cuda_Ctrl 100 1 0 0 1 \u003cpath_to_device_selection_file\u003e\n```\nControllers is prepared to execute on distributed environments:\n```\nmpirun -n 4 ./build/examples/Matrix_Add/Matrix_Add_Cuda_Ctrl 100 1 0 0 1 \u003cpath_to_device_selection_file\u003e\n\nsrun -w node1,node2 -n 4 ./build/examples/Matrix_Add/Matrix_Add_Cuda_Ctrl 100 1 0 0 1 \u003cpath_to_device_selection_file\u003e\n```\nThe user controls which device(s) are selected and used for each process on each node, using a runtime configuration file. More information about the syntax and options of the device-selection configuration files can be found [here](./DEVICE_SELECTION.md).\n\n## Documentation\n\n### API\n\nThe Controllers library uses Doxygen for function and macro documentation. The documentation can be generated as follows:\n```\ncd Ctrl/doc\ndoxygen Doxyfile\n```\n\n### Project structure\n\nIn the root directory of this project you can find the following subdirectories:\n- `Ctrl`: the source code of the Controllers library.\n- `CtrlBlas`: premade BLAS kernels for Controllers. Contains implementations for MKL, cuBLAS and Magma.\n- `examples`: examples using the Controllers library.\n- `exp`: results and scripts for experimentations.\n- `extern`: Controllers dependencies (Hitmap).\n\n## Contributing\n\nThank you for your interest in contributing to the Controllers library! There are many ways to contribute to this project. You can take a look at [the document on contributing](./CONTRIBUTING.md) for tips on how to get started.\n\nFeel free to contact us at [trasgo@infor.uva.es](mailto://trasgo@infor.uva.es) to share your experience with us, or visit our page [https://trasgo.infor.uva.es/](https://trasgo.infor.uva.es/) to learn more about us.\nIf you find any bugs or problems, or want to request a new feature, feel free to [open an issue](https://gitlab.com/trasgo-group-valladolid/controllers/-/issues) detailing it.\n\n## Citation and further reading\n\nIf you are interested in knowing more about Controllers and the Controller model, you can review the following published research papers about the project:\n - Supporting efficient overlapping of host-device operations for heterogeneous programming with CtrlEvents. Y. Torres, F.J. Andújar, . Gonzalez-Escribano, D.R. Llanos. Journal of Parallel and Distributed Computing, 179, Elsevier, 2023. DOI: [10.1016/j.jpdc.2023.04.009](https://doi.org/10.1016/j.jpdc.2023.04.009).\n - Efficient heterogeneous programming with FPGAs using the Controller model. G. Rodriguez-Canal, Y. Torres, F.J. Andújar, A. Gonzalez-Escribano. The Journal of Supercomputing,77, 13995-14010, Springer, 2021. DOI: [10.1007/s11227-021-03792-7](https://doi.org/10.1007/s11227-021-03792-7).\n - Controllers: An abstraction to ease the use of hardware accelerators. A. Moretón-Fernández, H. Ortega-Arranz, A. Gonzalez-Escribano. The International Journal on High Performance Computing Aplications (IJHPCA), 32 (6), pag. 838-853, SAGE Journals, 2018. DOI: [10.1177/1094342017702962](https://doi.org/10.1177/1094342017702962).\n\nIf you use Controllers in your research in any meaningful way, we would appreciate that you cite any of those papers. Here are the BibTeX references for them:\n```BibTeX\n@article{Torres2023:CtrlEvents,\n\ttitle = {Supporting efficient overlapping of host-device operations for heterogeneous programming with CtrlEvents},\n\tauthor = {Yuri Torres and Francisco J. And\\'{u}jar and Arturo Gonzalez-Escribano and Diego R. Llanos},\n\tjournal = {Journal of Parallel and Distributed Computing},\n\tvolume = {179},\n\tpages = {104708},\n\tyear = {2023},\n\tissn = {0743-7315},\n\tdoi = {https://doi.org/10.1016/j.jpdc.2023.04.009},\n}\n\n@article{Rodriguez-Canal2021:FPGAControllers,\n\ttitle = {Efficient heterogeneous programming with FPGAs using the Controller model},\n\tauthor = {Rodriguez-Canal, Gabriel and Torres, Yuri and And\\'{u}jar, Francisco J. and Gonzalez-Escribano, Arturo},\n\tyear = {2021},\n\tissue_date = {Dec 2021},\n\tpublisher = {Kluwer Academic Publishers},\n\taddress = {USA},\n\tvolume = {77},\n\tnumber = {12},\n\tissn = {0920-8542},\n\tdoi = {10.1007/s11227-021-03792-7},\n\tjournal = {J. Supercomput.},\n\tmonth = dec,\n\tpages = {13995-14010},\n\tnumpages = {16},\n}\n\n@article{Moreton-Fernandez2018:Controllers,\n\ttitle = {Controllers: An abstraction to ease the use of hardware accelerators},\n\tauthor = {Ana Moreton-Fernandez and Hector Ortega-Arranz and Arturo Gonzalez-Escribano},\n\tjournal = {The International Journal of High Performance Computing Applications},\n\tvolume = {32},\n\tnumber = {6},\n\tpages = {838-853},\n\tyear = {2018},\n\tdoi = {10.1177/1094342017702962},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuva-trasgo%2Fcontrollers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuva-trasgo%2Fcontrollers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuva-trasgo%2Fcontrollers/lists"}