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

wf_t Class Reference

#include <weif.hxx>

List of all members.

Public Methods

 wf_t ()
 Initialize the object fields with zero/null values.

void clear ()
 Release the z-grid and weight matrix and assigns them zero. More...

 ~wf_t ()
 Release all dynamic memory storages for deletion of object. More...

void setaper (int nap, double diam=0, double *eps_in=0, double *eps_ou=0)
 Assign the reference size and relative diameters for apertures. More...

int getnaper () const
 Return the number of apertures set in structure. More...

int getnw () const
 Return the number of apertures and their combinations. More...

const char * name (int index) const
 Give a name for respective weight. More...

void setzgrid (double z0, double zmax, double dz, double dzmin)
 Generate the altitude grid given its parameters. More...

int getnz () const
 Return the number of altitude steps in z-grid. More...

void write (const char *filename) const
 Writes weight matrix with parameters in disk ASCII file. More...

int checkfile (const char *filename) const
 Checks the weight file header values to conform the wf_t parameters (fields). More...

int read (const char *filename)
 Read the object -- weight matrix and its parameters -- from the disk file. More...

void calc (double *lambda, double *edist, int nedist, void(*progress)(int))
 Calculate the weight matrix for a given energy distribution. More...

int calcleff (double *lambda, double *edist, int nedist, int fix)
 Calculate the effective wavelength and 50%-levels of the light energy distribution and compares them with that set in member fields. More...

void interpolate (wf_t *refwf, double shift, double *maxerr=0, int *iz_maxerr=0, int *iw_maxerr=0)
 Interpolate the weights from the reference object to the z-grid set in the object with a given optional z-shift. More...

double getleff () const
double getblue () const
double getred () const
double getval (int iz, int iw) const
 Get the weight value for given weight and altitude indices. More...

void copy (int lowiz, int hiiz, int iw, double *dest) const
 Copy (part of) a certain weight function to double-type array. More...

double getalt (int iz) const
 Get the altitude grid value for a given altitude index. More...


Detailed Description

This class contains all the data which describe the scintillation weighting functions of altitudes for all entrance apertures with which it is measured. The information on the apertures themselves and on the spectral characteristics of the incident light is also present in members of this class.

The allocation of the memory for double-type arrays is made in several member functions:

Deallocation of all the memory allocated for arrays is done by setaper() with one zero parameter (it is called also from the destructor).

The constructor initializes the arrays and members with zeros; in all functions null pointer is a necessary demand for array to allow its allocation and, wise versa, if an array is not null, it is believed to be already allocated.


Constructor & Destructor Documentation

wf_t::~wf_t   [inline]
 

Release all dynamic memory storages for deletion of object.

The feature of setaper() to release all the memory on call with a zero argument is used.


Member Function Documentation

void wf_t::calc double *    lambda,
double *    edist,
int    nedist,
void(*    progress)(int)
 

Calculate the weight matrix for a given energy distribution.

Parameters:
lambda  grid of wavelengths [mkm]
edist  incident energy distribution (given on lambda grid)
nedist  length of the lambda and edist grids
progress  function to call to visualize the work stage (if needed)
Given the parameters in numeric members of the object (aperture geometry) and input spectrum, the weights are computed on a filled zgrid (see setzgrid()).

The weights are computed for the polychromatic case of incident light SED which involves the Fourier Transform of the SED divided by the wavelength. This FT is made by wf::make_fft() once before calculation of all weights and is represented in two global arrays as cubic spline coefficients. In order to have smoother shape, the SED is shifted to its origin (starting wavelength ) to dump the high-frequency oscillations in FT. The back-correction for this shift is made analytically after the spline interpolation for the given frequency.

Before calculations, the weight matrix is allocated IF it was NULL. If it was not NULL, it is assumed that it was already allocated (e.g. in a previous call of this routine, say, with different en.dist.).

Then, for all apertures, their combinations and for all altitudes in the z-grid, the function wf::weight() is called to make the weight integration itself.

At the end, the SED characteristics computer calcleff() is called to fill in the respective spectral fields. It appears that effective wavelength represents best the shape of weights if they are computed for the "quasi-gaussian" approximation of SED with its actual FWHM. Meanwhile, the deviations may be as high as 10% from the exact shape, especially for differential indices of small apertures.

