This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Jun 7 13:17:36 2017.
Function: file_extract_time_from_name Generic function that will extract the time from a file name that has YYYYMMDD_hhmmss as part of the name
(See projects/maven/general/file_extract_time_from_name.pro)
PROCEDURE: mvn_altitude
PURPOSE:
Determines the altitude of MAVEN. Altitude is defined as the distance
from a point (e.g., MAVEN) to a reference surface along a line normal
to the reference surface. The reference surface is sometimes called the
"datum". This routine recognizes four definitions of altitude:
aerocentric: The datum is a sphere with Mars' volumetric mean radius
of 3389.50 km.
aerodetic: The datum is the IAU Mars ellipsoid:
R_equator = 3396.19 km ; R_pole = 3376.20 km
aeroid: The datum is the Mars aeroid, which is a gravitational
equipotential ("sea level"). This surface is irregular
but within ~2 km of the IAU Mars ellipsoid.
topographic: The datum is the solid surface, based on laser altimeter
data (MGS-MOLA).
Areocentric and areodetic longitudes are identical, while the latitudes
differ by less than 0.3 deg. The altitudes can differ by more than 10 km,
(about an atmospheric scale height), so this is the main reason for
choosing the ellipsoid (or the areoid) for the region around periapsis.
The areoid and solid surface are irregular, so areocentric longitude and
latitude are used for those reference surfaces. This is consistent with
usage in the literature.
The results are stored in TPLOT variables.
You must have SPICE installed for this routine to work.
USAGE:
mvn_altitude, trange
INPUTS:
trange: Optional. Time range for calculating altitude. If not
specified, then use the current range set by timespan.
KEYWORDS:
DT: Time resolution (sec). Default is to use the time resolution
of maven_orbit_tplot (usually 10 sec).
CART: A 3 x N array of cartesian coordinates in the IAU_MARS frame.
If specified, then trange and DT are ignored and the result
is returned via keyword RESULT. If not specified, then try
to get this information from maven_orbit_tplot, and the result
is stored in tplot variables as well as in RESULT.
DATUM: String for specifying the datum. Can be one of "sphere",
"ellipsoid", "areoid", or "surface". Default = 'sphere'.
Minimum matching is used for this keyword.
LATLON: Create tplot variables for latitude and longitude. If
DATUM = 'ellipsoid', then you get areodetic latitude and
longitude.
RESULT: Returns a structure containing the altitude, latitude and
longitude. If CART is set, then each of these will have N
values. If CART is not set, then the structure will be
compatible with tplot (x = time, y = altitude).
PANS: Named variable to hold the tplot variables created. Variable
names are in the form: mvn_<par>_<dat>, where <par> is the
parameter (alt, lon, lat) and <dat> is a three-letter code
for the datum (sph, ell, are, sur).
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-06-02 18:41:15 -0700 (Fri, 02 Jun 2017) $
$LastChangedRevision: 23399 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_altitude.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_altitude.pro)
NAME:
mvn_file_source( [default_source] )
PURPOSE:
Returns a structure that contains all the information (or options) needed to download and return MAVEN data file names.
The structure is stored in a common block variable and has persistance.
This funtion is used primarily by the routine mvn_pfp_file_source(). However users might wish to change the default values.
see "file_retrieve" for specific information on how to use the options in this structure.
Typical Usage:
source=mvn_file_source() ; get the options
printdat, source ; display the options
Examples:
#1a:
tempsource = mvn_file_source(verbose=4,local_data_dir='tempdir/') ; temporarily change VERBOSE and LOCAL_DATA_DIR
files = mvn_pfp_file_retrieve(source=tempsource)
INPUT:
default_source (optional) if this is a structure then it will be returned as the output
KEYWORDS:
SET = [0,1] : If set, then new options (KEYWORDS or DEFAULT_SOURCE) are made to the common block variable are therefor persistant.
DO NOT USE THIS KEYWORD INSIDE publically distributed code - IT WILL PRODUCE SIDE EFFECTS FOR OTHERS! !
RESET = [0,1] : If set then the default is restored.
DO NOT USE THIS KEYWORD INSIDE publically distributed code - IT WILL PRODUCE SIDE EFFECTS FOR OTHERS! !
EXAMPLE 1:
printdat, mvn_file_source(/set, USER_PASS='user:password') ; Add the user and password to enable authentication on the remote server.
#1b
help,/structure, mvn_file_source(verbose=3,/set) ; Permanentaly change the verbose level for all subsequent calls
files = mvn_pfp_file_retrieve()
#1c
help,/structure, mvn_file_source(no_server=1,/set) ; Permanently disable searching on the remote server
#2
help,/structure, mvn_file_source(/reset) ; reset structure to the default.
OUTPUT:
Structure:
see "FILE_RETRIEVE" for a description of each structure element.
$LastChangedBy: davin-mac $
$LastChangedDate: 2015-11-06 14:01:30 -0800 (Fri, 06 Nov 2015) $
$LastChangedRevision: 19295 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_file_source.pro $
(See projects/maven/general/mvn_file_source.pro)
FUNCTION: mvn_frame_name
PURPOSE:
Expands a MAVEN frame name fragment to the full frame name
recognized by SPICE. You can omit the leading 'MAVEN_' or
'IAU_' from the fragment. Case folded minimum matching is
performed. For example, all of the following are expanded
to 'MAVEN_STATIC': 'maVEn_st', 'sta', 'St'.
Simply returns the input if the fragment is not recognized
or ambiguous.
USAGE:
spice_frame = mvn_frame_name(frame)
INPUTS:
frame: Sring scalar or array of MAVEN frame name fragments.
KEYWORDS:
SUCCESS: An array of integers with the same number of elements
as frame:
0 = match not found or ambiguous
1 = unique match found
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-06-06 18:52:17 -0700 (Tue, 06 Jun 2017) $
$LastChangedRevision: 23430 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_frame_name.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_frame_name.pro)
FUNCTION: mvn_get_altitude
PURPOSE:
Calculates the altitude of the MAVEN spacecraft above the Martian
surface (either the solid planet or the constant-pressure surface
known as the 'areoid'). This routine is called by the more general
mvn_altitude, which has other possible definitions for altitude.
USAGE:
mav_get_altitude, elon_sc, lat_sc,r_sc, alt_sc
INPUTS:
xpc: a 1-dimensional array of values of the east longitude
of the spacecraft. UNITS: km
ypc: a 1-dimensional array of values of the latitude
of the spacecraft. UNITS: km
zpc: a 1-dimensional array of values of the radial
distance of the spacecraft from the planet's center
of mass. UNITS: kilometers
OUTPUT:
The output array of spacecraft altitudes.
UNITS: kilometers
KEYWORDS:
TOPOGRAPHIC: Set this keyword to anything nonzero if the spacecraft
altitude above the planet's topography is
desired. If this keyword is not specified, the
altitude will be above the constant-pressure
surface known as the areoid (the equivalent of
sea level) and the relevant altitude for most
MAVEN studies.
MOLA_STRUC: Depreciated. Structure now stored in a common block.
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-05-29 15:49:17 -0700 (Mon, 29 May 2017) $
$LastChangedRevision: 23361 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_get_altitude.pro $
CREATED BY: Robert J. Lillis 2013-01-22
(See projects/maven/general/mvn_get_altitude.pro)
PROCEDURE: mvn_nadir
PURPOSE:
Determines the direction of nadir at the position of the spacecraft in
one or more coordinate frames. The results are stored in TPLOT variables.
You must have SPICE installed for this routine to work. If SPICE is
already initialized (e.g., mvn_swe_spice_init), this routine will use the
current loadlist. Otherwise, this routine will try to initialize SPICE
based on the current timespan.
USAGE:
mvn_nadir, trange
INPUTS:
trange: Optional. Time range for calculating the nadir direction.
If not specified, then use current range set by timespan.
KEYWORDS:
DT: Time resolution (sec). Default is to use the time resolution
of maven_orbit_tplot (usually 10 sec).
FRAME: String or string array for specifying one or more frames
to transform the nadir direction into. Any frame recognized
by SPICE is allowed. The default is 'MAVEN_SPACECRAFT'.
Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
POLAR: If set, convert the direction to polar coordinates and
store as additional tplot variables.
Phi = atan(y,x)*!radeg ; [ 0, 360]
The = asin(z)*!radeg ; [-90, +90]
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'Nadir_MAVEN_SPACECRAFT'.
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-03-28 14:02:00 -0700 (Tue, 28 Mar 2017) $
$LastChangedRevision: 23058 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_nadir.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_nadir.pro)
NAME: MVN_ORBIT_NUM
function: mvn_orbit_num()
PURPOSE:
returns database structure that contains orbit information about each MAVEN orbit.
Alternatively - Returns the time if given the orbit number or returns the orbit number if given the time.
Typical CALLING SEQUENCE:
orbdata = mvn_orbit_num()
store_data,'orbnum',orbdata.peri_time,orbdata.num,dlimit={ytitle:'Orbit'}
tplot,var_label='orbnum'
TYPICAL USAGE:
print, mvn_orbit_num(time=systime(1) ) ; prints current MAVEN orbit number
print , time_string( mvn_orbit_num(orbnum = 6.0) ; prints the time of periapsis of orbit number 6
timebar, mvn_orbit_num( orbnum = indgen(300) ) ; plots a vertical line at periapsis for the first 300 orbits
Author: Davin Larson - October, 2014
$LastChangedBy: jimm $
$LastChangedDate: 2017-02-02 15:24:16 -0800 (Thu, 02 Feb 2017) $
$LastChangedRevision: 22720 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_orbit_num.pro $
(See projects/maven/general/mvn_orbit_num.pro)
FUNCTION mvn_pfp_file_next_revision(filename,ndigits, [extension=extension]) Returns the filename with the next revision number Warning: unpredictable results at rollover.
(See projects/maven/general/mvn_pfp_file_next_revision.pro)
Function: files = mvn_pfp_file_retrieve(PATHNAME)
Purpose: Retrieve or Download MAVEN data files (i.e. L0 files) (Can be used to generate filenames too)
INPUT:
PATHNAME: string specifying relative path to files. Default might change- Currently: 'maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat'
PATHNAME must be relative to the LOCAL_DATA_DIR and REMOTE_DATA_DIR fields of the source keyword.
"globbed" filenames (*,?) are accepted.
typical usage:
files = mvn_pfp_file_retrieve('maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat',/daily_names) ; get L0 files for user defined time span
files = mvn_pfp_file_retrieve(pathname,/daily_names,trange=trange) ; set time range
Keywords: (All are optional - none are recommended)
L0: set to 1 to return PFP L0 files
DAILY_NAMES : resolution (in days) for generating file names.
YYYY, yy, MM, DD, hh, mm, ss, .f, DOY, DOW, TDIFF are special characters that will be substituted with the appropriate date/time field
Be especially careful of extensions that begin with '.f' since these will be translated into a fractional second.
See "time_string" TFORMAT keyword for more info.
TRANGE : two element vector containing start and end times (UNIX_TIME or UT string). if not present then timerange() is called to obtain the limits.
SOURCE: alternate file source. Default is whatever is return by the function: mvn_file_source() (see "mvn_file_source" for more info)
FILES: if provided these will be passed through as output.
VALID_ONLY: Set to 1 to prevent non existent files from being returned.
CREATE_DIR: Generates a filename and creates the directories needed to create the file without errors. Will not check for file on remote server.
KEYWORDS Passed on to "FILE_RETRIEVE":
LAST_VERSION : [0,1] if set then only the last matching file is returned. (Default is defined by source)
VALID_ONLY: [0,1] If set then only existing files are returned. (Default is defined by source keyword)
VERBOSE: set verbosity level (2 is typical)
USER_PASS: user:password combination for the remote server
LIMITATIONS:
Beware of file pathnames that include the character sequences: YY, MM, DD, hh, mm, ss, .f since these can be retranslated to the time
(See projects/maven/general/mvn_pfp_file_retrieve.pro)
Function: files = mvn_pfp_spd_download(PATHNAME)
Purpose: Retrieve or Download MAVEN data files. (Can
be used to generate filenames too). Note that this is a
Hacked version of mvn_pfp_file_retrieve, to use for SPICE
kernels which are no longer able to be accessed via
file_retrieve, jmm, 2017-01-30
INPUT:
PATHNAME: string specifying relative path to files. Default might change- Currently: 'maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat'
PATHNAME must be relative to the LOCAL_DATA_DIR and REMOTE_DATA_DIR fields of the source keyword.
"globbed" filenames (*,?) are accepted.
typical usage:
files = mvn_pfp_spd_download('maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat',/daily_names) ; get L0 files for user defined time span
files = mvn_pfp_spd_download(pathname,/daily_names,trange=trange) ; set time range
Keywords: (All are optional - none are recommended)
L0: set to 1 to return PFP L0 files
DAILY_NAMES : resolution (in days) for generating file names.
YYYY, yy, MM, DD, hh, mm, ss, .f, DOY, DOW, TDIFF are special characters that will be substituted with the appropriate date/time field
Be especially careful of extensions that begin with '.f' since these will be translated into a fractional second.
See "time_string" TFORMAT keyword for more info.
TRANGE : two element vector containing start and end times (UNIX_TIME or UT string). if not present then timerange() is called to obtain the limits.
SOURCE: alternate file source. Default is whatever is return by the function: mvn_file_source() (see "mvn_file_source" for more info)
FILES: if provided these will be passed through as output.
VALID_ONLY: Set to 1 to prevent non existent files from being returned.
CREATE_DIR: Generates a filename and creates the directories needed to create the file without errors. Will not check for file on remote server.
KEYWORDS Passed on to "SPD_DOWNLOAD":
LAST_VERSION : [0,1] if set then only the last matching file is returned. (Default is defined by source)
VALID_ONLY: [0,1] If set then only existing files are returned. (Default is defined by source keyword)
VERBOSE: set verbosity level (2 is typical)
LIMITATIONS:
Beware of file pathnames that include the character sequences:
YY, MM, DD, hh, mm, ss, .f since these can be retranslated to
the time
$LastChangedBy: jimm $
$LastChangedDate: 2017-03-24 14:19:59 -0700 (Fri, 24 Mar 2017) $
$LastChangedRevision: 23030 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_pfp_spd_download.pro $
(See projects/maven/general/mvn_pfp_spd_download.pro)
PROCEDURE: mvn_ramdir
PURPOSE:
Calculates the spacecraft orbital velocity relative to the body-fixed
rotating Mars frame (IAU_MARS). If you sit on the spacecraft and look
in this direction, the flow will be in your face.
This vector can be rotated into any coordinate frame recognized by
SPICE. The default is MAVEN_SPACECRAFT.
The co-rotation velocity in the IAU_MARS frame as a function of altitude
(h) and latitude (lat) is:
V_corot = (240 m/s)*[1 + h/3390]*cos(lat)
Models (LMD and MTGCM) predict that peak horizontal winds are 190-315 m/s
near the exobase and 155-165 m/s near the homopause. These are comparable
to the co-rotation velocity. The spacecraft velocity is ~4200 m/s in this
altitude range, so winds could result in up to a ~4-deg angular offset of
the actual flow from the nominal ram direction.
You must have SPICE installed for this routine to work. If SPICE is
already initialized (e.g., mvn_swe_spice_init), this routine will use the
current loadlist. Otherwise, this routine will try to initialize SPICE
based on the current timespan.
USAGE:
mvn_ramdir, trange
INPUTS:
trange: Optional. Time range for calculating the RAM direction.
If not specified, then use current range set by timespan.
KEYWORDS:
DT: Time resolution (sec). Default is to use the time resolution
of maven_orbit_tplot (usually 10 sec).
FRAME: String or string array for specifying one or more frames
to transform the ram direction into. Any frame recognized
by SPICE is allowed. The default is 'MAVEN_SPACECRAFT'.
Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
POLAR: If set, convert the direction to polar coordinates and
store as additional tplot variables.
Phi = atan(y,x)*!radeg ; [ 0, 360]
The = asin(z)*!radeg ; [-90, +90]
MSO: Calculate ram vector in the MSO frame instead of the
rotating IAU_MARS frame. May be useful at high altitudes.
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'V_sc_MAVEN_SPACECRAFT'.
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-03-20 09:42:50 -0700 (Mon, 20 Mar 2017) $
$LastChangedRevision: 22992 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_ramdir.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_ramdir.pro)
NAME: mvn_set_userpass,username,password PURPOSE: Sets the username and password for automatic file retrieval Typical Usage: mvn_set_userpass,'joe@gmail.com','passwd!'[,/TEMPORARY] ; This line is typically put in your IDL_STARTUP routine. Keywords: TEMPORARY: Set this keyword to prevent the username and password from being stored in an environment variable $LastChangedBy: $ $LastChangedDate: $ $LastChangedRevision: $ $URL: $
(See projects/maven/general/mvn_set_userpass.pro)
NAME: mvn_spc_clear_spice_kernels PURPOSE: Clears spice kernels, and unsets the 'kernel verified' flag in the mvn_spc_met_to_unixtime so that mvn_spc_met_to_unixtime doesn't crash CALLING SEQUENCE: mvn_spc_clear_spice_kernels $LastChangedBy: jimm $ $LastChangedDate: 2015-03-16 11:57:01 -0700 (Mon, 16 Mar 2015) $ $LastChangedRevision: 17140 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_spc_clear_spice_kernels.pro $
(See projects/maven/general/mvn_spc_clear_spice_kernels.pro)
Function: mvn_spc_unixtime_to_met Purpose: Convert unixtime to MET (mission Elapsed Time) Note: This routine MUST remain reasonably efficient since it could potentially be called from within an inner FOR loop. Author: Davin Larson $LastChangedBy: davin-mac $ $LastChangedDate: 2014-01-21 17:00:30 -0800 (Tue, 21 Jan 2014) $ $LastChangedRevision: 13959 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu:36867/repos/idl_socware/trunk/projects/maven/mvn_spc_met_to_unixtime.pro $
(See projects/maven/general/mvn_spc_unixtime_to_met.pro)
PROCEDURE: mvn_sundir
PURPOSE:
Determines the direction of the Sun at the position of the spacecraft in
one or more coordinate frames. The results are stored in TPLOT variables.
You must have SPICE installed for this routine to work. If SPICE is
already initialized (e.g., mvn_swe_spice_init), this routine will use the
current loadlist. Otherwise, this routine will try to initialize SPICE
based on the current timespan.
USAGE:
mvn_sundir, trange
INPUTS:
trange: Optional. Time range for calculating the Sun direction.
If not specified, then use current range set by timespan.
KEYWORDS:
DT: Time resolution (sec). Default = 1.
FRAME: String or string array for specifying one or more frames
to transform the Sun direction into. Any frame recognized
by SPICE is allowed. The default is 'MAVEN_SPACECRAFT'.
Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
POLAR: If set, convert the direction to polar coordinates and
store as additional tplot variables.
Phi = atan(y,x)*!radeg ; [ 0, 360]
The = asin(z)*!radeg ; [-90, +90]
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'Sun_MAVEN_SPACECRAFT'.
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-03-20 09:42:50 -0700 (Mon, 20 Mar 2017) $
$LastChangedRevision: 22992 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_sundir.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_sundir.pro)
PROCEDURE: mvn_topography
PURPOSE:
Calculates topographic profiles along the orbit track based on laser
altimeter measurements by MGS-MOLA. Topography is relative to the
areoid (same as published maps).
The result is stored in a TPLOT variable.
USAGE:
mvn_topography
INPUTS:
None: Gets all necessary inputs from tplot.
KEYWORDS:
PANS: Named variable to hold the tplot variable created.
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-05-31 11:09:39 -0700 (Wed, 31 May 2017) $
$LastChangedRevision: 23376 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_2_00/projects/maven/general/mvn_topography.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_topography.pro)
FUNCTION mvn_usr_dir() NAME: mvn_usr_dir PURPOSE: returns a user directory that can be used to store user specific files. Use sparingly! Typical Usage: file = mvn_usr_dir() + '/mvn_user_pass.sav' Keywords: $LastChangedBy: $ $LastChangedDate: $ $LastChangedRevision: $ $URL: $
(See projects/maven/general/mvn_usr_dir.pro)