starlist: Make an artificial star list

Package: artdata

Task

starlist -- make an artificial star list

Usage

starlist starlist nstars

Parameters

starlist: The name of the output text file for the x and y coordinates and magnitudes of the artificial stars. Output will be appended to this file is it exists.

nstars = 5000: The number of stars in the output star list.

interactive = no: Examine plots and change the parameters of the spatial luminosity distributions interactively.

SPATIAL DISTRIBUTION

spatial = "uniform"

Type of spatial distribution. The types are:

uniform: The stars are uniformly distributed between xmin, xmax, ymin, and ymax.

hubble: The stars are distributed around the center of symmetry xcenter and ycenter according to a Hubble density law of core radius core_radius and background density base.

file: The radial density function is contained in the text file sfile.

xmin = 1., xmax = 512., ymin = 1., ymax = 512.: The range of output coordinates in x and y.

xcenter = INDEF, ycenter = INDEF: The coordinate of the center of symmetry for the "hubble" and "file" radial density functions. The default is the midpoint of the coordinate limits.

core_radius = 30: The core radius of the Hubble spatial distribution in pixels.

base = 0.0: The background density relative to the central density of the Hubble density distribution.

sseed = 1: The initial value supplied to the random number generator used to generate the output x and y coordinates. If a value of "INDEF" is given then the clock time (integer seconds since 1980) is used as the seed yielding different random numbers for each execution.

MAGNITUDE DISTRIBUTION

luminosity = "powlaw"

Type of luminosity distribution. The types are:

uniform: The stars are uniformly distributed between minmag and maxmag.

powlaw: The stars are distributed according to a power law with coefficient power.

salpeter: The stars are distributed with a Salpeter luminosity function between minmag and maxmag.

bands: The stars are distributed with a Bahcall and Soneira luminosity function between minmag and maxmag. The function is described by the parameters alpha, beta, delta and mstar whose default values give a best fit to the observed main sequence in several nearby globular clusters.

file: The luminosity function is contained in the text file lfile.

minmag = -7., maxmag = 0.: The range of output magnitudes. The "salpeter" luminosity function imposes limits of -4 and 16 and the "bands" luminosity function imposes limits of -7 and 17 relative to the zero point given by mzero.

mzero = -4.: The zero point for converting the output relative magnitudes to absolute magnitudes for the Salpeter and Bahcall and Soneira luminosity functions. For example the default values give an absolute magnitude range of -3 to +4.

power = 0.6: Coefficient for the power law magnitude distribution. The default value of 0.6 is the value for a homogeneous and isotropic distribution with no cutoff in distance.

alpha = 0.74, beta = 0.04, delta = 0.294, mstar = 1.28: The parameters of the Bahcall and Soneira luminosity function.

lseed = 1: The initial value supplied to the random number generator used to generate the output magnitudes. If a value of "INDEF" is given then the clock time (integer seconds since 1980) is used as the seed yielding different random numbers for each execution.

USER FUNCTIONS

sfile: The name of the input text file containing the sampled spatial radial density function, one sample point per line, with the radius and relative probability in columns one and two respectively. The sample points need not be uniformly spaced or normalized.

nssample = 100: The number of points at which the spatial density function is sampled. If the spatial density function is analytic or approximated analytically (the "uniform" and "hubble" options) the function is sampled directly. If the function is read from a file (the "file" option) an initial smoothing step is performed before sampling.

sorder = 10: The order of the spline fits used to evaluate the integrated spatial density function.

lfile: The name of the input text file containing the sampled luminosity function, one sample point per line, with the magnitude and relative probability in columns one and two respectively. The sample points need not be uniformly spaced or normalized.

nlsample = 100: The number of points at which the luminosity function is sampled. If the luminosity function is analytic or approximated analytically (the "salpeter" and "bands" options) the function is sampled directly. If it is read from a file (the "file" option) an initial smoothing step is performed before sampling.

lorder = 10: The order of the spline fits used to evaluate the integrated luminosity function.

INTERACTIVE PARAMETERS

rbinsize = 10.: The bin size in pixels of the plotted histogram of the radial density distribution.

mbinsize = 0.5: The bin size in magnitudes of the plotted histogram of the luminosity function.

graphics = stdgraph: The default graphics device.

cursor = "": The graphics cursor.

Description

Starlist generates a list of x and y coordinates and magnitudes for a sample of nstars stars based on a user selected spatial density function spatial and luminosity function luminosity and writes (appends) the results to the text file starlist. If the interactive parameter is "yes" the user can interactively examine plots of the spatial density function, the radial density function, and the luminosity function, and alter the parameters of the task until a satisfactory artificial field is generated.

The spatial density function generates x and y values around a center of symmetry defined by xcenter and ycenter within the x and y limits xmin, xmax, ymin and ymax according to the spatial density function specified by spatial. The three supported spatial density functions are listed below where R is the radial distance in pixels, P is the relative spatial density, C is a constant and f is the best fitting cubic spline function to the spatial density function R(user), P(user) supplied by the user in the text file sfile.

uniform:  P = C
hubble:   P = 1.0 / (1 + R / core_radius) ** 2 + base
file:     P = f (R(user), P(user))

