;---------------------------------------------------------------------------
; Document name: XTKI_SIM.HLP
; Created by:    Liyun Wang, NASA/GSFC, October 9, 1996
;
; Last Modified: Tue Jun  1 21:58:27 1999 (GERMEROTT@linsu1.mpae.gwdg.de)
;---------------------------------------------------------------------------
;

!Remarks

 ! Moving MC2 (Azimuth Mechanism) will cause an ERROR !

!Default Settings

		      Default Settings

When  starting the Simulator, the following value are set as
default:

 Detector       : B
 TM-Rate       : 10.5 kb/s
 Pointing        : 0 0 (Sun center) *
 Slit                : 2 (1 x 300 arcsec)
 Sun radius    : 985.8 arcsec
 Ram Disk      : No Data
 compression: 5
 High Volt.     : On and at -3100 V
 Sim Mode     : Non-interactive (see Simulation Mode)
 Mechanisms : all initialized and on default Pos.
                       (see Global Parameters in OPG or use
                       "/global" CMD in Simulator)

 *if UDP-Standard header is available and the pointing is is
  set in the fields DEF_Y and DEF_Z then this values are taken
  as default pointing. (see UDP Standard header)

!Overview

		   SUMER Simulation Tool

This  SUMER  Simulation  Tool  is  designed  as  the  widget
interface to the SUMER technical and  photometric  simulator
and to SUMER command generator. It can be used  to  simulate
SUMER user defined programs (UDP) written in  SUMER  control
language (SCL). Simulated UDPs can  be  exported  for  later
use.

To  do  any operation, you need to load in an UDP (in either
SCL code or UDP file).

 When you move the mouse cursor over an active widget field,
 you will get an interactive instruction in "Interactive
 Instruction" window on what that widget field does.

!UDP Standard Header

		    UDP Standard Header

The UDP Standard Header is defined to include information in
the  UDP  which  allows an automatic information grabbing in
the MAKE-Study Procedure and  the  simulation  to  fill  the
corresponding  required  fields  automatically.  In  case of
changes the header fields  are  updated  during  MAKE  STUDY
procedure in ST_SUMER. The header is not nessecary  required
but makes creating a Study easier.

Definition:

 The header starts with

 /*+++

 and ends with

 ---*/
 beginning in the first row

 vaild tag names start with ! in first row:

 !NAME
       name of UDP  (max one line) 
 !TITLE
       title of UDP (max one line) 
 !PURPOSE
       purpose of UDP (1 to 4 lines)
 !CATEGORY
       category of UDP ([OP,CLB,TEST]) 
 !DEF_Y
       default Y pointing before start of UDP in arcsec
 !DEF_Z
       default Z pointing before start of UDP in arcsec
 !TIME_SAVED
       last save time (automatically added by ST_SUMER)

 Example for valid header:

 /*+++
 !NAME
      LAM_VERIFY
 !TITLE
      LAMBDA VERIFICATION
 !PURPOSE
      Verify Simulator Lambda Function
 !CATEGORY
      OP
 !DEF_Y
      0.00
 !DEF_Z
      1000
 !TIME_SAVED
       8-Nov-1996 22:56:12
 ---*/

!Messages

		     Simulator Messages

The Simulator messages are classified in three categories:

ERROR        % E %
WARNING      % W %
INFORMATION  % I %

ERROR  -  a  serious Problem occured during simulation which
makes the running of  this  UDP  in  SUMER  impossible.  The
simulation aborts.

WARNING - a condition ocurred during simulation which has to
be checked by the user because the outcome of the UDP may be
unpredictable or not what the user expected. 

INFORMATION - self explanatory

!File

!!Load UDP

		       Load UDP

Uncompiled  UDPs  (*.SCL)  can  be  loaded into XTKI via the
"Load UDP" option of the pull-down menu  button  "File".   A
widget program will appear allowing one to select a SCL file
from  the  disk.  This  SCL file is compiled and if no ERROR
occured during  compilation  the  OBJ-Code  is  loaded.  The
actual loaded UDP is named in the "UDP:" field

In Non-interactive Mode the simulation starts automatically.

!!Add other UDP

		       Add other UDP

Once  a  UDP is simulated it is possible to simulate another
UDP inside the same Study to check effects from previews UDP
to the next. Loading a second or  third  UDP  use  the  "Add
other  UDP"  option  of the pull-down menu button "File".  A
widget program will appear allowing one to select a OBJ file
from the disk.
 
