This page was created by the IDL library routine `mk_html_help2`.

Last modified: Sat Jul 26 18:17:38 2025.

# Directory Listing of Routines

# projects/maven/mag

- BITLIS
- CHECKSUM_16BITS
- CMSYSTIME
  Compute seconds since Jan 1, 1970 and (Modified) Julian Days
- DECOM_2S_COMPLEMENT
- MARKER_SEARCH
- MAV_APID_MAG_HANDLER
- MAVEN_MAG_PKTS_READ
- MVN_MAG_GEN_L1_SAV
- MVN_MAG_GEN_SAV
- MVN_MAG_GEOM
  Given MAVEN magnetometer and ephemeris data, computes the azimuth,
- MVN_MAG_HANDLER[1]
- MVN_MAG_HANDLER[2]
- MVN_MAG_L1_STS_READ
  Convert magnetometer .sts to array of structures
- MVN_MAG_LOAD
- MVN_MAG_LOAD_QL
  Loads MAG-1 data based on a time range. The source data are sts files
- MVN_MAG_PKTS_READ
- MVN_MAG_STS_READ
  Read magnetometer .sts files
- MVN_MAG_STS_TO_SAV
- MVN_MAG_TRACE
  Given the spacecraft ephemeris and the mag vector in GEO coordinates,

# Routine Descriptions

## BITLIS

[Next Routine] [List of Routines]

    *NAME:

    	BITLIS       AUG. 28, 1989

    *CLASS:

    	data display

    *CATEGORY:

    *PURPOSE:

    	To display bit pattern for byte, integer or longword integer scalars
    	or vectors.

    *CALLING SEQUENCE:

    	BITLIS,A,B

    *PARAMETERS:

    	A   	(REQ) (I) (0,1) (B,I,L)
    		Input scalar or vector

    	B   	(REQ) (O) (1,2) (B)
    		Output vector or array of 0's (off) and 1's (on) representing
    		bit patterns of input vector A.

    *EXAMPLES:

    	a = bindgen(5)
    	bitlis,a,b
    	print,b
    	0 0 0 0 0 0 0 0 0
    	1 0 0 0 0 0 0 0 0
    	0 1 0 0 0 0 0 0 0
    	1 1 0 0 0 0 0 0 0
    	0 0 1 0 0 0 0 0 0

    *SYSTEM VARIABLES USED:

    	none

    *INTERACTIVE INPUT:

    	none

    *SUBROUTINES CALLED:

        	none

    *FILES USED:

    	none

    *SIDE EFFECTS:

    *RESTRICTIONS:

           Input parameter must be scalar or vector and either
           byte, integer or longword integer data type.

    *NOTES:

           When integers are stored in two's complement, the bit pattern
           for negative numbers will be different than for positive numbers.

    *PROCEDURE:

          Each bit in the input parameter is checked.

          Note that negative integers are stored in twos complement form.
          Therefore, the left-most bits are ON rather than OFF as they are for
          positive numbers. Input the absolute value of A is negative numbers
          to avoid this problem.

          If the input parameter is a integer vector with N elements,
          the output parameter will be an array with 16xN elements, with
          the first bit status contained in the first column 0, second bit in
          the second column, etc. A scalar byte value would produce a 8
          element vector.

          Note when the output parameter is displayed, the bit order will be
          opposite that normally used for displaying bit patterns (i.e.,
          the least significant bit is on the left and the most significant
          is on the right).

    *MODIFICATION HISTORY:

            3/30/93 rwt allow byte data
    	   Dec 1998       removed use of PARCHECK;  incorporated BITTEST code

(See projects/maven/mag/bitlis.pro)

## CHECKSUM_16BITS

