Requirements

Software

If running on Windows, the following are required:

  • Python 3
  • SpiceyPy
  • Various standard packages (numpy, os, sys, datetime, matplotlib)
  • Xlsxwriter and xlrd

If running on the BIRA servers, please use one of the new Cent OS machines. All the above are available when loading the module 18/py36. 

 

Other

  • Latest TGO spice kernels
  • SOC event file, available from the Ops team or MAPPS (git pull the MTP you require)
  • List of MTP start/end times, sent by Ops team
  • List of solar calibration start/end times, available in the overview files sent by Ops team

   

Scripts

The observation planning software consists of 4 scripts.

Name

Description

obs_config.py

Contains hardcoded paths to main directories to find e.g. cop tables, spice kernels, etc.

Modify before running program (if required)

obs_functions.py

Contains the functions and calculations that do the obs planning.

In general, do not modify.

obs_inputs.py

Contains the information for all previous mtps and is where new information is to be added by the user for the upcoming mtps. E.g. observation types, mtp start/end times, regions of interest, lists of observation types to be added.

Information must be added here before the script is run for a new mtp.

run_planning.py

This is the script to be run.

In general, do not modify, except the mtp number

 

Set up paths

If running on Windows, or if you prefer to run the planning in a different directory, modify obs_config.py as required. There are five paths to be specified.

BASE_DIRECTORY

This is the directory containing the 4 scripts, and is where new orbit plans will be placed.

OBS_DIRECTORY

This is the base directory for the master version of the website. All input files must be placed here, and all output files, webpages and images will be generated here.

DEV_DIRECTORY

This is the base directory for the website, to be placed on the web dev server. A copy of all images and files will be made here.

COP_TABLE_DIRECTORY

This is the directory containing the cop table directories. Can be temporarily modified to a local folder for testing new cop table patches in the system.

KERNEL_DIRECTORY

This is the base directory containing up to date spice kernels. The subdirectories contain each type of kernel e.g. mk, ck, ik, etc. inside this directory.

There is an option to run offline, by setting OFFLINE=True, for when running locally outside the institute. This will not update the website and should only be done if absolutely necessary.

 