!!Export UDP

			 Export UDP

If  you  are running XTKI on non-operations machine, you can
still simulate any UDP written in SCL; the simulated UDP can
be saved into a special format called MMD  for  future  use.
This  is  what we call exporting. To export a simulated UDP,
press the "Export UDP" button under "File", a file with  the
same name as the SCL file but  a  different  extension  .MMD
will  be  created.  This is the UDP file you can take to the
SUMER   operations   machine  (SUMOP1)  and  have  your  UDP
registered with the SUMER database system.

Note:  This  option is not available if you are not inside a
Study. When simulating a UDP in  Non-Interactive  Mode  this
exporting is automatically done.


!!Compile UDP

			Compile UDP

XTKI  needs  the SCL-Code for an UDP simulation.  If you are
running  XTKI, you can produce if nessecary OBJ-Code via the
"Compile UDP" button under the "File" menu button.  A widget
program will appear allowing one to select a SCL  file  from
the  disk.   This  button is an option to compile a UDP from
running XTKI, it has no effect on simulation.

Note: This Option is only available on VMS-SYSTEMS

!!SUBMIT

			   SUBMIT

The  "SUBMIT"  button  under the menue button "File" enables
the user to start a simulation job in a BATCH QUEUE.   After
being selected, a SCL file is compiled and sent to the batch
queue.  The  simulation  is  done  independently  from  XTKI
program.  The user will be notified through a  Mail  message
after the simulation is done. In any case the user can check
the  simulation via the batch log file.  The name convention
of the log file is:

  SYS$LOGIN:udp-name_BATCH.LOG

Note: This Option is only available on VMS-SYSTEMS

!!Quit

			    Quit

Leaving XTKI is initiated by pushing the "Quit" button under
the "File" menu button.

!Simulation Mode

The  Mode selection has to be done before loading a UDP. The
actual modesetting is indicated  as  not  available  in  the
pull-down menu button "Simulation Mode".

Note: The default mode is Noninteractve

!!Interactive

			Interactive

In  Interactive  Mode  the  user  can effect the  simulation
interactively.  The control of output (debug), Detector  and
TM-Rate is available.  Most of  the  SUMER  -  Commands  are
interactive available to test effect to the UDP  before  ore
after running simulation.  The simulation  is  initiated  by
the CMD "/sim" (default in CMD-Line) The  CMD  "/cont"  ends
the interactive Mode. This CMD is as default in the CMD-Line
after simulation.

Note: The Interactive Control-Area appears after a valid UDP
is loaded

!!Noninteractive

		       Noninteractive

In Noninteractive Mode there is no posibility to control the
simulation.   After   loading   a   UDP   it   is  simulated
automatically  and  the  results  are presented. If no Error
occurs during  Simulation  the  results  are  saved  in  the
UDP-Export-File.

!Display Info

!!SCL File

		      Display SCL Code

Once a UDP is loaded into XTKI the SCL Code of the  UDP  can
be displayed by selecting the "SCL File"  button  under  the
"Display Info" menu button. This option is only available if
a valid SCL-File (UDPNAME.SCL) is found.

!!Log File

		      Display LOG File

After  simulation  the  LOG-File  including  the  simulation
results is available and can be displayed via the "Log File"
button under the "Display Info" menu button.

!!TRC File

		      Display Trace File

After  simulation  the  TRC-File  including  the  simulation
Commads  and  Messages is available and can be displayed via
the "TRC File" button under the "Display Info" menu button.

!!Tok File

		      Display Token Code

Once a UDP is loaded into XTKI the Token Code of the UDP can
be  displayed  by  selecting the "Tok File" button under the
"Display Info" menu button. This option is only available if
a valid Token-File (UDPNAME.tok) is found.


!!UDP Structure

		   Display UDP Structure

Once  an  UDP  written  in  SCL  has been properly simulated
without  any  error, all information about the UDP itself is
saved into an  IDL  structure  which  can  be  displayed  by
selecting "UDP Structure" under the  pull-down  menu  button
"Display  Info";  this  will  bring up a widget program that
display the contents of the UDP  structure  in  a  pull-down
menu format.

!!Tech result

	     Display the technical result plots

Once  a  simulation  is done or the interactive mode is left
the  simulation results are plotted to the TECH-Screen. This
Screen can be shown by  pushing  the  "Tech  result"  button
under the "Display Info" menu button.

In this screen the movements of the six important mechanisms
is shown as plot.

