EIS planning - a step-by-step guide

Version 1.2, Peter Young
If you find any errors in this guide, or notice something has changed please contact Peter Young. Feel free to modify the text and either send it to the eis-soft mailing list or Peter Young.

The EIS planning week - orientation

The EIS Chief Observer (CO) begins work on Friday, attending the daily and weekly planning meetings that day, and also planning for the period Saturday 11 UT to Monday 11 UT.

On Saturday, the CO plans for the period Monday 11 UT to Tuesday 11 UT.

On Monday to Thursday the CO plans for a 24 hour period starting from 11 UT of the following day.

The CO must be at ISAS on the Friday morning after the last planning day in case there are any changes to the plan that need to be uploaded (e.g., a pointing change).

The EIS planning period - daily structure

Due to the different time zones (JST and UT), and the fact that a 1 day planning period straddles two days it can become confusing about what happens when. The notation I use is as follows.

The plan is prepared on Day 0, and is uploaded on Day 1 for observations to begin on Day 1 and finish on Day 2. The upload takes place around 8-9 UT on Day 1, with observations beginning around 11 UT on Day 1. Because the plans prepared on Friday and Saturday are different from the rest of the week, Day 1 and Day 2 are different.
I summarise the actual days below

Planning day (Day 0) Day 1 Day 2
Fri Sat Mon
Sat Mon Tue
Mon-Thu Tue-Fri Wed-Sat

The EIS plan is usually prepared in the afternoon of Day 0, i.e., 13-18 JST, or 4-9 UT.

There is the opportunity to adjust pointing on Day 1 after the daily meeting (10.30 JST, 1.30 UT) , and this should be done before 13.00 JST. Either you can request a change to the Hinode pointing (requires permission of all 3 instruments), or you can adjust only EIS. The latter, however, requires the plan to be edited and re-processed through CPT. A change to the actual studies inserted in the timeline must be agreed by the Chief Planner.

Daily planning meeting

When negotiating with the other teams about what to do, remember that the EIS "prime time" is 10-16 UT when we aren't affected by the SAA, so if you want a good data-set for yourself try and protect this period.

Try asking the XRT planner if they're prepared to sacrifice a synoptic in order to give you a longer observation.

Make sure to ask the planner to show an XRT image during the meeting. This will be useful for planning later (see section on image_tool).

Before starting the planning

The EIS weekly schedule and calibration

The EIS planner will receive from the SSCs an outline of what observations are suggested to be run during the week. If you haven't received this outline directly, then ask one of the Davids. Note that you don't have to support everything in this outline as some will be target dependent.

The Davids will also send you a list of calibration and engineering activities to perform during the week.

Editing the Daily Events page

The Hinode Daily Events page contains a section that lists what observations are occurring each day. Before the start of the weekly meeting on Friday, you should edit each day of the planning week to insert any requests that EIS has (based on the weekly outline mentioned above and your own plans).

Note: the Hinode planning week starts on Monday 11 UT, which is different to the EIS planning week, so you will need to edit from Monday through to the following Sunday.

Starting the planning

Upon sitting down at the eisco machine to start your planning, the first thing you should do is to open the eisco_manual file found in ~/scripts. This contains a number of useful commands that can simply be cut-and-pasted into the terminal, including most of the commands mentioned in this document.

Four useful  things to cut-and-paste are the following

# [ ] Show OP period
xterm -geometry   40x25+0+50  -hold -e \
"cd /home/flare/slb/cp/cmdpln/tomorrow; cat op_period_????????????.evt" &

# [ ] Show SAA information in the left bottom window
xterm -geometry   40x55+0+800 -hold -e \
"cd /home/flare/slb/cp/cmdpln/tomorrow; grep SAA obev_????????????.evt" &

# [ ] Show night information in the right bottom window
#      - added by Peter Young, 22-May-2007 for eclipse season
xterm -geometry   40x65+1700+600 -hold -e \
"cd /home/flare/slb/cp/cmdpln/tomorrow; grep NGT obev_????????????.evt" &

# [ ] Show re-point schedule in the right window
xterm -geometry  140x40+250+50  -hold -e \
"cd /home/flare/slb/cp/cmdpln/tomorrow; cat re-point_????????????.txt" &

These pop up four windows with useful information for the planner.

Next enter IDL and start up the planning tool:

> sswidl
IDL> eis_mk_plan

Working out the planning period

