Solo Predictor Installation and Configuration

Installation and Configuration

The following section describes the options available for configuring Solo_Predictor. For details on interfacing, scripting Solo_Predictor, see the Solo_Predictor Reference Manual.

Installation

Solo_Predictor is packaged in several different ways depending on the platform on which it is being installed. Follow the instructions on the main Solo installation page to install on the appropriate platform.

Prior to or at the first start of Solo_Predictor, the user must enter a license code to enable the software. There are two ways of providing this information:

1. Starting Solo_Predictor and provide the code on the Configuration Page. This same page allows you to change frequently modified settings. If you need to modify configuration options not included in this dialog, these must be done by manually modifying the default.xml file located in the main Solo_Predictor application folder.
2. Adding the license code to the configuration file directly.

NOTE: If Solo_Predictor is installed as administrator but run as a different user, copies of default.xml may be stored in (%userprofile%\AppData\local\VirtualStore\Program Files\EVRI\Solo_Predictor). To update default.xml either delete the copy in the VirtualStore or update the copy.

Installing a New Version (Updating)

Installing a new version of Solo_Predictor into the same location ("Destination Folder", default = "C:\Program Files\EVRI\Solo_Predictor) as the earlier version is performed just like a new install. This means that the previous version's default.xml file will be overwritten, losing any special setting which might have been present there. In this case it is a good idea to save a copy of the earlier default.xml file for use with the new Solo_Predictor. Once a copy has been saved then proceed with installing the new Solo_Predictor. When the installer wizard reaches the page "Solo_Predictor_Configuration" click on the "Cancel" button. At this stage the new Solo_Predictor files will have been installed. Now edit the copy of the earlier default.xml file to insert the new Solo_Predictor license code value. Copy this file over the newly installed Solo_Predictor's default.xml file (this will require Admin privileges to copy into C:\Program Files\...). Finally, start Solo_Predictor as usual. The new default.xml file settings will be used and Solo_Predictor will start without the Solo_Predictor_Configuration window appearing.

Starting Solo_Predictor

Solo_Predictor is typically started by one of these methods:

1. Making a direction connection using the .NET EigenvectorTools objects (see the EigenvectorTools object page for installation and configuration information)
2. Starting it manually via a start-up process or as a service (on Windows) or daemon (on Linux) (see the SoloManager page for installation and configuration information)
3. Started "on-demand" by simply executing the Solo_Predictor executable file or shortcut. For this method, note the options for stopping or restarting the server depend on the configuration of the Status Window (see below).

If starting Solo_Predictor by the third method then a status console window should appear:

If connecting to Solo_Predictor via sockets, the server's IP address depends on the local network setup. If the client is running on the same system as Solo_Predictor, then the loopback address (127.0.0.1) can be used for both client and server. The port number is configured as described below. If, however, Solo_Predictor is on a different computer than the client, the client must make a connection into the computer running Solo_Predictor. Normally this is done by IP address but most sockets provide some means for looking up an IP address based on the computer name. If dynamic IP addresses are being used, it is recommended that the Solo_Predictor computer be set up with a preference for a given IP address. However, if the IP address does get changed, the client will need to be pointed to the new address.

For more information on programming socket connections, see Appendix C: Solo_Predictor_Example_Connection_Code.

Configuration

All configuration of Solo_Predictor is accomplished through the default.xml file which is located in the program's main folder and/or through the Solo_Predictor Configuration Page. This XML file uses the Solo Settings File Format and contains a number of tags which can be edited by the user. Note that changes in this file will not be read by Solo_Predictor until the server is stopped and restarted.

The tags within the <socketserver> tag control the server settings. In each case, an options value is provided using standard XML notation:

 <optionname>value</optionname>

In addition, inside each opening tag, several attributes are set:

 <optionname class="numeric" size="[1,1]">1</optionname>

The "class" attribute should not be changed from the given value. The "size" attribute is informational only and can be omitted.

Load Settings command line flag

The user can specify a different XML file using the command line startup flag loadsettings.

 -loadsettings "filename"

This startup flag will load user settings from the XML file specified by the fully-qualified string "filename". A settings XML file can be created by using the "Save" option from the Preferences Expert or using the settings file format description. Often used with -clearsettings so that only the settings in the specified file are used.

If a file named Default.xml is present in the application folder or the top-level installation folder (usually C:/Program Files/EVRI/Solo or similar on Windows), this file will always be read before reading the file specified by the -loadsettings flag.

The following are the user-modifiable options. The expected class attribute is included in parentheses.

License Code

At the bottom of the configuration file is the licensecode tag which is empty in a new installation. Entering a code into this tag allows Solo_Predictor to start up without asking the user for the code. The license code, provided by Eigenvector Research, can be added to the file by simply entering it between the <licensecode></licensecode> tags. The next time the server is restarted, the code (if valid) will be used and Solo_Predictor will not prompt for a code. If the license code is a demonstration code and expires, or if the code is invalid, Solo_Predictor will display a dialog indicating the error when it starts up. When done, the license code tag would look like that shown below:

<licensecode>123456-3456789-12-34ab-cdef</licensecode>

Status Window and Controls Options

These options control functionality of the Solo_Predictor status window.

• controls (class="string"): Manages the display and functionality of the status window. Valid settings include:
  • none: no status window will be given and all controls are hidden.
  • status: status window is shown, but all server controls are disabled.
  • limited: status window is shown and only the "restart" control is enabled.
  • full: status window is shown and all controls (stop/start/restart/exit) are enabled.

Except when "full" settings are used, the only means to stop and/or restart the server is by using operating-system-specific process kill commands ("Program Manager" in windows, the "Activity Monitor" in OS X, and the kill command in linux or unix). Default is "status".

• max_screen_lines (class="numeric"): Defines the total number of past message lines displayed on the (on-screen) status window. Default is 20 lines.
• pulseperiod (class="numeric"): Defines the number of seconds between "pulse" messages in the status window. Default is 15 seconds.

Log File

These options control the log file and the level of detail and age of messages retained.

• log_severity (class="numeric"): Defines the minimum message "severity" which will be reported in the log file (on disk). The level must be one of the following:

0 = log all messages

1 = log all startup, shutdown, rejected connection and fatal error messages

2 = log fatal error messages only

3 = log no messages (disable logging).

The default level is 1 (one).

If the debug mode is on (see below), an additional setting is available:

-1 = log all messages including debug-mode information

• max_log_size (class="numeric"): Defines the maximum log file size (in bytes). Solo_Predictor will discard old messages to keep the log file from exceeding this size. Default is 50000 (50 Kb).
• logfile (class="string"): Gives the path and filename to use for the log file. By default, this is solo_pred.log in the user's temporary directory. The exact location of the temporary folder depends on the operating system. For example, this is usually:

Windows XP: \Documents and Settings\username\Local Settings\Temp.

Windows Vista: \Users\username\AppData\Local\Temp

• log_backups (class="numeric"): Indicates how many "backup" copies of the log file to allow to exist at any one time. If zero, then the one log file will be rolled over and messages removed. If greater than zero, the existing log file will be rolled into a backup file when it reaches max_log_size bytes. Old backup files are renumbered in increasing order (allowing up to this number of backup files) and the oldest file is deleted. For example, a value of 2 will allow two backups of the log file (each max_log_size in bytes)
• debug (class="numeric"): This tag is not normally listed in the default.xml file but can be added at any time to enable/disable the "debug" mode of Solo_Predictor. A value of 1 (one) will enable debug mode and 0 (zero) will disable it (the default). When debug mode is enabled, Solo_Predictor will display on the screen and optionally log in the log file (see log_severity above) details about each connection and action including information like timing of each step in processing, content of incoming messages, and names of requested files. This can be helpful in diagnosing issues with socket connections. Note that, because any messages being sent are logged and displayed, debug mode may significantly slow down processing if large messages are being passed in (e.g. large data files in XML format)

Server Connection Options

These options control the behavior of the socket server and the kind of connections it will accept.

• port (class="numeric"): Defines the computer port on which the socket server will respond to requests. This value should be changed with great care as some sockets are used by the operating system and other software. The default port value of 2211 is selected to minimize conflict between known port uses. Additional ports which might be of use include: 2210, 2212, and 2005. Contact Eigenvector Research for more information on valid ports.
• loopbackonly (class="numeric"): If set to 1 (one), the server will only respond to a client which is located on the same computer as the server. All external requests will be ignored. A value of 0 (zero) will respond to any IP address (see also validip option). Default is 1 (one).
• validip (class="cell"): Gives a list of valid IP addresses to which the server may respond. If empty, any IP address client is permitted to contact the server (unless the loopbackonly option is set to 1 (one)). Remember that the server is limited to a given number of clients (usually 1 (one)) and once it has been contacted by that many clients, it cannot respond to any other clients. This setting only limits the clients who can contact the server before it has imprinted on a given client.

The ip addresses must be supplied as separate items each inside a set of tags with all tags enclosed in a set of tags. For example:

 <validip class="cell">

10.0.0.1 10.0.0.2 </validip>

• privateworkspace (class="numeric"): If set to 1 (one), each client will have its own workspace to store objects and no client can access another client's objects. If set to 0 (zero), each client accesses the same workspace. A client may access and/or overwrite other client's objects. This may lead to unexpected results (if a given client expects a model to stay loaded but other clients are using the same object name and overwrite the model, for example). Default is one.
• maxclients (class="numeric"): Maximum number of clients allowed to connect into server. If 1 (one), the first client to connect to the server will be the only client allowed to connect ever. If 0 (zero), no socket connections will be allowed. If set to the numeric value inf (infinity), there will be no limit to the number of clients allowed to connect. This final setting is used when Solo_Predictor is being used as a web server, for example.

Incoming Message Format and Timeout Settings

• eomstring (class="string") End Of Message character or string. If non-empty, this character or string must be passed to indicate end of message. The same string will be appended onto any messages returned by the server. The use of an EOM string allows Solo_Predictor to function on higher-load systems or with large messages where the entire contents of the message may not be queued and delivered all at once. See Introduction to Socket Interfaces for more information. It is best to set a string which is very unique and will never show up in a common message, for example: **EndOfMessage**
• tickletimeout (class="numeric") Number of seconds of delay allowed between opening socket and getting first character. At timeout, before sending client a space character. Required to tickle some clients into responding.
• emptytimeout (class="numeric") Number of seconds of delay allowed before receiving first message from client. At timeout, throws an empty packet message.
• eomtimeout (class="numeric") Number of seconds after which no more characters received indicates an end-of-message (generally for use with POST messages and EOMSTRING messages only).

Wait-For-File Options

Wait for file options control the optional Solo_Predictor wait-for-file engine. This engine will watch a given folder for a new file (with an optional specific file type). When a new file appears, the file will be automatically loaded as the object "data" and a specific script (stored in a disk file) will be executed. This script can use a :writefile command (see Script Construction section) to store results of an analysis in an output file.

• waitforfile (class="string"): either "on" or "off" (the default). When "on", the wait-for-file functionality is enabled (although the waitfolder and waitscript must also be non-empty strings for wait-for-file to operate).
• waitfolder (class="string"): defines the folder (local or networked) in which Solo_Predictor should look for new files.
• waitfilespec (class="string"): defines the file specifications (if any) to which the wait-for-file should be limited. For example, waitfilespec = "*.spc" will only recognize .spc files appearing in the wait folder.
• waitfilemode (class="String"): either "date" (default) or "name". When waitfilemode = "date" process files in waitfolder which are newer than the most recently run file. Note that this uses files' modification date, NOT the date or time when a file is dropped into the waitfolder. This may explain why "new" files dropped into the waitfolder are not being processed. Check their modification dates. When waitfilemode = "name" process files which were not in the folder before. If there are multiple new files then they are processed in order based on their modification date, oldest first.
• waitfileimporter (class="string") : defines the file import method to use. If empty (the default value), the file extension is used to determine the import method. This option allows overriding normal import behavior if the file extension is ambiguous (e.g. "dat") or otherwise misleading.
• waitloadfile (class="string"): If "on", the contents of the file are loaded into the object named "data" in the Solo_Predictor workspace. If "off", the contents are not read and only the file name is passed (in the object named "filename")
• waitscript (class="string"): defines the file containing the script to execute when a new file is found. This option must contain the entire path to the file. Note that the indicated script should expect to find the loaded data in the object named "data" in the current workspace (see waitloadfile above) and the file name in the "filename" object. NOTE: If no wait script is defined, any imported data will be added to the DataCache which is used by the Solo_Predictor Field Monitor and can also be accessed via a datacache scripting object.
• waiterrorscript (class="string"): defines the file containing the script to execute if the file import or waitscript throws an error. This script can anticipate having the object "filename" in its workspace but should not anticipate any other objects.

Output Format Options

• default_format (class="string"): Defines the default response format. This is the output format used by the server if no format type is included in the request script. Valid types are: "xml", "plain" or "html". See Scripting Language for more information on these formats. Default is "xml".

• plaindelimiter (class="string", default = , ) Character which should be used to separate numerical values when outputting a vector in the plain text format. The comma is default (implying comma-separated-values) but can be any character (e.g. tab, semicolon). If a control-character is to be used, use regular expression notation such as "\t" or "\r" (without quotes) also accepted is hex notation, for example, use "\x20" to represent a space character:

<plaindelimiter class="string">\t</plaindelimeter>  <!-- tab character -->

• writefilefolder (class="string"): Defines the top-level folder to which the :writefile and :export commands are allowed to write. These commands can ONLY write to this folder and any sub-folders within it. An empty string for writefilefolder indicates that :writefile and :export commands are NOT permitted.

User Timers

User timers allow you to schedule particular scripts to be run at specified intervals. These scripts could perform cleanup, or trigger hardware, or even system restarts (to clean up system resources). User timers primarily consist of specifying a script to run, a time interval at which the script should be run, and the recurrence of the event (one time, repeating).

User timers are created by adding one or more <usertimer> tags to the configuration file (within the socketserver tag) with the following possible properties set as tags within each outer tag:

Required Usertimer Properties

• script : (class="string") Any valid Solo_Predictor script script to execute. Often uses an :include command to read a script.
• name : (class="string") REQUIRED descriptive name for the timer object, should be unique.

Recommended Usertimer Properties

• ExecutionMode : (class="string") [ 'fixedDelay' | 'fixedRate' | 'fixedSpacing' |{'singleShot'}] type of timer execution.

A timer follows the sequence: Queue --> Start --> Run --> End ... where "Queue" is an indefinite period of time in which other processes may delay the script starting, the following execution modes can be used:

'singleShot' = script is executed once (default)

'fixedRate' = script is queued for execution Period seconds after the last execution was queued (queue-queue = Period)

'fixedDelay' = script is queued for execution Period seconds after the last execution started (start-queue = Period).

'fixedSpacing' = script is queued for execution Period seconds after the last execution ended (end-start = Period)

• Period : (class="numeric") [default = 1] seconds between executions if any mode other than 'singleShot'
• BusyMode : (class="string") [{'drop'}| 'error' | 'queue' ] control overlapping timer executions. 'drop' ignores timer requests which occur while another timer process is executing. 'queue' keeps a queued list of executions which occured while another timer was executing and executes these missed actions in sequence. 'error' throws an error if two timers conflict.
• StartDelay : (class="numeric") [default = 0] number of seconds to wait before initial execution.

Other Usertimer Properties:

• error : (class="string") define how the timer should handle if an untrapped error occurs during the script. One of the following strings:

  'die' Let the timer die without action except log messages.

  'restart' [default] Attempt to restart the timer (see maxrestart setting below)

  'reboot' Reboot the computer (requires "shutdown" (Windows) or "reboot" (Linux) functions be on the system path)

  'stop' Stops Solo_Predictor (often used to trigger an alarm on the watchdog program.)

• maxrestart : (class="numeric") number of times a timer can be restarted before switching to "errorrestart" error mode [default = 5]
• errorrestart : (class="string") error mode (see error above) to use if restarts failed maxrestart times [default = 'die']

Web Access

The following elements appear within the socketserver element, as tags:

• serverfolder (class="string"): The folder where files for web access are located.

• requirelogin (class="numeric"): Does web access require login via authorization object? Choices are 'true' or 'false'.

• loginfolder (class="string"): The folder were served files are stored for non-logged in users (used when requirelogin is true and user hasn't logged in).

Q and T Squared Statistics

The following elements appear within the socketparse element, as tags:

• matchvars (class="string"): Governs whether variable matching to model is performed. Valid choices are: 'on' or 'off'. When 'on', variables provided in data are automatically matched to model before application (if possible - see MATCHVARS for more information). When 'off', mismatch of passed variables and those expected by model will return an error.

• reducedstats (class="string"): Governs whether Q and T^2 statistics from models are "reduced" using the confidence limit set in the model.detail.reslim and model.detail.tsqlim fields. Valid choices are: 'off', 'on', or 'force'. If 'on', statistics accesed methods like .Q and .T2 are normalized using the value stored in the appropriate detail sub-field. If 'off', statistics are returned as calculated. If 'force', the old-style of normalization is used in which the raw fields (.ssqresiduals and .tsqs) are reduced so that any route to access the Q and T2 will return reduced values. Note that in 'on' mode, the non-reduced statistics will be returned by .ssqresiduals or .tsqs references.

• contributions (class="string"): Governs detail of returned T^2 and Q contributions. Valid choices are: 'passed', 'used', and 'full'. Return contributions for:

  'passed' = only the variables passed by the client in the order passed. This mode allows the client to easily map contributions back to passed data and is the preferred mode.

  'used' = all variables used by the model including even variables which client did not provide. Variable order is that used by model and may not match the order passed by the client.

  'full' = all variables used or excluded by the model, including even variables which client did not provide. Variable order is that used by model and may not match the order passed by the client.

Evriscript Object Use

The following element may appear within the evriscript element, as a tag:

• keywordonly (class="numeric"): Values 0 or 1. Default value 1 limits access to evriscripts to predefined objects only. Value 0 is required if customized evriscripts have been added to this product by Eigenvector Research.

Example default.xml File

The following is an example of a typical Solo_Predictor default.xml configuration file.

<Settings>
  <Preferences>
    <socketserver>
      <controls class="string">limited</controls>
      <max_screen_lines class="numeric" size="[1,1]">20</max_screen_lines>
      <pulse_period class="numeric" size="[1,1]">15</pulse_period>
      <log_severity class="numeric" size="[1,1]">1</log_severity>
      <max_log_size class="numeric" size="[1,1]">50000</max_log_size>
      <logfile class="string">C:\Program Files\EVRI\Solo_Predictor\log_sp.txt</logfile>
      <port class="numeric" size="[1,1]">2211</port>
      <maxclients class="numeric" size="[1,1]">1</maxclients>
      <loopbackonly class="numeric" size="[1,1]">1</loopbackonly>
      <validip class="cell" />
      <privateworkspace class="numeric" size="[1,1]">1</privateworkspace>
      <eomstring class="string" />
      <tickletimeout class="numeric" size="[1,1]">1</tickletimeout>
      <emptytimeout class="numeric" size="[1,1]">2</emptytimeout>
      <eomtimeout class="numeric" size="[1,1]">3</eomtimeout>
      <waitforfile class="string">on</waitforfile>
      <waitfolder class="string">C:\temp\solopredictor\waitforSP</waitfolder>
      <waitfilespec class="string">*.mat</waitfilespec>
      <waitscript class="string">C:\temp\solopredictor\waitforSPscript.txt</waitscript>
      <writefilefolder class="string">C:\temp\solopredictor\outSP</writefilefolder>
      <default_format class="string">xml</default_format>
      <serverfolder class="string" />
    </socketserver>    
    <socketparse>
      <matchvars class="string">on</matchvars>
      <reducedstats class="string">on</reducedstats>
      <contributions class="string">passed</contributions>
    </socketparse>
    <evriscript>
      <keywordonly class="numeric" size="[1,1]">1</keywordonly>
    </evriscript>
    <allowedobjects>
      <allowed class="cell" size="[1,15]">
        <tr>
          <td class="string">dataset</td>
          <td class="string">evrigui</td>
          <td class="string">evriarchive</td>
          <td class="string">evriscript</td>
          <td class="string">bwteklaser</td>
          <td class="string">bwtekspecinterface</td>
          <td class="string">bwtekspectrometer</td>
          <td class="string">predictor</td>
          <td class="string">datacache</td>
          <td class="string">usertimer</td>
          <td class="string">resultitem</td>
          <td class="string">evriscript_step</td>
          <td class="string">evridb</td>
          <td class="string">evrimodel</td>
          <td class="string">tcast</td>
          <td class="string">evriauthentication</td>
        </tr>
      </allowed>
    </allowedobjects>
  </Preferences>
  <Licensecode class="string">########-#########-##-####-####</Licensecode>
</Settings>