Extended IDL Help

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue Jan 4 12:52:37 2011.


List of Routines


Routine Descriptions

CORRECT_POPS

[Next Routine] [List of Routines]
 NAME

    CORRECT_POPS()

 PROJECT

    CHIANTI

 EXPLANATION

    Corrects CHIANTI level populations with the ionization and recombination
    rate coefficients

 INPUTS

    PP      The level populations that need to be corrected.

    T       Temperature at which calculation is performed. Units: K.

    XNE     Electron density at which calculation is performed. Units: cm^-3

    IONREC  Structure with the following tags
            .rec        Effective recomb. rate coefficients
            .ci         Effective ionization rate coefficients
            .temp       Temperatures at which rates are tabulated
            .lev_up_rec Levels to which recombination takes place
            .lev_up_ci  Levels to which ionization takes place
            .status     Either +1 (ion/rec data exists) or -1 (dosen't exist)
            .ioneq      Ion fractions of the 3 ions

    CC      2D matrix produced by MATRIX_SOLVER that contains the rate
            coefficents from the standard CHIANTI processes.

 OPTIONAL OUTPUTS

    CRATE   A 1D array of same size as POP containing the collisional
            ionization rate coefficients (units: cm^3 s^-1).

    RECRATE A 1D array of same size as POP containing the recombination
            rate coefficients (units: cm^3 s^-1).

    CORRECTION A 1D array of same size as POP containing the correction
               factors for each level.

    FRAC_LOW The ratio of the current ionization fraction to the fraction
             of the one lower ion (i.e., less ionized).

    FRAC_HIGH The ratio of the current ionization fraction to the fraction
              of the one higher ion (i.e., more ionized).

 CALLS

    ION_FRAC_INTERP(), CI_REC_INTERP()

 HISTORY

    Ver.1, 10-Jun-2005, Peter Young
        Taken original code of Enrico Landi and inserted it into a separate
        routine.

    Ver.2, 16-Aug-2005, Peter Young
        Changed total_exc to be dblarr in order to prevent NaNs.

    Ver.3, 1-Feb-2006, Peter Young
        Corrected error: sum of populations is now renormalized to 1.

    Ver.4, 12-Jun-2009, Enrico Landi
        Changed the temperature array for ion fractions, now taken from
        the IONREC variable

    Ver.5,  6-Jul-2009, Enrico Landi
        Corrected error in the definition of total_rate

    Ver.6, 30-Oct-2009, Enrico Landi
        Corrected error in the calculation of the correction factor

(See level_population/correct_pops.pro)


MATRIX_SOLVER

[Previous Routine] [Next Routine] [List of Routines]
 NAME

    MATRIX_SOLVER()

 PROJECT

    CHIANTI

 EXPLANATION

    Takes the matrices for the various atomic processes employed in
    CHIANTI and returns the level populations.

 INPUTS

    XNE    Electron density (cm^-3). Scalar.

    AA     2-D array of transition probabilities.

    QQ     2-D array of electron excitation rates.

    PPR    2-D array of proton rates

    AAX    2-D array of photoexcitation/stimulated emission rates.

 OPTIONAL INPUT

    FRAC_CUTOFF The fraction of non-zero elements in the C matrix below
                which the sparse matrix solver is used. The default value
                is zero (i.e., don't use sparse matrix solver).

 OPTIONAL OUTPUT

    C      The 2D matrix containing all rate coefficients.

 OUTPUT

    A 1-D array of level populations, scaled so that the sum of the 
    populations is 1.

 HISTORY

    Ver.1, 1-Jul-2005, Peter Young

    Ver.2, 10-Mar-2006, Peter Young
        commented out warning message about status as the level populations
        are still accurate to < 0.001% when this occurs and so it's not
        neccessary to warn users.

(See level_population/matrix_solver.pro)


PLOT_POPULATIONS

[Previous Routine] [Next Routine] [List of Routines]

 PROJECT:  CHIANTI

       CHIANTI is an Atomic Database Package for Spectroscopic Diagnostics of
       Astrophysical Plasmas. It is a collaborative project involving the Naval
       Research Laboratory (USA), the University of Florence (Italy), the
       University of Cambridge and the Rutherford Appleton Laboratory (UK). 


 NAME:
	PLOT_POPULATIONS

 PURPOSE:
	plot the population of a number of the lowest levels as a function of 
       electron density for a specific temperature

 CATEGORY:

	science.

 CALLING SEQUENCE:

       PLOT_POPULATIONS,Ion,T,Nlevels


 INPUTS:

       Ion:  CHIANTI style name for the ion, i.e., 'c_6' for C VI
       T:  electron temperature (K)


 OPTIONAL INPUT:
       Nlevels:  the number of levels for which populations are plotted
                 starts from level 1 (the ground level)

	
 KEYWORD PARAMETERS:

	OUTFILE:   the (optional) name of the output file where the listing 
                  is produced
	PSFILE:    the (optional) name of the output file where a postscript 
                  plot produced

	RADTEMP	Specify background radiation temperature (default: 6000 K)

	RPHOT   Distance from the centre of the star in stellar radius units.
               I.e., RPHOT=1 corresponds to the star's surface. (Default is
               infinity, i.e., no photoexcitation.)

       NOPROT  If set, then the default setting will be NOT to use 
               proton rates. This can be changed within the routine.

               NOT_INTERACTIVE Avoid interactive use.

 OUTPUTS:


 COMMON BLOCKS:

	common elvlc,l1a,term,conf,ss,ll,jj,ecm,eryd,ecmth,erydth,eref
       common wgfa, wvl,gf,a_value
       common upsilon,t_type,c_ups,splups

 CALLS

       POP_SOLVER, ION2SPECTROSCOPIC, ION2FILENAME, READ_IP,
       CONVERTNAME, READ_ELVLC, READ_WGFA2, READ_SPLUPS

 EXAMPLE:

 to plot populations of the 5 ground configuration levels of Fe XIII
 and store these values in a file 'Fe_XIII.lis' for a temperature of 1.5 MK

             > plot_populations,'fe_13',1.5e+6,5,outfile='Fe_XIII.lis'

 MODIFICATION HISTORY:

 	Written by:	Ken Dere
	March 1996:     Version 2.0
       November 1997:  Ken Dere, added psfile keyword
       September 1999:  Ken Dere, for Version 3, 
       14-Jul-2000     Peter Young, now calls pop_solver
	Version 6, 21-Dec-2000, William Thompson
		Modified for better cross-platform capability.

       V. 7, 21-May-2002, Giulio Del Zanna (GDZ), modified the plotting bit
                   generalized directory concatenation to work for
                   Unix, Windows  and VMS. 

       V 8, 15-July-2002, GDZ 
         Added keyword  not_interactive

       V 9, 4-Oct-2003, GDZ
                  modified the input to POP_SOLVER, now it is dealt with an
                  input structure.

       V 10, 4-May-2005, Enrico Landi (EL)
                  Modified in order to include ionization and recombination
                  data in the input to POP_SOLVER, now it allows choice of .ioneq
                  file needed to include ionization and recombination.

       V 11, 12-Aug-2005, GDZ 
                  The number of levels is now optional. Also, a check that the
                  number of levels must be less than the levels in the file is
                  now enforced.

       V 12, 12-Jun-2009, Enrico Landi
                  Changed the definition of the temperature array for ion fractions
                  in the IONREC variable, now taken directly from the output of
                  READ_IONEQ.PRO


 VERSION     :   12, 12-Jun-2009

(See level_population/plot_populations.pro)


POP_PLOT

[Previous Routine] [Next Routine] [List of Routines]

 PROJECT:  CHIANTI

       CHIANTI is an Atomic Database Package for Spectroscopic Diagnostics of
       Astrophysical Plasmas. It is a collaborative project involving the Naval
       Research Laboratory (USA), the University of Florence (Italy), the
       University of Cambridge and the Rutherford Appleton Laboratory (UK). 


 NAME: POP_PLOT
       
 PURPOSE:

	To compute n_j A_ji / N_e for a selected transition(s) and plot it
	against N_e. If it is insensitive to N_e, then the line(s) is 
	suitable for emission measure analysis.

 CATEGORY:

       Atomic data analysis

 EXPLANATION:

	The routine calls EMISS_CALC to give values of DE*n_j*A_ji at the 
	temperature TEMP and densities from 10^8 to 10^12. You are then 
	asked to select which transition(s) you are interested in. (If 
	more than one line is selected, the lines are blended.) 
	DE*n_j*A_ji/N_e is then plotted against density.

	If TEMP is not specified, then the temperature at which the 
	ionisation fraction has its maximum is calculated. For the iron 
	ions, the ion balance calcs of Arnaud & Raymond are used, 
	otherwise Arnaud & Rothenflug are used. If TEMP is specified, 
	and the value is less than 20, then it is assumed that the log 
	of the temperature has been specified.

	In emission measure work it is important to isolate lines for 
	which DE*n_j*A_ji/N_e is insensitive to density. If only such lines 
	are used, then the derived emission measure curve is independent 
	of density.

 CALLING SEQUENCE:

       POP_PLOT, IZ, ION, WRANGE=WRANGE, [TEMP=TEMP, /QUICK, DATA=DATA, $
				DENS_RANGE=DENS_RANGE, DILUTE=DILUTE]

 EXAMPLES:

	POP_PLOT, 26, 14, WRANGE=[330,360]

	- 3 lines should appear in the widget. Selecting 334.17 should show 
	a curve that falls off with density. Choosing 353.83 shows a curve 
	that rises with density. By selecting a blend of the two lines, 
	the curve will be insensitive to density, telling us that only a 
	blend of 334.17 and 353.83 is suitable for emission measure work.

	POP_PLOT, 8, 4, WRANGE=[550,560], TEMP=6.0, /QUICK, DENS_RANGE=[6,10]

	- O IV is a member of the boron sequence, and so calculations take a 
	lot longer. Giving the QUICK keyword speeds things up. The 
	temperature is well away from the T_max of the ion

 INPUTS:

	IZ	The atomic number of the ion

	ION	The spectroscopic number of the ion (e.g., 12 = XII)

 OPTIONAL INPUTS:

	DILUTE	Used to set radiative dilution factor. (Default: 0.0)

	TEMP	The temperature at which calculations are required. Usually 
		this will be the Tmax of the ion.

	DENS_RANGE  The default density range is log Ne = 8 to 12. By 
		    inputting two integers, a different range can be chosen.

	WRANGE  Wavelength range from which lines are required. If not 
		given, then the user is allowed to choose from the complete 
		set of lines for the ion.

       ABUND_FILE  The name of a CHIANTI abundance file. This is used for 
               calculating the proton to electron ratio. Default is 
               !abund_file.

       IONEQ_FILE  The name of a CHIANTI ion balance file. This is used for 
               calculating the proton to electron ratio and evaluating 
               the T_max of the ion. Default is !ioneq_file.

       RADTEMP The blackbody radiation field temperature (default 
               6000 K).

       RPHOT   Distance from the centre of the star in stellar radius 
               units. I.e., RPHOT=1 corresponds to the star's surface. 
               (Default is infinity, i.e., no photoexcitation.)

 OPTIONAL OUTPUTS:

	DATA:	An array that contains the data that is plotted: data(*,0) 
		contains
		the densities, while data(*,1) contains the Y-axis values.

 KEYWORDS:

       NOPROT  If set, then the default setting will be NOT to use 
               proton rates. This can be changed within the routine.

	QUICK:	The density range over which the calculations are done is 
		8 to 12 in 0.2 intervals. This keyword forces the 
		calculations to be done at 0.5 intervals.

 CALLS:

	EMISS_CALC, EMISS_SELECT, READ_IONEQ

 HISTORY:

	Ver.1, PRY 28-Jul-97.
	Ver.2, PRY 23-Sep-97 - added DILUTE keyword for photo-excitation
	Ver.3, PRY 30-May-98 - added DENS_RANGE
	Ver.4, PRY 5-Sep-98  - added call to choose_ioneq
	Ver.5, PRY 7-Apr-99  - tidied up, and introduced call to emiss_select
       Ver.6, PRY 7-Dec-01  - modified for v.4 of CHIANTI

       V. 7, 21-May-2002, Giulio Del Zanna (GDZ) 
                   generalized directory concatenation to work for
                   Unix, Windows  and VMS. 

       V.8, 06-Aug-02 GDZ
              added ABUND_FILE to the call to emiss_calc (was missing).
              Changed the use of CHIANTI system variables. 


 VERSION     : 8,  06-Aug-02

(See level_population/pop_plot.pro)


POP_PROCESSES

[Previous Routine] [Next Routine] [List of Routines]
 NAME

      POP_PROCESSES

 PROJECT

      CHIANTI

 PURPOSE:

      Outputs to the screen the contributions of the different physical 
      processes to the population of the specified level within the ion. 


      E.g., for Fe XIII, level 4, the output is:

      Population leaving level 4
        rad. decay:     1.51e+01     39.17%
        e de-exc:       3.56e-01      0.92%
        e exc:          2.28e+01     59.12%
        p de-exc:       2.63e-01      0.68%
        p exc:          4.05e-02      0.11%
        stim. emiss:    0.00e+00      0.00%
        photoexc:       0.00e+00      0.00%
                        --------
                 TOTAL  3.85e+01
      
      Population entering level 4
        rad. decay:     3.59e+01     93.19%
        e de-exc:       3.81e-02      0.10%
        e exc:          1.46e+00      3.79%
        p de-exc:       3.18e-03      0.01%
        p exc:          1.12e+00      2.91%
        stim. emiss:    0.00e+00      0.00%
        photoexc:       0.00e+00      0.00%
                        --------
                 TOTAL  3.85e+01

      which shows that the level population is dominated by electron
      excitation and cascading into the level, and by radiative decay
      out of the level.

      Note that the rates for each physical process are multiplied by the 
      population of originating level (this results in the totals for 
      entering and leaving the level to balance).

      For some ions, ionization and recombination are additional processes
      included when working out the level balance. Because of the way these
      processes are included (see the v.5 paper for details), the populations
      entering and leaving some levels *will not balance*.

 INPUTS

      IZ      The atomic number of the ion

      ION     The spectroscopic number of the ion (e.g., 12 = XII)

 OPTIONAL INPUTS

      LEVEL   The ion level for which information is required.

      DENS    Electron density at which rates calculated (units: cm^-3).
              If not specified, a value of 10^10 is assumed.

      TEMP    Temperature at which rates calculated (units: K). If not set,
              then T_max of the ion is used

      PATH    If the ion data-files are not in the CHIANTI directories, 
              then PATH allows you to choose an alternative location.

      RPHOT   Distance from the centre of the star in stellar radius units.
              I.e., RPHOT=1 corresponds to the star's surface. (Default is
              infinity, i.e., no photoexcitation.)

      RADTEMP Specify background radiation temperature (default: 6000 K)

      N_LEVELS Restrict the ion model to this number of levels. E.g., if
               the CHIANTI model contains 40 levels for the ion, then
               setting N_LEVELS=12 reduces the model to 12 levels.

      RADFUNC  The name of a user-defined function that will generate
               a radiation spectrum as a function of temperature. 
               This radiation field will replace the black-body that
               is assumed when using the RADTEMP keyword in the call
               to pop_solver.

 KEYWORDS

      NOPROT  If set, then the default setting will be NOT to use 
              proton rates. This can be changed within the routine.

 CALLS

      R2W, ZION2FILENAME, PROTON_DENS, POP_SOLVER, SETUP_ION

 EXAMPLES

      One can compare the effect of cascading on a level population by using
      the N_LEVELS keyword. Consider the case of Fe XIV:
        IDL> pop_processes,'fe_14',lev=5
        IDL> pop_processes,'fe_14',lev=5,n_levels=12
      With the first call there are two dominant terms to the population
      entering level 5: approximately 47% for radiative decays (cascading)
      and 53% for electron excitation. Setting n_levels=12, one finds that
      the cascading contribution disappears as there are no longer any
      high-lying levels that cascade into level 5. The cascading provides
      a strong contribution to the population of this level.

 HISTORY

      Ver.1, 11-Sep-2002, Peter Young
      Ver.2, 15-Jan-2004, Peter Young
          modified call to pop_solver following recent revision to
          pop_solver; changed input from IZ,ION to IONNAME to match other
          CHIANTI routines
      Ver.3, 26-May-2005, Peter Young
          changed TEMP and DENS keywords
      Ver.4, 10-Jun-2005, Peter Young
          added common block for ionization/recombination data and modified
          INPUT structure.
      Ver.5, 14-Jun-2005, Peter Young
          routine now prints the percentage contribution of each process;
          added N_LEVELS= keyword
      Ver.6, 1-Jul-2005, Peter Young
          added warning for ions with ionization/recombination
      Ver.7, 12-Jun-2009, Enrico Landi
          Changed the definition of the temperature array for ion fractions
          in the IONREC variable, now taken directly from the output of
          READ_IONEQ.PRO

