TLUSTY grid - IDL programs

TLUSTY grid - IDL programs

About...

The programs described on this page are IDL utilities to provide a useful interface to the library of TLUSTY runs performed on the APS nonLTE PC cluster. Before using these programs you should understand those model grids, and their limitations.

Conditions of use

The programs and model atmosphere results that compose this suite of tools are Copyright Robert Ryans, and the Queen's University of Belfast. Any use of these tools must be by agreement with the author, and subject to suitable recognition in any publication which makes use of them.

Setup

To run the programs you need to set some environment variables so that IDL knows where to find the data and program source codes. Add the lines below to your .login file:

setenv TLABUND_DATADIR /scratch/rsir/nlte/tlabund setenv IDL_PATH /home/rsir/tlusty/tlabund:${IDL_PATH}

tlgui

tlgui is an easy to use interactive GUI tool for accessing the grids of nonLTE line equivalent widths, much in the spirit of the old Xabund tool. It is suitable for interactive analysis of a small number of lines, exploring the datasets, and some debugging of the datasets themselves.

To start the program, type tlgui in an IDL terminal window. A GUI control panel will appear as shown below:

The layout of the panel should be intuitive to people familar with model atmosphere analysis work. In summary:

Select basic atmospheric parameters:
Effective temperature, and logarithmic gravity, is entered in the boxes in section 1. Microturbulent velocity is selected using the slider widget, in the range 0 to 30 kms^-1. Clicking in the slider bar allows the value to be moved in increments of 5 kms^-1.
Select the line, and enter equivalent width:
Select the line you want to analyse using the menus, and enter the line equivalent width in the box. The currently selected line is shown in the box at the bottom of area 2.
Select the model metallicity and type:
LTE (LT) and nonLTE (NL) models are available for each of 4 metallicities (at time of writing many grids are not available. They will be added as time allows!). Metallicites are GAL - Galactic; LMC - Large Magellanic Cloud - -0.3 dex from Galactic; SMC - Small Magellanic Cloud - -0.7 dex from Galactic; MCB - Magellanic Cloud Bridge - -1.1 dex from Galactic.
Click Calculate:
There are 5 buttons in Area 4. Calculate tries to perform the calculation requested. Extrapolate also performs a calculation, but enables the routines to extrapolate outside the boundaries of the models that have been computed. Obviously, this should be used with care. Verbose performs the calculation, showing each step and every data point used along the way. This may be useful when the program warns of some anomalous condition and you need to verify the reliability of the result. Show Grid displays a window (below) showing all the model grid points available for the selected transition. Exit returns you to the IDL prompt.

When you start tlgui, and run a calculation, you will probably see output like this in the terminal window:

IDL> tlgui
    TLSetup complete.
    T=20000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew=150.0 grid=NLGAL
    Linear abund:  6.96  Poly. abund:  6.96

The output summarises the model that has been run, giving model atmosphere paramters, the line selected, equivalent width, and grid. The second line gives two abundance measurements, one linear and one polynomial. The codes use two types of interpolation (or extrapolation) as a sanity check - if these do not agree, there is a serious problem with your calculation, and you'll probably have seen one of the error messages below.

tlcli

tlcli is a command line interactive interface to the model codes, similar in spirit to the LTE spectrum code.

Start the program by typing tlcli - which will produce output like this:

IDL> tlcli
    TLSetup complete.
    Initialising line lists.
    Using terminal input. Type exit to quit.
    Enter element, wavelength, ew. Example: si 4128 55

>>>

From here you can then start to set the model atmosphere parameters, select the metallicity grid and type, and - of course - enter lines to analyse. Commands in tlcli are:

model - sets the model atmosphere paramters of T_eff, log g, and v_t. Either type model, press return, and enter the parameters when prompted, or enter all at once, i.e.
```
>>> model
Enter new Teff, log g, vt: 25000 3.5 10
```
or
```
>>> model 25000 3.5 10
```
grid - select the model atmosphere grid type. Grid types are selected by specifying the appropriate string: nlgal, nllmc, nlsmc, nlmcb, ltgal, ltlmc, ltsmc, ltmcb. As with the model command, you can enter the grid type when prompted, or directly on the command prompt:
```
>>> grid
Enter new grid name: nlgal
```
or
```
>>> grid nlgal
```
verbose and noverbose - turn verbose mode on and off. Once activated with verbose, all calculations will run in verbose mode until the noverbose command is issued.
extrapolate and noextrapolate - turn extrapolation mode on and off, permitting or forbidding extrapolation outside the model grid equivalent width limits. As with verbose mode, extrapolate mode will remain enabled until the noextrapolate command is given.
quit and q - exit tlcli and return to IDL.

Entering lines is done exactly as prompted when the program starts. Enter the ion name (c, n, o, mg, si), wavelength, and equivalent width, then press return. Line wavelength does not have to be exact - the code will search for the nearest line of that species within 1 Å. For safety, the code will print up the exact wavelenth of the line it thinks you requested. It will also warn you if no suitable match could be found.

>>> si 4128 25
    You entered 4128.00, setting line wavelength to 4128.05
    T=25000 log g=3.50 vt=10 Atom: Si II 4128.05 ew= 25.0 grid=NLGAL
    Linear abund:  7.90  Poly. abund:  7.95

>>> si 4200 25
*** No line found within 1.0 angstroms of specified wavelength 4200.00
    The nearest is 4212.00

tlbatch

tlbatch is a batch mode program, which runs a list of lines through a specified model atmosphere. Output can be logged to a file for later analysis.

The format of the input file is quite simple, just one line per line of the file, specified the same way as in tlcli, i.e.

