JOSS review: Address #45

.gitignore

@@ -44,6 +44,9 @@ build2
 build*
 cmake-build*
 
+# pixi lock file
+pixi.lock
+
 # ide directory
 .idea
 .idea/workspace.xml

CMakeLists.txt

@@ -6,28 +6,34 @@
 # Distributed under the Boost Software License, Version 1.0. (See accompanying
 # file LICENSE)
 
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.10...4.3)
 
 #----------------------------------#
 #<<<<<<<<<< Project name >>>>>>>>>>#
 #----------------------------------#
-project(PeriDEM LANGUAGES CXX C)
+project(PeriDEM VERSION 0.2.1 LANGUAGES CXX C)
 
 set(CMAKE_PROJECT_HOMEPAGE_URL "https://github.com/prashjha/PeriDEM")
 set(CMAKE_PROJECT_DESCRIPTION "PeriDEM -- Peridynamics-based high-fidelity model for granular media")
 
-# version
-set(VERSION_MAJOR 0)
-set(VERSION_MINOR 2)
-set(VERSION_UPDATE 0)
-
 #----------------------------------#
 #<<<<<<<<<< Project setting >>>>>>>>>>#
 #----------------------------------#
 
-# config files
-configure_file("${PROJECT_SOURCE_DIR}/PeriDEMConfig.h.in"
-        "${PROJECT_SOURCE_DIR}/src/PeriDEMConfig.h")
+# Configure header with version info
+configure_file(
+  "${PROJECT_SOURCE_DIR}/PeriDEMConfig.h.in"
+  "${PROJECT_BINARY_DIR}/PeriDEMConfig.h"
+  @ONLY
+)
+
+# Use version from project() for CMake package config
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+  "${CMAKE_CURRENT_BINARY_DIR}/PeriDEMConfigVersion.cmake"
+  VERSION ${PROJECT_VERSION}
+  COMPATIBILITY AnyNewerVersion
+)
 
 # executable directory
 set(EXECUTABLE_OUTPUT_PATH "${PROJECT_BINARY_DIR}/bin")
@@ -159,9 +165,9 @@ endif()
 if (${Enable_CMAKE_Debug_Build})
     message(STATUS "Including key directories")
 endif()
-include_directories(SYSTEM external)
-include_directories(${MPI_INCLUDE_PATH})
-include_directories(src)
+# include_directories(SYSTEM external)
+# include_directories(${MPI_INCLUDE_PATH})
+# include_directories(src)
 
 #----------------------------------#
 #<<<<<<<<<< Subdirectories >>>>>>>>>>#
@@ -212,12 +218,52 @@ endif()
 #----------------------------------#
 add_executable(PeriDEM src/main.cpp)
 
+target_include_directories(PeriDEM
+  PUBLIC
+    $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>
+    $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}>
+    $<INSTALL_INTERFACE:include>
+)
 target_link_libraries(PeriDEM PUBLIC Model)
 
+install(TARGETS PeriDEM Model Util RW Inp Material Loading Geometry FE Particle NSearch
+  EXPORT PeriDEMTargets
+  RUNTIME DESTINATION bin
+  LIBRARY DESTINATION lib
+  ARCHIVE DESTINATION lib
+)
+
+install(EXPORT PeriDEMTargets
+  FILE PeriDEMTargets.cmake
+  NAMESPACE PeriDEM::
+  DESTINATION lib/cmake/PeriDEM
+)
+
+
 #----------------------------------#
 #<<<<<<<<<< PeriDEM install >>>>>>>>>>#
 #----------------------------------#
