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 Features
  18 ========
  19
  20 Finite systems
  21 --------------
  22  * Computing multipole excitations and fields scattered from nanoparticle
  23    clusters illuminated by plane, spherical or *cylindrical (TODO)* waves.
  24  * Finding eigenmodes (optical resonances).
  25  * Calculating cross sections.
  26  * Reducing numerical complexity of the computations by exploiting
  27    symmetries of the cluster (decomposition to irreducible representations).
  28
  29
  30 Infinite systems (lattices)
  31 ---------------------------
  32  * 2D-periodic systems with arbitrary unit cell geometry supported. (TODO 1D and 3D.)
  33  * Computing multipole excitations and fields scattered from nanoparticle
  34    arrays illuminated by plane (or other periodic) waves.
  35  * Finding eigenmodes and calculating dispersion relations.
  36  * Calculation of the scattered fields.
  37  * *Calculation of total transmission and reflection properties (TODO).*
  38  * *Reducing numerical complexity of the computations by exploiting
  39    symmetries of the lattice (decomposition to irreducible representations) (in development).*
  40
  41
  42 Installation
  43 ============
  44 The package depends on several python modules, a BLAS/LAPACK library with
  45 the respective C bindings (incl. the `lapacke.h` and `cblas.h` headers;
  46 [OpenBLAS][OpenBLAS] does have it all and is recommended) and GSL (>= 2.0).
  47 The python module dependencies should be installed automatically when running
  48 the installation script. If you have a recent enough OS,
  49 you can get GSL easily from the repositories; on Debian and derivatives,
  50 just run `apt-get install libgsl-dev` under root. Alternatively,
  51 you can [get the source and compile it yourself][GSL].
  52
  53 You also need a fresh enough version of [cmake][].
  54
  55 QPMS uses a C version of the Amos library for calculating Bessel function
  56 from a submodule. Before proceeding with running `cmake`, the submodules
  57 need to be downloaded first (in the QPMS source root directory):
  58
  59 ```{.sh}
  60   git submodule init
  61   git submodule update
  62 ```
  63
  64 After GSL is installed and submodules updated, you can install qpms to your local python library using
  65
  66 ```{.sh}
  67   cmake -DCMAKE_INSTALL_PREFIX=${YOUR_PREFIX} .
  68   make install
  69   python3 setup.py install --user
  70 ```
  71 Above, replace `${YOUR_PREFIX}` with the path to where you want to install the shared library;
  72 you will also need to make sure that the linker can find it;
  73 on Linux, this means the path `${YOUR_PREFIX}/lib` is included in your
  74 `LIBRARY_PATH` and `LD_LIBRARY_PATH` environment variables. The same applies
  75 to the GSL and OpenBLAS dependencies: they must be installed where the
  76 installation scripts and linker can find them (setting the `C_INCLUDE_PATH` environment
  77 variable might be necessary as well).
  78
  79 Special care might need to be taken when installing QPMS in cluster environments.
  80 Specific installation instructions for Aalto University's Triton cluster
  81 can be found in a [separate document][TRITON-README].
  82
  83
  84 Documentation
  85 =============
  86
  87 Documentation of QPMS is a work in progress. Most of the newer code
  88 is documented using [doxygen][] comments. To build the documentation, just run
  89 `doxygen`
  90 in the root directory; the documentation will then be found in
  91 `docs/html/index.html`.
  92
  93 Of course, the prerequisite of this is having doxygen installed.
  94 If you don't, you will probably find it easily in your OS's
  95 repositories. On Debian and derivatives, simply run `apt-get install doxygen`
  96 under root.
  97
  98
  99 Tutorials
 100 ---------
 101
 102   * [Infinite system (lattice) tutorial][tutorial-infinite]
 103   * [Finite system tutorial][tutorial-finite]
 104
 105 See also the examples directory.
 106
 107 [SCUFF-EM]: https://homerreid.github.io/scuff-em-documentation/
 108 [OpenBLAS]: https://www.openblas.net/
 109 [GSL]: https://www.gnu.org/software/gsl/
 110 [cmake]: https://cmake.org
 111 [TRITON-README]: README.Triton.md
 112 [tutorial-finite]: finite_systems.md
 113 [tutorial-infinite]: lattices.md
 114 [doxygen]: http://doxygen.nl/