The Hubble and user file spatial density function are sampled at nssample equally spaced points, and integrated to give the spatial density probability function at each sampled point. The integrated probability function is normalized and approximated by a cubic spline of order sorder. The x and y coordinates are computed by randomly sampling the integrated probability function until nstars stars which satisfy the x and y coordinate limits xmin, xmax, ymin and ymax are generated.

The luminosity function generates relative magnitude values between minmag and maxmag according to the luminosity function specified by luminosity. The four supported luminosity functions are defined below where M is the magnitude, P is the relative luminosity function, C is a constant and f is the best fitting cubic spline function to the luminosity function M(user), P(user) supplied by the in the text file lfile.

uniform:  P = C

powlaw:   P = C * 10. ** (power * M)

salpeter: P = C * 10. ** (-3.158 + 1.551e-1*dM - 5.194e-3*dM**2)

          dM = M - mzero

                           C * 10. ** (beta * dM)
bands:   P =  --------------------------------------------------
             (1. + 10. ** ((beta-alpha)*delta*dM))) ** 1. /delta

         dM = M - mstar - mzero

file:    P = f (M(user), P(user))

The Salpeter and "bands" functions are defined in terms of absolute magnitudes so the parameter mzero is used to convert from relative magnitudes. Equivalently, one could use absolute magnitudes for the magnitude limits while setting the zero point to 0.

The luminosity function is sampled at nlsample equally spaced points, and integrated to give the luminosity probability function at each sampled point. The probablity function is normalized and approximated by a cubic spline of order lorder. The magnitudes are computed by randomly sampling the integrated probability function until nstars objects which satisfy the magnitude limits minmag and maxmag are generated. The Salpeter luminosity is a best fit function to the data of McCuskey (McCuskey, 1966, Vistas Astr. 7, 141). The Bahcall and Soneira function and the default values of the parameters are discussed by Bahcall and Soneira (Ap.J. Supp. 44, 73).

Cursors

The following interactive keystroke commands are available from within the STARLIST task.

        Starlist Keystroke Commands

?       Print options
f       Fit  one or more of the following
            Spatial density function (SDF)
            Luminosity functions (LF)
x       Plot the x-y spatial density function
r       Plot the histogram of the radial density function
m       Plot the histogram of the luminosity function
:       Colon escape commands (see below)
q       Exit program

The following parameters can be shown or set from within the STARLIST task.

                Starlist Colon Commands

:show                   Show starlist parameters
:nstars     [value]     Number of stars

:spatial    [string]    Spatial density function (SDF)
                        (uniform|hubble|file)
:xmin       [value]     Minimum X value
:xmax       [value]     Maximum X value
:ymin       [value]     Minimum Y value
:ymax       [value]     Maximum Y value
:xcenter    [value]     X center for SDF
:ycenter    [value]     Y center for SDF
:core       [value]     Core radius for Hubble density function
:base       [value]     Background density for Hubble density function

:luminosity [string]    Luminosity function (LF)
                        (uniform|powlaw|salpeter|bands|file)
:minmag     [value]     Minimum magnitude
:maxmag     [value]     Maximum magnitude
:mzero      [value]     Magnitude zero-point for salpeter and bands LF
:power      [value]     Exponent for powlaw LF
:alpha      [value]     Alpha parameter for bands LF
:beta       [value]     Beta parameter for bands LF
:delta      [value]     Delta parameter for bands LF
:mstar      [value]     Mstar parameter for bands LF

:sfile      [string]    File containing the user SDF
:nssample   [value]     Number of SDF sample points
:sorder     [value]     Order of spline fit to integrated SDF
:lfile      [string]    File containing the user LF
:nlsample   [value]     Number of LF sample points
:lorder     [value]     Order of spline fit to the integrated LF

:rbinsize   [value]     Resolution of radial profile histogram (pixels)
:mbinsize   [value]     Resolution of magnitude histogram (mag)

Examples

1. Create a uniform artificial starfield of 5000 stars for a 512 square image.

ar> starlist starfield.dat 5000
ar> mkobjects starfield obj=starfield.dat gain=2 rdnoise=10 poisson+

This example takes about a minute on a SPARCstation 1.

2. Create a globular cluster field of 5000 stars for a 512 square image.

ar> starlist gc.dat 5000 spat=hubble lum=bands
ar> mkobjects starfield obj=gc.dat gain=2 rdnoise=10 poisson+

This example takes about a minute on a SPARCstation 1.

3. Examine the distributions for a Hubble spatial distribution and Salpeter magnitude distribution using 1000 stars without creating a data file.

ar> starlist dev$null 1000 inter+ spat=hubble lum=salpeter
        ... an x-y plot will appear on the screen
        ... type r to examine the radial density function
        ... type m to examine the luminosity function
        ... type = to make a copy of any of the plots
        ... type q to quit

Revisions

STARLIST V2.11+: The random number seeds can be set from the clock time by using the value "INDEF" to yield different random numbers for each execution.

Bugs

The spline approximation to the spatial density and luminosity probability functions can cause wiggles in the output spatial density and luminosity functions. Users can examine the results interactively and experiment with the spline order and number of sample points if they are not satisfied with the results of STARLIST. The default setup of 10 sample points per spline piece is generally satisfactory for the spatial density and luminosity functions supplied here.