xstardb_help.txt

%--------------------------------------------------------------------
% This file is part of XSTARDB
% Copyright (C) 2014 Massachusetts Institute of Technology
%
% This software was developed by the MIT Kavli Institute for
% Astrophysics and Space Research under NASA grant NNX10AD41G.
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either < version number > of the
% License, or (at your option) any later version.
%
% This program is distributed in the hope that it will be useful, but
% WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
% General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA
%--------------------------------------------------------------------------

rd_xstar_output

 SYNOPSIS
   Reads the output fits table from an XSTAR model

 USAGE
   db = rd_xstar_output( filename )

 DESCRIPTION
   Returns a structure, containing fields sorted by ascending wavelength
     transition  : (int) an index for the transition
     type        : (string) "line" or "edge/rrc"
     ion         : (string) describing ion, e.g. "si_iv"
     wavelength  : (double) transition wavelength in Angs
     tau0        : (float) optical depth of the transition (??)
     tau0grid    : (float) optical depth of the transition (??)
     ew          : (float) equivalent width of a line transition,
    		   has a negative value in the case of emission
     luminosity  : (float) luminosity of a line transition
     lower_level : (string) lower level of transition
     upper_level : (string) upper level of transition
     a_ij        : (float) A_ij rate coefficient
     f_ij        : (float) f_ij rate coefficient
     g_lo        : (float) g value for lower level of transition
     g_up        : (float) g value for upper level of transition
     ind_lo      : (int) index for transition lower level,  
     ind_up      : (int) index for transition upper level,
     ind_ion     : (int) index for ion

   fields added to the basic output:
     model_name  : (string) "warmabs" or "photemis", etc...
     Z           : (int) atomic number; e.g., Ne = 10
     q           : (int) ion state (arabic; e.g., 9 for IX)
     params      : sub-structure holding model parameters
     transition_name : (string) description of other fields 
                       "<Element> <ion> <upper_level> <lower_level> <type>"
     filename        : (string) name of file(s) the database was read from

   merged databases only (see xstar_merge)
     origin_file     : (int) index of db.filename from which transition was read

 SEE ALSO
   xstar_merge, xstar_load_tables

------------------------------------------------------------------------

xstar_wl

 SYNOPSIS
   Search for transitions within a specified wavelength range.

 USAGE
   bool_array = xstar_wl( db, wlo, whi[; redshift] )

 DESCRIPTION
   Returns boolean array of characters for transitions in db matching
  
         wlo < db.wavelength*(1+redshift) <= whi
  
   where wavelength is in units of angstroms.

   Qualifiers:
     redshift = 0.0 by default

 SEE ALSO
   xstar_el_ion, xstar_trans, xstar_strong

------------------------------------------------------------------------

xstar_el_ion

 SYNOPSIS
  Search for transitions from a particular element and ion.

 USAGE
  bool_array = xstar_el_ion( db, el_list[, ion_list] )

 DESCRIPTION
  Returns boolean array of characters for transitions in db matching

	ismember( db.Z, el_list ) and
	ismember( db.q, ion_list )

  where Z is an array of integers specifying atomic number (e.g. 6 for oxygen)
  and q is an array of integers specifying charge (e.g. 1 for neutral)

  Examples:
    o_all = where( xstar_el_ion( db, 8 ) );
    o_vii = where( xstar_el_ion( db, 8, 7 ) );

 SEE ALSO
  xstar_wl, xstar_trans, xstar_strong

------------------------------------------------------------------------

xstar_trans

 SYNOPSIS
  Search for transitions by lower and upper energy level index.

 USAGE
  bool_array = xstar_trans( db, el_list, ion_list[, lower_list[, upper_list]] )

 DESCRIPTION
  Returns boolean array of characters for transitions in db matching
  
        xstar_el_ion( db, el_list, ion_list ) and
	ismember( db.ind_lo, lower_list ) and
	ismember( db.ind_up, upper_list )

  Examples:
    o_vii_triplet = where( xstar_trans( db, 8, 7, 1, [2:7] ) );

 SEE ALSO
  xstar_wl, xstar_el_ion, xstar_strong

