Parameter Editor Help

The parameter editor is a graphical user interface (GUI) that helps editing parameter files of scientific codes. It behaves like a normal editor: one can open a new file or an existing file (the name is arbitrary, but we will use the name PARAMFILE in this manual). When an existing file is opened, the original file is copied into PARAMFILE~ (similarly to the emacs editor). If the editor is exited or a new file is opened without saving the edited file, then the last state of the file is saved into PARAMFILE.bak. The GUI consists of three frames:

top frame with various buttons and select menus,
left frame showing the parameter file,
right frame showing extra information, such as manuals, clipboard, files to be inserted, or list of errors.

The parameter editor GUI can be customized with the configuration file ParamEditor.conf.

Top Frame

By default the top frame shows the name of the edited parameter file in the middle and the following buttons:

: check the parameter file for errors. First all previous errors (if any) are removed from the left frame. Next a list of errors will be displayed in the right frame, as well as where they occur in the left frame.
: save the edited parameter file.
: save the edited parameter file under a different name. The new name will be entered into a text box in the top frame.
: re-read the input file. Changes after the last save will be lost except for a safety save of the current content into PARAMFILE.bak
: open another input file. Changes after the last save will be lost except for a safety save of the current content into PARAMFILE.bak
: delete the content of the clipboard so that it is not saved into the parameter file after the #END command.
: save file and exit from the editor.
: exit from the editor. Changes after the last save will be lost except for a safety save of the current content into PARAMFILE.bak
: show this help message.

The following menus and options are shown:

View: The view menu determines how the parameter file is displayed in the left frame, and it also determines what and where can be inserted from the insert menu.
- ALL: show everything.
- ALL ITEMS: show everything but all command/comments are minimized.
- ALL SECTIONS: show all sessions with minimized sections.
- ALL SESSIONS: show all sessions in minimized format.
- Session X: show session X maximized, others minimized.
- Session X/Y: show section Y from session X maximized, all others minimized.
If any of the ALL* options is selected then full sessions can be inserted only. If a session is selected then sections can be inserted into any session. If a section is selected then comments and commands can be inserted into any of the sections of the selected type.
Insert: Inserting an object into the parameter file consist of up to four steps: select the appropriate view from the view menu, select an object from the insert menu, select a file in case a file is to be inserted, and finally insert the object by clicking on any of the insert buttons in the left frame.
The content of the insert list depends on the view list. When the view list is set to one of the ALL* options, the insert list contains NEW SESSION, FILE and PASTE SESSION if the clipboard contains a session. It the view list is set to a session, the insert list contains FILE, Section CON, sections for all components with a non-empty version, and PASTE SECTION if the clipboard contains a section. Finally, when the view list is set to a section, the insert list contains FILE, COMMENT, all the commands appropriate for the selected section, and PASTE COMMAND/COMMENT in case the clipboard contains a comment or a command. The commands are either listed by groups (as determined by the command groups in the PARAM.XML file) or alphabetically. The choice can be made by clicking on the check box abc.

Left Frame

The left frame shows the parameter file. Most of the functionality is shown if the mouse if hovering over any link or button. The parameter file consists of one or more sessions. The sessions are numbered from 1 to the number of sessions, but they can also be named descriptively. Click on the blue session marker to input the session name, or click on the session name to modify it. The code first runs with the parameters of the first session, then upon completion it continues with the parameter modifications of the second session, etc. A session consists of one or more sections. A section contains input parameters for the control module (CON), or one of the components (e.g. IE or GM) allowed by the current configuration of the framework. Each session contains one or more items. An item can be one of the following:

#COMMAND: text that starts with '#' but not '#USERINPUT' followed by zero or more non-empty lines containing the parameters of the command.
#USERINPUT segment: text that starts with '#USERINPUT(BEGIN)' and ends with '#USERINPUT(END)'.
ERROR: text starting with the string 'ERROR' or 'WARNING'.
COMMENT: any other text

All items (except for errors) can be edited by clicking on the first line of the item. The edited item opens a text area that can be modified and saved with the SAVE button.

The sessions, sections and items can be manipulated with the following buttons:

: remove object. The removed object is moved to the clipboard in the right frame and the insert list is set to the PASTE option.
: copy object (except for errors). The object is copied to the clipboard in the right frame and the insert list is set to the PASTE option.
: insert object defined in the insert menu. If the selected option in the insert menu is FILE, or PASTE or a command, then the object to be inserted is shown in the right frame.
or : minimize object (except for errors or objects consisting of a single line) to a single line. The button is placed to the last line of sessions, sections and user-input segments.
: maximize object, ie. show all lines of the object.

