Solves #313.

Add comments to the README for when #181 is finished. Add instructions
to the dev docs (since devs might be compiling the HEAD of main.

README.md

@@ -30,6 +30,8 @@ For Debian-based distributions this should be as simple as
 $ sudo apt install git gcc cmake libfftw3-dev libgomp1
 ```
 
+<!-- TODO: add libhdf5-dev here when updating to v1.2 -->
+
 </details>
 
 <details>
@@ -52,6 +54,8 @@ $ arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Home
 $ arch -x86_64 /usr/local/bin/brew install cmake fftw llvm
 ```
 
+<!-- on MacOS it's just hdf5 as an argument to brew -->
+
 </details>
 
 <details>
@@ -67,6 +71,7 @@ This has been tested Windows 10 and 11, with PowerShell.
 
 Assuming you don't already have them, you'll need to download and install:
 
+<!-- * HDF5 -->
 * [MATLAB](https://www.mathworks.com/products/matlab.html),
 * [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and **be sure to select the C++ developer kit**,
 * [CMake](https://cmake.org/download/),
@@ -80,10 +85,13 @@ PS> MSBuild.exe -h
 
 Potentially the simplest way to get FFTW is via [conda](https://anaconda.org/conda-forge/fftw):
 
+
 ```{pwsh}
 PS> conda install -c conda-forge fftw --yes
 ```
 
+<!-- TODO: add HDF5 👆 here when updating to v2 -->
+
 You'll need to ensure the paths to FFTW and MATLAB (the locations of `fftw3.dll` and `libmex.dll` respectively) are in the `env:Path`.
 
 These can be found, e.g. by
@@ -126,7 +134,7 @@ To compile and install, follow these steps:
 ```{sh}
 $ git clone [email protected]:UCL/TDMS.git
 $ cd TDMS
-$ git checkout v1.0.0 # the stable version
+$ git checkout v1.0.1 # the stable version
 $ mkdir build; cd build
 $ cmake ../tdms \
 $ # -DMatlab_ROOT_DIR=/usr/local/MATLAB/R20XXx/ \
@@ -137,6 +145,8 @@ $ cmake --build . --target install --config Release
 
 If CMake cannot find MATLAB, FFTW, or install to the default installation prefix, uncomment the relevant line(s) and modify the path(s) accordingly.
 
+<!-- TODO: add HDF5 when updating to v2 -->
+
 You can check that `tdms` was installed correctly and is in your `PATH` by running:
 ```{sh}
 $ tdms --help

doc/developers.md

@@ -18,6 +18,7 @@ We depend on ...
 * [fftw](https://www.fftw.org/) to calculate numerical derivatives (numerical_derivative.h)
 * [spdlog](https://github.com/gabime/spdlog) for logging (this is installed automatically by a CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) if not found).
 * [MATLAB](https://www.mathworks.com/products/matlab.html) since we read in and write out MATLAB format files. We are actually thinking of removing this as a strict dependency ([#70](https://github.com/UCL/TDMS/issues/70)).
+* [HDF5](https://portal.hdfgroup.org/display/HDF5/HDF5+CPP+Reference+Manuals) for TDMS versions newer than v1.0.1 or for building the ``HEAD`` of ``main``. See [issue #181](https://github.com/UCL/TDMS/issues/181) for more details.
 
 ### Versions
 
@@ -107,7 +108,23 @@ ls .git/hooks
 
 ## Compiling and debugging {#compiling}
 
-Once you've checked the code out, compile with:
+Once you've checked the code out, compile following the [user instructions](https://github-pages.ucl.ac.uk/TDMS).
+If you're building the ``HEAD`` of ``main`` you'll also need to install HDF5 with:
+
+```{.sh}
+sudo apt install libhdf5-dev
+```
+on Linux or
+
+```{.sh}
+brew install hdf5
+```
+on MacOS.
+
+(This is omitted from the user-facing docs because we don't have a stable version of TDMS with HDF5 yet.)
+
+There are extra build options for developers:
+
 ```{.sh}
 mkdir build; cd build
 cmake ../tdms \
@@ -119,7 +136,7 @@ cmake ../tdms \
 # -DCMAKE_BUILD_TYPE=Debug
 make install
 ```
-You may need to help CMake find MATLAB/fftw etc.
+You may need to help CMake find MATLAB/fftw/libhdf5 etc.
 
 - By default, build testing is turned off. You can turn it on with `-DBUILD_TESTING=ON`.
 - By default, code coverage is disabled. You can enable it with `-DCODE_COVERAGE=ON`.
@@ -180,7 +197,7 @@ it's because the MATLAB module is interfering with the SSL certificates (and we
 </details>
 
 
-## Where's the main?
+## Navigating the algorithm code
 
 The C++ `main` function is in `main.cpp` however the main algorithm code is in the `execute()` method of the `SimulationManager` class, in `execute_simulation.cpp`.
 
@@ -194,7 +211,7 @@ Broadly speaking, the `main` function - and thus a call to (or execution of) `td
 The `SimulationManager` class governs steps 2 through 5.
 
 A flowchart that further breaks down the above steps can be viewed below.
-![](assets/TDMS_flowchart.png)
+![](doc/assets/TDMS_flowchart.png)
 
 ## Code organisation of the TDMS algorithm
 
@@ -336,7 +353,7 @@ The combinations and expected results are listed in the table below.
 
 \note `TD-field` is also known as `exi/eyi` in some docstrings.
 
-\note `usecd` was the legacy name for the variable that controlled which solver method to use in the timestepping algorithm. Previous convention was that `usecd = 1` (or not present) resulted in the use of FDTD. This has since been superceeded by the `use_pstd` flag which is `true` when PSTD is to be used, and FDTD will be used otherwise (such as when this flag is not present or set explicitly to `false`).
+\note `usecd` was the legacy name for the variable that controlled which solver method to use in the timestepping algorithm. Previous convention was that `usecd = 1` (or not present) resulted in the use of FDTD. This has since been superseded by the `use_pstd` flag which is `true` when PSTD is to be used, and FDTD will be used otherwise (such as when this flag is not present or set explicitly to `false`).
 
 | TD-field | Using FDTD | compactsource | efname | hfname | Raises error? |                             Error info                              |
 | :------: | :--------: | :-----------: | :----: | :----: | :-----------: | :-----------------------------------------------------------------: |
@@ -442,7 +459,7 @@ The system tests rely on `.mat` input files that are generated through a series
 (Re)generating the input data for a particular test case, `arc_XX`, is a three-step process:
 1. Determine variables, filenames, and the particular setup of `arc_XX`. This information is stored in the corresponding `config_XX.yaml` file. For example, is an illumination file required? What are the spatial obstacles? What is the solver method?
 1. Call the `run_bscan.m` function (and sub-functions in `./matlab`) using the information in `config_XX.yaml` to produce the `.mat` input files. Each test case requires an input file (`input_file_XX.m`) which defines test-specific variables (domain size, number of period cells, material properties, etc) which are too complex to specify in a `.yaml` file.
-1. Clean up the auxillary `.mat` files that are generated by this process. In particular, any `gridfiles.mat`, illumination files, or other `.mat` files that are temporarily created when generating the input `.mat` file.
+1. Clean up the auxiliary `.mat` files that are generated by this process. In particular, any `gridfiles.mat`, illumination files, or other `.mat` files that are temporarily created when generating the input `.mat` file.
 
 #### Contents of the `data/input_generation` Directory (and subdirectories)