------------------------------------------------------------------------

xstar_strong

 SYNOPSIS
  Search for strong transitions.

 USAGE
  indices = xstar_strong( n, db [; type, wmin, wmax, elem, ion, redshift] )

 DESCRIPTION
  Returns the indices in db structure for the n strongest features.
  Depending on the feature type, "strongest" is defined by the most
  luminous (e.g. photemis models) or the largest equivalent width
  (e.g. warmabs models).

  The search may be modified by several qualifiers.  Defaults are
  determined from by model type.

  Qualifiers:

    field  : arbitrary field name of the input structure field
     	     defining the feature for the selection of the strongest
     	     elements. The user can override this.
	     
	     = "ew" (equivalent width) if model_type == T_HOTABS or T_WARMABS
	     = "luminosity" (line luminosity) if model_type == T_HOTEMIS or T_PHOTEMIS

	     If model_type is not found, field="ew" is the default setting

	     Values also change according to type qualifier:
	     = "luminosity" if type == "rrc"
	     = "tau0" if type == "edge"

	     If field is set by user, it will override all conditionals above

     type  : "line" | "edge" | "rrc" | "any"
	    
	     "any" will match all types with default field as described above.
	     "edge" and "rrc" will change the field parameter

     wmin  : minimum wavelength [A] for selection.

     wmax  : maximum wavelength [A] for selection

     elem  : Element atomic number (integer); output will be limited to this element.

     ion   : Ion state (integer); output will be limited to this ion.

     limit : Lower limit for the field of interest. Only transitions
     	     with db.field >= limit will be returned.

     redshift : Will adjust search to wmin < db.wavelength * (1+redshift) <= wmax

  Examples:

    fit_fun( "warmabs2(1)" );
    set_par( "warmabs2(1).rlogxi", 1 );
    set_par( "warmabs2(1).write_outfile", 1 );
    (w1, w2) = linear_grid( 1.0, 40.0, 8192 );
    y = eval_fun( w1, w2 );

    db = rd_xstar_output( "warmabs_1.fits" ) ;
    l = xstar_strong( 10, db; elem=O, wmin=10, wmax=20, type="edge" ) ; 

    xstar_page_group( db, l );
    #     id       ion   lambda    A[s^-1]          f  gl  gu      tau_0       W(A) L[10^38 cgs]       type                    label
        3543   O  VIII  14.2281  0.000e+00  0.000e+00   2   0  2.317e-01  0.000e+00    0.000e+00   edge/rrc   1s1.2S_1/2 -     continuu
        3363   O   VII  16.7705  0.000e+00  0.000e+00   1   0  1.261e+00  0.000e+00    0.000e+00   edge/rrc     1s2.1S_0 -    continuum

 SEE ALSO
  xstar_wl, xstar_el_ion, xstar_trans

------------------------------------------------------------------------

xstar_page_group

 SYNOPSIS
  Prints a table of transition information

 USAGE
  xstar_page_group( db, l[; sort, redshift, file] )

 DESCRIPTION
  Prints a table of features in db, selected by array index list l

  Qualifiers:
    sort : "wavelength" | "tau0" | "none" | field name

	   Will sort the list in descending order based on the field
	   name value in these fields, except in a few special cases:
    	   = "wavelength" by default, sorts in ascending order
	   = "none" will print the data in the same order as l
	   = "tau0" sorts according to tau0grid field in db

    redshift : Will print the observer-frame wavelengths in the table.
               In the case of a merged database, the user should
               supply an array containing the redshift for each origin
               file, in the same order as db.filename
	       (see xstar_merge and rd_xstar_output)

    file     : (string) Save the output to a text file

 SEE ALSO
  xstar_page_grid, xstar_plot_group

------------------------------------------------------------------------

xstar_plot_group

 SYNOPSIS
  Marks line features in the current plot

 QUALIFIERS
  xstar_plot_group( db, l[, color[, style[, redshift]]] )

 DESCRIPTION
  Marks features from db selected by index list l

  Qualifiers:
    color    : optional integer specifying label color
   	       default = 2

    style    : optional structure giving labeling attributes 
   	       default = line_label_default_style()

    redshift : redshift for marker placement
   	       default = 0

 SEE ALSO
  xstar_page_group, xstar_page_grid