(See level_population/pop_processes.pro)


POP_SOLVER

[Previous Routine] [Next Routine] [List of Routines]

 PROJECT:  CHIANTI

       CHIANTI is an atomic database package for the calculation of
       astrophysical emission line spectra.  It is a collaborative project
       involving Ken Dere (Naval Research Laboratory, Washington DC), 
       Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory, 
       Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).


 NAME:  POP_SOLVER
       
 PURPOSE:

	To solve the level balance equations for Chianti ions.

 CATEGORY:

       Scientific analysis
 
 EXPLANATION:

	This routine solves the level balance equations for the CHIANTI ions. 
       Atomic data is pre-loaded into the COMMON blocks, and so POP_SOLVER 
       can only be called indirectly through other routines.

       The matrix equation Ax=b is solved where A contains all the atomic 
       data (electron rate coefficients, radiative decay rates, proton rate 
       coefficients, photoexcitation rates), x are the level populations, 
       and b a vector set to zeros except for the first element which is 1.

       To solve the matrix equation, pop_solver calls out to the CHIANTI
       routine matrix_solver.

       The matrix A is created from the atomic data in the COMMON blocks. 
       In order to optimise POP_SOLVER, A is created where possible through 
       array operations rather than FOR loops.

       With v.5 of CHIANTI the additional atomic processes of ionization
       and recombination can be included when calculating the level
       populations. These processes are not included in the matrix A.
       Instead the level populations x are 'corrected' for ionization and
       recombination afterwards. This correction is performed by the routine
       correct_pops. More details of this method are found in the CHIANTI
       v.5 paper.

 CALLING SEQUENCE:

	POP_SOLVER, T, XNE, POP, N_LEVELS=N_LEVELS

 INPUTS:

	T	Temperatures, e.g., 10.^6

	XNE	Densities, e.g., 10.^8

 OPTIONAL INPUTS:

	N_LEVELS	This allows the number of levels in the model to 
			be reduced. E.g., if the full model contains 100 
			levels, one could set n_levels=50. This can be 
			useful if one is interested in looking at the 
			effects of cascading from higher levels

       SUM_MWL_COEFFS  An array of coefficients of the same length as 
                       the array of temperatures. Electron and proton rate 
                       coefficients will be calculated at each temperature 
                       and then a weighted sum of the coefficients is 
                       performed using SUM_MWL_COEFFS. This allows 
                       non-Maxwellian energy distributions to be 
                       incorporated into the level balance equations.

       RADFUNC         The name of a user-defined function that will generate
                       a radiation spectrum as a function of temperature. 
                       This radiation field will replace the black-body that
                       is assumed when using the RADTEMP keyword in the call
                       to pop_solver.

       FRAC_CUTOFF     The fraction of non-zero elements in the C matrix below
                       which the sparse matrix solver is used. See the routine
                       matrix_solver for more details.

 OUTPUT:

	POP	An array of level populations of size 
		n_T x n_XNE x n_levels

 OPTIONAL OUTPUTS

       DATA_STR If POP_SOLVER is called for just 1 temperature and density, 
                then the individual data arrays for each of the physical 
                processes can be output through DATA_STR. This allows the 
                user to check for the dominant processes affecting the 
                population of a given level. DATA_STR is a structure with 
                the following tags:

                .aa          A-values (2D array)
                .aax         Photoexcitation/stimulated emission (2D array)
                .cc          Electron rate coefficients (2D array)
                .ccp         Proton rate coefficients (2D array)
                .ion_rate    Ionization rate (1D array)
                .rec_rate    Recombination rate (1D array)
                .correction  Correction factor for level pop (1D array)
                .frac_low    Ratio of N+1 ion fraction to N (scalar)
                .frac_high   Ratio of N-1 ion fraction to N (scalar)

                The 2D arrays are such that, e.g., aa[0,20] 
                corresponds to an excitation, while aa[20,0] is a 
                de-excitation.

                The 1D arrays are simply the rate coefficients into the
                individual levels.

 PROGRAMMING NOTES:

       PROTON RATES
       ------------
       To include the proton rates, it is necessary to have the 
       proton-to-electron ratio. This needs to be calculated before the 
       call to pop_solver, and the resulting ratio(s) passed through 
       'pe_ratio' in the common block 'proton'.

       Note that there is no keyword to switch off proton rates (i.e., 
       no /NOPROT keyword). To switch off proton rates, it is necessary 
       to set pstr=-1. This should be done by the calling routine.


 COMMON BLOCKS:

	None.

 CALLS:

	DESCALE_ALL, PROTON_DENS(), MATRIX_SOLVER(), CORRECT_POPS()

 HISTORY:

	Ver 1, PRY 29-Mar-99
	Ver 2, PRY 30-Apr-99, added call to get_prot_rates
	Ver 3, PRY 15-Dec-99, added deu to upsilon common block in order 
		to be consistent with the main Chianti routines.
	Ver 4, PRY 9-May-00, corrected problem with threshold when dealing 
		with sparse matrices. Basically values less than 1.e-30 in 
		the c-matrix were being set to zero and giving rise to 
		NaN's in certain circumstances.
       Ver.5, PRY 14-Jul-00, changed elvl common block to the elvlc common 
               block which is now the Chianti standard. Also, when 
               descaling upsilons, the routine now uses the Delta-E from 
               the .splups file.
       Ver.6, PRY 9-Aug-00, changed routine to deal better with the 
               dielectronic recombination files
       Ver.7, PRY 17-Aug-00, routine does not call LINBCG now if radtemp 
               is non-zero.
       Ver.8, PRY 29-Aug-00, the sparse matrix section has been disabled.
       Ver.9, PRY 12-Nov-01, calls routine proton_dens() to calculate the 
               proton to electron ratio.
       Ver.10, PRY, 6-Dec-01, corrected bug when there are more levels 
               in .splups file than in .elvlc file (ZnXXV).
       Ver.11, PRY, 11-Jul-02, removed ION keyword
       Ver.12, PRY, 9-Aug-02, within the equation solving section, I've set 
               the population of the ground level (rather the n_level level) 
               to 1, and this seems to stop negative populations appearing 
               in extreme conditions.
       Ver.12, PRY, 21-Aug-02, changed exp(-1/1/a) to exp(-a) in electron
               excitation section which caused a hang-up in some 
               circumstances. Also, the routine now uses vector ECMC 
               (combined experimental and theoretical energies) in 
               determining if a level lies above or below another level. 
               Previously only used the observed energy vector. Also, the 
               exponential in the electron excitation section now uses the 
               (accurate) .elvlc energy separation rather than the .splups 
               energy separation, which can cause significant (~20-30%) 
               differences in level populations of high-lying levels at 
               low temperatures.
       Ver.13, PRY, 10-Sep-02, corrected bug for proton rates. The excitation 
               and de-excitation rates were being swapped.

       V. 14  4-Oct-2003  Giulio Del Zanna (GDZ).
               -removed all COMMON blocks (note that only proton_dens.pro has
                one: COMMON elements,abund,abund_ref,ioneq,ioneq_logt,ioneq_ref)
               -only the essential information input is passed to the routine
                via a new input structure.
               -fixed a bug, that affected all the satellite lines, and was 
                introduced in v.12,  included in  CHIANTI v.4.0.
                basically the ionization potential was not subtracted when
                calculating the Delta E in the exponential.

       V. 15  7-Oct-2004  Enrico Landi (EL)
               Included ionization and recombination as level population 
               processes.

       V. 16  6-Apr-2005  Enrico Landi (EL)
               Included extrapolation of ionization and recombination rates
               for temperatures beyond those provided in the .ci and .rec
               files.

       V. 17  10-Jun-2005  Peter Young
               Tidied up code, introduced call to correct_pops for
               ionization/recombination, and added radfunc= and
               sum_mwl_coeffs= keywords

       V. 18  12-Jul-2005, Peter Young
               Improved implementation of RADFUNC keyword

       V. 19  27-Jul-2005, Peter Young
               Corrected bug when the ionrec structure does not exist.

       V. 20  16-Aug-2005, Peter Young
               Routine now catches any NaN values in the level populations
               and prints a warning. All pops are set to zero in this case.

       V. 21  1-Aug-2006, Enrico Landi
               Changed the way recombination is handled for the He-like ions.
               Collision rates are redefined including recombination rates
               (plus cascades) for the levels for which they are available,
               scaled by the ratio of the abundances of the recombining and
               recombined ion.

 VERSION     : 21, 1-Aug-2006 

