# Artificial Frames

This tool is designed to create the artificial, nevertheless photometric realistic, frames. They are intended for modelling of various observation effects as well as for testing purposes.

## Synopsis

`munipack artificial [.. parameters ..]`

## Description

Artificial frames are created by artificial photons having origin in physical principles and mathematical formulas rather than in nature. This approach can be very useful for understanding of true nature of many effects which can be else gathered by a plenty of observational experiences.

There is list of currently implemented features:

- Quantum efficiency of detector, telescope parameters.
- Atmospheric extinction (monochromatic)
- Astronomical Seeing
- Point spread functions (PSF): Gaussian, Moffat and seeing.
- Background noise
- Light curves: plain wave, Algol-like, δ Cep and user defined
- Field stars: by a catalogue or generated randomly.

The frames are generated:

- on base of catalogue stars which simulates nearly real field or
- on base of randomly generated positions and magnitudes of stars.

### Modelling of Telescope Properties

The properties of star images can be easy simulated for various quantum efficiency η of a detection apparatus (including detector itself), an exposure duration and a telescope diameter.

Both angular resolution and collecting area of a telescoped are proportional to diameter. The parameter `--airy` can set it directly, but better way is set diameter (via `--diameter` in meters) which sets both diffraction limit and input area.

### Modelling of Extinction

An observed light intensity I(X) passing the clear (no clouds) Earth's atmosphere is attenuated proportionally of air-mass X according to the formula

I(X) = I0 e-k(X-1)

where I0 is an extra-atmospheric intensity. The extinction coefficient k depends on a spectral band.

The sky brightness (see below) is modelled by the same way (bZ is its zenit value)

b(X) = bZ e-k(X-1)

### Modelling of seeing

Turbulent motion in atmosphere creates large cells which slightly reflect light rays. The nature of turbulent motion is totally chaotic. There is a formula describing effect of chaotic moving of picture of a star due atmosphere during long exposures. It modelled star profile as function of air mass.

By Mr.Fries theory (very nice description has Electronic Imaging in Astronomy by Ian S. McLean), the seeing radius is modelled as

r'0 = r0 X0.6.

r'0 is an actual radius of stars at air-mass X, while r0 is the one at zenith.

### Modelling of Star Profiles

These profiles known as point spread functions (PSF) are available:

- Seeing spread function which convoluted diffraction pattern of telescope aperture and Gaussian spread by seeing. It is the best method for simulation of any star natural profile.
- Moffat profile which is commonly used for rough description of observed profiles.
- Gaussian profiles exp(-r2/r20) which is the basic estimator. It is ideal for theoretical work; any practical use is limited on extra-atmospheric applications, such as spacecraft or Moon base observatories, without image perturbations by the seeing.

Gauss
Moffat
seeing

The plain diffraction pattern, representing response of an input aperture of a telescope without atmosphere seeing, can be generated as seeing spread with zero seeing parameter. It is difficult to expose it, even in laboratory, due to limited dynamical range of detectors.

The distribution of seeing is supposed as Gaussian and convoluted with actual diffraction profile. There are two methods convolution implemented:

- Direct convolution -- diffraction profile is randomly shifted in both directions and the result is accumulated. This slow method gives slightly asymmetrical frames and is intended for simulating of short exposures.
- Fourier convolution -- this method generates both diffraction profile and Gaussian with the Fried's width. The profiles are convoluted with help of convolution theorem and FFT. This method is fast and results are perfectly smooth.

All stars, on the image, are modelled with the same profile.

### Elliptic star profiles

Non-circular star profiles are modelled by ellipse. Any ellipse is characterised by semi-major axis a (having radius meaning r0) and semi-minor axis b. b can not be specified directly: eccentricity 0 ≤ e < 1 is used instead; the parameter squeezes circle (e=0, a = b) to a line (e → 1).

Ellipsis is oriented to have its major semi-axis parallel to horizontal Cartesian axis by default. It can be optionally rotated by angle -90° < i ≤ 90°.

Non-circularity can be used to model imperfections in telescope tracking.

Ellipsis

### Modelling of Background

Background B(x,y) is modelled as a plane

b(x,y) = B0 + ΔBx (x - x0) + ΔBy (y - y0)

B(x,y) = N( b(x,y), Δb)

where B0 is a mean level (derived from `--skymag`) at centre of the picture x0, y0, N(b, Δb) is a function which makes a noise with Normal distribution. The parameters are mean level b and standard deviation Δb, which is computed as Δb = √ B0.