------------------------------------------------------------------------

xstar_merge

 SYNOPSIS
  Loads an XSTAR db structure from two or more files

 USAGE
  db = xstar_merge( file_list )

 DESCRIPTION
  Merges two or more databases from an array of file names.
  
  The resulting database structure includes an additional field
    origin_file : (int) index of db.filename from which transition was read
  
  See rd_xstar_output for full list of structure fields.

 SEE ALSO
  rd_xstar_output, xstar_load_table

------------------------------------------------------------------------

xstar_run_model_grid

 SYNOPSIS
  Runs a series of XSTAR models from ISIS

 USAGE
  xstar_run_model_grid( model_info, root_dir[; nstart] )

 DESCRIPTION
  Runs a series of XSTAR models specified by the model_info structure.
  All output is stored in the location specified by root_dir.

  model_info is a structure containing the following fields
    mname   : model name, e.g., "warmabs" or "photemis"
    pname   : parameter of interest to vary, e.g., "column"
    min	    : minimal value for parameter of interest
    max	    : maximal value for parameter of interest
    step    : step-size for parameter of interest
    bins    : a sub-structure containing
      bin_lo
      bin_hi

  Two global variables are provided to help initialize model_info
    _default_model_info : initializes structure with the above fields
    _default_binning    : (bin_lo, bin_hi) = linear_grid(1.0, 40.0, 8192);

 SEE ALSO
  xstar_load_tables, xstar_page_grid

------------------------------------------------------------------------

xstar_load_tables

 SYNOPSIS
  Loads a grid of XSTAR db models from a list of files.

 USAGE
  g = xstar_load_tables( fnames )

 DESCRIPTION
  Loads a series of xstar models, defined by sorted array of strings
  containing the database file names (fnames).

  Output is a grid structure containing the following fields
   db        : An array of database structures loaded from each file
   	       (See results of rd_xstar_output)

      Each structure in db contains an additional field
      uid     : (long int) the "unique id" assigned to each transition
                according to ion index, ind_lo, and ind_hi;
                see xstarlevels.text on XSTAR website

   mdb : The "master database" sub-structure containing the union 
   	 of all transitions in db array. It contains:
      type        : (string) "line" or "edge/rrc"
      ion	    	: (string) describing ion, e.g. "si_iv"
      wavelength  : (double) transition wavelength in Angs
      lower_level : (string) lower level of transition
      upper_level : (string) upper level of transition
      Z           : (int) atomic number; e.g., Ne = 10
      q	          : (int) ion state (arabic; e.g., 9 for IX)
      a_ij        : (float) A_ij rate coefficient
      f_ij        : (float) f_ij rate coefficient
      g_lo        : (float) g value for lower level of transition
      g_up        : (float) g value for upper level of transition
      ind_lo      : (int) index for transition lower level, 
		    see xstarlevels.text on XSTAR manual
      ind_up      : (int) index for transition upper level,
		    see xstarlevels.text on XSTAR website
      ind_ion     : (int) index for ion
      transition_name : (string) description of other fields 
		        "<Element> <ion> <upper_level> <lower_level> <type>"

   uids      : (long int) Union of all uid values in db array
   uid_flags : An array of character arrays containing boolean information.
   	       length(g.uid_flags)    = length(g.db)
   	       length(g.uid_flags[i]) = length(g.uids)
               g.uid_flags[i][j] = '1' if g.uids[j] is in g.db[i]

 SEE ALSO
  rd_xstar_output, xstar_run_model_grid, xstar_page_grid

------------------------------------------------------------------------

xstar_get_grid_par

 SYNOPSIS
  Returns the array for parameter of interest over an XSTAR grid

 USAGE
  par_values = xstar_get_grid_par( g, param )

 DESCRIPTION
  Returns an array containing the parameter of interest from the grid
  of XSTAR models.

  Input:
    g     : grid structure from xstar_load_tables
    param : (string) name of interesting parameter from the XSTAR
            model, e.g. "rlogxi"

 SEE ALSO
  xstar_run_model_grid, xstar_load_tables, xstar_line_prop

