Windows with WSL#

../_images/windows.png

Important

Distributions compatibility: Windows 10 and Windows 11

See also

This tutorial is aimed at Windows users who have no prior knowledge of Linux. To keep it simple, all dependencies are installed using candi. Installation options given in this tutorial are well suited for lethe users. If you are a developer or need more options, see Regular Installation on Linux.

Throughout this tutorial:

  • win_shell indicates operations performed in the Windows session, and

  • linux_shell indicates operations performed in the Linux subsystem.

Tip

To execute a command on a shell (Ubuntu or Windows command prompt), type or copy/paste the given command and hit Enter. Multiple commands are given in multiple lines, or separated by ;: when copying/pasting, they will be executed one after the other.

Installing WSL and Ubuntu (Step #0)#

  1. win_shell Install WSL (Windows Subsystem for Linux). Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting “Run as administrator”, enter the wsl –install command, then restart your machine.

wsl --install

  1. win_shell Enable WSL and Ubuntu 22.04 LTS from the microsoft store, following the steps indicated in this tutorial

Verify the installed version of WSL

In the windows command prompt (Start menu > cmd):

wsl -l -v

should indicate version 2. If not, follow this to update WSL: https://docs.microsoft.com/fr-fr/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2

  1. win_shell Launch Ubuntu (from the start menu) and linux_shell update Ubuntu:

sudo apt update
sudo apt upgrade

Tip

The sudo command will ask you to type your user password, as defined during Ubuntu installation. Note that Linux does not show any symbol while typing a password, contrary to Windows with *: simply type your password and press Enter.

When prompted “do you want to continue?”, proceed by typing y and hitting Enter.

  1. win_shell (optional) To activate copy/paste in the Linux sub-terminal (tutorial with screenshots):

  • right-click on the Ubuntu Window pane header

  • in Properties, select Use Ctrl+Shift+C/V as Copy/Paste

  • you can then use Ctrl+Shift+V to paste text or commands in the Linux sub-terminal

  1. win_shell (optional) For better ease in the Linux terminal (better coloring, multiple tabs), change the default terminal:

  • in the microsoft store, download Windows Terminal

  • in the parameters of Windows Terminal, select on the left panel “start”: change default profile with Ubuntu-22.04

  • from now on, you can use this application instead to launch Ubuntu terminal

Tip

A (very) few Linux commands useful for navigation:

  • mkdir $dir: (make directory) create a directory with the name specified as $dir

  • cd $dir: (change directory) move to the directory $dir

  • cd ..: move up to the parent directory

  • pwd: (print working directory) return the directory you are in

  • cd $HOME: move to your home directory (/home/<user_name>/)

You can find here a thorough guide for the most basic Linux commands.

The following step is to install deal.II. This can be done through

  1. Advanced Packaging Tool (apt) (this is by far the easiest way to proceed) : Installing deal.II using apt (Step #1) (recommended for users)

  2. Candi shell script (candi github page): Installing deal.II using Candi (Step #1) (recommended for developers)

Installing deal.II using apt (Step #1)#

This is done following this procedure.

  1. linux_shell In case you are using Ubuntu, you will need to update the backports:

sudo add-apt-repository ppa:ginggs/deal.ii-9.5.1-backports
sudo apt update

  1. linux_shell A dependency required by Lethe, and that deal.II needs to be compiled with, is muParser:

sudo apt-get install libmuparser-dev

  1. linux_shell To install deal.II, run:

sudo apt-get install libdeal.ii-dev

To verify if the correct version of deal.II is installed, run:

apt show libdeal.ii-dev

This should output several information about the installed version. Everything worked as expected if deal.ii-9.5.1 is output

Note

If the installed version is other than deal.ii-9.5.1, follow this link.

Installing deal.II using Candi (Step #1)#

Important

This step is by far the most troublesome in all Lethe installation. Read and follow each step carefully.

  1. linux_shell Install candi required packages:

sudo apt-get install lsb-release git subversion wget \
bc libgmp-dev build-essential autoconf automake cmake \
libtool gfortran libboost-all-dev zlib1g-dev openmpi-bin \
openmpi-common libopenmpi-dev libblas3 libblas-dev \
liblapack3 liblapack-dev libsuitesparse-dev libmuparser-dev

Tip

The symbols \ indicate that this a single command written on multiple lines.

  1. linux_shell Install compilers:

sudo apt-get install gcc-10 g++-10 gfortran-10

Check the default version of the compilers

In the Ubuntu terminal:

gcc --version

should return gcc (Ubuntu 10.X.X...) 10.X.X or higher. If not, go to Change Compiler Default Version.

  1. linux_shell Create folders (suggested structure):

mkdir Software; cd Software
mkdir candi; cd candi

Note the use of ; which enable to serialize operations on a single execution line.

  1. linux_shell Download candi:

git clone https://github.com/dealii/candi.git .

Do not forget the . at the end of the command, which means “here”.

  1. win_shell Modify installation parameters (deal.II version and trilinos version):

  • open Windows file manager, and on the left panel (along with Files, Computer etc.) click on the Ubuntu mount.

Tip

If you do not see any Ubuntu mount, use this alternative method: Modify Candi Installation Parameters with Nano.

  • navigate to reach the candi folder, in: /home/<user_name>/Software/candi

  • open the candi.cfg file with notepad (or other text editor) and change the following lines:

line #

initial line

changed line

7

CLEAN_BUILD=OFF

CLEAN_BUILD=ON

86

# PACKAGES="${PACKAGES} once:netcdf"

PACKAGES="${PACKAGES} once:netcdf"

97

DEAL_II_VERSION=v9.5.0

DEAL_II_VERSION=master

  • save and close

  • navigate to reach the following subfolder: deal.II-toolchain/packages/

  • open the trilinos.package file with notepad and change the following lines:

Tip

The prefix # is used to comment a line. Here we are simply commenting lines 44 and 45, and uncommenting lines 50 and 51, to change the trilinos version.

line #

initial line

changed line

44

VERSION=12-18-1

#VERSION=12-18-1

45

CHECKSUM=9c1d151169949bca6cf203831e4d6aee

#CHECKSUM=9c1d151169949bca6cf203831e4d6aee

50

#VERSION=12-12-1

VERSION=12-12-1

51

#CHECKSUM=ecd4606fa332212433c98bf950a69cc7

CHECKSUM=ecd4606fa332212433c98bf950a69cc7

  • save and close

  • To ensure that the Lethe test suite works, deal.II must be configured with p4est version 2.3.6, the current default candi version of p4est. Otherwise, application tests that include restart files will fail.

  1. linux_shell Still in the candi subfolder, run candi installation script:

./candi.sh -j$numprocs
Where $numprocs corresponds to the number of processors used for the compilation:

  • if you have less than 8Gb of RAM, use 2 procs: ./candi.sh -j2

  • if you have 16Gb of RAM and above, $numprocs can be the number of physical cores minus 1. For instance, for a computer with 6 physical cores: ./candi.sh -j5

Tip

Candi will print messages asking you if you installed the dependency. Hit Enter two times to validate and the installation will launch. If new lines are written in the console, this means the installation is going on correctly. The installation will take from 1 to 3 hours depending on your hardware.

If the installation is stuck (no change on the console for a few minutes), hitting Enter can unstuck it.

You can exit the installation at any time hitting Ctrl+C 2-3 times.

  1. win_shell At the end of the installation, check that you have deal.II and its dependencies installed:

  • on Windows file manager, go to the Ubuntu mount

  • in home/<user_name> you should have a folder deal.ii-candi, or dealii-candi

  • inside this folder, you should have folders for the dependencies, namely: p4est, petsc, parmetis, trilinos

  • you should also see this folder: deal.II-master

  1. linux_shell Add a deal.II environment variable in Ubuntu through the following command:

echo "export DEAL_II_DIR=$HOME/dealii-candi/deal.II-master" >> ~/.bashrc

Note

Even if we use a echo command, nothing will be outputted in the terminal: the text is written directly at the end the .bashrc file.

Warning

For this change to be effective, you may need to restart your Ubuntu terminal.

Installing Lethe (Step #2)#

  1. linux_shell Set-up the folder structure. Create the Software folder (if you are doing the candi installation, this folder should already exist from Step #1).

mkdir Software; cd Software

In the Software folder created (if you are in the candi folder, type cd ..), type:

mkdir -p lethe/{git,build,inst}

After installation is complete, the folder structure will be:

  • lethe/git with lethe downloaded files (git),

  • lethe/build for compilation files (cmake command),

  • lethe/inst for installation files (make install command).

  1. linux_shell Download lethe:

cd lethe
git clone https://github.com/chaos-polymtl/lethe --single-branch

  1. linux_shell Build lethe:

cd build
cmake ../lethe -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../inst/

  1. linux_shell Compile lethe:

make -j$numprocs
Where $numprocs corresponds to the number of processors used for the compilation:

  • if you have less than 8Gb of RAM, use 1 to 2 procs: make -j1 or make -j2

  • if you have 16Gb of RAM and above, $numprocs can be the number of physical cores minus 1. For instance, for a computer with 6 physical cores: make -j5

  1. linux_shell (optional) Finally, it is recommended to test your installation:

Run the tests in the build folder:

ctest -j$numprocs

This will take from a few minutes to an hour, depending on your hardware. At the end, you should have this message on the console:

100% tests passed

Note

If you are running these tests for the first time, install numdiff (if you need superuser privilege, use sudo):

apt-get numdiff

or

apt install numdiff

Warning

The lethe test suites requires that deal.II be configured with p4est 2.2.1, otherwise the test which include restart files will fail.

Congratulations, you are now ready to use lethe! For instance, proceed to Launching Your First Simulation.

Updating deal.II and Lethe#

If you have already installed deal.II and lethe, you can update them without doing the entire installation from scratch:

Through apt#

  1. linux_shell As all other apt packages, run:

sudo apt update
sudo apt upgrade -y

  1. linux_shell Then, update lethe:

cd ../lethe/git
git pull
cd ../build
cmake ../git -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../inst/
make -j$numprocs

With Candi#

  1. linux_shell Update deal.ii by typing, from your home directory:

cd Software/candi
./candi.sh -j$numprocs

  1. linux_shell Then, update lethe:

cd ../lethe/git
git pull
cd ../build
cmake ../git -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../inst/
make -j$numprocs

Troubleshooting#

Change Compiler Default Version#

linux_shell After you installed gcc-10, g++-10 and gfortran-10, manually update default versions in the terminal:

sudo update-alternatives --remove-all gcc
sudo update-alternatives --remove-all g++
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10
sudo update-alternatives --set cc /usr/bin/gcc
sudo update-alternatives --set c++ /usr/bin/g++

Then, check again the version used:

gcc --version

Should return gcc (Ubuntu 10.X.X...) 10.X.X.

Modify Candi Installation Parameters with Nano#

linux_shell If you do not see the Ubuntu mount in the Windows file manager, you can modify the candi parameter files in the Ubuntu terminal directly.

Note

You cannot click, so use the keyboard arrows to move inside the text.

  1. Open the desired file in the terminal with nano (built-in text editor):

cd <folder_name>
nano <file_name>

Example for the candi.cfg

cd /home/<user_name>/Software/candi
nano candi.cfg

  1. Modify the text in the file, using only the keyboard.

  2. Save the file:

  • hit Ctrl + X

  • a prompt will appear at the bottom of the terminal asking Save modified buffer?

  • confirm by hitting y

  • a prompt will appear at the bottom of the terminal to recall the file name

  • hit Enter to confirm

  • the file will be closed automatically and you will be back on the Ubuntu terminal