Getting started

Note: For instrument specific guides, please see the IRDB

A basic simulation would look something like this:

from matplotlib import pyplot as plt
from matplotlib.colors import LogNorm

import scopesim as sim
from scopesim.source import source_templates as st

src = st.star_field(n=100,
                    mmax=15,      # [mag]
                    mmin=20,
                    width=200)    # [arcsec]

opt = sim.load_example_optical_train()
opt.cmds["!OBS.dit"] = 60         # [s]
opt.cmds["!OBS.ndit"] = 10

opt.observe(src)
hdulist = opt.readout()[0]

plt.figure(figsize=(10,8))
plt.imshow(hdulist[1].data, norm=LogNorm(), vmin=1)
plt.colorbar()

<matplotlib.colorbar.Colorbar at 0x28cd17665f8>

Code breakdown

Let’s break this down a bit.

There are three major components of any simulation workflow:

1. the target description,

2. the telescope/instrument model, and

3. the observation.

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

Here we create a field of 100 A0V stars with Vega magnitudes between V=15 and V=20 within a box of 200 arcsec:

src = st.star_field(n=100,
                    mmax=15,      # [mag]
                    mmin=20,
                    width=200)    # [arcsec]

Next we load the sample optical train object from ScopeSim.

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

For real instruments loading the optical system generally follows a different pattern:

cmd = sim.UserCommands(use_instrument="instrument_name", set_modes=["mode_1", "mode_2"])
opt = sim.OpticalTrain(cmds)

Once we have loaded the instrument, we can set the observation parameters by accessing the internal commands dictionary:

opt = sim.load_example_optical_train(set_modes=["imaging"])
opt.cmds["!OBS.dit"] = 60         # [s]
opt.cmds["!OBS.ndit"] = 10

Finally we observe the target source and readout the detectors.

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.

opt.observe(src)
hdulist = opt.readout()[0]

Tips and tricks

Focal plane images

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:

noiseless_image = opt.image_planes[0].data

Turning optical effects on or off

All effects modelled by the optical train can be listed with the .effects attribute:

opt.effects

Table length=17

element	name	class	included
str16	str22	str29	bool
basic_atmosphere	atmospheric_radiometry	AtmosphericTERCurve	False
basic_telescope	psf	SeeingPSF	True
basic_telescope	telescope_reflection	TERCurve	True
basic_instrument	static_surfaces	SurfaceList	True
basic_instrument	filter_wheel : [J]	FilterWheel	True
basic_instrument	slit_wheel : [narrow]	SlitWheel	False
basic_detector	detector_window	DetectorWindow	True
basic_detector	qe_curve	QuantumEfficiencyCurve	True
basic_detector	exposure_action	SummedExposure	True
basic_detector	dark_current	DarkCurrent	True
basic_detector	shot_noise	ShotNoise	True
basic_detector	detector_linearity	LinearityCurve	True
basic_detector	readout_noise	PoorMansHxRGReadoutNoise	True
basic_detector	source_fits_keywords	SourceDescriptionFitsKeywords	True
basic_detector	effects_fits_keywords	EffectsMetaKeywords	True
basic_detector	config_fits_keywords	SimulationConfigFitsKeywords	True
basic_detector	extra_fits_keywords	ExtraFitsKeywords	True

These can be turned on or off by using their name and the .include attribute:

opt["detector_linearity"].include = False

Listing available modes and filters

The list of observing modes can be found by using the .modes attribute of the commands objects:

opt.cmds.modes

imaging: Basic NIR imager
spectroscopy: Basic three-trace long-slit spectrograph

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:

opt["filter_wheel"].filters

{'BrGamma': FilterCurve: "BrGamma",
 'CH4': FilterCurve: "CH4",
 'J': FilterCurve: "J",
 'H': FilterCurve: "H",
 'Ks': FilterCurve: "Ks",
 'open': FilterCurve: "open"}

Setting observation sequence

Although this could be different for some instruments, most instruments use the exptime = ndit * dit format. nditand dit are generally accessible in the top level !OBS dictionary of the command object in the optical train.

opt.cmds["!OBS.dit"] = 60         # [s]
opt.cmds["!OBS.ndit"] = 10

Listing and changing simulation parameters

The command dictionary inside the optical system contains all the necessary paramters.

opt.cmds

<SystemDict> contents:
SIM:
  spectral: {'wave_min': 0.7, 'wave_mid': 1.2, 'wave_max': 2.7, 'wave_unit': 'um', 'spectral_bin_width': 0.0001, 'spectral_resolution': 5000, 'minimum_throughput': 1e-06, 'minimum_pixel_flux': 1}
  sub_pixel: {'flag': False, 'fraction': 1}
  random: {'seed': None}
  computing: {'chunk_size': 2048, 'max_segment_size': 16777217, 'oversampling': 1, 'spline_order': 1, 'flux_accuracy': 0.001, 'preload_field_of_views': False, 'bg_cell_width': 60}
  file: {'local_packages_path': './inst_pkgs/', 'server_base_url': 'https://www.univie.ac.at/simcado/InstPkgSvr/', 'use_cached_downloads': False, 'search_path': ['./inst_pkgs/', './'], 'error_on_missing_file': False}
  reports: {'ip_tracking': False, 'verbose': False, 'rst_path': './reports/rst/', 'latex_path': './reports/latex/', 'image_path': './reports/images/', 'image_format': 'png', 'preamble_file': 'None'}
  logging: {'log_to_file': False, 'log_to_console': True, 'file_path': '.scopesim.log', 'file_open_mode': 'w', 'file_level': 'DEBUG', 'console_level': 'WARNING'}
  tests: {'run_integration_tests': True, 'run_skycalc_ter_tests': True}
  spectral_bin_width: 0.0005
OBS:
  psf_fwhm: 1.5
  modes: ['imaging']
  dit: 60
  ndit: 10
  slit_name: narrow
  include_slit: False
  filter_name: J
TEL:
  etendue: 0.007853981633974483 arcsec2 m2
  area: 0.19634954084936207 m2
  temperature: 0
INST:
  pixel_scale: 0.2
  plate_scale: 20
  decouple_detector_from_sky_headers: False
  temperature: -190
ATMO:
  background: {'filter_name': 'J', 'value': 16.6, 'unit': 'mag'}
  element_name: basic_atmosphere
DET:
  image_plane_id: 0
  temperature: -230
  dit: !OBS.dit
  ndit: !OBS.ndit
  width: 1024
  height: 1024
  x: 0
  y: 0
  element_name: basic_detector

The command object is a series of nested dictionaries that can be accessed using the !-string format:

opt.cmds["!<alias>.<param>"]
opt.cmds["!<alias>.<sub_dict>.<param>"]

For example, setting the atmospheric background level is achieved thusly:

opt.cmds["!ATMO.background.filter_name"] = "K"
opt.cmds["!ATMO.background.value"] = 13.6

More information

For more information on how to use ScopeSim be see:

• Use Examples

• Instrument Specific Documentation

• Effect data formats

• `Setting up a custom instrument <>`__

Contact

• For bugs, please add an issue to the github repo

• 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