[ ESO ]  

ESO SkyCalc Command Line Interface (CLI)

An Interface to ESO SkyCalc

This is a command-line interface to ESO SkyCalc.

SkyCalc is an online tool to predict the atmospheric emission and transmission spectra as well as the magnitudes of the sky for the given observation conditions.

It is based on the Cerro Paranal Advanced Sky Model, which was developed in particular to be used in the ESO Exposure Time Calculators, by a team of astronomers at the Institute for Astro- and Particle Physics at the University of Innsbruck, as part of an Austrian in-kind contribution to ESO.

The command-line interface allows the user to perform requests directly to SkyCalc which is hosted on the ESO web server instead of using the usual web form. This is useful if one wants to calculate the sky for many different observation conditions, or to integrate ESO SkyCalc in another astronomical tool for instance.

Installation

The SkyCalc CLI works in Python 2.7 or Python 3. Install the SkyCalc CLI on your computer using the command:

$ pip install --user skycalc_cli

This will also install skycalc_cli's dependency, i.e. the requests package for making HTTP calls. Note that the --user is optional. You might want to install it globally as root depending on what you usually do.

If you use the --user option, the program is located in ~/.local/bin/. Either, call it from ~/.local/bin/skycalc_cli or have ~/.local/bin in your PATH environment variable.

The skycalc_cli installation can be updated to the latest version with the command: pip install --upgrade skycalc_cli. A specific version, for example 1.4, can be installed with pip install --upgrade skycalc_cli==1.4.

How to use the interface?

The command line is skycalc_cli. Running the command line without any parameter gives the online help:

$ skycalc_cli
usage: skycalc_cli -i|--in inputfile -o|--out file.fits [-a|--alm almanacparameterfile] [-v|--verbose] [--version]

Several options are available:

The user can use the almanac (option --alm) and provide (or not) an input file (option --in). In this case, the SkyCalc input parameters are retrieved from the Almanac. If an input file is also given, parameters in this file override the corresponding ones from the Almanac.

The verbose option displays which parameters are eventually used for SkyCalc and their values.

Example

$ skycalc_cli -i skycalc_defaults.txt -o output.fits -a almanac_example.json
$ ls output.fits
output.fits

skycalc_cli input parameter file

This file contains the input parameters for SkyCalc. A comprehensive list is provided in section SkyCalc Input parameters.

The input file format can be JSON or a simple text file in which the user specifies a pair key/value on each individual line as follows:

# comment
key1 : value1
key2 : value2
Example files: skycalc_defaults.json   skycalc_defaults.txt

Almanac input parameter file

This file contains the input parameters for the SkyCalc Almanac. A comprehensive list is provided in section SkyCalc Almanac Input parameters.

The input file format can be either JSON or simple text file, exactly as it is for the skycalc_cli input parameter file.

Example files: almanac_example.json   almanac_example.txt

SkyCalc Input parameters