Apart from Friday, when you plan for two days, you will be planning for a 24 hour period. 

To determine the start time of your plan firstly check the OP_START time in the OP window, and then the time of the first pointing in the re-pointing file (usually 10 mins after OP_START). Your plan should then start at two minutes after the first pointing. E.g.,

OP_START: 10:24
First pointing: 10:34
EIS plan start time: 10:36

However, if yesterday's plan finishes at a time after this time, then you should start the new EIS plan about 5 minutes after the end of the last study.

There is no definite end point to day's plan. You can choose to finish the plan by the OPPLN_PROHIBIT time (see the OP window). However, if you're confident that the satellite pointing will remain the same into the next day's plan, then you can choose to allow a study to run beyond OPPLN_PROHIBIT (although see restriction below) and even up to the time of the next day's synoptic (usually around 11 UT).

Planning restrictions - 1. EIS table upload

No study is allowed to run through the table upload on Day 2, thus this period must remain empty on the timeline. Please check the Hinode daily event page for Day 2 to find out the table upload period. The plan should be restarted one minute after the table upload has taken place.

Planning restrictions - 2. OP prohibit

In the OP window, you'll see a time given for OPPLN_PROHIBIT. Any new studies placed in the plan after this time will not get run (as their commands will be overwritten by the next day's plan). However, it is OK for a study started before OPPLN_PROHIBIT to run past this time and so into the next day's planning period. Typically you would simply repeat the study started directly after the EIS table upload.

Planning restrictions - 3. SAAs

Studies should not be started in the SAA. If you try to start a study in the SAA, then mk_plan will check and ask you to move it to five minutes after the SAA.

Planning restrictions - 4. Re-pointing events

After a re-pointing (e.g., when Hinode goes to disk centre for a synoptic) it takes about 1.5 minutes for the pointing to stabilise. You should thus leave 2 minutes after all re-pointing events.

Planning restrictions - 5. XRT synoptics

There are usually four synoptics per day, roughly at 11, 18, 24 and 6 UT. EIS runs the study SYNOP001 during these synoptics. Note that sometimes a planner may decide to run a study through the synoptic period in order to get a complete 12 hour run. You will thus see a 10 minute period in your data-set where Hinode moves to Sun centre and then moves back again.

Using eis_mk_plan

Inserting a study on the timeline

Move the cursor to the time you want the study to start  by entering the time  in the "Cursor time" text widget.

Now select your study. Click on 'Study' and from the drop-down list choose 'Load/Select study'. A new widget will pop up with the list of studies. Click on the study, and then 'Insert at cursor time (time-tagged)'. Do not use the Append to highlighted entry button.

For each study you add to the timeline, you should try to fill in the following fields:

OBS_DEC: A short description of the observation, e.g., "Sac Peak campaign to observe spicules"
SCI_OBJ: The target should be selected from a list. You can pick up to 5. Make sure to always choose one of : active region, quiet Sun, coronal hole, synoptic, engineering.
NOAA_NUM: If you're observing an active region, then give the NOAA number here. E.g., for AR 10956 type "10956".
JOP_ID

These entries will be valuable when users come to search the EIS archive.

Raster repeats

The study duration is not fixed. It can be increased by changing the number of repeats of each raster in the study. You will see a dialogue box towards the bottom of the eis_mk_plan GUI that lists each raster contained in the study. You can change the number of raster repeats by clicking on one of the rasters. Several widgets below the raster window will now become activated.

In the box 'Raster Repeats' type in the number of repeats you would like, and hit return. You should see the study duration on the timeline increase in length based on the repeats you've typed.

Pointing

Firstly, note that the default pointing for an EIS study is the centre of the EIS field of view. This is different from the satellite pointing (i.e., SOT pointing). Currently EIS is offset -50" in solar-Y, but there is no offset in solar-X. Thus if you want to point to exactly the same position as SOT you must add 50" to the solar-Y pointing. 

There are three ways to point a study:

  1. Type the coordinates manually into the X and Y boxes in the bottom left of the mk_plan widget.
  2. Click on the Pointing... button which will bring up another widget with two options: either to reset to spacecraft pointing (i.e., go back to the centre of the EIS field of view); or you can select running offsets to the rasters. I.e., if your study contains 5 rasters (5 entries in the raster box), you can point the first one, and then specify a running offset to the subsequent 4 rasters. If your study contains 1 raster and you specify 5 repeats, then the offset will not apply to these.
  3. Click on 'Send to image_tool' to use image_tool to choose a pointing. See the next section.

