VSTAR
Author: Kim Bott 2019, 2020
VSTAR code Authors: J. Bailey, L. Kedziora-Chudczer, S. Chamberlain
This is an introductory primer for new users of the Versatile Software for the Transfer of Atmospheric Radiation. This refers to versions of the code that might be used for vectorized (polarimetric) radiative transfer calculations (to produce a spectrum of emitted, reflected, or transmitted light). Good sources in literature on the development of this software are Bailey & Kedziora-Chudczer 2012 and Bailey, Kedziora-Chudczer & Bott 2018
VSTAR is the Versatile Software for the Transfer of Atmospheric Radiation. It is a line-by-line, plane-parallel radiative transfer solver with multiple scattering.
Information on how to set up VSTAR (including the vital components) can be found on this page.
On this page we provide an example of a simple wrapper script to run the code, and example of an input atmosphere profile, an explanation of the polarized light output, and step through some of the more common user-callable routines (work in progress).
Click here for an example of the wrapper script (.f file) you would use to set up your VSTAR run.
Click here for an example of an input atmospheric profile for MOD_READ.
Modules and subroutines
VSTAR is divided into Modules: MOD, LIN, RAY, PART, and RT. Within each of these modules there are subroutines either called by the user in a top-level wrapper, or called by other subroutines.
The modules are available in readable .f files (e.g. in typical distributions /vstar/source/mod.f or /vstar/source/pol/mod.f). A few of the radiative transfer solutions are typically kept in their own directories such as the polarimetry solution /vstar/source/vvlidort/vvlidort.f and the transmission solution for transiting planets /vstar/source/transmission.f). These other solutions can be added to the wrapper in the same fashion but you’ll need to ensure you use the right libraries and set up your build appropriately.
In general…
MOD subroutines do things like set up the input atmospheric model or set up parameters for the computed radiative transfer model (like the wavelength)
LIN subroutines call in line lists and adjust line shapes
RAY adds Rayleigh scattering
PART subroutines describe particles in the atmosphere such as a cloud
RT subroutines do things like add surface properties, add the light source (star) and produce the radiative transfer solution itself.
The most simple model you could make would contain two MOD subroutines (to read in a model(MOD_ADD/SLAB/BUILTIN/… there are a few options) and set the wavelength grid (MOD_SET_GRID)) and two RT subroutines (to read in a stellar source and to calculate the rt solution). This would give an unphysical result of an atmosphere that does not interact with light.
A note on RT_POLDISK output:
The output from this radiative transfer solver (based on VLIDORT) are files per orbital angle (steps you can set in a “DO” loop in your .f wrapper) with points across the surface of the disk calculated to later be integrated (we use a python program named poldisk.py, email for a copy). The files are arranged into columns as follows (numbered for python here)…
0. Wavelength (um)
1. Wavenumber (cm^-1)
2. IXX ( points across surface in x, should count up near your assigned radius from the call)
3. IYY (points across surface in Y)
4. Flux Factor (the flux incident at the top of the atmosphere for this wavelength)
5. Flux Stokes (still not sure about this one)
6. Stokes I
7. Stokes Q
8. Stokes U
9.Stokes V (will provide a column of zeros if asked to only calculate first 3 stokes in call)
10. XXL2 (negative pixel limit for integration)
11. XXL1 (limit for integration)
12. Relative azimuth
13. AZ (Azimuth?)
14. VZ Angles (zenith angles)
15. Solar zenith angles
User-callable subroutines
These are organize per module (.f file) in the format of:
Name and syntax with the variables you typically set in bold (but note this can vary wildly by use!)
Explanation
User input variables
Notes and tricks
Example
Please note I’m only about half way through this currently…
Subroutines in MOD.f
MOD_SLAB(T,P,H,MR,MM,MID,STATUS)
*+
* Create a vertically homogenous "slab" atmosphere model. This is an atmosphere
* with a single homogenous layer and hence two levels (top and bottom)
* The layer, top level and bottom level properties are all identical.
*
* T (Real) The temperature (K)
* P (Real) The pressure (Pa)
* H (Real) The height of the single layer (km)
* MR (MAX_GAS) (Real) The mixing ratios for each HITRAN gas number
* (zero if not included)
* MM (Real) Mean molecular weight of the atmosphere
* MID (Integer) Returned - a unique identifier for the model
* that identifies it to subsequent routines.
* STATUS (Integer) Status return
Notes:
Example:
MOD_CREATE(NL,PROFILE,MM,G,MID,STATUS)
*+
* Create a model by specifying a profile array
*
* Note that values are specified for levels
*
* NL (Integer) The number of levels in the atmosphere
* PROFILE(MAX_GAS+3,NL) (Real)
* PROFILE(1,NL) is the height of the level (km)
* PROFILE(2,NL) is the pressure of the level (Pa)
* PROFILE(3,NL) is the temperature of the level (K)
* PROFILE(4,NL) - PROFILE(MAX_GAS+3,NL) are the
* mixing ratios for each gas included in the model
* (e.g. PROFILE(4,NL) is the mixing ratio for gas
* 1 (H2O) etc.). Should be set to zero for
* any gas not used in the model.
* MM (Real) Mean molecular weight
* G (Real) Gravitational acceleration (ms-2)
* MID (Integer) Returned - a unique identifier for the model
* that identifies it to subsequent routines.
* STATUS (Integer) Status return
Notes:
Example:
MOD_BUILTIN(NAME,MID,GASES,STATUS)
*+
* Use one of the "built-in" models
*
* Note that values are specified for levels
*
* NAME (Char) The name of the model
* 'TROPIC' - Tropical (50 level)
* 'MLS' - Mid latitude summer (50 level)
* 'MLW' - Mid latitude winter (50 level)
* 'SAS' - Sub arctic summer (50 level)
* 'SAW' - Sub arctic winter (50 level)
* 'MK' - Mauna Kea (46 level)
* 'SSO' - Siding Spring (50 level)
* MID (Integer) Returned - a unique identifier for the model
* that identifies it to subsequent routines.
* GASES (Logical array (1:MAX_GASES) - Array specifying the gases
* included in the model - This can be passed to
* LIN_ADD.
* STATUS (Integer) Status return
Notes: These are typically used for telluric line removal where the atmosphere should be very well constrained and the model must be exact. Variables like water vapor levels can be adjusted with MOD_ADJUST_H2O
Example:
MOD_SET_GRID(MID,W1,W2,WINC,ITYPE,STATUS)
*+
* Set up a fixed spaced wavenumber grid for a model
*
* Arguments
*
* MID (Integer) The model identifier
* W1 (Real) The first (lowest) wavenumber to use
* W2 (Real) The last (highest) wavenumber to use
* WINC (Real) The wavenumber increment at the centre of
* the grid
* ITYPE (Character) Grid spacing uniformity. Possible values are
* WAVENUMBER - Fixed spacing in wavenumber
* WAVELENGTH - Fixed spacing in wavelength
* RESOLUTION - Fixed resolving power
* (Lambda/DLmabda)
* STATUS (Integer) Status return
Notes:
Wavenumber, in my experience, is the least likely option to complain. One can set conversions for W1 and W2 earlier in the code if they tend to think in wavelength.
Example:
MOD_ADJUST_H2O(MID,FACTOR,MAXHT,STATUS)
*+
* Adjust the water vapour content of a model
*
*
* MID (Integer) Model identifier
* FACTOR (Real) Factor to multiply H2O mixing ratios by
* MAXHT (Real) Maximum height to apply correction
* STATUS (Integer) Non zero if an error occurs
Notes: A quick way to adjust the water vapor content multiplicatively.
Example:
MOD_SET_MRATIO(MID,IL,MOL,MR,STATUS)
*+
* Set the mixing ratio for a molecule at a specified layer
*
* MID (Integer) Model identifier
* IL (Integer) The layer to return data for
* MOL (Integer) HITRAN index of molecules
* MR (Real) The mixing ratio of the molecule
* for this layer
* STATUS (Integer) Status return
Notes: Is this ever used as user input?
Example:
MOD_READ(CFILE,MM,G,MID,GASES,STATUS)
*+
* READ
*
* Create a new model by reading the profile data from a text file.
*
* The file format is consistent with that output by MOD_LISTC and is shown by the following
* example:
*
* Z (km) P(Pa) T(K)
* 4
* 1 2 3 4
* 0.1200E+03 0.2270E-02 0.3800E+03 0.2000E-06 0.3500E-04 0.5000E-09 0.1851E-09
* 0.1150E+03 0.3560E-02 0.3168E+03 0.2400E-06 0.4000E-04 0.5000E-08 0.2039E-09
* 0.1100E+03 0.6110E-02 0.2624E+03 0.2800E-06 0.6000E-04 0.5000E-07 0.2260E-09
* .
* .
*
* First line - column headings (ignored on input)
* Second line - Number of HITRAN gases included in model
* Third line - HITRAN gas indices of gases included in the model
* Fourth and subsequent lines - Data for each level in the atmosphere starting with
* the topmost
* First column - level height in km
* Second column - level pressure in Pa
* Third column - level temperature in K
* Fourth and subsequent columns - volume mixing ratios of each gas component as
* listed in the third line.
*
* The lines are read with free format - precise layout is not important.
*
* Arguments
*
* CFILE (Char) Name of file containing profile data
* MM (Real) Mean molecular weight of atmosphere
* G (Real) Gravitational acceleration of atmosphere
* MID (Integer) Returned - a unique idenitifier for the model
* that identified it to subsequent routines
* GASES (Logical array (1:MAX_GASES) - Array specifying the gases
* included in the model - This can be passed to
* LIN_ADD.
* STATUS (Integer) Status return
Notes: Typically for an exoplanet this is the type of model read in you will use.
It is important to ensure that the file is in the right format: that the first three columns are height in km, pressure in pascals, and temperature in kelvin. What is written in the first line does not matter, it will be ignored so I typically label the columns here including the chemical names of the species in the subsequent columns (i.e. H2O in case I can’t remember that it is HITRAN molecule 1). The order of the species (the subsequent columns) do not matter. The height should decrease with each line, the pressure increase (in other words the way a profile looks to someone standing on the ground, top of atmosphere at top of this file, first line).
In this particular read, the mixing ratios are volume mixing ratios, another subroutine is available for mass mixing ratios. If you are given or retrieve an atmospheric profile in number mixing ratios (mole fractions) you will need to convert the units (basically the weighting will change).
Example:
MOD_READ_MUCP(CFILE,MCFILE,MID,GASES,STATUS)
*+
* READ_MUCP
*
* Create a new model by reading the profile data from a text file.
*
* Alternate version of MOD_READ that allows the mean molecular weight to vary through the
* atmosphere, and also reads information on the Cp (Molar specific heat at constant pressure)
* of each layer. The first file read CFILE is in the same format as that for MOD_READ, the second
* file contains the MU and Cp information at each level. Both of these files can be generated by
* running the program "icemod".
*
* The file format is consistent with that output by MOD_LISTC and is shown by the following
* example:
*
* Z (km) P(Pa) T(K)
* 4
* 1 2 3 4
* 0.1200E+03 0.2270E-02 0.3800E+03 0.2000E-06 0.3500E-04 0.5000E-09 0.1851E-09
* 0.1150E+03 0.3560E-02 0.3168E+03 0.2400E-06 0.4000E-04 0.5000E-08 0.2039E-09
* 0.1100E+03 0.6110E-02 0.2624E+03 0.2800E-06 0.6000E-04 0.5000E-07 0.2260E-09
* .
* .
*
* First line - coluumn headings (ignored on input)
* Second line - Number of gases included in model
* Third line - Extended-HITRAN gas indices of gases included in the model
* Fourth and subsequent lines - Data for each level in the atmosphere starting with
* the topmost
* First column - level height in km
* Second column - level pressure in Pa
* Third column - level temperature in K
* Fourth and subsequent columns - volume mixing ratios of each gas component as
* listed in the third line.
*
* The lines are read with free format - precise layout is not important.
*
* Arguments
*
* CFILE (Char) Name of file containing profile data
* MCFILE (Char) Name of file containing mean molecular weight and Cp data
* (3 Columns H km, Mu, Cp (J mol-1 K-1) for same levels as in CFILE.
* MID (Integer) Returned - a unique idenitifier for the model
* that identified it to subsequent routines
* GASES (Logical array (1:MAX_GASES) - Array specifying the gases
* included in the model - This can be passed to
* LIN_ADD.
* STATUS (Integer) Status return
Notes:
Example:
MOD_READM(CFILE,MM,G,MID,GASES,STATUS)
*+
* READM
*
* Create a new model by reading the profile data from a text file.
*
* This is a modified version of MOD_READ that reads a file with
* mass mixing ratios rather than the volume mixing ratios used in
* the standard MOD_READ.
*
* The file format is consistent with that output by MOD_LISTC and is shown by the following
* example:
*
* Z (km) P(Pa) T(K)
* 4
* 1 2 3 4
* 0.1200E+03 0.2270E-02 0.3800E+03 0.2000E-06 0.3500E-04 0.5000E-09 0.1851E-09
* 0.1150E+03 0.3560E-02 0.3168E+03 0.2400E-06 0.4000E-04 0.5000E-08 0.2039E-09
* 0.1100E+03 0.6110E-02 0.2624E+03 0.2800E-06 0.6000E-04 0.5000E-07 0.2260E-09
* .
* .
*
* First line - coluumn headings (ignored on input)
* Second line - Number of HITRAN gases included in model
* Third line - HITRAN gas indices of gases included in the model
* Fourth and subsequent lines - Data for each level in the atmosphere starting with
* the topmost
* First column - level height in km
* Second column - level pressure in Pa
* Third column - level temperature in K
* Fourth and subsequent columns - mass mixing ratios of each gas component as
* listed in the third line.
*
* The lines are read with free format - precise layout is not important.
*
* Arguments
*
* CFILE (Char) Name of file containing profile data
* MM (Real) Mean molecular weight of atmosphere
* G (Real) Gravitational acceleration of atmosphere
* MID (Integer) Returned - a unique idenitifier for the model
* that identified it to subsequent routines
* GASES (Logical array (1:MAX_GASES) - Array specifying the gases
* included in the model - This can be passed to
* LIN_ADD.
* STATUS (Integer) Status return
Notes: This is the version of MOD_READ for mass mixing ratios rather than volume mixing ratios. If you have an atmosphere profile with number mixing ratios you will need to convert it.
Example:
MOD_TROPIC, MOD_MLS, MOD_SAS, MOD_SAW, MOD_MK, MOD_SSO
These are all canned atmospheres for typical earth environments or popular observing sites. The molecules included and PT profile are set. (tropic, mid latitude summer, sub artic summer, sub arctic winter, Mauna Kea, Siding Spring Observatory)
Subroutines in LIN.f
LIN_ZERO(MID,IG,STATUS)
*+
* LIN_ZERO
*
* Zero one of the three optical depth arrays
*
* MID (Integer) Model ID
* IG (Integer) Number of the array to zero (1 = H2O, 2 = CO2, 3 = others)
* STATUS (Integer) Status return
* 0 - Completed OK
Notes:
Example:
LIN_LOG_ON(MID,LFILE,W1,W2,LFORM,STATUS)
*+
* LIN_LOG_ON
*
* Turn on logging of line data to file LFILE. Details of lines added
* to the model by LIN_ADD* routines will be logged to the log file
* if the lines wavenumber is between W1 and W2.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier
* LFILE (Char) Name of log file
* W1 (Real) Lowest wavenumber to log (cm-1)
* W2 (Real) Highest wavenumber to log (cm-1)
* LFORM (Integer) Log file format
* 1 - Summary format
* 2 - HITRAN 2K format
* 3 - HITRAN 04 format
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
LIN_SET_LOWEN(MID,MOL,LOWEN,STATUS)
*+
* LIN_SET_LOWEN
*
* HITRAN lists the lower state energy of a line as -1 if no reliable
* value is considered to be available. By default VSTAR will not use
* such lines as no reliable estimate of line strength can be made at
* temperatures different from the standard value. However such lines
* can be included in a model by specifying a lower state energy here
* to use for these lines. A value can be specified for each molecule
* code.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) HITRAN molecules number
* LOWEN (Real) Lower state energy (cm-1) to be used.
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
SUBROUTINE LIN_SET_FAST(MID,MOL,FCUT,STATUS)
*+
* LIN_SET_FAST
*
* Set FAST mode for a specific molecule. In this mode lines with
* intensity less than FCUT do not have full profiles calculated, but
* instead have all their absorption added into a single spectral bin
* containing the line centre.
*
* The intensity cut off is applied at the actual layer temperature
* being used in each case.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) HITRAN molecules number
* FCUT (Real) Intensity cutoff (cm/mol) to be used.
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
LIN_SET_CUT(MID,MOL,CUT,STATUS)
*+
* LIN_SET_CUT
*
* Set a line profile cutoff for a molecule. If this
* is specified the line wings will be cut off at diatnces
* of CUT cm-1 from the line centre.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) Extended HITRAN molecules number
* CUT (Real) cutoff (cm-1) to be used.
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
SUBROUTINE LIN_SET_BROAD(MID,MOL,MODEL,STATUS)
*+
* LIN_SET_BROAD
*
* Set the line broadening model to use when line data is read using LIN_ADD or
* LIN_ADD_FULL. HITRAN/GEISA files include a value for the air-broadened width,
* a temperature exponent for the air-broadened width, and a self-broadened width.
* The default broadening model is to derive the line width from these parameters.
*
* However this is strictly only valid for broadening in air. VSTAR includes
* alternative broadening models for some cases which may be better suited to
* other planets.
*
* For some formats (e.g. Yurchenko NH3 list) the default broadening is in
* H2/He, not Air.
*
* Models currently implemented are:
*
* H2O broadened in CO2, AIR
*
* NH3 broadened in AIR, H2HE, N2
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) HITRAN molecules number
* MODEL (Character*(*)) Broadening model
* 'DEFAULT' - use the default broadening (either
* air or H2/He depending on line list).
* 'CO2' - use model for broadening in CO2
* 'H2HE' - use model for broadening in H2/He
* 'AIR' - use model for broadening in Air
* 'N2' - use model for broadening in N2
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
LIN_ISO_SCALE(MID,MOL,ISO,SCALE,STATUS)
*+
* LIN_ISO_SCALE
*
* HITRAN assumes standard terrestrial values for isoptope ratios. A
* non-standard isotope ratio can be achieved by using this routine to
* set a scaling factor for a given molecule and isotopologue number
* which will be used to scale the number density used for line strength
* calculations. For example to allow for the 120 times higher D/H ratio
* in Venus compared with Earth the call would be:
*
* CALL LIN_ISO_SCALE(MID,1,4,120.0,STATUS)
*
* Where 1 is the molecule code for water and 4 is the isotopologue number
* for HDO (162).
*
* Note that:
* The routine needs to be called for each isotopologue of each molecule
* affected by a given isotope ratio.
* And:
* The isotopologue is specified by its single digit code used in the HITRAN
* file, (according to the sequence given in Table 6 of Rothman et al., 2005,
* JQSRT, 96, 135), NOT by its multi-digit AFGL notation.
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) HITRAN molecule number
* ISO (Integer) HITRAN isotoplogue number (1-9)
* SCALE (Real) Scale factor to be used.
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
SUBROUTINE LIN_SET_SHAPE(MID,MOL,NS,S,A,B,E,STATUS)
*+
* LIN_SET_SHAPE
*
* Set a non-Lorentzian line wing shape for the lines of a specified molecule.
* The line shape is defined by a model of similar form to that used by
* Meadows and Crisp (1996, JGR, 101, E2, 4595) for the CO2 lines of Venus.
* The line shaped is defined by NS sets of parameters S1, A1, B1, E1; S2, A2
* B2, E2 up to SN etc. The Chi factor that defines the ratio of the line profile
* to a Lorentzian profile is 1 for DN < S1, where DN is the wavenumber distance
* from the line centre:
* Chi = exp[-F1*(DN-S1)] for DN > S1 and DN < S2
* Chi = exp[-F1*(S2-S1) - F2*(DN-S2)] for DN > S2 and DN < S3
* Chi = exp[-F1*(S2-S1) - F2*(S3-S2) - F3*(DN-S3)] for DN > S3 and DN < S4
* etc.
* where FN = AN + BN * exp(-EN * T) for temperature T.
*
* to get a constant Chi factor beyond SN set AN=BN=EN = 0
*
* See equations 5-10 of Meadows and Crisp (1996)
*
* This routine must be called before LIN_ADD.
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) HITRAN molecule number
* NS (Integer) Number of stages in the profile shape description
* S(NS) (Real array) S (Sigma) values for profile shape
* A(NS) (Real array) A (Alpha) values for profile shape
* B(NS) (Real array) B (Beta) values for profile shape
* E(NS) (Real array) E (Epsilon) values for profile shape
* STATUS (Integer) Status value
* 0 - Completed OK
Notes:
Example:
LIN_ADD(MID,DFILE,IFMT,GASES,
: STATUS)
*+
* LIN_ADD
*
* Add gas absorption line data to the model. This subroutine reads
* the absorption line data from a line database file in HITRAN format
* (see Rothman, L.S. et al. Journal of Quantitative Spectroscopy and
* Radiation Transfer, 60, pp665-710 (1998)).
*
* It then sets up arrays containing the dimensionless optical depth for
* each layer of the atmosphere. These are used by other routines
* such as those in the RT package.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory. The file
* used can be the complete HITRAN database file
* or a suitable subset of it for a restricted
* set of gases and wave-numbers.
* IFMT (Integer) File format - 1 = 100 Character HITRAN 2000 or earlier
* 2 = 160 Character HITRAN 2004 format.
* 3 = GESIA 03 format.
* 4 = GEISA 97 format
* 5 = CDSD-1000 (Hitran format with Tref = 1000)
* 6 = CDSD-Venus (Hitran format with Tref = 750)
* 7 = Summary format produced by LIN_LOG_ON/OFF
* 10 = Yurchenkoe et al. NH3 list
* 11 = Harris et al. HCN/HNC list
* 12 = Hargreaves et al. FeH list
*
* 50 = preliminary VTT format
*
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes: This is the most common call to line lists.
Example:
LIN_ADD_FULL(MID,DFILE,IFMT,GASES,
: LCUT,TCUT,ICUT,STATUS)
*+
* LIN_ADD_FULL
*
* LIN_ADD with additional options
*
* Add gas absorption line data to the model. This subroutine reads
* the absorption line data from a line database file in HITRAN format
* (see Rothman, L.S. et al. Journal of Quantitative Spectroscopy and
* Radiation Transfer, 60, pp665-710 (1998)).
*
* It then sets up arrays containing the dimensionless optical depth for
* each layer of the atmosphere. These are used by other routines
* such as those in the RT package.
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory. The file
* used can be the complete HITRAN database file
* or a suitable subset of it for a restricted
* set of gases and wave-numbers.
* IFMT (Integer) File format - 1 = 100 Character HITRAN 2000 or earlier
* 2 = 160 Character HITRAN 2004 format.
* 3 = GESIA 03 format.
* 4 = GEISA 97 format
* 5 = CDSD-1000 (Hitran format with Tref = 1000)
* 6 = CDSD-Venus (Hitran format with Tref = 750)
*
* 50 = preliminary VTT format
*
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* LCUT (Logical) If TRUE apply a line intensity cutoff
* TCUT (Real) Temperature to specify intensity cutoff at
* ICUT (Real) Line intensity cutoff at specified temperature (cm-1/mol cm-2)
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_HYD(MID,DFILE,HYD,GASES,
: STATUS)
*+
* LIN_ADD_HYD
*
* Add gas absorption line data for metal hydrides to the model.
* The data is described in papers as follows:
* FeH Dulick et al. (2003), ApJ, 594, 651
* CrH Burrows et al. (2002), ApJ, 577, 986
* TiH Burrows et al. (2005), ApJ, 624, 988
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory.
* HYD (Character*(*)) Hydride to use 'FeH', 'CrH', 'TiH'
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_PLEZ(MID,DFILE,TIISO,GASES,
: STATUS)
*+
* LIN_ADD_PLEZ
*
* Add gas absorption line data for TiO or VO to the model
* using the TiO line list of Plez, 1998, A&A, 337, 495
* or the VO line list from Plez.
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory.
* TIISO (Integer) The TiO isotopologue (46, 47, 48,49, 50)
* ignored for VO
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_GOOR(MID,DFILE,GASES,
: BROAD,STATUS)
*+
* LIN_ADD_GOOR
*
* Add gas absorption line data for CO to the model
* using the CO line list of Goorvitch, 1994, ApJS, 95, 535
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory.
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* BROAD (Character*(*) Broadening gas 'AIR', 'H2HE', 'CO2'
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_UGA(MID,DFILE,EFILE,MNAME,GASES,
: STATUS)
*+
* LIN_ADD_UGA
*
* Add gas absorption line data for CaH or MgH to the model
* using the line lists from the University of Georgia
* Molecular opacity database.
*
* http://www.physast.uga.edu/ugamop/index.html
*
* A seperate file is needed for the energy levels for the X
* state (the lower state for all listed transitions).
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory.
* EFILE (Character*(*) The name if the energy level file
* MNAME (Vjaracter*(*) The molecule name 'CaH' or 'MgH'
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_BT2(MID,EFILE,DFILE,GASES,BROAD,ECUT,
: LCUT,TCUT,ICUT,STATUS)
*+
* LIN_ADD_BT2
*
* Add H2O absorption line data to the model from the BT2 line list
* (Barber et al., 2006, MNRAS, 368, 1087)
* This is a large computed database containing over 500 million transitions.
* This subroutine reads the energy level file and absorption line data
* and adds it into the optical depth array for each layer.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* EFILE (Character*(*) The name of the BT2 energy level file
* This should be a full path name if the file
* is not in the working directory.
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory. The file can be
* one of the BT2 frequency range files (e.g. 14000-20000-BT2.txt)
* or a number of these files concatenated together if a wider
* frequency range is required.
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* BROAD (Character*(*) Broadening gas ('CO2' or 'AIR')
* ECUT (Real) Maximum lower state energy to include in the model (cm-1). The
* database includes levels up to 30000cm-1, appropriate for
* very high temperatures up to ~4000K. At lower temperatures
* higher energy levels can be omitted.
* LCUT (Logical) If TRUE apply a line intensity cut off
* TCUT (Real) Temperature to specify intensity cutoff at
* ICUT (Real) Line intensity cutoff at specified temperature (cm-1/mol cm-2)
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes: This is a far more detailed line list for water than what is available from HITRAN, this of course means it will take much longer to read in
Example:
LIN_ADD_VTT(MID,EFILE,DFILE,GASES,BROAD,ECUT,
: LCUT,TCUT,ICUT,STATUS)
*+
* LIN_ADD_VTT
*
* Add HDO absorption line data to the model from the VTT line list
* (Voronin et al., 2010, MNRAS, 402, 492)
* This is a large computed database containing over 700 million transitions.
* This subroutine reads the energy level file and absorption line data
* and adds to the optical depth array for each layer
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* EFILE (Character*(*) The name of the VTT energy level file
* This should be a full path name if the file
* is not in the working directory.
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory. The file can be
* one of the VTT frequency range files (e.g. 14000-20000.txt)
* or a number of these files concatenated together if a wider
* frequency range is required.
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* BROAD (Character*(*) Broadening gas ('CO2' or 'AIR')
* ECUT (Real) Maximum lower state energy to include in the model (cm-1). The
* database includes levels up to 25000cm-1, appropriate for
* very high temperatures up to ~3000K. At lower temperatures
* higher energy levels can be omitted.
* LCUT (Logical) If TRUE apply a line intensity cut off
* TCUT (Real) Temperature to specify intensity cutoff at
* ICUT (Real) Line intensity cutoff at specified temperature (cm-1/mol cm-2)
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_EXOMOL_CH4(MID,EFILE,DFILE,GASES,
: LCUT,TCUT,ICUT,STATUS)
*+
* LIN_ADD_EXOMOL_CH4
*
* Add CH4 absorption line data to the model from the Exomol YT10to10
* list
* This is a large computed database containing around 10 billion transitions.
* This subroutine reads the energy level file and absorption line data
* and adds it into the optical depth array for each layer.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* EFILE (Character*(*) The name of the states file
* This should be a full path name if the file
* is not in the working directory.
* DFILE (Character*(*) The name of the transitions file
* This should be a full path name if the file
* is not in the working directory.
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* LCUT (Logical) If TRUE apply a line intensity cut off
* TCUT (Real) Temperature to specify intensity cutoff at
* ICUT (Real) Line intensity cutoff at specified temperature (cm-1/mol cm-2)
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
SUBROUTINE LIN_ADD_EXOMOL_CH4_BIN(MID,EFILE,DFILE,GASES,
: LCUT,TCUT,ICUT,STATUS)
*+
* LIN_ADD_EXOMOL_CH4
*
* Add CH4 absorption line data to the model from the Exomol YT10to10
* list
* This is a large computed database containing around 10 billion transitions.
* This subroutine reads the energy level file and absorption line data
* and adds it into the optical depth array for each layer.
*
* This version reads the binary bersion of the transitions file.
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* EFILE (Character*(*) The name of the states file
* This should be a full path name if the file
* is not in the working directory.
* DFILE (Character*(*) The name of the transitions file
* This should be a full path name if the file
* is not in the working directory.
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* LCUT (Logical) If TRUE apply a line intensity cut off
* TCUT (Real) Temperature to specify intensity cutoff at
* ICUT (Real) Line intensity cutoff at specified temperature (cm-1/mol cm-2)
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_PS(MID,EFILE,DFILE,GASES,BROAD,ECUT,
: LCUT,TCUT,ICUT,STATUS)
*+
* LIN_ADD_PS
*
* Add H2O absorption line data to the model from the Partridge and
* Schwenke line list
* (Partridge and Schwenke, 1997, J. Chem. Phys., 106, 4618)
* This is a large computed database containing transitions of four
* isotopologues of H2O (161, 171, 181, 162). The version used here
* is the list as supplied by Bob Kurucz
* (http://kurucz.harvard.edu/molecules/H2O). The files needed are
* the energy level list (eh2opartridge.asc) and the binary line list
* file (h2oslow.bin). These files contain 65,912,356 lines over the
* wavelength range 408nm to 100 microns.
* This subroutine reads the energy level file and absorption line data
* and add the data into the optical depth array for each layer.
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* EFILE (Character*(*) The name of the PS energy level file
* This should be a full path name if the file
* is not in the working directory.
* (e.g. eh2opartidge.asc)
* DFILE (Character*(*) The name of the line database binary file
* This should be a full path name if the file
* is not in the working directory.
* (e.g. h2oslow.bin)
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS HITRAN gases that are
* to be included in the model, numbered according
* to their HITRAN numbering e.g. 1 = H2O,
* 2 = CO2, 3 = O3 etc.
* BROAD (Character*(*) Broadening gas ('CO2' or 'AIR')
* ECUT (Real) Maximum lower state energy to include in the model (cm-1). The
* database includes levels up to 28000cm-1, appropriate for
* very high temperatures up to ~4000K. At lower temperatures
* higher energy levels can be omitted.
* LCUT (Logical) If TRUE apply a line intensity cut off.
* TCUT (Real) Temperature to specify intensity cutoff at.
* ICUT (Real) Line intensity cutoff at specified temperature (cm-1/mol cm-2)
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN1_ADDLN(MID,MOL,ISO,WAVEN,DINTENS,MOM,EINA,
: AIRWID,SELWID,LOWEN,N,DELTA,CIVP,CIVPP,QP,QPP,W1,W2,
: IE,IR,CFLAG,SWT1,SWT2,TREF,STATUS)
*+
* LIN1_ADDLN
*
* Add the line profiles of a specified line into the accumulated
* absorption data for an atmospheric profile.
*
* The line data are corrected for the temperature and pressure of
* each layer and the absorption profile as a function of wavenumber
* added into the arrays for each layer
*
* The arguments marked "if available" are not needed for the calculations.
* They are only used in log file writing - particularly for writing a
* HITRAN 2004 format output file.
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) Molecule number according to HITRAN numbering
* ISO (Integer) Isotopologue number
* WAVEN (Real) Wavenumber of line (cm^-1)
* INTENS (Double) Line intensity
* MOM (Real) Weighted transition moment squared (if available)
* EINA (Real) Einstein A coefficient (if available)
* AIRWID (Real) Air broadened half width
* SELWID (Real) Self broadened half width
* LOWEN (Real) Lower state energy level
* N (Real) Temperature dependence of half width
* DELTA (Real) Pressure shift (cm^-1/atm)
* CIVP (Char) Upper state local quantum numbers (if available)
* CIVPP (Char) Lower state local quantum numbers (if available)
* QP (Char) Upper state local quantum numbers (if available)
* QPP (Char) Lower state local quantum numbers (if available)
* W1 (Real) First wave-number to use (cm^-1)
* W2 (Real) Last wave-number to use (cm^-1)
* IE (Integer array(6)) HITRAN uncertainty codes (if available)
* IR (Integer array(6)) HITRAN reference indices (if available)
* CFLAG (Char) Line mixing flag (if available)
* SWT1 (Real) Statistical weight upper level (if available)
* SWT2 (Real) Statistical weight lower level (if available)
* STATUS (Integer) Status return
* 0 - Completed OK
Notes:
Example:
LIN_ADD_ATOMIC(MID,DFILE,IFMT,GASES,
: STATUS)
*+
* LIN_ADD_ATOMIC
*
* Add atomic (or ionic) absorption line data to the model. This subroutine reads
* the absorption line data from a line database file in either VALD (Vienna
* Atomic Line Database) or Kurucz format, and adds the data into the optical depth
* array for each atmospheric layer.
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory.
* IFMT (Integer) File format - 1 = VALD (short) format
* 2 = Kurucz format (e.g. gfall.dat)
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS gases included in
* the model where e.g HI is 101, CI is 106,
* NII is 207. i.e. first digit is ionixation state
* second and third digits are atomic number.
* Lines will only be added to the model if the
* corresponding index is set to TRUE.
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN_ADD_ATLIST(MID,DFILE,ATLIST,IFMT,GASES,
: STATUS)
*+
* LIN_ADD_ATLIST
*
* Add atomic (or ionic) absorption line data to the model for ATOMS NOT LISTED
* in the GASES array using a supplementary list of atomic mixing ratios.
* This subroutine reads the absorption line data from a line database file in
* either VALD (Vienna Atomic Line Database) or Kurucz format, and adds the data
* into the optical depth array for each atmospheric layer.
*
*
*
* Input Arguments:
*
* MID (Integer) Model identifier for the model being
* defined
* DFILE (Character*(*) The name of the line database file
* This should be a full path name if the file
* is not in the working directory.
* ATLIST (Character*(*) The supplementary list of mixing ratios for
* atomic and ionic spaces as generated by the
* "icemod" program.
* IFMT (Integer) File format - 1 = VALD (short) format
* 2 = Kurucz format (e.g. gfall.dat)
* GASES(MAX_GAS) (Logical)
* TRUE for each of the MAX_GAS gases included in
* the model where e.g HI is 101, CI is 106,
* NII is 207. i.e. first digit is ionixation state
* second and third digits are atomic number.
* Lines will only be added to the model if the
* corresponding index is set to FALSE.
* STATUS (Integer) Status return
* 0 - Completed OK
* 3 - Failed to open line database file
* 4 - Error reading data file
Notes:
Example:
LIN1_ADDLNA(MID,MOL,WAVEN,LOWEN,LGF,WR,WS,WW,
: W1,W2,STATUS)
*+
* LIN1_ADDLNA
*
* Add the line profiles of a specified line into the accumulated
* absorption data for an atmospheric profile (Atomic line version).
*
* The line data are corrected for the temperature and pressure of
* each layer and the absorption profile as a function of wavenumber
* added into the arrays for each layer
*
*
* Input Arguments:
*
* MID (Integer) Model identifier
* MOL (Integer) Molecule number according to HITRAN numbering
* WAVEN (Real) Wavenumber of line (cm^-1)
* LOWEN (Real) Lower state energy level
* LGF (Real) Log (gf)
* WR (Real) Natural broadening
* WS (Real) Stark broadening
* WW (Real) Van der Waals broadening
* W1 (Real) First wave-number to use (cm^-1)
* W2 (Real) Last wave-number to use (cm^-1)
* STATUS (Integer) Status return
* 0 - Completed OK
Notes:
Example:
Subroutines in PART.f
SUBROUTINE PART_ADD_PCALC(MID,OFILE,NC,CW,CQE,CQS,CG,DTFILE,CDT,WR,PFUNC,PFILE,STATUS)
Adds a scattering particle to the model with precalculated (user set) data. Requires a known extinction coefficient, scattering coefficient, and asymmetry factory (HG) at multiple (3+) wavelengths.
SUBROUTINE PART_ADD_SPHER(MID,RFILE,NDISTR,AA,BB,GAM,AA1,BB1,AA2,BB2,R1,R2,DTFILE,CDT,WR,PFUNC,OUT,OFILE,STATUS)
Adapted from Mishchenko, Travis and Lacis 2002 (http://www.giss.nasa.gov/~crmim/books.html, or contact Kim for copy) this treatment fro scattering particles is widely used by radiative transfer codes.
The RFILE refers to your refractive index file with 1. wavelength in microns, 2. the real ref ind (n) and 3. the imaginary refractive index (k) across relevant wavlengths. If the k values are unknown they can be set to zero however the output will technically not be physical.
The DTFILE is the delta tau (optical depth per layer) file which should have the same number of layers (one less than the levels from the atmosphere file) and for which the CDT value selects the column with the tau values. (These are often a single file for multiple clouds so they may be many columns with different ones called in multiple calls to PART_ADD_SPHERE).
WR refers to the reference wavelength for the optical depth (it is measured at a particular wavelength).
PFUNC is the phase function type either ‘Henyey-Greenstein’ or ‘Moments’. In polarized atmospheric calculations the MOMENTS option must be used to calculate the full moments and thus the polarization introduced by the cloud itself.
OUT is typically set to true, the OFILE can have an arbitrary name.
NDISTR refers to the particle size distribtuion, and the AA, BB, GAM etc values after this may need to be set by the user depending on which of these distributions is used. A very popular distribution is 3, the power law distribution, with AA and BB as the effective radius and effective variance. In some planet scenarios a gamma distrubution (4) may be more appropriate, although it is not typically how a gamma distribution is characterized, it seems that in the Mishchenko code AA and BB are still the effective radius and effective variance (from the book, the example of Hansen and Hovenier’s solution for Venus was a gamma distrubtion with Reff of 1.05 and Veff of 0.07.