{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Setting up and running SimCADO\n", "\n", "This notebook gives a brief overview of the practical aspects of SimCADO that you may find useful.\n", "\n", "Topics include:\n", "\n", "* [Installing and updating SimCADO](#Installing-and-updating-SimCADO)\n", "* [Running SimCADO](#Running-SimCADO)\n", " * simcado.run()\n", " * Making your own simulation chain\n", "* [Customising a simulation](#Customising-a-simulation)\n", " * Exposure times\n", " * Detector layout\n", "* [Understanding SimCADO](#Understanding-SimCADO)\n", " * The building blocks" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Installing and updating SimCADO\n", "\n", "### Installing\n", "\n", "Installing SimCADO is easy:\n", "\n", " $ pip3 install --user http://www.univie.ac.at/simcado/SimCADO.zip\n", "\n", "**Note:** The ``--user `` command is useful if you do not have write permissions for the normal python install folder. If you have full access, then it can be ignored.\n", "\n", "Once in python, SimCADO can be imported like any other package" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import simcado" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "SimCADO has several modules which contain the classes and functions that you will use. They will ont be described in detail here. This is just to make sure you know they exist." ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "collapsed": true }, "outputs": [], "source": [ "from simcado import source, commands, utils, optics" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you want to know where simcado is installed, and where the data files that SimCADO uses are located, the ``utils`` package contains the variable ``__pkg_dir__``. This is helpful when you want to view the data outside of a python session." ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "'C:\\\\Program Files\\\\Anaconda3\\\\lib\\\\site-packages\\\\simcado'" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "simcado.utils.__pkg_dir__" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Updating\n", "\n", "Quite often we will update the data files used by SimCADO. This doesn't require a full re-install of the package. SimCADO will download new files from the SimCADO website by calling ``get_extras()``.\n", "\n", "**Note** this requires that the Python package ``wget`` is installed on your system and that you have write permission for the folder where SimCADO is installed. If not, try reinstalling SimCADO with the ``--user`` parameter." ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "100% [..................................................................................] 984 / 984\n", "\n", "Downloading: default.config Version: 20170118a Size: 12KB\n", "100% [..............................................................................] 11436 / 11436\n", "\n", "PSF_POPPY.fits is already the latest version: 20161103a\n", "PSF_LTAO.fits is already the latest version: 20161108a\n", "PSF_MCAO.fits is already the latest version: 20161110a\n", "PSF_SCAO.fits is already the latest version: 20161115b\n", "FPA_nirspec_pca0.fits is already the latest version: 20161108a\n", "FPA_noise.fits is already the latest version: 20161108a\n", "TC_surface.dat is already the latest version: 20161122a\n", "TC_mirror_gold.dat is already the latest version: 20161122a\n", "TC_aluminium.dat is already the latest version: 20161215a\n", "TC_filter_J.dat is already the latest version: 20170105a\n", "TC_filter_H.dat is already the latest version: 20170105a\n", "TC_filter_Ks.dat is already the latest version: 20170105a\n", "TC_filter_Y.dat is already the latest version: 20170105a\n", "FPA_chip_layout.dat is already the latest version: 20170105a\n", "Downloading: TC_mirror_EELT.dat Version: 20170118a Size: 1KB\n", "100% [..................................................................................] 469 / 469\n", "\n", "Finished downloading data for SimCADO\n" ] } ], "source": [ "simcado.get_extras()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Creating noise frames for the H4RG detectors is time consuming, so SimCADO randomly samples from a cube of noise frames. The default installation comes with a cube with 1 layer. Therefore it is recommended to generate more frames when first running SimCADO.\n", "\n", "**Note:** the 3rd party python package for this only works on Python 3" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "simcado.install_noise_cube(n=9) # Generate n noise frames." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running SimCADO\n", "\n", "### *One function to rule them all* : simcado.run()\n", "\n", "Run a simulation by calling ``simcado.run(src=)``. For this you will need a ``Source`` object. These described in the other tutorial notebooks. You can create your own ``Source`` object or use one of the helper functions in the module ``simcado.source``." ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Detector layout\n", " id x_cen y_cen x_len y_len gain\n", "--- ----- ----- ----- ----- ----\n", " 0 0 0 1024 1024 1.7\n", "Creating 1 layer(s) per chip\n", "1 chip(s) will be simulated\n", "Reading out chip 0\n" ] }, { "data": { "text/plain": [ "[]" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "my_star = simcado.source.star(mag=20, filter_name=\"Ks\", spec_type=\"G2V\")\n", "simcado.run(src=my_star)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If no ``filename=`` is given, the detector read-outs are returned to the console. If ``filename=`` is set, SimCADO saves the read-out images to disk" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "simcado.run(src=the_sun, filename=\"test.fits\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The function ``simcado.run()`` has some useful functionality built into it. Let take a look at the function definition:" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "collapsed": true }, "outputs": [], "source": [ "simcado.run(src, filename=None, \n", " mode=\"wide\", detector_layout=\"small\", \n", " cmds=None, opt_train=None, fpa=None, \n", " return_internals=False,\n", " **kwargs)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### mode and detector_layout\n", "Two important parameters here are ``mode`` and ``detector_layout``: These two define the MICADO observing modes. \n", "\n", "Currently ``mode`` can be either ``=\"wide\"`` (4mas/pixel) or ``=\"zoom\"`` (1.5mas/pixel). \n", "\n", "The ``detector_layout`` can also be changed to speed up simulations of single objects. For example if the galaxy you're interested in is at z=5, you don't need to read out all 9 MICADO chips for each observation. In fact, a 1024x1024 window at the centre of the middle chip will probably be enough. Therefore SimCADO offers the following \"layouts\" for the detector - \"small\", \"wide\", \"full\". The default is \"small\".\n", "\n", "* ``small`` - 1x 1k-detector centred in the FoV \n", "* ``centre`` - 1x 4k-detector centred in the FoV \n", "* ``full`` - 9x 4k-detector as described by the keyword FPA_CHIP_LAYOUT\n", "\n", "#### **kwargs\n", "Kwargs stands for keyword arguments, meaning any keyword-value pair from the list of SimCADO parameters. These will be discussed in the section [Customising a simulation](#Customising-a-simulation). Suffice to say, any keyword-value pair which controls an aspect of SimCADO can be passed as an extra parameter to ``simcado.run``.\n", "\n", "### Making your own simulation chain\n", "\n", "For those who want more control over how a simulation is run. A simulation consists of three main steps:\n", "1. Creating a ``UserCommands`` list, an ``OpticalTrain`` and a ``Detector``, \n", "1. Pushing a ``Source`` through the ``OpticalTrain`` onto the ``Detector``, and\n", "1. Reading out the ``Detector``\n", "\n", "For more information on each of these object, please see the online documentation.\n", "\n", "#### 1) Setting up the optical train\n", "The first step of a simulation chain looks like this: all the information needed for the simulation is held in the ``UserCommands`` object. This is then use to set up the ``OpticalTrain`` and the ``Detector``" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Safety switch is on - Detector(..., small_fov='True')\n" ] } ], "source": [ "cmd = simcado.UserCommands()\n", "opt = simcado.OpticalTrain(cmd)\n", "fpa = simcado.Detector(cmd)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 2) Applying the optical train\n", "The second step involves calling the ``apply_optical_train()`` method in the ``Source`` object that we have already created. This propogates the light sources from the ``Source`` object through the optical train and creates an image on the detector focal plane. Hence the method requires both objects as parameters:" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": true }, "outputs": [], "source": [ "my_star.apply_optical_train(opt_train=opt, detector=fpa)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "After calling ``apply_optical_train()`` the chips in the detector object are now full of photons. We can check this:" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "collapsed": false }, "outputs": [ { "data": { "text/plain": [ "array([[ 20.11373939, 20.11373939, 20.11373939, ..., 20.11373939,\n", " 20.11373939, 20.11373939],\n", " [ 20.11373939, 20.11375038, 20.11375067, ..., 20.11375138,\n", " 20.11375212, 20.11375045],\n", " [ 20.11373939, 20.11374998, 20.11375045, ..., 20.11375115,\n", " 20.11375148, 20.11375006],\n", " ..., \n", " [ 20.11373939, 20.11374998, 20.11374987, ..., 20.11374868,\n", " 20.11374851, 20.11374866],\n", " [ 20.11373939, 20.11374757, 20.1137475 , ..., 20.1137499 ,\n", " 20.11374938, 20.1137492 ],\n", " [ 20.11373939, 20.11374791, 20.11374653, ..., 20.11375087,\n", " 20.11375036, 20.1137504 ]])" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fpa.chips[0].array" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "What we have here is the expected flux per pixel on the detector, i.e. total photons per second that will be arriving at each pixel. These values also include photons coming from non-astronomical sources, e.g. the thermal emission from the atmosphere and the mirror.\n", "\n", "#### 3) Reading out the detector\n", "The final step is to read out the detector, either into a fits file or back to the user in the form of an astropy FITS object:" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "collapsed": false }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Reading out chip 0\n" ] }, { "data": { "text/plain": [ "[]" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fpa.read_out(filename=\"test.fits\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In Summary, the sequence of events behind a full simulation, i.e. what happens in ``simcado.run()``, looks like this" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import simcado\n", "\n", "# create a 1000 Msun cluster in the LMC\n", "src = simcado.source.cluster(mass=1000, distance=50000, half_light_radius=4)\n", "\n", "# create the simulation commands, optical train and detector\n", "cmd = simcado.UserCommands()\n", "opt = simcado.OpticalTrain(cmd)\n", "fpa = simcado.Detector(cmd)\n", "\n", "# observe the source - get the expected ph/s/pixel rate\n", "my_star.apply_optical_train(opt_train=opt, detector=fpa)\n", "\n", "# read the final image out to disk\n", "fpa.read_out(filename=\"test.fits\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Customising a simulation" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Understanding SimCADO" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [] } ], "metadata": { "anaconda-cloud": {}, "kernelspec": { "display_name": "Python [conda root]", "language": "python", "name": "conda-root-py" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.5.2" } }, "nbformat": 4, "nbformat_minor": 1 }