The utility calls the external function progress() (if supplied as non-null) to visualize the degree of the made work. This degree, in percents, is an integer-type argument changing from 0 in the beginning to 100 at the end. Progress function is called twice per altitude step.

Performance

At the IBM P-III 667 MHz machine, the calculations of weights with 26 proportional steps of altitude (up to 20 km) and for 4 apertures take 14 seconds.

int wf_t::calcleff double *    lambda,
double *    edist,
int    nedist,
int    fix
 

Calculate the effective wavelength and 50%-levels of the light energy distribution and compares them with that set in member fields.

Parameters:
lambda  grid of wavelengths [mkm]
edist  incident energy distribution (SED), given on lambda grid
nedist  number of nodes in lambda grid (points of en.dist.), or 0 to reset the spectral information in weight structure
fix  If fix==1: assign the computed spectral characteristics to wf_t fields, or leave them otherwise (use wf::LEFFFIX or wf::LEFFTEST)
Returns:
int(SED characteristics differ from that set in the structure) or the (negative) error code
The effective wavelength and the wavelengths at which the relative light energy is equal to 50% of the maximal are computed by the local linear interpolation for the given incident light SED. It is assumed that an array of relative intensities edist[] takes into account the instrument and atmospheric transmission functions. The computed effective wavelength and 50% points are first compared to the values in the fields leff, lblue and lred, and then assigned to them, if fix==1 and (!) the difference is significant.

The result of comparison is returned: 0 if the difference is not significant, i.e. all three calculated numbers are within +/- EPSLEFF interval from the field values, and 1 if at least one of them differs by more than EPSLEFF. All wavelengths are in [mkm].

If the parameter \nedist is supplied as 0, the calculations and comparison are skipped and the fields leff, lblue and lred are reset to zero. 0 is returned.

int wf_t::checkfile const char *    filename const
 

Checks the weight file header values to conform the wf_t parameters (fields).

Parameters:
filename  name of the file to read
Returns:
0 if parameters coincide, <0 if error or parameters do not coincide (the reason of incoincidence is reflected by following error codes: nr::ERSPE, nr::ERGEO and nr::ERZGR).
Procedure reads the header info in weight file (see description of the header in write() documentation) and checks whether the parameters given in the file header coincide (within some allowed errors) with respective fields of the supplied wf_t object. The latter can be, for example, initialized from some task-file (configuration file or something else). The aim is to get a clue to decide whether the weights for given parameters can be read from a given file or should be recomputed.

The comparison is made until the first significant difference is found, in the following order: Z-grid, Apertures and Spectrum.

The major source of the difference in weights is the spectrum of light and apertures geometry. Spectral characteristics in file (3 wavelengths, see calcleff()) must coincide to within EPSLEFF with given in wf; aperture diameters in wf_t and in file must differ not more than EPSD in a relative measure.

Another determinator is an altitude grid. The range boundaries in file (z0 and zmax) must cover from both sides the range in wf_t to be allowed. Since the weights are normally well interpolated, the minimal spacing in altitude dzmin and altitude modifier dz in file do not have to coincide to that given in wf. Instead, they only have to be not more than EPSZ times larger than in wf_t. If the grid in the file is thinner, it is accepted.

If no error is found in header, the function read() is called on the checked file with a trial weight structure. After call this structure is cleared and resulting error (if any ) is returned.

See also:
write() read()

void wf_t::clear  
 

Release the z-grid and weight matrix and assigns them zero.

The signature of allocation of memory to zgrid and ws members of wf_t is non-zero z-dimention nz and non-zero respective pointers. Memory is released if only both nz and pointers are not zero.

void wf_t::copy int    lowiz,
int    hiiz,
int    iw,
double *    dest
const
 

Copy (part of) a certain weight function to double-type array.

Parameters:
lowiz  low limit of the altitude index (see getnz())
hiiz  upper limit of the altitude index (see getnz())
iw  weight index, must be in range [0..getnw(wf)-1]
dest  double-type array
This function copies one of available rows of the weight matrix into the pre-allocated destination array.

