HAL quick start guide version 1.1.0 July 26, 2012 NOTE: This guide remains a work-in-progress. If you have any isses that aren't covered here, or any bug reports, feature requests, comments, or questions, please contact the current HAL developers at hal-dev@cs.ubc.ca 1.0 Super quick start (linux only, unfortunately SPEAR is unavailable for other platforms): - download full HAL 1.0 zip distribution; install using below instructions. - download sample experiment package; import using the HAL "Import HAL objects" task in the UI. - try configuration and analysis using the provided sample algorithm (SPEAR) 2.0 Installing HAL - download the full zip package - extract the zip to a working directory - double click the hal_.jar file OR type "java -jar hal_.jar" to start the HAL server - navigate to http://:8080/hal to get the UI - If you need a different port, use "java -jar hal_.jar -p " - If you wish to limit the memory available to HAL, use e.g., "java -Xmx512M -jar hal_.jar" 2.1 Basic configuration - After first start of HAL, a file called hal.json will be created. Basic configuration settings can be modified by editing this file. - RECOMMENDED: if you have a MySQL server, use it instead of the default SQLite database. To do so, edit the hal.json file; change: "database":"jdbc:sqlite:hal.db" to something like "database":"jdbc:mysql://@:/hal_db" 2.1 Plugin installation - to install a new HAL plugin, copy the plugin .jar file into the /plugins/ folder and restart HAL. Note that in some cases, a new version of HAL or a new version of the plugin will necessitate a newly-created database. Migration is a known feature request, but not something we anticipate in the next several releases. 3. Defining an algorithm To add a new algorithm for use in HAL, use the "Define a new algorithm" wizard: 3.1: Algorithm specification - The name+version combination must be unique in the database. - Supported instance tag sets are used to restrict which algorithms can be run on particular instances. A tag set such as {cnf, 3sat} marks the algorithm as compatible with any instance with both "cnf" and "3sat" tags. An algorithm can have multiple instance tag sets; at least one of them must be satisfied by an instance in order for it to be considered compatible. If no tags are specified, then HAL will assume the algorithm is compatible with all instances. - Advanced properties: deterministic: Multiple runs of the algorithm with the same parameter settings and instance will yield identical results; note that if your algorithm has a seed as an input, mark it as NOT determinsitic, and explicitly identify the seed parameter (below). - Advanced properties: exportable: An algorithm is exportable if and only if HAL can compress the entire directory tree rooted at the executable file, extract it on a different machine, and the algorithm will work on that second machine. - Advanced properties: cutoff-independence: Set this to true if the algorithm's behaviour will not change if cutoff inputs are changed but all other inputs remain the same. HAL uses this property to decide whether it can infer cutoffs or completions from previously-performed runs. - Executable: should be the first command to run the algorithm; if the algorithm is an interpreted script this might be "python" or "ruby". Note that this path must exist ON THE SYSTEM RUNNING HAL, not the system running the browser that is interfacing with HAL (if the two differ). - Command-line argument string: see example in the UI, or the linked help file. Note that all input variables (specified like $name$ in the command string) will need to be further defined in later steps. (NOTE: HAL does not currently support generating input files for target algorithms.) - Algorithm output specification. Format is the same as the command-line argument specification; and as in that case, all identified output variables will require further specification. HAL will use this string to parse outputs from the standard output and error streams of the algorithm during execution. 3.2: Identify configurable parameters: - a configurable parameter is a parameter whose value may be tuned by a configurator to optimize performance; all "other" settings will be left unchanged during configuration (other than cutoffs and the instance file(s)). 3.3: Specify configurable parameter domains - for every input parameter marked as configurable, the domain of valid values must be specified. - conditionalities between parmeters can be specified, where conditionality refers to "activation" of parameters. For example, parameter X can be marked as active only if parameter Y takes some particular value. - prohibited parameter configurations can similarly be specified. 3.4: as 3.3, for "other" input settings 3.5: as 3.3, for output variables 4.0: Instance set specification To specify an instance set, use the Create New InstanceDistribution wizard: - distirbution name must be unique - tags are used to filter compatible algorithms (see 3.1 above) - An instance is exportable if it is fully-defined by a single file - The directory path must be valid on the system runnign HAL, not the system runnign the web browser --- 5.0 Experiment specification - Metrics: PAR1 and PAR10 rely on HAL-measured CPU time; Reported PAR1 and PAR10 rely on algorithm-reported CPU time