From d77a1b75598131b2866fd4d5c5f378ffa1800cad Mon Sep 17 00:00:00 2001 From: Nicolas Tessore Date: Mon, 1 Jun 2015 19:38:40 +0200 Subject: [PATCH] improved handling of binary dependencies, documentation for releases --- .travis.yml | 25 ++++---- Makefile | 2 +- README.md | 62 ++++++++++++------ docs/building.md | 113 ++++++++++++++++++++++++++------ docs/dependencies.md | 28 +++++--- docs/download.md | 82 ------------------------ docs/foregrounds.md | 4 +- docs/lenses.md | 4 +- docs/licenses.md | 138 ++++++++++++++++++++++++++++++++++++++++ docs/performance.md | 4 +- docs/releases.md | 58 +++++++++++++++++ docs/results.md | 5 +- docs/sources.md | 4 +- docs/troubleshooting.md | 78 +++++++++++++++++------ docs/usage.md | 22 +++---- mkdocs.yml | 53 +++++++-------- 16 files changed, 472 insertions(+), 210 deletions(-) delete mode 100644 docs/download.md create mode 100644 docs/licenses.md create mode 100644 docs/releases.md diff --git a/.travis.yml b/.travis.yml index 3ab3987..31af4d5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,9 +5,6 @@ compiler: os: - linux - osx -env: -- MULTINEST=3.8 -- MULTINEST=3.9 notifications: email: false branches: @@ -26,11 +23,7 @@ before_install: fi - pushd /tmp && git clone git://github.com/JohannesBuchner/MultiNest.git && - cd MultiNest && - if [ "$MULTINEST" == "3.9" ]; then - curl -L http://git.io/vk01k | patch -p1; - fi && - cd build && + cd MultiNest/build && cmake .. -G "Unix Makefiles" && make && sudo make install && @@ -44,15 +37,25 @@ script: - make test before_deploy: - export RELEASE_VERSION=$(git describe --tags) -- export RELEASE_TAG=$TRAVIS_OS_NAME.multinest-$MULTINEST +- export RELEASE_TAG=$TRAVIS_OS_NAME - export RELEASE=build/lensed-$RELEASE_VERSION.$RELEASE_TAG.tar.gz - if [ "$TRAVIS_OS_NAME" = "linux" ]; then - export CFITSIO_LIB="/usr/lib/x86_64-linux-gnu/libcfitsio.a"; - export EXTRA_LIBS="/usr/lib/x86_64-linux-gnu/libz.a"; + export CFITSIO_LIB="-l:libcfitsio.a"; + export EXTRA_LIBS="-lz -Wl,-rpath='$ORIGIN'"; fi - if [ "$TRAVIS_OS_NAME" = "osx" ]; then export CFITSIO_LIB="/usr/local/lib/libcfitsio.a"; + export EXTRA_LIBS="-Wl,-rpath,@executable_path"; fi +- pushd /tmp && + cd MultiNest && + curl -L http://git.io/vkACf | patch -p1 && + cd build && + cmake .. -DCMAKE_MACOSX_RPATH=ON && + make && + sudo make install && + if [ "$TRAVIS_OS_NAME" = "linux" ]; then sudo ldconfig; fi && + popd - make distclean - make - make release diff --git a/Makefile b/Makefile index 5c59ae6..8d9dcb8 100644 --- a/Makefile +++ b/Makefile @@ -264,7 +264,7 @@ RELEASE_FILES = \ # release version from git ifndef RELEASE_VERSION -RELEASE_VERSION = $(shell git describe --tags) +RELEASE_VERSION = release endif # release tag diff --git a/README.md b/README.md index 5fb3edb..ef2db38 100644 --- a/README.md +++ b/README.md @@ -15,50 +15,72 @@ that was broken. Contributions in the form of new models are most welcome if they are generally useful. -Setup ------ +Installation +------------ + +Pre-compiled binary distributions of Lensed are available for the official +release versions, found on [GitHub](https://github.com/glenco/lensed/releases). +More information can be found in the [documentation](docs/releases.md). + +There are a number of ways to get source distributions of the code, please see +the [documentation](docs/building.md). -There are a number of dependencies for Lensed (see docs/dependencies.md). Once -they are satisfied and installed into the system, it should be possible to run -or compile Lensed. -If you are building Lensed from source, is typically enough to run +Building +-------- + +Lensed is a simple Makefile project. If all dependencies are satisfied and +installed into the system, it should be possible to compile Lensed by simply +calling $ make -in the root of the source directory, and the code should start compiling. +from the root of the source directory. For further information, please refer to +the [documentation](docs/building.md). Usage ----- -The most common way to invoke Lensed is to create a configuration file (see -docs/configuration.md) which contains both the program options and the model -that is being reconstructed. In this case, the reconstruction is started using +The usual invocation of Lensed is with a [configuration](docs/configuration.md) +file which contains program options and the model that is being reconstructed. +The reconstruction is started using $ lensed config.ini -where `config.ini` is the name of the parameter file. +where `config.ini` is the name of the configuration file. -It is possible to split the configuration into different configuration files, -in order to e.g. modularise options and individual aspects of the model. For -example, the following command would run Lensed with the configuration taken -from three different files: +It is possible to split the configuration into different files, for example to +modularise options and individual aspects of the model. The following command +would run Lensed with the configuration taken from three different files: $ lensed options.ini lens.ini sources.ini Repeated options are overwritten by the later configuration files. -Finally, it is possible to give all of the options of a configuration file -directly on the command line. For example, in order to change the number of -live points for a quick look at results, one could invoke Lensed in the -following way: +Finally, it is possible to give any of the options (but not the model) directly +on the command line. For example, in order to change the number of live points +for a quick look at results, one could invoke Lensed in the following way: $ lensed config.ini --nlive=50 As before, the order of the given configuration files and options is important. -For more information on how to run Lensed, see the [documentation]. + +License +------- + +The Lensed source code can be freely modified and distributed under the terms +of the [MIT license](LICENSE.txt). The authors also kindly ask that any and all +scientific work which benefits from this software cites the relevant articles. + +This software makes use of the following libraries from third parties: + +- MultiNest, copyrighted by Farhan Feroz and Mike Hobson, with some + limitations (especially for commercial use) +- CFITSIO + +Please see the [licenses file](docs/licenses.md) for copyright information. Versions diff --git a/docs/building.md b/docs/building.md index 943095e..a3553c5 100644 --- a/docs/building.md +++ b/docs/building.md @@ -1,5 +1,5 @@ -Building Lensed -=============== +Building from source +==================== Lensed is a standard Makefile project. On a system where all dependencies can be resolved automatically, it should be enough to call @@ -9,7 +9,7 @@ $ make ``` from the root folder of Lensed to build the program. If this fails, further -[configuration](#configuration) might be necessary. +[configuration of the build system](#build-configuration) might be necessary. After compilation has finished, a quick check of @@ -21,8 +21,84 @@ lensed X.Y.Z should display the correct version number of Lensed. -Configuration -------------- +Getting the sources +------------------- + +### Releases + +Sources are available for each release of Lensed. These can be downloaded from +the [releases page](https://github.com/glenco/lensed/releases). For details on +releases, see the [corresponding page](releases.md). + + +### Using Git + +Lensed is developed using the [Git version control system](https://git-scm.com) +and [hosted on GitHub](https://github.com/glenco/lensed). Use Git to get the +most recent development version of the code, especially if you plan on taking +part in extending the code or fixing bugs. + +With Git installed on your system, use + +```sh +$ git clone https://github.com/glenco/lensed.git +``` + +to clone the most recent version of the code into a subfolder of the current +directory. + +There is a lot of information available about Git. For a first introduction, +please [refer to the documentation](https://git-scm.com/doc), especially the +first two chapters on [getting started](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) +and the [Git basics](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository). +A quick introduction can also be found in the [Git tutorial](http://git-scm.com/docs/gittutorial). + + +### From an archive + +On systems where no Git client is available, it is alternatively possible to +get the latest development version of the sources in the form of an archive. +A link is provided at the [project page](https://github.com/glenco/lensed). + +When working in a terminal environment, it is possible to download and extract +Lensed using a combination of cURL and tar with the following command: + +```sh +$ curl -L https://github.com/glenco/lensed/archive/master.tar.gz | tar -xz +``` + +Alternatively, if `curl` is not available, you can try to use `wget` instead: + +```sh +$ wget https://github.com/glenco/lensed/archive/master.tar.gz +$ tar -xzf master.tar.gz +``` + +Finally, if `tar` is not available you can replace the `.tar.gz` extension by +`.zip`, and try the `unzip` command. + +Please note that using this method to get Lensed, it will not be possible to +commit your changes or bug fixes back into the code base. Use of this method is +therefore discouraged for normal development work, and only intended for the +distribution of the code to "difficult" environments. + + +Dependencies +------------ + +Building from source requires a number of dependencies to be met, namely + +- MultiNest >= 3.8 , +- CFITSIO 3 , +- OpenCL headers and runtime library . + +If these dependencies are installed in a system-wide, default-accessible path, +Lensed should be able to find them without any further intervention. For more +information, refer to the [dependencies page](dependencies.md). + + +Build configuration +------------------- There are a number of configuration variables that can be passed to Lensed's build system. They are given in the form of `NAME="value"` pairs to `make`, @@ -69,16 +145,15 @@ OPENCL_LIB = -framework OpenCL EXTRA_LIBS = ``` -Please note that the `_INCLUDE_DIR` and `_LIB_DIR` variables override the value -of the corresponding `_DIR` variable, so either the former two or the latter -should be set. +Please note that the `XYZ_INCLUDE_DIR` and `XYZ_LIB_DIR` variables override the +value of the corresponding `XYZ_DIR` variable, so either the former two or the +latter should be set. The following sections contain further details on configuring the individual components of Lensed. -CFITSIO -------- +### CFITSIO If CFITSIO has been built from source, the path to the source folder can be given to Lensed using the `CFITSIO_DIR` variable. @@ -106,8 +181,7 @@ $ make CFITSIO_LIB="$HOME/libraries/my-cfitsio-lib.a" ``` -MultiNest ---------- +### MultiNest In case MultiNest was built using CMake, it is usually enough to pass the path to the source folder to make using the `MULTINEST_DIR` variable. @@ -144,14 +218,18 @@ $ make MULTINEST_INCLUDE_DIR="/path/to/multinest/example_eggbox_C" \ ``` -OpenCL ------- +### OpenCL + +* +**Mac OS X**: Please note that Mac OS X comes with a framework containing the +OpenCL headers and library. It is not necessary to change the OpenCL settings. +* In order to build Lensed, the compiler needs the OpenCL header `CL/cl.h` and the OpenCL runtime library. -If these are provided by a vendor SDK, it is usually enough to point the -`OPENCL_DIR` variable to the root of the SDK: +If these are provided by a vendor SDK, it can be enough to set the `OPENCL_DIR` +variable to the root of the SDK: ```sh $ make OPENCL_DIR="/usr/local/cuda" @@ -174,6 +252,3 @@ This can be a linker flag such as `-lOpenCL` or an explicit path to a library. ```sh $ make OPENCL_LIB="$HOME/experimental-driver/libOpenCL.so" ``` - -**Mac OS X**: Please note that Mac OS X comes with a framework containing the -OpenCL headers and library. It is not necessary to change the OpenCL settings. diff --git a/docs/dependencies.md b/docs/dependencies.md index f1340a4..bc77cf2 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -1,10 +1,10 @@ Dependencies ============ -Lensed has a number of dependencies, namely +Lensed has a number of compile-time dependencies, namely -- [CFITSIO 3.370](#cfitsio) , -- [MultiNest 3.9](#multinest) , +- [CFITSIO 3](#cfitsio) , +- [MultiNest >= 3.8](#multinest) , - [OpenCL](#opencl) . If these dependencies are installed in a system-wide, default-accessible path, @@ -17,6 +17,10 @@ CFITSIO The [CFITSIO](http://heasarc.gsfc.nasa.gov/docs/software/fitsio/) library is the standard for reading and writing FITS files. +Binary releases are statically linked against a recent version of CFITSIO and +therefore do not depend on it. When building from source, it is necessary to +have both the CFITSIO library and the header files available. + ### Packages @@ -24,7 +28,8 @@ Because CFITSIO is a mature library, pre-compiled binary versions are often found in the repositories of package management systems. If it is possible to install new packages into the system, this is the easiest way to get CFITSIO. -**Ubuntu Linux** + +#### Ubuntu Linux For running a binary release, it should suffice to install the CFITSIO runtime: @@ -38,7 +43,8 @@ When building Lensed from source, the CFITSIO development package must be used: $ sudo apt-get install libcfitsio3-dev ``` -**Mac OS X (Homebrew)** + +#### Mac OS X (Homebrew) The CFITSIO library can be found in the default Homebrew repository. @@ -147,11 +153,15 @@ Lensed was designed from the start for heterogeneous computing environments, using [OpenCL](https://www.khronos.org/opencl/) to communicate with both CPU and GPU devices through a unified programming platform. -A OpenCL runtime library for the compute devices present in the system. When +A OpenCL runtime library for the compute devices must present in the system. +Such a library usually comes with the driver of an OpenCL-enabled device. When building Lensed from source, it is further necessary to have the OpenCL headers installed. -**Ubuntu Linux** + +### Packages + +#### Ubuntu Linux For the OpenCL runtime library, it is necessary to install the device drivers for the CPUs/GPUs present in the system. Please refer to the Ubuntu manual for @@ -164,7 +174,7 @@ The OpenCL headers necessary for compiling Lensed can be found in package $ sudo apt-get install opencl-headers ``` -**Linux (general)** +#### Linux (general) The device vendors usually provide Linux drivers and SDKs for their platforms. Some useful links are @@ -173,7 +183,7 @@ Some useful links are - [AMD APP SDK](http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing-app-sdk/) , - [Nvidia OpenCL](https://developer.nvidia.com/opencl) . -**Mac OS X** +#### Mac OS X Mac OS X ships with the libraries and headers required to build OpenCL programs by default. diff --git a/docs/download.md b/docs/download.md deleted file mode 100644 index bedcefc..0000000 --- a/docs/download.md +++ /dev/null @@ -1,82 +0,0 @@ -Get Lensed -========== - -There are a number of ways to get Lensed, depending on the intended use case -and capabilities of the system. - - -Releases --------- - -*Note: binary releases are not yet available* - -The [releases page](https://github.com/glenco/lensed/releases) contains current -and previous versions of Lensed that have been assigned a fixed version number. - -Release versions are provided in both source and binary form. The binaries are -built on the following platforms: - -- Linux: *Ubuntu 12.04 LTS* -- Mac OS X: *Mac OS X Yosemite* - -Please note that the binary versions are linked dynamically against Lensed's -[dependencies](dependencies/), which must still be satisfied. - -This method of distribution is intended primarily for users of Lensed who do -not wish to modify the source code. It is still possible to extend Lensed with -new lens and source objects. For people intending to develop Lensed, please see -the next section. - - -Using Git ---------- - -Lensed is developed using the [Git version control system](https://git-scm.com) -and [hosted on GitHub](https://github.com/glenco/lensed). Use Git to get the -most recent development version of the code, especially if you plan on taking -part in extending the code or fixing bugs. - -With Git installed on your system, use - -```sh -$ git clone https://github.com/glenco/lensed.git -``` - -to clone the most recent version of the code into a subfolder of the current -directory. - -There is a lot of information available about Git. For a first introduction, -please [refer to the documentation](https://git-scm.com/doc), especially the -first two chapters on [getting started](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) -and the [Git basics](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository). -A quick introduction can also be found in the [Git tutorial](http://git-scm.com/docs/gittutorial). - - -From an archive ---------------- - -On systems where no Git client is available, it is alternatively possible to -get the latest development version of the sources in the form of an archive. -A link is provided at the [project page](https://github.com/glenco/lensed). - -When working in a terminal environment, it is possible to download and extract -Lensed using a combination of cURL and tar with the following command: - -```sh -$ curl -L https://github.com/glenco/lensed/archive/master.tar.gz | tar -xz -``` - -Alternatively, if `curl` is not available, you can try to use `wget` instead: - -```sh -$ wget https://github.com/glenco/lensed/archive/master.tar.gz -$ tar -xzf master.tar.gz -``` - -Finally, if `tar` is not available you can replace the `.tar.gz` extension by -`.zip`, and try the `unzip` command. - -Please note that using this method to get Lensed, it will not be possible to -commit your changes or bug fixes back into the code base. Use of this method is -therefore discouraged for normal development work, and only intended for the -distribution of the code to "difficult" environments. diff --git a/docs/foregrounds.md b/docs/foregrounds.md index cbc9cdc..63b19bc 100644 --- a/docs/foregrounds.md +++ b/docs/foregrounds.md @@ -1,5 +1,5 @@ -Foreground objects -================== +Foregrounds +=========== Foreground objects are not lensed. diff --git a/docs/lenses.md b/docs/lenses.md index cc13a25..21d56b4 100644 --- a/docs/lenses.md +++ b/docs/lenses.md @@ -1,5 +1,5 @@ -Lens models -=========== +Lenses +====== SIS --- diff --git a/docs/licenses.md b/docs/licenses.md new file mode 100644 index 0000000..f924291 --- /dev/null +++ b/docs/licenses.md @@ -0,0 +1,138 @@ +Licenses +======== + +This page contains the copyright information for Lensed and libraries contained +in the binary distribution of the software. + + +Lensed +------ + +The MIT License (MIT) + +Copyright (c) 2015 Nicolas Tessore, Fabio Bellagamba, R. Benton Metcalf + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + + +MultiNest +--------- + +Copyright (c) 2010 Farhan Feroz & Mike Hobson + +Permission to include in application software or to make digital or +hard copies of part or all of this work is subject to the following +licensing agreement. + + +MultiNest License Agreement + +MultiNest (both binary and source) is copyrighted by Farhan Feroz and +Mike Hobson (hereafter, FF&MH) and ownership of all right, title and +interest in and to the Software remains with FF&MH. By using or +copying the Software, User agrees to abide by the terms of this +Agreement. + + +Non-commercial Use + +FF&MH grant to you (hereafter, User) a royalty-free, non-exclusive +right to execute, copy, modify and distribute both the binary and +source code solely for academic, research and other similar +non-commercial uses, subject to the following + +1. User acknowledges that the Software is still in the development +stage and that it is being supplied "as is," without any support +services from FF&MH. FF&MH do not make any representations or +warranties, express or implied, including, without limitation, any +representations or warranties of the merchantability or fitness for +any particular purpose, or that the application of the software, will +not infringe on any patents or other proprietary rights of others. + +2. FF&MH shall not be held liable for direct, indirect, incidental or +consequential damages arising from any claim by User or any third +party with respect to uses allowed under this Agreement, or from any +use of the Software. + +3. User agrees to fully indemnify and hold harmless FF&MH of the +original work from and against any and all claims, demands, suits, +losses, damages, costs and expenses arising out of the User's use of +the Software, including, without limitation, arising out of the User's +modification of the Software. + +4. User may modify the Software and distribute that modified work to +third parties provided that: (a) if posted separately, it clearly +acknowledges that it contains material copyrighted by FF&MH (b) no +charge is associated with such copies, (c) User agrees to notify FF&MH +of the distribution, and (d) User clearly notifies secondary users +that such modified work is not the original Software. + +5. User agrees that the authors of the original work and others may +enjoy a royalty-free, non-exclusive license to use, copy, modify and +redistribute these modifications to the Software made by the User and +distributed to third parties as a derivative work under this +agreement. + +6. This agreement will terminate immediately upon User's breach of, or +non-compliance with, any of its terms. User may be held liable for any +copyright infringement or the infringement of any other proprietary +rights in the Software that is caused or facilitated by the User's +failure to abide by the terms of this agreement. + + +Commercial Use + +Any User wishing to make a commercial use of the Software must contact +FF&MH at f.feroz@mrao.cam.ac.uk to arrange an appropriate license. +Commercial use includes (1) integrating or incorporating all or part +of the source code into a product for sale or license by, or on behalf +of, User to third parties, or (2) distribution of the binary or source +code to third parties for use with a commercial product sold or +licensed by, or on behalf of, User. + + +CFITSIO +------- + +Copyright (Unpublished--all rights reserved under the copyright laws of +the United States), U.S. Government as represented by the Administrator +of the National Aeronautics and Space Administration. No copyright is +claimed in the United States under Title 17, U.S. Code. + +Permission to freely use, copy, modify, and distribute this software +and its documentation without fee is hereby granted, provided that this +copyright notice and disclaimer of warranty appears in all copies. + +DISCLAIMER: + +THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, +EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, +ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY +IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR +PURPOSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE +DOCUMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE +SOFTWARE WILL BE ERROR FREE. IN NO EVENT SHALL NASA BE LIABLE FOR ANY +DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR +CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY +CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY, +CONTRACT, TORT , OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY +PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED +FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR +SERVICES PROVIDED HEREUNDER. + diff --git a/docs/performance.md b/docs/performance.md index c4416a5..9fac7ca 100644 --- a/docs/performance.md +++ b/docs/performance.md @@ -1,4 +1,4 @@ -Performance -=========== +Performance & tuning +==================== diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 0000000..61a6d98 --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,58 @@ +Get Lensed +========== + +The easiest way to get started with Lensed is by downloading a release version +from the [releases page](https://github.com/glenco/lensed/releases), where you +can find current and previous iterations of the code that have been assigned a +fixed version number. New versions are released often and usually do not miss +features from the development branch. + +Releases are the recommended way to run Lensed for production use. People who +intend to contribute to the development of Lensed should refer to the relevant +section on [building Lensed from source](building.md). + +Binary distributions are available for Linux and Mac OS X. When using a binary, +it is still possible to extend Lensed with new lens and source objects, as this +does not require recompiling the code. + + +Dependencies +------------ + +Binary releases of Lensed have the following dependencies: + +- [MultiNest](dependencies.md#multinest) +- [OpenCL drivers](dependencies.md#opencl) + +Source code releases have the following additional dependencies: + +- [CFITSIO](dependencies.md#cfitsio) +- OpenCL header files + +Detailed descriptions of the requirements can be found in the relevant sections +of the [dependencies page](dependencies.md). A number of common issues related +to dependencies are resolved on the [troubleshooting page](troubleshooting.md). + + +Installation +------------ + +Lensed is self-contained in its directory. The layout of the distribution is +important, as Lensed's binary located at `bin/lensed` will look for files in +the `kernel` and `objects` folders relative to its own location. Therefore, the +Lensed directory should be moved in its entirety, and individual files should +not be redistributed into various folders such as `/usr/local/bin/` or similar. + +A possibility for a system-wide installation is to move the entire directory of +Lensed to a folder such as `/usr/local/lensed` or `/opt/lensed`, and create a +symbolic link to the binary somewhere on the PATH, e.g. `/usr/local/bin/lensed` +or `/opt/bin/lensed`, as this does not interfere with the internal lookup. + + +Source releases +--------------- + +The source code for release versions is available together with the binaries. +On "special needs" systems such as clusters, it is often necessary to compile +Lensed for the particular requirements at hand. This is detailed on a [separate +page](building.md). diff --git a/docs/results.md b/docs/results.md index 4f33e9b..f20bcfd 100644 --- a/docs/results.md +++ b/docs/results.md @@ -1,4 +1,3 @@ -Results -======= - +Analysing the results +===================== diff --git a/docs/sources.md b/docs/sources.md index f29cc6a..b2743f1 100644 --- a/docs/sources.md +++ b/docs/sources.md @@ -1,5 +1,5 @@ -Source models -============= +Sources +======= The sources in Lensed are two-dimensional surface brightness distributions \\[ diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6f3d548..4f17042 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,43 +1,79 @@ Troubleshooting =============== -Contents: - [TOC] Problems running Lensed ----------------------- -### The program complains that shared libraries cannot be loaded. +### The program cannot find the MultiNest library. + +When MultiNest was not installed to a default system path such as `/usr/lib`, +it is possible that the linker cannot find the shared library `libmultinest.so` +(Linux) or `libmultinest.dylib` (Mac OS X). + +The easiest fix is to link the shared library into the `bin/` folder of Lensed, +side by side with the program executable. + +```sh +$ # in Lensed's root directory +$ cd bin +$ ls +lensed +$ ln -s /path/to/libmultinest.so # .dylib on Mac OS X +``` + +After this, the program should be able to load the shared library. + + +### The program crashes when loading the MultiNest library. + +This error usually occurs when the program tries to load a version of MultiNest +that is not binary-compatible with the one Lensed was linked against. + +For binary releases, please take a careful look at the version requirements for +the MultiNest library. For maintainability, releases are not linked against a +particular shared library version of MultiNest (i.e. `libmultinest.so.3.9` on +Linux or `libmultinest.3.9.dylib` on Mac OS X), but rather against the generic +`libmultinest.so` or `libmultinest.dylib` library. This is because MultiNest's +shared library version increases by default with every new version, even though +the libraries might be binary-compatible. To prevent either having to link the +binaries against many versions of MultiNest, or forcing users to recompile the +MultiNest library even though it is binary-compatible, the program links with +the version-less shared library name. + + +### The program complains that other shared libraries cannot be loaded. -*Note: When building Lensed, this can be fixed at the compiler level, see -[here](#the-linker-complains-that-shared-libraries-cannot-be-loaded).* +* +Note: When building Lensed, this can be fixed at the compiler level, see +[here](#the-linker-complains-that-shared-libraries-cannot-be-loaded). +* -This error occurs when the dynamic library loader cannot find the libraries -which where linked into Lensed at compile time. This is usually the case when -a pre-compiled binary is used without all [dependencies](dependencies/) present -and resolvable in the system, or when some of the libraries were moved after -the code has been compiled. +This error occurs when the dynamic library loader cannot find shared libraries +on which parts of Lensed (for example MultiNest) depends. These libraries are +usually the Fortran runtime, LAPACK or BLAS, or system libraries. To diagnose which libraries cannot be found, use (on Linux) ```sh $ ldd bin/lensed - libcfitsio.so.2 => /usr/local/lib/libcfitsio.so.2 - libmultinest.so.3.8 => /usr/local/lib/libmultinest.so.3.8 - libOpenCL.so.1 => /usr/lib64/libOpenCL.so.1 - libm.so.6 => /lib64/libm.so.6 - libc.so.6 => /lib64/libc.so.6 + libmultinest.so => /usr/local/lib/libmultinest.so + libOpenCL.so.1 => /usr/lib/fglrx/libOpenCL.so.1 + libz.so.1 => /lib/x86_64-linux-gnu/libz.so.1 + libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 + libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 + libgfortran.so.3 => /usr/lib/x86_64-linux-gnu/libgfortran.so.3 + libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 /lib64/ld-linux-x86-64.so.2 ``` or (on Mac OS X) ```sh -$ otool -L bin/lensed +$ otool -L bin/lensed bin/lensed: - /usr/local/lib/libcfitsio.2.dylib - /usr/local/lib/libmultinest.3.8.dylib + @rpath/libmultinest.dylib /System/Library/Frameworks/OpenCL.framework/Versions/A/OpenCL /usr/lib/libSystem.B.dylib ``` @@ -88,13 +124,15 @@ Problems building Lensed ### Some of Lensed's dependencies cannot be resolved. -Please see the [section on configuring](building/#configuration) the Lensed +Please see the [section on configuring](building/#build-configuration) Lensed's build system. ### The linker complains that shared libraries cannot be loaded. -*Note: This is different from required libraries that cannot be found.* +* +Note: This is different from required libraries that cannot be found. +* This issue usually occurs when some of the successfully linked shared libraries depend dynamically on further shared libraries which cannot be resolved. diff --git a/docs/usage.md b/docs/usage.md index b0b4eda..ea7a5a7 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,20 +1,19 @@ Usage ===== -The most common way to invoke Lensed is to create a configuration file (see -docs/configuration.md) which contains both the program options and the model -that is being reconstructed. In this case, the reconstruction is started using +The usual invocation of Lensed is with a [configuration](configuration.md) file +which contains program options and the model that is being reconstructed. The +reconstruction is started using ```sh $ lensed config.ini ``` -where `config.ini` is the name of the parameter file. +where `config.ini` is the name of the configuration file. -It is possible to split the configuration into different configuration files, -in order to e.g. modularise options and individual aspects of the model. For -example, the following command would run Lensed with the configuration taken -from three different files: +It is possible to split the configuration into different files, for example to +modularise options and individual aspects of the model. The following command +would run Lensed with the configuration taken from three different files: ```sh $ lensed options.ini lens.ini sources.ini @@ -22,10 +21,9 @@ $ lensed options.ini lens.ini sources.ini Repeated options are overwritten by the later configuration files. -Finally, it is possible to give all of the options of a configuration file -directly on the command line. For example, in order to change the number of -live points for a quick look at results, one could invoke Lensed in the -following way: +Finally, it is possible to give any of the options (but not the model) directly +on the command line. For example, in order to change the number of live points +for a quick look at results, one could invoke Lensed in the following way: ```sh $ lensed config.ini --nlive=50 diff --git a/mkdocs.yml b/mkdocs.yml index abbc6e5..a5873b6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,40 +3,43 @@ site_url: https://glenco.github.io/lensed/ site_author: The Lensed team site_description: > - Reconstruct gravitational lenses and lensed sources from - strong lensing observations. + Reconstruct gravitational lenses and lensed sources from + strong lensing observations. repo_url: https://github.com/glenco/lensed pages: - - [ 'index.md', 'Documentation' ] - - [ 'download.md', 'Getting started', 'Get Lensed' ] - - [ 'dependencies.md', 'Getting started', 'Dependencies' ] - - [ 'building.md', 'Getting started', 'Building' ] - - [ 'troubleshooting.md', 'Getting started', 'Troubleshooting' ] - - [ 'usage.md', 'Running Lensed', 'Usage' ] - - [ 'configuration.md', 'Running Lensed', 'Configuration files' ] - - [ 'units.md', 'Running Lensed', 'Units' ] - - [ 'results.md', 'Running Lensed', 'Results' ] - - [ 'strategies.md', 'Running Lensed', 'Modelling strategies' ] - - [ 'performance.md', 'Running Lensed', 'Performance' ] - - [ 'lenses.md', 'Objects', 'Lenses' ] - - [ 'sources.md', 'Objects', 'Sources' ] - - [ 'foregrounds.md', 'Objects', 'Foregrounds' ] - - [ 'create.md', 'Objects', 'Creating objects' ] +- 'Documentation': 'index.md' +- 'Getting started': + - 'Get Lensed': 'releases.md' + - 'Usage': 'usage.md' + - 'Building from source': 'building.md' + - 'Dependencies': 'dependencies.md' + - 'Troubleshooting': 'troubleshooting.md' +- 'Running Lensed': + - 'Configuration files': 'configuration.md' + - 'Units': 'units.md' + - 'Analysing the results': 'results.md' + - 'Modelling strategies': 'strategies.md' + - 'Performance & tuning': 'performance.md' +- 'Objects': + - 'Lenses': 'lenses.md' + - 'Sources': 'sources.md' + - 'Foregrounds': 'foregrounds.md' + - 'Creating objects': 'create.md' theme: readthedocs extra_css: - - '//cdnjs.cloudflare.com/ajax/libs/KaTeX/0.3.0/katex.min.css' - - 'lensed.css' +- '//cdnjs.cloudflare.com/ajax/libs/KaTeX/0.3.0/katex.min.css' +- 'lensed.css' extra_javascript: - - '//cdnjs.cloudflare.com/ajax/libs/KaTeX/0.3.0/katex.min.js' - - '//cdnjs.cloudflare.com/ajax/libs/KaTeX/0.3.0/contrib/auto-render.min.js' - - 'lensed.js' +- '//cdnjs.cloudflare.com/ajax/libs/KaTeX/0.3.0/katex.min.js' +- '//cdnjs.cloudflare.com/ajax/libs/KaTeX/0.3.0/contrib/auto-render.min.js' +- 'lensed.js' markdown_extensions: - - toc - - footnotes - - fenced_code +- toc +- footnotes +- fenced_code