Setting Up Windows Subsystem for Linux (WSL)#
If you would like to use Linux on a Windows machine, you can set up the Windows Subsystem for Linux (WSL). This allows you to run a Linux distribution in parallel to your regular Windows environment. Compared to a dual-boot setup or virtual machine, WSL is more lightweight and integrates well with a number of IDEs. It is primarily based on the command-line, although you can also run graphical applications.
In the context of Tudat(Py), having a Linux environment is required as of v0.9, as no more Windows conda packages are provided.
Installing WSL#
Important
Before you start, make sure that the Windows Subsystem for Linux (WSL) feature is enabled on your Windows machine.
To check this, open the Control Panel -> Programs -> Programs and Features -> “Turn Windows features on or off” and make sure that the Windows Subsystem for Linux feature is enabled.
Follow the installation guide on the Microsoft website to install WSL.
By default, this will install Ubuntu as a Linux distribution. This is a common choice and recommended for beginners as you will find plenty of support, but you can also install other distributions.
Note
If you run into any issues during the installation, you can find help in the WSL troubleshooting guide.
Setting up WSL#
In the following steps, we will assume that you have installed Ubuntu as your Linux distribution. Other distributions may have slightly different steps.
After installing WSL, open Ubuntu from the start menu and follow the instructions to set up your Linux distribution.
You can now run Linux commands in the terminal. For example, you can check the installed Ubuntu version by typing
lsb_release -a
This should return something like the following:
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 20.04.2 LTS
Release: 20.04
Codename: focal
Tip
If this is your first time using a Linux environment, take a look at the Linux and Bash tutorial in the WSL documentation or the Linux command line basics tutorial for a more extensive background.
In short, some basic commands you might need to know are:
ls
to list files in a directory,cd my_directory/
to change directories to the directory calledmy_directory
, usecd ..
to go up one directory,mkdir new_directory
to create (make) a new directory callednew_directory
,rm old_file.txt
to remove the file calledold_file.txt
,cat environment.yaml
to display the contents of the fileenvironment.yaml
,sudo
to run a command as an administrator,apt-get
to install packages.
Update your package list and upgrade your packages by running the following commands:
sudo apt-get update && sudo apt-get upgrade
Using WSL with Windows#
To access your Windows files from the Linux environment, you can navigate to
/mnt/c/
in the terminal. This is where your Windows files are mounted and accessible from inside Linux.To access the Linux files from Windows, you can navigate to
\\wsl$\
in the file explorer.You can also access the Linux environment from the Windows terminal by running
wsl
.To access the Linux environment from the Windows file explorer, you can run
explorer.exe .
in the Linux terminal.
Tip
While it is possible to access files stored in the Windows environment from within WSL (and vice-versa), it is not recommended! Instead, store your files in the environment you are planning to use them in.
In any case, make sure you have backups of your files in case something goes wrong! If something goes wrong, it will be in the worst moment possible. Don’t ask how we know 🤐
Preparing WSL to use Tudat(Py)#
In principle, you are now ready to use WSL. However, you might want to install some additional packages to make your life easier.
Install Conda#
Tudat(Py) uses Conda to manage its dependencies. If you have used Conda before in your Windows environment, you will still have to install it in your WSL environment. As we will mainly use the command-line in WSL, Miniconda is recommended. The instructions in the following are based on the official Anaconda documentation.
Open the terminal in WSL and download the latest Miniconda installer by running:
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
Install Miniconda by running the following command in the same directory:
bash Miniconda3-latest-Linux-x86_64.sh
Read through the Terms of Service and accept them.
In the next step, it is recommended to install Miniconda in the default location.
In the final step, you can configure the initialization of conda. It is recommended to add conda to your PATH, but not activate the base environment automatically upon opening a new terminal, to avoid accidentally installing packages in the base environment.
You can configure this by typing
yes
when prompted for the initialization option. Then, restart your terminal and run the following command:conda config --set auto_activate_base false
Next time you open a terminal, the
base
environment will not be activated. You can activate any environment by runningconda activate <ENVIRONMENT_NAME>
.Lastly, make sure that conda is installed correctly by running:
conda --version
This should return the installed Conda version.
From there on, you can follow the instructions in the Conda primer to set up your Conda environment and install Tudat(Py).
Quick TudatPy installation
In case you want to install TudatPy quickly, you can run the following commands from inside your WSL environment:
Download environment.yaml
file inside your WSL environment:
wget https://raw.githubusercontent.com/tudat-team/tudat-space/refs/heads/develop/docs/source/_src_getting_started/_static/environment.yaml
Create a new Conda environment from the environment.yaml
file:
conda env create -f environment.yaml
Activate the new Conda environment:
conda activate tudat-space
For more information on the installation and issues you might encounter, see the installation page.
Setting up an IDE#
As mentioned before, WSL is primarily based on the command-line. While you can run graphical applications, it is not recommended to run a full-fledged IDE in WSL. Instead, you can use an IDE on your Windows machine and connect it to the WSL environment. If you have a preference for a specific IDE, have a look if it supports WSL.
In the following, two options will be presented: PyCharm and Visual Studio Code.
Setting up PyCharm#
Warning
At the time of writing, only the PyCharm Professional version but not the Community version supports WSL natively. As a student you can get a free license for the Professional version. If you do not have access to the Professional version, Visual Studio Code is a good alternative.
In the following, it is assumed that you have installed PyCharm Professional and have a Conda environment set up in WSL. See also the PyCharm documentation.
To connect PyCharm to your WSL environment and set it up for TudatPy, follow these steps:
Open PyCharm and create a new project inside WSL.
Choose your WSL instance in the following dialog (Ubuntu by default).
If you haven’t done so already, create a new project directory. Make sure that the project path starts with
\\wsl$\
, indicating that your project is stored in the WSL environment.Click
OK
andStart IDE and Connect
to open your project. This might take some time, as the JetBrains client is downloaded.Finally, we can set up the Conda environment in PyCharm. Click on the Python version and add a new interpreter on WSL:
After the introspection was successful, click next and select the Conda environment you want to use. For TudatPy, you should select the Conda environment you created in the WSL environment.
You are now ready to use PyCharm with your WSL environment. Make sure to follow the last step to setup Git in the WSL environment.
Setting up Visual Studio Code#
Visual Studio Code (VS Code) is freely available and supports WSL using official extensions.
To connect VS Code to your WSL environment and set it up for TudatPy, follow these steps:
If you haven’t done so already, install VS Code from the official website.
Open VS Code and install the Remote - WSL extension by Microsoft. You can also search for the extension in the Extensions tab in VS Code.
Remote - WSL: Identifier
ms-vscode-remote.remote-wsl
Open the command palette by pressing
Ctrl+Shift+P
and typeWSL: Connect to WSL
. You should now see being connected to your WSL environment.Alternatively, you can also navigate from the command line to your project directory and type
code .
. This will open VS Code directly in the WSL environment. In this case, you can skip the next step.Open your project folder in VS Code.
Install the Python extension by Microsoft. You can also use the identifier
ms-python.python
in the Extensions tab.Create a new Python file and select the Python interpreter. You should now see the Conda environment you set up in WSL.
You are now ready to use VS Code with your WSL environment. Make sure to follow the last step to setup Git in the WSL environment. For more information on how to use VS Code with WSL, see the official documentation.
Setting up Git#
Lastly, you will likely want to use source control for your projects. In order to use Git in WSL, you will have to install it inside your Linux environment, even if you have installed it previously in your Windows environment. Follow the setup instructions by Microsoft, in particular the setup instructions of the Git Credential Manager.
Next steps#
Congratulations! You are now all set to use WSL with Tudat(Py). If you would like to learn more about how to use the Tudat source code, which is written in C++, have a look at the Using the Tudat source code page. You can also make use of your new environment to contribute to the Tudat project on GitHub, see this page for more information.