MAESTROeX

MAESTROeX: A Massively Parallel Low Mach Number Astrophysical Solver - Published in JOSS (2019)

https://github.com/amrex-astro/maestroex

Science Score: 100.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 4 DOI reference(s) in README and JOSS metadata
✓
Academic publication links
Links to: joss.theoj.org, zenodo.org
✓
Committers with academic emails
8 of 28 committers (28.6%) from academic institutions
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

amrex astrophysical-simulation

Keywords from Contributors

amr adaptive-mesh-refinement pde hydrodynamics finite-volume hpsf astrophysics gravity cfd radiation

Last synced: 6 months ago · JSON representation ·

Repository

A C++ low Mach number stellar hydrodynamics code

Basic Info

Host: GitHub
Owner: AMReX-Astro
License: bsd-3-clause
Language: C++
Default Branch: main
Homepage: https://amrex-astro.github.io/MAESTROeX/
Size: 80.6 MB

Statistics

Stars: 44
Watchers: 6
Forks: 22
Open Issues: 29
Releases: 35

Topics

amrex astrophysical-simulation

Created over 8 years ago · Last pushed 6 months ago

Metadata Files

Readme Changelog License Code of conduct Citation Zenodo

README.md

a C++ low Mach number stellar hydrodynamics code

MAESTROeX solves the equations of low Mach number hydrodynamics for stratified atmospheres/full spherical stars with a general equation of state, and nuclear reaction networks in an adaptive-grid finite-volume framework. It includes reactions and thermal diffusion and can be used on anything from a single core to 100,000s of processor cores with MPI + OpenMP or 1,000s of GPUs.

A description of the algorithm and links to the algorithm papers can be found here:

http://amrex-astro.github.io/MAESTROeX/

Getting started

MAESTROeX requires a C++ compiler that supports the C++17 standard and a C compiler that supports the C99 standard. Several compiler suites are supported, including GNU, Intel, LLVM, and Cray. GNU Make (>= 3.82) is also required, as is Python (>= 3.9) and standard tools available in any Unix-like environments (e.g., Perl and sed).

For GPU computing, CUDA 10 or later is required.

To stay up-to-date with MAESTROeX, you will want to periodically pull changes from the repository by typing git pull.
To get things running, you will need to get a copy of Microphysics and AMReX. Both are available on github separately or as submodules.

To clone MAESTROeX with the submodules, do:

git clone --recursive https://github.com/AMReX-Astro/MAESTROeX.git

To add the submodules to an existing clone, from the top-level MAESTROeX directory, do:

git submodule update --init --recursive

If you want to get the AMReX and Microphysics separately, they can be directly cloned as:

git clone https://github.com/AMReX-Astro/Microphysics.git git clone https://github.com/AMReX-Codes/amrex.git

You will then need to setup your shell environment to tell MAESTROeX where to find AMReX and Microphysics. Define the AMREX_HOME environment variable to point to the amrex/ directory, and MICROPHYSICS_HOME environment variable to point to the Microphysics/ directory. For example, if your shell is Bash:

export AMREX_HOME="/path/to/amrex/" export MICROPHYSICS_HOME='/path/to/Microphysics"

Note: you must specify the full path to the directories. Do not use ∼ to refer to your home directory; the scripts used by the build system will not be able to process this.

Change directory to correspond to the problem that you want to run. Each problem lives under one of three sub-directories of MAESTROeX/Exec/: SCIENCE/, TEST_PROBLEMS/, or UNIT_TESTS/. Then build the executable and run it by specifying an input file.
- For example, to run the standard reacting_bubble problem in 2-D:
cd MAESTROeX/Exec/TEST_PROBLEMS/reacting_bubble/ make DIM=2 ./Maestro2d.gnu.ex inputs_2d_C
The plotfiles (named pltXXXXXXX) are in BoxLib/AMReX format and can be visualized using yt, Amrvis, and VisIt.

For more detailed instructions on how to run the code and available test problems, refer to MAESTROeX User's Guide:

https://amrex-astro.github.io/MAESTROeX/docs/getting_started.html

Regression and unit testing

