From e7e7adc019dcedcfb9679f303c142d15b387bd63 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 15 May 2023 18:36:49 +0100 Subject: [PATCH 1/7] First pass adding basic prerequisites Very basic preliminaries. CMake, Windows SDK, Xcode etc. --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 046a5c96e..667bee6d4 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,58 @@ For further details about the method, please refer to the [PDF documentation](ht ![The normed z-component of the H field incident on a cylinder](doc/assets/HzNormBanner.png) +## Prerequisites + +We don't ship binaries at the moment, so to use TDMS, it has to be compiled. +It needs to be built against [FFTW](https://www.fftw.org/) and [MATLAB](https://www.mathworks.com/products/matlab.html), which must be downloaded and installed first. + +
+Windows prerequisite setup + +TDMS has been tested with **Windows subsystem for Linux (WSL)** and natively with the SDK on Windows 10. + +If you're a complete beginner we recommend you download the [Windows subsystem for Linux (WSL2)](https://learn.microsoft.com/en-gb/windows/wsl/install), or set up an linux virtual machine, and follow the linux instructions. +If you can't (or don't want to) do this for some reason, you'll need to install the [Windows software developer kit (SDK)](https://developer.microsoft.com/en-gb/windows/downloads/windows-sdk/) which contains the Windows C++ compiler, [CMake](https://cmake.org/download/), and then [FFTW](https://www.fftw.org/), the latter works via [conda](https://anaconda.org/conda-forge/fftw). + +You'll also need [MATLAB](https://www.mathworks.com/products/matlab.html). +Note: MATLAB inside WSL2 is not _officially_ supported but does work (and we still recommend this as the most straightforward). +You may have to do [some setup to ensure your license key is recognised](https://uk.mathworks.com/matlabcentral/answers/1696925-matlab-licence-using-both-window11-and-wsl2). +
+ +
+Linux and MacOS prerequisite setup + +Assuming you don't already have them, you'll need a C++ compiler, CMake, OpenMP and FFTW. + +For Debian-based distributions this should be as simple as +```{sh} +sudo apt install git gcc cmake libfftw3-dev libgomp1 +``` + +On MacOS you will need an x86 compiler with libraries for OpenMP. +You'll need to download the latest [xcode tools](https://apps.apple.com/app/xcode). +And everything else can be installed using [Homebrew](https://brew.sh) with the command: + +```{sh} +brew install cmake fftw llvm +``` + +On an ARM Mac, you will need to install the x86 version of Homebrew. +To do so, use the following commands: + +```{sh} +arch -x86_64 zsh +arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +arch -x86_64 /usr/local/bin/brew install cmake fftw llvm +``` +------ + +You'll need to download and install [MATLAB](https://www.mathworks.com/products/matlab.html), and take note where the headers are installed. +
+ ## Getting started -To use TDMS, it needs to be built against [FFTW](https://www.fftw.org/) and [MATLAB](https://www.mathworks.com/products/matlab.html), which must be downloaded and installed first. -To install, follow these steps: +To compile and install, follow these steps: ```bash $ git clone git@github.com:UCL/TDMS.git @@ -40,14 +88,7 @@ If CMake cannot find MATLAB, FFTW, or install to the default installation prefix
Mac-specific instructions -To compile TDMS on a Mac, you will need an x86 compiler with libraries for OpenMP. -You can install these using [Homebrew](https://brew.sh) with the command: - -```{sh} -brew install llvm -``` - -After installing with Homebrew, you may need to set the following CMake arguments: + After installing with Homebrew, you may need to set the following CMake arguments: ```{sh} -DCMAKE_CXX_COMPILER=/Users/username/.local/homebrew/opt/llvm/bin/clang++ From f34f406fe7a08fb6378732d9368eaab9683d8846 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 16 May 2023 07:57:46 +0100 Subject: [PATCH 2/7] Add OS logos * V. minor tweak to language. * Add OS logos from EgoistDeveloper/operating-system-logos * Split MacOS into its own thing. --- README.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 667bee6d4..8e87a1396 100644 --- a/README.md +++ b/README.md @@ -23,49 +23,56 @@ For further details about the method, please refer to the [PDF documentation](ht We don't ship binaries at the moment, so to use TDMS, it has to be compiled. It needs to be built against [FFTW](https://www.fftw.org/) and [MATLAB](https://www.mathworks.com/products/matlab.html), which must be downloaded and installed first. +------ +
-Windows prerequisite setup + Windows prerequisite setup TDMS has been tested with **Windows subsystem for Linux (WSL)** and natively with the SDK on Windows 10. - + If you're a complete beginner we recommend you download the [Windows subsystem for Linux (WSL2)](https://learn.microsoft.com/en-gb/windows/wsl/install), or set up an linux virtual machine, and follow the linux instructions. If you can't (or don't want to) do this for some reason, you'll need to install the [Windows software developer kit (SDK)](https://developer.microsoft.com/en-gb/windows/downloads/windows-sdk/) which contains the Windows C++ compiler, [CMake](https://cmake.org/download/), and then [FFTW](https://www.fftw.org/), the latter works via [conda](https://anaconda.org/conda-forge/fftw). - + You'll also need [MATLAB](https://www.mathworks.com/products/matlab.html). Note: MATLAB inside WSL2 is not _officially_ supported but does work (and we still recommend this as the most straightforward). You may have to do [some setup to ensure your license key is recognised](https://uk.mathworks.com/matlabcentral/answers/1696925-matlab-licence-using-both-window11-and-wsl2).
-Linux and MacOS prerequisite setup + Linux prerequisite setup Assuming you don't already have them, you'll need a C++ compiler, CMake, OpenMP and FFTW. - + For Debian-based distributions this should be as simple as ```{sh} sudo apt install git gcc cmake libfftw3-dev libgomp1 ``` +
+ +
+ MacOS prerequisite setup + On MacOS you will need an x86 compiler with libraries for OpenMP. You'll need to download the latest [xcode tools](https://apps.apple.com/app/xcode). -And everything else can be installed using [Homebrew](https://brew.sh) with the command: +And everything else can be installed using [Homebrew](https://brew.sh): ```{sh} brew install cmake fftw llvm ``` -On an ARM Mac, you will need to install the x86 version of Homebrew. -To do so, use the following commands: +On an ARM Mac, you will need to install the x86 version of Homebrew: ```{sh} arch -x86_64 zsh arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" arch -x86_64 /usr/local/bin/brew install cmake fftw llvm ``` +
+ ------ - + You'll need to download and install [MATLAB](https://www.mathworks.com/products/matlab.html), and take note where the headers are installed. -
## Getting started From 705d2da0626eb17ab822d2dccf647af3717b4ec6 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Fri, 26 May 2023 10:10:58 +0100 Subject: [PATCH 3/7] Working Windows instructions. --- README.md | 109 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 56 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 94569b358..92f09d54b 100644 --- a/README.md +++ b/README.md @@ -15,24 +15,11 @@ For further details about the method, please refer to the [PDF documentation](ht ![The normed z-component of the H field incident on a cylinder](doc/assets/HzNormBanner.png) -## Prerequisites +## Getting started We don't ship binaries at the moment, so to use TDMS, it has to be compiled. It needs to be built against [FFTW](https://www.fftw.org/) and [MATLAB](https://www.mathworks.com/products/matlab.html), which must be downloaded and installed first. -
- Windows prerequisite setup - -TDMS has been tested with **Windows subsystem for Linux (WSL)** and natively with the SDK on Windows 10. - -If you're a complete beginner we recommend you download the [Windows subsystem for Linux (WSL2)](https://learn.microsoft.com/en-gb/windows/wsl/install), or set up an linux virtual machine, and follow the linux instructions. -If you can't (or don't want to) do this for some reason, you'll need to install the [Windows software developer kit (SDK)](https://developer.microsoft.com/en-gb/windows/downloads/windows-sdk/) which contains the Windows C++ compiler, [CMake](https://cmake.org/download/), and then [FFTW](https://www.fftw.org/), the latter works via [conda](https://anaconda.org/conda-forge/fftw). - -You'll also need [MATLAB](https://www.mathworks.com/products/matlab.html). -Note: MATLAB inside WSL2 is not _officially_ supported but does work (and we still recommend this as the most straightforward). -You may have to do [some setup to ensure your license key is recognised](https://uk.mathworks.com/matlabcentral/answers/1696925-matlab-licence-using-both-window11-and-wsl2). -
-
Linux prerequisite setup @@ -49,15 +36,15 @@ $ sudo apt install git gcc cmake libfftw3-dev libgomp1 MacOS prerequisite setup On MacOS you will need an x86 compiler with libraries for OpenMP. -You'll need to download the latest [xcode tools](https://apps.apple.com/app/xcode). -And everything else can be installed using [Homebrew](https://brew.sh) with the command: +You'll need to download the latest [Xcode tools](https://apps.apple.com/app/xcode). + +Everything else can be installed using [Homebrew](https://brew.sh): ```{sh} $ brew install cmake fftw llvm ``` -On an ARM Mac, you will need to install the x86 version of Homebrew. -To do so, use the following commands: +On an ARM Mac, you will need to install the x86 version of Homebrew: ```{sh} $ arch -x86_64 zsh @@ -67,61 +54,77 @@ $ arch -x86_64 /usr/local/bin/brew install cmake fftw llvm
+
+ Windows prerequisite setup + +TDMS was developed on, and has been extensively tested on linux. +Support for Windows is quite new and experimental (please [report](https://github.com/UCL/TDMS/issues/new/choose) any issues you encounter!). + +It might be more straightforward to use the [Windows subsystem for Linux (WSL2)](https://learn.microsoft.com/en-gb/windows/wsl/install), or set up an linux virtual machine. + +However, TDMS _can_ be compiled natively on Windows. +This has been tested Windows 10 with PowerShell. + +Assuming you don't already have them, you'll need to download and install: + +* [MATLAB](https://www.mathworks.com/products/matlab.html), +* [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and be sure to select the C++ kit, +* [CMake](https://cmake.org/download/), +* and [FFTW](https://www.fftw.org/install/windows.html). + +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 +``` + +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 +```{pwsh} +PS> conda list fftw # assuming you installed via conda +PS> which.exe MATLAB +``` +Which should return something like `C:\Program Files (x86)\MATLAB\R20XXx\bin\matlab` and maybe `C:\ProgramData\envs\base\bin`. +If you downloaded FFTW and created `fftw3.dll` with `lib.exe`, you just need to know where you saved it. + +You can append the paths: + +```{pwsh} +PS> $env:Path += ";C:\Program Files (x86)\MATLAB\R20XXx\bin\;C:\ < wherever fftw3.dll is >" +``` + +Which will help Windows locate `.dll` files later. +For all following instructions, you'll have to substitute our mentions of `tdms` with `tdms.exe` and `$` is used to denote a command prompt which, in PowerShell would look like `PS>` + +
+ ------ You'll need to download and install [MATLAB](https://www.mathworks.com/products/matlab.html), and take note where the headers are installed. -## Getting started +## Installation To compile and install, follow these steps: -```bash +```{sh} $ git clone git@github.com:UCL/TDMS.git $ cd TDMS $ git checkout v1.0.0 # the stable version $ mkdir build; cd build $ cmake ../tdms \ -# -DMatlab_ROOT_DIR=/usr/local/MATLAB/R2019b/ \ +# -DMatlab_ROOT_DIR=/usr/local/MATLAB/R20XXx/ \ # -DFFTW_ROOT=/usr/local/fftw3/ \ # -DCMAKE_INSTALL_PREFIX=$HOME/.local/ -$ make install +$ 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. -
-Mac-specific instructions - -To compile TDMS on a Mac, you will need an x86 compiler with libraries for OpenMP. -You can install these using [Homebrew](https://brew.sh) with the command: - -```{sh} -$ brew install llvm -``` - -After installing with Homebrew, you may need to set the following CMake arguments: - -```{sh} --DCMAKE_CXX_COMPILER=/Users/username/.local/homebrew/opt/llvm/bin/clang++ --DOMP_ROOT=/Users/username/.local/homebrew/opt/llvm/ --DCXX_ROOT=/Users/username/.local/homebrew/opt/llvm --DHDF5_ROOT=/Users/username/.local/homebrew/opt/hdf5 -``` - -On an ARM Mac, you will need to install the x86 version of Homebrew. -To do so, use the following commands: - -```{sh} -$ arch -x86_64 zsh -$ arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -$ arch -x86_64 /usr/local/bin/brew install llvm hdf5 -``` -
- You can check that `tdms` was installed correctly and is in your `PATH` by running: ```{sh} -$ tdms --help +$ tdms -h $ tdms --version ``` in a new terminal. @@ -158,7 +161,7 @@ In a terminal run $ which tdms ``` -Copy the full path (something like `/usr/local/bin/tdms`) into [`run_pstd_bscan.m`](https://github.com/UCL/TDMS/blob/main/examples/arc_01/run_pstd_bscan.m), replacing the `'tdms'` text in the calls to the `system()` function. +Copy the full path (something like `/usr/local/bin/tdms`) into [`run_pstd_bscan.m`](https://github.com/UCL/TDMS/blob/main/examples/arc_01/run_pstd_bscan.m), replacing the ` 'tdms' ` text in the calls to the ``system()`` function. From 797106869386334a77b8686358003c94de5f4a13 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Fri, 26 May 2023 13:50:06 +0100 Subject: [PATCH 4/7] Boldify the C++ kit thing. Co-authored-by: Will Graham <32364977+willGraham01@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 92f09d54b..9f3edf9f9 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ This has been tested Windows 10 with PowerShell. Assuming you don't already have them, you'll need to download and install: * [MATLAB](https://www.mathworks.com/products/matlab.html), -* [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and be sure to select the C++ kit, +* [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and **be sure to select the C++ kit**, * [CMake](https://cmake.org/download/), * and [FFTW](https://www.fftw.org/install/windows.html). From 1a3c69462518edc4f6964edf27f065947b3f2144 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Fri, 26 May 2023 16:47:35 +0100 Subject: [PATCH 5/7] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9f3edf9f9..349c18f3d 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ If CMake cannot find MATLAB, FFTW, or install to the default installation prefix You can check that `tdms` was installed correctly and is in your `PATH` by running: ```{sh} -$ tdms -h +$ tdms --help $ tdms --version ``` in a new terminal. From a35fcc0c6d011d847b1b5ae642afa01a8189d500 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 13 Jun 2023 09:14:27 +0100 Subject: [PATCH 6/7] Final (?) README polishing. --- README.md | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 139742493..b7786d980 100644 --- a/README.md +++ b/README.md @@ -63,15 +63,21 @@ Support for Windows is quite new and experimental (please [report](https://githu It might be more straightforward to use the [Windows subsystem for Linux (WSL2)](https://learn.microsoft.com/en-gb/windows/wsl/install), or set up an linux virtual machine. However, TDMS _can_ be compiled natively on Windows. -This has been tested Windows 10 with PowerShell. +This has been tested Windows 10 and 11, with PowerShell. Assuming you don't already have them, you'll need to download and install: * [MATLAB](https://www.mathworks.com/products/matlab.html), -* [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and **be sure to select the C++ kit**, +* [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and **be sure to select the C++ developer kit**, * [CMake](https://cmake.org/download/), * and [FFTW](https://www.fftw.org/install/windows.html). +You can check that the Visual Studio compiler was installed with: + +```{pwsh} +PS> MSBuild.exe -h +``` + Potentially the simplest way to get FFTW is via [conda](https://anaconda.org/conda-forge/fftw): ```{pwsh} @@ -95,7 +101,16 @@ PS> $env:Path += ";C:\Program Files (x86)\MATLAB\R20XXx\bin\;C:\ < wherever fftw ``` Which will help Windows locate `.dll` files later. -For all following instructions, you'll have to substitute our mentions of `tdms` with `tdms.exe` and `$` is used to denote a command prompt which, in PowerShell would look like `PS>` +For all following instructions, you'll have to substitute our mentions of ``tdms`` with ``tdms.exe`` and ``$`` is used to denote a command prompt which, in PowerShell, would look like ``PS>`` + +
+Even more Windows troubleshooting + +We've seen that in a fresh PowerShell window, Windows does not remember the location of the ``.dll`` files, so you may have to re-add them to the path, or copy them into the directory where TDMS was installed. + +TDMS typically installs to ``"C:\Program Files (x86)\tdms\bin\tdms.exe"``. + +
@@ -114,9 +129,9 @@ $ cd TDMS $ git checkout v1.0.0 # the stable version $ mkdir build; cd build $ cmake ../tdms \ -# -DMatlab_ROOT_DIR=/usr/local/MATLAB/R20XXx/ \ -# -DFFTW_ROOT=/usr/local/fftw3/ \ -# -DCMAKE_INSTALL_PREFIX=$HOME/.local/ +$ # -DMatlab_ROOT_DIR=/usr/local/MATLAB/R20XXx/ \ +$ # -DFFTW_ROOT=/usr/local/fftw3/ \ +$ # -DCMAKE_INSTALL_PREFIX=$HOME/.local/ $ cmake --build . --target install --config Release ``` @@ -135,8 +150,8 @@ You can run TDMS either directly or from a MATLAB script. For beginners, we recommend starting with the demonstration MATLAB script, which you can find in the `examples/arc_01` directory. Move into this directory, launch MATLAB, and run the MATLAB script [`run_pstd_bscan.m`](https://github.com/UCL/TDMS/blob/main/examples/arc_01/run_pstd_bscan.m). This script will generate the input to TDMS, run TDMS, and display sample output. -It also commentates on what it is doing, so you can follow along with what is being setup and created at each stage. -We have also annotated the input file [`arc_01_example_input.m`](https://github.com/UCL/TDMS/blob/main/examples/arc_01/arc_01_example_input.m) that this script passes to `iteratefdtd_matrix.m`. +There are comments explaining what it is doing, so you can follow along with what is being setup and created at each stage. +We have also commented the input file [`arc_01_example_input.m`](https://github.com/UCL/TDMS/blob/main/examples/arc_01/arc_01_example_input.m) that this script passes to `iteratefdtd_matrix.m`.
Troubleshooting From a5ef852f009e2436ddeb3073bb103b8a29693566 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 13 Jun 2023 10:59:40 +0100 Subject: [PATCH 7/7] 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 | 12 +++++++++++- doc/developers.md | 29 +++++++++++++++++++++++------ 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b7786d980..df9c82a36 100644 --- a/README.md +++ b/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 ``` + +
@@ -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 ``` + +
@@ -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: + * [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 ``` + + 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 git@github.com: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. + + You can check that `tdms` was installed correctly and is in your `PATH` by running: ```{sh} $ tdms --help diff --git a/doc/developers.md b/doc/developers.md index 9632f56ae..a5e17650b 100644 --- a/doc/developers.md +++ b/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
-## 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)