From 578211ff30763692a86fc6c2c689850410d72790 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Ne=C4=8Dada?= Date: Tue, 11 Jun 2019 17:28:15 +0300 Subject: [PATCH] README update, include to Doxyfile. Former-commit-id: cab9d665ae32308d1669dad426a7a84accc4ac6f --- Doxyfile | 4 +- Triton-troubleshooting.md => README.Triton.md | 0 README.md | 84 +++++++++++++++++++ README.rst | 40 --------- 4 files changed, 86 insertions(+), 42 deletions(-) rename Triton-troubleshooting.md => README.Triton.md (100%) create mode 100644 README.md delete mode 100644 README.rst diff --git a/Doxyfile b/Doxyfile index a09c854..4c723bb 100644 --- a/Doxyfile +++ b/Doxyfile @@ -753,7 +753,7 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = qpms +INPUT = qpms finite_systems.md README.md README.Triton.md finite_systems.md lattices.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -889,7 +889,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/Triton-troubleshooting.md b/README.Triton.md similarity index 100% rename from Triton-troubleshooting.md rename to README.Triton.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ae171c6 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ +QPMS README +=========== + +QPMS is a toolkit for frequency-domain simulations of photonic systems +consisting of compact objects (particles) inside a homogeneous medium. Scattering +properties of the individual particles are described by their T-matrices +(which can be obtained e.g. with the `scuff-tmatrix` tool from +the [SCUFF-EM] suite). + +QPMS handles the multiple scattering of electromagnetic radiation between +the particles. The system can consist either of a finite number of particles +or an infinite number of periodically arranged lattices (with finite number +of particles in a single unit cell). + +Features +======== + +Finite systems +-------------- + * Computing multipole excitations *and fields (TODO)* scattered from nanoparticle + clusters illuminated by plane, spherical or *cylindrical (TODO)* waves. + * Finding eigenmodes. + * *Calculating cross sections (TODO).* + * Reducing numerical complexity of the computations by exploiting + symmetries of the cluster (decomposition to irreducible representations). + +Infinite systems (lattices) +--------------------------- + * 2D-periodic systems supported. (TODO 1D and 3D.) + * *Calculation of transmission and reflection properties (TODO).* + * Finding eigenmodes and calculating dispersion relations. + * *Calculation of far-field radiation patterns of an excited array (TODO).* + * Reducing numerical complexity of the computations by exploiting + symmetries of the lattice (decomposition to irreducible representations). + + +Installation +============ +The package depends on several python modules and GSL (>= 2.0). +The python module dependencies should be installed automatically when running +the installation script. If you have a recent enough OS, +you can get GSL easily from the repositories; on Debian and derivatives, +just run `apt-get install libgsl-dev` under root. Alternatively, +you can [get the source and compile it yourself][GSL]. + +You also need a fresh enough version of [cmake][]. + +After GSL is installed, you can install qpms to your local python library using:: + +``` + cmake . + make amos + python3 setup.py install --user +``` + +If GSL is not installed the standard library path on your system, you might +need to pass it to the installation script using the +`LIBRARY_PATH` and `LD_LIBRARY_PATH` environment +variables. + +Special care has often be taken when installing QPMS in cluster environments. +Specific installation instructions for Aalto University's Triton cluster +can be found in a [separate document][TRITON-README]. + +Documentation +============= + +Documentation of QPMS is a work in progress. Most of the newer code +is documented using doxygen comments. To build the documentation, just run +`doxygen` +in the root directory; the documentation will then be found in +`docs/html/index.html`. + +Of course, the prerequisite of this is having doxygen installed. +If you don't, you will probably find it easily in your OS's +repositories. On Debian and derivatives, simply run `apt-get install doxygen` +under root. + + +[SCUFF-EM]: https://homerreid.github.io/scuff-em-documentation/ +[GSL]: https://www.gnu.org/software/gsl/ +[cmake]: https://cmake.org +[TRITON-README]: README.Triton.md + diff --git a/README.rst b/README.rst deleted file mode 100644 index 4ce7002..0000000 --- a/README.rst +++ /dev/null @@ -1,40 +0,0 @@ -Quantum photonic multiple scattering -==================================== - -TODO description - -Installation -============ -The package depends on several python modules and GSL (>= 2.0). -The python module dependencies should be installed automatically when running -the installation script. If you have a recent enough OS, -you can get GSL easily from the repositories; on Debian and derivatives, -just run ``apt-get install libgsl-dev`` under root. Alternatively, -you can `get the source -`_ get the source and compile it yourself. - -You also need a fresh enough version of ``cmake``. - -After GSL is installed, you can install qpms to your local python library using:: - - cmake . - make amos - python3 setup.py install --user - -If GSL is not installed the standard library path on your system, you might -need to pass it to the installation script using the LD_LIBRARY_PATH environment -variable. - -Documentation -============= - -Documentation of QPMS is a work in progress. Most of the newer code -is documented using doxygen comments. To build the documentation, just run -``doxygen`` -in the root directory; the documentation will then be found in -``docs/html/index.html``. - -Of course, the prerequisite of this is having doxygen installed. -If you don't, you will probably find it easily in your OS's -repositories. On Debian and derivatives, simply run ``apt-get install doxygen`` -under root.