MAESTROeX needs to be tested in tandem with the AMReX and Microphysics repo updates. We use github CI as well as testing on local machines using the AMReX regression test framework (https://github.com/AMReX-Codes/regression_testing). Tests are run nightly and reported here:

https://ccse.lbl.gov/pub/RegressionTesting/MAESTROeX/ http://groot.astro.sunysb.edu/MAESTROeX/test-suite/gfortran/

A number of small unit tests exist in Exec/UNIT_TESTS for testing physics solvers independently.

Development Model:

Development generally follows the following ideas:

New features are committed to the development branch.

Nightly regression testing is used to ensure that no answers change (or if they do, that the changes were expected).

If a change is critical, we can cherry-pick the commit from development to main.
Contributions are welcomed from anyone. Any contributions that have the potential to change answers should be done via pull requests. A pull request should be generated from your fork of MAESTROeX and target the development branch. (If you mistakenly target main, we can change it for you.)

If there are a number of small commits making up the PR, we may wish to squash commits upon merge to have a clean history. Please ensure that your PR title and first post are descriptive, since these will be used for a squashed commit message.
On the first workday of each month, we perform a merge of development into main, in coordination with AMReX, MAESTROeX, and Microphysics. For this merge to take place, we need to be passing the regression tests.

To accommodate this need, we close the merge window into development a few days before the merge day. While the merge window is closed, only bug fixes should be pushed into development. Once the merge from development -> main is done, the merge window reopens.

Core Developers

People who make a number of substantive contributions will be named "core developers" of MAESTROeX. The criteria for becoming a core developer are flexible, but generally involve one of the following:

10 non-merge commits to MAESTROeX/Source/ or MAESTROeX/sphinx_docs/ or one of the problems that is not your own science problem or
addition of a new algorithm / module or
substantial input into the code design process or testing

Core developers will be recognized in the following ways:

invited to the group's slack team
listed in the User's Guide and website as a core developer
listed in the author list on the Zenodo DOI for the project (as given in the .zenodo.json file)
invited to co-author general code papers / proceedings describing MAESTROeX, its performance, etc. (Note: science papers will always be left to the science leads to determine authorship).

If a core developer is inactive for 3 years, we may reassess their status as a core developer.

Getting help

For answers to frequently asked questions and solutions to common problems, consult the FAQ section of the User's Guide.

If you discover any bugs in the code or would like to request further help, then please submit a issue to the MAESTROeX Github repository describing your problem.

For general questions, post to the discussion forum: https://github.com/AMReX-Astro/MAESTROeX/discussions

and for problems, raise an issue: https://github.com/AMReX-Astro/MAESTROeX/issues

Owner

Name: AMReX-Astro
Login: AMReX-Astro
Kind: organization

Repositories: 16
Profile: https://github.com/AMReX-Astro

The AMReX Astrophysics Suite: adaptive mesh refinement hydrodynamics codes for astrophysical flows.

JOSS Publication

MAESTROeX: A Massively Parallel Low Mach Number Astrophysical Solver

Published

December 19, 2019

DOI

10.21105/joss.01757

Volume 4, Issue 43, Page 1757

Authors

Duoming Fan

Center for Computational Sciences and Engineering, Lawrence Berkeley National Laboratory

Andrew Nonaka

Center for Computational Sciences and Engineering, Lawrence Berkeley National Laboratory

Ann Almgren

Center for Computational Sciences and Engineering, Lawrence Berkeley National Laboratory

Donald Willcox

Center for Computational Sciences and Engineering, Lawrence Berkeley National Laboratory

Alice Harpole

Department of Physics and Astronomy, Stony Brook University

Michael Zingale

Department of Physics and Astronomy, Stony Brook University

Editor

Arfon Smith

Citation (CITATION)

MAESTROeX derives from MAESTRO.  When citing the code, please cite the
two primary algorithm papers below as well as any of the MAESTRO
papers appropriate to the discussion.

   @ARTICLE{2019ApJ...887..212F,
          author = {{Fan}, Duoming and {Nonaka}, Andrew and {Almgren}, Ann S. and
            {Harpole}, Alice and {Zingale}, Michael},
           title = "{MAESTROeX: A Massively Parallel Low Mach Number Astrophysical Solver}",
         journal = {\apj},
        keywords = {Stellar convective zones, Hydrodynamics, Computational methods, Nuclear astrophysics, Nucleosynthesis, Nuclear abundances, Physics - Computational Physics, Astrophysics - Solar and Stellar Astrophysics},
            year = "2019",
           month = "Dec",
          volume = {887},
          number = {2},
             eid = {212},
           pages = {212},
             doi = {10.3847/1538-4357/ab4f75},
   archivePrefix = {arXiv},
          eprint = {1908.03634},
    primaryClass = {physics.comp-ph},
          adsurl = {https://ui.adsabs.harvard.edu/abs/2019ApJ...887..212F},
         adsnote = {Provided by the SAO/NASA Astrophysics Data System}
   }


    @ARTICLE{2010ApJS..188..358N,
       author = {{Nonaka}, A. and {Almgren}, A.~S. and {Bell},
                  J.~B. and {Lijewski}, M.~J. and {Malone}, C.~M. and
                  {Zingale}, M.},
	title = "{MAESTRO: An Adaptive Low Mach Number Hydrodynamics
                  Algorithm for Stellar Flows}",
      journal = {\apjs},
    archivePrefix = "arXiv",
       eprint = {1005.0112},
     primaryClass = "astro-ph.IM",
     keywords = {convection, hydrodynamics, methods: numerical,
                  nuclear reactions, nucleosynthesis, abundances,
                  supernovae: general, white dwarfs},
	 year = 2010,
	month = jun,
       volume = 188,
	pages = {358-383},
	  doi = {10.1088/0067-0049/188/2/358},
       adsurl = {http://adsabs.harvard.edu/abs/2010ApJS..188..358N},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }


For the software itself, please cite the JOSS paper:

    @ARTICLE{2019JOSS....4.1757F,
           author = {{Fan}, Duoming and {Nonaka}, Andrew and {Almgren}, Ann and
             {Willcox}, Donald and {Harpole}, Alice and {Zingale}, Michael},
            title = "{MAESTROeX: A Massively Parallel Low Mach Number Astrophysical Solver}",
          journal = {The Journal of Open Source Software},
         keywords = {abundances, supernovae, Fortran, Fortran90, nucleosynthesis, C++, Python, Jupyter Notebook, nuclear reactions, hydrodynamics, convection},
             year = "2019",
            month = "Nov",
           volume = {4},
           number = {43},
              eid = {1757},
            pages = {1757},
              doi = {10.21105/joss.01757},
           adsurl = {https://ui.adsabs.harvard.edu/abs/2019JOSS....4.1757F},
          adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }



There are several other papers that may be appropriate to cite,
depending on which capabilities you are using.  These are discussed
below.

The development of the low Mach number formulation is described in the
following papers -- we ask that they be cited if you are discussing
the low Mach asymptotics or expansion of the background state (paper
II in particular):

    @ARTICLE{2006ApJ...637..922A,
       author = {{Almgren}, A.~S. and {Bell}, J.~B. and {Rendleman},
                  C.~A. and {Zingale}, M.},
	title = "{Low Mach Number Modeling of Type Ia
                  Supernovae. I. Hydrodynamics}",
      journal = {\apj},
       eprint = {astro-ph/0509892},
     keywords = {Convection, Hydrodynamics, Methods: Numerical,
                  Nuclear Reactions, Nucleosynthesis, Abundances,
                  Stars: Supernovae: General, Stars: White Dwarfs},
	 year = 2006,
	month = feb,
       volume = 637,
	pages = {922-936},
	  doi = {10.1086/498426},
       adsurl = {http://adsabs.harvard.edu/abs/2006ApJ...637..922A},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }

    @ARTICLE{2006ApJ...649..927A,
       author = {{Almgren}, A.~S. and {Bell}, J.~B. and {Rendleman},
		      C.~A. and {Zingale}, M.},
	title = "{Low Mach Number Modeling of Type Ia
		      Supernovae. II. Energy Evolution}",
      journal = {\apj},
       eprint = {astro-ph/0606496},
     keywords = {Convection, Hydrodynamics, Methods: Numerical, Nuclear
		      Reactions, Nucleosynthesis, Abundances, Stars:
		      Supernovae: General, Stars: White Dwarfs},
	 year = 2006,
	month = oct,
       volume = 649,
	pages = {927-938},
	  doi = {10.1086/507089},
       adsurl = {http://adsabs.harvard.edu/abs/2006ApJ...649..927A},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }

    @ARTICLE{2008ApJ...684..449A,
       author = {{Almgren}, A.~S. and {Bell}, J.~B. and {Nonaka},
                  A. and {Zingale}, M.  },
	title = "{Low Mach Number Modeling of Type Ia
                  Supernovae. III. Reactions}",
      journal = {\apj},
     keywords = {convection, hydrodynamics, methods: numerical,
                  nuclear reactions, nucleosynthesis, abundances,
                  supernovae: general, white dwarfs },
	 year = 2008,
	month = sep,
       volume = 684,
	  eid = {449-470},
	pages = {449-470},
	  doi = {10.1086/590321},
       adsurl = {http://adsabs.harvard.edu/abs/2008ApJ...684..449A},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }


If you use diffusion, we appreciate citing the following paper which
introduced the diffusion algorithm:

    @ARTICLE{2011ApJ...728..118M,
       author = {{Malone}, C.~M. and {Nonaka}, A. and {Almgren},
                  A.~S. and {Bell}, J.~B. and {Zingale}, M.},
	title = "{Multidimensional Modeling of Type I X-ray
                  Bursts. I. Two-dimensional Convection Prior to the
                  Outburst of a Pure $^{4}$He Accretor}",
      journal = {\apj},
    archivePrefix = "arXiv",
       eprint = {1012.0609},
     primaryClass = "astro-ph.HE",
     keywords = {convection, hydrodynamics, methods: numerical, stars:
                  neutron, X-rays: bursts},
	 year = 2011,
	month = feb,
       volume = 728,
	  eid = {118},
	pages = {118},
	  doi = {10.1088/0004-637X/728/2/118},
       adsurl = {http://adsabs.harvard.edu/abs/2011ApJ...728..118M},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }


If you are dealing with a spherical geometry, we appreciate citing
this paper, which describes the spherical geometry:

    @ARTICLE{2009ApJ...704..196Z,
       author = {{Zingale}, M. and {Almgren}, A.~S. and {Bell},
                  J.~B. and {Nonaka}, A. and {Woosley}, S.~E.},
	title = "{Low Mach Number Modeling of Type IA
                  Supernovae. IV. White Dwarf Convection}",
      journal = {\apj},
    archivePrefix = "arXiv",
       eprint = {0908.2668},
     primaryClass = "astro-ph.HE",
     keywords = {convection, hydrodynamics, methods: numerical,
                  nuclear reactions, nucleosynthesis, abundances,
                  supernovae: general, white dwarfs},
	 year = 2009,
	month = oct,
       volume = 704,
	pages = {196-210},
	  doi = {10.1088/0004-637X/704/1/196},
       adsurl = {http://adsabs.harvard.edu/abs/2009ApJ...704..196Z},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
    }

GitHub Events

Total

Create event: 1
Release event: 1
Issues event: 2
Watch event: 5
Delete event: 1
Issue comment event: 3
Push event: 6
Pull request event: 8

Last Year

Create event: 1
Release event: 1
Issues event: 2
Watch event: 5
Delete event: 1
Issue comment event: 3
Push event: 6
Pull request event: 8

Committers

Last synced: 7 months ago

All Time

Total Commits: 2,235
Total Committers: 28
Avg Commits per committer: 79.821
Development Distribution Score (DDS): 0.7

Past Year

Commits: 5
Committers: 1
Avg Commits per committer: 5.0
Development Distribution Score (DDS): 0.0

Top Committers

Name	Email	Commits
Alice Harpole	a**e@g**m	670
Andy Nonaka	A**a@l**v	610
Doreen Fan	d**n@l**v	472
Michael Zingale	m**e@s**u	296
Donald E. Willcox	e**x@g**m	68
Travis CI		21
Chris DeGrendele	c**e@g**m	17
Max Katz	m**z@g**m	13
Weiqun Zhang	w**g@l**v	11
GitHub Action	a**n@g**m	10
Brendan Boyd	4****d	7
Andrew Snodin	a**n@g**m	5
Simon Guichandut	4****t	5
Alice Harpole	a**4@s**k	5
Xinlong Li	4****U	4
dependabot[bot]	4****]	4
Arfon Smith	a****n	4
Regression Tester	c**l@g**m	2
Jonathan Thurgood	4****d	2
Xinlong Li	4****y	1
Justin Lague	j**e@h**m	1
Alice Harpole	a**e@g**u	1
Alice Harpole	h**a@c**v	1
Andrew Nonaka	a**a@l**v	1
Doreen Fan	d**n@c**v	1
Philipp Edelmann	e**n@f**e	1
Xinlong Li	x**g@e**v	1
Eric T. Johnson	y****3	1

Committer Domains (Top 20 + Academic)

lbl.gov: 3 edison04.nersc.gov: 1 fs.tum.de: 1 cori11.nersc.gov: 1 login3.summit.olcf.ornl.gov: 1 cori04.nersc.gov: 1 groot.astro.sunysb.edu: 1 soton.ac.uk: 1 github.com: 1 stonybrook.edu: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 15
Total pull requests: 84
Average time to close issues: 2 months
Average time to close pull requests: 10 days
Total issue authors: 4
Total pull request authors: 7
Average comments per issue: 3.07
Average comments per pull request: 0.48
Merged pull requests: 78
Bot issues: 0
Bot pull requests: 6

Past Year

Issues: 3
Pull requests: 9
Average time to close issues: N/A
Average time to close pull requests: 41 minutes
Issue authors: 3
Pull request authors: 3
Average comments per issue: 0.67
Average comments per pull request: 0.11
Merged pull requests: 5
Bot issues: 0
Bot pull requests: 1

View more stats

Top Authors

Issue Authors

zingale (14)
biboyd (3)
andrewsilver1997 (2)
dwillcox (1)
Seauagain (1)
harpolea (1)

Pull Request Authors

zingale (109)
dependabot[bot] (10)
simonguichandut (8)
biboyd (8)
ajnonaka (6)
maximumcats (1)
yut23 (1)

Top Labels

Issue Labels

documentation :book: (1)

Pull Request Labels

dependencies (10) test coversage (2) github_actions (1)

Dependencies

.github/workflows/c-linter.yml actions

AMReX-Astro/cpp-linter-action main composite
actions/checkout v3 composite
actions/upload-artifact v1 composite

.github/workflows/check-ifdefs.yml actions

actions/cache v3 composite
actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/codespell.yml actions

actions/cache v3 composite
actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/create_release.yml actions

actions/checkout v2 composite
actions/create-release v1 composite

.github/workflows/docs-test.yml actions

actions/cache v3 composite
actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/gh-pages.yml actions

actions/cache v1 composite
actions/checkout v2 composite
actions/setup-python v2 composite
peaceiris/actions-gh-pages v3 composite

.github/workflows/gpu_action.yml actions

actions/checkout v3 composite

.github/workflows/reacting_bubble-compare.yml actions

actions/checkout v3 composite

Exec/science/urca/analysis/setup.py pypi

matplotlib *
numpy *
yt *

requirements.txt pypi

IPython >=3
Sphinx *
breathe >=4.13
jupyter *
more_itertools *
nbconvert *
numpy *
numpydoc *
pandoc *
sphinx-copybutton *
sphinx-math-dollar *
sphinx-prompt *
sphinx_rtd_theme *
sphinxcontrib_bibtex *

MAESTROeX

Science Score: 100.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Getting started

Regression and unit testing

Development Model:

Core Developers

Getting help

Owner

JOSS Publication

MAESTROeX: A Massively Parallel Low Mach Number Astrophysical Solver

Authors

Editor

Tags

Citation (CITATION)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Dependencies