Using image_tool

Loading an image

To load an image into eis_image_tool click on File and then Import Images. This brings up the show_synop tool.

Click on the Search button in show_synop, and the routine will connect over the internet to remote servers from where SOHO and TRACE images can be accessed (no ground-based?). After selecting an image, click on download and the image will be downloaded to a local directory (see the bottom window in show_synop). Click on the image in this window and then click Display which will send the image to image_tool. You can now close show_synop.

At present Hinode/XRT images are not available to show_synop. The images available in the XRT quicklook directory in /soda seem to have some pointing problems, so it is best to use the image used by the chief planner in the daily meeting as software is used to automatically fit the limb in these images, thus giving accurate coordinates. The image is available as an IDL map in a save file and you can convert it to a fits file suitable for the EIS image tool by running the following routine in IDL:

IDL> .r ~/young/make_latest_xrt_fits

which creates the file 'latest_xrt.fits' in the directory ~/solar_images.

If you need to use a TRACE mosaic (for example during the SOHO keyhole, when no EIT images are available), then you can download these manually from:

http://trace.lmsal.com/mosaic_archive/fits/

To find the image you need, do a search (Ctrl-F in Firefox) for the month in the format "200705" for May 2007, and find the most recent 171 image. Download the file to ~/solar_images.

Image_tool features