!!Phot result

	      Display the photometric results

Once a simulation is done or the interactive  mode  is  left
the    photometrical    results    are    plotted   to   the
Photometric-Screen. This Screen can be shown by pushing  the
"Phot result" button under the "Display Info" menu button.

The display of the photometric results contains two windows,
the  left  window  shows the the spectral range for SUMER in
the 1st order (quiet sun).  The part of the  spectrum  which
is  currently  visible  for  the choosen detector is marked.
The right window shows the marked part of  the  spectrum  in
detail.  Diffrent colors in this window  mark  the  diffrent
sensitive regions of the SUMER detector.

!!Sun result

	       Display the Scan Areas on Sun

During simulation it is possible to view the movement of the
Telescope  mechanisms  on  sun.  This Figure is shown in the
Sun-Screen  available  via the "Sun result" button under the
"Display Info" menu button.

!!Messages

		Display Simulation Messages

During  the  simulation  the  Messages  of the simulator are
printed on the Message-Screen. This Screen is  available  by
pushing the "Messsage" button under the "Display Info"  menu
button.

!Simulation Control

All  simulation  control  CMDs  are case sensitive. Required
Parameters are separeted by spaces or  comma  the  Simulator
Parser accepts both.

!!?

			     ?

Help  on  a  specified  CMD pattern. ? * lists all available
CMDs.

Syntax: ? X
Example: ? spec

  This CMD lists all CMDs where "spec" is inside e.g.
  spectrohelio1 or ref_spec

!!/help

			   /help

This  CMD  prints  a short Simulator control CMD overview on
screen 

!!begin

			   begin

This  Cmd  Marks  the  start  of  Study.   "begin"  is  done
automatically when a UDP is loaded.  Beeing  in  interactive
mode  after  "/cont",  this CMD must be the first CMD before
any other CMD is executable.

"begin" is automatically executed when loading a new UDP

Syntax: begin

!!end

			    end

This Cmd Marks the end of Study and is done autmaticaly with
the "/cont" CMD. This CMD initiates computing the results of
simulation. 

Syntax: end

Note: This CMD does not include displaying the results


!!search_p

			  search_p

The  CMD  "search_p" processes the Parameter search inside a
loaded UDP. The Parameter search  looks  for  the  Functions
ParamR, ParamS and ParamU inside a UDP. If such  a  function
is  found,  the simulator looks for a file with the UDP-name
and  extension  ".DAT" with the required Parameters in ASCII
Format.  If no such File is found, an error is indicated and
no simulation will be done.

Note: UDPs with Parameters (ParamX) are no longer supported

Syntax: search_p

!!/cont

			   /cont

The "/cont" CMD indicates the end of the Study using the end
CMD but including the Display processing.

Syntax: /cont

!!/det

			    /det

Choose Detector (A or B is accepted, invalid Val is  set  to
A). The same CMD is executed when phushing the Radio buttons
"Det A" and "Det B" in the interactive Control Panel.

Syntax: /det X 
Example: /det A

         This CMD switches to Detector A for simulation

!!/save

			   /save

This  CMD saves the simulation result structure for the last
simulated  UDP.   This  CMD  is  executed  when  pushing the
"Export UDP" under the "File" button menu. /save can only be
executed  if no error occured during simulation and the only
SCL-CMD before starting the simulation was point.

Syntax: /save

!!/sim

			    /sim

The CMD /sim initiates the simulation of the  UDP  displayed
in the field "UDP:". This CMD is as default  in  the  Comand
field  after  a  UDP  is  loaded. /sim takes nearly the same
effect like "start_UDP" in real.

Syntax: /sim

!!/sunrad

			  /sunrad

The CMD /sunrad offers the ability of setting the  Sunradius
to  the actual value. The values have to be in the the range
of 953.4 to 985.8 arcsec. The default value at program start
is  985.8  arcsec.  An  invalid  Value  is  set   to   985.8
arcsec. This value is used for  internal  calculation  which
checks if an observation made for the  corona  is  still  in
corona and not on solar disk.
                       
Syntax: /sunrad X       (953.4 <= X <= 985.8 arcsec)
Example: /sunrad 960.4

   This CMD set the value for the sun radius to 960.4 arcsec

!!/tm

			    /tm

The CMD /tm switch to the choosen telemetry  rate  given  in
the parameter. Accepted parameter values  are  'L'  for  low
rate (10.5 kb/s) and 'H' for high rate (21 kb/s). An invalid
value is set to low rate.  This CMD is executed when pushing
the "TM Rate" button in the interactive Control panel.