Attention:
In case of unallocated dest vector, the segmentation fault failure occurs! It is only checked to be non-null.

double wf_t::getalt int    iz const
 

Get the altitude grid value for a given altitude index.

Parameters:
iz  altitude grid index, must be in range [0..getnz(wf)]
Returns:
Altitude value (non-negative, in [km])

double wf_t::getblue   const [inline]
 

Return the member lblue value

double wf_t::getleff   const [inline]
 

Return the member leff value

int wf_t::getnaper   const [inline]
 

Return the number of apertures set in structure.

Returns:
Number of apertures set in wf_t

int wf_t::getnw   const [inline]
 

Return the number of apertures and their combinations.

Returns:
Number of weights which corresponds to the apertures number set
The function which returns the number of apertures and their combinations with no difference in order is defined in scind.hxx: sc::napcomb().

int wf_t::getnz   const [inline]
 

Return the number of altitude steps in z-grid.

Returns:
Number of z-steps set in object

double wf_t::getred   const [inline]
 

Return the member lred value

double wf_t::getval int    iz,
int    iw
const
 

Get the weight value for given weight and altitude indices.

Parameters:
iz  altitude grid index, must be in range [0..getnz(wf)-1]
iw  weight index, must be in range [0..getnw(wf)-1]
Returns:
Weight value (non-negative)
See also:
copy()

void wf_t::interpolate wf_t *    refwf,
double    shift,
double *    maxerr = 0,
int *    iz_maxerr = 0,
int *    iw_maxerr = 0
 

Interpolate the weights from the reference object to the z-grid set in the object with a given optional z-shift.

Parameters:
refwf  wf_t to get the weights from
shift  the shift of weight function along z-grid [km]
maxerr  pointer where to put the maximal weight error due to interp (works in POLINT option of compilation; may be null).
iz_maxerr  pointer to put the z-grid index of this error (may be null)
iw_maxerr  pointer to put the weight index of this error (may be null)
This function uses the NR recipe for interpolation of weight values from one z-grid into another. Input weight structure wf_t must be fully determined; output structure must only contain the computed new z-grid: i.e. only the setzgrid() function must be called for it before interpolation. Other parameters must be empty - they will be assigned from the reference wf_t fields.

The parameter shift allows one to obtain the shifted weighting functions suited to work with the indices measured with the shifted pupil of the system (defocusing of the instrument). The negative altitudes when probed during the interpolation of the positively shifted functions are replaced with their absolute values. When negatively shifted function is stretched to reach the same zmax, the extrapolation case takes place.

The rest parameters are three pointers to variables in which the user may receive the estimated maximal interpolation error of the weight, and the indices in z-grid and weight number where this maximal error was found. For example, for 4-aperture weight matrix (10 weights for each altitude), iz_maxerr = 2 and iw_maxerr = 5 will mean that maximal error maxerr was found at the third stage of the NEW altitude grid zgrid[2] and for the weight of AC-aperture combination.

const char* wf_t::name int    index const [inline]
 

Give a name for respective weight.

Parameters:
index  sequential number of weight in weight matrix
Returns:
pointer to the static const char* name, which is empty if index is invalid
Name of the weight is a name of aperture or their combinations which corresponds to the given index. Thus, this function is just a synonym of sc::apername(). In case of a problem, the error message nr::ermessage() originates from the WEIF module.

int wf_t::read const char *    filename
 

Read the object -- weight matrix and its parameters -- from the disk file.

Parameters:
filename  name of file to read
Returns:
0 if Ok, <0 if reading error
Procedure reads the matrix of weights and its parameters from the disk file into the fields of object. Thus, parameters are modified compared to that assigned to the structure fields before. Before reading, the procedure will try to clear all the dynamic data if the pointers of respective member arrays are not nulls.

This function is meant to be used with files which were tested by checkfile() to contain exactly the needed data. It does not check the validity of numbers in file. The weight matrix and z-grid data are converted from character representation to floating point numbers with standard function "strtod" and thus checked to be indeed numbers. Otherwise, the nr::ERFIO is returned and the altitude where the error in weight value occured.

