Kl/upgrade/rename xhw to x size

.travis.yml

@@ -31,4 +31,4 @@ jobs:
 
 script: 
   - pytest
-  # - pytest --doctest-modules
+#  - jupyter nbconvert --execute docs/source/_static/scopesim_basic_intro.ipynb

OLD_code/OLD_database.py

@@ -648,7 +648,7 @@ def download_package(pkg_name, unzip_package=True, save_dir=None,
     if pkg_entry is None:
         raise ValueError("{} wasn't found on the server".format(pkg_name))
 
-    pkg_url  = rc.__rc__["FILE_SERVER_BASE_URL"] + pkg_entry["path"]
+    pkg_url = rc.__rc__["FILE_SERVER_BASE_URL"] + pkg_entry["path"]
     pkg_type = determine_type_of_package(svr_db)
 
     if not check_package_exists(pkg_name, server_db_urls()[pkg_type]):
@@ -658,6 +658,9 @@ def download_package(pkg_name, unzip_package=True, save_dir=None,
         stem = os.path.dirname(pkg_entry["path"])
         save_dir = os.path.join(rc.__rc__["FILE_LOCAL_DOWNLOADS_PATH"], stem)
 
+    if not os.path.exists(save_dir):
+        os.mkdir(save_dir)
+
     local_filename = download_file(pkg_url, save_dir)
     print("Saved {} in {}".format(pkg_name, local_filename))
     if unzip_package and ".fits" not in local_filename:

docs/source/index.rst

@@ -18,8 +18,9 @@ ScopeSim_ is on pip::
     :maxdepth: 2
     :caption: Contents:
 
-    interfaces/controlling_simulations
+
     use_examples/index
+    use_examples/jupyter_notebooks
     interfaces/index
     architecture/index
     effects/index

docs/source/use_examples/5-liners/0_setup.rst

@@ -0,0 +1,18 @@
+Setup for the docs
+==================
+
+.. jupyter-execute::
+
+    import os, scopesim
+
+    if not os.path.exists("./temp/"):
+        os.mkdir("./temp/")
+    scopesim.rc.__config__["!SIM.file.local_packages_path"] = "./temp/"
+    scopesim.rc.__config__["!SIM.file.use_cached_downloads"] = False
+
+    pkg_names = ["locations/Paranal",
+                 "telescopes/VLT",
+                 "instruments/HAWKI",
+                 "telescopes/LFOA"]
+
+    scopesim.server.download_package(pkg_names)

docs/source/use_examples/5-liners/A_bang_strings.rst

@@ -0,0 +1,114 @@
+Control: Using bang "!" strings in ScopeSim
+===========================================
+
+.. jupyter-execute::
+    :hide-code:
+    :raises:
+
+    import scopesim
+    scopesim.rc.__config__["!SIM.file.local_packages_path"] = "./temp/"
+
+TL;DR
+-----
+
+.. jupyter-execute::
+    :raises:
+
+    hawki = scopesim.OpticalTrain("HAWKI")
+
+    hawki.cmds["!ATMO"]
+    hawki.cmds["!SIM.random.seed"] = 9001
+
+    hawki.effects
+    hawki["filter_curve"].meta["filter_name"]
+    hawki.cmds["!OBS.filter_name"] = "H"
+
+
+This 5-liner uses concepts from:
+
+- :doc:`A_loading_packages`: downloading instrument packages
+
+
+Explanation
+-----------
+
+Top level parameters
+++++++++++++++++++++
+
+Let's assume we are in out working directory and have already downloaded the
+packages needed to model HAWKI at the VLT (i.e. Paranal, VLT, HAWKI).
+If not, see :doc:`A_loading_packages`
+
+We can start by loading an ``OpticalTrain`` object for HAWKI
+
+.. jupyter-execute::
+    :raises:
+
+    hawki = scopesim.OpticalTrain("HAWKI")
+
+The commands are located in ``hawki.cmds`` and the ``Effect``-objects are
+located deep within the depths of the ``OpticalTrain``. They can however be
+retrieved if you know what you are looking for.
+
+To view all "user"-facing commands, we can simply print ``hawki.cmds``.
+To print just a subset, use "!" plus the alias. E.g:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki.cmds["!OBS"]
+
+.. note:: Aliases are quick ways to refer to command catagories
+
+    As ScopeSim treats independent parts of the optical train separately, they
+    can each be given a different alias (set in the ``yaml`` files).
+    The standard aliases are (with obvious meanings):
+
+    ``!ATMO``, ``!TEL``, ``!RO`` (relay optics), ``!INST``, ``!DET``
+
+    Additionally there are two special categoies ``!OBS`` and ``!SIM`` for the
+    observation and simulation parameters respectively.
+
+As ScopeSim uses a YAML structure (nested dictionaries) for the configuration
+files, some parameters may themselves also be dictionaries (of dictionaries).
+We can navigate down the layers using the "." separator:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki.cmds["!SIM.random.seed"] = 9001
+
+
+Lower level parameters
+++++++++++++++++++++++
+
+The top level parameters should contain all the levers the casual user may want
+to play with.
+If we want to control effects that would normally be hidden from an observer, we
+need to know the name of the effect we are looking for.
+
+To list all the effects contained in the HAWKI system, we call:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki.effects
+
+By treating ``hawki`` as a dictionary, we can access the individual ``Effect``
+objects. The configuration parameters are contained in the ``.meta`` dictionary.
+
+.. jupyter-execute::
+    :raises:
+
+    hawki["filter_curve"].meta["filter_name"]
+
+Here we notice that the internal HAWKI configuration is actually referring to
+a top-level parameter that is available to the user via the normal ``.cmds``
+parameter.
+
+If we want to use another filter, we can still use the "bang"-string format:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki.cmds["!OBS.filter_name"] = "H"

docs/source/use_examples/5-liners/A_loading_packages.rst

@@ -0,0 +1,85 @@
+Control: Loading Packages
+=========================
+
+TL;DR
+-----
+
+.. jupyter-execute::
+    :raises:
+
+    import scopesim, os
+    if not os.path.exists("./temp/"): os.mkdir("./temp/")
+
+    scopesim.rc.__config__["!SIM.file.local_packages_path"] = "./temp/"
+
+    pkg_names = ["locations/Paranal", "telescopes/VLT", "instruments/HAWKI"]
+    scopesim.server.download_package(pkg_names)
+
+    cmds = scopesim.UserCommands(use_instrument="HAWKI")
+    hawki = scopesim.OpticalTrain(cmds)
+
+
+Explanation
+-----------
+
+Before we can load anything we need to download the instrument packages from the
+instrument reference database (https://github.com/astronomyk/irdb).
+
+We can list all the available packages like so:
+
+.. jupyter-execute::
+    :raises:
+
+    scopesim.server.list_packages()
+
+
+Note that the packages are split into three categories:
+
+* locations
+* telescopes
+* instruments
+
+To use an instrument package, we will need to download the support packages (location and telescope) that are relevant to the instrument.
+In the case HAWKI, this means also getting the VLT and Paranal packages:
+
+.. jupyter-execute::
+    :raises:
+
+    pkg_names = ["locations/Paranal", "telescopes/VLT", "instruments/HAWKI"]
+    scopesim.server.download_package(pkg_names)
+
+
+The standard way to load an instrument package is to create a ``UserCommands``
+object and the ``use_instrument=`` parameter:
+
+
+.. jupyter-execute::
+    :raises:
+
+    hawki_cmds = scopesim.UserCommands(use_instrument="HAWKI")
+
+This will allow us to play around with the parameters before we generate a model
+of the whole optical system.
+The optical model is created by passing the ``UserCommands`` object to an
+``OpticalTrain`` object:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki = scopesim.OpticalTrain(hawki_cmds)
+
+However if we are happy to accept all the default values and simply want to
+simulate an observation, we can bypass the user commands step, and initialise
+the ``OpticalTrain`` with the name of package that we have on the local disc.
+
+.. jupyter-execute::
+    :raises:
+
+    hawki = scopesim.OpticalTrain("HAWKI")
+
+.. note:: Packages are stored by default in the working directory
+
+   This can be changed by setting the following ``rc`` entry::
+
+   scopesim.rc.__config__["!SIM.file.local_packages_path"]
+

docs/source/use_examples/5-liners/A_turning_effects_on_or_off.rst

@@ -0,0 +1,68 @@
+Control: Turning Effect objects on or off
+=========================================
+
+.. jupyter-execute::
+    :hide-code:
+    :raises:
+
+    import scopesim
+    scopesim.rc.__config__["!SIM.file.local_packages_path"] = "./temp/"
+
+TL;DR
+-----
+
+.. jupyter-execute::
+    :raises:
+
+    hawki = scopesim.OpticalTrain("HAWKI")
+
+    hawki.effects
+    hawki["detector_linearity"].include = False
+    hawki["detector_linearity"].meta["include"] = True
+
+
+Background
+----------
+
+This 5-liner uses concepts from:
+
+- :doc:`A_loading_packages`: downloading instrument packages
+- :doc:`A_bang_strings`: accessing top- and lower-level parameters.
+
+
+Explanation
+-----------
+
+To list all the effects in the HAWKI optical train, we do:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki = scopesim.OpticalTrain("HAWKI")
+    print(hawki.effects)
+
+This table already shows us which ``Effect`` objects are turned on.
+
+To turn ``Effect`` object on or off manually, we use the ``.include`` attribute.
+Here we must call the ``Effect`` by it's name as given in the previous table:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki["detector_linearity"].include = False
+    hawki["detector_linearity"].include
+
+Turning back on is simple:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki["detector_linearity"].include = True
+
+If we want to change many parameters at once, including ``include`` we can
+access it via the ``.meta`` dictionary:
+
+.. jupyter-execute::
+    :raises:
+
+    hawki["detector_linearity"].meta["include"] = True

docs/source/use_examples/5-liners/B_source_from_arrays.rst

@@ -0,0 +1,19 @@
+Source: From Arrays
+===================
+
+TL;DR
+-----
+
+.. jupyter-execute::
+    :raises:
+
+    import scopesim, numpy as np
+
+    vega = scopesim.source.source_templates.vega_spectrum(mag=20)
+    point_source = scopesim.Source(x=[0], y=[0], ref=[0], spectra=[vega])
+    flat_source = scopesim.Source(x=[0], y=[0], ref=[0],
+                                  spectra=np.array([1, 1]),
+                                  lam=np.array([0.5, 2.5]))
+
+    print(flat_source.fields)
+    print(flat_source.spectra)

docs/source/use_examples/5-liners/B_source_from_image.rst

@@ -0,0 +1,39 @@
+Source: From ImageHDUs
+======================
+
+TL;DR
+-----
+
+.. jupyter-execute::
+    :raises:
+
+    import scopesim, scipy, astropy.io.fits as fits
+
+    hdu = fits.ImageHDU(data=scipy.misc.face(gray=True))
+    hdu.header.update({"CDELT1": 1, "CUNIT1": "arcsec", "CRPIX1": 0, "CRVAL1": 0,
+                       "CDELT2": 1, "CUNIT2": "arcsec", "CRPIX2": 0, "CRVAL2": 0,})
+
+    ab_spec = scopesim.source.source_templates.ab_spectrum(mag=20)
+
+    image_source = scopesim.Source(image_hdu=hdu, spectra=[ab_spec])
+
+    print(image_source.fields)
+    print(image_source.spectra)
+
+
+Explanation
+-----------
+
+.. jupyter-execute::
+    :raises:
+
+    import matplotlib.pyplot as plt
+    %matplotlib inline
+
+    plt.subplot(121)
+    wave = range(3000, 25000)
+    plt.plot(wave, image_source.spectra[0](wave))
+    plt.xlabel("Wavelength [Angstrom]")
+    plt.ylabel("Flux [ph/s/cm2/Angstrom]")
+    plt.subplot(122)
+    plt.imshow(image_source.fields[0].data)