README.md

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