The optional gradient in background in counts per pixels is given by terms ΔBx, ΔBy (`--sky-grad-x, --sky-grad-y`). It can do modelling of a light pollution (by Moon). The common values for gradients are of order 0.0001 … 0.001 (negative values means negative slope of the plane in given direction).

Common sky brightness in zenit
value [mag/arcsec2] | light conditions
--- | ---
above 22 | natural sky, high-altitude observatory
22 | dark place, excellent night
21 | countryside sky, average night
20 | suburban sky, poor night
18 | urban sky, full Moon
under 17 | city sky, twilight

Values in the table are rought and determined by my observing experiences (wiki page).

### Star fields

Field stars are generated by a random number generator, if no `-c` option (a catalogue) is presented. Catalogue star coordinates and magnitudes are used otherwise.

Rectangular (without projection) coordinates of the stars has uniform distribution in ranges given by a frame size. The standard Fortran random number generator, with no initial seed, is used.

Magnitude distribution, meaning a probability to found number of stars in given magnitude interval per square degree, is modelled as an exponential function with a cut-off to prevent Olbersʼ paradox. I derived a rough approximation of the observed (surface) distribution of stars by brightens from DR1 by Gaia mission:

Σ(m) = 10-4 · e1.1m [□°], m < m0,

(the symbol □° designates square degree). The cut-off m0 is given by `--maglim` parameter. Large values of m0 and large field of view can effectively exhaust the computer memory.

The distribution approximation must be considered as an effective description. Stars are distributed over our sky very non homogeneously. Standard galaxy textbooks (like Binney's & Merrifield's Galactic Astronomy) gives more extensive description with references.

### Models of light curves

The artificial tool has three models of light curves included. The model of the pulsating star δ Cep (data computed by Mérand et al.) and the eclipsing binary star Algol (observed by Kim, Ho-Il). Both the curves has been approximated by Fourier series. The last model is a simple cosine wave.

The approximation of light curves of δ Cep and Algol.

There is also possibility to define own Fourier series approximation of light curves which is suitable for wave-like patterns. Do create a FITS table with format similar to fourier.lst. The table contains real Fourier coefficients an, bn. If the coefficients are estimated from measured data with noise, any appearance of high-order terms indicates inappropriateness of Fourier approximation. I can't recommend use on curves with sharp edges as Algol-like objects has. Note. The Fourier approximation gives very good approximation of Cepheids but is not very suitable for Algoids. The spline approximation can be recommended in that case.

Universal flux-time pattern is implemented as a time series table. It can represent a periodic object like Algol star or exoplanet transition, but it can also model an non periodic behaviour like a supernova explosion or an optical afterglow. The usage is described in Light Curves section of Overview.

### Galaxy models

This artificial tool implements models of elliptical galaxies. A radial profile have Sérsic profile (generalised de Vaucouleurs profile). A shape (nearly circular or nearly lenticular) is given by the Hubble classification; an orientation and shape of ellipticity is the same as for PSF of stars. All parameters are specified in the particular galaxy catalogue file. See Artificial sky for examples.

### Watermark

Every generated frame is marked by a symbol which indicates its artificial origin to prevent potential confusion. The mark can not be hide.

## Parameters

`--psf [SEEING|MOFFAT|GAUSS]`
  Selects PSF function: SEEING (the best, slow, default), MOFFAT (commonly used), GAUSS (basic model, fast)
`--psf-file filename`
  PSF by the external FITS file (specification).
`--spread [AUTO|FFT|RANDOM]`
  The method used to spread diffraction pattern (useful with --psf SEEING only): FFT (fast, smooth), RANDOM (slow, natural look) or AUTO (the RANDOM is selected for exposures shorter than 3 seconds)
`--hwhm hwhm`
  Half with of half of maximum of spread Gaussian in pixels. It represents half of seeing parameter. The parameter is common for all PSF.
`--airy airy`
  Radius of Airy spot in pixels. It is useful for seeing PSF. This parameter can be also set by `--diameter`.
`--beta β`
  Value of β exponent of Moffat profile (β > 0, β ≠ 1).
`--eccentricity e`
  Eccentricity of PSF by a contour ellipse: 0 ≤ e < 1. The default value e=0 specifies a circular PSF.
`--inclination i`
  Inclination of major semi-axis of the ellipse in degrees. Positive values of the angle are in mathematics sense (counter-clockwise).
`--maglim m0`
  Sets the most faint stars on frame for random generated field stars. This option is active only when star catalogue (by `-c,--cat`) is not used.
