This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Jun 12 10:49:46 2024.
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:
areocentric: The datum is a sphere with Mars' volumetric mean radius
of 3389.50 km.
areodetic: The datum is the IAU Mars ellipsoid:
R_equator = 3396.19 km ; R_pole = 3376.20 km
areoid: The datum is the Mars areoid, 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 = 'ellipsoid'.
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: 2021-04-07 16:16:41 -0700 (Wed, 07 Apr 2021) $
$LastChangedRevision: 29857 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_altitude.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_altitude.pro)
PROCEDURE: mvn_appdir
PURPOSE:
Determines the direction of the APP I-axis in the spacecraft frame.
There are two gimbals: inner and outer. The outer gimbal performs
rotations about the APP J-axis (orthogonal to I). The inner gimbal
performs rotations about the spacecraft Y-axis.
This vector can be rotated into any coordinate frame recognized by
SPICE. See mvn_frame_name for a list. The default is MAVEN_SPACECRAFT.
You must have SPICE installed for this routine to work. This routine will
check to make sure SPICE has been initialized and that the loaded kernels
cover the specified time range.
USAGE:
mvn_appdir, time
INPUTS:
time: If time has two elements, interpret it as a time range and
create an array of evenly spaced times with resolution DT.
If time has more than two elements, then the APP direction
is calculated for each time in the array.
Otherwise, attempt to get the time range from tplot and
create an array of evenly spaced times with resolution DT.
KEYWORDS:
DT: Time resolution (sec). Default = 10 sec.
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'.
Type 'mvn_frame_name(/list)' to see a full list of frames.
Minimum matching name fragments (e.g., 'sta', 'swe') are
allowed -- see mvn_frame_name for details.
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]
PH_180: If set, the range for Phi is -180 to +180 degrees.
REVERSE: Reverse the sense to be the -I direction.
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'APP_MAVEN_SPACECRAFT'.
FORCE: Ignore the SPICE check and forge ahead anyway.
SUCCESS: Returns 1 on normal completion, 0 otherwise.
$LastChangedBy: dmitchell $
$LastChangedDate: 2024-01-15 12:18:34 -0800 (Mon, 15 Jan 2024) $
$LastChangedRevision: 32371 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_appdir.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_appdir.pro)
PROCEDURE: mvn_earthdir
PURPOSE:
Determines the direction of Earth as viewed from Mars in any coordinate
frame recognized by SPICE. See mvn_frame_name for a list. The default
is MAVEN_SPACECRAFT. If you sit on the spacecraft and look in this
direction, you will see Earth.
You must have SPICE installed for this routine to work. This routine will
check to make sure SPICE has been initialized and that the loaded kernels
cover the specified time range.
USAGE:
mvn_earthdir, trange
INPUTS:
trange: Time range for calculating the sub-Earth point. If not
specified, this routine will attempt to get the time range
from tplot_com.
KEYWORDS:
DT: Time resolution (sec). Default = 1.
FRAME: String or string array for specifying one or more frames
to transform the Earth direction into. Any frame recognized
by SPICE is allowed. The default is 'MAVEN_SPACECRAFT'.
Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
Type 'mvn_frame_name(/list)' to see a full list of frames.
Minimum matching name fragments (e.g., 'sta', 'swe') are
allowed -- see mvn_frame_name for details.
ABCORR: Aberration correction. Options are:
'NONE' : No correction (default)
Receive (photons leave Mars at ET-LT and reach Earth at ET)
'LT' : One-way light time
'LT+S' : One-way light time + stellar aberration
'CN' : Same as 'LT' but with better accuracy
'CN+S' : Same as 'LT+S' but with better accuracy
Transmit (photons leave Earth at ET and reach Mars at ET+LT)
'XLT' : One-way light time
'XLT+S' : One-way light time + stellar aberration
'XCN' : Same as 'LT' but with better accuracy
'XCN+S' : Same as 'LT+S' but with better accuracy
The aberration correction is used for situations where photons
leave one object and arrive at the other object at a later time.
By far, the largest part of this correction is the rotation of
Mars (0.75 to 5.5 degrees). The motions of Earth and Mars in
their orbits result in a correction smaller than 0.003 deg.
For MAVEN, the only time to use an aberration correction is for
radio occultations. For all other purposes, use 'NONE'.
See documentation for CSPICE_SUBPNT for details:
https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/IDL/icy/cspice_subpnt.html
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]
PH_180: If set, the range for Phi is -180 to +180 degrees.
REVERSE: Reverse the sense to be the anti-Earth direction. If you sit on
the spacecraft and look in this direction you will have turned
your back on Earth. You're a Martian now.
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'Earth_MAVEN_SPACECRAFT'.
FORCE: Ignore the SPICE check and forge ahead anyway.
SUCCESS: Returns 1 on normal completion, 0 otherwise.
$LastChangedBy: dmitchell $
$LastChangedDate: 2023-04-11 20:59:57 -0700 (Tue, 11 Apr 2023) $
$LastChangedRevision: 31732 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_earthdir.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_earthdir.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_6_1/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'. The fragment
can appear anywhere in the full name. For example, 'LiMb'
is expanded to 'MAVEN_IUVS_LIMB'.
'GEO' is accepted as a synonym for 'MARS'.
Simply returns the input if the fragment is not recognized
or ambiguous.
USAGE:
spice_frame = mvn_frame_name(frame)
INPUTS:
frame: String scalar or array of MAVEN frame name fragments.
If no frame is provided, keyword LIST is set.
KEYWORDS:
SUCCESS: An array of integers with the same number of elements
as frame:
0 = match not found or ambiguous
1 = unique match found
RESET: Refresh the list of frame names.
LIST: Print a list of frame names and exit. Returns the
null string.
$LastChangedBy: dmitchell $
$LastChangedDate: 2023-04-24 13:29:18 -0700 (Mon, 24 Apr 2023) $
$LastChangedRevision: 31785 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/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_6_1/projects/maven/general/mvn_get_altitude.pro $
CREATED BY: Robert J. Lillis 2013-01-22
(See projects/maven/general/mvn_get_altitude.pro)
FUNCTION:
mvn_get_scpot
PURPOSE:
Given a time, returns the spacecraft potential. Only works after
the potentials have been restored/calculated by mvn_scpot.
AUTHOR:
David L. Mitchell
CALLING SEQUENCE:
pot = mvn_get_scpot(time)
INPUTS:
time: Time or array of times for getting the potential, in
any format accepted by time_double().
KEYWORDS:
OUTPUTS:
$LastChangedBy: dmitchell $
$LastChangedDate: 2018-09-12 14:13:48 -0700 (Wed, 12 Sep 2018) $
$LastChangedRevision: 25778 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_get_scpot.pro $
(See projects/maven/general/mvn_get_scpot.pro)
FUNCTION: mvn_ls
PURPOSE:
Calculates the Mars season (i.e. solar longitude)
USAGE:
ls = mvn_ls(time)
INPUT:
time: time in any format accepted by time_double.
OUTPUT:
Mars solar longitude
KEYWORDS:
TPLOT: make a tplot variable of Ls
$LastChangedBy: hara $
$LastChangedDate: 2023-12-05 16:37:25 -0800 (Tue, 05 Dec 2023) $
$LastChangedRevision: 32274 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_ls.pro $
CREATED BY: Robert J. Lillis 2017-10-09
FILE: mvn_ls
VERSION: 1.0
(See projects/maven/general/mvn_ls.pro)
PROCEDURE: mvn_mars_year
PURPOSE:
Calculates the Mars year
USAGE:
mvn_year, time
INPUTS:
time: time in string ('YYYY-MM-DD', 'YYYY-MM-DD/hh:mm:ss' etc) or double format.
OUTPUT:
Mars year (decimal)
KEYWORDS:
TPLOT: makes a tplot variable of Ls
CREATED BY: Robert J. Lillis 2017-10-09
FILE: mvn_mars_year
VERSION: 1.0
LAST MODIFICATION:
$LastChangedBy: hara $
$LastChangedDate: 2023-04-15 16:43:52 -0700 (Sat, 15 Apr 2023) $
$LastChangedRevision: 31753 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_mars_year.pro $
(See projects/maven/general/mvn_mars_year.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.
If you sit on the spacecraft and look in this direction, you will see the
ground.
This vector can be rotated into any coordinate frame recognized by
SPICE. See mvn_frame_name for a list. The default is MAVEN_SPACECRAFT.
You must have SPICE installed for this routine to work. This routine will
check to make sure SPICE has been initialized and that the loaded kernels
cover the specified time range.
USAGE:
mvn_nadir, time
INPUTS:
time: If time has two elements, interpret it as a time range and
create an array of evenly spaced times with resolution DT.
If time has more than two elements, then the ram direction
is calculated for each time in the array.
Otherwise, attempt to get the time range from tplot and
create an array of evenly spaced times with resolution DT.
KEYWORDS:
DT: Time resolution (sec). Default is 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.
Type 'mvn_frame_name(/list)' to see a full list of frames.
Minimum matching name fragments (e.g., 'sta', 'swe') are
allowed -- see mvn_frame_name for details.
POLAR: If set, convert the direction to polar coordinates and
store as additional tplot variables.
Phi = atan(y,x)*!radeg ; units deg [ 0, 360]
The = asin(z)*!radeg ; units deg [-90, +90]
PH_180: If set, the range for Phi is -180 to +180 degrees.
REVERSE: Reverse the sense of nadir to be zenith. If you sit on the
spacecraft and look in this direction you will see the stars
above.
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'Nadir_MAVEN_SPACECRAFT'.
FORCE: Ignore the SPICE check and forge ahead anyway.
SUCCESS: Returns 1 on normal completion, 0 otherwise
$LastChangedBy: dmitchell $
$LastChangedDate: 2023-04-11 20:26:40 -0700 (Tue, 11 Apr 2023) $
$LastChangedRevision: 31731 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/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.
This routine uses the NAIF convention, where the orbit number increments at periapsis. Two other
conventions are in use for MAVEN: (1) orbit number increments at the inbound periapsis segment
boundary (LM and IUVS), and (2) orbit number increments at apoapsis (NGIMS). All three conventions
agree at periapsis.
Typical CALLING SEQUENCE:
orbdata = mvn_orbit_num()
store_data,'orbnum',orbdata.peri_time,orbdata.num,dlimit={ytitle:'Orbit'}
tplot,var_label='orbnum'
KEYWORDS:
VERBOSE: Message level for dprint.
RELOAD_TIME: Interval at which to sync local files with remote server. Default = 3600 sec.
REFRESH: Ignore RELOAD_TIME and check the remote server anyway.
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: dmitchell $
$LastChangedDate: 2021-09-20 09:12:57 -0700 (Mon, 20 Sep 2021) $
$LastChangedRevision: 30304 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/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: 2021-03-17 12:57:32 -0700 (Wed, 17 Mar 2021) $
$LastChangedRevision: 29766 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/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. The default is to
calculate this direction in the MAVEN_SPACECRAFT frame.
Careful! Some people consider the opposite of the spacecraft velocity
to be the RAM direction. Watch for sign errors.
This vector can be rotated into the APP frame or any of the instrument
frames. See mvn_frame_name for a list. This is a pure rotation, so
don't try to rotate into the MSO frame, since the result would still be
in a frame that rotates with the planet. Instead, use the MSO keyword.
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. This routine will
check to make sure SPICE has been initialized and that the loaded kernels
cover the specified time range. With reconstructed kernels, this routine
has an accuracy of ~0.1 deg.
USAGE:
mvn_ramdir, time
INPUTS:
time: If time has two elements, interpret it as a time range and
create an array of evenly spaced times with resolution DT.
If time has more than two elements, then the ram direction
is calculated for each time in the array.
Otherwise, attempt to get the time range from tplot and
create an array of evenly spaced times with resolution DT.
KEYWORDS:
DT: Time resolution (sec). Default is 10 sec.
FRAME: String or string array for specifying one or more frames
to rotate the ram direction into. Any frame recognized
by SPICE is allowed. The default is 'MAVEN_SPACECRAFT'.
Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
Type 'mvn_frame_name(/list)' to see a full list of frames.
Minimum matching name fragments (e.g., 'sta', 'swe') are
allowed -- see mvn_frame_name for details. This is a pure
rotation!
POLAR: If set, convert the direction to polar coordinates and
store as additional tplot variables.
Mag = sqrt(x*x + y*y + z*z) ; units km/s
Phi = atan(y,x)*!radeg ; units deg [ 0, 360]
The = asin(z/Mag)*!radeg ; units deg [-90, +90]
PH_180: If set, the range for Phi is -180 to +180 degrees.
REVERSE: Reverse the sense of RAM to be the velocity of the incoming
ions with respect to the spacecraft. If you sit on the
spacecraft and look in this direction the flow will be into
the back of your head.
MSO: Calculate ram vector in the MSO frame instead of the
rotating IAU_MARS frame. May be useful at high altitudes.
ERROR: Calculate the magnitude of the RAM pointing error (deg)
and store as a separate tplot variable. This only works for
the APP and NGIMS frames. The STATIC frame is reversed.
Using ephemeris predicts refreshed on a regular basis, the
spacecraft can usually point the APP into the RAM direction
with an accuracy of ~0.5 deg. Occasionally, the error can
be up to ~2 deg. The reconstructed RAM direction has an
accuracy of ~0.1 deg.
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'V_sc_MAVEN_SPACECRAFT'.
RESULT: Named variable to hold the result structure.
FORCE: Ignore the SPICE check and forge ahead anyway.
SUCCESS: Returns 1 on normal operation, 0 otherwise.
$LastChangedBy: dmitchell $
$LastChangedDate: 2024-01-14 17:42:11 -0800 (Sun, 14 Jan 2024) $
$LastChangedRevision: 32365 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_ramdir.pro $
CREATED BY: David L. Mitchell
(See projects/maven/general/mvn_ramdir.pro)
PROCEDURE:
mvn_scpot
PURPOSE:
Merges five separate methods for estimating the spacecraft potential.
In cases where more than one method yields a potential, this routine
sets a hierarchy for which method takes precedence. The hierarchy
depends on location (altitude, shadow). The five methods are:
SWE+ : Estimate positive potentials by looking for a sharp
break in the electron energy spectrum. Mainly for
the solar wind and sheath.
(Author: D. Mitchell)
SWE- : Estimate negative potentials by measuring shifts in
position of the He-II photoelectron peak. Mainly
for the ionosphere.
(Author: S. Xu)
SWE/LPW : Use LPW I-V curves, empirically calibrated by the
SWE+ and SWE- methods. Works almost everywhere,
except in the EUV shadow or when the spacecraft
charges to large negative potentials.
(Author: Y. Harada)
STA- : Estimate negative potentials by the low energy
cutoff of the H+ distribution (away from periapsis),
or energy shifts, relative to the ram energy, of O+
and O2+ (near periapsis).
(Author: J. McFadden)
SWEPAD : Use pitch angle resolved photoelectron spectra to
estimate negative potentials in the wake. Combined
with the STA- method, may be used to distinguish
spacecraft and Mars potentials. Only works with
burst data.
(Author: S. Xu)
The general order of precedence is: SWE/LPW, SWE+, SWE-, STA-, and
SWEPAD (when activated by keyword).
AUTHOR:
David L. Mitchell
CALLING SEQUENCE:
mvn_scpot
INPUTS:
none - energy spectra are obtained from SWEA common block.
KEYWORDS:
POTENTIAL: Returns a time-ordered array of structures:
{time : 0D , $
potential : 0. , $
method : -1 }
The methods are: -1 (invalid), 0 (manually set),
1 (SWE/LPW), 2 (SWE+), 3 (SWE-), 4 (STA-), 5 (SWEPAD),
6 (interpolated).
The optimal value depends on the plasma environment.
SETVAL: Make no attempt to estimate the potential, just set it to
this value. Units = volts. No default.
COMPOSITE: The composite potential (SWE/LPW, SWE+, SWE-, STA-) has
been pre-calculated with this routine and stored in save
files. Set this keyword to simply restore this file and
save lots of time. (Works for multiple days and can span
UT day boundaries.) This is the default. Set this keyword
to zero to force a recalculation.
NOCALC: Do not perform a recalculation. Use the composite potential
or nothing.
LPWPOT: Use pre-calculated LPW/SWE derived potentials. There is
a ~2-week delay in the production of this dataset. You can
set this keyword to the full path and filename of a tplot
save/restore file, if one exists. Otherwise, this routine
will determine the potential from SWEA and STATIC.
Default = 1 (yes).
POSPOT: Calculate positive potentials with mvn_swe_sc_pot (SWE+).
Default = 1 (yes).
BIAS: Bias to add to SWE+ estimate. This corrects for the common
situation in which the maximum slope that is used to locate
the photoelectron line does not quite match the optimal value
of the potential. Default = 0.5 V.
NEGPOT: Calculate negative potentials with mvn_swe_sc_negpot.
Default = 1 (yes).
STAPOT: Use STATIC-derived potentials to fill in gaps. This is
especially useful in the high-altitude shadow region.
Assumes that you have calculated STATIC potentials.
(See mvn_sta_scpot_load.pro)
Default = 1 (yes).
SHAPOT: Calculate negative potentials with 'mvn_swe_sc_negpot_
twodir_burst'. Two estimates are obtained, one each for
the parallel and anti-parallel electron populations. If
both directions yield a potential, then the one closer to
zero is chosen for merging with other methods.
Requires keyword NEGPOT to be set.
Default = 1 (yes).
PANS: Named varible to hold the tplot panels created.
QLEVEL: Minimum quality level for SWEA data. Filters out the vast
majority of spectra affected by the sporadic low energy
anomaly below 28 eV. The validity levels are:
0B = Data are affected by the low-energy anomaly. There
are significant systematic errors below 28 eV.
1B = Unknown because: (1) the variability is too large to
confidently identify anomalous spectra, as in the
sheath, or (2) secondary electrons mask the anomaly,
as in the sheath just downstream of the bow shock.
2B = Data are not affected by the low-energy anomaly.
Caveat: There is increased noise around 23 eV, even
for "good" spectra.
Default = 1.
QINTERP: Interpolate the potential for small gaps caused by the
sporadic low-energy anomaly. Set this keyword to the largest
gap (in seconds) to interpolate across.
SUCCESS: Returns exit status.
OUTPUTS:
None - Result is stored in common blocks, returned via the POTENTIAL
keyword, and stored as TPLOT variables. Two TPLOT variables
are created: one with a single merged potential and one showing
the five unmerged methods in one panel.
$LastChangedBy: hara $
$LastChangedDate: 2024-02-23 14:47:10 -0800 (Fri, 23 Feb 2024) $
$LastChangedRevision: 32458 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_scpot.pro $
(See projects/maven/general/mvn_scpot.pro)
COMMON BLOCK: mvn_scpot_com
PURPOSE:
Stores the spacecraft potential information. Place this near the top
of any routine that needs access to the common block.
mvn_sc_pot : spacecraft potential structure
mvn_pot_struct : potential structure template
Espan : energy search range for swe+ method
thresh : minimum value of d(logF)/d(logE) for swe+ method
dEmax : maximum width of d(logF)/d(logE) for swe+ method
minflux : minimum 40-eV energy flux for swe+ method
badval : fill value for potential when no method works
ee : 4x oversampled energy array
dfs : 4x oversampled d(logF)/d(logE)
d2fs : 4x oversampled d2(logF)/d(logE)2
min_lpw_pot : minimum valid LPW potential
maxdt : maximum time gap to interpolate over
min_sta_pot : minimum valid STA potential for altitudes below sta_peri_alt
max_sta_alt : maximum altitude for limiting range of STA potentials
$LastChangedBy: dmitchell $
$LastChangedDate: 2017-11-30 21:10:58 -0800 (Thu, 30 Nov 2017) $
$LastChangedRevision: 24365 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_scpot_com.pro $
CREATED BY: David L. Mitchell
FILE: mvn_scpot_com.pro
(See projects/maven/general/mvn_scpot_com.pro)
PROCEDURE: mvn_scpot_comp_dailysave
PURPOSE:
USAGE:
mvn_scpot_comp_dailysave,start_day=start_day,end_day=end_day,ndays=ndays
INPUTS:
None
KEYWORDS:
start_day: Save data over this time range. If not
specified, then timerange() will be called
end_day: The end day of intented time range
ndays: Number of dates to process. Will be overwritten
if start_day & end_day are given. If both
end_day and ndays are not specified, ndays=7
$LastChangedBy: xussui $
$LastChangedDate: 2018-05-23 13:50:00 -0700 (Wed, 23 May 2018) $
$LastChangedRevision: 25251 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_scpot_comp_dailysave.pro $
CREATED BY: Shaosui Xu, 08/01/2017
FILE: mvn_scpot_comp_dailysave.pro
(See projects/maven/general/mvn_scpot_comp_dailysave.pro)
PROCEDURE:
mvn_scpot_defaults
PURPOSE:
Sets defaults for mvn_scpot and related routines. These are stored
in a common block (mvn_scpot_com).
AUTHOR:
David L. Mitchell
CALLING SEQUENCE:
mvn_scpot_defaults
INPUTS:
none - simply sets defaults for the common block.
KEYWORDS:
ERANGE: Energy range over which to search for the potential.
Default = [3.,30.]
THRESH: Threshold for the minimum slope: d(logF)/d(logE).
Default = 0.05
A smaller value includes more data and extends the range
over which you can estimate the potential, but at the
expense of making more errors.
MINFLUX: Minimum peak energy flux. Default = 1e6.
DEMAX: The largest allowable energy width of the spacecraft
potential feature. This excludes features not related
to the spacecraft potential at higher energies (often
observed downstream of the shock). Default = 6 eV.
ABINS: When using 3D spectra, specify which anode bins to
include in the analysis: 0 = no, 1 = yes.
Default = replicate(1,16)
DBINS: When using 3D spectra, specify which deflection bins to
include in the analysis: 0 = no, 1 = yes.
Default = replicate(1,6)
OBINS: When using 3D spectra, specify which solid angle bins to
include in the analysis: 0 = no, 1 = yes.
Default = reform(ABINS#DBINS,96). Takes precedence over
ABINS and OBINS.
MASK_SC: Mask the spacecraft blockage. This is in addition to any
masking specified by the above three keywords.
Default = 1 (yes).
BADVAL: If the algorithm cannot estimate the potential, then set it
to this value. Units = volts. Default = NaN.
MIN_LPW_POT : Minumum valid LPW potential.
MIN_STA_POT : Minumum valid STA potential.
MAX_STA_ALT : Maximum altitude for limiting range of STA potentials.
MAXDT: Maximum time gap to interpolate across. Default = 64 sec.
LIST: Take no action. Just list the defaults.
OUTPUTS:
$LastChangedBy: dmitchell $
$LastChangedDate: 2024-01-08 16:17:13 -0800 (Mon, 08 Jan 2024) $
$LastChangedRevision: 32345 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_scpot_defaults.pro $
(See projects/maven/general/mvn_scpot_defaults.pro)
PROCEDURE: mvn_scpot_restore
PURPOSE:
Reads in save files mvn_swe_l3_scpot_YYYYMMDD_v??_r??, create tplot
varibles for s/c pot, store potential structures in results and/or full
USAGE:
mvn_scpot_restore, trange
INPUTS:
trange: Restore data over this time range. If not specified, then
uses the current tplot range or timerange() will be called
KEYWORDS:
ORBIT: Restore mvn_swe_l3_scpot data by orbit number.
RESULTS: Hold the structure of composited potentials
TPLOT: Create tplot varibles for the composited s/c
potentials as well as for all the available s/c pots
FULL: Hold the structure of composited potentials and
all other potential structures
SUCCESS: Set to 1 if valid potentials are found.
$LastChangedBy: hara $
$LastChangedDate: 2024-02-23 14:47:10 -0800 (Fri, 23 Feb 2024) $
$LastChangedRevision: 32458 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_scpot_restore.pro $
CREATED BY: Shaosui Xu 06-23-17
FILE: mvn_scpot_restore
(See projects/maven/general/mvn_scpot_restore.pro)
PROCEDURE: mvn_scpot_survey
PURPOSE:
Makes a survey of the spacecraft potential at periapsis +/- 1 minute.
USAGE:
mvn_scpot_survey, result=result
INPUTS:
None.
KEYWORDS:
DOPLOT: Create tplot variables.
APOAPSIS: Create a database for apoapsis instead.
$LastChangedBy: dmitchell $
$LastChangedDate: 2020-03-17 11:18:56 -0700 (Tue, 17 Mar 2020) $
$LastChangedRevision: 28419 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/projects/maven/general/mvn_scpot_survey.pro $
CREATED BY: David L. Mitchell 2017-04-02
FILE: mvn_scpot_survey
(See projects/maven/general/mvn_scpot_survey.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_6_1/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.
If you sit on the spacecraft and look in this direction, you will see the
Sun. Be sure to use eye protection.
This vector can be rotated into any coordinate frame recognized by
SPICE. See mvn_frame_name for a list. The default is MAVEN_SPACECRAFT.
You must have SPICE installed for this routine to work. This routine will
check to make sure SPICE has been initialized and that the loaded kernels
cover the specified time range.
USAGE:
mvn_sundir, time
INPUTS:
time: If time has two elements, interpret it as a time range and
create an array of evenly spaced times with resolution DT.
If time has more than two elements, then the ram direction
is calculated for each time in the array.
Otherwise, attempt to get the time range from tplot and
create an array of evenly spaced times with resolution DT.
KEYWORDS:
DT: Time resolution (sec). Default = 10 sec.
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.
Type 'mvn_frame_name(/list)' to see a full list of frames.
Minimum matching name fragments (e.g., 'sta', 'swe') are
allowed -- see mvn_frame_name for details.
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]
PH_180: If set, the range for Phi is -180 to +180 degrees.
REVERSE: Reverse the sense to be the anti-Sun direction. If you sit
on the spacecraft and look in this direction, sunlight will
hit the back of your head. Be sure to use skin protection.
PANS: Named variable to hold the tplot variables created. For the
default frame, this would be 'Sun_MAVEN_SPACECRAFT'.
FORCE: Ignore the SPICE check and forge ahead anyway.
SUCCESS: Returns 1 on normal completion, 0 otherwise.
$LastChangedBy: dmitchell $
$LastChangedDate: 2023-04-11 20:26:40 -0700 (Tue, 11 Apr 2023) $
$LastChangedRevision: 31731 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/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_6_1/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)