(See level_population/pop_solver.pro)


SHOW_POPS

[Previous Routine] [List of Routines]

 PROJECT:  CHIANTI

       CHIANTI is an Atomic Database Package for Spectroscopic Diagnostics of
       Astrophysical Plasmas. It is a collaborative project involving the Naval
       Research Laboratory (USA), the University of Florence (Italy), the
       University of Cambridge and the Rutherford Appleton Laboratory (UK). 


 NAME: SHOW_POPS
       
 PURPOSE:

	To display populations of significant levels in a CHIANTI ion 
	model

 CATEGORY:

       Scientific analysis

 EXPLANATION:

	Displays percentage level populations and level IDs for all levels 
	in the specified ion with populations greater than 0.01%. If the 
	temperature is not specified, then it is taken to be where the 
	maximum of the ionisation fraction is.

       If the keyword /ALL is set, the output populations are relative 
       values and not percentages. All levels are shown.

 CALLING SEQUENCE:

	SHOW_POPS, IZ, ION [, POPSTR, DENS= , TEMP= , /NOPROT,
                           RADTEMP= , RPHOT= , /ALL, /DIEL, PATH=,
                           IONEQ_FILE= , ABUND_FILE= ]

 EXAMPLES:

	show_pops,26,13,popstr
	show_pops,26,13,dens=7.5,temp=6.0,rphot=1.2

 INPUTS:

	IZ	The atomic number of the ion

	ION	The spectroscopic number of the ion (e.g., 12 = XII)

 OPTIONAL INPUTS:

	DENS	Logarithm of electron density

	TEMP	Logarithm of electron temperature. If not specified, then
               T_max of the ion is used

	RADTEMP	Specify background radiation temperature (default: 6000 K)

	RPHOT   Distance from the centre of the star in stellar radius units.
               I.e., RPHOT=1 corresponds to the star's surface. (Default is
               infinity, i.e., no photoexcitation.)

	PATH	Directly specify the path where the ion data is contained, 
		e.g., path='/home/other_data/fe_13'

       N_LEVELS  The size of the ion model is automatically determined 
                 from the information in the CHIANTI data files. Setting 
                 this keyword allows the number of levels in the model to 
                 be reduced. E.g., N_LEVELS=14 reduces the model to the 
                 first 14 levels given in the .ELVLC file.

       IONEQ_FILE To include proton rates in the level balance equations 
                  requires the number of density of protons to be known, 
                  and this requires an ion balance file and an abundance 
                  file to be specified, which are done through the 
                  IONEQ_FILE and ABUND_FILE keywords. If they are not set 
                  then the default files specified by !ioneq_file and 
                  !abund_file are used.

       ABUND_FILE See IONEQ_FILE.

       SUM_MWL_COEFFS  An array of coefficients of the same length as 
                       the array of temperatures. Electron and proton rate 
                       coefficients will be calculated at each temperature 
                       and then a weighted sum of the coefficients is 
                       performed using SUM_MWL_COEFFS. This allows 
                       non-Maxwellian energy distributions to be 
                       incorporated into the level balance equations.
                       If this keyword is set for an ion that has ionization
                       and recombination included in the level balance, then
                       these processes will be switched off for the
                       calculation since their rates implicitly assume a
                       single Maxwellian to describe the ion fractions of
                       the neighbouring ions.

       LEVEL   Allows the control of which level populations are displayed
               to the screen. If set to a positive scalar or array, then
               only those levels are printed. If it is set to a negative
               scalar (-n), then all level populations up to level n are
               printed. E.g., LEVEL=20 (only level 20); LEVEL=[5,7,20]
               (levels 5, 7 and 20); LEVEL=-20 (all levels up to level 20).

       RADFUNC         The name of a user-defined function that will generate
                       a radiation spectrum as a function of temperature. 
                       This radiation field will replace the black-body that
                       is assumed when using the RADTEMP keyword in the call
                       to pop_solver.

