{"id":22668196,"url":"https://github.com/lanl/vpic","last_synced_at":"2025-10-05T08:18:35.930Z","repository":{"id":3918522,"uuid":"51323352","full_name":"lanl/vpic","owner":"lanl","description":"Vector Particle-In-Cell (VPIC) Project","archived":false,"fork":false,"pushed_at":"2025-06-19T18:38:36.000Z","size":24210,"stargazers_count":165,"open_issues_count":21,"forks_count":76,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-09-12T00:39:00.083Z","etag":null,"topics":["high-performance","high-performance-computing","hpc","hpc-applications","particle-in-cell"],"latest_commit_sha":null,"homepage":null,"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/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-02-08T20:04:21.000Z","updated_at":"2025-09-03T13:04:38.000Z","dependencies_parsed_at":"2023-07-05T17:00:09.825Z","dependency_job_id":null,"html_url":"https://github.com/lanl/vpic","commit_stats":{"total_commits":830,"total_committers":20,"mean_commits":41.5,"dds":0.6855421686746987,"last_synced_commit":"5d1aa3cceac48c5ff36e131cd26c89a85b118d75"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lanl/vpic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fvpic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fvpic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fvpic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fvpic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/vpic/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fvpic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278425778,"owners_count":25984765,"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","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["high-performance","high-performance-computing","hpc","hpc-applications","particle-in-cell"],"created_at":"2024-12-09T15:14:03.986Z","updated_at":"2025-10-05T08:18:35.908Z","avatar_url":"https://github.com/lanl.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vector Particle-In-Cell (VPIC) Project\n\nWelcome to the legacy version of VPIC!  The new version of VPIC, based on the\nKokkos performance portable framework, is available here:\n[https://github.com/lanl/vpic-kokkos](https://github.com/lanl/vpic-kokkos).\nThis legacy version is no longer under active development, and new users are\nencouraged to use the Kokkos version.\n\nVPIC is a general purpose particle-in-cell simulation code for modeling\nkinetic plasmas in one, two, or three spatial dimensions. It employs a\nsecond-order, explicit, leapfrog algorithm to update charged particle\npositions and velocities in order to solve the relativistic kinetic\nequation for each species in the plasma, along with a full Maxwell\ndescription for the electric and magnetic fields evolved via a second-\norder finite-difference-time-domain (FDTD) solve. The VPIC code has been\noptimized for modern computing architectures and uses Message Passing\nInterface (MPI) calls for multi-node application as well as data\nparallelism using threads. VPIC employs a variety of short-vector,\nsingle-instruction-multiple-data (SIMD) intrinsics for high performance\nand has been designed so that the data structures align with cache\nboundaries. The current feature set for VPIC includes a flexible input\ndeck format capable of treating a wide variety of problems. These\ninclude: the ability to treat electromagnetic materials (scalar and\ntensor dielectric, conductivity, and diamagnetic material properties);\nmultiple emission models, including user-configurable models; arbitrary,\nuser-configurable boundary conditions for particles and fields; user-\ndefinable simulation units; a suite of \"standard\" diagnostics, as well\nas user-configurable diagnostics; a Monte-Carlo treatment of collisional\nprocesses capable of treating binary and unary collisions and secondary\nparticle generation; and, flexible checkpoint-restart semantics enabling\nVPIC checkpoint files to be read as input for subsequent simulations.\nVPIC has a native I/O format that interfaces with the high-performance\nvisualization software Ensight and Paraview. While the common use cases\nfor VPIC employ low-order particles on rectilinear meshes, a framework\nexists to treat higher-order particles and curvilinear meshes, as well\nas more advanced field solvers.\n\n# Attribution\n\nResearchers who use the VPIC code for scientific research are asked to cite\nthe papers by Kevin Bowers listed below.\n\n1. Bowers, K. J., B. J. Albright, B. Bergen, L. Yin, K. J. Barker and\nD. J. Kerbyson, \"0.374 Pflop/s Trillion-Particle Kinetic Modeling of\nLaser Plasma Interaction on Road-runner,\" Proc. 2008 ACM/IEEE Conf.\nSupercomputing (Gordon Bell Prize Finalist Paper).\nhttp://dl.acm.org/citation.cfm?id=1413435\n\n2. K.J. Bowers, B.J. Albright, B. Bergen and T.J.T. Kwan, Ultrahigh\nperformance three-dimensional electromagnetic relativistic kinetic\nplasma simulation, Phys. Plasmas 15, 055703 (2008);\nhttp://dx.doi.org/10.1063/1.2840133\n\n3. K.J. Bowers, B.J. Albright, L. Yin, W. Daughton, V. Roytershteyn,\nB. Bergen and T.J.T Kwan, Advances in petascale kinetic simulations\nwith VPIC and Roadrunner, Journal of Physics: Conference Series 180,\n012055, 2009\n\n# Getting the Code\n\nTo checkout the VPIC source, do the following:\n\n```bash\n    git clone https://github.com/lanl/vpic.git\n```\n\n## Branches\n\nThe stable release of vpic exists on `master`, the default branch.\n\nFor more cutting edge features, consider using the `devel` branch.\n\nUser contributions should target the `devel` branch.\n\n# Requirements\n\nThe primary requirement to build VPIC is a C++11 capable compiler and\nan up-to-date version of MPI.\n\n# Build Instructions\n\n```bash\n    cd vpic \n```\n\nVPIC uses the CMake build system. To configure a build, do the following from\nthe top-level source directory:\n  \n```bash\n    mkdir build\n    cd build\n```\n\nThe `./arch` directory also contains various cmake scripts (including specific build options) which can help with building, but the user is left to select which compiler they wish to use.  The scripts are largely organized into folders by compiler, with specific flags and options set to match the target compiler.\n\nAny of the arch scripts can be invoked specifying the file name from inside a build directory:\n\n```bash\n    ../arch/reference-Debug\n```\n\nAfter configuration, simply type: \n\n```bash\n    make\n```\n\nThree scripts in the `./arch` directory are of particular note: lanl-ats1-hsw, lanl-ats1-knl and lanl-cts1. These scripts\nprovide a default way to build VPIC on LANL ATS-1 clusters such as Trinity and Trinitite and LANL CTS-1 clusters. The LANL\nATS-1 clusters are the first generation of DOE Advanced Technology Systems and consist of a partition of dual socket Intel\nHaswell nodes and a partition of single socket Intel Knights Landing nodes. The LANL CTS-1 clusters are the first generation\nof DOE Commodity Technology Systems and consist of dual socket Intel Broadwell nodes running the TOSS 3.3 operating system.\nThe lanl-ats1-hsw, lanl-ats1-knl and lanl-cts1 scripts are heavily documented and can be configured to provide a large\nvariety of custom builds for their respective platform types. These scripts could also serve as a good starting point for\ndevelopment of a build script for other platform types. Because these scripts also configure the users build environment\nvia the use of module commands, the scripts run both the cmake and make commands.\n\nFrom the user created build directory, these scripts can be invoked as follows:\n\n```bash\n    ../arch/lanl-ats1-hsw\n```\n\nor\n\n```bash\n    ../arch/lanl-ats1-knl\n```\n\nor\n\n```bash\n    ../arch/lanl-cts1\n```\n\nAdvanced users may choose to instead invoke `cmake` directly and hand select options. Documentation on valid ways\nto select these options may be found in the lanl-ats1 and lanl-cts1 build scripts mentioned above.\n\nGCC users should ensure the `-fno-strict-aliasing` compiler flag is set (as shown in `./arch/generic-gcc-sse`).\n\n\n# Building an example input deck\n\nAfter you have successfully built VPIC, you should have an executable in\nthe `bin` directory called `vpic` (`./bin/vpic`).  To build an executable from one of\nthe sample input decks (found in `./sample`), simply run:\n\n```bash\n    ./bin/vpic input_deck\n```\n\nwhere *input_deck* is the name of your sample deck.  For example, to build\nthe *harris* input deck in the *sample* subdirectory\n*(assuming that your build directory is located in the top-level\nsource directory)*:\n\n```bash\n    ./bin/vpic ../sample/harris\n```\n\nBeginners are advised to read the harris deck thoroughly, as it provides many examples of common uses cases.\n\n# Command Line Arguments\n\nNote: Historic VPIC users should note that the format of command line arguments was changed in the first open source release. The equals symbol is no longer accepted, and two dashes are mandatory. \n\nIn general, command line arguments take the form `--command value`, in which two dashes are followed by a keyword, with a space delimiting the command and the value.\n\nThe following specific syntax is available to the users:\n\n## Threading\n\nThreading (per MPI rank) can be enabled using the following syntax: \n\n```bash\n    ./binary.Linux --tpp n\n```\n\nWhere n specifies the number of threads\n\n### Example:\n\n```bash\n    mpirun -n 2 ./binary.Linux --tpp 2\n```\n\n\nTo run with VPIC with two threads per MPI rank.\n\n## Checkpoint Restart\n\nVPIC can restart from a checkpoint dump file, using the following syntax:\n\n```bash\n    ./binary.Linux --restore \u003cpath to file\u003e\n```\n\n### Example:\n\n```bash\n    ./binary.Linux --restore ./restart/restart0 \n```\n\nTo restart VPIC using the restart file `./restart/restart0`\n\n# Compile Time Arguments\n\nCurrently, the following options are exposed at compile time for the users consideration:\n\n## Particle Array Resizing\n\n- `DISABLE_DYNAMIC_RESIZING` (default `OFF`): Enable to disable the use of dynamic particle resizing\n- `SET_MIN_NUM_PARTICLES` (default 128 [4kb]): Set the minimum number of particles allowable when dynamically resizing\n\n## Threading Model\n\n - `USE_PTHREADS`: Use Pthreads for threading model, (default `ON`)\n - `USE_OPENMP`:   Use OpenMP for threading model\n\n## Vectorization\n\nThe following CMake variables are used to control the vector implementation that\nVPIC uses for each SIMD width.  Currently, there is support for 128 bit, 256 bit\nand 512 bit SIMD widths.  The default is for each of these CMake variables to be\ndisabled which means that an unvectorized reference implementation of functions\nwill be used.\n\n - `USE_V4_SSE`:       Enable 4 wide (128-bit) SSE\n - `USE_V4_AVX`:       Enable 4 wide (128-bit) AVX\n - `USE_V4_AVX2`:      Enable 4 wide (128-bit) AVX2\n - `USE_V4_ALTIVEC`:   Enable 4 wide (128-bit) Altivec\n - `USE_V4_PORTABLE`:  Enable 4 wide (128-bit) portable implementation\n\n - `USE_V8_AVX`:       Enable 8 wide (256-bit) AVX\n - `USE_V8_AVX2`:      Enable 8 wide (256-bit) AVX2\n - `USE_V8_PORTABLE`:  Enable 8 wide (256-bit) portable implementation\n\n - `USE_V16_AVX512`:   Enable 16 wide (512-bit) AVX512\n - `USE_V16_PORTABLE`: Enable 16 wide (512-bit) portable implementation\n\nSeveral functions in VPIC have vector implementations for each of the three SIMD\nwidths.  Some only have a single implementation.  An example of the latter is\nmove_p which only has a reference implementation and a V4 implementation.\n\nIt is possible to have a single CMake vector variable configured as ON for each\nof the three supported SIMD vector widths.  It is recommended to always have a\nCMake variable configured as ON for the 128 bit SIMD vector width so that move_p\nwill be vectorized.  In addition, it is recommended to configure as ON the CMake\nvariable that is associated with the native SIMD vector width of the processor\nthat VPIC is targeting.  If a CMake variable is configured as ON for each of the\nthree available SIMD vector widths, then for a given function in VPIC, the\nimplementation which supports the largest SIMD vector length will be chosen.  If\na V16 implementation exists, it will be chosen.  If a V16 implementation does not\nexist but V8 and V4 implementations exist, the V8 implementation will be chosen.\nIf V16 and V8 implementations do not exist but a V4 implementation does, it will\nbe chosen.  If no SIMD vector implementation exists, the unvectorized reference\nimplementation will be chosen.\n\nIn summary, when using vector versions on a machine with 256 bit SIMD, the\nV4 and V8 implementations should be configured as ON. When using a machine\nwith 512 bit SIMD, V4 and V16 implementations should be configured as ON.\nWhen choosing a vector implementation for a given SIMD vector length, the\nimplementation that is closest to the SIMD instruction set for the targeted\nprocessor should be chosen.  The portable versions are most commonly used for\ndebugging the implementation of new intrinsics versions.  However, the portable\nversions are generally more performant than the unvectorized reference\nimplemenation.  So, one might consider using the V4_PORTABLE version on ARM\nprocessors until a V4_NEON implementation becomes available.\n\n## Output \n\n - `VPIC_PRINT_MORE_DIGITS`: Enable more digits in timing output of status reports\n\n## Particle sorting implementation\n\nThe CMake variable below allows building VPIC to use the legacy, thread serial\nimplementation of the particle sort algorithm.\n\n - `USE_LEGACY_SORT`: Use legacy thread serial particle sort, (default `OFF`)\n\nThe legacy particle sort implementation is the thread serial particle sort\nimplementation from the legacy v407 version of VPIC. This implementation\nsupports both in-place and out-of-place sorting of the particles. It is very\ncompetitive with the thread parallel sort implementation for a small number\nof threads per MPI rank, i.e. 4 or less, especially on KNL because sorting\nthe particles in-place allows the fraction of particles stored in High\nBandwidth Memory (HBM) to remain stored in HBM. Also, the memory footprint\nof VPIC is reduced by the memory of a particle array which can be significant\nfor particle dominated problems.\n\nThe default particle sort implementation is a thread parallel implementation.\nCurrently, it can only perform out-of-place sorting of the particles. It will\nbe more performant than the legacy implementation when using many threads per\nMPI rank but uses more memory because of the out-of-place sort.\n\n# Workflow\n\nContributors are asked to be aware of the following workflow:\n\n1) Pull requests are accepted into `devel` upon tests passing\n2) `master` should reflect the *stable* state of the code\n3) Periodic releases will be made from `devel` into `master`\n\n# Feedback\n\nFeedback, comments, or issues can be raised through [GitHub issues](https://github.com/lanl/vpic/issues).\n\nA mailing list for open collaboration can also be found [here](https://groups.google.com/forum/#!forum/vpic-users)\n\n# Versioning\n\nVersion release summary: \n\n## V1.2 (October 2020)\n\n- Improved Neon intrinsics support\n- Added Takizuka-Abe collision operator\n- Threaded hydro_p pipelines\n- Added unit documentation\n\n## V1.1 (March 2019)\n\n- Added V8 and V16 functionality\n- Improved documentation and build processes\n- Significantly improved testing and correctness capabilities\n\n## V1.0\n\nInitial release\n\n# Release\n\nThis software has been approved for open source release and has been assigned **LA-CC-15-109**.\n\n# Copyright\n\n© (or copyright) 2020. Triad National Security, LLC. All rights reserved.  This\nprogram was produced under U.S. Government contract 89233218CNA000001 for Los\nAlamos National Laboratory (LANL), which is operated by Triad National\nSecurity, LLC for the U.S. Department of Energy/National Nuclear Security\nAdministration. All rights in the program are reserved by Triad National\nSecurity, LLC, and the U.S. Department of Energy/National Nuclear Security\nAdministration. The Government is granted for itself and others acting on its\nbehalf a nonexclusive, paid-up, irrevocable worldwide license in this material\nto reproduce, prepare derivative works, distribute copies to the public,\nperform publicly and display publicly, and to permit others to do so.\n\n# License\n\nVPIC is distributed under a [BSD license](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fvpic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fvpic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fvpic/lists"}