Description Parameter Unit Type / Allowed values Default value
Airmass airmass float / range [1.0, 3.0] 1.0
Season and period of night pwv_mode string / "pwv" or "season" "pwv"
season int / range [0, 6] (0=all year, 1=dec/jan, 2=feb/mar...) 0
time int / range [0, 3] (0=all night, 1,2,3 = third of night) 0
Precipitable Water Vapor pwv mm float / [0.05,0.01,0.25,0.5,1.0,1.5,2.5,3.5,5.0,7.5,10.0,20.0,30.0] 3.5
Monthly Averaged Solar Flux msolflux sfu=0.01 MJy float / range [0.0, +∞[ (Monthly averaged solar radio flux density F10.7cm) 130.0
Scattered Moon Light

Note the following moon coordinate constraints:

|z – zmoon| ≤ ρ ≤ |z + zmoon|

where ρ=moon/target separation, z=90°−alt, zmoon=90°−moon_alt; z and alt refer to the target 		incl_moon string / ["Y", "N"] (Flag for inclusion of scattered moonlight) "Y"
moon_sun_sep degrees float range [0.0, 360.0] (Separation in deg of Sun and Moon as seen from Earth) 90.0
moon_target_sep degrees float range [0.0, 180.0] (Moon-Target Separation in deg) 45.0
moon_alt degrees float range [-90.0, 90.0] (Moon Altitude over Horizon in deg) 45.0
moon_earth_dist float range [0.91, 1.08] (Moon-Earth Distance, mean=1) 1.0
Star Light incl_starlight string / ["Y", "N"] (Flag for inclusion of scattered starlight) "Y"
Zodiacal light incl_zodiacal string / ["Y", "N"] (Flag for inclusion of zodiacal light) "Y"
ecl_lon degrees float / range [-180.0, 180.0] (Heliocentric ecliptic longitude) 135.0
ecl_lat degrees float / range [-90.0, 90.0] (Ecliptic latitude) 90.0
Molecular Emission of Lower Atmosphere incl_loweratm string / ["Y", "N"] (Flag for inclusion of lower atmosphere) "Y"
Molecular Emission of Upper Atmosphere incl_upperatm string / ["Y", "N"] (Flag for inclusion of upper atmosphere) "Y"
Airglow Continuum incl_airglow string / ["Y", "N"] (Flag for inclusion of upper airglow) "Y"
Instrumental Thermal Emission incl_therm string / ["Y", "N"] (Flag for inclusion of instrumental thermal radiation) "N"
therm_t1 K float / range [0.0, +∞[ 0.0
therm_e1 float / range [0.0, 1.0] (Emmisivity) 0.0
therm_t2 K float / range [0.0, +∞[ 0.0
therm_e2 float / range [0.0, 1.0] (Emmisivity) 0.0
therm_t3 K float / range [0.0, +∞[ 0.0
therm_e3 float / range [0.0, 1.0] (Emmisivity) 0.0
Wavelength Grid vacair string / ["vac", "air"] (Calculation in vacuum or air) "vac"
wmin nm float / range [300.0, 30000.0] < wmax (Minimum wavelength in nm) 300.0
wmax nm float / range [300.0, 30000.0] > wmin (Maximum wavelength in nm) 2000.0
wgrid_mode string / ['fixed_spectral_resolution','fixed_wavelength_step'] "fixed_wavelength_step"
wdelta nm float / range [0, 30000.0] (Wavelength sampling dlambda) 0.1
wres float / range [0, 1.0e6] (lambda / dlambda) 20000.0
Line Spread Function lsf_type string / ["none", "Gaussian", "Boxcar"] "none"
lsf_gauss_fwhm wavelength bins float / range [0.0, +∞[ 5.0
lsf_boxcar_fwhm wavelength bins float / range [0.0, +∞[ 5.0
Observatory observatory string / ["paranal", "lasilla", "3060m"] "paranal"
Compute atmosphere temperature and bolometric radiance temp_flag integer / [0, 1] (flag for inclusion in the output) 1

SkyCalc Almanac Input parameters

Description Parameter Unit Type / Allowed values
Equatorial Coordinates ra degrees float / [0., 360.] (Right Ascension)
dec degrees float / [-90.0, 90.0] (Declination)
Observatory observatory string / ["paranal", "lasilla", "3060m"]
Observation Date date | mjd string (timestamp, YYYY-MM-DDThh:mm:ss) | float (Modified Julian Day)

Output FITS file

The output from skycalc_cli is a binary FITS file with one extension which contains data columns of type DOUBLE. The input parameters and some additional information are listed as comments in the FITS header.

If the input option temp_flag is enabled, the computed atmosphere temperature and bolometric radiance values will be included in the FITS header.

Wavelength, radiance and transmission

LAM Wavelength in nm (not μm, see version note)
FLUX Radiance in photons/s/m2/μm/arcsec2
TRANS Fractional transmission

Individual radiance components in photons/s/m2/μm/arcsec2

FLUX_SML Scattered Moonlight
FLUX_SSL Scattered Starlight
FLUX_ZL Zodiacal Light
FLUX_TME Molecular Emission of Lower Atmosphere
FLUX_AEL Emission Lines of Upper Atmosphere (Airglow)
FLUX_ARC Airglow/Residual Continuum
FLUX_TIE Telescope/Instrument Thermal Emission

Individual transmission components

TRANS_MA Molecular Absorption
TRANS_O3 Ozone UV/optical absorption
TRANS_RS Rayleigh Scattering
TRANS_MS Mie Scattering

For more information refer to section 6 in the document Cerro Paranal Advanced Sky Model.

Version Information

Send comments and questions via https://support.eso.org/