[Previous Routine] [Next Routine] [List of Routines]

    *NAME:

    	CHECKSUM_16BITS

    *PURPOSE:

    	Calculate a 16 bit checksum.  Also converts 2 bytes into hexidecimal.

    *CALLING SEQUENCE:

    	checksum_16bits,byte_buff,hex_string,/rfc1071,/debug,/complement,
              /lastbitzero

    *PARAMETERS:

    	byte_buff	(input) (array) (integer)
    		The array of values to be used to determine the checksum.

    	hex_string (output) (scalar) (string)
    	        The hexidecimal checksum value.

    	rfc1071 (input) (keyword) (integer)
    		When set, the RFC1071 formula is followed which
    		includes wrap during addition.
    		http://www.faqs.org/rfcs/rfc1071.html
    		When only 2 bytes are supplied in input, this has
    		no meaning since no addition is done.

    	debug	(input) (keyword) (integer)
    		Set for debug output.

    	lastbitzero (input) (keyword) (integer)
    	        Last bit is zero for the calculated checksum value.
                   This is needed for data that is from the MAVEN MAG instruments
    		(without processing thr the PFP).

    *EXAMPLES:

    	2 bytes examples

    	   temp = [248b, 95b]
              checksum_16bits,temp,hex_string & print,hex_string
    	   F85F

    	   temp = [0b, 0b]
    	   checksum_16bits,temp,hex_string & print,hex_string
    	   0000

    	   temp = [77b, 239b]
    	   checksum_16bits,temp,hex_string & print,hex_string
    	   4DEF

    	   temp = [77b, 239b]
    	   checksum_16bits,temp,hex_string & print,hex_string,/lastbitzero
    	   4DEE

    	addition example

    	   temp = [69b, 0b, 0b, 52b, 0b, 0b, 64b, 0b, 255b, 17b,  $
    	           192b, 168b, 1b, 7b, 192b, 168b, 1b, 1b]

    	without rfc1071

    	   checksum_16bits,temp,hex_string & print,hex_string
    	   079D

    	with rfc1071

    	   checksum_16bits,temp,hex_string,/rfc1071 & print,hex_string
    	   07A0

    	another addition example

    	   temp = [69b, 0b, 0b, 52b, 0b, 0b, 64b, 0b, 255b, 17b,  $
    	           248b, 95b, 192b, 168b, 1b, 7b, 192b, 168b, 1b, 1b]

    	without rfc1071

    	   checksum_16bits,temp,hex_string & print,hex_string
    	   FFFC

    	with rfc1071

    	   checksum_16bits,temp,hex_string,/rfc1071 & print,hex_string
    	   FFFF

    *SYSTEM VARIABLES USED:

    	none

    *INTERACTIVE INPUT:

    	none

    *SUBROUTINES CALLED:

    	none

    *FILES USED:

    	none

    *SIDE EFFECTS:

    *RESTRICTIONS:

    	Input must be in multiples of 2 bytes (16 bits).

    *NOTES:

    *PROCEDURE:

    	Confirm multiple of 2 bytes.

    	Split bytes into bits.  Reverse bits.
    	Reformat to 16 bit array.

    	If more than 2 bytes
    	   Add bits.  Calculate remainder in base 2.  If RFC1071
    	   keyword is set, wrap carry.

    	Determine hexidecimal value and return.

    *MODIFICATION HISTORY:

    	14 Dec 2009  PJL  wrote
    	15 Dec 2009  PJL  changed 2 byte case to use same convert to
    			  hexidecimal logic;  added examples
    	 8 Dec 2010  PJL  add returning the bit value of the checksum
           16 Dec 2010  PJL  addeed complement keyword to obtain one's
                             complement checksum
    	11 Dec 2013  PJL  lastbitzero keyword added

(See projects/maven/mag/checksum_16bits.pro)