; OPTIONAL OUTPUTS

       POPSTR  Send level population information to a structure. POPSTR has 
               the tags:
               .dens    Density (cm^-3)
               .temp    Temperature (K). Can be an array if SUM_MWL_COEFFS=
                        is used.
               .radtemp RADTEMP. Set to -1 if RADTEMP not 
                        set.
               .rphot   RPHOT value. Set to -1 if RPHOT not set.
               .proton  String set to 'yes' if proton rates included, 'no' 
                        otherwise
               .version CHIANTI version used to derive populations.
               .date    Date and time at which structure created.
               .level   Structure containing level information. Tags are:
                  .index   CHIANTI level index
                  .term    String containing level identifier.
                  .pop     Population of level
               .sumtst  Set to 1 if the SUM_MWL_COEFFS keyword has been used.
                        Set to 0 otherwise.
               .sum_mwl_coeffs Contains SUM_MWL_COEFFS. Set to -1 if sumtst=0.

 KEYWORDS:

	ALL	Show populations for all levels.
               the output populations are relative 
               values and not percentages.

       NOPROT  If set, then the default setting will be NOT to use 
               proton rates. This can be changed within the routine.

       DIEL    Use the dielectronic recombination files. E.g., for Fe XXII, 
               the routine will read in the fe_22d.* files instead of the 
               fe_22.* files.

 COMMON BLOCKS:

	ELVLC, WGFA, UPSILON, RADIATIVE, PROTON, ELEMENTS

 CALLS:

	ZION2FILENAME, POP_SOLVER, SETUP_ION, READ_IONEQ,
       READ_ABUND, PROTON_DENS, CONCAT_DIR

 HISTORY:

	Ver 1, PRY 22-Sep-97
	Ver.2, PRY 5-Sep-98  - added call to choose_ioneq
	Ver.3, PRY 23-Apr-99 - calls pop_solver now; added DENS keyword
	Ver.4, PRY 18-Dec-99 - added deu to upsilon common block to be 
			consistent with main Chianti routines.
       Ver.5, PRY 7-Aug-00  - added /DIEL keyword to allow populations of 
                       the dielectronic recombination files to be studied.
                       Also changed elvlc common block to match new 
                       version of pop_solver.
       Ver 6, PRY 10-Oct-00 - now calls setup_ion to read ion data
       Ver 7, PRY 12-Nov-01 - modified for proton rates, photoexcitation,
                       and 9 pt splines.
       Ver 8, PRY 9-Dec-01  - completed modifications for v4 of CHIANTI.

       V.  9, 25-May-2002, Giulio Del Zanna (GDZ) 
                   generalized directory concatenation to work for
                   Unix, Windows  and VMS. 
                   Now we only call zion2filename

       V. 10, 9-Aug-2002, Peter Young
                   corrected !ioneq_file problem

       V. 11, 12-Aug-2002, Peter Young
                   added POPSTR output, and tidied up header.

       V. 12, 4-Oct-2003, GDZ
                  modified the input to POP_SOLVER, now it is dealt with an
                  input structure.

       V 13, 4-May-2005, Enrico Landi (EL)
                  Modified in order to include ionization and recombination
                  data in the input to POP_SOLVER

       V.14, 26-May-2005, Peter Young (implemented by GDZ)
                  added SUM_MWL_COEFFS optional input for allowing
                  non-Maxwellian distributions to be considered.

                  added LEVEL= optional input to only print the populations of
                  a few levels.

       V.15, 5-Jul-2005, Peter Young
                  added RADFUNC= and /QUIET keywords

       V.16, 14-Sept-2005 Giulio Del Zanna 
              modified header.

       v.17, 12-Dec-2005, Peter Young
              routine now performs check on existence of .splups file
              instead of .elvlc since with v.5 some ions have a .elvlc
              file but nothing else (fe_3, fe_4)

       v.18, 12-Jun-2009, Enrico Landi
              Changed the definition of the temperature array for ion fractions
              in the IONREC variable, now taken directly from the output of
              READ_IONEQ.PRO

 VERSION     :   18, 12-Jun-2009

(See level_population/show_pops.pro)