`--lc-model [Cepheid|Algol|wave]`
  The light curve model: `Cepheid' means light curve of δ Cep, `Algol' means β Per, `wave' means cosine function. This parameter is mutually exclusive with `--lc-table, --lc-fourier`.
`--lc-table file`
  The light curve model is determined by an smoothing spline interpolation in a table. The table is represented by the passed FITS file (see Time Series Table for format description). This parameter is mutually exclusive with `--lc-model, --lc-fourier`.
`--lc-fourier file`
  The light curve model is given by the coefficients of Fourier series listed in the FITS file. This parameter is mutually exclusive with `--lc-model, --lc-table`.
`--lc-mag mag, --lc-amp amp`
  The mean magnitude of the variable source. The relative amplitude of light curve. For example, 0.1 (10%) means cca 0.1 magnitude. The amplitude is ignored with conjunction of `--lc-table`.
`--lc-jd0 jd0, --lc-per period`
  Time elements of the light curve: jd0 is a reference time in Julian date (exact meaning depends on the kind of the curve), period in days. Don't use modified JD.
`--lc-ra α, --lc-dec δ`
  A Right Ascension and Declination of the variable source. If the coordinates are undefined, the centre of projection (as `--rcen, --dcen`) is used.
`--sky-mag skymag`
  Set sky brightness in magnitudes per square arcsecond. Default value is 21 meaning good observing conditions.
`--sky-grad-x xmag, --sky-grad-y ymag`
  Background change in magnitues per square arcsecond and pixel in given direction. The order of common values is in the interval 0.0001 … 0.001. It simulates a light pollution (by Moon).
`--gnoise dispersion`
  Set the dispersion of gaussian noise per pixel. The parameter is intended to simulate various sources of noise like dark current, noise of background, etc. The value of gnoise is merged with skymag.
`--area area`
  The detection area of a simulated telescope in square meters. It is 1m² by default (see `--diameter` option). This is equivalent area for 56 cm (22 inch) diameter telescope.
`--diameter diameter`
  Sets diameter (twice of radius) of a telescope in meters. If set, the area (`--area`) and Airy radius (`--airy`) is (re-)defined.
`--exptime time`
  The exposure time of generated frames in seconds.
`--qeff η`
  The quantum efficiency of a whole apparatus (0 ≤ η ≤ 1).
`--disable-noise`
  Switch-off including of these sources of noise: photon, and background noise. This switch is intended for some algorithm testing.
`--atmosphere`
  Switch-on modelling of the atmosphere. The model includes both extinction and seeing.
`--extk k`
  Monochromatic extinction coefficient. Setting on zero effectively suppress of the extinction determination.
`--long λ, --lat φ`
  Geographic coordinates of a station in degrees (+east, +north). Coordinates of Brno observatory are specified as `--long +16.6, --lat +49.2`.
`--date YYYY-MM-DD, --time HH:MM:SS`
  Date as YYYY-MM-DD and time as HH:MM:SS of (initial) frame.
`--count #`
  Total count of generated frames.
`--timestep time`
  Time delay between simulated exposures in seconds.
`-f, --filter filter`
  Simulated filter.
`-c, --cat file`
  Input catalogue with star positions and magnitudes.
`--galcat file`
  Input catalogue with galaxy models (format)
`--fov fov`
  Field of view in degrees.
`--rcen α, --dcen δ`
  Centre of the field of view in Right Ascension and Declination in degrees.
`--scale s`
  Scale of the frame in degrees per pixel.
`--angle φ`
  Angle of rotation of the frame around the centre in degrees. Clockwise direction is positive.
`--width width, --height height`
  Dimensions of output frame in pixels.

## Examples

      $ munipack artificial
      $ xmunipack artificial.fits

Overview comes with more useful examples.

## Light curve table

The table has similar format as the time-series table. It contains magnitudes (optionally, with errors) with columns: TIME,MAG,MAGERR. Records in the table must be sorted in time-increasing order. Overview describes its application.

## Table of Fourier coefficients

This table contains two valid columns with Fourier series approximation of a light curve. The columns are: first is the real and second the imaginary part of Fourier complex coefficient. The text file fourier.lst demonstrates an instance of data (NAXIS2 must be updated when modified). A FITS file, required by `--lc-fourier`, will be created as

      $ munipack fits --restore fourier.lst

## See Also

Overview of Artificial sky, Artificial Sky … (seminary talk), Common options.