README.md

   1 QPMS README
   2 ===========
   3
   4 QPMS (standing for QPMS Photonic Multiple Scattering)
   5 is a toolkit for frequency-domain simulations of photonic systems
   6 consisting of compact objects (particles) inside a homogeneous medium. Scattering
   7 properties of the individual particles are described by their T-matrices
   8 (which can be obtained using one of the built-in generators or
   9  e.g. with the `scuff-tmatrix` tool from
  10 the [SCUFF-EM] suite).
  11
  12 QPMS handles the multiple scattering of electromagnetic radiation between
  13 the particles. The system can consist either of a finite number of particles
  14 or an infinite number of periodically arranged lattices (with finite number
  15 of particles in a single unit cell).
  16
  17
  18 Features
  19 ========
  20
  21
  22 Finite systems
  23 --------------
  24  * Computing multipole excitations and fields scattered from nanoparticle
  25    clusters illuminated by plane, spherical or *cylindrical (TODO)* waves.
  26  * Finding eigenmodes (optical resonances).
  27  * Calculating cross sections.
  28  * Reducing numerical complexity of the computations by exploiting
  29    symmetries of the cluster (decomposition to irreducible representations).
  30
  31
  32 Infinite systems (lattices)
  33 ---------------------------
  34  * 2D-periodic systems with arbitrary unit cell geometry supported. (TODO 1D and 3D.)
  35  * Computing multipole excitations and fields scattered from nanoparticle
  36  * Finding eigenmodes and calculating dispersion relations.
  37  * Calculation of the scattered fields.
  38  * *Calculation of total transmission and reflection properties (TODO).*
  39  * *Reducing numerical complexity of the computations by exploiting
  40    symmetries of the lattice (decomposition to irreducible representations) (in development).*
  41
  42
  43 Getting the code
  44 ================
  45
  46 The main upstream public repository is located at <https://repo.or.cz/qpms.git>.
  47 Just clone the repository with `git` and proceed to the installation instructions
  48 below.
  49
  50
  51 Installation
  52 ============
  53 The package depends on several python modules, a BLAS/LAPACK library with
  54 the respective C bindings (incl. the `lapacke.h` and `cblas.h` headers;
  55 [OpenBLAS][OpenBLAS] does have it all and is recommended) and GSL (>= 2.0).
  56 The python module dependencies should be installed automatically when running
  57 the installation script. If you have a recent enough OS,
  58 you can get GSL easily from the repositories; on Debian and derivatives,
  59 just run `apt-get install libgsl-dev` under root. Alternatively,
  60 you can [get the source and compile it yourself][GSL].
  61
  62 You also need a fresh enough version of [cmake][].
  63
  64 QPMS uses a C version of the Amos library for calculating Bessel function
  65 from a submodule. Before proceeding with running `cmake`, the submodules
  66 need to be downloaded first (in the QPMS source root directory):
  67
  68 ```{.sh}
  69   git submodule init
  70   git submodule update
  71 ```
  72
  73 After GSL is installed and submodules updated, you can install qpms to your local python library using
  74
  75 ```{.sh}
  76   cmake -DCMAKE_INSTALL_PREFIX=${YOUR_PREFIX} .
  77   make install
  78   python3 setup.py install --user
  79 ```
  80 Above, replace `${YOUR_PREFIX}` with the path to where you want to install the shared library;
  81 you will also need to make sure that the linker can find it;
  82 on Linux, this means the path `${YOUR_PREFIX}/lib` is included in your
  83 `LIBRARY_PATH` and `LD_LIBRARY_PATH` environment variables. The same applies
  84 to the GSL and OpenBLAS dependencies: they must be installed where the
  85 installation scripts and linker can find them (setting the `C_INCLUDE_PATH` environment
  86 variable might be necessary as well).
  87
  88 Special care might need to be taken when installing QPMS in cluster environments.
  89 Specific installation instructions for Aalto University's Triton cluster
  90 can be found in a [separate document][TRITON-README].
  91
  92
  93 Documentation
  94 =============
  95
  96 Documentation of QPMS is a work in progress. Most of the newer code
  97 is documented using [doxygen][] comments. To build the documentation, just run
  98 `doxygen`
  99 in the root directory; the documentation will then be found in
 100 `docs/html/index.html`.
 101
 102 Of course, the prerequisite of this is having doxygen installed.
 103 If you don't, you will probably find it easily in your OS's
 104 repositories. On Debian and derivatives, simply run `apt-get install doxygen`
 105 under root.
 106
 107
 108 Tutorials
 109 ---------
 110
 111   * [Finite system tutorial][tutorial-finite]
 112
 113 See also the examples directory in the source repository.
 114
 115
 116 Command line utilities
 117 ----------------------
 118
 119   * [Overview of the Python command line utilities][cliutils]
 120
 121
 122 Acknowledgments
 123 ================
 124
 125 This software has been developed in the [Quantum Dynamics research group][QD],
 126 Aalto University, Finland. If you use the code in your work, please cite
 127 **M. Nečada and P. Törmä, Multiple-scattering T-matrix simulations for nanophotonics: symmetries and periodic lattices, [arXiv: 2006.12968][lepaper] (2020)**
 128 in your publications, presentations, and similar.
 129
 130 Please also have a look at other publications by the group
 131 (google scholar Päivi Törmä), they may be useful for your work as well.
 132
 133
 134 Bug reports
 135 ===========
 136
 137 If you believe that some parts of QPMS behave incorrectly, please mail
 138 a bug report to [marek@necada.org][authormail]. To ensure that your message is not
 139 considered spam, please start the subject line with `QPMS`.
 140
 141 If you were able to fix a bug yourself, please include the patch as well,
 142 see below.
 143
 144
 145 Contributions
 146 =============
 147
 148 Contributions to QPMS are welcome, be it bug fixes, improvements to the
 149 documentation, code quality, or new features.
 150
 151 You can send patches prepared using the
 152 [`git format-patch`](https://git-scm.com/docs/git-format-patch) tool
 153 to [marek@necada.org][authormail].
 154
 155 If you plan to contribute with major changes to the codebase, it is
 156 recommended to discuss that first (see the contact information below).
 157
 158
 159 Contact & discussion
 160 ====================
 161
 162 You can contact the main author e.g. via [e-mail][authormail]
 163 or [Telegram](https://t.me/necadam).
 164
 165 You are also warmly welcome to the [QPMS user chat][telegramchat]
 166 in Telegram!
 167
 168
 169
 170 [SCUFF-EM]: https://homerreid.github.io/scuff-em-documentation/
 171 [OpenBLAS]: https://www.openblas.net/
 172 [GSL]: https://www.gnu.org/software/gsl/
 173 [cmake]: https://cmake.org
 174 [TRITON-README]: README.Triton.md
 175 [tutorial-finite]: finite_systems.md
 176 [tutorial-infinite]: lattices.md
 177 [doxygen]: http://doxygen.nl/
 178 [QD]: https://www.aalto.fi/en/department-of-applied-physics/quantum-dynamics-qd
 179 [lepaper]: https://arxiv.org/abs/2006.12968
 180 [telegramchat]: https://t.me/QPMScattering
 181 [authormail]: mailto:marek@necada.org
 182 [cliutils]: CLIUTILS.md