si 4128 55
si 4131 67
mg 4481 250

This is saved to a simple plain text file.

The syntax of the tlbatch command is:
tlbatch, T_eff, log g, v_t, 'gridname', 'input_file'

The name of the model grid is selected from nlgal, nllmc, nlsmc, nlmcb, ltgal, ltlmc, ltsmc, ltmcb, as in tlcli. input_file is the name of the file the linelist is saved to. An example:

IDL> tlbatch, 20000, 4.00, 5, 'nlgal', 'test.lis'
    TLSetup complete.
    Initialising line lists.
    Using input from file: test.lis

    You entered 4128.00, setting line wavelength to 4128.05
    T=20000 log g=4.00 vt= 5 Atom: Si II 4128.05 ew= 55.0 grid=NLGAL
    Linear abund:  7.47  Poly. abund:  7.47

    You entered 4131.00, setting line wavelength to 4130.89
    T=20000 log g=4.00 vt= 5 Atom: Si II 4130.89 ew= 67.0 grid=NLGAL
    Linear abund:  7.44  Poly. abund:  7.44

    You entered 4481.00, setting line wavelength to 4481.00
    T=20000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew=250.0 grid=NLGAL
    Linear abund:  7.57  Poly. abund:  7.57

Note the quoting used for the two final strings on the command line.

Extra command options for tlbatch are:

/extrap - enable extrapolation in equivalent widths
verb - enable verbose mode
log='logfile' - log (most of) the output to a file called logfile

Thereofore a more common calling sequence for the program might be:

IDL> tlbatch, 20000, 4.00, 5, 'nlgal', 'test.lis', /extrap, log='log.txt'

hydfit

To be added.

error messages

The error messages you're most likely to see involve the model you are trying to run lying outside the bounds of the grids that have been calculated. There are two cases - outside the limits of the equivalent widths, or outside the T/g grid.

Equivalent widths
By default the codes will not extrapolate outside the range of equivalent widths that have been calculated. This is to ensure some quality control on the results. If your desired EW lies outside the available range, you'll see a message like this:

*** EW is more than maximum in model. EW=400.0 maxEW=334.9
*** To calculate this value, run with the extrapolate flag set!
    T=20000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew=400.0 grid=NLGAL
*** No abundance returned

*** EW is less than minimum in model. EW= 60.0 minEW= 76.7
*** To calculate this value, run with the extrapolate flag set!
    T=20000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew= 60.0 grid=NLGAL
*** No abundance returned

If you absolutely need the result, you can click the Extrapolate button, which will force the calculation through. In these cases it is vital to check for consistency between the linear and polynomial abundances. You should also check how far away from the grid values you are by comparing your EW to the grid limits displayed by the code when the extrapolate button is pressed. Clearly, the further you go from the models, the riskier.

*** EW is more than maximum in model. Extrapolating. EW=400.0 maxEW=334.9
    T=20000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew=400.0 grid=NLGAL
    Linear abund:  8.42  Poly. abund:  8.40

*** EW is less than minimum in model. Extrapolating. EW= 60.0 minEW= 76.7
    T=20000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew= 60.0 grid=NLGAL
    Linear abund:  6.33  Poly. abund:  6.32

Temperature/gravity limits
Unlike Xabund, which allowed limited extrapolation from the extant T/g points to others outside the grid, this is not supported with the TLUSTY grids. This was done to ensure that anyone operating outside the bounds of the 'safe' models at least had to think about what they were doing. If you encounter this issue you'll see a message like those below. This might be a good time to use the Show grid button.

*** Temperature outside bounds of grid. T, Tmin, Tmax = 36000  13500  35000
*** Bailing out at lower VT - grid bounds exceeded or file not found.
    T=36000 log g=4.00 vt= 5 Atom: Mg II 4481.00 ew=100.0 grid=NLGAL
*** No abundance returned

*** Gravity outside grid limits. g, gmin, gmax =  2.00   2.75   4.50
*** Unable to complete due to log g exceeding grid bounds, or file error
*** Bailing out at lower VT - grid bounds exceeded or file not found.
    T=25000 log g=2.00 vt= 5 Atom: Mg II 4481.00 ew=100.0 grid=NLGAL
*** No abundance returned

File not found
If you get this sort of error message without the EW or grid errors above , it's probably due to a missing model atmosphere file. Contact rsir about this, it may be a simple naming error, or perhaps the calculations you need are not completed.

Features in emission
You're likely to see this error message at the high and low temperature extremes of the grids. Basically, the TLUSTY calculation has gone wrong, and the model spectrum contained an emission line instead of an absorption feature. Where possible such errors have been fixed, if it's still in the dataset then we probably can't do anything - an LTE model may be the only option.

*** Warning - some features in emission!
*** EW is more than maximum in model. EW= 50.0 maxEW=  0.0
*** To calculate this value, run with the extrapolate flag set!
    T=32500 log g=3.25 vt=10 Atom: Si IV 4631.00 ew= 50.0 grid=NLGAL
*** No abundance returned

In the example above no abundance is returned, but this is not always the case. Each model grid point is calculated at 5 abundances, and those 'in emission' are automatically set to zero. If sufficient other points exist to allow the calculation to be performed, a result may be returned. However, it would be prudent in such a case to use the verbose mode to make sure it is a correct return. Clearly, you really do need to know what you're doing in these cases...

Multiple error messages
It's quite possible you will see multiple copies of some of the error messages above, but this is normal - the code is simply noting an error and trying to proceed with the calculation anyway. Consider it a little extra warning that you need to be careful!