-install(TARGETS PeriDEM DESTINATION bin)
+install(FILES ${PROJECT_BINARY_DIR}/PeriDEMConfig.h DESTINATION include)
+install(DIRECTORY src/ DESTINATION include FILES_MATCHING PATTERN "*.h")
+install(FILES external/csv/csv.h DESTINATION include/csv)
+install(DIRECTORY external/nanoflann/ DESTINATION include/nanoflann FILES_MATCHING PATTERN "*.hpp")
+install(DIRECTORY external/taskflow/taskflow/ DESTINATION include/taskflow)
+install(DIRECTORY external/fmt/include/ DESTINATION include)
+
+configure_package_config_file(
+  cmake/PeriDEMConfig.cmake.in
+  ${CMAKE_CURRENT_BINARY_DIR}/PeriDEMConfig.cmake
+  INSTALL_DESTINATION lib/cmake/PeriDEM
+)
+
+install(FILES
+  ${CMAKE_CURRENT_BINARY_DIR}/PeriDEMConfig.cmake
+  ${CMAKE_CURRENT_BINARY_DIR}/PeriDEMConfigVersion.cmake
+  ${PROJECT_SOURCE_DIR}/cmake/FindMetis.cmake
+  DESTINATION lib/cmake/PeriDEM
+)
+
+
 
 #----------------------------------#
 #<<<<<<<<<< Post build operations >>>>>>>>>>#

PeriDEMConfig.h.in

@@ -13,8 +13,12 @@
 
 #include<cstddef>
 
-size_t const MAJOR_VERSION = @VERSION_MAJOR@;
-size_t const MINOR_VERSION = @VERSION_MINOR@;
-size_t const UPDATE_VERSION = @VERSION_UPDATE@;
+#define PERIDEM_VERSION_MAJOR @PROJECT_VERSION_MAJOR@
+#define PERIDEM_VERSION_MINOR @PROJECT_VERSION_MINOR@
+#define PERIDEM_VERSION_PATCH @PROJECT_VERSION_PATCH@
+
+const size_t MAJOR_VERSION = PERIDEM_VERSION_MAJOR;
+const size_t MINOR_VERSION = PERIDEM_VERSION_MINOR;
+const size_t UPDATE_VERSION = PERIDEM_VERSION_PATCH;
 
 #endif

README.md