The metakernel name, given by METAKERNEL_NAME, should be specified. This should be em16_plan.tm for planning purposes. The path to the kernel directory will need to be given inside the file i.e. PATH_VALUES = ( ‘<path>\kernels' )

If running on the BIRA linux servers, all the paths are already pointing to the default locations on the servers. The planning kernel will be taken from the NOMAD datastore, so please ensure this is updated prior to running.

 

 

Operating instructions

Set up MTP and observation parameters

Add required information to obs_inputs for the MTP to be planned. Minimum required:

mtpStart

This is the EXMGEO_TD2N start time as specified by the Ops team

mtpEnd

This is the EXMGEO_TD2N end time as specified by the Ops team

copVersion

This is the cop table folder for this MTP. Remember that after each patch is executed onboard, this must be updated to reflect the new COP rows.

 

Optional additions - modify the following parameters if desired:

occultationObservationDict

nadirObservationDict

These are the dictionaries of all defined observation types, of the form:

name:[[list of diffraction orders], integration time, rhythm, number of detector lines, channel]

Where integration time is in milliseconds, rhythm is in seconds (usually 1 for occultation, 15 for nadir); the number of detector lines is usually 16 for occultation and 144 for nadir; and channel=0 for SO and 1 for LNO.

These names are used in the final orbit plan.

occultationRegionsOfInterest

nadirRegionsOfInterest

List of Mars regions where special observations should be run, of the form:

["region name", priority, "observation cycle name", min latitude, max latitude, min longitude, max longitude]

For occultations or nadir which probe one of these regions, the observation type will be chosen from a specific list rather than the generic list. If multiple regions are probed, the one with the highest priority (lowest value) will be used.

Observation cycle lists for nominal science and the regions of interest above. E.g.:

OCCULTATION_KEYS

OCCULTATION_MERGED_KEYS

OCCULTATION_GRAZING_KEYS

OCCULTATION_CH4_REGION_KEYS

NADIR_KEYS

NADIR_LIMB_KEYS

NADIR_NIGHTSIDE_KEYS

 Lists of observation types for both nominal science types (e.g. normal occultations, merged occultations, grazing occultations) and also for regions of interest (e.g. special CH4 occultation types for the regions where "observation cycle name" above is set to "OccultationCycleCH4". These are of the form:

[

["observation name 1"] * 1,
["observation name 2"] * 3,
["observation name 3"] * 1,

]

 

Where observation name corresponds to a key in the occultation or nadir dictionaries above and the number (e.g. *3) corresponds to the number of entries given to that particular observation type. Observations are chosen at random from this list, and so in the above example, observation name 1 will be run on 1/5 of corresponding occultations, type 2 will be run on 3/5 of occultations, and type 3 will be run on 1/5 (on average).

USE_TWO_SCIENCES

 For running different sets of COP rows above/below 50km tangent altitude (SO occultation only). Observations for which this happens are hard-coded. This should be set to False.

 

 

Make generic orbit plan

In run_planning.py, change mtpNumber to the desired value.

Run the script. Step 1 will be initiated, and the orbitList list will be populated with all the geometric data for the MTP

The generic orbit plan nomad_mtpxxx_plan_generic.xlsx will be placed in base directory. The generic script generally includes too many LNO dayside nadirs. Remove some by deleting some of the entries in the LNO dayside column (a blank entry means no observation will be run). Note that:

  • If the observation corresponds to a region of interest, this will be indicated in the last column – it is better to keep these observations and remove others before/after to keep to the LNO 50% duty cycle.
  • Do not delete limbs.
  • Observations conflicting with OCM slots are automatically removed. These will be indicated in the last column.
  • If a row has no SO or LNO observations, the orbit type in the 1st column must be changed to type 14.
  • Check the times of solar calibration measurements. There will be no occultations on these orbits, but LNO nadirs maybe have been assigned. Manually remove all conflicting LNO observations and set the first column to type 14.

LNO on average should have a 50% duty cycle i.e. half of all rows should be of type 4 or 14. See appendix A for more information and see previous MTPs for examples.

Send nomad_mtp0xxx_plan_generic.xlsx to the iops mailing list

 

Finalise generic orbit plan

When the modified version is received from the OU, check for errors - e.g. remove observations that are not allowed, for example UVIS observations that conflict with OCMs. There are two types of UVIS nightsides, which will be highlighted in blue or yellow:

  • Those in yellow are UVIS calibration measurements. If desired, LNO can run nightside measurements in these slots (change orbit type to 7 and add “irNightside” to irNightside column)
  • Those in blue are UVIS nightside measurements. LNO and UVIS must be switched off on the previous orbit dayside (irDayside and uvisDayside must be blank), and LNO must not run on this nightside (irNightside must be blank). Note that observations on the dayside in the chosen orbit are acceptable, as these always occur after the nightside.

For all nightsides, add “uvisNightside” to uvisNightside column if not present.

 

Additional LNO limb measurements

Orbits with types 4, 14 and 3 can be changed to LNO limb. These should correspond with CaSSIS off-nadir observations where possible, using the list provided by the ops team. This allows measurements to be made when the boresight is pointing closer to the ground than when flying in pure nadir-pointing mode.

To do this, change the orbit type to “8” and add “irLimb” to the irDayside column. Note that nightside limbs are not yet implemented. Remember that LNO should not measure continuously - if there are LNO measurements on previous/next orbits these should be removed (by setting irDayside column blank).

 

Additional LNO nightside measurements

Add if desired: change orbit type to 7 and add “irNightside” to irNightside column

 

Targeted observations

Observations lying within one of the regions of interest are automatically assigned a specific SO/LNO observation type in the generic plan.

 

 

Make LNO-UVIS joint observation list

Place the new generic orbit plan file in the orbit_plans/mtpxxx folder and run entire script again.

The LNO-UVIS joint observation file will be created in the orbit plan directory. Send this and the generic orbit plan to iops mailing list

 

Make final files

If all is ok then place generic orbit plan in the orbit_plans/mtpxxx folder and run entire script again

Final orbit plan will be placed in base directory.

If there are no errors, place the final orbit plan in the orbit_plans/mtpxxx folder and run the entire script again.

The output COP row files will be generated in cop_rows/mtpxxx folder:

#this and the other ir cop rows should be checked (compare to summary files from bojan/claudio), particularly timings and number of rows in files

LNO occultations are implemented. In the 5th column, 0 is changed to 1.

The joint occultation file is created for the ACS team. This will be sent by bojan/claudio to the soc.

 

Make calibration file

The calibration file must be filled in manually. Use values from solar_calibrations.xlsx file for miniscans/fullscans. See previous mtps for examples.

Send all files in the cop_row/mtpxxx folder to the iops mailing list

 

Add UVIS observations to website 

When UVIS COP rows are ready, place them in the cop_rows/mtpxxx directory and run step5 of the script. This will add the UVIS COP rows to the website: the new website will be updated automatically; the old website can be updated using the following commands:

  • Then log in to Tethys, change directory to “/bira-iasb/websites/dev/mars>”
  • Then run  “./sync_to_prod.sh”

 

 

Important things to remember

  • 1st observation after OCM slot should always be LNO+UVIS to keep instrument warm
  • Remember to check what calibrations there are, and send calibration COP rows separately!

 

Issues

Grazing / merged / nominal occultations do not match those assigned by the Ops team. This can occur when an observation is near-grazing or when only part of the sun is occulted by the FOV. The Ops team's orbit assignment is final.

In general, differences between nominal and merged occultations should not cause any problems. However in the final COP rows provided to the Ops team, nominal+merged are given in one file, and grazing are given in another, and so a difference in merged and grazing assignments will cause issues. There are two possible workarounds to solve this:

1. The final cop rows are manually edited, moving the conflicting row to/from the ingress file to/from the grazing file.

2. The offending orbit is manually assigned in the planning software. Search for "manually assign occultation observation type to orbit" in obs_functions.py to see previous examples of how this is done manually.

 

 

Appendix A: Typical orbit plans

The TGO orbit can be divided, approximately, into 3 categories:

  1. Periods where there are no occultations (due to high beta angle)
  2. Periods with short occultations, typically either ingress or egress in one orbit
  3. Periods with long or multiple occultations in the same orbit

The temperature of NOMAD is lowest in case (1) and highest in case (3) and so this must be offset by running the appropriate number of LNO observations. The script, in general, tends to place too many LNO nadirs during the periods where occultations are prevalent and not enough nadirs when there are no occultations.