Merge branch 'development' into tune_PermutationForDeposition_for_MI250X

.github/workflows/dependencies/dependencies_hip.sh

@@ -17,10 +17,23 @@ set -eu -o pipefail
 #   failed files the given number of times.
 echo 'Acquire::Retries "3";' | sudo tee /etc/apt/apt.conf.d/80-retries
 
-# Ref.: https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html#ubuntu
+# Ref.: https://rocm.docs.amd.com/projects/install-on-linux/en/latest/how-to/native-install/ubuntu.html
+
+# Make the directory if it doesn't exist yet.
+# This location is recommended by the distribution maintainers.
+sudo mkdir --parents --mode=0755 /etc/apt/keyrings
+
+# Download the key, convert the signing-key to a full
+# keyring required by apt and store in the keyring directory
+wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \
+    gpg --dearmor | sudo tee /etc/apt/keyrings/rocm.gpg > /dev/null
+
 curl -O https://repo.radeon.com/rocm/rocm.gpg.key
 sudo apt-key add rocm.gpg.key
-echo "deb [arch=amd64] https://repo.radeon.com/rocm/apt/${1-debian}/ ubuntu main" \
+
+source /etc/os-release # set UBUNTU_CODENAME: focal or jammy or ...
+
+echo "deb [arch=amd64] https://repo.radeon.com/rocm/apt/${1-latest} ${UBUNTU_CODENAME} main" \
   | sudo tee /etc/apt/sources.list.d/rocm.list
 echo 'export PATH=/opt/rocm/llvm/bin:/opt/rocm/bin:/opt/rocm/profiler/bin:/opt/rocm/opencl/bin:$PATH' \
   | sudo tee -a /etc/profile.d/rocm.sh

CMakeLists.txt

@@ -1,5 +1,13 @@
 cmake_minimum_required(VERSION 3.18)
 
+#
+# Setting a cmake_policy to OLD is deprecated by definition and will raise a
+# verbose warning
+#
+if(CMAKE_SOURCE_DIR STREQUAL PROJECT_SOURCE_DIR)
+    set(CMAKE_WARN_DEPRECATED OFF CACHE BOOL "" FORCE)
+endif()
+
 #
 # Allow for MSVC Runtime library controls
 #

CONTRIBUTING.md