@@ -16,6 +16,7 @@
     * [Dependencies](#Dependencies)
     * [Building the code](#Building-the-code)
     * [Recommendations for quick build](#Recommendations-for-quick-build)
+    * [Install & use as a CMake package](#install--use-as-a-cmake-package)
   - [Running simulations](#Running-simulations)
     * [Two-particle with wall](#Two-particle-with-wall)
     * [Compressive test](#Compressive-test)
@@ -25,6 +26,7 @@
   - [Developers](#Developers)
 
 ## Introduction
+
 Implementation of the high-fidelity model of granular media that combines the advantages 
 of peridynamics and discrete element method (DEM). 
 The model has the following advantages over existing mechanical models for granular media:
@@ -48,14 +50,17 @@ We have created channels on various platforms:
   * Email us if interested in joining the workspace.
 
 ## Documentation
+
 [Doxygen generated documentation](https://prashjha.github.io/PeriDEM/) details functions and objects in the library. 
 
 ## Tutorial
+
 We explain the setting-up of simulations in further details in [tutorial](./tutorial/README.md). 
 We consider `two-particle` test setup with non-circular particles and `compressive-test` to 
 discuss the various aspects of simulations.
 
 ## Examples
+
 We next highlight some key examples. Further details are available in [examples/README.md](./examples/README.md). 
 
 ### Two-particle tests
@@ -75,6 +80,7 @@ We next highlight some key examples. Further details are available in [examples/
 | Concave particles |
 
 ### Compressive tests
+
 Setup for this test consists of 502 circular and hexagonal-shaped particles of varying 
 radius and orientation inside a rectangle container. The container's top wall is moving 
 downward at a prescribed speed, resulting in the compression of the particle system. 
@@ -91,6 +97,7 @@ yielding of the system. For more details, we refer to
 
 
 ### Attrition tests
+
 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 [examples/PeriDEM/attrition_tests](./examples/PeriDEM/attrition_tests)
 
 |                                         <img src="./assets/attrition_test_sim1.gif" width="250">                                         |                                                                              <img src="./assets/attrition_test_sim2.gif" width="250">                                                                               | 
@@ -102,14 +109,17 @@ Complex container geometries can be considered as well. For example, the image b
 <img src="./examples/PeriDEM/attrition_tests/sim4_multi_particle_circ_tri_drum_hex_with_rotating_rectangle_container_with_protrusion_and_opening_within_bigger_rectangle_container/init_view.png" width="600">
 
 ### Single particle deformation
+
 We can use `PeriDEM` executable or `Peridynamics` executable in `apps` directory to simulate the deformation of single particle/structure using peridynamics. See [examples/README.md](./examples/README.md) and [examples/Peridynamics](./examples/Peridynamics) folder. 
 
 ## Brief implementation details
+
 The main implementation of the model is carried out in the model directory [dem](./src/model/dem). 
 The model is implemented in class [DEMModel](./src/model/dem/demModel.cpp). 
 Function `DEMModel::run()` performs the simulation. We next look at some key methods in `DEMModel` in more details:
 
 ### DEMModel::run()
+
 This function does three tasks:
 ```cpp
 void model::DEMModel::run(inp::Input *deck) {
@@ -129,6 +139,7 @@ In `DEMModel::init()`, the simulation is prepared by reading the input
 files (such as `.yaml`, `.msh`, `particle_locations.csv` files). 
 
 ### DEMModel::integrate()
+
 Key steps in  `DEMModel::integrate()` are 
 ```cpp
 void model::DEMModel::run(inp::Input *deck) {
@@ -197,6 +208,7 @@ void model::DEMModel::integrateVerlet() {
 ```
 
 ### DEMModel::computeForces()
+
 The key method in time integration is `DEMModel::computeForces()`
 In this function, we compute internal and external forces at each node of a particle 
 and also account for the external boundary conditions. This function looks like
@@ -220,13 +232,19 @@ void model::DEMModel::computeForces() {
 ```
 
 ### Further reading
+
 Above gives the basic idea of simulation steps. For more thorough understanding of 
 the implementation, interested readers can look at 
 [demModel.cpp](./src/model/dem/demModel.cpp).
 
 ## Installation
 
+The [pixi.toml](pixi.toml) file defines the dependencies and build instructions for the library. It should be used to create a reproducible environment and build the code using Pixi and CMake.
+
+To install the Pixi package manager, follow the instructions at the official [installation page](https://pixi.sh/dev/installation/#update).
+
 ### Dependencies
+
 Core dependencies are:
   - [cmake](https://cmake.org/) (>= 3.10.2) 
   - [vtk](https://vtk.org/) (>= 7.1.1)
@@ -242,6 +260,7 @@ Following dependencies are included in the `PeriDEM` library in `external` folde
   - [doxygen-awesome-css](https://github.com/jothepro/doxygen-awesome-css) (>= v2.3.3) 
 
 ### Building the code
+
 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
@@ -261,14 +280,63 @@ make -j 4
 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.
+### Install & use as a CMake package
+- Build and install (starting from a fresh clone, e.g., `git clone ... && cd PeriDEM`; create a build dir wherever you like—`build` inside the source is assumed below):
+  ```sh
+  # from the source root
+  mkdir -p build
+  cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+  cmake --build build -- -j$(sysctl -n hw.ncpu)
+
+  # install library in /tmp/peridem-install
+  cmake --install build --prefix /tmp/peridem-install
+  ```
+  This installs `bin/PeriDEM`, shared libs in `lib/`, headers in `include/`, and the CMake package files under `lib/cmake/PeriDEM`.
+- Consume in another CMake project:
+  ```cmake
+  cmake_minimum_required(VERSION 3.18)
+  project(peridem_consumer LANGUAGES CXX)
+  find_package(PeriDEM REQUIRED)
+  add_executable(hello main.cpp)
+  target_link_libraries(hello PRIVATE PeriDEM::Model) # or another PeriDEM library target
+  ```
+  Place this in, e.g., `/tmp/peridem-consumer/CMakeLists.txt`. A minimal `main.cpp` in the same folder:
+  ```cpp
+  #include <iostream>
+  #include <PeriDEMConfig.h>
+  int main() {
+    std::cout << "PeriDEM version: "
+              << PERIDEM_VERSION_MAJOR << "."
+              << PERIDEM_VERSION_MINOR << "."
+              << PERIDEM_VERSION_PATCH << "\n";
+  }
+  ```
+  Configure and build the consumer (run these inside `/tmp/peridem-consumer`):
+  ```sh
+  cmake -S . -B build -DCMAKE_PREFIX_PATH=/tmp/peridem-install
+  cmake --build build -- -j$(sysctl -n hw.ncpu)
+  ./build/hello
+  ```
+- External dependencies required on the target system: MPI, Threads, yaml-cpp, VTK (CommonCore/DataModel/IOXML), BLAS/LAPACK (Accelerate on macOS), Metis (found via bundled `FindMetis.cmake`), plus their transitive libraries. Ensure these are installed and discoverable (e.g., via `CMAKE_PREFIX_PATH` or system paths) when configuring consumers.
+
+### Using docker to test the library
+```sh
+# run ubuntu using docker (we are using the same image we use to test the library)
+docker run -it prashjha/peridem-base-noble
+
+# we install pixi and add it to the path
+curl -fsSL https://pixi.sh/install.sh | sh
+export PATH="/root/.pixi/bin:$PATH"
+
+# assuming we are now in root of docker image
+cd user/
+git clone git@github.com:prashjha/PeriDEM.git
+cd PeriDEM/
+pixi run build
+```
 
 ### Future plans
+
 We are trying to make PeriDEM MPI-friendly so that we can target large problems. 
 We are moving in following key directions:
 - MPI parallelism for Peridynamics simulations (deformation of single body subjected to external loading)
@@ -285,6 +353,7 @@ If any of the above future directions interest you or if you have new directions
 in mind, please do reach out to us.    
 
 ### Ask for help
+
 In the past, `PeriDEM` library depended on large libraries such as `HPX`, `PCL`, `Boost` (explicitly dependence). 
 We have put a lot of efforts into reducing the dependencies to absolutely minimum 
 so that it is easier to build and run `PeriDEM` in different operating systems and clusters. 
@@ -301,6 +370,7 @@ If you like some help, want to contribute, extend the code, or discuss new ideas
 please do reach out to us.
 
 ## Running simulations
+
 Assuming that the input file is `input.yaml` and all other files such as `.msh` 
 file for particle/wall and particle locations file are created and their filenames 
 with paths are correctly provided in `input.yaml`, we will run the problem (using 4 threads) 
@@ -311,6 +381,7 @@ 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 [examples/PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp](.examples/PeriDEM/two_particles/twop_wall_concave_diff_material_diff_size/inp) 
 and run the example as follows
 ```sh
@@ -334,6 +405,7 @@ to modify simulation parameters and run the simulation using
 > Here we set all model parameters, create `.yaml` input file, and `.geo` files for meshing.
 
 ### Compressive test
+
 Navigate to the example directory [examples/PeriDEM/compressive_test/compression_large_set/inp](./examples/PeriDEM/compressive_test/compression_large_set/inp) 
 and run the example as follows (note that this is a computationally expensive example)
 ```sh
@@ -349,6 +421,7 @@ As before:
   - run the simulation using [run.sh](./examples/PeriDEM/compressive_test/compression_large_set//run.sh).
 
 ## Visualizing results
+
 Simulation files `output_*.vtu` can be loaded in either [ParaView](https://www.paraview.org/) 
  or [VisIt](https://wci.llnl.gov/simulation/computer-codes/visit). 
 
@@ -371,12 +444,14 @@ type from **`Surface`** to **`Point Gaussian`**. Next, a couple of things to do
     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:
 
 > Jha, P.K., Desai, P.S., Bhattacharya, D. and Lipton, R., 2021. 
@@ -388,5 +463,6 @@ You can also cite the PeriDEM using zenodo doi:
 > Prashant K., J. (2024). Peridynamics-based discrete element method (PeriDEM) model of granular systems. Zenodo. https://doi.org/10.5281/zenodo.13888588
 
 ## Developers
+
   - [Prashant K. Jha](https://prashjha.github.io/) 
     (pjha.sci@gmail.com, prashant.jha@sdsmt.edu)