{"id":26766120,"url":"https://github.com/ucl/tdms","last_synced_at":"2025-04-15T12:35:59.701Z","repository":{"id":39594998,"uuid":"448864310","full_name":"UCL/TDMS","owner":"UCL","description":"Time Domain Maxwell Solver","archived":false,"fork":false,"pushed_at":"2024-11-18T12:49:04.000Z","size":91237,"stargazers_count":12,"open_issues_count":35,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T11:11:18.605Z","etag":null,"topics":["matlab","maxwell-equations","maxwell-equations-solver","physics","time-domain"],"latest_commit_sha":null,"homepage":"https://github-pages.ucl.ac.uk/TDMS","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UCL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-01-17T11:22:44.000Z","updated_at":"2024-09-11T08:39:49.000Z","dependencies_parsed_at":"2023-11-30T18:28:21.805Z","dependency_job_id":"50b6e35c-1d85-4b84-bee5-5b6ae58e20a9","html_url":"https://github.com/UCL/TDMS","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FTDMS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FTDMS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FTDMS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UCL%2FTDMS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UCL","download_url":"https://codeload.github.com/UCL/TDMS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249072822,"owners_count":21208253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["matlab","maxwell-equations","maxwell-equations-solver","physics","time-domain"],"created_at":"2025-03-28T20:19:12.484Z","updated_at":"2025-04-15T12:35:59.681Z","avatar_url":"https://github.com/UCL.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- \\cond\n --\u003e\n\u003c!-- 👆 this comment and the endcond below, tells doxygen to ignore the badges\nand title at the top of README.md when building the project page (the title\nwould be duplicated) everything else in README.md is also the project homepage. --\u003e\n\n# TDMS · [![latest release](https://badgen.net/github/release/UCL/TDMS)](https://github.com/UCL/TDMS/releases)  [![license](https://badgen.net/badge/license/GPL-3.0/blue)](https://github.com/UCL/TDMS/blob/main/LICENSE) [![Build and test](https://github.com/UCL/TDMS/actions/workflows/ci.yml/badge.svg)](https://github.com/UCL/TDMS/actions/workflows/ci.yml) [![MATLAB tests](https://github.com/UCL/TDMS/actions/workflows/matlab_tests.yml/badge.svg)](https://github.com/UCL/TDMS/actions/workflows/matlab_tests.yml) [![codecov](https://codecov.io/gh/UCL/TDMS/branch/main/graph/badge.svg?token=3kqP14kslL)](https://codecov.io/gh/UCL/TDMS) [![DOI](https://zenodo.org/badge/448864310.svg)](https://zenodo.org/badge/latestdoi/448864310)\n\n\u003c!-- \\endcond --\u003e\n\n# Time-Domain Maxwell Solver\n\nTDMS, the Time Domain Maxwell Solver, is a hybrid C++ and MATLAB tool for simulating light propagation through a medium by solving Maxwell's equations.\nFor further details about the method, please refer to the [PDF documentation](https://github.com/UCL/TDMS/blob/gh-doc/masterdoc.pdf).\n\n![The normed z-component of the H field incident on a cylinder](doc/assets/HzNormBanner.png)\n\n## Getting started\n\nWe don't ship binaries at the moment, so to use TDMS, it has to be compiled.\nIt 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cimg src=\"https://github.com/EgoistDeveloper/operating-system-logos/blob/master/src/24x24/UBT.png\"/\u003e Linux prerequisite setup\u003c/summary\u003e\n\nAssuming you don't already have them, you'll need a C++ compiler, CMake, OpenMP and FFTW.\n\nFor Debian-based distributions this should be as simple as\n```{sh}\n$ sudo apt install git gcc cmake libfftw3-dev libgomp1\n```\n\n\u003c!-- TODO: add libhdf5-dev here when updating to v1.1+ --\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cimg src=\"https://github.com/EgoistDeveloper/operating-system-logos/blob/master/src/24x24/MAC.png\"/\u003e MacOS prerequisite setup\u003c/summary\u003e\n\nOn MacOS you will need an x86 compiler with libraries for OpenMP.\nYou'll need to download the latest [Xcode tools](https://apps.apple.com/app/xcode).\n\nEverything else can be installed using [Homebrew](https://brew.sh):\n\n```{sh}\n$ brew install cmake fftw llvm\n```\n\nOn an ARM Mac, you will need to install the x86 version of Homebrew:\n\n```{sh}\n$ arch -x86_64 zsh\n$ arch -x86_64 /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n$ arch -x86_64 /usr/local/bin/brew install cmake fftw llvm\n```\n\n\u003c!-- TODO (v1.1+) on MacOS it's just hdf5 as an argument to brew --\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cimg src=\"https://github.com/EgoistDeveloper/operating-system-logos/blob/master/src/24x24/WIN.png\"/\u003e Windows prerequisite setup\u003c/summary\u003e\n\nTDMS was developed - and extensively tested - on linux.\nSupport for Windows is quite new and experimental (please [report](https://github.com/UCL/TDMS/issues/new/choose) any issues you encounter!).\n\nIt 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.\n\nHowever, TDMS _can_ be compiled natively on Windows.\nThis has been tested Windows 10 and 11, with PowerShell.\n\nAssuming you don't already have them, you'll need to download and install:\n\n\u003c!-- when updating to version 1.1+, uncomment\n\n* [HDF5](https://portal.hdfgroup.org/display/HDF5/HDF5+CPP+Reference+Manuals) --\u003e\n* [MATLAB](https://www.mathworks.com/products/matlab.html),\n* [Visual Studio](https://visualstudio.microsoft.com/vs/community/) and **be sure to select the C++ developer kit**,\n* [CMake](https://cmake.org/download/),\n* and [FFTW](https://www.fftw.org/install/windows.html).\n\nYou can check that the Visual Studio compiler was installed with:\n\n```{pwsh}\nPS\u003e MSBuild.exe -h\n```\n\nPotentially the simplest way to get FFTW is via [conda](https://anaconda.org/conda-forge/fftw):\n\n\n```{pwsh}\nPS\u003e conda install -c conda-forge fftw --yes\n```\n\n\u003c!-- TODO: add HDF5 👆 here when updating to v1.1+ probably also via conda is the easiest --\u003e\n\nYou'll need to ensure the paths to FFTW and MATLAB (the locations of `fftw3.dll` and `libmex.dll` respectively) are in the `env:Path`.\n\nThese can be found, e.g. by\n```{pwsh}\nPS\u003e conda list fftw # assuming you installed via conda\nPS\u003e which.exe MATLAB\n```\nWhich should return something like `C:\\Program Files (x86)\\MATLAB\\R20XXx\\bin\\matlab` and maybe `C:\\ProgramData\\envs\\base\\bin`.\nIf you downloaded FFTW and created `fftw3.dll` with `lib.exe`, you just need to know where you saved it.\n\nYou can append the paths:\n\n```{pwsh}\nPS\u003e $env:Path += \";C:\\Program Files (x86)\\MATLAB\\R20XXx\\bin\\;C:\\ \u003c wherever fftw3.dll is \u003e\"\n```\n\nWhich will help Windows locate `.dll` files later.\nFor 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\u003e``\n\n\u003cdetails\u003e\n\u003csummary\u003eEven more Windows troubleshooting\u003c/summary\u003e\n\nWe'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.\n\nTDMS typically installs to ``\"C:\\Program Files (x86)\\tdms\\bin\\tdms.exe\"``.\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n------\n\nYou'll need to download and install [MATLAB](https://www.mathworks.com/products/matlab.html), and take note where the headers are installed.\n\u003c/details\u003e\n\n## Installation\n\nTo compile and install, follow these steps:\n\n```{sh}\n$ git clone git@github.com:UCL/TDMS.git\n$ cd TDMS\n$ git checkout v1.0.1 # the stable version\n$ mkdir build; cd build\n$ cmake ../tdms \\\n$ # -DMatlab_ROOT_DIR=/usr/local/MATLAB/R20XXx/ \\\n$ # -DFFTW_ROOT=/usr/local/fftw3/ \\\n$ # -DCMAKE_INSTALL_PREFIX=$HOME/.local/\n$ cmake --build . --target install --config Release\n```\n\nIf CMake cannot find MATLAB, FFTW, or install to the default installation prefix, uncomment the relevant line(s) and modify the path(s) accordingly.\n\n\u003c!-- TODO: add HDF5 when updating to v1.1+ --\u003e\n\nYou can check that `tdms` was installed correctly and is in your `PATH` by running:\n```{sh}\n$ tdms --help\n$ tdms --version\n```\nin a new terminal.\n\n## How to run\n\nYou can run TDMS either directly or from a MATLAB script.\nFor beginners, we recommend starting with the demonstration MATLAB script, which you can find in the `examples/arc_01` directory.\nMove 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).\nThis script will generate the input to TDMS, run TDMS, and display sample output.\nThere are comments explaining what it is doing, so you can follow along with what is being setup and created at each stage.\nWe 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`.\n\n\u003cdetails\u003e\n\u003csummary\u003eTroubleshooting\u003c/summary\u003e\n\nWe've seen that launching MATLAB on MacOS via the launcher (cmd + space) may not preserve the system `PATH`.\n\n```\ncommand not found: tdms\n```\n\nAssuming `tdms --help` works in a new terminal, try launching MATLAB _from_ that terminal.\n\n```{sh}\n$ tdms --help\n$ /Applications/MATLAB_\u003cversion\u003e.app/bin/matlab\n```\n\nThe MATLAB example scripts should then find `tdms`.\nIf you still have problems, you can try hard-coding the full path to `tdms` into the MATLAB script.\n\nIn a terminal run\n\n```{sh}\n$ which tdms\n```\n\nCopy 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.\n\n\u003c/details\u003e\n\n### MATLAB file version\n\nIn order to be readable by TDMS, files need to be saved in .mat (MATLAB file) version 7.3 or newer.\nThis can be done by passing '-v7.3' to MATLAB's save command as the final argument, for example:\n\n```\nsave('my_input_file.mat', 'my_input_var_1', 'my_input_var_2', ..., 'my_input_var_N', '-v7.3');\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOr set v7.3 as the default in MATLAB's settings.\u003c/summary\u003e\n\n![](doc/assets/matlab-file-settings.png)\n\n\u003c/details\u003e\n\n### On the command line\n\nIf 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.\nYou can choose between two solver methods: **finite-difference** or **pseudo-spectral**, as well as two interpolation methods: **cubic** or **bandlimited**.\nThese options can be selected by setting the corresponding flag variables in the input file.\nWhen `tdms` reads the input, it will verify if the input file contains a dataset that matches the names of these flags.\n\nThere are two flags available for configuration in the input file.\n\u003cdetails\u003e\n\u003csummary\u003e `use_pstd` \u003c/summary\u003e\n- If not provided, or provided as `false`, then the default timestepping method of finite-differences (FDTD) will be used.\n- If present and set to `true`, then `tdms` will use the pseudo-spectral (PSTD) method when performing simulation timesteps.\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e `use_bli` \u003c/summary\u003e\n- If not provided, or provided as `false`, then the default interpolation method of cubic interpolation will be used to obtain field values at the centres of Yee cells.\n- If present and set to `true`, then `tdms` will use bandlimited interpolation (BLI) when obtaining field values at Yee cell centres.\n\n\\note Typically bandlimited interpolation is superior to cubic interpolation when the extent of the Yee cell is of approximately the same order as, but slightly less than, one-sixth of the shortest wavelength of interest.\nOtherwise, cubic interpolation typically enjoys superior accuracy.\n\u003c/details\u003e\n\nTDMS is parallelised with [OpenMP](https://en.wikipedia.org/wiki/OpenMP).\nYou can set the maximum number of threads using the `OMP_NUM_THREADS` environment variable before calling the TDMS executable.\n```{sh}\n$ export OMP_NUM_THREADS=4 # for example\n```\n\n## Citation\n\nIf you used TDMS in your research and found it helpful, please cite this work: [10.5281/zenodo.7950604](https://doi.org/10.5281/zenodo.7950604).\n\n\u003c!-- If you use TDMS in your work and have examples that you would like to share with other users, please get in touch with us at --\u003e\n\u003c!-- [contact_address)[mailto:FIXME] --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eBibTEX\u003c/summary\u003e\n\n```bibtex\n@software{tdms,\n    author       = {Munro, Peter and others},\n    license      = {GPL-3.0},\n    title        = {{TDMS - The Time-Domain Maxwell Solver}},\n    URL          = {https://github.com/UCL/TDMS},\n    publisher    = {Zenodo},\n    doi          = {10.5281/zenodo.7950603}\n}\n```\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eLaTeX\u003c/summary\u003e\n\n```tex\n\\bibitem{tdms}\nP. Munro, et al \\emph{TDMS - The Time-Domain Maxwell Solver}, \\url{https://github.com/UCL/TDMS}, \\href{https://doi.org/10.5281/zenodo.7950603}{10.5281/zenodo.7950603}.\n```\n\n\u003c/details\u003e\n\n## Acknowledgements\n\nThe 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](https://ucl.ac.uk/medphys) and [Centre for Advanced Research Computing](https://ucl.ac.uk/arc) with generous funding from the [Royal Society](https://royalsociety.org).\n\n![medphys](doc/assets/biomedlogo.png)\u0026nbsp;![arc](doc/assets/arclogo.png)\n\nDevelopment of this software has previously benefited from funding from the [Commonwealth Scholarships Commission](https://cscuk.fcdo.gov.uk/about-us/scholarships-and-fellowships/), the [Engineering and Physical Sciences Research Council](https://www.ukri.org/councils/epsrc/), and the [Australian Research Council](https://www.arc.gov.au/).\n\n## Want to contribute?\n\nWe're grateful for bug reports, feature requests, and pull requests. Please see our [contribution guidelines](https://github-pages.ucl.ac.uk/TDMS/md__c_o_n_t_r_i_b_u_t_i_n_g.html) (we also have some [developer documentation](https://github-pages.ucl.ac.uk/TDMS/md_doc_developers.html)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucl%2Ftdms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucl%2Ftdms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucl%2Ftdms/lists"}