Main Page   Namespace List   Compound List   File List   Namespace Members   Compound Members   File Members  

atm Namespace Reference

Namespace at contains the set of functions of highest logical level for atmospheric calculations. More...


Enumerations

enum  ordint {
  FSEE, WSEE, ISP, M2,
  FHEFF, HEFF, TC, LAST
}
enum  atmwhat { ATMPAR, CN2PROF }
enum  poweridx {
  IFSE, IWSE, IISP, IEFF,
  IISK
}

Functions

void init (int nchan, double diam, double *eps_inn, double *eps_out, double z0, double zmax, double dz, double dzmin, const char *responsefile)
 Initialize the module local structures for calculations. More...

int loadsed (const char *sedfile)
 Load the spectrum from file and check its validity. More...

int checkwf (const char *wfile)
 Check the weight file to fit the currently set system parameters and loaded spectrum. More...

void calcwf (const char *wfile, void(*progress)(int))
 Calculate the new set of weight functions and write it in the file. More...

void update (const char *wfile, const char *checkfile, double zshift1, double zshift2)
 Update the data structures for atmospheric calculations with a new weight function file. More...

void alloc (int nmeas)
 Allocate the storages for atmospheric integrals calculated by calcint(). More...

void done ()
 Deallocate the memory reserved for module structures. More...

double getval (ordint what)
 Return calibrated atmospheric parameter. More...

double geterr (ordint what)
 Return error of the calibrated atmospheric parameter. More...

int getncn2 ()
 Return number of the Turbulence profile altitudes. More...

double getzcn2 (int i)
 Get the altitude of the restored turbulence profile layer. More...

double getcn2 (int i)
 Get the strength of the restored turbulence profile layer or chi-square. More...

void calcint (double *scind, double *scinds)
 Compute the atmosphere integral parameters and Cn2-profile. More...

double calcn2 (double *scind, double *scinds, double *e2scind, double *e2scinds, bool isfixed)
 Restore the low-resolution Cn2 profile. More...

void avgint (double desi, double e2desi, double zdist)
 Average Cn2 integrals and compute from them the atmospheric parameters. More...

void write (FILE *f, const char *stamp, atmwhat what, bool header=false)
 Write computed atmospheric parameters or restored Cn2 profile or the header line for one of them. More...

double getavgint (int i)
 Get the average integral value. More...

double geter2int (int i)
 Get the squared error of the average integral. More...


Variables

const bool HEAD = true
const int NMODE = 2
const double MINRELW = 1e-4
const int MAXNBASE = 10
const char USESHFT [] = "1100100000"
const double POWSEE = 0
const double POWISP = 5/3.
const double POWEFF = 1.0
const double POWISK = 2.0
const double HBOUND = 1.0
const int NPOWER = 5
const double KS = 1.73588e+07
const double KP = 0.000756348
const double KT = 0.175
const double DZCN2 = 1
const char INTFMT [][8]
const char INTDLM [] = " "
const char ALTFMT [] = "%s%2.0f"
const char CN2FMT [] = "%s%8.2e"


Detailed Description

Namespace at contains the set of functions of highest logical level for atmospheric calculations.

Enumeration Type Documentation

enum atm::atmwhat
 

Writing selector in write():

Enumeration values:
ATMPAR  write atmospheric parameters
CN2PROF  write the restored Cn2 profile with altitudes and Chi-square

enum atm::ordint
 

Order of atmosphere integrals in their storage matrix and output file line. In a file, each value is followed by its error. LAST must stay always at the end since it gives a number of integrals in enumeration

Enumeration values:
FSEE  free seeing
WSEE  whole atm. seeing
ISP  isoplanatic angle
M2  second moment of turbulence (integral(Cn2(h)*h^2dh))
FHEFF  effective altitude of turbulence in free atm.
HEFF  effective altitude of turbulence in whole atm.
TC  atmospheric time constant

enum atm::poweridx
 

Arrangement of the moment decomposition coefficients in the coef[] array: it's essential for calcint() that IWSEE goes in advance to IFSEE.

Enumeration values:
IFSE  coef[Free seeing][]:
IWSE  coef[Seeing][]
IISP  coef[Isoplanatic angle][]
IEFF  coef[Turbulence effective altitude][]
IISK  coef[Isokinetic angle][]


Function Documentation

void alloc int    nmeas
 

Allocate the storages for atmospheric integrals calculated by calcint().

Parameters:
nmeas  maximal possible number of calcint() starts (base times per accumulation time)

void avgint double    desi,
double    e2desi,
double    zdist
 

