WWW Interface

Adding/Modifing a Solver





Adding/Modifying a Solver

Two steps are required to add a new solver to the server:

1. You must first make the server aware of your solver by "registering" your solver with the server. All you need to do is fill out the submission form as per the "Detailed Instruction" given below.

2. You must then start up a communications daemon (comms-daemons) on every workstation you intend to run your solver on. The communications daemon is responsible for: a) automatically retrieving the user's data, b) calling your solver, and c) returning the solver's results to the user.

Once you complete step #1 you will be presented with instructions for completing step #2. For a quick start, you can just submit an empty form and refer to the documentation below as needed. If you are using the WWW interface, just scroll down to the bottom of this form and click "Submit." For the Submission Tool, just click "Submit" on the submission form, and for the e-mail interface just mail in the empty template included at the bottom of this file. The registration will not be complete until you have provided all of the necessary information.

Detailed Instructions on Registering Your Solver

1. Solver Type: Specify the type of solver. Leaving this entry blank will return to you a complete listing of types to choose from.

Solver Type :


2. Solver Identifier: This identifier will be used by the server server to uniquely identify your solver.

Solver Identifier:


3. Solver Name: This is the name of your solver.

Solver Name :


4. Solver Password: Enter a password to prevent others from modifying your registration. Note: this password is not protected, so don't use your real account password.

Solver Password:


5. Contact Person (e-mail): e-mail address of person to notify when problems with the solver occur.

Contact Person (e-mail):


6. Workstations: Enter the the workstations your solver will execute on. For example: 

      liberty.mcs.anl.gov
      merlin.mcs.anl.gov
      fate.mcs.anl.gov

Workstations (one per line):


7. Token Configuration: token configuration serves two purposes:

a. It tells the server what data you are expecting from the user, and what files to place this data in.

b. It tells the server how to create your submission tool and web interfaces, which support text entries, file entries, check- buttons and radiobuttons.

The following example token configuration file demonstrates some the various types of of entries. In fact, this token configuration file is the exact file used by the "Adding/Modifying a Solver" solver: 

       Solver Type::TYPE:NULL:TYPE
       Solver Identifier::SOLVER:NULL:TOKEN
       Solver Name::TITLE:NULL:TITLE
       Solver Password::PASSWORD:NULL:PASSWORD
       Contact Person (e-mail)::CONTACT:NULL:CONTACT
       Workstations (one per line):TEXT:BEGIN.STATIONS:END.STATIONS:STATIONS
       Token Configuration::BEGIN.CONFIG:END.CONFIG:config
       E-mail Help::BEGIN.HELP1:END.HELP1:help
       Submission Tool Help::BEGIN.HELP2:END.HELP2:socket-help
       WWW Help::BEGIN.HELP3:END.HELP3:explain
       WWW Samples::BEGIN.TRIAL:END.TRIAL:trial_config
       WWW Abstract::BEGIN.ABSTRACT:END.ABSTRACT:abstract
       WWW About URL::ABOUT:NULL:about.url
Note that "Adding/Modifying a Solver" is just like any other solver as far as the server is concerned. In other words, it accepts data via files and produces some kind of output for the user. Solvers need to tell the server what data they are expecting, and what files to place this data into. Further, all data is delimited by one or more tokens. If the data occupies a single line, then only one token is necessary. If it occupies multiple lines, then two tokens are necessary. Each line in the token configuration file takes the following form: 
       title:default value:begin token:end token:filename
Field 1 is used to specify a name for the data. Note that only the GUI interfaces display this name (i.e., WWW, Submission Tool).

Field 2 is used to present to the user a default value. Note again that only GUI users are presented with this default.

Field 5 specifies the filename that the datum should be saved in. Your solver will be expected to read in the data from this file.

Fields 3 & 4 are used to delimit the data. This is how the server parses incoming jobs, placing each datum in the appropriate file. If the data is single-line data (like a variable), then you only need one token to delimit it. For example, "Contact Person" only requires one line and thus uses the only the single token "CONTACT." An email user would then specify "Contact Person" like this: 

       contact = somebody@someplace
If you are a GUI user then you do not need to worry about tokens at all. Instead, the GUI will generate a single line entry for you to type "Contact Person" into. Also supported for GUI users are checkbuttons and radiobuttons (described shortly).

Now suppose that your data is multi-line. In this case you will need two tokens to delimit it: one for the beginning, and one for the end. For example, email users will provide their token configuration data to the "Adding/Modifying a Solver" solver like this: 

       BEGIN.CONFIG
         
       END.CONFIG
