Add realistic example

.gitignore

@@ -183,3 +183,9 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Data binary
+*.dat
+
+# TorchScript model
+*.pt

examples/2_ResNet18/README.md

@@ -1,6 +1,8 @@
 # Example 2 - ResNet-18
 
-This example provides a simple but complete demonstration of how to use the library.
+This example provides a more realistic demonstration of how to use the library, using ResNet-18 to classify an image.
+
+As the input to this model is four-dimensional (batch size, colour, x, y), care must be taken dealing with the data array in Python and Fortran. See [When to transpose arrays](#when-to-transpose-arrays) for more details.
 
 ## Description
 
@@ -34,10 +36,22 @@ pip install -r requirements.txt
 ```
 
 You can check that everything is working by running `resnet18.py`:
+
 ```
 python3 resnet18.py
 ```
-it should produce the result `tensor([[623, 499, 596, 111, 813]])`.
+
+When using single precision, it should produce the result:
+
+```
+Top 5 results:
+
+Samoyed (id=258): probability = 0.8846225142478943
+Arctic fox (id=279): probability = 0.045805174857378006
+white wolf (id=270): probability = 0.0442761555314064
+Pomeranian (id=259): probability = 0.005621383432298899
+Great Pyrenees (id=257): probability = 0.004652013536542654
+```
 
 To save the pretrained ResNet-18 model to TorchScript run the modified version of the
 `pt2ts.py` tool :
@@ -67,6 +81,15 @@ executable with an argument of the saved model file:
 ./resnet_infer_fortran ../saved_resnet18_model_cpu.pt
 ```
 
+This should produce the same top result:
+
+```
+ Top result
+
+ Samoyed (id=         259 ), : probability =  0.884623706
+```
+
+
 Alternatively we can use `make`, instead of cmake, with the included Makefile.
 However, to do this you will need to modify `Makefile` to link to and include your
 installation of FTorch as described in the main documentation. Also check that the compiler is the same as the one you built the Library with.  
@@ -82,3 +105,45 @@ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:</path/to/library/installation>/lib64
 To explore the functionalities of this model:
 
 - Try saving the model through tracing rather than scripting by modifying `pt2ts.py`
+- Try changing the input image. For example, running the following code will download an alternative image of a dog from [pytorch/vision](https://github.com/pytorch/vision/tree/v0.15.2/gallery/assets), saving it in the `data` directory:
+
+```python
+import urllib
+
+url, filename = (
+    "https://github.com/pytorch/vision/raw/v0.15.1/gallery/assets/dog1.jpg",
+    "data/dog2.jpg",
+)
+urllib.request.urlretrieve(url, filename)
+```
+
+`image_filename` in resnet18.py and resnet_infer_python.py must then be modified to match the name of this new file.
+
+Note that the ImageNet labels can be downloaded and accessed similarly, using:
+
+```python
+import urllib
+
+url, filename = (
+    "https://raw.githubusercontent.com/pytorch/hub/e55b003/imagenet_classes.txt",
+    "imagenet_classes.txt",
+)
+data = urllib.request.urlopen(url)
+categories = [s.strip().decode("utf-8") for s in data]
+```
+
+## When to transpose arrays?
+
+In this example, it is expected that the shape and indices of `in_data` in resnet_infer_fortran.f90 match that of `input_batch` in resnet18.py, i.e. `in_data(i, j, k, l) ==  input_batch[i, j, k, l]`.
+
+Since C is row-major (rows are contiguous in memory), whereas Fortran is column-major (columns are contiguous), it is therefore necessary to perform a transpose when converting from the NumPy array to the Fortran array to ensure that their indices are consistent.
+
+In this example code, the NumPy array is transposed before being flattened and saved to binary, allowing Fortran to `reshape` the flatted array into the correct order.
+
+An alternative would be to save the NumPy array with its original shape, but perform a transpose during or after reading the data into Fortran, e.g. using:
+
+```
+in_data = reshape(flat_data, shape(in_data), order=(4,3,2,1))
+```
+
+For more general use, it should be noted that the function used to create the input tensor from `input_batch`, `torch_tensor_from_blob`, performs a further transpose, which is required to allow the tensor to interact correctly with the model.