Average Cn2 integrals and compute from them the atmospheric parameters.

Parameters:
desi  average DESI for shifted channel A
e2desi  squared error of desi
zdist  zenith distance in [degree]
Given the instantaneous integrals in their storage, their average values and standard deviations are computed and put in respetive global vectors. The function sc::avgmatrix() is used for averaging. Errors thus take into account the correlation of values.

Then the average integrals are converted into atmospheric parameters - seeing, isoplanatic angle and effective altitude of turbulence. They are available via getval() and - errors - via geterr(). Also, the atmospheric time constant is computed from provided desi and e2desi values.

Seeing is computed as

where the zero-moment Mo of the turbulence is:

(integration goes from 0 for whole-atm. seeing and starting from HBOUND for free-atm. seeing) and KS is the calibration constant.

Isoplanatic angle is computed as

where the 5/3-th moment of the turbulence profile is:

and is the calibration constant.

Second moment of the turbulence is related to the differential astrometry precision and the operation of optical interferometers. Unlikely the isoplanatic angle, it is saved in files with no any calibration to any "angle".

The free atmosphere effective altitude is computed as

where alpha_1 is 5/3 and alpha_2 is 1.

The value of Heff in the whole atmophere is computed by definition:

but only if the shifted indices are available.

The related to adaptive optics atmospheric time constant is computed from Differential Exposure Scintillation Index (DESI) as

where KT is the empirical calibration constant.

Note:
During the conversion of integrals into atmospheric parameters, the integrals are checked to be positive. If at least one of integrals is invalid, the error nr::ERNOD is set which will block the writing of results by write() unless error is reset by nr::erreset() after avgint() and before write().

void calcint double *    scind,
double *    scinds
 

Compute the atmosphere integral parameters and Cn2-profile.

Parameters:
scind  array of non-shifted indices
scinds  array of shifted indices (may be NULL)
Using the Cn2-moments decomposition coefficients and scintillation indices, the calculation of integral atmospheric parameters is performed. Number of indices in either scind or scinds must be equal to number of respective computed weights in wf which are made in init() call. No check of the validity of supplied scind(s) arrays is done.

The coefficients of multiplication of the indices in normal and shifted mode are already precomputed in init(); the results become accessible after the function call by getval() and geterr(). The atmospheric time constant is computed given the desi parameter. If scind(s) or desi parameters are empty (NULL or 0, respectively), the calculations for supplied not-NULL parameters are only made.

The computed quantities are saved in the current ine of the global storage for further averaging by avgint(). The number of calls to calcint() should not exceed the nmeas parameter of alloc().

Performance

One calculation of integrals takes 5 ms at PC P-III 667 Mhz.

double calcn2 double *    scind,
double *    scinds,
double *    e2scind,
double *    e2scinds,
bool    isfixed
 

Restore the low-resolution Cn2 profile.

Parameters:
scind  array of average non-shifted indices
scinds  array of average shifted indices (may be NULL)
e2scind  array of squared errors of scind
e2scinds  array of squared errors of scinds
isfixed  Use fixed-altitude layers restoration rather than strongest layers search
Returns:
Minimal chi-square reached, or (double)(error_code,<0) on error
The profile restoration results in altitudes of the getncn2() layers altitudes getzcn2() with strengths getcn2(). Two methods are implemented - the search for four strongest layers (if not isfixed) and the search for the intensity of six layers placed proportionally in the altitude range with relative resolution 0.5.

Performance

One restoration takes typically 45 ms at PC P-III 667 Mhz for the method with 6 fixed layers, and 140 ms for placing 4 floating altitude layers.

void calcwf const char *    wfile,
void(*    progress)(int)
 

Calculate the new set of weight functions and write it in the file.

Parameters:
wfile  file name to write the weight functions set in
progress  progress indicator function (may be null)
This function first checks the wfile with checkwf(). If result is zero (i.e. "ok"), nothing follows. If not, the weights are calculated with currently loaded spectrum and system parameters.

The grid parameters depend on the result of checkfile(). If the checking resulted in error sc::ERZGR (user-supplied grid in init() does not fit the file grid), the weights are calculated with user's grid, otherwise - with the "optimal" grid. Optimal grid parameters are specified in WEIF module - wf::Z0, wf::ZMAX, wf::DZ and wf::DZMIN.

int checkwf const char *    wfile
 

Check the weight file to fit the currently set system parameters and loaded spectrum.

Parameters:
wfile  weight file name
Returns:
0 if file fits, <0 on mismatch or error
The function wf_t::calcleff() is used with the current spectrum and then wf_t::checkfile() is used to check the file. The result of this function is returned.