@@ -271,41 +271,3 @@ to be documented where appropriate. For example:
 ```
 Additional information regarding Doxygen comment formatting can be found
 in the [Doxygen Manual](https://www.doxygen.nl/manual/).
-
-
-
-
-## Core Developers
-
-People who make a number of substantive contributions will be named
-"core developers" of AMReX.  The criteria for becoming a core
-developer are flexible, but generally involve one of the following:
-
-  * 100 non-trivial commits to `amrex/Src/`  *and/or*
-
-  * addition of a new algorithm / module  *and/or*
-
-  * substantial input into the code design process or testing
-
-If a core developer is inactive for multiple years, we may reassess their
-status as a core developer.
-
-The current list of core developers is:
-Ann Almgren (LBNL),
-Vince Beckner,
-John Bell (LBNL),
-Johannes Blaschke (LBNL),
-Cy Chan (LBNL),
-Marcus Day (LBNL),
-Brian Friesen (NERSC),
-Kevin Gott (NERSC),
-Daniel Graves (LBNL),
-Axel Huebl (LBNL),
-Max Katz (NVIDIA),
-Andrew Myers (LBNL),
-Tan Nguyen (LBNL),
-Andrew Nonaka (LBNL),
-Michele Rosso (LBNL),
-Sam Williams (LBNL),
-Weiqun Zhang (LBNL),
-Michael Zingale (Stony Brook University).

Docs/Doxygen/main.dox

@@ -19,8 +19,7 @@
   applications. AMReX is freely available on Github at 
   <a href="https://github.com/AMReX-Codes/amrex">AMReX-Codes/amrex</a>.
 
-  AMReX is developed at LBNL, NREL, and ANL as part of the 
-  Block-Structured AMR Co-Design Center in DOE’s Exascale Computing Project.
+  AMReX is developed at LBNL.
 
 
   \subsection development Development

Docs/sphinx_documentation/source/Governance.rst

@@ -0,0 +1 @@
+.. include:: ../../../GOVERNANCE.rst

Docs/sphinx_documentation/source/Introduction.rst

@@ -20,5 +20,4 @@ Key features of AMReX include:
    - Parallel I/O
    - Plotfile format supported by AmrVis, VisIt, ParaView, and yt.
 
-AMReX is developed at LBNL, NREL, and ANL as part of the Block-Structured AMR
-Co-Design Center in DOE's Exascale Computing Project.
+AMReX is developed at LBNL.

Docs/sphinx_documentation/source/Visualization.rst

@@ -331,6 +331,52 @@ To open a plotfile (for example, you could run the
 
    \end{center}
 
+Another useful feature in ParaView to load and re-load a group of plotfiles is using a ``.series`` file
+(similar to the ``.visit`` file in VisIt). It is a text file (say ``plot_files.series``) which lists
+the plotfiles in a JSON format as below.
+
+.. highlight:: console
+
+::
+
+{ "file-series-version": "1.0", "files": [
+{ "name": "plt00000", "time": 0},
+{ "name": "plt00100", "time": 1},
+{ "name": "plt00200", "time": 2},
+{ "name": "plt00300", "time": 3},
+{ "name": "plt00400", "time": 4},
+{ "name": "plt00500", "time": 5},
+{ "name": "plt00600", "time": 6},
+{ "name": "plt00700", "time": 7},
+{ "name": "plt00800", "time": 8},
+{ "name": "plt00900", "time": 9},
+{ "name": "plt01000", "time": 10},] }
+
+:download:`write_series_file.sh </Visualization/write_series_file.sh>` is a bash script
+that can generate such a ``.series`` file. Navigate to the directory with the plotfiles and
+save this script. Then run the bash script by executing the following command in the terminal.
+
+.. highlight:: console
+
+::
+
+    bash write_series_file.sh
+
+This will generate a file ``plot_files.series``. Open ParaView, and then select
+"File" :math:`\rightarrow` "Open". In the "Files of Type" dropdown menu (see :numref:`fig:ParaView_filegroup`)
+choose the option ``All Files (*)``. Then choose ``plot_files.series`` and click "OK". Now the plotfiles have been
+loaded as a Group as in Step 2 of section :ref:`section-1`. Now, you can follow the steps 2 to 7 in the section
+:ref:`section-1` to plot. As new plotfiles are generated, just re-run the bash script to re-generate the
+``plot_files.series`` file, right-click on ``plot_files.series`` in the ParaView menu, and click on
+"Reload Files" (see :numref:`fig:ParaView_series_reload`).
+
+.. _fig:ParaView_series_reload:
+
+.. figure:: ./Visualization/ParaView_series_reload.png
+   :width: 3.0in
+
+   : File dialog in ParaView showing how to reload a series file
+
 Building an Iso-surface
 -----------------------
 

Docs/sphinx_documentation/source/Visualization/write_series_file.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+# Specify the root directory for traversal
+root_directory="./"
+
+# Create a temporary file to store the list of directories
+temp_file=$(mktemp)
+find "$root_directory" -type d -print0 > "$temp_file"
+
+# Initialize an empty string to store file information
+files_list=""
+
+# file counter to be used as time entry
+count=0
+
+ls -d */ | sort -z > temporary_file
+
+# Read from the temporary file
+for dir in */; do
+
+    dir_name=$(basename "$dir")
+
+    # Check if the folder starts with "plt" and contains a file named "Header"
+    if [[ "$dir_name" == plt* && -f "$dir/Header" ]]; then
+        # Extract version number from folder name
+        version="${dir_name#plt}"
+        echo $version
+
+        # Create file information
+        files_list+="$(printf "{ \"name\": \"plt$version\", \"time\": $count},")"
+        files_list+=$'\n'
+
+        ((count++))
+    fi
+done < "$temp_file"
+
+# Remove trailing comma from the last entry
+files_list="${files_list%,}"
+
+# Create the final JSON structure
+# Header line
+header_line="{ \"file-series-version\": \"1.0\", \"files\": ["
+# Write the files list
+all_files="$(printf '%s\n' "$files_list") ] }"
+
+file_series_data="$header_line"
+file_series_data+=$'\n'
+file_series_data+="$all_files"
+
+# Write the generated JSON structure to a file named plot_files.series
+echo "$file_series_data" > plot_files.series
+
+# Remove the temporary file
+rm "$temp_file"
+
+echo "JSON structure has been written to plot_files.series"

Docs/sphinx_documentation/source/conf.py

@@ -59,7 +59,7 @@ def get_amrex_version():
 
 # General information about the project.
 project = u'amrex'
-copyright = u'2017-2018, AMReX Team'
+copyright = u'2024, AMReX Team'
 author = u'AMReX Team'
 
 # The version info for the project you're documenting, acts as replacement for

Docs/sphinx_documentation/source/index.rst

@@ -8,8 +8,7 @@ massively parallel, block-structured adaptive mesh refinement (AMR)
 applications. AMReX is freely available `on Github
 <https://github.com/AMReX-Codes/amrex>`_.
 