Right Frame

The right frame contains one of the following:

Manual: description of a command to be inserted or edited.
File: the content of a file that can be inserted.
Clipboard: a removed or copied object than can be pasted.
Errors: list of errors produced by the button.

Customization with ParamEditor.conf

The GUI as well as the micro web-server running the GUI can be customized by creating a ParamEditor.conf file in the user's home directory. When the GUI is started with the share/Scripts/ParamEditor.pl script, the script starts a micro web-server and reads the ParamEditor.conf file for configuration settings. One can set the default browser and/or the default name of the edited parameter file. For example

$browser   = "/opt/kde3/bin/konqueror";
$paramfile = "run_test/PARAM.in";

Note that the default browser cannot be set under Mac OSX. For more detail type

share/Scripts/ParamEditor.pl -h

The GUI itself can be customized by setting variables in the ParamEditor.conf file. Type

grep '^our' share/Scripts/ParamConvert.pl

to see the variables that can be modified. Currently the following variables can be modified:

$RedoFrames       = 0         ; # rewrite index.php (jump.html)
$DoSafariJumpFix  = 0         ; # work around the Safari bug
$FrameHeights     ='15%,85%'  ; # heights of top frame and lower frames
$FrameWidths      ='60%,40%'  ; # widths of the left and right frames
$TopBgColor       ='#DDDDDD'  ; # background color for the top frame
$TopFileNameFont  ='COLOR=RED'; # font used for file name in top frame
$FileNameEditorWidth = 40     ; # width (chars) of filename input box
$TopTableWidth    ='100%'     ; # width of stuff above the line in top frame
$TopLine          ='<HR>'     ; # separator line in top frame
$RightBgColor     ='WHITE'    ; # background color for the right side frame
$LeftTableWidth   ='100%'     ; # width of table in left frame
$LeftColumn1Width =  30       ; # width of minimize/maximize button column
$LeftColumn2Width = 380       ; # width of column with command parameters
$LeftBgColor      ='#DDDDDD'  ; # background color for the left side frame
$SessionBgColor   ='#CCCCCC'  ; # background color for session markers
$SessionLine ='<HR COLOR=BLACK NOSHADE SIZE=4>';  # session separator line
$SessionEditorSize = 30       ; # size (characters) for session name input
$SectionBgColor   ='#CCCCCC'  ; # background color for section markers
$SectionLine ='<HR COLOR=GREY NOSHADE SIZE=2>';  # section separator line
$SectionColumn1Width = 8      ; # The space before the section marker
$ItemEditorBgColor='#BBEEFF'  ; # background color command/comment editor
$ItemEditorWidth  = 60        ; # width (chars) for command/comment editor
$CommandBgColor   ='#CCCCCC'  ; # background color for commands
$ParameterBgColor ='#CCCCCC'  ; # background color for command parameters
$CommentBgColor   ='#DDDDDD'  ; # background color for comments
$ErrorBgColor     ='RED'      ; # background color for errors
$UserInputBgColor ='#CCCCCC'  ; # background color for user input commands

Note the use of dollar signs at the beginning of the variables, the quotation marks around string values and the semicolons at the end of lines. The comments starting with # are optional. The customization file has to have correct Perl language syntax to work properly.

Other then changing colors and width of table columns, the configuration file can be used to work around a bug in the Safari browser. The bug causes the browser to jump to the wrong place in the left frame. Set

$DoSafariJumpFix = 1; # work around the Safari bug

in the configuration file to activate the work-around: first the browser jumps to a jump.html file that has a JavaScript that directs it to the proper part of the param.html file. As a result there is a little bit of blinking in the left frame, but still better than not seeing the selected items and scrolling all the time.

One can also change the proportions of the three frames by e.g. setting the variables

$FrameHeights = '18%,82%';   # heights of top frame and lower frames
$FrameWidths  = '50%,50%';   # widths of the left and right frames

to diffferent values. Note that the sum should be 100% in both cases.

If the frame sizes or the Safari jump fix is modified in the configuration file while the editor, set

$RedoFrames = 1;             # rewrite index.php (jump.html)

so that the changes take effect without restarting the editor. Note, however, that this setting should be removed from the configuration file once the settings are permanent.