void done  
 

Deallocate the memory reserved for module structures.

Returns:
void
This function releases the memory which is allocated for weights, SED, coefficients of Cn2-moments decomposition etc by init().

Note:
This function must be kept in strict sync with init(), update() and alloc().

double getavgint int    i
 

Get the average integral value.

Parameters:
i  kind of the integral, see atm::ordint
Returns:
array of averages
Available after avgint() call.

double getcn2 int    i
 

Get the strength of the restored turbulence profile layer or chi-square.

Parameters:
i  layer index [0..getncn2()-1] or getncn2() for Chi-square
Returns:
strength [m^-2/3]
Last element of required array contains the Chi-square measure of the fitted profile accessible as getcn2(getncn2()).

See also:
calcn2()

double geter2int int    i
 

Get the squared error of the average integral.

Parameters:
i  kind of the integral, see atm::ordint
Returns:
array of error^2 of averages
Available after avgint() call. Guaranteed to be non-negative.

double geterr ordint    what
 

Return error of the calibrated atmospheric parameter.

Parameters:
what  one of computed parameters - seeing, Heff, isoplanatic angle etc. presented in ordint enumeration
Returns:
error value or 0 on error
See also:
avgint()

int getncn2  
 

Return number of the Turbulence profile altitudes.

Returns:
Length of the private computed Cn2-array
Note that this number is not necessary the length of allocated array cn2[].

See also:
calcn2()

double getval ordint    what
 

Return calibrated atmospheric parameter.

Parameters:
what  one of computed parameters - seeing, Heff, isoplanatic angle etc. presented in ordint enumeration
Returns:
value or 0 on error
See also:
avgint()

double getzcn2 int    i
 

Get the altitude of the restored turbulence profile layer.

Parameters:
i  layer index [0..getncn2()-1]
Returns:
altitude [km]
See also:
calcn2()

void init int    nchan,
double    diam,
double *    eps_inn,
double *    eps_out,
double    z0,
double    zmax,
double    dz,
double    dzmin,
const char *    responsefile
 

Initialize the module local structures for calculations.

Parameters:
nchan  Number of the MASS detector channels to use
diam  see wf_t::setaper()
eps_inn  see wf_t::setaper()
eps_out  see wf_t::setaper()
z0  see wf_t::setzgrid()
zmax  see wf_t::setzgrid()
dz  see wf_t::setzgrid()
dzmin  see wf_t::setzgrid()
responsefile  The system transmission function file "lambda[mkm or nm or \AA] P(lambda)"
This function should be called, in general, once per working session, or if some basic system parameters (see the function parameters list) are changed. In this case, done() must be invoked in advance.

First, the global structures are initialized, including the normal and shifted weight functions sets. Then the weight-related instrumental parameters are initialized. Finally, the system transmission function is read from the file. The wavelengths, if different from [mkm], are converted into micrometers automatically.

See also:
done()

int loadsed const char *    sedfile
 

Load the spectrum from file and check its validity.

Parameters:
sedfile  name of the two-column ASCII file with spectrum "lambda[mkm or nm or \AA] E(lambda)"
Returns:
0 if Ok, <0 on error
The function calls the local file-reader utility (the same as used for the MASS response curve reading). If the file is successfully read (seems that spectrum does not contain errors as it is), the wavelengths, if different from [mkm], are converted into micrometers. Then an attempt is performed to multiply this spectrum by response curve read in init(). Here the negative error code may be returned if no match is found between them. If the spectrum matches the response curve, it is stored in a global module storage to be used in weight functions handling.

Possible errors (see nr::erget()) include:

  • sedfile is not readable
  • init() is not called in advance
  • spectrum is zero or spectrum does not match the MASS response curve with any offset. In this case nr::ermessage() may specify the row number of the spectrum file sedfile from where the problem originates.
See also:
update()

void update const char *    wfile,
const char *    checkfile,
double    zshift1,
double    zshift2
 

Update the data structures for atmospheric calculations with a new weight function file.

Parameters:
wfile  The file name of the weight matrix (see wf_t::write())
checkfile  file to print the moment approximation information for checking (may be null)
zshift1  Altitude shift (in [km], normally non-positive) for the normal mode or for one part of the generalized mode measurements
zshift2  Altitude shift (in [km], normally negative) for the rest part of the generalized mode measurements
This function should be called each time the star (i.e. its SED) or the measurement mode (generalized or normal; number of base times per accumulation time etc), is changed.