-AMReX is developed at LBNL, NREL, and ANL as part of the Block-Structured AMR
-Co-Design Center in DOE's Exascale Computing Project.
+AMReX is developed at LBNL.
 
 All of AMReX's development is done in the GitHub repository under the
 development branch; anyone can see the latest updates. A monthly release is tagged at the beginning
@@ -64,6 +63,7 @@ Documentation on migration from BoxLib is available in the AMReX repository at D
    External_Frameworks_Chapter
    Regression_Testing_Chapter
    Faq
+   Governance
 
 .. toctree::
    :maxdepth: 1

GOVERNANCE.rst

@@ -0,0 +1,147 @@
+.. _governance:
+
+AMReX Governance
+================
+
+AMReX is led in an open governance model, described in this document.
+
+
+Steering Committee
+------------------
+
+Current Roster
+^^^^^^^^^^^^^^
+
+- Ann Almgren
+- John Bell (chair)
+- Andrew Myers
+- Weiqun Zhang
+
+See: `GitHub team <https://github.com/orgs/AMReX-Codes/teams/amrex-steering-committee>`__
+
+Role
+^^^^
+
+Members of the steering committee (SC) can change organizational settings, do administrative operations such as rename/move/archive repositories, change branch protection rules, etc.
+
+SC members can call votes for decisions (technical or governance).
+
+The SC can veto decisions of the technical committee (TC) by voting in the SC.
+The TC can override a veto with a 2/3rd majority vote in the TC.
+Decisions are documented in developer meeting notes and/or on the GitHub repository.
+
+The SC can change the governance structure, but only in a unanimous vote.
+
+Decision Process
+^^^^^^^^^^^^^^^^
+
+Decisions of the SC usually happen in the developer meetings, via e-mail or public chat.
+
+Decisions are made in a non-confidential manner, by the majority of votes cast by SC members.
+
+Votes can be cast asynchronously, e.g., over a time period of 1-2 weeks.
+In tie situations, the chair of the SC acts as the tie breaker.
+
+Appointment Process
+^^^^^^^^^^^^^^^^^^^
+
+New members of the SC can be appointed by unanimous vote of the current SC members.
+
+SC members are expected to attend and contribute to regular developer meetings.
+
+SC members can resign or be removed by majority vote, e.g., due to inactivity, inappropriate or otherwise negative behavior, or other reasons.
+
+
+Technical Committee
+-------------------
+
+Current Roster
+^^^^^^^^^^^^^^
+
+- Ann Almgren
+- Marc Day
+- Candace Gilet
+- Kevin Gott
+- Axel Huebl
+- Andrew Myers
+- Andy Nonaka
+- Jean Sexton
+- Weiqun Zhang
+- Michael Zingale
+
+See: `GitHub team <https://github.com/orgs/AMReX-Codes/teams/amrex-technical-committee>`__
+
+Role
+^^^^
+
+The technical committee (TC) is the core governance body, where, under normal operations, most ideas are discussed and decisions are made.
+Individual TC members can approve and merge code changes.
+TC members are expected to seek approval of another maintainer for their own changes, except under exigent circumstances.
+TC members lead and weigh in on technical discussions and, if needed, can call for a vote of the TC for a technical decision.
+TC members can merge/close PRs and issues, and moderate (including blocking or muting) bad actors.
+The TC can propose governance changes to the SC.
+
+
+Decision Process
+^^^^^^^^^^^^^^^^
+
+Discussion in the TC usually happens in the developer meetings. Developer meetings can be scheduled by any member of the SC or TC.
+
+If a member of the TC calls for a vote, the vote will be decided by the majority of the votes cast, provided that at least half of the TC members participate in the vote. If fewer than half of the TC members cast votes, the SC will make the decision according to the guidelines specified above.
+
+Votes are cast in a non-confidential manner.
+Decisions are documented in the developer meeting notes and/or in the GitHub repository.
+
+Individual TC members can suggest the addition of new contributors. The suggestion must be seconded by another TC member. Any TC member has the right to oppose the suggestion and call for a vote on the decision.
+
+Appointment Process
+^^^^^^^^^^^^^^^^^^^
+
+TC members are the maintainers of AMReX.
+TC members are expected to attend and contribute to regular developer meetings.
+
+New TC members can be suggested by either SC or TC members. Confirmation of a new TC member requires a majority of votes cast by either the SC or the TC. The SC can veto any new appointment.
+
+Steering committee members can also be TC members.
+
+TC members can resign or be removed by majority vote by either TC or SC due to inactivity, inappropriate or otherwise negative behavior, or other reasons.
+
+
+Contributors
+------------
+
+Current Roster
+^^^^^^^^^^^^^^
+
+See: `GitHub team <https://github.com/orgs/AMReX-Codes/teams/amrex-contributors>`__
+
+Role
+^^^^
+
+Contributors are valuable, vetted developers of AMReX.
+Contributions can be in many forms and not all need to be code contributions.
+Examples include code pull requests, support in issues & user discussions, writing and updating documentation, writing tutorials, visualizations, R&D on algorithms, testing and benchmarking, etc.
+Contributors can participate in developer meetings and weigh in on discussions.
+Contributors can "triage" (i.e., add and remove labels to) pull requests, issues, and GitHub discussion pages.
+Contributors can comment on and review PRs (but not merge).
+
+Decision Process
+^^^^^^^^^^^^^^^^
+
+Contributors can individually decide on classification (triage) of pull requests, issues, and GitHub discussion pages.
+
+Appointment Process
+^^^^^^^^^^^^^^^^^^^
+
+Appointed after contributing to AMReX (see above) through nomination by any member of the TC. Another member of the TC must second the nomination.
+
+The role can be lost by resigning or by majority vote of either the TC or the SC due to inactivity, inappropriate or otherwise negative behavior, or other reasons.
+
+
+Former Members
+--------------
+
+Former contributors do not play any role in the governance of AMReX.
+Instead, former (e.g., inactive) contributors are acknowledged separately in GitHub contributor tracking, the AMReX documentation, references, etc. as appropriate.
+
+Former members of SC, TC and Contributors are not kept on the roster, since committee role rosters should reflect currently active members and the responsible governance body. Former members of the SC or TC also do not play any role in the governance of AMReX.