Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

# 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.

- Step 1: Create an executable that evaluates the objective function.
- Step 2: Create an APPSPACK input file
- Step 3: Run APPSPACK

We use `example1` for illustration. The code for this example is provided in the `examples` directory (at the top level of the source tree).

## 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:

      example1 ex1_in.27 ex1_out.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:

      2
      1.24e-1
      17.4e-3

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:

      7.58e-3

- 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. (This file is used to create a Parameter::List with three sublists: "Evaluator", "Bounds", and "Solver". These sublists are then used as arguments to the constructors for the APPSPACK::Evaluator::SystemCall, APPSPACK::Constraints::Bounds, and APPSPACK::Solver objects, respectively.)

- Here is a sample input file (see `examples/example1`.apps):

      # SAMPLE APPSPACK INPUT FILE
      @ "Evaluator"
      "Executable Name" string "/home/username/appspack/examples/example1"
      "Input Prefix" string "ex1_in"
      "Output Prefix" string "ex1_out"
      @@
      @ "Bounds"
      "Upper" vector 2 1 1
      "Lower" vector 2 -1 -1
      @@
      @ "Solver"
      "Debug" int 4
      "Initial X" vector 2 2e-1 0.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".
  - "Bounds"
    - "Lower" - Lower bounds
    - "Upper" - Upper bounds
    - See Bounds Parameters for more details.
  - "Solver"
    - See Solver Parameters for a complete list of parameters that may be specified here.

- In general, the input file is processed as follows. Any empty lines are ignored, and comment lines begin with a `#`. The beginning of a category is specified by a `@` followed by a space and then the category name in quotes. The end of a category is designated by a line containing the symbols @. Within a category, parameters are defined by name (in quotes), type (`string`, `int`, `double`, `vector`, or `bool`,), and value. String values, such as the executable name, are given in quotes. Double and integer values are just numbers. Vectors values include an integer that represents their length followed by each entry. Boolean values are written without quotes. The only recognized boolean values are `true` and `false`, and any other input is treated as false. To summarize:

  - Empty lines are ignored.

  - Comment lines begin with a #.

  - Parameters are specified generically as follows.

        "String Parameter Name" string "A string"
        "Integer Parameter Name" int 4
        "Double Parameter Name" double 3.0
        "Vector Parameter Name" vector 2 0.3 0.4

  - A sublist group is specified as follows. (The dots are replaced by parameter specifications, as above.)

        @ "Sublist List Name In Quotes"
        ...
        @@

See APPSPACK::parseTextInputFile() for more details.

## 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

© Sandia Corporation | Site Contact | Privacy and Security

Generated on Wed Dec 14 18:41:05 2005 for APPSPACK 4.0.2 by 1.3.8 written by Dimitri van Heesch, © 1997-2002