## CMSYSTIME

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
       CMSYSTIME

     AUTHOR:
       Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
       craigm@lheamail.gsfc.nasa.gov

     PURPOSE:
       Compute seconds since Jan 1, 1970 and (Modified) Julian Days

     CALLING SEQUENCE:
       TIMEVAL1 = CMSYSTIME(TIMEVAL0, ...)

     DESCRIPTION:

       CMSYSTIME serves two functions.  It computes the current time in a
       fashion similar to the built-in IDL system function SYSTIME().  It
       also can convert between various time representations and systems,
       including a textual format.

       The current time can be obtained by invoking CMSYSTIME with the
       /NOW keyword (which is entirely equivalent to SYSTIME(1)).

       The most substantial part of CMSYSTIME, which distinguishes it
       from SYSTIME, is its ability to convert between different time
       formats.  CMSYSTIME recognizes can recognize and convert between
       time in seconds (seconds since Jan 1, 1970 [ = SEC ]) and days
       (Julian days [ = JDAY ] or "Modified" Julian days [ = MJD = JDAY -
       2400000.5 ]).  It can also recognize and convert between local and
       GM time.

       CMSYSTIME takes maximum care to preserve the full numerical
       precision of the time values.  It converts all values to double
       precision and may return days and seconds with fractional parts.

       CMSYSTIME can also represent any time textually, not just the
       current time.  The following textual formats are supported:
            DOW MMM DD hh:mm:ss YYYY              - (Default - same as SYSTIME)
            DOW MMM DD YYYY hh:mm:ss.uuuuuu TTTTT - (/EXTENDED)
       where DOW and MMM are the abbreviated day of week and month in
       English, DD is the day of the month, YYYY is the year, hh:mm:ss is
       the time in 24 hr military time, uuuuuu are additional
       microseconds, TTTTT is the timezone offset (in +hhmm
       representation).

       CMSYSTIME accepts one parameter, the input time to be converted.
       Unlike SYSTIME, the *function* of CMSYSTIME is governed by various
       keywords, as summarized in the following table:

       Converting from                       Converting to
       ---------------                       -------------
       JDAY - /FROM_JULIAN                   JDAY - /JULIAN
       MJD  - /FROM_MJD                      MJD  - /MJD
       SEC  - (Default)                      SEC  - /SECONDS
       Current time - /NOW                   TEXT - (Default or /EXTENDED)

       Local time - /FROM_LOCAL              Local time - /LOCAL
       GM time - (Default)                   GM time - (Default)

       If no argument is specified, the default is to report the current
       time textually in the GM time zone.  CMSYSTIME automatically
       determines the local time zone.

     INPUTS:

       TIMEVAL0 - input time, in seconds or days, as described above.
                  This value is ignored if the NOW keyword is set.  Array
                  values are allowed.

     KEYWORDS:

       NOW - If set, TIMEVAL0 is ignored and the current time is used as
             input.

       FROM_JULIAN - If set, TIMEVAL0 is in Julian days.
       FROM_MJD    - If set, TIMEVAL0 is in Modified Julian days (MJD).
       FROM_LOCAL  - If set, TIMEVAL0 is in the local time zone.
                     If no FROM_ keywords are set, the input is assumed
                     to be seconds from Jan 1, 1970.

       JULIAN  - If set, the input is converted to Julian days upon output.
       MJD     - If set, the input is converted to MJD upon output.
       SECONDS - If set, the input is converted to seconds from Jan
                 1, 1970 upon output.
       LOCAL   - If set, the input is converted to the local time zone.
                 If no "destination" keywords are set, the output is
                 converted to textual representation.

       EXTENDED - Convert to a textual representation with additional
                  information, as noted above.

       TIMEZONE - Upon output, the timezone offset is returned in this
                  keyword.  The offset is time difference in seconds
                  between GM time and the local time, such that LOCALTIME
                  = GMTIME + TIMEZONE

     RETURNS:
       The resulting converted time(s), either as a double precision
       number or a string.

     EXAMPLE:

       The equivalent to SYSTIME(0)
         IDL> print, systime(0) & print, cmsystime(/now, /local)
         Wed Jul  5 12:10:46 2000
         Wed Jul  5 12:10:46 2000

       The equivalent to SYSTIME(1)
         IDL> print, systime(1) & print, cmsystime(/now,/seconds)
            9.6277750e+08
            9.6277750e+08

       Comparison between local and GM time zones (I live in the Eastern
        US, daylight savings)
         IDL> print, cmsystime(/now,/extended)
         Wed Jul  5 2000 16:13:15.659000 -0400
         IDL> print, cmsystime(/now,/local,/extended)
         Wed Jul  5 2000 12:13:15.664000 -0400

       What day of the week was it 200 days ago?  (Note, there are 86400
        seconds in one day)
         IDL> today = cmsystime(/now,/seconds)
         IDL> print, cmsystime(today-86400L*200, /local)
         Sat Dec 18 12:17:52 1999

     SEE ALSO:

       SYSTIME, JULDAY, CALDAT

     MODIFICATION HISTORY:
       Written, CM, 05 Jul 2000
       Printed time zone is zero when LOCAL=0, CM, 21 Aug 2000
       Corrected behavior of /MJD (Thanks to Marshall Perrin), 03 Jun
         2002
       Corrected local vs. UTC problem caused by fractional UTC seconds,
         (thanks to J. Wolfe) CM, 28 Dec 2005
       Corrected problem with Julian day arrays, (thanks to W. Landsman),
         CM, 29 Dec 2005
       JRE changed the output to 10h10m5s instead of 10:10:5.

(See projects/maven/mag/cmsystime.pro)

## DECOM_2S_COMPLEMENT

[Previous Routine] [Next Routine] [List of Routines]

    *NAME:

    	decom_2s_complement

    *PURPOSE:

    	Decom 2 bytes into a long integer via 2's complement.

    *CALLING SEQUENCE:

    	decom_2s_complement,buff,value

    *PARAMETERS:

    	buff (required) (input) (array) (byte)
    	   An array of 2 bytes in order as read from file.

    	value (required) (output) (scalar) (longwod integer)
    	   The calculated value.

    *EXAMPLES:

    	decom_2s_complement,buff,value

    *SYSTEM VARIABLES USED:

    	none

    *INTERACTIVE INPUT:

    	none

    *SUBROUTINES CALLED:

    	none

    *FILES USED:

    	none

    *SIDE EFFECTS:

    	none

    *RESTRICTIONS:

    	Only for use with 2 bytes

    *NOTES:

    *PROCEDURE:

    	- Check inputs
    	- Bytes to bits
    	- calculate value

    *MODIFICATION HISTORY:

    	26 Jul 2010       wrote
           29 Jul 2010       generalized the code
            3 Aug 2010       RCS

