Index of /ssw/packages/vdem

      Name                    Last modified       Size  Description


[DIR] Parent Directory        23-Jan-2008 14:45      -  
[DIR] coeff/                  26-Jul-1999 13:20      -  
[DIR] idl/                    26-Jul-1999 13:15      -  
[DIR] setup/                  26-Jul-1999 13:16      -  

4/23/98

This is the README.TXT document for a package of routines which computes
the Velocity Differential Emission Measure (VDEM) from spectral line
profiles observed by the Yohkoh/BCS or SoHO/SUMER instruments.  Please
direct any questions about these routines to Dr. Elizabeth Newton
(elizabeth.newton@msfc.nasa.gov).

The Velocity Differential Emission Measure (VDEM) can be inverted or
deconvolved from observed spectral lines to recover the line-of-sight
velocity distribution of the emitting ion.   VDEM has units of
(photons s-1 (km s-1)-1).  The moments of VDEM are related to the
plasma's mass, momentum, and enthalpy flux.   Details on the derivation
and various uses of VDEM may be found in:

Newton, Emslie, Mariska 1995, ApJ, 447,915
Newton, Emslie, Mariska 1996, ApJ, 459, 804
Newton 1997, ApJ, 484, 455

There are 6 IDL .pro routines and one ASCII datafile associated with the
VDEM package:  vdem.pro, prep_vdem_bcs.pro, prep_vdem_sumer.pro,
gcvcompute.pro, gcvfunction.pro, v5_invert.pro, and excitcoef.dat.  
In order to utilize the data file, the user must set a vdem 
environment variable by adding the following line to the 
idl_startup.pro:
		set_env, 'VDEM=/where_vdem_files_are/".

A brief description of each routine follows below.  More detailed
documentation also appears at the beginning of each routine, in the
standard SolarSoft format.  These routines permit the user to input
observed spectra and obtain VDEMs for the line profiles.  No
post-processing (mass, momentum, or enthalpy) calculations are provided
in these routines however.

It should also be noted that the VDEM routines have really only
been validated for the Ca XIX and SXV lines observed by the BCS
or for SUMER lines.  The Fe lines observed by BCS present a particular
challenge for VDEM analysis since so many satellite lines are evidently
blended into the resonance line and there is fairly low resolution.
For this reason, it is not recommended to employ the VDEM package for
analysis of the Fe  lines.

Routines:

(1)  PREP_VDEM_BCS:
This routine prepares BCS data for use in VDEM.PRO.  In this routine,
spectra are extracted from Yohkoh BCS spectrally calibrated data files.
User-provided background is subtracted, and the user may define the
wavelength range over which the line will be inverted.  The background
model and wavelength window are important for successfully computing VDEM.

Prior to running this routine, the user must have generated Yohkoh/BCS
index and data arrays using yodat.pro (to select the flare, times,
channel, integration interval, etc.) as well as mk_bsc.pro (to perform
instrument calibrations and corrections).  In order to determine the
other inputs required by PREP_VDEM_BCS.PRO, the user should examine the
extracted spectra using plot_bsc.pro.   Specifically, the user must
determine the bin numbers of the first and last wavelength bins which
will define the wavelength range over which the line will be inverted.
Since the BCS wavelength is not absolutely calibrated, the user must
also determine the amount of correction to apply to the wavelength scale
to account for the pointing offset which arises from the flare's location
on the Sun.  Generally, to do this the user may examine the spectra
occurring late in the flare to determine the "rest wavelength" appropriate
for the flare and subtract this from the ion's laboratory rest wavelength
to determine the offset correction.   Finally, the user must have also
determined the background (constant or vector) to subtract from the spectra,
utilizing whatever method one prefers.

Once PREP_VDEM_BCS.PRO has been run, the data is ready for input into VDEM.PRO.


