Quickstart tutorial
Download and install Idefix
One first need to download Idefix from the public git. Say you want to install Idefix in the directory ~/src/idefix
, you need to run:
cd ~/src
git clone https://<yourFavouriteIdefixRepo> idefix
cd idefix
git submodule init
git submodule update
Note that the idefix
directory is automatically created by git clone
. Because Kokkos is embedded as a submodule of Idefix, the last two lines will download Kokkos for you and put it
at the right place.
The configuration and compilation of Idefix relies on the environement variable $IDEFIX_DIR
, which should point to the
install directory of Idefix. We therefore conclude the installation with:
export IDEFIX_DIR=~/src/idefix
Tip
The IDEFIX_DIR
environment variable can also be set in the .profile
file of your home directory so that it is automatically set
when you launch a terminal
Configure and run the SOD tube test problem
The test problem are all located in the $IDEFIX_DIR/test
directory of the distribution. To access the Sod shock tube test, one go to:
cd $IDEFIX_DIR/test/HD/sod
From there, one sees 3 files and a directory:
definitions.hpp
The configuration file. It contains C preprocessor directives for configuration options which require a re-compilation of the code. These are mostly the number of vector components, the number of dimensions of the problem, the geometry, etc.
setup.cpp
The physical setup definition. Its role is to define the initial conditions of the problem, but also to provide functions for user-defined properties (boundary conditions, diffusivity, potential, etc.)
idefix.ini
The input file. This file is read at runtime only. It defines most of the properties of the code: resolution, integrator, output, physical modules.
python
directoryThis directory is provided with most of the tests. Its content allows one to check that the code output is consistent with what is expected.
For the time being, the files are already set up for the Sod test problem. The only thing lacking is a makefile
to actually compile the code.
In Idefix the makefile is created by Cmake ,a tool to control code generation on diverse platforms. To configure Idefix,
you need Cmake version >=3.16 installed on your machine. For this quickstart, let us configure the code to run on
the cpu in serial (default behaviour). Assuming a cmake
is in the PATH, we simply type in:
cmake $IDEFIX_DIR
which automatically setups a build tree from the sources in $IDEFIX_DIR using the setup in the current directory.
Tip
If you want to use a specific C++ compiler which is not the default one on your configuration, you can add the -D CMAKE_CXX_COMPILER=foo
option to cmake.
Finally, we compile and run the code:
make -j 8
./idefix
This test being one dimensional, it runs very fast. We can check that the final solution match the prediction of the shock tube problem. To this end, we go to the python
subdirectory and run the test:
cd python
python3 ./testidefix.py
If everything goes well, testidefix.py
will load the latest output produced by idefix, display it, compare it with an analytical solution and tell you
whether the error is acceptable or not.
Configure and run the Orszag-Tang test problem
The Orszag-Tang problem is a well known test problem for MHD codes. The configuration for this test may be found in:
cd $IDEFIX_DIR/test/MHD/OrszagTang
As in the Sod test problem, there are 3 files in that directory which completely define the Orszag Tang test problem. We now need to configure the test with:
cmake $IDEFIX_DIR
Once the code is configured, it can be ran:
./idefix
This test can take much more time that the sod test since it is 2D. In the end, you can visualize the results, which are written as VTK files using
Paraview of Visit. As in the Sod tube test, a python/testidefix.py
script is provided
to check that the last output is consistent with the reference output.
Tip
Given that the Orszag-Tang test can take a long time, you may want to accelerate your computation with a little bit of parallelisation. This can be done with openmp (assuming you have an openmp-compatible compiler):
cmake $IDEFIX_DIR -DKokkos_ENABLE_OPENMP=ON
make -j 8
export OMP_NUM_THREADS=4
./idefix
or assuming a MPI library is installed on your machine:
cmake $IDEFIX_DIR -DIdefix_MPI=ON
make -j 8
mpirun -np 4 ./idefix
In both cases, this will run the Orszag-Tang test with 4 threads/processes.