(See projects/maven/mag/decom_2s_complement.pro)

## MARKER_SEARCH

[Previous Routine] [Next Routine] [List of Routines]

    *NAME:

    	marker_search

    *PURPOSE:

    	Find the first marker in the data file and
    	return the byte number of the beginning of that marker.

    *CALLING SEQUENCE:

    	marker_search,lun,sync_pattern,after_byte,found_byte,/debug

    *PARAMETERS:

    	lun  (required) (input) (integer) (scalar)
    	   Open file unit

           sync_pattern  (required) (input) (scalar) (string - hex)
    	   The pattern to find.  Hex - include leading zeros.

    	after_byte (required) (input) (integer) (scalar)
    	   The byte to start the search after.  If not needed, use 0.

    	found_byte (required) (output) (scalar) (long word integer)
    	   The byte number in the file where
    	      - if no after_byte, the occurance of the pattern starts
    	      - if after_byte set, the next occurance of the pattern starts
    	   If marker not found, equals -1

    	debug (keyword) (input) (integer) (scalar)
    	   Set to print out debug information

    *EXAMPLES:

    	marker_search,lun,'fe6b2840',0,found_byte,/debug
    	marker_search,lun,'fe6b2840',found_byte+1L,found_byte

    *SYSTEM VARIABLES USED:

    	none

    *INTERACTIVE INPUT:

    	none

    *SUBROUTINES CALLED:

    	none

    *FILES USED:

    	open input file from parameter list

    *SIDE EFFECTS:

    	Sets input file read pointer to start of file

    *RESTRICTIONS:

    *NOTES:

    	found_byte equals -1 if marker not found

    *PROCEDURE:

           - determine size of file
           - determine length of sync pattern and separate first byte value
    	- If after_byte not equals 0, skip number of bytes.
    	- Until end-of-file or marker is found,
    	  - read a buffer of bytes
    	  - convert the bytes to hex
    	  - check for the start of the marker
    	  - if start of marker is found,
    	    - obtain additional bytes if needed
               - add leading zeros if necessary
    	    - combine the hex of the neceaary number of bytes
    	    - if equals the marker, return found byte of the marker

    *MODIFICATION HISTORY:

    	 7 May 2012  PJL  wrote - based on juno_cip_marker_search and
                             juno_fgm_pkts_search - generalize
           13 Mar 2013  PJL  before each readu, make sure there are enough bytes
                             remaining
            8 Jul 2013  PJL  subtract bytes read from track number

(See projects/maven/mag/marker_search.pro)

## MAVEN_MAG_PKTS_READ