(2)  PREP_VDEM_SUMER
This routine prepares SUMER data for use in VDEM.PRO.  User-defined pixels
are averaged and calibrated.  Then a background may be computed for the
spectra and subtracted.  Finally SUMER's specific intensity data are
converted to flux data for processing by VDEM.PRO.

Prior to running PREP_VDEM_SUMER, the user must have generated SUMER
index and data arrays using the rd_sumer.pro routine.  It is also suggested
that the user calculate the wavelength array for the data set utilizing
observations of reference lines.

Once PREP_VDEM_SUMER.PRO has been run, the data is ready for input into VDEM.PRO.


(3) VDEM.PRO
This routine is the main program for inverting spectral line profiles
(BCS or SUMER) to obtain the VDEM.  Input data must be prepared using
either PREP_VDEM_BCS or PREP_VDEM_SUMER.  The user must also input the
appropriate atomic information for the emitting ion, such as the mass,
laboratory rest wavelength, and the average temperature at which the
ion is formed.

As a default, VDEM.PRO performs the spectral line inversions utilizing the
GCV technique to calculate the optimal smoothing parameter.  However, the
user may provide this smoothing weight as an optional  input.  VDEM.PRO
also utilizes a default velocity bin size which is the instrument's
observational limit, i.e.,
dvel= speed of light * wavelength binwidth/rest wavelength.

For the deconvolution, VDEM.PRO constructs a gaussian kernel function
with a default width equal to the thermal Doppler velocity of the ion.
However, the user may provide a nonthermal velocity as an optional input
in order to account for any nonthermal broadening, and, in the case of
SUMER, the instrumental broadening, that may be consistently
present in the line.  In the special case of the CaXIX line profiles
observed by Yohkoh/BCS, for which the user sets the keyword /CAXIX,
VDEM.PRO constructs a kernel which contains not only the main resonance
line feature, but also a structure which accounts for emission by the
d13 satellite feature.  This satellite feature appears on the long
wavelength side of the CaXIX resonance line and results in persistent
line asymmetry.  Hence the VDEM inversion must account for this feature
in order to arrive at a velocity distribution that does not overestimate
plasma downflows.

This routine outputs a structure containing the VDEM, errors in the VDEM,
and the velocity array.  VDEM.PRO may optionally provide a flux computed
by forward convolving the VDEM, so that this flux may be compared to the
observed flux.

Users are cautioned that the deconvolved VDEM's behavior at its
endpoints is poorly constrained by the data, and hence its endpoint
values will exhibit artifacts which typically arise in inverse problems.


(4) GCVFUNCTION.PRO
This function computes the Generalized Cross Validation (GCV) function
which is minimized by GCVCOMPUTE.PRO in order to find the optimal smoothing
parameter for the VDEM inversion.  Details on the derivation of GCV may
be found in Golub, Heath, & Wahba.  Newton et al. 1996 may be consulted
for its application to VDEM.


(5) GCVCOMPUTE.PRO
This routine minimizes the GCV function to compute the optimal smoothing
parameter for the VDEM inversion.  GCVCOMPUTE.PRO utilizes the
single-dimension bracketing and Brent's minimization schemes which are
published in Numerical Recipes.


(6) v5_INVERT.PRO
This routine determines which inversion procedure is employed, 
depending on the user's IDL version.

(7) EXCITCOEF.DAT
This ASCII file contains a (4 columns x 11 rows) array which
has the excitation coefficients for the Ca XIX 'w' line, 'd13' satellite
line, and the dielectronic recombination features (which contribute to
emission in the same wavelength range as the 'w' line).  This file
is utilized only if Yohkoh/BCS CaXIX spectra are being inverted and the /CAXIX
switch is employed.  The data come from Bely-Dubau et al. Dec. 1982,
RAS, Monthly Notices, v. 201, p. 1155-1169, "Dielectronic Satellite
Spectra for highly-charged He-like ions. VII. Calcium Spectra."  The
first column comprises temperature; the second, 'w' line coefficients;
the third, 'd13' coefficients; and the fourth, dielectronic
recombination values.