 |
PRISMS-PF Manual
|
|
PRISMS-PF Manual
|
Before you can install PRISMS-PF, you will need to have some prerequisites installed on your machine. These include:
You can install these prerequisites however you like. The first three are typically available on most OS through your package manager. For example, on Ubuntu, you can install them with:
To install p4est and deal.II, we recommend following the instructions on the deal.II installation guide. Building deal.II and p4est using deal.II's automatic installation script candi is by far the best option for most users.
Modify the candi.cfg file, commenting out any PACKAGES other than dealii and p4est. Also, turn on the native optimizations option. You should have something like the following.
DEAL_II_CONFOPTS="" section with -march=<arch>.DEAL_II_CONFOPTS="-DDEAL_II_ALLOW_AUTODETECTION=OFF -DDEAL_II_FORCE_BUNDLED_BOOST=ON"Then perform the configuration, compilation, and installation with
or
to compile with multiple processors (much faster).
This will install both p4est and deal.II in a local directory (by default,$HOME/dealii-candi/). You can override the installation path with the prefix command (./candi.sh -p /path/to/install). Be sure to permanently set the DEAL_II_DIR environment variable to point to the deal.II installation. The candi script will prompt you with steps on how to do this.
Once you have all the prerequisites installed, you can clone the PRISMS-PF repository from GitHub, configure, build, and install the code.
First, clone the repository and navigate to the main directory.
Next, we'll configure the library. We have a table of configuration options below. Additionally, if you have CMake 3.28+ you can use our CMakePresets.json.
| Default | Description | |
|---|---|---|
PRISMS_PF_AUTODETECTION | ON | Try to detect Optional Dependencies that are in path |
PRISMS_PF_UNIT_TESTS | OFF | Build the unit tests |
PRISMS_PF_REGRESSION_TESTS | OFF | Build the regression tests |
PRISMS_PF_PERFORMANCE_TESTS | OFF | Build the performance tests |
PRISMS_PF_EXAMPLES | OFF | Build the examples |
PRISMS_PF_DOCS | OFF | Build the documentation |
PRISMS_PF_CLANG_TIDY | OFF | Run clang-tidy during the build stage |
| Default | Description | |
|---|---|---|
PRISMS_PF_64BIT_INDICES | OFF | Use 64-bit indices for large scale simulations (>2.147 billion DoFs). This relies on the fact that deal.II is also configured with this option on. Leaving this on when unnecessary will result in worse performance. |
PRISMS_PF_ADDITIONAL_DEGREES | OFF | Compile the core library with element degrees 3+. When turned off, explicit templates will only be compiled for elements degrees 1 and 2. Turning it on will allow access to higher element degrees on the application level, but increases compile time. Note that deal.II is typically configured with element degrees up to 6. If you want higher element degrees, you must configure deal.II accordingly. |
PRISMS_PF_THREADS | ON | Use threading when possible for MPI processes in Release mode. When turned off, each MPI process will only use one thread. |
PRISMS_PF_GPU | OFF | [Experimental] Use GPU backends instead of CPU. This is still under active development |
| Default | Description | |
|---|---|---|
PRISMS_PF_WITH_VTK | OFF | Enable additional VTK file I/O options |
PRISMS_PF_WITH_HDF5 | OFF | Enable HDF5 file I/O options |
PRISMS_PF_WITH_CALIPER | OFF | Enable Caliper as a profiler |
First, set the PRISMS_PF_DIR environment variable to point to where you want to install PRISMS-PF. You can add this to your rc file to have permanent access to $PRISMS_PF_DIR.
The most basic configuration is as follows:
where <nprocs> is how processors to build in parallel with.
This will build the PRISMS-PF library in both Debug and Release modes (something that deal.II does that we think is nice). If you'd like to use typical CMake build types you can also do that.
You can now compile and run any of the applications in the applications directory. For example, to compile and run the explicit allen_cahn application, you can use the following commands:
Unlike before, there is no DebugRelease build type on the application level. As an application you must choose between Debug and Release. Debug is the default build type for applications.
Debug is slooww, concerningly so sometimes. However, it's for good reason. We have a bunch of assertions that are being checked! If you have something wrong with your application, you'll get a meaningful error that will tell you how to fix it. This is good when developing applications. Always run in Debug when developing applications. If you're playing around with model parameters or want to run non-test systems use Release. However, if something goes wrong, you may get an unintelligible error message or a SEGFAULT. Debug when developing applications 
1.13.2