Image_tool automatically plots the EIS field of view on the selected solar image. To show the location of the raster fields of view, click on the 'Plot All Rasters' button (you'll see a separate box for each of the rasters in the study).

To zoom in on a region, draw a "rubber-band" box on the image by clicking-and-dragging the mouse. Then click on the "Zoom in" button.

Running CPT

  1. Select the OP period that applies from the drop-down menu (check the op_period*.evt file in ../cp/cmdpln/tomorrow)
  2. The start time is set to any time between the end of the previous day's plan and the beginning of the new plan..
  3. Choose an end time shortly after your plan finishes (say an hour afterwards).
  4. Enter the upload time. Check the Hinode daily events webpage for Day 1, and choose a time midway between the start and end of the EIS upload pass.
  5. Input names of observer, planner and tohban (refer to the Hinode daily events webpage).
  6. Test CPT, and check the console window for any messages.

After testing CPT (and assuming the test is OK), there are two options. If you are planning on Day 0, then you do not press the 'Run CPT' - you simply perform the test and exit CPT. See 'Completing the plan - Day 0' below.

After the daily meeting on Day 1, the plan will be finalised and it is necessary to press the 'Run CPT' button in CPT. See 'Completing the plan - Day 1' below.

Completing the plan - Day 0

Running Test CPT generates three files:

These files need to be moved to the ~/cmdpln/latest directory, but first the files from the previous day need to moved out of this directory. This is done by executing the following commands:

[**ENTER COMMANDS HERE**]

Now move the three files into ~/cmdpln/latest:

[**ENTER COMMANDS HERE**]

The names of the ORL and DR files now need to be modified.

Firstly, ensure that the dates in the filename correspond to the upload date (i.e., Day 1) - usually the ORL file date needs to be changed, but not the DR file.

The name of the DR file is of the form "dr_EIS_yyyymmddpppp.txt" where yyyymmdd is the date of the upload, and pppp is the pass number of the OP/OG upload. Go to the Hinode daily events webpage to get the pass number. Make sure you are checking the page for Day 1.

The orl filename is of the form "EIS_yyyymmddpppp.orl" where again pppp needs to be modified to the pass number of the OP/OG upload (same as the DR file).

Editing the ORL file

The ORL file needs to be hand-edited in two places.

At the top of the file you should see two lines of the form:

/*Stop EIS observation, load OBSTBL, dump OBSTBL*/
START:2007/05/22.08:48:00 { SEQ:EIS_LOAD_OBSTBL_REAL ;}

The 2nd line needs to be commented out by placing "/*" in front of it.

Scrolling down the file you will see the following lines:

  NP_C.:"*********************************";
  NP_C.:"EIS START OBSTBL LOAD";
  NP_C.:"*********************************";

Directly below these lines you need to add the following two lines:

  CMD:EIS_MODE_MANU;
  C.:"Confirm EIS_MODE_MANU before upload";

Checking the data rate

Check the EIS data rate for the plan by doing:

> sswidl
IDL> dr_tlmlmt_plan

A widget will pop up and you should click the EIS button and hit Run. You will see a "sawtooth" plot that shows the EIS data accumulating and being dumped at each pass. The key thing is to ensure that the plot never goes above the red line. If it does you will have to revise the plan to reduce the rate at which the data accumulates. Normally this will only be a problem if you are running high data rate studies. 

Finishing off

The next part of the planning on Day 0 requires you to log on to the chief planner's account and run some checks. Remaining in the ~/latest directory do:

> ISACS

which logs you on to the chief planner account. Then do:

> sh tool/coorlchk.sh
> sh tool/coplnchk.sh

for the latter, you will be asked questions to which you should reply 'y' to all. If there are any problems, contact one of the Davids.

Exit from the chief planner account.

Your last task of the day is to send the EIS summary plan file to the following e-mail addresses:

eis_co@solar.isas.jaxa.jp
sot_co@solar.isas.jaxa.jp
xrt_co@solar.isas.jaxa.jp
cds.planner@gmail.com
trace_planner@cheyenne.nascom.nasa.gov

Make sure to put "eis_co:", "sot_co:" and "xrt_co:" in the subject line otherwise the e-mail will not go to these addresses because of their spam filters.

A short description of what's being observed and at what times should be added to the message.

Your Day 0 work is now complete!

Completing the plan - Day 1

After the daily planning meeting on Day 1 you need to run CPT properly. The steps are almost the same as above, but there are some important differences.

Firstly, you need to start up eis_mk_plan. If there were any changes required from the daily meeting, then perform these now.

Now start up CPT and hit the 'Test CPT' (after inputting the usual CPT info). If it runs successfully then hit the 'Run CPT' button.

In addition to the ORL, DR and plan summary files described earlier, a fourth file will be generated: the Hex file (.hex).

If there were no changes to the plan, then you have to move the Hex and ORL files over to ~/cmdpln/latest. This can be done by just cutting-and-pasting the following lines into your linux session:

cp `ls -t ~/EIS_CPT_output/orl/EIS_????????????.orl           | head -1` ~/cmdpln/latest
cp `ls -t ~/EIS_CPT_output/obstbl/EIS_OBSTBL_????????????.hex | head -1` ~/cmdpln/latest

if the plan has been modified then please also copy over the DR and plan summary files.

The ORL and DR files need to be renamed as done on Day 0.

The Hex file also needs to be renamed. The format of the filename is EIS_OBSTBL_yyyymmddpppp.hex". Make sure the date matches the upload date (Day 1). pppp is the pass number of the EIS table upload (NOT the pass number of the OP/OG upload). Make sure the pass number is different to those of the DR and ORL files.

The ORL needs to be hand-edited again. This time, however, you only have to do the second edit, i.e., after the lines:

  NP_C.:"*********************************";
  NP_C.:"EIS START OBSTBL LOAD";
  NP_C.:"*********************************";

add the following two lines.

  CMD:EIS_MODE_MANU;
  C.:"Confirm EIS_MODE_MANU before upload";

The data rate file does not need to be checked again unless there were major changes to the plan.

You now need to load up the new files onto the Chief Planner machine.

> ISACS

which logs you on to the chief planner account. Then do:

> sh tool/coorlchk.sh
> sh tool/pdlchk.sh

Note that the second script is different to the one you ran on Day 0!!  You will be asked to confirm the date for which pdlchk.sh is being run. It should be the day of the upload.

Once this has run successfully, let the Chief Planner know that you've finished.

This completes the planning for the plan period Day 1 to Day 2. You should now start preparing the next day's plan.

Communicating with the SOHO/CDS planner

Apart from the observing period Mon 11 - 24 UT, the EIS plan is always prepared in advance of the SOHO/CDS plan. There is often flexibility in what studies CDS runs each day and so, simply by sending some details about the EIS target, it will be possible to obtain simultaneous observations with CDS.

Experienced CDS planners may be able to suggest particular CDS studies that they want run when they are planning for EIS. Otherwise, some basic information can help the CDS planner decide what to run. E.g., one might send the following information:

12:00   Sit-and-stare on AR 10939
18:00   Fast rasters on AR 10939
24:00   Sit-and-stare on AR 10939
06:00   Quiet Sun spectral atlas, Sun centre

CDS could run rasters while EIS is doing sit-and-stare to help provide context information in this example.

EIS plans should be sent by e-mail to the address: cdsplanner@gmail.com.