{"id":37643593,"url":"https://github.com/charmplusplus/projections","last_synced_at":"2026-01-16T11:22:41.240Z","repository":{"id":39615805,"uuid":"86751036","full_name":"charmplusplus/projections","owner":"charmplusplus","description":"Performance Analysis Tool for Charm++","archived":false,"fork":false,"pushed_at":"2025-09-02T16:35:46.000Z","size":7891,"stargazers_count":6,"open_issues_count":42,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-10T01:30:38.605Z","etag":null,"topics":["charm","java","parallel","performance-analysis"],"latest_commit_sha":null,"homepage":"","language":"Java","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/charmplusplus.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-03-30T21:36:35.000Z","updated_at":"2025-09-02T16:35:49.000Z","dependencies_parsed_at":"2024-05-16T21:43:59.907Z","dependency_job_id":"97ed9047-638e-444f-be63-ae31edde0a85","html_url":"https://github.com/charmplusplus/projections","commit_stats":null,"previous_names":["charmplusplus/projections"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/charmplusplus/projections","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmplusplus%2Fprojections","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmplusplus%2Fprojections/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmplusplus%2Fprojections/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmplusplus%2Fprojections/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charmplusplus","download_url":"https://codeload.github.com/charmplusplus/projections/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charmplusplus%2Fprojections/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: 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":["charm","java","parallel","performance-analysis"],"created_at":"2026-01-16T11:22:40.680Z","updated_at":"2026-01-16T11:22:41.233Z","avatar_url":"https://github.com/charmplusplus.png","language":"Java","readme":"# Projections\n\n![Projections CI](https://github.com/UIUC-PPL/projections/workflows/Projections%20CI/badge.svg?event=push)\n[![Documentation Status](https://readthedocs.org/projects/charm/badge/?version=latest)](https://charm.readthedocs.io/en/latest/projections/manual.html)\n[![DOI](https://zenodo.org/badge/86751036.svg)](https://zenodo.org/badge/latestdoi/86751036)\n\n\nProjections is a tool to visusalize execution traces of Charm++ and AMPI applications.\n\n## Compiling Projections\n\n1) Make sure the JDK commands `java`, `javac` and `jar`\n   are in your path. You should use at least Java version 8,\n   and your java and javac should be of the same version.\n   You also need [`gradle`](https://gradle.org/) and, optionally,\n   the GNU tool `make`.\n\n2) Type `make` (or `gradle copyJarToBin` if you don't have `make`).\n\n3) The following files will be located in `bin`:\n\n      `projections`          : Starts projections, for UNIX machines\n      \n      `projections.bat`       : Starts projections, for Windows machines\n      \n      `projections.jar`       : archive of all the java and image files\n\n\n## Running Projections\n\nRun `$ ./bin/projections` from the root of the Projections directory.\n\n## Using Projections\n\nProjections is a visualization tool to help you understand and analyze what it\nhappening in your parallel (Charm++) program.  To use Projections, you first\nhave to make sure that Charm++ is compiled with tracing enabled and that your\nprogram is compiled with the Projections tracemode.  Usually, this means adding\n`--enable-tracing` to your Charm++ build options and `-tracemode projections`\nto your program compile options.  When you run your program compiled with this\ntracemode, a log file will be created for each processor.  An additional state\nfile will also be created.  The names of the log files will be `NAME.#.log{.gz}`,\nwhere NAME is the name of your executable and # is the processor #.  The name of\nthe state file is NAME.sts.\n\nIf your environment is set up correctly, as described in the previous section,\nall you have to do to start Projections is type 'projections' at the prompt.\n\nWhen Projections starts, you will see the main window with a toolbar with three\noptions, File, Tools, and Debug.\n\nTo begin using Projections, use \"File -\u003e Open File(s)\" to select the data you\nwant to analyze.  To do so, navigate to the directory containing your data and\nselect the \\*.sts file.  If you have selected a valid file, Projections will load\nin some preliminary data from the files and then activate the rest of the buttons\nin the main window.  If your file is invalid, you will be shown an error dialog.\n\nAfter opening a file, there are many different tools you can use to analyze your\ndata:\n\n1. Timelines\n2. Usage Profile\n3. Communication Per Processor\n4. Communication Over Time\n5. Call Table\n6. View Log Files\n7. Histograms\n8. Overview\n9. Animation\n10. Time Profile\n11. Performance Counters\n12. User Events\n13. User Stats Over Time\n14. User Stats Per Processor\n15. Extrema Analysis\n16. Multirun Analysis\n17. Noise Miner\n18. Streaming CCS\n19. Memory Usage\n\n### Tool descriptions\n\n#### 1. Timelines\n\nThe Timelines window lets you look at what a specific processor is doing at\neach moment of the program.\n\nWhen the Timelines window first appears, a dialog box appears along with it.\nThe box asks for the following information:\n\n- Processors:  Choose which processor(s) you want to see a timeline for.\n               To enter multiple values, separate them with a comma or a\n               dash (for ranges).  Strides can be specified by\n               using a colon to denote the stride size.  Some\n               examples:\n\n    | To see processors | Enter   |\n    |-------------------|---------|\n    | 1, 3, 5, 7        |  1,7:2  |\n    | 1, 2, 3, 4        | 1-4     |\n    | 1, 2, 3, 7        | 1,2,3,7 |\n\n\n\n- Start Time  : Choose what time you want your timeline to start at.\n- End Time    : Choose what time you want your timeline to end at.\n\nThe dialog box tells you what the valid processor choices are, as well as what\nthe valid time ranges are.\n\nParticular time/processor ranges can be saved by using the \"Add to\nHistory List\" button, which will save the currently selected\nprocessors and time range for later use.  The dropdown menu above\nthe button shows the current saved ranges.  Particular ranges can\nbe removed by clicking the \"Remove Selected History\" button and the\nhistory can be saved to disk for future runs using the \"Save\nHistory to Disk\" button.\n\nTo select annotated timesteps, click the \"Find Annotated Timesteps\"\nbutton. This finds user supplied notes on PE 0 that contain the\nsigil \"***\".  The times that these notes were made on PE 0 are\nannotated timesteps. After clicking the button, two dropdown\ncontaining the names of the annotated timesteps are displayed, and\nyou can then select which timesteps you would like to use for the\nstart and end times of the range.\n\nThere are options to filter out entries shorter than a certain\ntime, filter out messages, filter out user events, and highlight\nthe top n longest idle and entry times.\n\nTo automatically select the portion of the execution with valid\nperformance data, click on \"Adjust ranges to show useful\ninformation\" at the bottom of the window.\n\nWhen you are satisfied with your time and processor ranges, click on 'OK'.\nProjections will then get the Timeline data for you.  The time for this step\ndepends on the number of items in your time range and the number of\nprocessors you have chosen.\n\nThe Timeline Window consists of two parts:\n\n1) Display Panel:\n\n   This is where the timelines are displayed and is the largest portion of\n   the window.  The time axis is displayed at the top of the panel,\n   and the units are microseconds.  The left side of the panel\n   shows the processor labels.  Underneath each label are two numbers, the first\n   indicating the percentage of the total time in your\n   timeline that particular PE spent busy during the execution, and\n   the second indicating the percentage of the total time that PE\n   spent actually working on the application's entry methods.  The\n   timeline itself consists of colored bars for each\n   work item.  Placing the cursor over one of these bars will bring up a\n   pop-up window telling you the name of that item, the begin time, the end\n   time, and the total time.  It will also tell you what amount of time was\n   spent packing, how many messages were created during this work item, and\n   which processor created this item.  If you click on the item, by\n   default, a line will be traced from the work item to the sender\n   of the message responsible for this work item.  This behavior\n   can be modified by selecting different options in the Tracing menu\n   item.  Additionally, right clicking on a work item brings up a\n   context menu, allowing you to view more details of that work\n   item, change the color of that entry method, and drop or load\n   other PEs based on their relation to that work item.  Viewing\n   more details shows a window listing all of the messages\n   created during this work item along with their targets and send\n   times, along with other details of the work item.\n\n2) Control Panel:\n\n   - At the bottom of the window\n   Checkboxes:\n   - Display Pack Times\n   - Display Message Sends\n     These are represented by little white vertical lines at the\n     time a message was created.\n   - Display Idle Time\n   - Display User Events\n   - View n User Events\n     Opens a new window showing user events on the selected PEs\n   Buttons:\n   - Load New Time/PE Range\n     Brings up the initial dialog box to select a new range\n   - Zoom In/Out\n   - Zoom Selection / Load Selection\n     After highlighting a section of the display by clicking and\n     dragging in the time axis area, these options let you either zoom\n     into the selected area or reload the selected area.\n\n\n#### 2. Usage Profile:\n\nThe Usage Profile window lets you see percentage-wise what each processor\nspends its time on during a specified period.\n\nWhen the window first comes up, a dialog box appears asking for the\nprocessor(s) you want to look at as well as the time range you want to look\nat.  This is similar to the dialog for the Timelines.\n\nThe bottom portion of the Usage Profile window lets you adjust the scales in\nboth the X and Y directions.  The X direction is useful if you are looking at\na large number of processors.  The Y direction is useful if there are\nsmall-percentage items for a processor.\n\nThe left side of the display shows a scale from 0% to 100%.  The main part of\nthe display shows the statistics.  Each processor is represented by a\nvertical bar.  The top of the bar always shows the overhead time.  Below that\nis always (if exists) the idle time and then the message packing/unpacking\ntimes.  The rest of the bar is ordered from the bottom with the largest\npercentage items being closest to the bottom.  If you place the cursor over a\nportion of the bar, a pop-up window will appear telling you the name of the\nitem, what percent of the usage it has, and the processor it is on.\n\n\n#### 3. Communication Per Processor:\n\nThis tool shows communication over the interval per selected\nPE. This view is in the processor domain. It can show the number of\nmessages or bytes sent or received, depending on the option\nselected at the bottom of the window.\n\n\n#### 4. Communication Over Time:\n\nThis tool shows communication over time across all selected PEs.\nThis view is in the time domain. It can show the number of messages\nor bytes sent or received, depending on the option selected at the\nbottom of the window.\n\n\n#### 5. Call Table:\n\nThis tool shows all the entry methods invoked by other entry\nmethods. The left aligned entry method name indicates the current\nentry method, and the indented entry methods below are those called\nby the current entry method.  Enabling EP Detail or Statistics at\nthe bottom shows the qualified name and parameter list of the EP\nor the number of total messages received, bytes received, and\nstatistics on the received bytes, respectively.\n\n\n#### 6. View Log Files:\n\nThis tool shows raw log files for the selected PEs and time\ninterval. The log files are parsed by Projections and event types,\nentry method names, etc. are printed rather than the raw integers\nof the actual logs.\n\n\n#### 7. Histograms:\n\nThis tool creates histograms for various properties of the program,\nexecution time, accumulated execution time, message size, and idle\npercentage.\n\n\n#### 8. Overview:\n\nThis tool shows a high level overview of execution across the\nselected PEs and time interval. It displays a dense, quantized view\nof the execution of the program, either in terms of entry methods\nor utilization.  Essentially, it provides a coarser view of the\nsame information as Timeline (see #1).\n\n\n#### 9. Animations:\n\nThis window animates the processor usage by displaying\ndifferent colors for different amount of usage.\n\nThe left box allows you to select the real time between frames;\nthe right box the processor time between frames.\n\n\n#### 10. Time Profile:\n\nThis tool shows execution across the selected PEs and time\ninterval. This view is in the time domain. This tool shows a high\nlevel overview of execution across the selected PEs and time\ninterval. It displays a dense, quantized view of the execution of\nthe program, either in terms of entry methods or utilization.\nEssentially, it provides a coarser view of the same information as\nTimeline (see #1).\n\n\n#### 11. Performance Counters:\n\nThis tool shows the values of performance counters per entry point\nand PE. This option is disabled unless Charm++ was compiled with\nsupport for PAPI counters.\n\n\n#### 12. User Events:\n\nThis tool shows the summation of bracketed user events per PE\nacross the selected PEs and time interval.\n\n\n#### 13. User Stats Over Time:\n\nThis tool shows the values of user stats over the program execution\nacross the selected PEs and time interval. This view is in the\ntime domain.\n\n\n#### 14. User Stats Per Processor:\n\nThis tool shows the values of user stats per PE\nacross the selected PEs and time interval. This view is in the\nPE domain.\n\n\n#### 15. Extrema Analysis:\n\nThis tool identifies extreme clusters of particular attributes\nthrough the execution. The attribute, activity, extrema threshold,\nand number of clusters are customizable when selecting a time range.\n\n\n#### 16. Multirun Analysis:\n\nThis tool compares multiple executions of a program to each other,\nshowing how time spent in entry methods changes across the\nexecution. Currently, this view only works with summary data due to\nmemory constraints.\n\n\n#### 17. Noise Miner:\n\nThis tool identifies abnormally long entry methods to detect\nsymptoms consistent with computational noise.  Long events are\nfiltered and clustered to provide a summary of such occurrences.\n\n\n#### 18. Streaming CCS:\n\nThis tool uses the Converse Client Server feature of Charm++ to\nstream performance data from running programs.  To use it, the\nCharm++ program must be compiled with `-tracemode utilization`, and\nexecuted with `++server ++server-port \u003cport number\u003e`.\n\n\n#### 19. Memory Usage:\n\nThis tool provides a view of memory utilization in the application\nwhen it is linked with the memory tracing module.\n\n\n\n## Notes\n\nCharts in some tools are produced by JFreeChart.\nImage output is performed by FreeHEP.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharmplusplus%2Fprojections","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharmplusplus%2Fprojections","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharmplusplus%2Fprojections/lists"}