{"id":23301879,"url":"https://github.com/briancairl/multi_field_array","last_synced_at":"2025-07-30T21:06:43.618Z","repository":{"id":43408548,"uuid":"410696194","full_name":"briancairl/multi_field_array","owner":"briancairl","description":"Data-oriented multi-field array container class template written in C++17 ","archived":false,"fork":false,"pushed_at":"2022-05-02T04:30:52.000Z","size":84,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-03-17T10:35:22.785Z","etag":null,"topics":["array","cpp","cpp17","data-oriented","data-oriented-design","data-oriented-programming","header-only","modern-cpp","parallel-array","soa","structure-of-arrays","template","vector"],"latest_commit_sha":null,"homepage":"","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/briancairl.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":"2021-09-27T00:36:57.000Z","updated_at":"2024-02-13T00:42:47.000Z","dependencies_parsed_at":"2022-08-26T20:58:00.444Z","dependency_job_id":null,"html_url":"https://github.com/briancairl/multi_field_array","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briancairl%2Fmulti_field_array","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briancairl%2Fmulti_field_array/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briancairl%2Fmulti_field_array/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briancairl%2Fmulti_field_array/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/briancairl","download_url":"https://codeload.github.com/briancairl/multi_field_array/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230568523,"owners_count":18246378,"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":["array","cpp","cpp17","data-oriented","data-oriented-design","data-oriented-programming","header-only","modern-cpp","parallel-array","soa","structure-of-arrays","template","vector"],"created_at":"2024-12-20T10:17:51.511Z","updated_at":"2024-12-20T10:17:52.455Z","avatar_url":"https://github.com/briancairl.png","language":"C++","readme":"[![Pull Request](https://github.com/briancairl/multi_field_array/actions/workflows/pr.yml/badge.svg)](https://github.com/briancairl/multi_field_array/actions/workflows/pr.yml)\n\n# MultiFieldArray container library\n\nC++17 library which implements the well known [\"parallel array\" or \"structure of arrays\" (SoA)](https://en.wikipedia.org/wiki/Parallel_array), called a \"multi-field array\" here. The container is essentially a data-oriented alternative to a `std::vector\u003cS\u003e`, where `S` is a structure with multiple fields, and is, thus, an \"array of structures\" (AoS).\n\n## Dependencies\n\n### General Use\n\n- C++17 Standard Library\n\n### Unit Tests\n\n- C++17 Standard Library\n- [google-test](https://github.com/google/googletest)\n\n### Benchmarking\n\n- C++17 Standard Library\n- [google-benchmark](https://github.com/google/benchmark)\n\n## Motivation\n\nTake the following use case:\n\n```c++\n\n#include \u003ciostream\u003e\n#include \u003cstring\u003e\n#include \u003cvector\u003e\n\nstruct MyStruct\n{\n  float a;\n  double b;\n  std::string c;\n};\n\nstd::vector\u003cMyStruct\u003e vec;\n\nvec.resize(5);\n\nfor (const auto\u0026 v : vec)\n{\n  std::cout \u003c\u003c v.a \u003c\u003c std::endl;\n}\n\n```\n\nWhen we iterate over `std::vector\u003cMyStruct\u003e`, all fields (a.k.a. comonent, member variable) of each element of type `MyStruct` is loaded into CPU cache, even if we don't need it. Instead, we can take a data-oriented approach where each field is stored in its own buffer. A container which models this approach might look as follows:\n\n```c++\n\ntemplate\u003ctypename A, typename B, typename C\u003e\nstruct MultiFieldArray\n{\n  // std::vector\u003cX\u003e for exposition only...\n  std::vector\u003cA\u003e a_data;\n  std::vector\u003cB\u003e b_data;\n  std::vector\u003cC\u003e c_data;\n};\n\n```\n\nThe `MultiFieldArray` follows this approach, and provides accessors for iterating over subsets of the types that it manages. For instance, one can achieve the following:\n\n```c++\nmf::multi_field_array\u003cint, float, char\u003e mfa;\n\nfor (auto [a, b] : mfa.view\u003cint, float\u003e())\n{\n  // Iterating over just the int and float fields\n}\n\nfor (auto [a, b, c] : mfa.view())\n{\n  // Iterating over all fields\n}\n```\n\nOne can also access a subset of components positionally, like so:\n\n```c++\nmf::multi_field_array\u003cint, float, char\u003e mfa;\n\nmfa.resize(10);\n\nauto view = mfa.view\u003cint, float\u003e();\n\nauto [int_ref, float_ref] = view[3];\n\nint_ref = 1;\n\nfloat_ref = 3.f;\n\nauto [int_ref_b, float_ref_b] = view.at(3);  // with bounds checking\n```\n\nAccessing all components positionally is also possible:\n\n```c++\nmf::multi_field_array\u003cint, float, char\u003e mfa;\n\nmfa.resize(10);\n\nauto [int_ref, float_ref, char_ref] = mfa[3];\n\nint_ref = 1;\n\nfloat_ref = 3.f;\n\nchar_ref = 'a';\n\nauto [int_ref_b, float_ref_b, char_ref_b] = mfa.at(3);  // with bounds checking\n```\n\n# Performance\n\n## Running micro-benchmarking tests\n```\nbazel test //test/benchmark/... --test_output=all --cache_test_results=no\n```\n\n## Example micro-benchmarking output\n```\nRun on (8 X 4500 MHz CPU s)\nCPU Caches:\n  L1 Data 32 KiB (x4)\n  L1 Instruction 32 KiB (x4)\n  L2 Unified 256 KiB (x4)\n  L3 Unified 8192 KiB (x1)\nLoad Average: 0.66, 0.48, 0.49\n\n--------------------------------------------------------------------------------------\nBenchmark                                            Time             CPU   Iterations\n--------------------------------------------------------------------------------------\nIteration_One_Of_Two_Fields_MFA                 911860 ns       911152 ns          765   \u003c-- Accessing one field of MultiFieldArray of two field types\nIteration_One_Of_Two_Fields_Vec                1924595 ns      1921561 ns          387   \u003c-- Accessing one field of std::vector\u003cStruct\u003e with two members\nIteration_Two_Of_Two_Fields_MFA                2335226 ns      2331385 ns          301\nIteration_Two_Of_Two_Fields_Vec                2542674 ns      2538851 ns          288\nIteration_Two_Of_Many_Fields_MFA_View          2454603 ns      2450854 ns          265\nIteration_Two_Of_Many_Fields_MFA_All_Fields    2286510 ns      2283481 ns          292\nIteration_Two_Of_Many_Fields_Vec               2908417 ns      2907053 ns          240\nIteration_One_Of_Many_Fields_MFA_View           909963 ns       909970 ns          766\nIteration_One_Of_Many_Fields_MFA_All_Fields     908849 ns       908857 ns          760\nIteration_One_Of_Many_Fields_Vec               2556763 ns      2556768 ns          263\nAllocation_Two_Fields_MFA                        20553 ns        20554 ns        34162\nAllocation_Two_Fields_Vec                        25640 ns        25641 ns        27229\nAllocation_Many_Fields_MFA                       20441 ns        20441 ns        33742\nAllocation_Many_Fields_Vec                       35104 ns        35104 ns        19913\n================================================================================\n```\n\n# TODOs\n\n- [x] Add \"single allocation\" strategy option, which will allocate all field memory at once, rather than with separate allocation calls\n- [ ] Add `CMake` build configuration\n- [ ] Add `CMake` CI step\n- [ ] Add Doxygen documentation page releases\n- [x] Add benchmark tests\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbriancairl%2Fmulti_field_array","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbriancairl%2Fmulti_field_array","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbriancairl%2Fmulti_field_array/lists"}