[Previous Routine] [Next Routine] [List of Routines]

    *NAME:

    	maven_mag_pkts_read

    *PURPOSE:

    	Read the MAVEN MAG data.  Formats handled are from
           - instrument,
    	- engineering packet from University of California at Berkeley
    	  Particle and Fields Package (PFP) DPU,
    	- science packets (multiple formats) from PFP DPU, and
           - CCSDS format from spacecraft (available via LASP SDC).

    *CALLING SEQUENCE:

    	maven_mag_pkts_read,filename,data,data_source,   $
              input_path=input_path,verbose=verbose

    *PARAMETERS:

    	filename (required) (input) (string) (scalar)
    	   Input filename - without path.

    	data (required) (output) (structure) (array)
    	   Data in a array of structures.  One array entry per packet.

    	data_source (required) (input) (scalar) (string)
    	   Describes the source os the data file.
    	   'instrument' - from the instrument, no PFP or spacecraft in path
    	   'pfp_eng' - engineering data via the PFP DPU which includes
    		       the PFP header
    	   'pfp_sci' - science data via the PFP DPU which includes the
    		       PFP header
    	   'ccsds' - data from the spacecraft which includes the CCSDS
    		     and PFP headers

    	input_path (keyword) (input) (string) (scalar)
    	   Path to input file.

    	verbose (keyword) (input) (integer) (scalar)
    	   Set to have additional output to screen.

    *EXAMPLES:

    	pfp_input_path = '/data4/maven/data/ucb/'
    	file26 = 'APID_26.dat'
    	maven_mag_pkts_read,file26,data26,'pfp_eng',   $
              input_path=pfp_input_path,/verbose

    	file40 = 'APID_40.dat'
    	maven_mag_pkts_read,file40,data40,'pfp_sci',   $
    	   input_path=pfp_input_path,/verbose

    	file40avg = 'APID_40_avg2.dat'
    	maven_mag_pkts_read,file40avg,data40avg,'pfp_sci',   $
    	   input_path=pfp_input_path

           input_path = '/home/magdata/maven/data/flight/telemetry/sci/mag/l0/'
           file = 'mvn_mag_svy_l0_20131205_v2.dat'
    	maven_mag_pkts_read,file,data,'ccsds',input_path=input_path

    *SYSTEM VARIABLES USED:

    	none

    *INTERACTIVE INPUT:

    	none

    *SUBROUTINES CALLED:

           parsestr
    	marker_search
    	bitlis
           decom_2s_complement
    	checksum_16bits

    *FILES USED:

    	File given in input parameters.

    *SIDE EFFECTS:

    	none

    *RESTRICTIONS:

    	assumes data in input files is
    	- all from the instrument, or
    	- all engineering via PFP DPU (ApIds 26 and 27), or
    	- all science via PFP DPU (ApIds 40, 41, 42, and 43), or
    	- from the spacecraft with CCSDS and PFP headers.

           ApId 30 (passthru) not coded for

           Maximum of 550,000 packets per file currently permitted.

    *NOTES:

      PFP MAG engineering checksum only uses MAG portion
      PFP MAG science checksum uses PFP header and MAG portion

      Which MAG sensor is which:

        OB is FM1; on +Y; SSN #5; PFP APID 26 (engr), 40, 42; Drive select 0
        IB is FM2; on -Y; SSN #6; PFP APID 27 (engr), 41, 43; Drive select 3
        PFP test setup at SSL is EM;  SSN #1

      Message ID not modified by PFP FSW - not to be used to determine packet type

      Problems
      - message ids not as expected for PFP packets
      - decom id not as expected for engr pkt (set to 0 not expected 1)
      - no PFP ApID 30 data (passthru)

    *PROCEDURE:

    	- determine input path to use
    	- make sure input file exists
    	- setup useful values and structures
    	- read until end of file - or not enough bytes left
    	- for the first (index 0) packet, calculate estimated number of packets
    	- if CCSDS source, decome that header
    	- if data via PFP DPU, decom the PFP header
    	  - if not a MAG packet, skip
    	  - if a MAG science packet, include the PFP header in the MAG
    	    checksum calculation
    	- decom the MAG data header
    	  - failed_flag set to 1 if values are not as expected
    	- decom the MAG engineering data (if not a science data packet)
    	- decom MAG science data (if not an engineering packet)
    	- decom MAG checksum and verify value
    	  - for instrument packet, last bit will always be 0
    	- if engineering data via PFP DPU, decom extra bytes
    	- if CCSDS packet, decom CCSDS checksum (not being checked)
    	- if falied_flag is set, find next packet
    	- after file is read, save only entries that have data

    *MODIFICATION HISTORY:

    	30 Mar 2012  PJL  started writing
           26 Apr 2012  PJL  continued
           27 Apr 2012  PJL  continued
            8 May 2012  PJL  determined that message ids in UCB supplied data
            and              not as expected;  change code to check second
            9 May 2012       byte to determine type - perfer to use message id -
                             will need to rework after data is corrected
           18 May 2012  PJL  might be able to handle muplitple UCB ApIds in
                             one file now - not tested
              Feb 2013  PJL  added CCSDC header;  more of UCB header
           24 May 2013  PJL  add code to skip bytes if PFP, but not MAG pkt
           13 Mar 2013  PJL  add check for if marker_search found additional data;
                             before each readu, check that there are enough bytes
                             remaining
           24 May 2013  PJL  skip data that is not MAG data
           29 May 2013  PJL  corrected data subseting at end (0.4.1)
           19 Jun 2013  PJL  handle headers with no or only time data
           19 Jul 2013  PJL  added check of source 2 if hex to determine source
    	                  is an 'else' (still need to code marker_search)
           22 Jul 2013  PJL  rearranged failed flag code;  handle sync pattern
                             not found
           15 Oct 2013  PJL  handle CCSDS length of 0 bytes;  set the marker_search
                             after_byte based on expected packet type (0.4.5)
           27 Nov 2013  PJL  data_source as input instead of trying to determine
           29 Nov 2013  PJL  adding MAG data checksum check (works for engineering
                             data, but not for science data);  engineering tags
                             renamed 'z' replaced with 'e' for 8p2vp, 8p2vn,
                             13vp, 13vn, 11p4v, 2p5vp, and 3p3vp
           02 Dec 2013  PJL  reformat help print
           04 Dec 2013  PJL  finally understand PFP MAG science packet checksum
           06 Dec 2013  PJL  ucb_ changed to pfp_;  rename pfp_extra_engr to
                             pfp_engr;  decom pfp_engr;  data_type (unused)
                             replaced with source;  replaced apid with apid_hex;
                             added apid (decimal);  clean up;  additional notes;
                             additional checks for failed cases (0.4.7)
           11 Dec 2013  PJL  messaage ids will not be fixed - remove messages
                             that assumes they will;  cross check serial number,
    			  drive value, and PFP apid; passthru (PFP Apid 0x30)
                             code commented out (no data to test;  handle
                             direct from instrument (last bit always zero)
                             checksum verification correctly; updated prolog (0.5)
           20 Dec 2013  PJL  compare pkt_type and difference flags - if not
                             correct match, set failed flag
    	11 Mar 2014  PJL  changed MAVEN spacecraft number from 202 to -202
    	18 Mar 2014  PJL  correct difference words (skip first difference
    			  since all zeros and use next 63)

(See projects/maven/mag/maven_mag_pkts_read.pro)

## MAV_APID_MAG_HANDLER

[Previous Routine] [Next Routine] [List of Routines]

    Function:  mav_apid_mag_handler
    Purpose:
     Author: Davin Larson
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2013-03-07 12:55:04 -0800 (Thu, 07 Mar 2013) $
     $LastChangedRevision: 11745 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mav_apid_mag_handler.pro $

(See projects/maven/mag/mav_apid_mag_handler.pro)

## MVN_MAG_GEN_L1_SAV

[Previous Routine] [Next Routine] [List of Routines]

     $LastChangedBy: ali $
     $LastChangedDate: 2023-10-21 18:50:42 -0700 (Sat, 21 Oct 2023) $
     $LastChangedRevision: 32205 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_gen_l1_sav.pro $
    This procedure will create IDL save files from STS files.  It is only intended to be run from a batch job

(See projects/maven/mag/mvn_mag_gen_l1_sav.pro)

## MVN_MAG_GEN_SAV

[Previous Routine] [Next Routine] [List of Routines]

    This procedure will creat IDL save files from STS files.  It is only intended to be run from a batch job

(See projects/maven/mag/mvn_mag_gen_sav.pro)

## MVN_MAG_GEOM

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_mag_geom
    PURPOSE:
      Given MAVEN magnetometer and ephemeris data, computes the azimuth,
      elevation and clock angles of the magnetic field in the local
      horizontal plane at the spacecraft, and traces the magnetic
      field in a straight line from the spacecraft to a specified
      altitude (see ALT keyword).  This tracing calculation can be
      sigificantly in error when the distance to the central object is
      large and the straight-line approximation becomes dubious.

      The information is appended to the mag_pc structure with the
      following tags:

          amp   : magnetic field amplitude (nT)
          azim  : magnetic azimuth angle (deg)
          elev  : magnetic elevation angle (deg)
          clock : magnetic clock angle (deg)
          dist  : distance along the magnetic field line between the
                  spacecraft and the trace location (km)
          lon   : east longitude at the trace location (deg)
          lat   : latitude at the trace location (deg)

      Magnetic azimuth and elevation are defined as follows:

          AZ =   0 --> East           EL =   0 --> horizontal
          AZ =  90 --> North          EL = +90 --> radial outward (up)
          AZ = 180 --> West           EL = -90 --> radial inward (down)
          AZ = -90 --> South

      Magnetic clock angle is an angle in the local horizontal plane
      (like AZ) that is referenced to the azimuth of the Sun:

          CLOCK =   0 --> azimuth of Sun
          CLOCK = 180 --> opposite to azimuth of Sun

    USAGE:
      mvn_mag_geom
    INPUTS:
           None:      All data obtained from tplot variables.  The result is
                      stored in tplot variables.

    KEYWORDS:
           ALT:       Electron absorption altitude.  Default is 170 km for Mars
                      and 0 km for Phobos and Deimos.

           VAR:       Tplot variable name that contains the magnetic field data
                      in payload coordinates.  Default = 'mvn_B_1sec'.  Variable
                      names for MAG data in other frames are derived from this.

           PHOBOS:    Set this keyword to trace magnetic field lines to Phobos.
                      Good luck!  The moon is small and you have to get very
                      close for a reasonable chance of intersection.

           DEIMOS:    Set this keyword to trace magnetic field lines to Deimos.
                      Good luck!  The moon is small and you have to get very
                      close for a reasonable chance of intersection.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2016-04-25 20:11:20 -0700 (Mon, 25 Apr 2016) $
     $LastChangedRevision: 20926 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_geom.pro $

    CREATED BY:	David L. Mitchell  2015-04-02

(See projects/maven/mag/mvn_mag_geom.pro)

## MVN_MAG_HANDLER[1]

[Previous Routine] [Next Routine] [List of Routines]

    Function:  mav_mag_handler
    Purpose:
     Author: Davin Larson
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2015-11-06 14:02:07 -0800 (Fri, 06 Nov 2015) $
     $LastChangedRevision: 19296 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_handler.pro $

(See projects/maven/mag/mvn_mag_handler.pro)

## MVN_MAG_HANDLER[2]

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  mvn_mag_svy_decom
    PURPOSE: Decomutates a ccsds structure and returns a the RAW decomutated data.  (either 32 or 64 vectors depending upon compression)
    Known Bugs:
       When the averaging period changes there can be a timing error for that packet (or a neighbor packet ?) Only occurs rarely
       When the scale changes there can be a scaling error in that packet.  Only occurs rarely

(See projects/maven/mag/mvn_mag_handler.pro)

## MVN_MAG_L1_STS_READ

[Previous Routine] [Next Routine] [List of Routines]

     Function:
     MVN_MAG_L1_STS_READ

     PURPOSE:
     Convert magnetometer .sts to array of structures

     AUTHOR:
     Roberto Livi (rlilvi@ssl.Berkeley.edu) and Davin Larson

     CALLING SEQUENCE:
     data = MVN_MAG_STS_READ(filename,header=header)

     KEYWORDS:
     FILENAME: String containing .sts filename to be loaded

     NOTES:
          Uses append_array.pro

     EXAMPLE:
            IDL> data_structure = mvn_mag_sts_read( filename, header = header)

     HISTORY:

     VERSION:
       $LastChangedBy: ali $
       $LastChangedDate: 2023-10-21 18:50:42 -0700 (Sat, 21 Oct 2023) $
       $LastChangedRevision: 32205 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_l1_sts_read.pro $

(See projects/maven/mag/mvn_mag_l1_sts_read.pro)

## MVN_MAG_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    Procedure MVN_MAG_LOAD
    Usage:
      MVN_MAG_LOAD                            ; Load default
      MVN_MAG_LOAD,'L1_FULL'                  ; load Full res sav files
      MVN_MAG_LOAD,'L2_30SEC',trange=trange

     Purpose: Loads MAVEN mag data into tplot variables

     Author: Davin Larson and Roberto Livi
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-03-23 14:45:46 -0700 (Sun, 23 Mar 2025) $
     $LastChangedRevision: 33197 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_load.pro $

(See projects/maven/mag/mvn_mag_load.pro)

## MVN_MAG_LOAD_QL

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_mag_load_ql
    PURPOSE:
      Loads MAG-1 data based on a time range.  The source data are sts files
      produced by the MAG team at GSFC.  These ascii files are first converted
      to cdf and sav files by mag_sts_to_cdf.  This routine downloads (if
      necessary) the sav file, restores it, and loads it into a tplot variable.

      These data are in payload coordinates (spice_frame = MAVEN_SPACECRAFT).
      Appropriate tags are added to the tplot structure for rotation to
      other frames.

      OBSOLETE as of 2014-12-11.

    USAGE:
      mvn_mag_load_ql

    INPUTS:
           trange:        Time range for loading data.

    KEYWORDS:
           FILENAME:      Full path and file name containing MAG QL data.
                          Can be an array of file names.

           VAR:           Name of TPLOT variable created.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2014-12-11 13:12:52 -0800 (Thu, 11 Dec 2014) $
     $LastChangedRevision: 16463 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_load_ql.pro $

    CREATED BY:    David L. Mitchell  2014/10/09

(See projects/maven/mag/mvn_mag_load_ql.pro)

## MVN_MAG_PKTS_READ

[Previous Routine] [Next Routine] [List of Routines]

    *NAME:

    	mvn_mag_pkts_read

    *PURPOSE:

    	Read the MAVEN MAG data.  Formats handled are from instrument,
    	engineering packet from University of California at Berkeley
    	(UCB) DPU, or science packets (multiple formats) from UCB DPU.

    *CALLING SEQUENCE:

    	mvn_mag_pkts_read,filename,data,input_path=input_path,verbose=verbose

    *PARAMETERS:

    	filename (required) (input) (string) (scalar)
    	   Input filename - without path.

    	data (required) (output) (structure) (array)
    	   Data in a array of structures.  One array entry per packet.

    	input_path (keyword) (input) (string) (scalar)
    	   Path to input file.

    	verbose (keyword) (input) (integer) (scalar)
    	   Set to have additional output to screen.

    *EXAMPLES:

    	ucb_input_path = '/data4/maven/data/ucb/'
    	file26 = 'APID_26.dat'
    	mvn_mag_pkts_read,file26,data26,input_path=ucb_input_path,/verbose

    	file40 = 'APID_40.dat'
    	mvn_mag_pkts_read,file40,data40,input_path=ucb_input_path,/verbose

    	file40avg = 'APID_40_avg2.dat'
    	mvn_mag_pkts_read,file40avg,data40avg,input_path=ucb_input_path

    *SYSTEM VARIABLES USED:

    	none

    *INTERACTIVE INPUT:

    	none

    *SUBROUTINES CALLED:

           parsestr
    	marker_search
    	bitlis
           decom_2s_complement

    *FILES USED:

    	File given in input parameters.

    *SIDE EFFECTS:

    	none

    *RESTRICTIONS:

    	assumes data in input files is all from the instrument, or all
    	engineering via UCB DPU (ApIds 26 and 27), or all science via UCB
           DPU (ApIds 40, 41, 42, and 43).  If that is not how it is going to
           be delivered, then data sample as will be delivered is required to
           be supplied

           ApId 30 not coded for

           Maximum of 550,000 packets per file currently permitted.

    *NOTES:

      need to
      - test bit sections
      - calculate and check checksum
      - add rms fields (2's complement?) - not in UCB CTM - clarification required
      - engr b field
      - work error cases (out of data, not in sync)
      - work difference word between header and checksum
      - work UCB header field names (JEPC will not care about these)
      - rework for UCB message ids being incorrect (mostly done)
      - increment engr & science packet numbers
      - test with ApID 30 (no data in that format)
      - test with mixed message ids (no data in that format)
      - clean up two arrays
      - think about ib vs ob packets
      - test resync section

      testing (special attention to)
      - bit sections

      Problems
      - message ids not as expected for UCB packets
      - decom id not as expected for engr pkt 9set to 0 not expected 1)

    *PROCEDURE:

    *MODIFICATION HISTORY:

    	30 Mar 2012    started writing
           26 Apr 2012   continued
           27 Apr 2012    continued
            8 May 2012    determined that message ids in UCB supplied data
            and              not as expected;  change code to check second
            9 May 2012       byte to determine type - perfer to use message id -
                             will need to rework after data is corrected
           18 May 2012    might be able to handle muplitple UCB ApIds in
                             one file now - not tested
              Feb 2013    added CCSDC header;  more of UCB header
           24 May 2013    add code to skip bytes if PFP, but not MAG pkt
           13 Mar 2013    add check for if marker_search found additional data;
                             before each readu, check that there are enough bytes
                             remaining
           24 May 2013    skip data thta is not MAG data
           29 May 2013    corrected data subseting at end (0.4.1)

(See projects/maven/mag/mvn_mag_pkts_read.pro)

## MVN_MAG_STS_READ

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
    	MVN_MAG_STS_READ

     PURPOSE:
    	Read magnetometer .sts files

     AUTHOR:
    	Roberto Livi (rlilvi@ssl.Berkeley.edu) and Davin Larson

     CALLING SEQUENCE:

     KEYWORDS:
    	FILENAME: String containing .sts filename to be loaded

     NOTES:
          Uses append_array.pro

     EXAMPLE:
         IDL> data_structure = mvn_mag_sts_read( filename, header = header)

     HISTORY:

     VERSION:
       $LastChangedBy: ali $
       $LastChangedDate: 2014-10-03 15:10:00 -0500 (Fri, 03 Otc 2014)$
       $LastChangedRevision: 2014-10-03 15:10:00 -0500 (Fri, 03 Otc 2014)$
       $URL:svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/projects/general/CDF/mag_sts_to_cdf.pro$

(See projects/maven/mag/mvn_mag_sts_read.pro)

## MVN_MAG_STS_TO_SAV

[Previous Routine] [Next Routine] [List of Routines]

     $LastChangedBy: ali $
     $LastChangedDate: 2023-10-21 18:50:42 -0700 (Sat, 21 Oct 2023) $
     $LastChangedRevision: 32205 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_sts_to_sav.pro $
    This procedure will create IDL save files from STS files. It is only intended to be run from a batch job

(See projects/maven/mag/mvn_mag_sts_to_sav.pro)

## MVN_MAG_TRACE

[Previous Routine] [List of Routines]

    PROCEDURE:   mvn_mag_trace
    PURPOSE:
      Given the spacecraft ephemeris and the mag vector in GEO coordinates,
      determines whether or not a straight-line extension of the mag vector
      intersects the Mars atmosphere at 170 km (nominally), and if so the
      location of that intersection point in GEO coordinates.

    USAGE:
      mvn_mag_trace
    INPUTS:
           None:      All data obtained from tplot variables.  The result is
                      stored in tplot variables.

    KEYWORDS:
           ALT:       Electron absorption altitude.  Default = 170 km.

           TRACE:     Named variable to hold result: [dist, lon, lat]
                      Units: km, deg, deg

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2015-08-21 14:39:32 -0700 (Fri, 21 Aug 2015) $
     $LastChangedRevision: 18564 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/mag/mvn_mag_trace.pro $

    CREATED BY:	David L. Mitchell  2015-04-02

(See projects/maven/mag/mvn_mag_trace.pro)