{"id":17970377,"url":"https://github.com/kkli08/electrostatic_particle_simulation","last_synced_at":"2025-08-16T15:32:42.679Z","repository":{"id":259692520,"uuid":"873373375","full_name":"kkli08/Electrostatic_Particle_Simulation","owner":"kkli08","description":"Range-Limited Electrostatic Particle Simulation.","archived":false,"fork":false,"pushed_at":"2024-10-27T09:17:37.000Z","size":47426,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-17T00:28:14.983Z","etag":null,"topics":["c-plus-plus","mpi","parallel-computing"],"latest_commit_sha":null,"homepage":"","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/kkli08.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":"2024-10-16T04:02:08.000Z","updated_at":"2024-10-27T09:28:30.000Z","dependencies_parsed_at":"2024-10-27T12:10:25.839Z","dependency_job_id":null,"html_url":"https://github.com/kkli08/Electrostatic_Particle_Simulation","commit_stats":null,"previous_names":["kkli08/electrostatic_particle_simulation"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkli08%2FElectrostatic_Particle_Simulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkli08%2FElectrostatic_Particle_Simulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkli08%2FElectrostatic_Particle_Simulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkli08%2FElectrostatic_Particle_Simulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkli08","download_url":"https://codeload.github.com/kkli08/Electrostatic_Particle_Simulation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230043790,"owners_count":18164066,"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":["c-plus-plus","mpi","parallel-computing"],"created_at":"2024-10-29T15:05:08.592Z","updated_at":"2024-12-17T00:28:42.521Z","avatar_url":"https://github.com/kkli08.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Electrostatic_Particle_Simulation\nA Range-Limited Electrostatic N-Particle Simulation.\n![](hist_data/chart/system_demo.png)\n\n### Usage\n```text\nUsage: nParticleSim [OPTIONS]\nOptions:\n--mode              Select Mode {1,2,3}\n--cutoff_radius     Enter the cutoff radius (1e-10 m)\n--input             Enter the file path for csv (particles.csv)\n--num_threads       Enter number of threads in Mode 2 and 3 (for each process)\n--leader            Enter number of leader process in Mode 3\n```\n\n### Build and Run\n```shell\nmkdir build\ncd build\ncmake ..\ncmake --build .\n```\n**_e.g_**\n```shell\n// Mode 1\n./nParticleSim --mode=1 --cutoff_radius=45000 --input=../dataset/particles.csv \n```\n```shell\n// Mode 2\n./nParticleSim --mode=2 --cutoff_radius=47500 --input=../dataset/particles.csv --num_threads=50\n```\n\u003e [!TIP]\n\u003e Inorder to run program in mode 3, `mpirun -np {#_of_leaders}` is REQUIRED.\n```shell\n// Mode 3\nmpirun -np 2 ./nParticleSim --mode=3 --cutoff_radius=45000 --input=../dataset/particles.csv --num_threads=10\n```\n\n### Repo Structure\n```text\n\\ main.cpp --\u003e main program\n\\ CMakeLists.txt\n\\ Particle\n    \\ Particle.cpp\n        --\u003e struct ParticleData\n        --\u003e class Particle\n        --\u003e class CoulombForceCalculator\n    \\ ParticleReader.cpp\n        --\u003e class ParticleReader\n\\ Sequential\n    \\ Sequential.cpp # Mode 1: Sequential Model\n\\ Distributed\n    \\ Parallel.cpp # Mode 2: Evenly-Distributed Parallel Computation Model\n\\ Leader\n    \\ Leader.cpp # Mode 3: Load-Balanced, Leader-Based Parallel Computation Model\n\\ hist_data    \n    \\ chart (charts generated by python scripts)\n    \\ * :\n        generated data \u0026 python scripts\n\\ dataset --\u003e input data path\n```\n### Mode 1: Sequential Computation\n\u003e [!NOTE]\n\u003e This implementation is entirely serial. No multithreading, just the approximation method  \napplied to compute the signed scalar force sums on every particle. \n\n**Input parameters:**\n```shell\n./nParticleSim --mode=1 --cutoff_radius={%d} --input=../dataset/particles.csv \n```\n\n![](dfd/mode_1_dfd.drawio.png)\n\n[//]: # (#### Area Chart for Different Cutoff Radius)\n\n[//]: # (![]\u0026#40;hist_data/chart/area_line_chart_cr.png\u0026#41;)\n[//]: # ()\n#### Mean Percentage Error for Different Cutoff Radius\n![](hist_data/chart/mape_cr.png)\n**_Run, Test and Generate Graph_**\n```shell\n// activate virtual env\nsource venv/bin/activate\n\n// GOTO directory\ncd hist_data/cr\n\n// the output files I provided have the format of output_parallel_{%d}.csv where {%d} is the\n// cutoff radius. you can use whatever mode you want to generate result and rename it in the \n// same format and add the cutoff radius in the list in the script.\npython3 output_parallel_mape.py\n```\n\n### Mode 2: Evenly-Distributed Parallel Computation\n\u003e [!NOTE]\n\u003e In this implementation, I use the `std::thread` execution model to create multiple threads and \ndivide the computation among the threads. I divide the dataset among the threads at the point in \ntime when the thread is created, so that once it finishes its given portion of work, it returns. \nThe work is as evenly as possible divided among the threads. \n\n**Input parameters:**\n```shell\n./nParticleSim --mode=2 --cutoff_radius={%d} --input=../dataset/particles.csv --num_threads={%d}\n```\n![](dfd/mode_2_dfd.drawio.png)\n\n#### Total Time Consumed vs Number of Threads\n\u003e [!IMPORTANT]\n\u003e `--cutoff_radius=45000`\n\n![](hist_data/chart/total_time_threads.png)\n**_Run, Test and Generate Graph_**\n```shell\n// activate virtual env\nsource venv/bin/activate\n\n// GOTO directory\ncd hist_data/mode_2_threads_compare\n\n// the output files I provided have the format of timing_cutoff_{radius}_threads_{%d}.csv where {%d} is the\n// number of threads. Use Mode 2 generate result txt files; The Mode 2 will record the time consumed and save\n// the result in the txt file.\npython3 threads_compare.py // this is Graph 1\n```\n#### Average Time per Particle vs Number of Threads\n\u003e [!IMPORTANT]\n\u003e `--cutoff_radius=45000`\n\n![](hist_data/chart/average_time_particle_threads.png)\n\n**_Run, Test and Generate Graph_**\n```shell\n// activate virtual env\nsource venv/bin/activate\n\n// GOTO directory\ncd hist_data/mode_2_threads_compare\n\n// the output files I provided have the format of timing_cutoff_{radius}_threads_{%d}.csv where {%d} is the\n// number of threads. Use Mode 2 generate result txt files; The Mode 2 will record the time consumed and save\n// the result in the txt file.\npython3 threads_compare.py // this is Graph 2\n```\n\n### Mode 3: Load-Balanced, Leader-Based Parallel Computation\n\u003e [!NOTE]\n\u003e In this implementation, I implement load-balanced, leader-based computation using [Open MPI](https://www.open-mpi.org/). Each leader is given an \nequal partition of the dataset. Each leader creates a pool of worker threads in the form of `threads`. \nEach leader’s partition of the data will be further partitioned into smaller chunks and placed into a `worker queue` that \ncan be accessed by all of its worker threads. Worker threads take one small chunk of data at a time, execute \nthe necessary computation, and then return to the queue to take more work. Threads only return once the queue is \nempty and all work is done. \n\n```shell\nmpirun -np {%num_of_leaders} ./nParticleSim --mode=3 --cutoff_radius=45000 --input=../dataset/particles.csv --num_threads={%d}\n```\n![](dfd/mode_3_dfd.drawio.png)\n\n#### Average Computation Time vs Number of Leaders\n\u003e [!IMPORTANT]\n\u003e `--cutoff_radius=45000` , `--num_threads=10`\n\n![](hist_data/chart/mode_3_average_leader_compute_time.png)\n**_Run, Test and Generate Graph_**\n```shell\n// activate virtual env\nsource venv/bin/activate\n\n// GOTO directory\ncd hist_data/mode_3\n\n// use leader_process_executions.py to automatically run the program with different \n// number of leaders and threads\npython3 leader_process_executions.py\n\n// Graph 1 is Average Computation Time vs Number of Leaders\npython3 comparision_of_total_computation.py\n```\n\n#### Mode 2 vs Mode 3 (same number of threads)\n\u003e [!IMPORTANT]\n\u003e `--cutoff_radius=45000`\n\n![](hist_data/chart/mode_3_load_balance_compare.png)\n**_Run, Test and Generate Graph_**\n```shell\n// activate virtual env\nsource venv/bin/activate\n\n// GOTO directory\ncd hist_data/mode_3\n\n// use leader_process_executions.py to automatically run the program with different \n// number of leaders and threads\npython3 leader_process_executions.py\n\n// Graph 2 is Total Computation Time vs Number of Threads (different mode)\npython3 comparision_of_total_computation.py\n```\n### _Hardware Resources_\n```text\nSystem:     macOS Sonoma Version 14.3.1\nChip:       Apple M3 Max\nMemory:     48 GB\nCore:       16-core CPU and 40-core GPU (400GB/s memory bandwidth)\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkli08%2Felectrostatic_particle_simulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkli08%2Felectrostatic_particle_simulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkli08%2Felectrostatic_particle_simulation/lists"}