{"id":22668567,"url":"https://github.com/lanl/branson","last_synced_at":"2025-04-12T11:08:50.117Z","repository":{"id":25789254,"uuid":"87237242","full_name":"lanl/branson","owner":"lanl","description":"A Monte Carlo transport mini-app for studying new parallel algorithms","archived":false,"fork":false,"pushed_at":"2024-05-30T18:06:54.000Z","size":2119,"stargazers_count":17,"open_issues_count":3,"forks_count":22,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2024-06-27T00:19:22.988Z","etag":null,"topics":[],"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/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2017-04-04T21:34:42.000Z","updated_at":"2024-06-27T00:19:22.989Z","dependencies_parsed_at":"2023-12-24T21:34:38.869Z","dependency_job_id":"5bb2223b-449a-4cbd-b668-41c30b0dadf9","html_url":"https://github.com/lanl/branson","commit_stats":{"total_commits":215,"total_committers":11,"mean_commits":"19.545454545454547","dds":"0.38604651162790693","last_synced_commit":"fb506b7f483f80131fa831f699be79afa8ca27cc"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fbranson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fbranson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fbranson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fbranson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/branson/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228911888,"owners_count":17990774,"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":[],"created_at":"2024-12-09T15:15:46.588Z","updated_at":"2024-12-09T15:15:47.541Z","avatar_url":"https://github.com/lanl.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"Branson\n----------------\n\n[![Linux Build Status](https://travis-ci.org/lanl/branson.svg?branch=develop)](https://travis-ci.org/lanl/branson)\n[![Windows Build Status](https://ci.appveyor.com/api/projects/status/xxxx/branch/develop?svg=true)](https://ci.appveyor.com/project/lanl/branson)\n[![codecov.io](https://codecov.io/github/lanl/branson/coverage.svg?branch=develop)](https://codecov.io/github/lanl/branson/branch/develop)\n[![Latest Version](https://img.shields.io/github/release/lanl/branson.svg?style=flat-square)](https://github.com/lanl/branson/releases)\n[![PyPI](https://img.shields.io/pypi/l/Django.svg)](https://github.com/lanl/branson/blob/develop/LICENSE.md)\n\n## Introduction\n\nSo you've decided to use Branson...\n\nHere are some things to know:\n\n- Branson is not an acronym.\n- The point of Branson is to study different algorithms for parallel Monte Carlo\n  transport. Currently it contains a particle passing method for domain decomposition (two mesh\n  passing methods for domain decomposition are available in older versions)\n- Many of the parameters that impact parallel performance can be set in the input file.\n- Input files are in XML, which makes them easy to generate and change in python.\n- Input files are complicated when you want to have multiple spatial regions but\n  are pretty simple otherwise.\n\n## How to install\n\nAccessing the sources\n\n- Download a tarball from Github, or\n- Fork and clone the git repository.\n```\n# after forking the repository\ngit clone git@github.com:[github-username]/branson\ncd branson\ngit remote add upstream git@github.com:lanl/branson\ngit checkout -b develop upstream/develop\n```\n\nInstalling Branson:\n\n- Build requirements:\n  - C/C++ compiler(s) with support for C11 and C++14.\n  - [CMake 3.9+](https://cmake.org/download/)\n  - MPI 3.0+ ([OpenMPI 1.10+](https://www.open-mpi.org/software/ompi/),\n    [mpich](http://www.mpich.org), etc.)\n- Optional dependencies\n  - [OpenMP](https://openmp.org) Used for parallelism on an MPI rank, currently just for the\n    transport phase. Note that the number of OpenMP threads is taken from the input file and not\n    the user's environment\n  - [Metis](http://glaros.dtc.umn.edu/gkhome/metis/metis/overview) Used to decompose the mesh, if\n    Metis is not found, Branson uses a simple decomposition where cells are divided evenly between\n    ranks with x being the fastest index and z being the slowest index\n  - [HDF5](https://support.hdfgroup.org/HDF5/)\n  - [Silo](http://wci.llnl.gov/simulation/computer-codes/silo)\n  - If these tools aren't readily avilable on your target machine, consider\n    using a package manager like [spack](https://github.com/spack/spack) to help\n    you install these tools.\n- There are multiple CMake options:\n  - `CMAKE_BUILD_TYPE`, set on the command line with `-DCMAKE_BUILD_TYPE=\u003cDebug|Release\u003e` where the\n    default is `Release`.\n  - `USE_OPENMP`, set on the command line with `-DUSE_OPENMP=\u003cON|OFF\u003e`, if this variable is not set\n    it will default to `ON`\n  - `ENABLE_VERBOSE_GPU_TRANSPORT`, set on the command line with\n    `DENABLE_VERBOSE_GPU_TRANSPORT=\u003cON|OFF`, defaults to `OFF`, useful for GPU debugging\n- If CMake has trouble finding your installed TPLs, you can try\n  - appending their locations to `CMAKE_PREFIX_PATH`,\n  - Setting helper variables like `HDF5_ROOT` (refer to the\n    [cmake\n    documentation](https://cmake.org/cmake/help/latest/module/FindHDF5.html?highlight=findhdf5)\n    or the `FindXXX.cmake` scripts in Branson's `src/config` directory for a\n    list of variables), or\n  - try running `ccmake .` from the build directory and changing the values of\n    build system variables related to TPL locations.\n```\nEXPORT CXX=`which g++`\ncd $build_dir\ncmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=\u003cinstall-location\u003e ${branson_source_dir}/src\nmake -j\n```\n\nTesting the build:\n\n```\ncd $build_dir\nctest -j 32\n```\n\n## Parameters ##\n\n- In the `common` block of the XML input file you can set several parameters related to parallel\n performance:\n  - `batch_size`: how many particles are processed by an MPI rank before it stops to process\n    particle messages (small means more processing of MPI messages and possibly more interleaving\n    of off rank and on rank work)\n  - `particle_message_size`: the size of the communication buffer for particle data (small means\n     more message but possibly more interleaving of on rank and off rank work)\n  - `mesh_decomposition`: Can be `METIS` or `CUBE`, generally use Metis unless you're trying to run\n    a very large problem (Metis is serial and ParMetis can't be used due to licensing restrictions).\n    For a cube decomposition, the number of ranks must be perfect cubes (x^(1/3) is an interger)\n\n## Special builds\n\n### Fake Multigrop Branson:\n\n- The clean_mg branch has a new capability that mimics the data flow in real\n  multigroup transport.\n- This branch sets the number of groups at the configure step in CMake. I know\n  this is messy from a usability standpoint but it makes the data layout very\n  easy to control when the number of groups is known at compile time. Use the\n  `N_GROUPS` CMake variable to set the number of groups (e.g. `cmake\n  -DN_GROUPS=10 ../path/to/CMakeLists.txt`).\n- The code will still produce gray results! The physical value in each group is\n  the same and it's still set via the input deck.\n- This branch samples a group with a uniform PDF (it does not weight the opacity\n  with a Planckian spectrum).\n\n## Running Branson on performance problems\n\n- There are two performance problems of interest in the `inputs` folder, they are both simplified\n 3D hohlraums and should be run with a 30 group build of Branson (see Special builds section above).\n- The `3D_hohlaum_single_node.xml` problem is meant to be run on a full node. It is in replicated\n mode which means there is very little MPI communication (end of cycle reductions). It is run with:\n```\nmpirun -n \u003cprocs_on_node\u003e \u003cpath/to/branson\u003e 3D_hohlaum_single_node.xml\n```\n- The `3D_hohlaum_multi_node.xml` problem is meant to be run on many nodes. It is in domain\n  decomposed mode which means particles must be communicated between spatial domains. It is run\n  with:\n```\nmpirun -n \u003cn_ranks\u003e \u003cpath/to/branson\u003e 3D_hohlaum_multi_node.xml\n```\n Note that Branson does not currently have any threading capability so `n_ranks` should usually be\n `n_nodes*n_ranks_per_node`. This problem is meant to consume about 30\\% of a 128 GB node.\n\n## Authors\n\n- Branson was written by Alex R. Long\n- [Random123](http://www.deshawresearch.com/resources_random123.html)\n  is by D. E. Shaw Research, Copyright 2010-2011\n- [PugiXML](https://github.com/zeux/pugixml)\n  is by zeux (Arseny Kapoulkine), [MIT License](https://github.com/zeux/pugixml/blob/master/LICENSE.md)\n- RNG.h uses code from [Draco](https://github.com/lanl/Draco), [BSD-3 Clause License](https://github.com/lanl/Draco/blob/develop/LICENSE.md)\n\n## Release\n\n- Branson is released under the BSD 3-Clause License. For more details see the\n[LICENSE.md file](https://github.com/lanl/branson/blob/develop/LICENSE.md).\n\n- Branson development follows the development model outlined in the CS-memo-2020-11-18.pdf file,\n  available in the top-level of this repo\n\n- LANL code designation: `C17048\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fbranson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fbranson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fbranson/lists"}