Merge branch 'Relax-in-development' into development

Author: yzeng

CONTRIBUTING.md

@@ -0,0 +1,267 @@
+## Development Model
+
+Development generally follows the following ideas:
+
+  * New features are merged into to the `development` branch using
+    Pull Requests (PRs).
+
+  * Bug fixes, questions and contributions of new features are welcome!
+
+       * Bugs should be reported through GitHub Issues.
+       * We suggest asking questions through GitHub Discussions.
+       * All contributions should be done via pull requests.
+         A pull request should be generated from your fork of
+         IAMReX and target the `development` branch. See below for
+         details on how this process works.
+
+         In general we squash commits upon merge to have a clean history.
+         *Please ensure that your PR title and description are descriptive,
+         since these will be used for a squashed commit message.*
+
+         Please note the following:
+            If you choose to make contributions to the code
+            then you hereby grant a non-exclusive, royalty-free perpetual license
+            to install, use, modify, prepare derivative works,
+            incorporate into other computer software,
+            distribute, and sublicense such enhancements or derivative works
+            thereof, in binary and source code form.
+
+
+## Git workflow
+
+IAMReX uses [git](https://git-scm.com) for version control. If you
+are new to git, you can follow one of these tutorials:
+- [Learn git with bitbucket](https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud)
+- [git - the simple guide](http://rogerdudler.github.io/git-guide/)
+
+### Make your own fork and create a branch on it
+
+The basic workflow is:
+- Fork the main repo (or update it if you already created it).
+- Implement your changes and push them on a new branch `<branch_name>` on
+your fork.
+- Create a Pull Request from branch `<branch_name>` on your fork to branch
+`development` on the main IAMReX repository.
+
+First, let us setup your local git repo. To make your own fork of the main
+repository, press the fork button on the [IAMReX Github page](https://github.com/ruohai0925/IAMReX).
+
+
+Then, clone IAMReX on your local computer. If you plan on doing a lot of IAMReX development,
+we recommend configuring your clone to use ssh access so you won't have to enter your Github
+password every time, which you can do using these commands:
+
+```
+git clone https://github.com/ruohai0925/IAMReX.git
+cd IAMReX
+
+# Add your own fork.
+# Here <Jane> is the name you give to your fork. It does not need to be your github name.
+# <myGithubUsername> is your GitHub name.
+git remote add <Jane> git@github.com:<myGithubUsername>/IAMReX.git
+git fetch <Jane>
+
+# Don't push to the main repo. Instead pushes go to your fork.
+git remote set-url --push origin git@github.com:<myGithubUsername>/IAMReX.git
+```
+
+For instructions on setting up SSH access to your Github account on a new
+machine, see
+[here.](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh)
+
+If you instead prefer to use HTTPS authentication, configure your local clone as follows:
+
+```
+git clone https://github.com/ruohai0925/IAMReX.git
+cd IAMReX
+
+# Add your own fork.
+# Here <Jane> is the name you give to your fork. It does not need to be your github name.
+# <myGithubUsername> is your GitHub name.
+git remote add <Jane> https://github.com/<myGithubUsername>/IAMReX.git
+git fetch <Jane>
+
+# Don't push to the main repo. Instead pushes go to your fork.
+git remote set-url --push origin https://github.com/<myGithubUsername>/IAMReX.git
+```
+
+Now you are free to play with your fork (for additional information, you can visit the
+[Github fork help page](https://help.github.com/en/articles/fork-a-repo)).
+
+> Note: you do not have to re-do the setup above every time.
+
+Make sure you are on the `development` branch with
+```
+git checkout development
+git pull
+```
+in the IAMReX directory.
+
+Create a branch `<branch_name>` (the branch name should reflect the piece
+of code you want to add, like `high_order_interpolation`) with
+```
+git checkout -b <branch_name>
+```
+and do the coding you want.
+Add the files you work on to the git staging area with
+```
+git add <file_I_created> <and_file_I_modified>
+```
+### Commit & push your changes
+
+Periodically commit your changes with
+```
+git commit -m "This is a 50-char description to explain my work"
+```
+
+The commit message (between quotation marks) is super important in order to
+follow the developments and identify bugs.
+
+For the moment, commits are on your local repo only. You can push them to
+your fork with
+```
+git push -u <Jane> <branch_name>
+```
+
+If you want to synchronize your branch with the `development` branch (this is useful
+when `development` is being modified while you are working on
+`<branch_name>`), you can use
+```
+# merge IAMReX main repo's development into current branch
+git pull origin development
+```
+and fix any conflicts that may occur.
+
+Do not merge your branch for PR into your local `development` branch,
+because it will make your local `development` branch diverge from the
+matching branch in the main repository after your PR is merged.
+
+### Submit a Pull Request
+
+A Pull Request is the way to efficiently visualize the changes you made
+and to propose your new feature/improvement/fix to the IAMReX project.
+Right after you push changes, a banner should appear on the Github page of
+your fork, with your `<branch_name>`.
+- Click on the `compare & pull request` button to prepare your PR.
+- It is time to communicate your changes: write a title and a description for
+your PR. People who review your PR are happy to know
+  * what feature/fix you propose, and why
+  * how you made it (created a new class than inherits from...)
+  * and anything relevant to your PR (performance tests, images, *etc.*)
+- Press `Create pull request`. Now you can navigate through your PR, which
+highlights the changes you made.
+
+Please DO NOT write large Pull Requests, as they are very difficult and
+time-consuming to review. As much as possible, split them into small,
+targeted PRs.
+For example, if find typos in the documentation open a pull request that only fixes typos.
+If you want to fix a bug, make a small pull request that only fixes a bug.
+If you want to implement a large feature, write helper functionality first, test it and submit those as a first pull request.
+If you want to implement a feature and are not too sure how to split it,
+just open a discussion about your plans and ping other IAMReX developers on it to chime in.
+
+Even before your work is ready to merge, it can be convenient to create a PR
+(so you can use Github tools to visualize your changes). In this case, please
+make a "draft" PR using the drop-down menu next to the "Create pull request" button.
+
+Once your pull request is made, we will review and potentially merge it.
+We recommend always creating a new branch for each pull request, as per the above instructions.
+Once your pull request is merged, you can delete your local PR branch with
+```
+git branch -D <branch_name>
+```
+
+and you can delete the remote one on your fork with
+```
+git push <Jane> --delete <branch_name>
+```
+
+Generally speaking, you want to follow the following rules.
+
+  * Do not merge your branch for PR into your local `development` branch that tracks IAMReX
+    `development` branch.  Otherwise your local `development` branch will diverge from IAMReX
+    `development` branch.
+
+  * Do not commit in your `development` branch that tracks IAMReX `development` branch.
+
+  * Always create a new branch based off the latest `development` branch for
+    each pull request, unless you are going to use git to fix it later.
+
+If you have accidentally committed in `development` branch, you can fix it as follows,
+```
+git checkout -b new_branch # save your changes in a branch
+git checkout development
+git fetch origin
+git reset --hard origin/development
+```
+After this, the local `development` should be in sync with IAMReX `development` and your recent
+commits have been saved in `new_branch` branch.
+
+## IAMReX Coding Style Guide
+
+### Code Guidelines
+
+IAMReX developers should adhere to the following coding guidelines:
+  * Indentations should use 4 spaces, not tabs.
+  * Use curly braces for single statement blocks. For example:
+```cpp
+       for (int n=0; n<10; ++n) {
+           Print() << "Like this!";
+       }
+```
+  or
+```cpp
+       for (int n=0; n<10; ++n) { Print() << "Like this!"; }
+```
+  but not
+```cpp
+
+       for (int n=0; n<10; ++n) Print() << "Not like this.";
+```
+  or
+```cpp
+       for (int n=0; n<10; ++n)
+          Print() << "Not like this.";
+```
+  * When declaring and defining a function, add a space after the function name and before the
+parenthesis of the parameter list (but not when simply calling the function). For example:
+```cpp
+        void CorrectFunctionDec (int input)
+```
+  Not
+```cpp
+        void IncorrectFunctionDec(int input)
+```
+  This makes it easy to find where functions are defined with grep.
+  * Member variables should be prefixed with `m_`. For example:
+```cpp
+       amrex::Real m_variable;
+```
+These guidelines should be adhered to in new contributions to IAMReX, but
+please refrain from making stylistic changes to unrelated sections of code in your PRs.
+
+### API Documentation Using Doxygen
+
+The Doxygen documentation is designed for advanced user-developers. It aims
+to maximize the efficiency of a search-and-find style of locating information.
+Doxygen style comment blocks should proceed the namespace, class, function, etc.
+to be documented where appropriate. For example:
+```cpp
+   /**
+    * \brief A one line description.
+    *
+    * \param[in] variable A short description of the variable.
+    * \param[inout] data The value of data is read and changed.
+    *
+    * A longer description can be included here.
+    */
+
+    void MyFunction (int variable, MultiFab& data){
+    ...
+```
+Additional information regarding Doxygen comment formatting can be found
+in the [Doxygen Manual](https://www.doxygen.nl/manual/).
+
+### Describe
+
+The current CONTRIBUTING.md file is modified based on the [CONTRIBUTING.md](https://github.com/AMReX-Codes/amrex/blob/development/CONTRIBUTING.md). in the amrex project.

Docs/IAMReX_documentation/source/Introduction_Chapter.rst

@@ -1,7 +1,7 @@
 Introduction
 ===================
 
-This IAMReX repo extends the capability of original `IAMR <https://amrex-fluids.github.io/IAMR/>`_ codes, aiming at simulating the multiphase incompressible flows and fluid structure interaction problems on both CPUs and GPUs with/without subcycling. The Navier-Stokes euqations are solved on an adaptive semi-staggered grid using the projection method. The gas-liquid interface is captured using the level set (LS) method. The fluid-solid interface is resolved using the multidirect forcing immersed boundary method (IBM). The particle-wall as well as the particle-particle collisions are also captured by the adaptive collision time model (ACTM).
+This IAMReX repo extends the capability of original `IAMR <https://amrex-fluids.github.io/IAMR/>`_ codes, aiming at simulating the multiphase incompressible flows and fluid structure interaction problems on both CPUs and GPUs with/without subcycling. The Navier-Stokes equations are solved on an adaptive semi-staggered grid using the projection method. The gas-liquid interface is captured using the level set (LS) method. The fluid-solid interface is resolved using the multidirect forcing immersed boundary method (IBM). The particle-wall as well as the particle-particle collisions are also captured by the adaptive collision time model (ACTM).
 
 
 Features

Docs/IAMReX_documentation/source/index.rst

@@ -6,7 +6,7 @@
 IAMReX documentation
 ====================
 
-This IAMReX repo extends the capability of original `IAMR <https://amrex-fluids.github.io/IAMR/>`_ codes, aiming at simulating the multiphase incompressible flows and fluid structure interaction problems on both CPUs and GPUs with/without subcycling. The Navier-Stokes euqations are solved on an adaptive semi-staggered grid using the projection method. The gas-liquid interface is captured using the level set (LS) method. The fluid-solid interface is resolved using the multidirect forcing immersed boundary method (IBM). The particle-wall as well as the particle-particle collisions are also captured by the adaptive collision time model (ACTM).
+This IAMReX repo extends the capability of original `IAMR <https://amrex-fluids.github.io/IAMR/>`_ codes, aiming at simulating the multiphase incompressible flows and fluid structure interaction problems on both CPUs and GPUs with/without subcycling. The Navier-Stokes equations are solved on an adaptive semi-staggered grid using the projection method. The gas-liquid interface is captured using the level set (LS) method. The fluid-solid interface is resolved using the multidirect forcing immersed boundary method (IBM). The particle-wall as well as the particle-particle collisions are also captured by the adaptive collision time model (ACTM).
 
 .. toctree::
    :maxdepth: 2

JOSS_paper/paper.md

@@ -68,10 +68,10 @@ affiliations:
 date: 17 January 2025
 bibliography: paper.bib
 
-# # Optional fields if submitting to a AAS journal too, see this blog post:
+# # Optional fields if submitting to a ASS, AS journal too, see this blog post:
 # # https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing
-# aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it.
-# aas-journal: Astrophysical Journal <- The name of the AAS journal.
+# aas-doi: 10.3847/xxxxx <- update this with the DOI from ASS, AS once you know it.
+# aas-journal: Astrophysical Journal <- The name of the ASS, AS journal.
 ---
 
 # Summary

JOSS_paper/paper.pdf

@@ -1,5 +1,5 @@
 <div align="center">
-<img src="./README_figures/IAMReX.png" alt="tittle" width="300">
+<img src="./README_figures/IAMReX.png" alt="title" width="300">
 <p align="center">
   <a href="https://arxiv.org/abs/2408.14140">
   <img src="https://img.shields.io/badge/arXiv-2408.14140-blue" alt="arxiv">
@@ -20,7 +20,7 @@
 
 ## Overview
 
-This IAMReX repo extends the capability of original [IAMR](https://github.com/AMReX-Fluids/IAMR) codes, aiming at simulating the multiphase incompressible flows and fluid structure interaction problems on both CPUs and GPUs with/without subcycling. The Navier-Stokes euqations are solved on an adaptive semi-staggered grid using the projection method. The gas-liquid interface is captured using the level set (LS) method. The fluid-solid interface is resolved using the multidirect forcing immersed boundary method (IBM). The particle-wall as well as the particle-particle collisions are also captured by the adaptive collision time model (ACTM).
+This IAMReX repo extends the capability of original [IAMR](https://github.com/AMReX-Fluids/IAMR) codes, aiming at simulating the multiphase incompressible flows and fluid structure interaction problems on both CPUs and GPUs with/without subcycling. The Navier-Stokes equations are solved on an adaptive semi-staggered grid using the projection method. The gas-liquid interface is captured using the level set (LS) method. The fluid-solid interface is resolved using the multidirect forcing immersed boundary method (IBM). The particle-wall as well as the particle-particle collisions are also captured by the adaptive collision time model (ACTM).
 
 
 
@@ -163,6 +163,24 @@ gfortran -o fixBed DomainFill.F90
 ## State of the field
 We made great efforts to simulate more complex multiphase flows at higher resolution using IAMReX. One effort is to combine the AMR technique with the multidirect forcing immersed boundary method to resolve particles only on the finest-level grid. It significantly reduces the grid requirements for particle-resolved simulation compared with commonly used uniform grid solvers [Incompact3d](https://github.com/xcompact3d/Incompact3d), [CaNS](https://github.com/CaNS-World/CaNS), and [CP3d](https://github.com/GongZheng-Justin/CP3d). Additionally, we utilized a subcycling technique to alleviate the time step constraint on coarser levels. It minimizes the total time step needed by time advancement compared with the non-subcycling technique used in other AMR-related packages, such as [IBAMR](https://github.com/IBAMR/IBAMR.git), [basilisk](http://basilisk.fr/), and [incflo](https://github.com/AMReX-Fluids/incflo.git).
 
+## Get Help
+
+You can also view questions
+and ask your own on our [GitHub Discussions](https://github.com/ruohai0925/IAMReX/issues) page.
+To obtain additional help, simply post an issue.
+
+## Contribute
+
+We are always happy to have users contribute to the IAMReX source code. To
+contribute, issue a pull request against the development branch.
+Any level of changes are welcomed: documentation, bug fixes, new test problems,
+new solvers, etc. For more details on how to contribute to IAMReX, please see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+💡 If you're using IAMReX in your own GitHub projects, consider adding `IAMReX`
+as a [repository topic](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics)!
+This helps others discover related work and strengthens the IAMReX ecosystem.
+
 ## Citation
 
 To cite IAMReX, please use

README.md

@@ -1207,7 +1207,7 @@ void Particles::Initialize()
             ParticleProperties::_x.shrink_to_fit();
             ParticleProperties::_y.shrink_to_fit();
             ParticleProperties::_z.shrink_to_fit();
-            amrex::Print() << "             intial Particle by file : " << particle_init_file
+            amrex::Print() << "             initial Particle by file : " << particle_init_file
                            << "             particle's size : " << ParticleProperties::_x.size() << "\n";
         }
 

Source/DiffusedIB.cpp

@@ -5483,7 +5483,7 @@ NavierStokesBase::reinitialization_sussman (Real dt,
     if (verbose) amrex::Print() << "In the NavierStokesBase::reinitialization_sussman() " << std::endl;
     if (verbose) amrex::Print() << "loop_iter " << loop_iter << std::endl;
 
-    // Step 1: get sgn, similiar to heaviside
+    // Step 1: get sgn, similar to heaviside
     if (loop_iter==1) {
         phi_to_sgn0(phi_original);
     }

Source/NavierStokesBase.cpp

@@ -23,7 +23,7 @@
 rhs = [-dis, 0, -dis, 0, dis, 0, -dis, 0, -dis]
 print(rhs)
 
-# Let us say wanna use the least square method to solver matrix * x = rhs, in whcih x is a 6 by 1 array.
+# Let us say wanna use the least square method to solver matrix * x = rhs, in which x is a 6 by 1 array.
 
 # Solve using least squares
 x, residuals, rank, s = np.linalg.lstsq(matrix, rhs, rcond=None)

Source/ls.py

@@ -13,7 +13,7 @@ python3 test_IAMReX.py
 # Here are the running results, which indicate that the case has been built and run successfully.
 Script Directory: xxx/IAMReX/Test_IAMReX
 Test Working Directory: xxx/IAMReX/Tutorials/RayleighTaylor_LS
-test_RayleighTaylor_LS succceed
+test_RayleighTaylor_LS succeed
 ```
 
 If you want to add a new test, here are only two thing you need to do. 
@@ -30,7 +30,7 @@ If you want to add a new test, here are only two thing you need to do.
         stdout=None if print_output else subprocess.DEVNULL,
         stderr=None if print_output else subprocess.DEVNULL
         )
-        print("test_RayleighTaylor succceed")
+        print("test_RayleighTaylor succeed")
     ```
 2. Add it to the main() .
     ```python