Hyperion Manual Release 0.9.8
Total Page:16
File Type:pdf, Size:1020Kb
Hyperion Manual Release 0.9.8 Thomas Robitaille May 14, 2018 Contents 1 Introduction 1 2 Note on units and constants 3 3 Documentation 5 4 Advanced 95 5 Credits 209 i ii CHAPTER 1 Introduction This is the documentation for Hyperion, a three-dimensional dust continuum Monte-Carlo radiative transfer code. Models are set up via Python scripts, and are run using a compiled Fortran code, optionally making use of the Message Passing Interface (MPI) for parallel computing. Important: Before you proceed, please make sure you have read the following disclaimers: • The developers cannot guarantee that the code is bug-free, and users should sign up to the mailing list to ensure that they are informed as soon as bugs are identified and fixed. The developers cannot be held responsible for incorrect results, regardless of whether these arise from incorrect usage, a bug in the code, or a mistake in the documentation. • Users should read the Important Notes before using Hyperion. In particular, users are fully responsible for ensuring that parameters such as photon numbers and grid resolution are adequate for the problem being studied. Hyperion will not raise errors if these inputs are inadequate. If your work makes use of Hyperion, please cite: Robitaille, 2011, HYPERION: an open-source parallelized three-dimensional dust continuum radiative transfer code, Astronomy & Astrophysics 536 A79 (ADS, BibTeX). If you need consulting on using Hyperion beyond the current documentation, then please contact me with details of your project. 1 Hyperion Manual, Release 0.9.8 2 Chapter 1. Introduction CHAPTER 2 Note on units and constants All quantities in Hyperion are expressed in the cgs system. Throughout the documentation, constants are sometimes used in place of values (e.g. au, pc). These can be imported (in Python) using: from hyperion.util.constants import * or, to control which constants are imported: from hyperion.util.constants import au, pc, lsun See hyperion.util.constants for more details. 3 Hyperion Manual, Release 0.9.8 4 Chapter 2. Note on units and constants CHAPTER 3 Documentation 3.1 Installation Important: This section contains information on setting up the dependencies for Hyperion as well as Hyperion itself. If you have any issues with the installation of any of the dependencies or Hyperion, please first talk to your system administrator to see if they can help you get set up! 3.1.1 The easy way The easiest way to install Hyperion and all the dependencies on MacOS X or Linux is to use the Anaconda Python Distribution or Miniconda. Once you have either of these set up, you can install Hyperion by simply doing: conda install-c conda-forge hyperion This will install both the Fortran binaries and the Python library for Hyperion (as well as all the dependencies including MPI and HDF5). That’s it! You can check that the installation works by making sure that the following commands do not return ‘command not found’: $ hyperion usage: hyperion [-h] [-f] [-m n_cores] input output hyperion: error: the following arguments are required: input, output $ hyperion_car Usage: hyperion_car [-f] input_file output_file If you see the same as the above, you are all set! 5 Hyperion Manual, Release 0.9.8 3.1.2 The longer way Dependencies First, you will need to install several dependencies for the Fortran and Python versions of Hyperion. Choose your own adventure! Installing dependencies on Debian/Ubuntu (requires root) Fortran dependencies The Fortran Hyperion code requires a Fortran compiler, HDF5 and MPICH2. You can install these dependencies with: sudo apt-get install libmpich2-dev libhdf5-serial-dev Python dependencies If you use the system Python installation, you can install the dependencies for the Python code with: sudo apt-get install python-numpy python-dev python-astropy python-h5py python- ,!matplotlib If instead you use the Anaconda Python Distribution you can install the Python dependencies with: conda install numpy matplotlib h5py astropy Hyperion You are now ready to install Hyperion. Proceed to the Hyperion installation instructions! Installing dependencies on Fedora (requires root) Fortran dependencies The Fortran Hyperion code requires a Fortran compiler, HDF5 and MPICH2. You can install these dependencies with: sudo yum install hdf5-static mpich-devel libgfortran-static export PATH=/usr/lib64/mpich/bin:$PATH Python dependencies If you use the system Python installation, you can install the dependencies for the Python code with: sudo yum install gcc-c++ numpy h5py python-matplotlib python-astropy 6 Chapter 3. Documentation Hyperion Manual, Release 0.9.8 If instead you use the Anaconda Python Distribution you can install the Python dependencies with: conda install numpy matplotlib h5py astropy Hyperion You are now ready to install Hyperion. Proceed to the Hyperion installation instructions! Installing dependencies on CentOS and Scientific Linux (requires root) Note: The HDF5 and Astropy packages are not available for these distributions, so a few additional steps are needed. Fortran dependencies The Fortran Hyperion code requires a Fortran compiler, HDF5 and MPICH2. You can install some of these dependencies with: sudo yum install mpich-devel gcc-gfortran libgfortran-static export PATH=/usr/lib64/mpich/bin:$PATH Then you can install HDF5 with: wget https://raw.githubusercontent.com/hyperion-rt/hyperion/master/deps/fortran/ ,!install.py sudo python install.py/usr/local--only-hdf5 You can ignore the message about setting the PATH, since /usr/local/bin should already be in your PATH by default. Python dependencies If you use the system Python installation, you can install some of the dependencies for the Python code with: sudo yum install gcc-c++ python-devel numpy python-matplotlib Cython then you can install h5py and Astropy: sudo easy_install pip pip install six--user--upgrade pip install h5py astropy--user If instead you use the Anaconda Python Distribution you can install the Python dependencies with: conda install numpy matplotlib h5py astropy Hyperion You are now ready to install Hyperion. Proceed to the Hyperion installation instructions! 3.1. Installation 7 Hyperion Manual, Release 0.9.8 Installing dependencies on Linux without root access Fortran dependencies Note that in order to proceed you will need a Fortran compiler such as gfortran or ifort (there is no easy way to install a Fortran compiler without root access). To install HDF5 and MPICH2, which are required by Hyperion, you can do: wget https://raw.githubusercontent.com/hyperion-rt/hyperion/master/deps/fortran/ ,!install.py python install.py $HOME/usr Then, make sure that $HOME/usr/bin is in your $PATH. If you use bash for example, you would do this with: export PATH=$HOME/usr/bin:$PATH Next, open a new terminal and ensure that the following commands: which mpif90 which h5fc return valid paths inside $HOME/usr/bin: $ which mpif90 /home/tom/bin/mpif90 $ which h5fc /home/tom/bin/h5fc If you get command not found then you have probably not set up your $PATH correctly. The installation script has a number of options (e.g. to set the compilers) that can be seen with: python install.py--help If the installation fails, a log will be posted to the Pastebin service. Copy the URL and report it either by email or on the Github Issues. Python dependencies Download and install the free Anaconda Python Distribution, which is a scientific linux distribution that contains all the dependencies required by Hyperion. By default, this will be installed to your home directory and will not require root access. Once you have installed it, you can check that you are indeed using the Python version from Anaconda by typing: python--version and you should see something like: Python 2.7.10 :: Continuum Analytics, Inc Hyperion You are now ready to install Hyperion. Proceed to the Hyperion installation instructions! 8 Chapter 3. Documentation Hyperion Manual, Release 0.9.8 Installing dependencies on MacOS X Fortran compiler The first dependency is a Fortran compiler. In addition to commercial compilers (e.g. ifort, pgfortran, . ), there are a couple of free ones, the most common of which is gfortran. If you don’t already have a compiler installed, you can install gfortran via package managers on Linux machines, or from MacPorts or binary installers on Mac (e.g. http://gcc.gnu.org/wiki/GFortranBinaries). If you are unsure about how to do this, speak to your system administrator. Fortran dependencies To install HDF5 and MPICH2, which are required by Hyperion, you can do: wget https://raw.githubusercontent.com/hyperion-rt/hyperion/master/deps/fortran/ ,!install.py sudo python install.py/usr/local Next, open a new terminal and ensure that the following commands: which mpif90 which h5fc return the following: $ which mpif90 /usr/local/bin/mpif90 $ which h5fc /usr/local/bin/h5fc If you get command not found then you will need to make sure /usr/local/bin is in your $PATH (it should be by default though). The installation script has a number of options (e.g. to set the compilers) that can be seen with: python install.py--help If the installation fails, a log will be posted to the Pastebin service. Copy the URL and report it either by email or on the Github Issues. If you don’t have root access, you can do: sudo python install.py $HOME/usr Then be sure to add $HOME/usr/bin to your $PATH: export PATH=$HOME/usr/bin:$PATH Python dependencies Download and install the free Anaconda Python Distribution, which is a scientific linux distribution that contains all the dependencies required by Hyperion. By default, this will be installed to your home directory and will not require root access. Once you have installed it, you can check that you are indeed using the Python version from Anaconda by typing: 3.1.