First, if the weight function matrix is new (its lastly loaded filename is stored internally), it is read from the file and all the calculations of the Cn2 moments decomposition are made. Also, the calculations are done if the z-shifts zshift1 and zshift2 have changed. Calculations involve the shift of weights by zshift1 and zshift2 and the approximation of the power-law dependences of altitude by shifted weight functions. The SVD method is used for this. Approximation enable us to represent the Cn2-moments by a set of scintillation indices. If zshift1 or zshift2 are non-zero, then both the coefficients for generalized and non-shifted modes are obtained. The coefficients are stored in global arrays to be used in calcint().

The quality of the approximation of the altitude moments with weight functions may be checked if one supplies the non-null file name checkfile. The utility writes then the decomposition coefficients and the approximated relations in this file. The file checkfile is rewritten each time, not appended, and consists of two similar parts - the first for approximations with zshift1 -shifted weights (normally - non-shifted) and the second for approximation with both zshift1 and zshift2 -shifted weights.

void write FILE *    f,
const char *    stamp,
atmwhat    what,
bool    header = false
 

Write computed atmospheric parameters or restored Cn2 profile or the header line for one of them.

Parameters:
f  FILE pointer
stamp  leading word in the output line
what  atm::ATMPAR: write atm. parameters, atm::CN2PROF: write the Cn2 profile
header  Write the header line instead of data
This utility writes the output results of atmospheric calculations on the disk.

For what==ATMPAR, the single line is written on disk, consisting of the average atmospheric parameters each followed by its error. Parameters are free seeing ["], seeing ["], isoplanatic angle ["], second moment of turbulence [m^{4/3}], and atmospheric time constant [ms].

For what==CN2PROF, the Cn2-profile data line is written. It consists of 1) the number of adjusted Cn2 layers, 2) Chi-square 3) the getncn2() altitudes of layers and each followed by it strength in [m^-2/3].

If header==true, the header line for respective what -selection is written instead of data. stamp must then contain the name of data which are normally written as a stamp when header==false.


Variable Documentation

const char atm::ALTFMT[] = "%s%2.0f"
 

Altitude of layers record format with leading "%s" for a delimiter

const char atm::CN2FMT[] = "%s%8.2e"
 

Profile values format with leading "%s" for a delimiter

const double atm::DZCN2 = 1
 

Cn2-profile restoration weight matrix spacing: 1km (integer-like!)

const double atm::HBOUND = 1.0
 

Height of the boundary layer [kilometers] to fit the Cn2-integral for free seeing (h^0 in integral is forced to resemble the AB-pair weight function below this height)

const bool atm::HEAD = true
 

Last (defaulted to "data"==false) parameter in write()

const char atm::INTDLM[] = " "
 

Delimiter of entries in the average data file

const char atm::INTFMT[][8]
 

Initial value:

 {"%s%6.3f","%s%6.3f","%s%6.3f","%s%8.2e","%s%5.0f",\
        "%s%5.0f","%s%5.2f"}
Formats of the records of average integral and their errors in the file. The order of strings follows the order of integrals specified in ordint. Each format must be preceded with "%s" to insert a delimiter specified in INTDLM.

const double atm::KP = 0.000756348
 

Calibration constant in isoplanatic angle formula (AstL 45, p.399) , where

const double atm::KS = 1.73588e+07
 

Calibration constant in seeing formula (AstL 45, p.399): , where lambda_eff is in [mkm]

const double atm::KT = 0.175
 

Atmospheric time constant empirical calibration constant for DESI for 1,3ms integrations in diameter=2cm apertures with -1km shift

const int atm::MAXNBASE = 10
 

Maximal number of orthonormal functions to use in h-powers restoration: (to apply after MINRELW based rejection)

const double atm::MINRELW = 1e-4
 

Minimal ratio of the singular value to the maximal one

const int atm::NMODE = 2
 

Number of modes: normal and generalized, hense = 2

const int atm::NPOWER = 5
 

Number of power laws to fit: 2 kinds of 0-th, 5/3-th, 1-st, 2-nd

const double atm::POWEFF = 1.0
 

Power of Cn2 moment for Effective altitude

const double atm::POWISK = 2.0
 

Cn2 second moment power

const double atm::POWISP = 5/3.
 

Power of Cn2 moment for isoplanatic angle

const double atm::POWSEE = 0
 

Power of Cn2 moment for seeing

const char atm::USESHFT[] = "1100100000"
 

Binary mask for using the shifted weights: "1"="use it". Now we thus use all non-shifted and As, Bs and ABs weights.


Generated on Wed Jan 16 00:40:06 2002 for MASS Software by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001