Merge pull request #144 from Cambridge-ICCS/changelog

Add a web docs page explaining the API changes and how to update.

README.md

@@ -11,6 +11,13 @@ For full API and user documentation please see the
 [online documentation](https://cambridge-iccs.github.io/FTorch/) which is 
 significantly more detailed than this README.
 
+**NOTE:** _We recently made breaking changes to the API as it heads towards a stable release.
+Please see the
+[online updates documentation](https://cambridge-iccs.github.io/FTorch/page/updates.html)
+for clear guidance on how to easily update your older code to run with the latest version of
+FTorch._
+
+
 ## Contents
 - [Description](#description)
 - [Installation](#installation)
@@ -60,7 +67,10 @@ The following presentations provide an introduction and overview of _FTorch_:
 
 Project status: This project is currently in pre-release with documentation and code
 being prepared for a first release.
-As such breaking changes may be made.
+As we stabilise the API in preparation for first release there may be some breaking changes.
+Please see 
+[online updates documentation](https://cambridge-iccs.github.io/FTorch/page/updates.html)
+for clear guidance on how to easily update your older code to run with the latest version.\
 If you are interested in using this library please get in touch.
 
 _For a similar approach to calling TensorFlow models from Fortran please see [Fortran-TF-lib](https://github.com/Cambridge-ICCS/fortran-tf-lib)._

pages/updates.md

@@ -0,0 +1,112 @@
+title: Recent API Changes
+
+[TOC]
+
+
+## Why?
+
+Recently we made a number of breaking changes to the FTorch API.
+
+We realise that this forms an inconvenience to those of you who are actively
+using FTorch and is not something we did lightly.
+These changes were neccessary to improve functionality and we have made them in one go
+as we move towards a stable API and first release in the very near future.
+Once the first release is set then the API becomes standardised then changes like this
+will be avoided. We hope that this is the last time we have such a shift.
+
+The changes allow us to implement two new features:
+
+1. Multiple output tensors
+   Previously you could pass an array of several input tensors to a Torch model, but
+   only recieve a single output tensor back. Now you can use models that return several
+   output tensors by passing an array of output tensors instead.
+2. Preparation for autograd functionality
+   We hope to make it easier to access the autograd features of PyTorch from within Fortran.
+   To do this we needed to change how data was assigned from a Fortran array to a Torch tensor.
+   This is now done via a subroutine call rather than a function.
+
+<br>
+
+## Changes and how to update your code
+
+<br>
+
+#### `torch_tensor`s are created using a subroutine call, not a function
+
+Previously you would have created a Torch tensor and assigned some fortran data to it as follows:
+```fortran
+real, dimension(5), target :: fortran_data
+type(torch_tensor) :: my_tensor
+integer :: tensor_layout(1) = [1]
+
+my_tensor = torch_tensor_from_array(fortran_data, tensor_layout, torch_kCPU)
+```
+<br>
+Now a call is made to a subroutine with the tensor as the first argument:
+```fortran
+real, dimension(5), target :: fortran_data
+type(torch_tensor) :: my_tensor
+integer :: tensor_layout(1) = [1]
+
+call torch_tensor_from_array(my_tensor, fortran_data, tensor_layout, torch_kCPU)
+```
+
+<br>
+
+#### `module` becomes `model` and loading becomes a subroutine call, not a function
+
+Previously a neural net was referred to as a '`module`' and loaded using appropriately
+named functions and types.
+```fortran
+type(torch_module) :: model
+model = torch_module_load(args(1))
+call torch_module_forward(model, in_tensors, out_tensors)
+```
+<br>
+Following user feedback we now refer to a neural net and its associated types and calls
+as a '`model`'.
+The process of loading a net is also now a subroutine call for consistency with the
+tensor creation operations:
+```fortran
+type(torch_model) :: model
+call torch_model_load(model, 'path_to_saved_net.pt')
+call torch_model_forward(model, in_tensors, out_tensors)
+
+```
+
+<br>
+
+#### `n_inputs` is no longer required
+
+Previously when you called the forward method on a net you had to specify the number of tensors
+in the array of inputs:
+```fortran
+call torch_model_forward(model, in_tensors, n_inputs, out_tensors)
+```
+<br>
+Now all that is supplied to the forward call is the model, and the arrays of input and
+output tensors. No need for `n_inputs` (or `n_outputs`)!
+```fortran
+call torch_model_forward(model, in_tensors, out_tensors)
+```
+
+<br>
+
+#### Outputs now need to be an array of `torch_tensor`s
+
+Previously you passed an array of `torch_tensor` types as inputs, and a single `torch_tensor`
+to the forward method:
+```fortran
+type(torch_tensor), dimension(n_inputs) :: input_tensor_array
+type(torch_tensor) :: output_tensor
+...
+call torch_model_forward(model, input_tensor_array, n_inputs, output_tensor)
+```
+<br>
+Now both the inputs and the outputs need to be an array of `torch_tensor` types:
+```fortran
+type(torch_tensor), dimension(n_inputs)  :: input_tensor_array
+type(torch_tensor), dimension(n_outputs) :: output_tensor_array
+...
+call torch_model_forward(model, input_tensor_array, output_tensor_array)
+```