Note:
The zgrid[] is read directly from the leftmost column of data section of the weight file and is NOT CHECKED to correspond to the given z-grid parameters z0,zmax,dz,dzmin parameters which are read from the header.
See also:
checkfile()

void wf_t::setaper int    nap,
double    dia = 0,
double *    eps_in = 0,
double *    eps_ou = 0
 

Assign the reference size and relative diameters for apertures.

Parameters:
nap  number of annular apertures
diam  reference size or magnification factor
eps_in  array of inner diameters of apertures [cm]
eps_ou  array of outer diameters of apertures [cm]
Procedure assigns the field naper to the number of apertures and allocates and fills in the arrays of their relative sizes. Input arrays eps_inn and eps_out are interpreted as:
  • physical instrumental sizes of apertures -- then diam plays the role of the magnification of the system;
  • or relative sizes ( ) with respect to the outer diameter of the largest aperture -- then diam is a size of a largest entrance aperture.
In any case, only the values diam*eps_... have a physical sense.

Usage:

  • if nap<0, then the member arrays eps_inn and eps_out are simply ASSIGNED to parameters eps_in and eps_ou, respectively. In this case they are not released afterwards (see naper==0 case) -- the member flag staticapert is set "true" for this.
  • if nap>0, then input arrays are COPIED into newly allocated member arrays eps_inn, eps_out. staticapert is set "false" to allow releasing of them in destructor.
  • If nap==0, then this function RELEASES all the memory allocated previously in dynamic memory for member arrays.
See also:
setzgrid()

void wf_t::setzgrid double    uz0,
double    uzmax,
double    udz,
double    udzmin
 

Generate the altitude grid given its parameters.

Parameters:
z0  starting altitude [km]
zmax  altitude to reach [km]
dz  altitude modifier ([km] for equidistant grid, unitless for proportional)
dzmin  minimal altitude step [km]
Compute the grid of altitude steps for calculation of weighting functions like follows:

The grid may be either equidistant (if dzmin ==0) or proportional (dzmin !=0). The current restriction is that the altitude modifier should be positive.

Equidistant grid is given as:

where i is in [0,nz-1], nz conforms to the following condition:

and

Proportional grid is constructed as follows:

        z[0] = z0
        z[i] = z[i-1] + step
        step0 = z[i-1] * dz
        step = ( dzmin > step0 ) ? (step = dzmin) : (step = step0)
        
where i is in [0,nz-1], nz conforms to the following condition:

and

In both types of grid, z[nz-1] is replaced with zmax.

This function is an interface to the lower-level private function zgrid_set() which works directly with the array wf_t::zgrid.

See also:
setaper()

void wf_t::write const char *    filename const
 

Writes weight matrix with parameters in disk ASCII file.

Parameters:
filename  file name to write weight
Procedure writes the matrix of weights which rows are preceded with the z-grid altitudes in the first column. The header is also created which contains all the parameters - the fields of wf_t.

The format of the header line is following:

        # <KEY> <VALUE1> [<VALUE2> [VALUE3 VALUE4]]
        

where <KEY> is a single-letter designation of parameter and <VALUE> - its value(s). Keys are listed below with names of respective wf_t fields and description in brackets:

  • N --naper (number of apertures)
  • A -- D*eps_inn[0] D*eps_inn[0] (diameters of the 1st aperture)
  • B -- D*eps_inn[1] D*eps_inn[1] (diameters of the 2nd aperture)
  • ...
  • S -- leff lblue lred (effective wavelength and 50%-level points in [mkm])
  • Z -- z0 zmax dz dzmin (parameters for an altitude grid generation)
  • W --weightscale (the scale-factor for the weight values written in this file)
After the header, the line goes which precedes the z-grid and wf-matrix values:

        ##Altit. W(A)/1E+11 W(B)/1E+11 ... W(AB)/1E+11
        

where 1E+11 is a number to which the values of weights are scaled in a file (weightscale).

Any similar line which starts with "##" is interpreted by wf_t::read() as a comment.

After the heading line "#Altit..." the z-grid and weight-matrix values go being separated with spaces for each altitude; thus -- one line per each altitude.


The documentation for this class was generated from the following files:
Generated on Wed Jan 16 00:40:06 2002 for MASS Software by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001