But GUI users will be presented with either a "Browse" button to upload a file containing the token configuration data. By default the GUI interfaces will generate the "Browse" feature for multi-line text. Also supported are text-entries where the user simply types in the data.

To activate one of checkbutton, radiobutton, or text-entry, you must specify the desired widget in field 2, just like these examples: 

       Function Type:RADIO.f.fg.ps:fcn.info:null:fcn.info 
       Gradient Only:BINARY-ON:gradient:null:gradient
       Comments:TEXT:begin.comment:end.comment:comments
Note: note that "RADIO," "BINARY-ON," "BINARY-OFF," and "TEXT" are all case-sensitive.

The first datum "Function Type" presents to GUI users a set of radio buttons labeled "f" "fg" and "ps". "f" is the default because it was listed first. Note that while a GUI user simply clicks the appropriate button, an email user would specify the selection like this example: 

       fcn.info = fg
The second datum "Gradient Only" presents a checkbutton (on/off). If the default should be ON use "BINARY-ON" else use "BINARY_OFF." An email user would specify this option simply be including the token in the email submission on a line by itself: 
       gradient
The third datum "Comments" presents a text entry to GUI users that can be used to directly type in the data, just like the "Workstations" entry for "Adding/Modifying a Solver." E-mail users will have to use two tokens however: 
       begin.comments
       
       end.comments

Token Configuration(local file):


8. Usage Restrictions: You can limit the number jobs that are sent by a certain user or group of users on an hourly, daily, or monthly basis. You need only provide a "usage restriction" file where each line takes the following form: 
    <users> <hour|day|month> <limit>
Here are a few examples: 
    #max                hour  20 
    #max_any_one_user   day   30
    #max_any_one_domain month 100
    /smith@net.com/     hour  3 
    /cs.uiuc.edu/       day   40
Any valid perl regular expression can be used to specify the user, or you can just usr the keywords #max, #max_any_one_user, or #max_any_one_domain. #max limits the cumulative number of jobs, #max_any_one_user limits the number of jobs sent by any one user, and #max_any_one_domain limits the number of jobs sent by any one domain. A regular expression is only needed if you want to limit the jobs sent by a particular user, group of users, or domain.

Usage Restrictions(local file):


9. E-mail Help: This help file should describe how to submit problems to your solver via e-mail.

E-mail Help(local file):


10. Submission Tool Help: This help file should describe how to submit problems to your solver via the Submission Tool.

Submission Tool Help(local file):


11. WWW Help: This help file should describe how to submit problems to your solver via the Web interface. In between each entry of your form, you should provide some text describing what the entry is for. You delimit this text with the token <NEXT ENTRY>. For example: 
      <description of first entry goes here without brackets>
      <NEXT ENTRY>
      <description of second entry goes here without brackets>
      <NEXT ENTRY>
      <description of third entry goes here without brackets>
      <NEXT ENTRY>
      ...
      <NEXT ENTRY>
      <description of nth entry goes here without brackets>

WWW Help(local file):


12. WWW Abstract: This HTML text will be placed on your solver web page. This should give only a brief description of your solver.

WWW Samples(local file):


13. WWW Samples: Used to specify a set of sample submissions. The file takes the following form: 
      <HTML TEXT>
      <URL of example e-mail style submission>
      <HTML TEXT>
      <URL of example e-mail style submission>
      ...
From this file, we will generate radio buttons that will allow the user to submit one of your example problems. Note: you must create the actual form that will be sent to the server. Once this form is created, you must place it in a Web readable area and give us the URL.

Here's an example trial-run file: 

      Click here to see example 1:
      http://www.mcs.anl.gov/home/otc/Server/lp/example1
      Click here to see example 2:
      http://www.mcs.anl.gov/home/otc/Server/lp/example2
Again, each of these URL's are maintained by you, and contain an example e-mail submission to your solver.

If you plan to have many trial run problems, you may consider using a table of problems. You need to specify the number of columns n, provide us with n columns titles, and then list your problems as n-tuples (problem name, url, url, ..., url). Look at the following example: 

      <COLUMNS 4>
      Problem Name
      Method 1
      Method 2
      Method 3
      Problem 1
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/a
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/b
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/c
      Problem 2
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/d
      NULL
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/f
      Problem 3
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/g
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/h
      http://www.mcs.anl.gov/home/otc/Server/lp/examples/i
This will generate a table of radio buttons. "NULL" URL entries will generate a blanked section of the table.

WWW Abstract(local file):


14. WWW About URL: The URL of your solver's homepage.

WWW About URL:


e-mail address:


[Testneos Server]