{"id":22668192,"url":"https://github.com/lanl/matar","last_synced_at":"2025-08-21T12:31:07.056Z","repository":{"id":38034888,"uuid":"331380624","full_name":"lanl/MATAR","owner":"lanl","description":"MATAR is a C++ software library to allow developers to easily create and use dense and sparse data representations that are also portable across disparate architectures using Kokkos. ","archived":false,"fork":false,"pushed_at":"2024-12-19T15:59:09.000Z","size":18483,"stargazers_count":26,"open_issues_count":7,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-12-19T16:44:41.371Z","etag":null,"topics":["data-oriented","kokkos","performance","portability"],"latest_commit_sha":null,"homepage":"https://lanl.github.io/MATAR/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-01-20T17:29:44.000Z","updated_at":"2024-12-19T15:59:23.000Z","dependencies_parsed_at":"2024-03-18T20:16:34.424Z","dependency_job_id":"97eb0adf-5859-4cce-a1c3-aecfb5c0c939","html_url":"https://github.com/lanl/MATAR","commit_stats":{"total_commits":391,"total_committers":28,"mean_commits":"13.964285714285714","dds":0.8439897698209718,"last_synced_commit":"4f9c59420ec466d357ebd2b848a27e2024c5a9a4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FMATAR","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FMATAR/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FMATAR/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2FMATAR/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/MATAR/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230511483,"owners_count":18237658,"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-oriented","kokkos","performance","portability"],"created_at":"2024-12-09T15:14:02.926Z","updated_at":"2024-12-19T23:15:32.469Z","avatar_url":"https://github.com/lanl.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MATAR\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/lanl/MATAR/blob/main/MATAR-logo.png\" width=\"350\"\u003e\n\nMATAR is a C++ library that addresses the need for simple, fast, and memory-efficient multi-dimensional data representations for dense and sparse storage that arise with numerical methods and in software applications. The data representations are designed to perform well across multiple computer architectures, including CPUs and GPUs. MATAR allows users to easily create and use intricate data representations that are also portable across disparate architectures using Kokkos. The performance aspect is achieved by forcing contiguous memory layout (or as close to contiguous as possible) for multi-dimensional and multi-size dense or sparse MATrix and ARray (hence, MATAR) types. Results show that MATAR has the capability to improve memory utilization, performance, and programmer productivity in scientific computing. This is achieved by fitting more work into the available memory, minimizing memory loads required, and by loading memory in the most efficient order. \n\n\n## Examples\n* [ELEMENTS](https://github.com/lanl/ELEMENTS/):   MATAR is a part of the ELEMENTS Library (LANL C# C20058) and it underpins the routines implemented in ELEMENTS.  MATAR is available in a stand-alone directory outside of the ELEMENTS directory because it can aid many code applications.  The dense and sparse storage types in MATAR are the foundation for the ELEMENTS library, which contains mathematical functions to support a very broad range of element types including: linear, quadratic, and cubic serendipity elements in 2D and 3D; high-order spectral elements; and a linear 4D element. An unstructured high-order mesh class is available in ELEMENTS and it takes advantage of MATAR for efficient access of various mesh entities. \n\n* [Fierro](https://github.com/lanl/Fierro): The MATAR library underpins the Fierro code that is designed to simulate quasi-static solid mechanics problems and material dynamics problems.  \n    \n* Simple examples are in the /example folder\n\n## Descriptions\n\n* All Array MATAR types (e.g., CArray, ViewCArray, FArray, RaggedRightArray, etc.) start with an index of 0 and stop at an index of N-1, where N is the number of entries.  \n\n* All Matrix MATAR types  (e.g., CMatrix, ViewCMatrix, FMatrix, etc.)  start with an index of 1 and stop at an index of N, where N is the number of entries. \n\n* The MATAR View types (e.g., ViewCArray, ViewCMatrix, ViewFArray, etc. ) are designed to accept a pointer to an existing 1D array and then access that 1D data as a multi-dimensional array.  The MATAR View types can also be used to slice an existing View.  \n\n* The C dense storage and View types (e.g., CArray, ViewCArray, CMatrix, etc.) access the data following the C/C++ language convection of having the last index in a multi-dimensional array vary the quickest.  In a 2D CArray A, the index j in A(i,j) varies first followed by the index i, so the optimal performance is achieved using the following loop ordering.\n```\n// Optimal use of CArray\nfor (i=0,i\u003cN,i++){\n    for (j=0,j\u003cN,j++){\n        A(i,j) = 0.0;\n    }\n}\n```\n\n* The F dense storage and View types (e.g., FArray, ViewFArray, FMatrix, etc.) access the data following the Fortran language convection of having the first index in a multi-dimensional array vary the quickest.  In a 2D FMatrix M, the index i in M(i,j) varies first followed by the index j, so the optimal performance is achieved using the following loop ordering.\n\n```\n// Optimal use of FMatrix\nfor (j=1,j\u003c=N,j++){\n    for (i=1,i\u003c=N,i++){\n        M(i,j) = 0.0;\n    }\n}\n```\n\n* The ragged data types (e.g., RaggedRightArray, RaggedDownArray, etc) in MATAR are special sparse storage types.  The Right access types are for R(i,j) where the number of column entries varies in width across the array.  The Down access types are for D(i,j) where the number of row entries vary in length across the array.\n\n* The SparseRowArray MATAR type is the idetical to the Compressed Sparse Row (CSR) or Compressed Row Storage (CSR) respresentation.\n\n* The SparseColumnArray MATAR type is identical to the Compressed Sparse Column (CSC) or Compressed Column Storage (CCS) respresentation.\n\n\n## Usage\n```\n// create a 1D array of integers and then access as a 2D array\nint A[9];\nauto A_array = ViewCArray \u003cint\u003e (A, 3, 3); // access as A(i,j) \n\n// create a 3D array of doubles\nauto B = CArray \u003cdouble\u003e (3,3,3); // access as B(i,j,k)\n\n// create a slice of the 3D array at index 1\nauto C = ViewCArray \u003cdouble\u003e (\u0026B(1,0,0),3,3); // access as C(j,k)\n\n\n// create a 4D matrix of doubles, indices start at 1 \nauto D = CMatrix \u003cdouble\u003e (10,9,8,7); // access as D(i,j,k,l)\n\n\n// create a 2D view of a standard array\nstd::array\u003cint, 9\u003e E1d;\nauto E = ViewCArray\u003cint\u003e (\u0026E1d[0], 3, 3);\nE(0,0) = 1;  // and so on\n\n\n// create a ragged-right array of integers\n//\n// [1, 2, 3]\n// [4, 5]\n// [6]\n// [7, 8, 9, 10]\n//\nsize_t my_strides[4] = {3, 2, 1, 4};\nRaggedRightArray \u003cint\u003e ragged(my_strides, 4);\n    \nint value = 1;\nfor (int i=0; i\u003c4; i++){\n    for (int j=0; j\u003cmy_ragged.stride(i); j++){\n        ragged(i,j) = value;\n        value++;\n    }\n}\n\n\n```\nMore information about the capabilities and usage of MATAR can be found in this presentation [here](https://www.researchgate.net/publication/360744549_General_purpose_GPU_programming_made_easy).\n    \n## Cloning the code\nIf your SSH keys are set in github, then from the terminal type:\n```\ngit clone --recursive ssh://git@github.com/lanl/MATAR.git    \n```\nThe code can also be cloned using\n```\ngit clone --recursive https://github.com/lanl/MATAR.git\n```\n\n## Basic build\nThe basic build is for users only interested in the serial CPU only MATAR data types.  For this build, we recommend making a folder perhaps called build then go into the build folder and type\n```\ncmake ..\nmake\n```\nThe compiled code will be in the build folder.\n\n## Debug basic build \n\nTo build serial CPU only MATAR data types in the debug mode, please use\n```\ncmake -DCMAKE_BUILD_TYPE=Debug ..\nmake\n```\nThe debug flag includes checks on array and matrix dimensions and index bounds.\n\n\n## Building MATAR with Kokkos\nA building script is provided to build the MATAR examples and tests, with or without Kokkos. The simplest build with all defaults can be run with\n```\nsource {path-to-repo}/scripts/build-matar.sh\n```\nRunning with the argument ```--help``` will give a full list of all possible arguments.\nIf an argument is not changed, it will be set to the default action, which can all be found from the help command\nIf the scripts fail to build, then carefully review the modules used and the computer architecture settings.\n\n## Building MATAR with Anaconda\nThe recommended way to build **MATAR** is inside an Anaconda environment. As a starting place, follow the steps for your platform to install [anaconda](https://docs.anaconda.com/free/anaconda/install/index.html)/[miniconda](https://docs.conda.io/en/latest/miniconda.html)/[mamba](https://mamba.readthedocs.io/en/latest/installation.html). \n\nOpen a terminal on your machine and go to a folder where you want to run the **MATAR** code. Activate a bash terminal by typing:\n```\nbash\n```\nThen create and activate an Anaconda environment by typing:  \n```\nconda create -n MATAR\nconda activate MATAR  \n```\nIn this example, the enviroment is called MATAR, but any name can be used.  In some cases, the text to activate an enviroment is `source activate MATAR`.  Likewise, if an enviroment already exists, then just activate the desired environment. \n\nNow install a compiler and cmake, which are needed to build the MATAR library.\n```\nconda install -c conda-forge \"cxx-compiler=1.5.2\"     \nconda install -c conda-forge \"fortran-compiler=1.5.2\"\nconda install cmake\n```\nBy using cxx-compiler=1.5.2., it install gcc 11.  Omit the version number and gcc 12 will be installed (at this time).  If building for a GPU, it is recommended to use an older gcc version. For example, we have success using gcc 11 with CUDA 12.\n\nIf running on an Nvidia GPU, install cudatoolkit by typing:\n```\nconda install -c conda-forge cudatoolkit    \nconda install -c conda-forge cudatoolkit-dev\n```\nThis installs CUDA 12 (at this time).  \n\nThe build script is located at\n```\nsource {path-to-repo}/scripts/build-matar.sh\n```\n\nTo build the MATAR library and examples with CUDA, type:\n```\nsource build-matar.sh --kokkos_build_type=cuda --build_cores=16\n```\nThe executables for the examples that run in parallel Nvidia GPUs using CUDA are located in:\n```\nMATAR/build-matar-cuda/bin\n```\n\nTo build the MATAR library and examples with OpenMP, type:\n```\nsource build-matar.sh --kokkos_build_type=openmp --build_cores=16\n```\n\nThe executables for the examples that run in parallel on multi-core CPUs using OpenMP are located in:\n```\nMATAR/build-matar-openmp/bin\n```\nUsing the main_kokkos.cpp executable as an example, it can be run by typing:\n```\n./mtestkokkos\n```\n\n## Running codes in parallel\nThe openMP and pthread Kokkos backends require the user to specify the number of threads used to run the code in parallel. \nTo specify the number of threads with the Kokkos pthread backend, add the following command line argument when executing the code,\n```\n--kokkos-threads=4\n```\nin otherwords,\n```\n./mycode --kokkos-threads=4\n```\nThe above command runs the code with fine grained parallelism using 4 threads.  In your code, ensure you pass the command line argument variables to Kokkos::initialize function as shown below here.\n```\nint main(int argc, char* argv[])\n{\n    Kokkos::initialize(argc, argv);\n\n    // coding goes here\n\n    Kokkos::finalize();\n\n    return 0;\n}\n```\nThe above coding will still work if no command line arguments are given; that is key because the other kokkos backends do not need command line arguments.\n\nFor the openMP backend, set the number of threads as an environement variable; this is done by typing the following command in the terminal,\n```\nexport OMP_NUM_THREADS=4\n```\nThe CUDA and HIP backends do not need the number of threads specified.\n\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n\n## License\nThis program is open source under the BSD-3 License.\n\n## Citation\n```\n@article{MATAR,\ntitle = \"{MATAR: A Performance Portability and Productivity Implementation of Data-Oriented Design with Kokkos}\",\njournal = {Journal of Parallel and Distributed Computing},\npages = {86-104},\nvolume = {157},\nyear = {2021},\nauthor = {Daniel J. Dunning and Nathaniel R. Morgan and Jacob L. Moore and Eappen Nelluvelil and Tanya V. Tafolla and Robert W. Robey},\nkeywords = {Performance, Portability, Productivity, Memory Efficiency, GPUs, dense and sparse storage}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fmatar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fmatar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fmatar/lists"}