TDMS ·

Time-Domain Maxwell Solver

TDMS, the Time Domain Maxwell Solver, is a hybrid C++ and MATLAB tool for simulating light propagation through a medium by solving Maxwell's equations. For further details about the method, please refer to the PDF documentation.

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 and MATLAB, which must be downloaded and installed first.

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). 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: ```{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 ```

Windows prerequisite setup

TDMS was developed - and 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 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/), * 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} 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>``

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"``.

You'll need to download and install MATLAB, and take note where the headers are installed.

Installation

To compile and install, follow these steps:

$ git clone git@github.com:UCL/TDMS.git
$ cd TDMS
$ git checkout v1.0.1 # 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/
$ 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:

$ tdms --help
$ tdms --version

in a new terminal.

How to run

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. This script will generate the input to TDMS, run TDMS, and display sample output. 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 that this script passes to iteratefdtd_matrix.m.

MATLAB file version

In order to be readable by TDMS, files need to be saved in .mat (MATLAB file) version 7.3 or newer. This can be done by passing '-v7.3' to MATLAB's save command as the final argument, for example:

save('my_input_file.mat', 'my_input_var_1', 'my_input_var_2', ..., 'my_input_var_N', '-v7.3');

On the command line

If you want to run TDMS standalone at the command line, the basic operation is with two arguments: an input file containing simulation parameters, and an output file name. You can choose between two solver methods: finite-difference or pseudo-spectral, as well as two interpolation methods: cubic or bandlimited. These options can be selected by setting the corresponding flag variables in the input file. When tdms reads the input, it will verify if the input file contains a dataset that matches the names of these flags.

There are two flags available for configuration in the input file.

TDMS is parallelised with OpenMP. You can set the maximum number of threads using the OMP_NUM_THREADS environment variable before calling the TDMS executable.

$ export OMP_NUM_THREADS=4 # for example

Citation

If you used TDMS in your research and found it helpful, please cite this work: 10.5281/zenodo.7950604.

Acknowledgements

The TDMS source code was released under a GPL-3.0 License as part of a joint project between University College London's Medical Physics and Biomedical Engineering and Centre for Advanced Research Computing with generous funding from the Royal Society.

Development of this software has previously benefited from funding from the Commonwealth Scholarships Commission, the Engineering and Physical Sciences Research Council, and the Australian Research Council.

Want to contribute?

We're grateful for bug reports, feature requests, and pull requests. Please see our contribution guidelines (we also have some developer documentation).