{% import macros as m with context %} .. _installation: Installation ================================================= .. tip:: :class: margin - Don't be discouraged if everything does not install in the first go. Use :fab:`discord` `Discord <{{ discord }}>`__ (`invitation link <{{ discord_invite }}>`__) and the TAs to get help. {{ m.embed('install', 'Installation instructions for windows', False) }} {# .. warning:: :class: margin Python 3.12 is not yet officially supported by libraries we use such as pytorch and gymnasium, however, it seems to work well enough now. #} This course supports the following python versions: .. note:: :class: margin All tests are known to work for the supported python versions. However, problems are often specific to certain computers/operating systems. Don't worry, all problems should be fixable! - :guilabel:`Python 3.8` - :guilabel:`Python 3.9` - :guilabel:`Python 3.10` - :guilabel:`Python 3.11` :bdg-success:`Recommended` - :guilabel:`Python 3.12` {# :bdg-danger:`Experimental` #} (see :ref:`python312`) Step 1: Install an IDE ----------------------------------------------------------------------------------------------------------------------- .. note:: :class: margin I would **not** recommend Spyder. It is both janky and underpowered. An IDE is the tool we use to edit code. I personally use Pycharm (see :ref:`pycharm` if you wish to use Pycharm), but VS Code is a little more popular at DTU, so therefore I will provide instructions for VS Code. .. tabs:: .. tab:: Windows - Download and install VS Code from ``__ - Use the default settings during install - Don't install python if VS Code suggests that you do so .. tab:: MacOS Full details available from: ``__. - Download Visual Studio Code for macOS from ``__. - Open the browser's download list and locate the downloaded app or archive. - If VS Code was downloaded a :file:`.zip`-file, extract the archive contents. Use double-click for some browsers or select the 'magnifying glass' icon with Safari. - Drag :file:`Visual Studio Code.app` to the :guilabel:`Applications` folder, making it available in the macOS Launchpad. - Open VS Code from the :guilabel:`Applications folder`, by double clicking the icon. - Add VS Code to your Dock by right-clicking on the icon, located in the Dock, to bring up the context menu and choosing :guilabel:`Options, Keep in Dock`. .. tab:: Linux On Ubuntu the simplest way is to use :guilabel:`snap`: .. code-block:: bash sudo apt install snap sudo snap install --classic code For additional distribution-specific instructions please see ``__. .. admonition:: Need help? If you run into issues following the instruction guide, you can get help from the Python support. :Python support: `pythonsupport.dtu.dk `__ .. _extension: Step 2: Install the Python extension for VS Code -------------------------------------------------------------------------------------------------------------- To enable Python support in VS Code, you must install the Python extension. To do this: - From the :ref:`activity bar `, click on the icon with the four boxes indicated in :ref:`the screenshot `. - This will open a pane. Type **python** in the search field and hit :kbd:`enter` - Install the :guilabel:`Python` extension (top most search hit). It will have :guilabel:`Microsoft` as publisher. .. _getsource: Step 3: Get the course software and exercises -------------------------------------------------------------------------------------------------------------- .. warning:: :class: margin You can put the :file:`02465students`-folder any place you like, but once you have completed the following steps you should **not move or rename** the folder for the remainder of the course, as this will confuse Python. To get started, you must first download the course folder to your computer: .. tabs:: .. tab:: Download as a :bash:`zip`-file You can download the folder as a :bash:`zip`-file: - ``__. - Extract the :bash:`zip`-archive to the location your normally store course material. - **Optionally:** rename the folder :file:`02465students-master` to :file:`02465students` .. tab:: Download using :bash:`git` Git is the de-facto standard for source management and collaboration. Although it is not needed for this course, familiarizing yourself with git will be a valuable skill you will likely use throughout your studies and career. To clone the repository using git, use this command: .. code-block:: bash git clone https://lab.compute.dtu.dk/02465material/02465students.git .. note:: If you don't have git, you can download it from: ``_. Accept the recommended default settings during install (on Linux, run :bash:`sudo apt install git`) You should end up with a folder called: :file:`02465students` containing the source code. .. _installpython: Step 4: Install Python --------------------------------------------------------------------------------------------------------------------------- .. note:: :class: margin I recommend Anaconda for windows. Anaconda will automatically install the program called :guilabel:`swig` (which is required for gymnasium) and that will save you some troubles. If you don't like anaconda, you can install swig manually on windows (use google to find instructions), and you can use anaconda on macos or Linux if you prefer. To run Python files, you must have a *Python interpreter* installed. The interpreter is responsible for actually running your programs. .. tabs:: .. tab:: Windows Download and install **Miniconda** from `https://docs.conda.io/en/latest/miniconda.html `__. **Important:** - Make sure to **check** :fa:`check-circle` the option :guilabel:`For this user only` when prompted Then next time you are prompted: - Make sure to **check** :fa:`check-square` the option :guilabel:`Add Miniconda to my PATH variable` - Make sure to **check** :fa:`check-square` the option :guilabel:`Register Miniconda as my default python 3.11` .. tab:: MacOS - From the :ref:`VS Code terminal ` type .. code-block:: bash python3 --version - If you have Python installed, this will print out the version number. If it is between :bash:`Python 3.8` and :bash:`Python 3.11`. - Otherwise follow these instructions ``__. .. tab:: Linux (Most linux users) Since there are many linux distributions, you may have to google your way to a solution. However, on Ubuntu, first check if you have python by running: .. code-block:: bash python --version If the version is between 3.8 to 3.11 you should be fine. Otherwise run: .. code-block:: bash sudo apt install -y python3-pip python3.11 python-is-python3 Confirm that :bash:`python --version` works. .. tab:: New linux distributions (Ubuntu 23.04+) The latest linux distributions requires you to use a virtual environment. The steps are a little more complicated, but once you are done, it will not affect how Python works. First, install (or rather, make sure you have) a base version of Python: .. code-block:: bash sudo apt-get update sudo apt-get install python3-venv The virtual environment is a special folder which will contain a separate version of Python. I recommend installing it in your home folder for simplicity as follows: .. code-block:: bash python3 -m venv ~/venv Then whenever you need to use Python in a terminal, type the following: .. code-block:: bash source ~/venv/bin/activate and you can now use Python as normal. When you install packages, they will be put in the :file:`~/venv`-folder. When you install the course software in :guilabel:`VS Code`, you need to select the interpreter located at :file:`~/venv/bin/python`. .. _installpackages: Step 5: Install the course toolbox and software packages ----------------------------------------------------------------------------------------------------------------------------- - Start a new terminal using :menuselection:`Terminal --> New Terminal` - Navigate to the folder you created in the step :ref:`getsource` step, :file:`02465students` - You can display the current path of the terminal by typing :bash:`cd` (Windows) or :bash:`pwd` on (Mac/Linux). - You change to a subfolder by typing :bash:`cd name_of_the_folder`, or move one folder up by typing :bash:`cd ..`. - Check that you have navigated to the correct folder by verifying that it contains :file:`requirements_pip.txt`. - You can list which files are in the folder by typing :bash:`dir` (Windows) or :bash:`ls` (Mac/Linux). .. tabs:: .. tab:: Windows - See :ref:`conda` for more conda commands or `install conda in VS Code `__ which this guide is based on. - Create a new conda environment by running: .. code-block:: powershell conda create --name my_irlc_env python=3.11 # The name is up to you. - Select your environment in VS Code. To do this open the command pallet using :kbd:`ctrl+Shift+P`, type :guilabel:`Python: Select Interpreter`, and select your environment (:guilabel:`my_irlc_env`) from the list. If it does not appear, select :guilabel:`Enter interpreter path..` and navigate to it. - **important:** Open a new terminal using :menuselection:`Terminal --> New Terminal` - The new terminal should display the name of your environment :guilabel:`my_irlc_env` to the left. See step 5 of `install conda in VS Code `__. - Navigate to the :file:`02465students` folder and run: .. code-block:: powershell conda install -c conda-forge --file requirements_conda.txt pip install -r requirements_pip.txt .. tab:: Linux - Run these commands in the VS Code terminal: .. code-block:: bash sudo apt install swig python3-dev build-essential python3 -m pip install -r requirements_pip.txt python3 -m pip install -r requirements_conda.txt .. tab:: MacOS - Run these commands in the VS Code terminal: .. code-block:: bash brew install cmake brew install zlib brew install swig python3 -m pip install -r requirements_pip.txt python3 -m pip install -r requirements_conda.txt .. note:: If you don't have Brew, install it using this guide `https://brew.sh/ `__. Check the output when you run the install commands to see if they exit with an error. Many common problems can be solved using the `pythonsupport.dtu.dk `__ .. _updating: Making sure your files are up to date ----------------------------------------------------------------------------------------------------------------------------- {{ m.embed('https://panopto.dtu.dk/Panopto/Pages/Viewer.aspx?id=a04fef38-b830-40eb-9a96-b10301550c3d', 'Updating your files', False) }} Since the course is being renewed, I plan to release the exercise and project code during the course. I have written a small python script to update the files, :gitref:`../irlc/update_files.py`. You can run it like a normal file, or from the terminal: .. code-block:: bash python -m irlc.update_files .. note:: The file will check your version of the toolbox against the most recent version on gitlab. It will then - Replace any files you are missing - Overwrite the **tests** for the weekly exercises and projects It will **not** overwrite your solutions to the exercises and projects. If you may have changed a file and wish to reset it, just delete it from your computer and run :file:`update_files.py` to update. Known Issues ------------------------------------------------------------------------------------------------------------- Even though the installation worked for the TAs and me you might experience problems specific to your system. This guide will try to keep track of common problems and their solution Cannot find file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **You get an error such as:** .. code-block:: bash ModuleNotFoundError: No module named 'irlc.exam.midterm2023a.question_pid' First check that the file you are trying to run exists (in this case :file:`irlc/exam/midterm2023a/question_pid.py`). If this is the case, you probably have two copies of the :python:`irlc`-package, and the file is not located in the one you installed in :ref:`installpackages`. **Solution**: To check where you installed :python:`irlc`, run the following command from the VS Code terminal .. note:: :class: margin on MacOS, assuming you normally run programs with :bash:`python3`, use: :bash:`python3 -c"import irlc; print(irlc.__path__)"` .. code-block:: bash python -c"import irlc; print(irlc.__path__)" On my computer this will print out :python:`['/home/tuhe/Documents/02465students/irlc']`. Then make sure the file you are trying to run is located in this directory, i.e. as :file:`/home/tuhe/Documents/02465students/irlc/exam/midterm2023a/question_pid.py`. Windows ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **This application failed to start because it could not find or load the Qt platform plugin "windows"** Try these commands in the VS Code terminal: .. code-block:: bash pip uninstall pyqt5 conda install pyqt If this fail to work see `this thread `__. .. _pycharm: Appendix A: Setting up Pycharm -------------------------------------------------------------------------------------------------------- If you wish to use Pycharm instead of VSCode, this is how I recommend you set it up. - Install Pycharm community edition - Start pycharm and create a new project. The name can be anything you like such as *02465rl* - The root of the project can be anything -- we are going to fix that later. - Select the interpreter you installed. If you followed the above guides, it should probably be under :guilabel:`System interpreter` - Create project and wait for pycharm to load. Then open settings using :kbd:`ctrl+alt+s` (or use the file menu) - Under :guilabel:`project: ` select :guilabel:`Interpreter` - Check you got the main packages you installed such as gym. If not, select an interpreter from the list. If the python version you installed is not show, use ``show all`` from the dropdown and you can add/configure the one you installed - Under :guilabel:`project: ` select :guilabel:`Project structure` - Select :guilabel:`Add project root`. Navigate to and add the :guilabel:`02465students` folder. - again in the settings dialog, under :guilabel:`Tools` select :guilabel:`Python integrated tools`. Then change :guilabel:`Default test runner` to just :guilabel:`Unittest`. - You are now done. You should be able to run and debug files. Note that pycharm will not allow you to run files while it is indexing your packages (check progress bar in lower right corner) In case Pycharm runs your tests twice (and first time fails) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Recent versions of pycharm use something called Pytest to set up and evaluate the test. Pytest has a bug where it will run the same test twice but in a different way, leading the test to crash in the first go. A way to tell this has happened is to look at the error message and see if it mentions pytest near the beginning. The way to fix that is to disable pytest and use regular python :guilabel:`unittest` instead. This is easy: - Click :guilabel:`File` then :guilabel:`Settings..` - Click :guilabel:`Tools` and select :guilabel:`Python integrated tools` - From the dropbox :guilabel:`Default test runner` select :guilabel:`Unittest` (see screenshot) .. image:: ../../shared/figures/pycharm_testconf.png :width: 500 :alt: Selecting your test runner. This will mean new tests are no longer run by Pytest, but Pycharm has a habit of remembering previous run configurations so if the problem occurs again, go in the top-right corner, click the drop-down menu left of the run-button (see screenshot below) and select :guilabel:`Edit Configurations`. This will open a window with all configurations. From the menu on the left, find all configurations that mention tests, select them, and press the small minus sign to delete them -- don't worry if you delete one too many, pycharm will recreate them. (see screenshot) .. image:: ../../shared/figures/pycharm_testconf2.png :width: 500 :alt: Deleting bad configurations. .. _python312: Appendix B: Python 3.12 -------------------------------------------------------------------------------------------------------- Python 3.12 is the most recent version of python. **It is not yet officially supported by gymnasium, pygame and pytorch**, and therefore I recommend that you use python 3.11. If you still wish to use Python 3.12, you should first install the pre-release version of pytorch: .. code-block:: bash pip install --pre torch --index-url https://download.pytorch.org/whl/nightly/cpu and then follow the installation instructions for your system. Using this approach I can run all tests on python 3.12/Linux, but you might experience platform-specific problems where the only solution is to wait for python 3.12 support. .. _conda: Appendix C: Conda guide ------------------------------------------------------------------------------------------------------------- .. tip:: :class: margin Learn from my mistakes and get in the habit of using conda now and not later. It will save you hours down the line When starting a new project *or* course it is always recommended to create a new virtual environment. We do this to prevent dependency issues down the line when installing new packages. To create a new environment with a specific python version, do the following: .. code-block:: powershell conda create -n python= Recommended version :bash:`=3.10` Pick an appropriate name for the environment like: :bash:`=rl_control` Use the below command to see all current anaconda environments and where they are installed. The currently activated environment is marked with a ``*`` .. code-block:: powershell conda env list Then activate the newly created environment .. code-block:: powershell conda activate env_name In your terminal you should now see :bash:`(env_name)` in front of your current file path. The name given in the parenthesises are indicating the currently activated environment and is also the environmnet where packages will be installed when using :bash:`conda` (recommended) or :bash:`pip`. You can now continue with the provided installation guide. For vscode users ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To ensure that vscode uses the correct virtual conda environment you should always launch vscode from within the anaconda navigator (terminal). This is achieved by running code in the terminal. .. code-block:: powershell code If you wish to open vscode within a specific folder you can run .. code-block:: powershell code Use :bash:`code .` to launch vscode in the current working directly. Deleting environments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: :class: margin Thanks to Calle for contributing this guide! Since we are installing complete sets of libraries every time we create a new environment over time we may have a bunch of old environment taking up unnecessary space. To delete an environment run the following code: .. code-block:: powershell conda env delete If for some reason this command fails you can also delete the folder manually. Remember that you can use :bash:`conda env list` to show where conda has installed the environment.