Syntax: /tm X
Example: /tm 'h'

    This CMD set the telemetry rate to 21 kb/s

!Output Control

The Simulator output can be controlled by  setting  diffrent
Output Flags.   These  Flags  are  set  or  cleared  by  the
following CMDs.

Default setting for Output after begin:

 Flags:   FILE SCREEN SCL NOTOKEN WARNINGS ERRORS


!!/debug

			   /debug

The CMD /debug switches all Simulator output to screen.  All
Messages are enabled. In this mode all internal functions of
a UDP are displayed.  For more knowledge about  TOKEN  refer
SUMER OP-Guide section 7.

 Flags:   NOFILE SCREEN SCL TOKEN WARNINGS ERRORS

Syntax: /debug

!!/[no]file 

		       /file /nofile

These  two  CMDs control whether the enabled Messages should
be recorded in the Trace File or not.

Syntax: /[no]file

!!/getflag

			  /getflag

The "/getflag" CMD shows the current Output Flag settings

Syntax: /getflag


!!/[no]log

			  /[no]log

The CMD "/[no]log switches the Output Flag to the following
state:

  /log :  FILE NOSCREEN SCL NOTOKEN NOWARNINGS ERRORS
/nolog :  NOFILE SCREEN NOSCL NOTOKEN NOWARNINGS ERRORS

Syntax: /[no]log

!!/[no]scl
			  /[no]scl

The  "/[no]scl" CMD switches the output of all SCL-Functions
ON or OFF

Syntax: /[no]scl
 
!!/[no]screen

			/[no]screen

The  "/[no]screen" CMD switches the output of all enabled
messages to screen ON or OFF

Syntax: /[no]screen

!!/[no]token

			 /[no]token

The  "/[no]token"  CMD  switches  the output of all internal
used  TOKEN  ON  or  OFF.  This  could be helpful in case of
debugging UDPs (see debug).

Syntax: /[no]token

!!/trace

 see /screen

!State Information

!!/getflag

			  /getflag

The "/getflag" CMD shows the actual setting for  the  output
flags.

Syntax: /getflag

!!/getmax

			  /getmax

The "/getmax" CMD shows the actual setting for  the  maximum
real time of simulation

Syntax: /getmax


!!/global

			  /global

The "/global" CMD displays the actual simulated state of the
SUMER global parameters.

Syntax: /global X Y        (X - first parameter to display,
                            Y - last parameter to display)

Example: /global 1 7

   This CMD shows the global parameters 1 to 7

!!/lam

			    /lam

The "/lam" CMD displays the actual  simulation  settings  of
the main and alternate line register of SUMER.

Syntax: /lam

!!/point

			   /point

The "/point" CMD displays the actual simulation settings  of
the the pointing coordinates of SUMER.

Syntax: /point

!!/timinf

			    /[no]timinf

The "/timinf" CMD enables [disables] the printing of the time
in front of each CMD relative to the start of the UDP.

Syntax: /timinf

!!/repoint

                            /repoint

The "/repoint" CMD sets the values for a possible repoint CMD
in the UDP and initializes the contY and contZ functions at a
specified time in seconds relative to the start of the UDP.
One can add as many 'repoint triggers' as you want,they are
added and automaticly sorted by time.

Syntax: /repoint Ypos Zpos time

Example: /repoint 17000 16000 3000

   This CMD set one repoint trigger after 3000 seconds for
   the coordinates Y=17000 [1/16 arcsec] and Z=16000 [1/16 arcsec]

See also /showtrig

!!/showtrig

                           /showtrig

The "/showtrig" CMD displays a list of set triggers set by the
/repoint CMD

Syntax: /showtrig

!!/setimgmax

                           /[no]setimgmax

The "/setimgmax" CMD sets the Value returned by the GetImageMax
function. By default this value is calculated from the spectrum
inside the simulator, but since this is Solar Disk spectrum it
might be nessecary to check out other simulation results for
off limb or other purpose. Therefor one can change the return
value for GetImageMax with this function.

Syntax: /setimgmax val

Example: /setimgmax 400

   This CMD set the return value of GetImageMax to 400
  
!!/ppar

!PRINT

Pushing the PRINT button creats a postscript file of the detailed
spectrum window. The filename is "DTKI_pix_lam.PS" where pix  and
lam are the reference pixel and the wavelength.

