# Uni Rostock PyTorch Framework The `uros_pf` framework intents to reduce the setup time for new machine learning projects based on pytorch. It unifies standard procedures, such as configuring, input/output procedures, training, logging etc., that are used in all projects. ## Basic principles - Files in the `uros_pf` package are of general interest. They must not be adapted to a certain project. - Project specific source code goes into the `scenario` folder. - Data / configuration files / model checkpoints etc. are stored in a separate workdir folder. - To implement a new scenario at least 3 files have to be coded: the `input_processor` (preparing the input and targets) the `model` (connecting the trainer, optimizer and model) and the `module` (containing the neural network or the ML-method) - The input processor, the model and all hyperparameter shall be configured by the config file (a `yaml`-file). It is usually stored in the workdir and passed to the trainer by `-cn config_name` (`config_name` without extension `.yaml`). ## Sample project A working configuration file (named `ag_linear_config.yaml`) is ```yaml hydra: run: dir: ${trainer.model_path} builder: input: "scenario.ag_news_corpus.ag_ip.AGInputProcessor" model: "scenario.ag_news_corpus.ag_simple_model.SimpleModel" trainer: epochs: 20 model_path: models/${now:%Y-%m-%d}/${now:%H-%M-%S} input: feature_size: 1000 train_file: "data/ag_news_corpus/train.csv" val_file: "data/ag_news_corpus/test.csv" batch_size: 10 samples_per_epoch: 12000 model: num_of_classes: 4 loss_fn: "torch.nn.MSELoss" metric_fns: "uros_pf.metrics.accuracy.Accuracy" module_cls: "scenario.ag_news_corpus.ag_least_square_module.AGLeastSquareModule" optimizer: "torch.optim.SGD" lr: 0.01 module: feature_size: ${input.feature_size} num_of_classes: ${model.num_of_classes} ``` The structure of the workdir is: ```commandline ├── data │ ├── ag_news_corpus │ │ ├── test.csv │ │ ├── train.csv ├── config │ ├── ag_linear_config.yaml ``` whereas the data is taken from [mhjabreel's github account](https://github.com/mhjabreel/CharCnn_Keras/tree/master/data/ag_news_csv). To run the example project just execute `python3 path/to/src/uros_pf/trainer/trainer.py -cn ag_linear_config` from the workdir. ## Install ### Ubuntu / Debian Open a terminal and execute the following command lines while substituting `path/2/virtual/environment` and `path/to/project/dir` with your own folders. ```commandline sudo apt-get update sudo apt install python3-venv python3-pip ENV_HOME=path/2/virtual/environment python3 -m venv $ENV_HOME source $ENV_HOME/bin/activate pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu pip install tensorboard transformers[torch] evaluate datasets scikit-learn tokenizers tqdm pip install hydra-core --upgrade ``` To install the project framework and the Pycharm environment download and install PyCharm from https://www.jetbrains.com/de-de/pycharm/download/other.html and run: ``` cd path/to/project/dir git clone https://citlab0.math.uni-rostock.de/gitlab/shared/uros_pf ``` (tested with Ubuntu 23.04) ### Windows #### Voraussetzungen - Betriebssystem: Windows 7, 8, 10 oder 11 (64bit) - Prozessor: x86-Prozessorarchitektur (keine ARM-Unterstützung) - Festplatte: 5GB freier Speicherplatz #### Generelles Im Workshop wird Python (3.11) als Programmiersprache und werden zahlreiche in Python geschriebene Module verwendet, die über den Python-eigenen Paketmanager **pip** bezogen werden. Um all das spezifisch für die Zwecke des Workshops auf deinem System zu installieren, ohne in Konflikt mit womöglich schon vorhandenen oder später einmal zu installierenden Python- und Modul-Versionen zu kommen, verwenden wir auf Windows-Systemen **Anaconda** (genauer: die minimierte Variante **Miniconda**). Mit dieser Software ist es möglich, voneinander unabhängige Python-Installationen in sogenannten **virtuellen Umgebungen** zu betreiben. Solltest du also im Nachgang zu diesem Workshop eigene Projekte mit anderen Python-Versionen, -Modulen oder -Modulversionen anlegen wollen, ist dies mit Anaconda problemlos möglich. Als Code-Editor verwenden wir **PyCharm**, das verschiedene Hilfsmittel für die Entwicklung von Python-Programmen bietet. #### Schritt für Schritt ##### Virtuelle Umgebung 1. Installiere [Miniconda](https://docs.conda.io/en/latest/miniconda.html#windows-installers): Benutze dafür den Installer für Windows 64bit-Systeme. Wähle im Installationsprozess die vorgeschlagenen Standard-Einstellungen. Sollte nach der Installation keine Verknüpfung mit dem Anaconda-Prompt (der Anaconda-eigenen Eingabeaufforderung) auf dem Desktop angelegt worden sein, lege selbst eine an: Erzeuge eine neue Verknüpfung mit dem Ziel `cmd /c start "Anaconda Prompt" "C:\path\to\Miniconda3\Scripts\activate"`, wobei `C:\path\to\` durch den korrekten Pfad zur Miniconda-Installation ersetzt werden muss. 2. Erweitere die Quellen, auf die Miniconda zugreifen kann, um Software in virtuelle Umgebungen zu installieren: Anaconda hat standardmäßig häufig nur Zugriff auf ältere Versionen von Softwarepaketen. Um den Umfang zu erweitern, fügen wir mit **Conda-Forge** eine weitere, von der Community gepflegte Quelle hinzu. Öffne dazu den Anaconda-Prompt und tippe ein: `conda config --add channels conda-forge`. Conda-Forge sollte nun in der Liste der Channels zum Bezug von Softwarepaketen eingetragen sein: `conda config --show channels`. 3. Erzeuge eine neue virtuelle Umgebung: Im Anaconda-Prompt sollte vor dem Cursor das Präfix `(base)` in der Zeile zu sehen sein, was bedeutet, dass du dich aktuell in der Basis-Umgebung von Anaconda befindest. Zum Erzeugen der neuen Umgebung, gebe ein: `conda create -n llm_workshop python=3.11 git`. Du kannst `llm_workshop` mit einem Namen deiner Wahl ersetzen. 4. Aktiviere die neue virtuelle Umgebung: `conda activate llm_workshop`. Solltest du einmal den Namen der Umgebung vergessen haben oder eine Übersicht über alle angelegte virtuelle Umgebungen sehen wollen: `conda env list`. 5. Aktualisiere die mit Python installierten Pakete *pip* und *setuptools*: `python -m pip install -U pip && pip install -U setuptools`. 6. Installiere die für den Workshop benötigten Python-Module: `pip install torch torchvision torchaudio transformers[torch] tensorboard evaluate datasets scikit-learn notebook hydra-core --upgrade`. ##### Workshop-Ordner und Repository 7. Lege auf deinem System einen Workshop-Ordner an. Wechsle im Anaconda-Prompt in diesen Workshop-Ordner. 8. Klone das Workshop-Repository in den Workshop-Ordner: `git clone https://citlab0.math.uni-rostock.de/gitlab/shared/uros_pf.git`. 9. Lege im Workshop-Ordner den Ordner `workdir` an, so dass jetzt insgesamt zwei Ordner sich im Workshop-Ordner befinden sollten: `workdir` und `uros_pf`. In `workdir` werden wir Daten, Konfigurationen und Modelle speichern. ##### PyCharm 10. Installiere [PyCharm](https://www.jetbrains.com/de-de/pycharm/download/other.html) (Community-Version 2023.2.1 für Windows). 11. Starte PyCharm und öffne den Repository-Ordner `uros_pf` im Workshop-Ordner: Klicke auf das Hauptmenü-Symbol oben links, klicke auf `Open` und wähle den Repository-Ordner aus. Beantworte die folgende Sicherheitsabfrage mit `Trust Project`. 12. Aktiviere deine virtuelle Umgebung in PyCharm: PyCharm kann nun die bereits von uns in Punkt 3 erzeugte virtuelle Umgebung als Arbeitsumgebung und damit auch den darin enthaltenen Python 3.11-Interpreter nutzen. Klicke dafür rechts unten auf die Auswahl des Python Interpreters. Sollte hier deine Miniconda-Umgebung noch nicht zur Auswahl stehen, wähle `Add New Interpreter` und anschließend `Add Local Interpreter`. In der nun geöffneten Anzeige `Add Python Interpreter` wähle als Typ links `Conda Environment`. Gebe anschließend rechts den Pfad zur `conda.exe` deiner Miniconda-Installation ein: `C:\path\to\Miniconda3\Scripts\conda.exe`. Aktiviere anschließend `Use existing environment` und wähle im Dropdown-Menü deine virtuelle Umgebung aus, die nun im Dropdown-Menü zu finden sein sollte. Bestätigte mit `OK`. Nun kann PyCharm die Python-Module nutzen, die du in Punkt 6 in die virtuelle Umgebung installiert hast.