Merge pull request #40 from prashjha/fix-joss

More fixes for comments during JOSS reviews
prashjha · Feb 7, 2025 · a67abb3 · a67abb3
2 parents 8599859 + 054af48
commit a67abb3
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ We have created channels on various platforms:
 - [PeriDEM on Gitter](https://gitter.im/PeriDEM/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
   * Gitter is absolutely open and easy to join.
 - [PeriDEM on slack](peridem.slack.com)
-  * Send us an email if interested in joining the workspace.
+  * Email us if interested in joining the workspace.
 
 ## Documentation
 [Doxygen generated documentation](https://prashjha.github.io/PeriDEM/) details functions and objects in the library. 
@@ -245,18 +245,27 @@ Following dependencies are included in the `PeriDEM` library in `external` folde
 If all the dependencies are installed on the global path (e.g., `/usr/local/`), 
 commands for building the PeriDEM code is as simple as
 ```sh
-cmake   -DEnable_Documentation=OFF # or ON \
+cmake   -DEnable_Documentation=OFF
         -DEnable_Tests=ON \
-        -DEnable_High_Load_Tests=OFF # ON if you want ctest to include high-load tests \
-        -DDisable_Docker_MPI_Tests=ON # only for docker; OFF if you can run MPI in docker\
-        -DVTK_DIR="${VTK_DIR}" # e.g., /usr/local/lib/cmake/vtk-9.3 \
-        -DMETIS_DIR="${METIS_DIR}" # e.g., /usr/lib \
+        -DEnable_High_Load_Tests=OFF \
+        -DDisable_Docker_MPI_Tests=ON \
+        -DVTK_DIR="${VTK_DIR}" \
+        -DMETIS_DIR="${METIS_DIR}" \
         -DCMAKE_BUILD_TYPE=Release \
         <PeriDEM source directory>
 
 make -j 4
 ```
 
+> :exclamation: `cmake` and `make` commands should be run inside the `build` 
+directory. You can create the `build` directory either inside or outside the 
+repository. 
+
+> :exclamation: As of now, we can only build the library and not install it. 
+ This means you will have to build the package in the `build` directory, and 
+ use the `build/bin/PeriDEM` executable. We plan to provide the method to `install` 
+ the library in the future.  
+
 We refer to [tools/README.md](./tools/README.md) for further details about installing dependencies and building the library in different ubuntu releases.
 
 ### Future plans
@@ -266,7 +275,7 @@ We are moving in following key directions:
 - MPI parallelism for PeriDEM simulations. Issue is distributing particles to different 
   processors and performing communication efficiently
 - Asynchronous parallelism within MPI? Currently, we use `Taskflow` to perform 
-  parallel for loops in a non-mpi simulation. In future, we will be interested in using 
+  parallel for loops in a non-mpi simulation. In the future, we will be interested in using 
   multithreading combined with MPI to further speed-up the simulations
 - GPU parallelism?
 
@@ -287,7 +296,7 @@ able to compile PeriDEM in ubuntu (>= 18.04) and mac.
 Feel free to reach out or open an issue. For more open 
 discussion of issues and ideas, contact via 
 [PeriDEM on Gitter](https://gitter.im/PeriDEM/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link) 
-or [PeriDEM on slack](peridem.slack.com) (for slack, send us an email to join). 
+or [PeriDEM on slack](peridem.slack.com) (for slack, email us to join). 
 If you like some help, want to contribute, extend the code, or discuss new ideas, 
 please do reach out to us.
 
@@ -306,7 +315,7 @@ Navigate to the example directory [examples/PeriDEM/two_particles/twop_wall_conc
 and run the example as follows
 ```sh
 # manually
-examples/PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp
+cd examples/PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp
 mkdir ../out # <-- make directory for simulation output. In .yaml, we specify output path as './out'
 <peridem build path>bin/PeriDEM -i input_0.yaml -nThreads 2
 
@@ -360,6 +369,12 @@ type from **`Surface`** to **`Point Gaussian`**. Next, a couple of things to do
   - Lastly, when the `Damage_Z` is very high at few nodes, you may want to rescale 
     the data to the range, say `[0,2]` or `[0,10]`, so that it is easier to identify 
     regions with elastic deformation and region with fracture.
+
+## Contributing
+We welcome contributions to the code. In `Future plans` section above, some 
+potential directions are listed.
+Please fork this repository, make changes, and make a pull request to the 
+source branch.  
 
 ## Citations
 If this library was useful in your work, we recommend citing the following article:

diff --git a/examples/README.md b/examples/README.md
@@ -17,25 +17,32 @@ and particle locations file. Typically, the input files consists of:
     * `r` - radius of the particle 
     * `o` - orientation in radians. This is used to give particle (particle mesh) a rotation
   - `mesh.msh` - mesh file for the reference particle or wall. For example, 
-    in [compressive test](./PeriDEM/compressive_test/n500_circ_hex/init_config/inp) example, 
-    there are four mesh files: one each for the circular and hexagon-shaped particle 
-    and one each for the fixed and mobile wall.
+    in [compressive test](./PeriDEM/compressive_test/compression_small_set
+    /inp) example, running `python3 -B 
+    problem_setup.py` will generate following `.msh` files: 
+    `mesh_cir_large_0.msh`, `mesh_cir_small_0.msh`, `mesh_drum2d_large_0.
+    msh`, `mesh_drum2d_small_0.msh`, `mesh_fixed_container_0.msh`, 
+    `mesh_hex_large_0.msh`, `mesh_hex_small_0.msh`, `mesh_moving_container_0.
+    msh`, `mesh_tri_large_0.msh`, `mesh_tri_small_0.msh`.
 
 ### Two-particle tests
 
+The examples below are for demonstration. Similar results can be obtained by 
+modifying and running examples in `PeriDEM/examples/PeriDEM/two_particles/`.
+
 |  <img src="../assets/two_particle_circ_no_damp.gif" width="200">  | <img src="../assets/two_particle_circ_damp.gif" width="200"> |
 |:-----------------------------------------------------------------:|:------------------------------------------------------------:|
-| [Circular without damping](./PeriDEM/two_particles/circ_no_damp/) | [Circular with damping](./PeriDEM/two_particles/circ_damp/)  |
+| Circular without damping | Circular with damping  |
 
-| <img src="../assets/two_particle_circ_diff_material.gif" width="200"> |  <img src="../assets/two_particle_circ_damp_diff_radius.gif" width="200">  |       <img src="../assets/two_particle_circ_diff_radius_diff_material.gif" width="200">        |
-|:---------------------------------------------------------------------:|:--------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:|
-|  [Different materials](./PeriDEM/two_particles/circ_diff_material/)   |     [Different radius](./PeriDEM/two_particles/circ_damp_diff_radius/)     | [Different radius different material](./PeriDEM/two_particles/circ_diff_radius_diff_material/) |
+| <img src="../assets/two_particle_circ_diff_material.gif" width="200"> | <img src="../assets/two_particle_circ_damp_diff_radius.gif" width="200">  |       <img src="../assets/two_particle_circ_diff_radius_diff_material.gif" width="200">        |
+|:---------------------------------------------------------------------:|:-------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:|
+|   Different materials   |     Different radius     | Different radius different material |
 
 ### Two-particle with wall test
 
 |  <img src="../assets/two_particle_wall_concave_diff_material_diff_size.gif" width="400">   | 
 |:------------------------------------------------------------------------------------------:| 
-|     [Concave particles](./PeriDEM/two_particles_wall/concave_diff_material_diff_size/)     |
+|     Concave particles     |
 
 ### Compressive tests
 Setup for this test consists of 502 circular and hexagonal-shaped particles of varying 
@@ -48,9 +55,9 @@ in individual particles, especially those connected by force chains, resulting i
 yielding of the system. For more details, we refer to 
 [Jha et al. 2021](https://prashjha.github.io/publication/jha-2020-peridem/)
 
-|     <img src="../assets/compressive_test_cir_hex_n500.jpg" width="600">     | 
-|:---------------------------------------------------------------------------:| 
-|     [Compressive test setup](./PeriDEM/compressive_test/n500_circ_hex/)     |
+|    <img src="../assets/compressive_test_cir_hex_n500.jpg" width="600">     | 
+|:--------------------------------------------------------------------------:| 
+|     Compressive test setup     |
 
 |                                                                            <img src="../assets/compressive_test_reaction_force_n500.jpg" width="600">                                                                             | 
 |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| 
@@ -60,6 +67,7 @@ yielding of the system. For more details, we refer to
 |:------------------------------------------------------:| 
 |              Compressive test simulation               | 
 
+Examples similar to above can be found in `PeriDEM/examples/PeriDEM/compressive_test/`.
 
 ### Attrition tests - Particles in a rotating container
 We consider mix of different particles in a rotating container. Particles considered include circular, triangular, hexagonal, and drum shaped. Particles come in large and small shapes (their sizes are purturbed randomly). In order to to introduce diversity of material properties, we considered large particles to be tougher compared to the smaller ones. Setup files are in [PeriDEM/attrition_tests](./PeriDEM/attrition_tests)
@@ -83,22 +91,25 @@ with paths are correctly provided in `input.yaml`, we will run the problem (usin
 Some examples are listed below.
 
 ### Two-particle with wall
-Navigate to the example directory [PeriDEM/two_particles_wall/concave_diff_material_diff_size/inp](./PeriDEM/two_particles_wall/concave_diff_material_diff_size/inp)
+Navigate to the example directory [PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp](./PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp)
 and run the example as follows
 ```sh
+# manually
+cd PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp
 mkdir ../out # <-- make directory for simulation output. In .yaml, we specify output path as './out'
 <peridem build path>bin/PeriDEM -i input_0.yaml -nThreads 2
+
+# or call run.sh script
+cd PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size
+./run.sh 4 # with 4 threads
 ```
 
-You may also use the included [problem_setup.py](./PeriDEM/two_particles_wall/concave_diff_material_diff_size/inp/problem_setup.py)
+You may also use the included [problem_setup.py](./PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp/problem_setup.py)
 to modify simulation parameters and run the simulation using
-[run.sh](./PeriDEM/two_particles_wall/concave_diff_material_diff_size/run.sh)
-(in directoy [PeriDEM/two_particles_wall/concave_diff_material_diff_size](PeriDEM/two_particles_wall/concave_diff_material_diff_size)).
-`run.sh` shows how different input files are created for the simulation.
+[run.sh](./PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/run.sh).
 
 > :exclamation: You may need to modify the path of `PeriDEM` executable in `run.sh` file.
 
-
 > In all `problem_setup.py` files in the example and test directory, the main function is `create_input_file()`.
 > Here we set all model parameters, create `.yaml` input file, and `.geo` files for meshing.
 
@@ -118,16 +129,19 @@ Except geometrical parameters of walls and particles, rest of the parameters in
 > all aspects of the simulation.
 
 ### Compressive test
-Navigate to the example directory [PeriDEM/compressive_test/n500_circ_hex/run1/inp](./PeriDEM/compressive_test/n500_circ_hex/run1/inp)
+Navigate to the example directory [PeriDEM/compressive_test/compression_large_set/inp](./PeriDEM/compressive_test/compression_large_set/inp)
 and run the example as follows (note that this is a computationally expensive example)
 ```sh
+cd PeriDEM/compressive_test/compression_large_set/inp
 mkdir ../out 
 <peridem build path>bin/PeriDEM -i input_0.yaml -nThreads 12
+
+# or you can use the run.sh script in the path PeriDEM/compressive_test/compression_large_set/
 ```
 
 As before:
-- you can modify [problem_setup.py](./PeriDEM/compressive_test/n500_circ_hex/run1/inp/problem_setup.py), see `create_input_file()` method, to change the simulation settings
-- run the simulation using [run.sh](./PeriDEM/compressive_test/n500_circ_hex/run1/run.sh) (in directory [PeriDEM/compressive_test/n500_circ_hex/run1](./PeriDEM/compressive_test/n500_circ_hex/run1)).
+- you can modify [problem_setup.py](./PeriDEM/compressive_test/compression_large_set/inp/problem_setup.py), see `create_input_file()` method, to change the simulation settings
+- run the simulation using [run.sh](./PeriDEM/compressive_test/compression_large_set//run.sh).
 
 ### Compute times for various examples (From old version of the code!)
 For reference, we list the compute times for various examples.

diff --git a/tools/README.md b/tools/README.md
@@ -51,12 +51,12 @@ Additional dependencies for running the examples:
 If all the dependencies are installed on the global path (e.g., `/usr/local/`), 
 commands for building the PeriDEM code is as simple as
 ```sh
-cmake   -DEnable_Documentation=OFF # or ON \
+cmake   -DEnable_Documentation=OFF
         -DEnable_Tests=ON \
-        -DEnable_High_Load_Tests=OFF # ON if you want ctest to include high-load tests \
-        -DDisable_Docker_MPI_Tests=ON # only for docker; OFF if you can run MPI in docker\
-        -DVTK_DIR="${VTK_DIR}" # e.g., /usr/local/lib/cmake/vtk-9.3 \
-        -DMETIS_DIR="${METIS_DIR}" # e.g., /usr/lib \
+        -DEnable_High_Load_Tests=OFF \
+        -DDisable_Docker_MPI_Tests=ON \
+        -DVTK_DIR="${VTK_DIR}" \
+        -DMETIS_DIR="${METIS_DIR}" \
         -DCMAKE_BUILD_TYPE=Release \
         <PeriDEM source directory>
 
@@ -66,6 +66,9 @@ ctest --verbose
 ```
 
 ## Installing dependencies
+
+> :exclamation: There are some libraries (e.g., tbb) below that are required by our dependencies. 
+
 ### Mac
 Brew can be used to install all dependencies in mac as follows
 ```shell