------------------------------------------------------------------------

xstar_page_grid

 SYNOPSIS
  Prints a table of transitions from a XSTAR model grid

 USAGE
  xstar_page_grid( g, l[; sort, file] )

 DESCRIPTION
  Print a table of transitions in g (a grid structure from xstar_load_tables) 
  selected by a list if index values, l

  Qualifiers:
    sort : "wavelength" | "none" | "uid" | field name

	   Will sort the list in descending order based on the field
	   name value in these fields, except in a few special cases:
    	   = "wavelength" by default, sorts in ascending order
	   = "none" will print the data in the same order as l
	   = "uid" will print the data in order of ascending uid,
	     this is the equivalent of ascending ion species

   file : (string) Save the output to a text file

 SEE ALSO
  xstar_run_model_grid, xstar_load_tables

------------------------------------------------------------------------

xstar_unpack_uid

 SYNOPSIS
  Returns values for ind_ion, ind_lo, and ind_up from unique id value

 USAGE
  (ion, lo, up) = xstar_unpack_uid( uid )

 DESCRIPTION
  Returns the values for ion (ind_ion), lower level (ind_lo),
  and upper level (ind_up) associated with a unique id (Llong)
  - see xstarlevels.text from XSTAR db

 SEE ALSO
  xstar_load_tables, xstar_page_id

------------------------------------------------------------------------

xstar_page_id

 SYNOPSIS
  Prints a table containing the transition name, ion index value,
  lower level index, and upper level index for a list of transitions

 USAGE
  xstar_page_id( db, l[; file] )

 DESCRIPTION
  Prints a table, sorted by wavelength, showing the index values for ion (ind_ion), lower level (ind_lo),
  and upper level (ind_up) associated with a list of transitions
  - see xstarlevels.text from XSTAR db

 SEE ALSO
  xstar_unpack_uid, rd_xstar_output

------------------------------------------------------------------------

xstar_line_prop

 SYNOPSIS
  Returns field values for a transition of interest over a grid of XSTAR models.

 USAGE
  line_ew = xstar_line_prop( g, l, field )

 DESCRIPTION
  Returns an array containing the values of "field" for the transition
  of interest over a grid of XSTAR models.

  Inputs:
    g     : grid structure containing all model databases (see xstar_load_tables)
    l     : (int) index for the transition in the master database (g.mdb)
    field : (string) name the database field of interest, e.g. "ew"

  Example:

    fgrid = glob("warmabs_*.fits");
    fgrid = fgrid[ array_sort(fgrid) ];
    wa_grid = xstar_load_tables(fgrid);

    line_ew = xstar_line_prop( wa_grid, 980040015LL, "ew" );

 SEE ALSO
  xstar_run_model_grid, xstar_load_tables, xstar_get_grid_par

------------------------------------------------------------------------

xstar_line_ratios

 SYNOPSIS
  Returns line ratios from a grid of XSTAR models

 USAGE
  lr = xstar_line_ratios( grid, l1, l2, field )

 DESCRIPTION
  Returns an array containing the ratio l2 to l1 for the field of
  interest, over grid of XSTAR models.

  Inputs:
    g     : grid structure containing all model databases (see xstar_load_tables)
    l1    : (int) index for the transition from master database (g.mdb),
            may be an array of integers to account for blended lines
    l2    : same as above
    field : (string) name of the database field of interest, e.g. "ew"

  Example:

    o_vii_R = where( xstar_trans(g.mdb, O, 7, 1, 7) );
    o_vii_I = where( xstar_trans(g.mdb, O, 7, 1, [3:5]) );
    ratio_IR = xstar_line_ratios( g, o_vii_R, o_vii_I, "ew" );

 SEE ALSO
  xstar_run_model_grid, xstar_load_tables, xstar_get_grid_par, xstar_line_prop 

------------------------------------------------------------------------