;
;Name: TOMOPRAMS
;
; REFERENCES: Morgan, H. and Cook, A. C., ApJ, 893, 57, 2020
;		Morgan, H., ApJS, 242, 3, 2019
;		Morgan, H., ApJS, 219, 23, 2015
;
;Purpose: To create structure containing parameters that the tomography module uses;
; to extrapolate the density datacubes (based on measurements) to other heights.
; To be called by driver routine and resulting structure will be named
; ModPramsStruct (with ModPramsStruct.name='tomo')
;
;
; The tomography method is described by
;         https://iopscience.iop.org/article/10.3847/1538-4357/ab7e32/meta
;         https://iopscience.iop.org/article/10.3847/1538-4365/ab125d/meta
;         https://iopscience.iop.org/article/10.1088/0067-0049/219/2/23/meta
; Please reference these works if you use this module for public work.
;
; The mean tomographical densities within streamers and coronal holes, as functions of height, are fitted to
; to a model velocity/acceleration profile assuming mass flux constant. This allows the extrapolation of
; densities and velocities throughout any coronal region. The velocity profile is given by the simple
; equation
;               v(r) = v_user * ( 1 - exp(-h/r_h) )
; where   v_user is the user-supplied vfast or vslow,
;         h is height ( = r - 1)
;         r_h is a scale height calculated by the tomo module to best fit the tomographical densities.
; Note this velocity allows acceleration up to the maximum v_user, over scale heights of r_H
;
; Based on this velocity profile, the densities at any given height are given by
;               p(r) = (p_f/( 1 - exp(-h/r_h) ) * (r_user/r)^2
; where   r_user is a user-supplied height where the outflow velocity reaches its asymptotic value
;         p_f is the density at r_user, calculated by the tomo module to best fit the tomographical densities.
;
; These equations are fitted separately to the mean streamer densities as given by the tomography maps, and
; the mean coronal hole densities. The final extrapolation then uses the longitude-latitude distribution
; of tomographical densities, plus the streamer/coronal hole height profiles, to calculate densities throughout
; the required coronal region. So, if, in the original tomography map a point has a density which is halfway between
; the maximum streamer and minimum coronal hole densities, it will be a mean of the streamer and coronal hole height profiles.
;
; Note that the module, given a required date, searches the FORWARD database for the tomographical map structure made
; closest in time. If this time is longer than 30 days a warning is given, but the module continues.
;
;Keyword Inputs:
;
;Parameters to control the density extrapolation and velocity calculation.
;
;   TOMOFILE: filename (including extension) of the save file of
;       tomographically determined densities found in $FORWARD_DB/TOMO directory
;       Default will be set to $FORWARD_DB/tomo_20080301_densfix.dat
;
;     NOTE -- TOMOFILE OVERWRITES DATE IF SET AND DIFFERENT
;               BE CAREFUL FOR EXAMPLE IF YOU WANT CMER AND BANGLE TO BE FOR
;               A SOMEWHAT DIFFERENT DATE THAN THE ONE IN THE CUBE - in this
;               case, you should explicitly define CMER, and BANG as keywords
;               In other words -- if you use keyword TOMOFILE, DATE will
;               be completely ignored and actually replaced by date from name of TOMOFILE.
;               Note widget should not send TOMOFILE explicitly, that is,
;               for most calls it will send DATE but not TOMOFILE;
;               unless TOMOFILE as a file is selected via the widget
;               or if READPRAMS is set it will use that TOMOFILE
;               (if there is one; generally, it will not be saved in READPRAMS
;               unless it is an original keyword)
;
;  DATE: if this is set,  it will look for datacube
;       for this date (or close to it) in $FORWARD_DB/TOMO
;       If TOMOFILE set, it will overrule and overwrite DATE.
;
; **TO SUMMARIZE ** there are three different potential observer point of view inputs
;
;       1) CMER/BANG - if these are set as keywords, they take precedence and
;               *define* the observer's point of view
;               These keywords are not defined or used in this subroutine, however.
;
;       2) TOMOFILE - if explicitly set, this will be the datacube used
;               for the TOMO model-- the date associated with its filename is
;               the date the tomography is centered on. This will
;               overwrite/replace DATE even if it is explicitly set, and will define
;               CMER/BANG if they are *not* explicitly set in the function call
;                 (note, if TOMOFILE is changed in the widget, CMER/BANG will be updated)
;
;       3) DATE - if this is the only thing set, it will define CMER/BANG
;               as the Earth's view on that date;
;               also TOMOFILE as described above.
;                 (note, if DATE is changed in the widget, CMER/BANG and TOMOFILE
;                    will be updated)
;
; *So, for example, one might want to know what STEREO saw on a particular day and time:
;       one would set DATE to that day and time, CMER and BANG to STEREO's view for that day and
;       time, and then TOMOFILE would be a close-by time (but not exactly the same as DATE)
;       that represented the time of the boundary condition.
;       The DATE itself would not have a huge impact on the result, except to the extent that
;       some issues of instrument calibration have a dependency on DATE, and of course in
;       picking the TOMOFILE to use.
;
;       The FORWARD plot will indicate all three of these points of view in the plot title,
;       via  "TOMO Cube" (the tomographic reconstruction date associated with TOMOFILE),
;       "observer's date" (DATE), and then explicit CMER + BANG
;
;
;   VFAST: asymptotic speed of the fast solar wind in km/s. Default 700 km/s
;
;   VSLOW: asymptotic speed of the slow solar wind in km/s. Default 300 km/s
;
;   HT_ASYMPT_FAST: the distance at which the fast solar wind reaches its
;                   maximum speed of VFAST. Default 1.5 solar radii (heliocentric)
;
;   HT_ASYMPT_SLOW: the height at which the slow solar wind reaches its
;                   maximum speed of VSLOW. Default 20 solar radii (heliocentric)
;
;   SIMPLE: if set, just has density fall off with power rpwr
;                  DEFAULT 0 (unset)
;
;   RPWR: only used if SIMPLE is set, and then controls density falloff
;                  if simple set DEFAULT -2 (falls off as 1/r^2)
;                     otherwise set to 'NULL'
;
;   TE
;              isothermal temperature parameter value
;                       DEFAULT 1.5D6
;
;
;   The above defaults are educated guesses. See https://iopscience.iop.org/article/10.3847/1538-4357/ab7e32/meta
;

