From e6ea98728380a222459049987ddbb858464741d3 Mon Sep 17 00:00:00 2001
From: Marcin Chrzanowski <m@m-chrzan.xyz>
Date: Sat, 1 May 2021 15:18:02 +0200
Subject: Translate and improve README

---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 53 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 61d97b5..a4fd6cf 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,53 @@
-# GSN, zadanie 1
-
-Rozpoznawanie kształtów i ich liczebności.
-
-## Trenowanie
-
-Po każdym trenowaniu wygenerowany jest raport zawierający informacje na temat
-danego eksperymentu. Zawiera:
-
-* Opis sieci
-    * Warstwy
-    * Liczebność parametrów
-* Hiperparametry
-    * Learning rate
-    * Liczba epok
-    * Batch size
-    * Momentum i inne jeśli wykorzystane
-* Wykorzystane dane (w postaci opisu nałożonych augmentacji)
-* Metryki
-    * Loss per epoka dla danych testowych
-    * Loss per epoka dla danych treningowych
-    * Accuracy dla danych treningowych
+# Deep Neural Networks, Homework 1
+
+Recognizing and counting shapes.
+
+## Running experiments
+
+    python src/run.py configuration.yaml
+
+### Configuration
+
+We can specify various training scenarios via YAML files. This allows us to
+experiment with different network architectures and hyperparameters.
+
+The configuration should have the following fields:
+
+* `type`: one of `classification`, `counting-small`, `counting-large`, depending
+  on which problem we're attempting to train for. This controls:
+    * the size of the final output layer
+    * final transformation applied to output layer
+    * transformations applied to targets, if necessary
+    * the loss function used
+    * the accuracy metric used
+* `batch_norm` (defaults to `false`)
+* `dropout` (defaults to `false`): `false` or `p` parameter for dropout layers
+* `lr`
+* `epochs`
+* `batch_size`
+* `augmentations`: list of augmentation specifications to expand the dataset
+  with:
+    * `rotation` (defaults to 0): integer 0-3 specifying number of 90° rotations
+      to apply
+    * `vflip` (defaults to `false`)
+    * `hflip` (defaults to `false`)
+* `convolutions`: a list of convolution layer specifications:
+    * `in_channels`
+    * `out_channels`
+    * `size` (defaults to 3)
+    * `stride` (defaults to 1)
+    * `padding` (defaults to 1)
+    * `max_pool` (defaults to `false`): whether to apply a 2x2 max pool layer
+* `linears`: a list of desnse layer specifications:
+    * `in_features`
+    * `out_features`
+
+### Results
+
+For each run, a timestamped directory is created under `outputs/` with:
+
+* A copy of the used configuration file
+* A CSV file with train set losses, test set losses, and test set accuracies,
+  for each epoch
+* `losses.png`: a plot of the losses
+* `accuracies.png`: a plot of the accuracies
-- 
cgit v1.2.3