{"id":13533393,"url":"https://github.com/StanfordLegion/legion","last_synced_at":"2025-04-01T21:32:22.171Z","repository":{"id":5528305,"uuid":"6730452","full_name":"StanfordLegion/legion","owner":"StanfordLegion","description":"The Legion Parallel Programming System","archived":false,"fork":false,"pushed_at":"2024-04-13T19:15:12.000Z","size":369473,"stargazers_count":644,"open_issues_count":469,"forks_count":144,"subscribers_count":37,"default_branch":"stable","last_synced_at":"2024-04-14T09:51:14.770Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://legion.stanford.edu","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StanfordLegion.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2012-11-17T00:43:58.000Z","updated_at":"2024-06-05T09:09:42.016Z","dependencies_parsed_at":"2023-02-14T00:00:20.230Z","dependency_job_id":"c34d39fa-748e-4dfc-92db-e310ef13121c","html_url":"https://github.com/StanfordLegion/legion","commit_stats":{"total_commits":12687,"total_committers":92,"mean_commits":"137.90217391304347","dds":0.7342161267439111,"last_synced_commit":"9ed6f4d6b579c4f17e0298462e89548a4f0ed6e5"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordLegion%2Flegion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordLegion%2Flegion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordLegion%2Flegion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StanfordLegion%2Flegion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StanfordLegion","download_url":"https://codeload.github.com/StanfordLegion/legion/tar.gz/refs/heads/stable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246713373,"owners_count":20821877,"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":[],"created_at":"2024-08-01T07:01:19.412Z","updated_at":"2025-04-01T21:32:17.158Z","avatar_url":"https://github.com/StanfordLegion.png","language":"C++","funding_links":[],"categories":["Software"],"sub_categories":["Trends"],"readme":"# Legion \n\n\n[Legion](http://legion.stanford.edu) is a parallel programming model\nfor distributed, heterogeneous machines.\n\n## Branches\n\nThe Legion team uses this repository for active development, so please make sure you're\nusing the right branch for your needs:\n\n  * stable - This is the default branch if you clone the\nrepository.  It is generally about a month behind the master branch, allowing us to get some\nmileage on larger changes before foisting them on everybody.  Most users of Legion should use this\nbranch, although you should be prepared to try the master branch if you run into issues.\nUpdates are moved to the stable branch roughly monthly, although important bug fixes may be\napplied directly when needed.  Each batch of updates is given a \"version\" number, and\n[CHANGES.txt](https://github.com/StanfordLegion/legion/blob/stable/CHANGES.txt) lists the\nmajor changes.\n  * master - This is the \"mainline\" used by the Legion team,\nand contains changes and bug fixes that may not have made it into the stable branch yet.  If you\nare a user of \"bleeding-edge\" Legion functionality, you will probably need to be using this branch.\n  * lots of other feature branches - These exist as necessary for larger changes, and users will\ngenerally want to steer clear of them.  :)\n\n## Overview\n\nLegion is a programming model and runtime system designed for decoupling the specification\nof parallel algorithms from their mapping onto distributed heterogeneous architectures.  Since\nrunning on the target class of machines requires distributing not just computation but data\nas well, Legion presents the abstraction of logical regions for describing the structure of\nprogram data in a machine independent way.  Programmers specify the partitioning of logical\nregions into subregions, which provides a mechanism for communicating both the independence \nand locality of program data to the programming system.  Since the programming system\nhas knowledge of both the structure of tasks and data within the program, it can aid the\nprogrammer in host of problems that are commonly the burden of the programmer:\n\n  * Discovering/verifying correctness of parallel execution: determining when two tasks\n    can be run in parallel without a data race is often difficult.  Legion provides mechanisms\n    for creating both implicit and explicit parallel task launches.  For implicit constructs \n    Legion will automatically discover parallelism.  For explicit constructs, Legion will\n    notify the programmer if there are potential data races between tasks intended to be\n    run in parallel.\n  * Managing communication: when Legion determines that there are data dependencies between\n    two tasks run in different locations, Legion will automatically insert the necessary\n    copies and apply the necessary constraints so the second task will not run until\n    its data is available.  We describe how tasks and data are placed in the next paragraph\n    on mapping Legion programs.\n\nThe Legion programming model is designed to abstract computations in a way that makes\nthem portable across many different potential architectures.  The challenge then is to make\nit easy to map the abstracted computation of the program onto actual architectures.  At\na high level, mapping a Legion program entails making two kinds of decisions:\n  \n  1. For each task: select a processor on which to run the task.\n  2. For each logical region a task needs: select a memory in which to create\n     a physical instance of the logical region for the task to use.\n\nTo facilitate this process Legion introduces a novel runtime 'mapping' interface.  One of the\nNON-goals of the Legion project was to design a programming system that was magically capable \nof making intelligent mapping decisions.  Instead the mapping interface provides a declarative\nmechanism for the programmer to communicate mapping decisions to the runtime system\nwithout having to actually write any code to perform the mapping (e.g. actually writing\nthe code to perform a copy or synchronization).  Furthermore, by making the mapping interface\ndynamic, it allows the programmer to make mapping decisions based on information that\nmay only be available at runtime.  This includes decisions based on:\n\n  * Program data: some computations are dependent on data (e.g. is our irregular graph\n    sparse or dense in the number of edges).\n  * System data: which processors or nodes are currently up or down, or which are running\n    fast or slow to conserve power.\n  * Execution data: profiling data that is fed back to the mapper about how a certain\n    mapping performed previously.  Alternatively which processors are currently over-\n    or under- loaded.\n\nAll of this information is made available to the mapper via various mapper calls, some\nof which query the mapping interface while others simply are communicating information\nto the mapper.\n\nOne very important property of the mapping interface is that no mapping decisions are\ncapable of impacting the correctness of the program.  Consequently, all mapping decisions\nmade are only performance decisions.  Programmers can then easily tune a Legion application\nby modifying the mapping interface implementation without needing to be concerned\nwith how their decisions impact correctness.  Ultimately, this makes it possible in Legion\nto explore whole spaces of mapping choices (which tasks run on CPUs or GPUs, or where data \ngets placed in the memory hierarchy) simply by enumerating all the possible mapping\ndecisions and trying them.\n\nTo make it easy to get a working program, Legion provides a default mapper implementation\nthat uses heuristics to make mapping decisions.  In general these decision are good, but\nthey are certain to be sub-optimal across all applications and architectures.  All calls\nin the mapping interface are C++ virtual functions that can be overridden, so programmers\ncan extend the default mapper and only override the mapping calls that are impacting performance.\nAlternatively a program can implement the mapping interface entirely from scratch.\n\nFor more details on the Legion programming model and its current implementation\nwe refer to you to our Supercomputing paper.\n\nhttp://theory.stanford.edu/~aiken/publications/papers/sc12.pdf\n\n## Contents\n\nThis repository includes the following contents:\n\n  * `tutorial`: Source code for the [tutorials](http://legion.stanford.edu/tutorial/).\n  * `examples`: Larger examples for advanced programming techniques.\n  * `apps`: Several complete Legion applications.\n  * `language`: The [Regent programming language](http://regent-lang.org/) compiler and examples.\n  * `runtime`: The core runtime components:\n      * `legion`: The Legion runtime itself (see `legion.h`).\n      * `realm`: The Realm low-level runtime (see `realm.h`).\n      * `mappers`: Several mappers, including the default mapper (see `default_mapper.h`).\n  * `tools`: Miscellaneous tools:\n      * `legion_spy.py`: A [visualization tool](http://legion.stanford.edu/debugging/#legion-spy) for task dependencies.\n      * `legion_prof.py`: A task-level [profiler](http://legion.stanford.edu/profiling/#legion-prof).\n\n## Dependencies\n\nTo get started with Legion, you'll need:\n\n  * Linux, macOS, or another Unix\n  * A C++ 17 (or newer) compiler (GCC, Clang, Intel, or PGI) and GNU Make\n  * *Optional*: CMake 3.16 or newer\n  * *Optional*: Python 3.5 or newer (used for tools and Python bindings)\n      * Note: Python 3.8 or newer is required for `tools/legion_prof.py`\n  * *Optional*: Rust 1.74 or newer (used for Rust profiler)\n  * *Optional*: CUDA 10.0 or newer (for NVIDIA GPUs)\n  * *Optional*: CUDA 11.7 or newer if using Legion's built-in complex reduction operators\n  * *Optional*: [GASNet](https://gasnet.lbl.gov/) (for networking, see\n     [installation instructions](http://legion.stanford.edu/gasnet/))\n  * *Optional*: LLVM 7-14 (for dynamic code generation)\n  * *Optional*: HDF5 (for file I/O)\n\n## Installing\n\nLegion is currently compiled with each application. To try a Legion\napplication, just call `make` in the directory in question. The\n`LG_RT_DIR` variable is used to locate the Legion `runtime`\ndirectory. For example:\n\n```bash\ngit clone https://github.com/StanfordLegion/legion.git\nexport LG_RT_DIR=\"$PWD/legion/runtime\"\ncd legion/examples/circuit\nmake\n./circuit\n```\n\n## Makefile Variables\n\nThe Legion Makefile includes several variables which influence the\nbuild. These may either be set in the environment (e.g. `DEBUG=0\nmake`) or at the top of each application's Makefile.\n\n  * `DEBUG=\u003c0,1\u003e`: controls optimization level and enables various\n    dynamic checks which are too expensive for release builds.\n  * `OUTPUT_LEVEL=\u003clevel_name\u003e`: controls the compile-time [logging\n    level](http://legion.stanford.edu/debugging/#logging-infrastructure).\n  * `USE_CUDA=\u003c0,1\u003e`: enables CUDA support.\n  * `USE_GASNET=\u003c0,1\u003e`: enables GASNet support (see [installation instructions](http://legion.stanford.edu/gasnet/)).\n  * `USE_LLVM=\u003c0,1\u003e`: enables LLVM support.\n  * `USE_HDF=\u003c0,1\u003e`: enables HDF5 support.\n\n## Build Flags\n\nIn addition to Makefile variables, compilation is influenced by a\nnumber of build flags. These flags may be added to variables in the\nenvironment (or again set inside the Makefile).\n\n  * `USE_SPY=1`: enables [Legion Spy](http://legion.stanford.edu/debugging/#legion-spy).\n  * `PRIVILEGE_CHECKS=1`: enables [extra privilege checks](http://legion.stanford.edu/debugging/#privilege-checks).\n  * `BOUNDS_CHECKS=1`: enables [dynamic bounds checks](http://legion.stanford.edu/debugging/#bounds-checks).\n\n## Command-Line Flags\n\nLegion and Realm accept command-line arguments for various runtime\nparameters. Below are some of the more commonly used flags:\n\n  * `-level \u003ccategory\u003e=\u003cint\u003e`:\n    sets [logging level](http://legion.stanford.edu/debugging/#logging-infrastructure) for `category`\n  * `-logfile \u003cfilename\u003e`:\n    directs [logging output](http://legion.stanford.edu/debugging/#logging-infrastructure) to `filename`\n  * `-ll:cpu \u003cint\u003e`: CPU processors to create per process\n  * `-ll:gpu \u003cint\u003e`: GPU processors to create per process\n  * `-ll:util \u003cint\u003e`: utility processors to create per process\n  * `-ll:csize \u003cint\u003e`: size of CPU DRAM memory per process (in MB)\n  * `-ll:gsize \u003cint\u003e`: size of GASNET global memory available per process (in MB)\n  * `-ll:rsize \u003cint\u003e`: size of GASNET registered RDMA memory available per process (in MB)\n  * `-ll:fsize \u003cint\u003e`: size of framebuffer memory for each GPU (in MB)\n  * `-ll:zsize \u003cint\u003e`: size of zero-copy memory for each GPU (in MB)\n  * `-lg:window \u003cint\u003e`: maximum number of tasks that can be created in a parent task window\n  * `-lg:sched \u003cint\u003e`: minimum number of tasks to try to schedule for each invocation of the scheduler\n\nThe default mapper also has several flags for controlling the default mapping.\nSee `default_mapper.cc` for more details.\n\n## Developing Programs\n\nTo start a new Legion application, make a new directory and copy\n`apps/Makefile.template` into your directory under the name\n`Makefile`. Fill in the appropriate fields at the top of the Makefile\nwith the filenames needed for your application.\n\nMost Legion APIs are described in `legion.h`; a smaller number are\ndescribed in the various header files in the `runtime/realm`\ndirectory. The default mapper is available in `default_mapper.h`.\n\n## Debugging\n\nLegion has a number of tools to aid in debugging programs.\n\n### Extended Correctness Checks\n\nCompile with `DEBUG=1 PRIVILEGE_CHECKS=1 BOUNDS_CHECKS=1\"\nmake` and rerun the application. This enables dynamic checks for\nprivilege and out-of-bounds errors in the application. (These checks\nare not enabled by default because they are relatively expensive.) If\nthe application runs without terminating with an error, then continue\non to Legion Spy.\n\n### Legion Spy\n\nLegion provides a task-level visualization tool called Legion\nSpy. This captures the logical and physical dependence graphs. These\nmay help, for example, as a sanity check to ensure that the correct\nsequence of tasks is being launched (and the tasks have the correct\ndependencies). Legion Spy also has a self-checking mode which can\nvalidate the correctness of the runtime's logical and physical\ndependence algorithms.\n\nTo capture a trace, invoke the application with `-lg:spy -logfile\nspy_%.log`. (No special compile-time flags are required.) This will\nproduce a log file per node. Call the post-processing script to render\nPDF files of the dependence graphs:\n\n```bash\n./app -lg:spy -logfile spy_%.log\n$LG_RT_DIR/../tools/legion_spy.py -dez spy_*.log\n```\n\nTo run Legion Spy's self-checking mode, Legion must be built with the\nflag `USE_SPY=1`. Following this, the application can be run again,\nand the script used to validate (or render) the trace.\n\n```bash\nDEBUG=1 USE_SPY=1 make\n./app -lg:spy -logfile spy_%.log\n$LG_RT_DIR/../tools/legion_spy.py -lpa spy_*.log\n$LG_RT_DIR/../tools/legion_spy.py -dez spy_*.log\n```\n\n## Profiling\n\nLegion contains a task-level profiler. No special compile-time flags\nare required. However, it is recommended to build with `DEBUG=0 make`\nto avoid any undesired performance issues.\n\nTo profile an application, run with `-lg:prof \u003cN\u003e` where `N` is the\nnumber of nodes to be profiled. (`N` can be less than the total number\nof nodes---this profiles a subset of the nodes.) Use the\n`-lg:prof_logfile \u003clogfile\u003e` flag to save the output from each node to\na separate file. The argument to the `-lg:prof_logfile` flag follows\nthe same format as for `-logfile`, except that a `%` (to be replaced\nby the node number) is mandatory. Finally, pass the resulting log\nfiles to `legion_prof.py`.\n\n```bash\nDEBUG=0 make\n./app -lg:prof \u003cN\u003e -lg:prof_logfile prof_%.gz\n$LG_RT_DIR/../tools/legion_prof.py prof_*.gz\n```\n\nThis will generate a subdirectory called `legion_prof` under the\ncurrent directory, including a file named `index.html`. Open this file\nin a browser.\n\n## Other Features\n\n- Inorder Execution: Users can force the high-level runtime to execute\nall tasks in program order by passing `-lg:inorder` flag on the\ncommand-line.\n\n- Dynamic Independence Tests: Users can request the high-level runtime\nperform dynamic independence tests between regions and partitions by\npassing `-lg:dynamic` flag on the command-line.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStanfordLegion%2Flegion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStanfordLegion%2Flegion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStanfordLegion%2Flegion/lists"}