{ "cells": [ { "cell_type": "markdown", "id": "owned-charles", "metadata": {}, "source": [ "# Getting started\n", "\n", "
\n", "\n", "Note: For instrument specific guides, please see the [IRDB](https://irdb.readthedocs.io/en/latest/)\n", "\n", "
\n", "\n", "A basic simulation would look something like this:" ] }, { "cell_type": "code", "execution_count": null, "id": "tracked-preview", "metadata": {}, "outputs": [], "source": [ "from matplotlib import pyplot as plt\n", "from matplotlib.colors import LogNorm\n", "\n", "import scopesim as sim\n", "from scopesim.source import source_templates as st\n", "\n", "src = st.star_field(n=100, \n", " mmax=15, # [mag]\n", " mmin=20, \n", " width=200) # [arcsec]\n", "\n", "opt = sim.load_example_optical_train()\n", "opt.cmds[\"!OBS.dit\"] = 60 # [s]\n", "opt.cmds[\"!OBS.ndit\"] = 10\n", "\n", "opt.observe(src)\n", "hdulist = opt.readout()[0]\n", "\n", "plt.figure(figsize=(10,8))\n", "plt.imshow(hdulist[1].data, norm=LogNorm(vmin=1))\n", "plt.colorbar()" ] }, { "cell_type": "markdown", "id": "exceptional-runner", "metadata": {}, "source": [ "## Code breakdown\n", "\n", "Let's break this down a bit.\n", "\n", "There are three major components of any simulation workflow:\n", "\n", "1. the target description,\n", "2. the telescope/instrument model, and\n", "3. the observation.\n", "\n", "For the target description we are using the ScopeSim internal template functions from `scopesim.source.source_templates`, however many more dedicated science related templates are available in the external python package [ScopeSim-Templates](https://scopesim-templates.readthedocs.io/en/latest/)\n", "\n", "Here we create a field of 100 A0V stars with Vega magnitudes between V=15 and V=20 within a box of 200 arcsec:" ] }, { "cell_type": "code", "execution_count": null, "id": "conscious-thomas", "metadata": {}, "outputs": [], "source": [ "src = st.star_field(n=100, \n", " mmax=15, # [mag]\n", " mmin=20, \n", " width=200) # [arcsec]" ] }, { "cell_type": "markdown", "id": "banned-murder", "metadata": {}, "source": [ "Next we load the sample optical train object from ScopeSim.\n", "\n", "Normally we will want to use an actual instrument. Dedicated documentation for real telescope+instrument systems can be found in the documentation sections of the individual instruments in the [Instrument Reference Database (IRDB) documentation](https://irdb.readthedocs.io/en/latest/)\n", "\n", "For real instruments loading the optical system generally follows a different pattern:\n", "\n", " cmd = sim.UserCommands(use_instrument=\"instrument_name\", set_modes=[\"mode_1\", \"mode_2\"])\n", " opt = sim.OpticalTrain(cmds)\n", "\n", "Once we have loaded the instrument, we can set the observation parameters by accessing the internal commands dictionary:" ] }, { "cell_type": "code", "execution_count": null, "id": "productive-branch", "metadata": {}, "outputs": [], "source": [ "opt = sim.load_example_optical_train(set_modes=[\"imaging\"])\n", "opt.cmds[\"!OBS.dit\"] = 60 # [s]\n", "opt.cmds[\"!OBS.ndit\"] = 10" ] }, { "cell_type": "markdown", "id": "rising-habitat", "metadata": {}, "source": [ "Finally we observe the target source and readout the detectors.\n", "\n", "What is returned (`hdulist`) is an `astropy.fits.HDUList` object which can be saved to disk in the standard way, or manipulated in a python session." ] }, { "cell_type": "code", "execution_count": null, "id": "blond-frequency", "metadata": {}, "outputs": [], "source": [ "opt.observe(src)\n", "hdulist = opt.readout()[0]" ] }, { "cell_type": "markdown", "id": "brazilian-centre", "metadata": {}, "source": [ "## Tips and tricks\n", "\n", "### Focal plane images\n", "\n", "Intermediate frames of the focal plane image without the noise proerties can be accessed by looking inside the optical train object and accessing the first image plane:" ] }, { "cell_type": "code", "execution_count": null, "id": "lined-windows", "metadata": {}, "outputs": [], "source": [ "noiseless_image = opt.image_planes[0].data" ] }, { "cell_type": "markdown", "id": "underlying-madison", "metadata": {}, "source": [ "### Turning optical effects on or off\n", "\n", "All effects modelled by the optical train can be listed with the `.effects` attribute:" ] }, { "cell_type": "code", "execution_count": null, "id": "sharing-campaign", "metadata": {}, "outputs": [], "source": [ "opt.effects" ] }, { "cell_type": "markdown", "id": "auburn-boulder", "metadata": {}, "source": [ "These can be turned on or off by using their name and the `.include` attribute:" ] }, { "cell_type": "code", "execution_count": null, "id": "original-appeal", "metadata": {}, "outputs": [], "source": [ "opt[\"detector_linearity\"].include = False" ] }, { "cell_type": "markdown", "id": "tracked-homeless", "metadata": {}, "source": [ "### Listing available modes and filters\n", "\n", "The list of observing modes can be found by using the `.modes` attribute of the commands objects:" ] }, { "cell_type": "code", "execution_count": null, "id": "better-hurricane", "metadata": {}, "outputs": [], "source": [ "opt.cmds.modes" ] }, { "cell_type": "markdown", "id": "quiet-jimmy", "metadata": {}, "source": [ "The names of included filters can be found in the filter effect. Use the name of the filter object from the table above to list these:" ] }, { "cell_type": "code", "execution_count": null, "id": "through-exclusive", "metadata": {}, "outputs": [], "source": [ "opt[\"filter_wheel\"].filters" ] }, { "cell_type": "markdown", "id": "driven-controversy", "metadata": {}, "source": [ "### Setting observation sequence\n", "\n", "Although this could be different for some instruments, most instruments use the `exptime = ndit * dit` format.\n", "`ndit`and `dit` are generally accessible in the top level `!OBS` dictionary of the command object in the optical train." ] }, { "cell_type": "code", "execution_count": null, "id": "knowing-passenger", "metadata": {}, "outputs": [], "source": [ "opt.cmds[\"!OBS.dit\"] = 60 # [s]\n", "opt.cmds[\"!OBS.ndit\"] = 10" ] }, { "cell_type": "markdown", "id": "preliminary-james", "metadata": {}, "source": [ "### Listing and changing simulation parameters\n", "\n", "The command dictionary inside the optical system contains all the necessary paramters." ] }, { "cell_type": "code", "execution_count": null, "id": "nervous-hearts", "metadata": {}, "outputs": [], "source": [ "opt.cmds" ] }, { "cell_type": "markdown", "id": "touched-participation", "metadata": {}, "source": [ "The command object is a series of nested dictionaries that can be accessed using the `!-string` format:\n", "\n", " opt.cmds[\"!.\"]\n", " opt.cmds[\"!..\"]\n", " \n", "For example, setting the atmospheric background level is achieved thusly:" ] }, { "cell_type": "code", "execution_count": null, "id": "thick-democrat", "metadata": {}, "outputs": [], "source": [ "opt.cmds[\"!ATMO.background.filter_name\"] = \"K\"\n", "opt.cmds[\"!ATMO.background.value\"] = 13.6" ] }, { "cell_type": "markdown", "id": "labeled-railway", "metadata": {}, "source": [ "## More information\n", "\n", "For more information on how to use ScopeSim be see:\n", "\n", "- [Use Examples](examples/index.rst)\n", "- [Instrument Specific Documentation](https://irdb.readthedocs.io/en/latest/)\n", "- [Effect data formats](effects/formats)\n", "- [Setting up a custom instrument]()\n", "\n", "\n", "## Contact\n", "\n", "- For bugs, please add an [issue to the github repo](https://github.com/AstarVienna/ScopeSim/issues)\n", "- For enquiries on implementing your own instrument package, please drop us a line at astar.astro@univie.ac.at or kieran.leschinski@univie.ac.at" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "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.9.16" } }, "nbformat": 4, "nbformat_minor": 5 }