{"id":19705868,"url":"https://github.com/llnl/ravel","last_synced_at":"2025-04-29T16:32:00.137Z","repository":{"id":24488446,"uuid":"27893053","full_name":"LLNL/ravel","owner":"LLNL","description":"Ravel MPI trace visualization tool","archived":false,"fork":false,"pushed_at":"2021-09-12T23:05:39.000Z","size":1488,"stargazers_count":30,"open_issues_count":8,"forks_count":10,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-05T18:05:23.073Z","etag":null,"topics":["data-viz","mpi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LLNL.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}},"created_at":"2014-12-11T21:45:08.000Z","updated_at":"2025-02-23T11:55:25.000Z","dependencies_parsed_at":"2022-08-22T18:00:27.256Z","dependency_job_id":null,"html_url":"https://github.com/LLNL/ravel","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LLNL","download_url":"https://codeload.github.com/LLNL/ravel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251540255,"owners_count":21605872,"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":["data-viz","mpi"],"created_at":"2024-11-11T21:31:07.839Z","updated_at":"2025-04-29T16:31:55.127Z","avatar_url":"https://github.com/LLNL.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"Ravel\n=====\nRavel is a trace visualization tool for MPI with recent experimental support\nfor Charm++. Ravel is unique in that it shows not only physical timelines, but\nalso logical ones structured to better capture the intended organization of\ncommunication operations. Ravel calculates logical structure from Open Trace\nFormat or Charm++ Projections logs and presents the results using multiple\ncoordinated views.\n\nIn logical time, all operations are colored via some metric. The default\nmetric for MPI is *lateness* which measures the difference in exit time of an\noperation compared to its peers at the same logical timestep. \n\n![Ravel Logical and Physical Timelines](/images/pf3d32_sf_700.png)\n\nInstallation\n------------\nRavel depends on:\n- [Open Trace Format version 2 1.4+](http://www.vi-hps.org/projects/score-p/)\n- [Qt5+](http://www.qt.io/download/)\n- [Muster 1.0.1+](https://github.com/scalability-llnl/muster)\n- (Install only) [cmake 2.8.9+](http://www.cmake.org/download/)\n- (Optional) [Open Trace Format 1.12+](http://tu-dresden.de/die_tu_dresden/zentrale_einrichtungen/zih/forschung/projekte/otf/index_html/document_view?set_language=en)\n\nTo install:\n\n    $ git clone https://github.com/scalability-llnl/ravel.git\n    $ mkdir ravel/build\n    $ cd ravel/build\n    $ cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/directory ..\n    $ make\n    $ make install\n\nIf a dependency is not found, add its install directory to the\n`CMAKE_PREFIX_PATH` environment variable.\n\nUsage\n-----\n\n### Opening a Trace\n\nBefore opening the trace, check your settings under `Options-\u003eOTF Importing`.\nThese options will affect the logical organization even determined by Ravel.\nOnce you are happy with your options, use `File-\u003eOpen Trace` and navigate to\nyour `.otf`, `.otf2`, or `.sts` file.\n\n#### Partitions\n\nRavel partitions the trace into fine-grained communication phases -- sets of\ncommunication operations that must belong together. It imposes a\nhappened-before ordering between traces to better represent how developers\nthink of them separately.\n\n* Automatically determine partitions: use happened-before relationships and\n  the following options:\n  * use Waitall heuristic: OTF version 1 only, will group all uninterrupted \n    send operations before each Waitall in the same phase\n  * merge Partitions by call tree: Will merge communication operations up the\n    call stack until reaching a call containing multiple such operations. MPI\n    only.\n  * merge Partitions to complete Leaps: Avoids sparse partitions by forcing\n    each rank to be active at each distance in the phase DAG. Useful for bulk\n    synchronous codes. MPI only.\n    * skip Leaps that cannot be merged: Relaxes the leap merge when it cannot\n      find a next merge.\n  * merge across global steps: This merge happens after stepping, so it does\n    not affect the logical structure, but groups MPI ranks that cover the same\n    logical step. MPI only.\n  * Charm++ break functions: Force the breaking of partitions at the given\n    common-separated list of Charm++ entry methods.\n* Partition at function breaks: Use if you know your phases are contained in\n  a given function. List the function. \n\n#### Other Options\n* Matching send/recv must have the same message size: Enforces send and receive\n  reporting the same message size. Uncheck this for Scalasca-generated OTF2.\n* Idealized order of receives: Change the order of receives from their true\n  physical time order to an idealized one in each phase. We recommend this for\n  Charm++. It is not compatible with clustering.\n* Advanced stepping within a partition: Align sends based on happened-before\n  structure rather than as early as possible. MPI only.\n* Coalesce Isends: Groups neighboring `MPI_Isend`s into a single operation\n  which may send to multiple receive operations. We recommend this option as a\n  default for all MPI traces.\n* Cluster processes: Shows a cluster view that clusters the processes by the\n  active metric. This is useful for large process counts. MPI only.\n  * Seed: Set seed for repeatable clustering.\n\n### Navigating Traces\n\nThe three timeline views support linked panning, zooming and selection. The\noverview shows the total metric value over time steps for the whole trace.\nClicking and dragging in this view will select a span of timesteps in the\nother views.\n\nNavigation | Control\n-----------|---------\nPan | Left-click drag\nZoom in time | Mouse wheel\nZoom in processes | Shift + Mouse wheel\nZoom to rectangle | Right-click drag rectangle\nSelect operation | Right-click operation\nTool tips | Hover\n\nThe cluster view has a slider which changes the size of the neighborhood shown\nin the upper part of the view. The lower part of the view shows the clusters.\nLeft-click to divide clusters into its children. Click on dendrogram nodes to\ncollapse clusters. Dendrogram pertains to left-most visible partition.\nClustering currently shows the first partition rather than all.\n\n### Saving Traces\nAll traces are saved in OTF2 and include only the information from the\noriginal trace that is used by Ravel. In addition, communication-related\noperations used for logical structure have an `OTF2_AttributeList` associated\nwith their Leave events. These lists include a `phase` and `step` value\ndefining the logical structure used by Ravel, as well as any metric values\ncomputed for that operation. Any metric values ending in `_agg` represent the\ncalculated value of the aggregated non-communication operation directly\npreceding.\n\n\nAuthors\n-------\nRavel was written by Kate Isaacs.\n\nLicense\n-------\nRavel is released under the LGPL license. For more details see the LICENSE\nfile.\n\nLLNL-CODE-663885\n\nRelated Publications\n--------------------\nKatherine E. Isaacs, Peer-Timo Bremer, Ilir Jusufi, Todd Gamblin, Abhinav\nBhatele, Martin Schulz, and Bernd Hamann. Combing the Communication Hairball:\nVisualizing Parallel Execution Traces using Logical Time. *IEEE Transactions on\nVisualization and Computer Graphics, Proceedings of InfoVis '14*, 20(12):2349-2358, December 2014. \n[DOI: 10.1109/TVCG.2014.2346456](http://dx.doi.org/10.1109/TVCG.2014.2346456)\n\nKatherine E. Isaacs, Abhinav Bhatele, Jonathan Lifflander, David Boehme, Todd\nGamblin, Bernd Hamann, Peer-Timo Bremer. Recovering Logical Structure from\nCharm++ Event Traces. In *Proceedings fo the ACM/IEEE Conference on\nSupercomputing (SC15)*, November 2015. [DOI:\n10.1145/2807591.2807634](http://dx.doi.org/10.1145/2807591.2807634)\n\nKatherine E. Isaacs, Todd Gamblin, Abhinav Bhatele, Martin Schulz, Bernd\nHamann, and Peer-Timo Bremer. Ordering Traces Logically to Identify Lateness\nin Message Passing Programs. *IEEE Transactions on Parallel and Distributed\nSystems*, 27(3):829-840, March 2016. [DOI:\n10.1109/TPDS.2015.2417531](http://dx.doi.org/10.1109/TPDS.2015.2417531)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllnl%2Fravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fravel/lists"}