diff --git a/README.md b/README.md index f050567bc..cae5fb7f5 100644 --- 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 \ 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' 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 index b796348b8..a64beb9a1 100644 --- 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/`. + | | | |:-----------------------------------------------------------------:|:------------------------------------------------------------:| -| [Circular without damping](./PeriDEM/two_particles/circ_no_damp/) | [Circular with damping](./PeriDEM/two_particles/circ_damp/) | +| Circular without damping | Circular with damping | -| | | | -|:---------------------------------------------------------------------:|:--------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:| -| [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/) | +| | | | +|:---------------------------------------------------------------------:|:-------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:| +| Different materials | Different radius | Different radius different material | ### Two-particle with wall test | | |:------------------------------------------------------------------------------------------:| -| [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/) -| | -|:---------------------------------------------------------------------------:| -| [Compressive test setup](./PeriDEM/compressive_test/n500_circ_hex/) | +| | +|:--------------------------------------------------------------------------:| +| Compressive test setup | | | |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| @@ -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' 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 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 index e9127c326..6a7a86223 100644 --- 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 \ @@ -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