(r5) HowToGuides < BETA

Tags: view all tags
---+!! !HAL-related tutorials
This page is the temporary home of HAL-related tutorials.

%TOC%

---++HA<!--unWikiWord-->L !WebUI Tutorial
---+++Starting !HAL !WebUI
   * Start !HAL by running *HAL_[version].jar* (==java -jar HAL_[version].jar [-p #port(default 8080)]==)
   * The !WebUI is available from !http://[machineaddress]:[port]/hal (e.g. http://localhost:8080/hal)

---+++Installation and Configuration

---+++Defining a New Algorithm

---+++Saving and Loading !HAL objects

---++ Matlab Builder JA Quick Start
_See attached [[%ATTACHURL%/javabuilder.pdf][user guide]]_

---+++ Hello World
A "Hello World" example is described below. We will describe how to call the following Matlab function from Java.
<pre><code>
function hello
% Hello world example
% hello.m

fprintf(1, 'Hello World\n');
</code></pre>

---++++ Exporting JAR
   1. *MCR* must be installed and its directory added to the system's path variable.
   1. Create a new deployment project by entering =deploytool= into the Matlab command window. <img src="%ATTACHURL%/java_t1.png" style="display:block;margin-left:auto;margin-right:auto;margin-top:10px;margin-bottom:10px" />
   1. In the Deployment Tool window, create the necessary classes by clicking *[Add Class]*. For each class, add the matlab function (_*.m_) files that belong to the class by selecting *[Add files]*.<img src="%ATTACHURLPATH%/java_t2.png" alt="Add classes and matlab functions"  width="768" height="215" style="display:block;margin-left:auto;margin-right:auto;margin-top:10px;margin-bottom:10px" />
   1. Create the Java Package by selecting the *build* button. This will create src and distrib folders containing your *[project].jar* file. The name of the jar file may be specified from Settings.

---++++ Calling code from Eclipse
   1. Add *[project].jar* and *javabuilder.jar* to the build path. The *javabuilder.jar* should be located in =/toolbox/javabuilder/jar/javabuilder.jar= inside your Matlab folder.
   1. Any code that calls code from these java classes must also import =com.mathworks.toolbox.javabuilder.*=.
   1. Call the function like a normal Java method from an instance of the class. Conversion between Java and Matlab types may be handled either automatically or explicitly (see [[#MatlabDataTypes][next section]]).

#MatlabDataTypes
---++++Data Types and Conversion
Data conversion classes are available in the following hierarchy:
   * !MWArray
      * !MWNumericArray
      * !MWLogicalArray
      * !MWCharArray
      * !MWCellArray
      * !MWStructArray

Matlab Builder will perform conversion from native types automatically, and constructors can be used with Java types and arrays.

Pass by reference is available with the !MWJavaObjectRef wrapper, a subclass of !MWArray.

---++ HAL quick start guide
_version 1.0b4 Nov. 29, 2010_

NOTE:  this quite is very much a work-in-progress.  If you have any isses that aren't covered here, or any other comments or questions, please contact us at cnell@cs.ubc.ca


---+++Super quick start (linux only):  
 - download full !HAL 1.0 zip distribution; install using below instructions.
 - download sample experiment package; import using the !HAL 1.0 interface
 - try configuring, analysing the provided sample algorithm (SPEAR)


---+++Installing !HAL
 - download the full zip package
 - extract the zip to a working directory
 - double click the !HAL_<version>.jar file OR type "java -jar !HAL_<version>.jar" to start the webserver
 - navigate to !http://&lt;machine address&gt;:8080/hal (e.g. [[http://127.0.0.1:8080/hal]]) to get the UI


---++++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://<user>@<mysql.server.url>:<port>/hal_db"


---++++Plugin installation
 - to install a new !HAL plugin, copy the plugin .jar file into the /plugins/ folder and restart !HAL.


---+++Defining an algorithm
To add a new algorithm for use in !HAL, use the "Define a new algorithm" wizard:

---++++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, the !HAL will assume the algorithm is compatible with all instances.
 - Advanced properties: deterministic:  stgraightforward; 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, exctract 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.  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.
 
---++++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

#SpecifyDomain
---++++Specify configurable parameter domains
 - for every input parameter marked as configurable, the domain of valid values must be specified.
 - conditionalities between parameters 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
 
 
---+++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 running the web browser
 
 
 ---
 
---+++Experiment specification
 - Metrics:  PAR1 and PAR10 rely on !HAL-measured CPU time; Reported PAR1 and PAR10 rely on algorithm-reported CPU time
 
 
   * [[%ATTACHURL%/javabuilder.pdf][javabuilder.pdf]]: Matlab Builder JA User Guide
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
pdf	javabuilder.pdf	r1	manage	1402.6 K	2011-01-06 - 21:59	UnknownUser	Matlab Builder JA User Guide
Topic revision: r5 - 2011-01-11 - mavc