Gallery

Transonic NACA0012 with adaptive refinement	Viscous NACA0012 with Recirculation bubble (Swanson)	Kelvin-Helmholtz Instability

Double Mach Reflection	Mach 80 Astrophysical Jet	Daru Tenaud Shock Tube

Table of Contents

• Parallel High-Order Library for PDEs
  • Code Description
  • Documentation
  • Building and Running the Code
    • Build using CMake
    • Compile using Make
  • Testing
  • Debugging
  • Performance
  • Contributing checklist
• License

Parallel High-Order Library for PDEs

The [P]arallel [Hi]gh-Order [Li]brary for [P]DEs (PHiLiP) uses Discontinuous Galerkin methods to solve convection-diffusion problems.

The math supporting this code can be viewed in this very rough draft in progress Overleaf document.

Code Description

• Code uses deal.II library as the backbone (https://www.dealii.org/)
• Parallelized through MPI
• Supports weak and strong (InProgress) form of discontinuous Galerkin (DG), and flux reconstruction (FR) (InProgress)
• Supported Partial Differential Equations: Linear advection, diffusion, convection-diffusion, Burgers, Euler, Navier-Stokes.
• Supported convective numerical fluxes: Lax-Friedrichs, Roe (Harten's entropy fix) for Euler, InProgress: Split-Form
• Supported diffusive numerical fluxes: Symmetric Interior Penalty, Bassi-Rebay's 2nd formulation (BR2)
• Supported elements: LINEs, QUADs, HEXs since it uses deal.II
• Supported refinements: h (size) or p (order) (InProgress).

Documentation

The code itself is documented using Doxygen, and the latest documentation is hosted on codedocs.xyz.

Since deal.II is heavily used, their documentation is probably the most useful.

Another great resource is the deal.II Google Groups, where developers are actively answering questions.

Finally, I am also always available to answer questions regarding the code by e-mail at doug.shi-dong@mail.mcgill.ca

Building and Running the Code

The code has been succesfully built in the following environments:

• linux (ubuntu 20.04 and later);

Please consult the installation instructions for details concerning required software.

Failing tests

Since this library is developed by graduate students at McGill, there will always be sections that are work-in-progress. Some tests currently fail and are left here as part of "to-do" fixes. Therefore, if you experience any issues with tests, please consult the following list of known test failures. https://github.com/dougshidong/PHiLiP/issues?q=is%3Aissue+is%3Aopen+label%3Atestfail

Build using CMake

This must be build out-of-source. An in-source build is likely to fail. For example, to configure for the debug build:

$ ROOT$ export PHILIP_DIR=/path_to_PHiLiP/
$ ROOT$ mkdir build_debug
$ ROOT$ cd build_debug
$ ROOT$ cmake -DDEAL_II_DIR=/path_to_dealii_install/ $PHILIP_DIR

Compile using Make

Once the code has been successfully built, the available make targets can be seen using

ROOT$ make help

Of primary interest are the following:

ROOT$ make -j2     // Compile the entire code, 1D, 2D, and 3D
ROOT$ make -j2 doc // Generate the Doxygen documentation.
ROOT$ make -j2 1D  // Compile the 1D version of the code
ROOT$ make -j2 2D  // Compile the 2D version of the code
ROOT$ make -j2 3D  // Compile the 3D version of the code

Based on past experiences, you might want to limit the number of processor to 2 or 3 (make -j 3) if you have 8GB of RAM.

The html documentation can be accessed by pointing a browser at ROOT/doc/html/index.html. e.g. google-chrome ROOT/doc/html/index.html.

Testing

A list of currently known failing tests is kept in the GitHub issues with testfail tags.

Testing can be performed using CMake's ctest functionality. After successfully compiling the project, all tests can be run by executing:

$ ROOT$ ctest (which is equivalent to ROOT$ make test)

An alternative make target is provided to run tests with --output-on-failure:

ROOT$ make check

Additional useful commands are:

ROOT$ ctest -N (List the tests that would be run but not actually run them)
ROOT$ ctest -R <regex> (Run tests matching regular expression)
ROOT$ ctest -E <regex> (Exclude tests matching regular expression)
ROOT$ ctest -V (Enable verbose output from tests)
ROOT$ ctest -L <label> (Run tests matching label)
ROOT$ ctest -LE <label> (Exclude tests matching label)

Note that running ctest in Debug will take forever since some integration tests fully solve nonlinear problems with multiple orders and multiple meshes. It is suggested to perform ctest in Release mode, and only use Debug mode for debugging purposes.

More detail about running tests using labels can be found here.

Multi-species Simulations (Beta Phase)

The multi-species implementation of PHiLiP is in very early stages. In this phase of the implementation, the code has been modified to accept any number of species > 1 but it only supports the Real Gas PDE type (Inviscid Euler Multi-species). Future implementations will extend this work to viscous flows and chemically reacting flows.

To compile the code for multi-species simulations, the build must be configured as such:

ROOT$ cmake ../ -DNUMBER_OF_SPECIES=2 // Compile code for 2 species

It is recommended that a separate build directory be used for single-species and multi-species. If a build is created for single-species, but then reconfigured for multi-species, there are likely to be test failures.

The Real Gas PDE type supported by PHiLiP uses the NASA polynomials to calculate the species specific heats and species enthalpy. The NASA polynomials have to be provided for the species that the user wishes to simulate. Example files for H2, O2, and N2 with the required data is provided in tests/chemistry_files.

Testing

The multi-species ctest suite is separate from the single-species suite as the difference in templating would result in several test failures. As such, it is highly recommended that a multi-species version of the code is built and tested alongside the single-species suite when making changes to the code. The Compute Canada Rorqual script has also been modified to reflect this and can be used as a reference when testing multi-species:

  if [ "${RUN_CTEST}" = true ]; then
      ctest
    ## Build and verify multi-species implementation as well
    mkdir ${SLURM_TMPDIR}/build_multispecies
    cd ${SLURM_TMPDIR}/build_multispecies
    cmake -DDEAL_II_DIR=$DEAL_II_DIR ../PHiLiP -DMPIMAX=${NUM_PROCS} -DCMAKE_BUILD_TYPE=Release -DNUMBER_OF_SPECIES=2 -DGMSH_DIR=$GMSH_DIR/bin/gmsh -DGMSH_LIB=$GMSH_DIR -DCMAKE_SKIP_INSTALL_RPATH=ON
    make -j${NUM_PROCS}
    ctest
  fi

Debugging

Please consult the debugging quick start guide for details concerning both serial and parallel debugging.

Performance

Please consult the performance inspection quick start guide for details concerning computational bottlenecks, memory leaks, and memory usage.

Contributing checklist

Please consult the contributing checklist for details concerning making a contribution.

License

The code is licensed under the GNU LGPLv2.1 due to the dependence on the deal.II library.