Using the APPSPACK Executables

Depending on the configuration options you choose (see Configuration, Compilation, and Installation), APPSPACK will create the following executables:

appspack_serial - compiled by default
appspack_mpi - compiled if MPI is enabled (e.g., --with-mpi-compilers is specified at configure time)

To use either of these, you need only complete three steps.

We use example4.cpp for illustration.

Step 1: Create an executable that evaluates the objective function.

The first step is to create an executable that evaluates the objective function, and this step is the same for both the serial and MPI versions of the code. The executable will find the point to be evaluated in a specified input file and should put the result in a specified output file.

The general formation for calling the function evaluation executable is as follows:
```
<Executable Name> <Input Prefix>.<tag> <Output Prefix>.<tag> <tag>
```

For example, the call might look something like:

example4 example4_input.27 example4_output.27 27

The tag is a unique identifier that is assigned to each trial point and is used in the naming of files to prevent conflicts. Thus, the calling sequence is as follows: the first argument is the name of the executable, the second argument is the name of the input file, the third argument is the name of the output file, and the fourth argument is a unique tag that can be used in the naming of auxillary files.

The input file is very simply formatted. The first line is an integer that indicates the length of the vector. This is then is followed by the vector itself, one entry per line.

An example input file for the objective function executable:
```
4
2.25
4.64
2.25
8.57e-1
```

Likewise, the output file is also simply formatted. It should contain either a single numeric entry that is the function value or an error string.

An example output file with a function value:
```
2.324e2
```
An example output file with a brief error string:
```
Infeasible wrt Nonlinear Constraint 5
```

In most cases, the executable you provide is actually a script that goes through several steps in order to calculate the objective value. If you are creating auxillary files, it is important that you use the tag (the fourth argument in the calling sequence) in the naming of your files to prevent conflicts. This is particularly important if running the MPI version of APPSPACK.

See the APPSPACK::Evaluator::SystemCall object for details on how the evaluation is processed.

Step 2: Create an APPSPACK input file

You must provide an input file specifying the parameters for running APPSPACK.

Below is a sample input file (see examples/example4.apps) specifying the following feasible region:

$\begin{array}{ccccc} -10 & \le & x_1 & \le & 10 \\ -10 & \le & x_2 & \le & 10 \\ -10 & \le & x_3 & \le & 10 \\ -10 & \le & x_4 & \le & 10 \\ \end{array}$

and

$\begin{array}{ccrcr} -10 & \le & -x_1 -x_2 -x_3 -x_4 & \le & \infty\phantom{.} \\ -\infty & \le & x_1 - x_2 + x_3 -x_4 & \le & -1\phantom{.} \\ & & 2x_1 +2x_3 -7x_4 & = & 3. \\ \end{array}$

# SAMPLE APPSPACK INPUT FILE
@ "Linear"
"Upper" vector 4  10 10 10 10
"Lower" vector 4 -10 -10 -10 -10
"Scaling" vector 4 1 1 1 1
"Inequality Upper" vector 2    DNE   -1
"Inequality Lower" vector 2    -10  DNE
"Equality Bound" vector 1 3
"Inequality Matrix"  matrix  2 4 
-1 -1 -1 -1
 1 -1  1 -1
"Equality Matrix" matrix 1 4
2 0 2 -7
@@
@ "Evaluator"
"Executable Name" string "/home/username/appspack/examples/example4"
"Input Prefix" string "example4_input"
"Output Prefix" string "example4_output"
@@
@ "Solver" 
"Debug" int 3
"Initial X" vector 4  -1 1 -1 -1 
"Step Tolerance" double 1e-3
@@

The format of the input file is as follows.
- "Evaluator"
  - "Executable Name" - Name of the executable that evaluates the function. The full path name should be specified. Defaults to "a.out".
  - "Input Prefix" - Input file prefix. Defaults to "input".
  - "Output Prefix" - Input file prefix. Defaults to "output".
- "Linear"
  - See Linear Constraint Parameters for a complete list of parameters that may be specified here.
- "Solver"
  - See Solver Parameters for a complete list of parameters that may be specified here.
In general, the input file is processed as follows.
- Empty lines are ignored.
- Comment lines begin with a #.
- String, integer, and double parameters are specified as follows.
```
"<String Parameter Name>" string "<A string>"
"<Integer Parameter Name>" int <value>
"<Double Parameter Name>" double <value>
```
- Vector parameters require a length (N)
```
"<Vector Parameter Name>" vector <N> <value1> ... <valueN>
```
- Matrix parameters require the number of rows (M) and columns (N). Each row is specified on a new line.
```
"<Matrix Parameter Name>" matrix <M> <N>
<(1,1) entry> <(1,2) entry> ... <(1,N) entry>
<(2,1) entry> <(2,2) entry> ... <(2,N) entry>
...
<(M,1) entry> <(M,2) entry> ... <(M,N) entry>
```
- A sublist group is specified as follows. (The dots are replaced by parameter specifications, as above.)
```
@ "<Sublist List Name>"
...
@@
```

This input file is processed by APPSPACK::parseTextInputFile() to create a Parameter::List with three sublists: "Evaluator", "Linear", and "Solver". These sublists are then used as arguments to the constructors for the APPSPACK::Evaluator::SystemCall, APPSPACK::Constraints::Linear, and APPSPACK::Solver objects, respectively.

Step 3: Run APPSPACK

Serial Version
The command line for what is illustrated might look something like the following:
```
appspack_serial example1.apps
```
In the serial version, there is one copy of APPSPACK running.

Serial APPSPACK
MPI Version
There is one master processor, and the remainder are workers that actually run the simulations. The command line varies a bit depending on your version of MPI. However, the command line for what is illustrated might be something like the following:
```
mpirun -np 5 appspack_mpi example1.apps
```
MPI APPSPACK