Contents

1 Introduction

This chapter describes the execution of OSTRICH from the command line and parallel computing environments. Four OSTRICH executables are available: a serial version which runs on Windows, a multi-core parallel version that runs on Windows, a serial version which runs on Linux, and a parallel version which runs on Linux-based parallel clusters. Regardless of which version of OSTRICH is used, the following components must be created and stored in a working directory before running OSTRICH:

• ostIn.txt: This is the main configuration file which should be created using the syntax described in the Setup section. Different groups should be filled out depending on the objective function (GCOP or WSSE)

• Template File(s): These are file(s) that OSTRICH uses to create a syntactically correct model input file(s), so as to evaluate some set of model parameters (X).

  1. Create a template file by making a copy of the corresponding model input file.
  2. Edit the template file by replacing parameter values with the corresponding parameter names.
  3. Check that template file has been listed in the FilePairs section of ostIn.txt.
  4. Check that parameter names in Params section of ostIn.txt are consistent with those used in template file.
  5. [optional] If including a ParameterCorrections group, prepare and include appropriate template files for parameter corrections
  6. [optional] If including a ParameterCorrections group, check that parameter names listed in the Corrections sub-group are consistent with the Params section as well as the template files for parameter corrections.
• Extra Model Input Files: Any model input files not required by OSTRICH (i.e. there is no corresponding template file), but needed by the model.

1.1 Using Weighted Sum of Squared Errors (WSSE) Calibration

Several groups and variables of the ostIn.txt input file should be filled out if calibration is desired. These include the ObjectiveFunction (set to WSSE), ProgramType (select desired search algorithm), ModelExecutable (specify executable or batch/script file), FilePairs, Parameters, Observations, and Math and Stats.

1.2 Using the General Constrained Optimization Platform (GCOP)

Several groups and variables of the ostIn.txt input file should be filled to use the general constrained optimization platform. These include the ObjectiveFunction (set to GCOP), ProgramType (select desired search algorithm), ModelExecutable (specify executable or batch/script file), FilePairs, Parameters, Response Variables, GCOP, and Constraints.

2 Serial (Single Processor) Execution

Once all files have been created and placed in the working directory, serial execution of OSTRICH is straightforward: open a command line prompt, change directory (cd) to the working directory, and run OSTRICH by typing:

Using Linux:

/[path]/Ostrich

Using Windows:

[path]\Ostrich.exe

Where [path] is the path to the location of the OSTRICH executable (e.g. “C:\Program Files\Ostrich” or /home/usr/bin). When run in serial, an optimization run record is printed for each iteration of the chosen algorithm.

3 Multi-core Parallel Execution in Windows

Prior to running OSTRICH in parallel, the ostIn.txt file must be adjusted to include appropriate ExtraFiles, ExtraDirs, and ModelSubdir entries as needed for your project.

OSTRICH can be launched in parallel on a single Windows machine using Microsoft’s MS-MPI implementation. Note that MS-MPI must be installed before OSTRICH can be run in parallel on a Windows machine. Consistent with other MPI implementations, the Windows-based parallel version of OSTRICH is launched using a program named mpiexec. For example, to run OSTRICH in parallel on an 8-core Windows desktop you would type the following from a DOS command line (or in a batch file):

mpiexec -n 8 OstrichMPI.exe

4 Distributed or Multi-core Parallel Execution in Linux

Prior to running OSTRICH in parallel, the ostIn.txt file must be adjusted to include appropriate ExtraFiles, ExtraDirs, and ModelSubdir entries as needed for your project.

To run OSTRICH in parallel on a Linux machine or Linux-based cluster of machines, the Linux environment must provide MPI (Message Passing Interface) libraries. Any MPI implementation will suffice and pre-compiled RedHat/CentOS OSTRICH binaries compatible with various versions of OpenMPI and Intel-MPI are provided with the OSTRICH distribution. For systems not supported by the pre-compiled binaries it is necessary to re-compile OSTRICH source so that it can link with a supported MPI implementation.

Currently supported parallel algorithms implemented in OSTRICH are listed in the Overview. While any of the other algorithms can be successfully run in a parallel environment, doing so will not result in any performance improvement. Launching an MPI program requires the use of a compatible launcher, such that one cannot simply invoke the OSTRICH binary and expect parallel calculations (i.e. running //OstrichMPI won’t work). Rather, a typical command line for launching OSTRICH in parallel on a Linux machine or cluster is given below:

mpirun –n 12 /home/user/bin/OstrichMPI

Where “mpirun” is a launcher provided with many implementations of MPI – other common launchers include “mpiexec” and “mpiexec.hydra”. On clusters managed using SLURM (Simple Linux Utility for Resource Management) an alternative launcher named “srun” may also be used. With respect to “mpirun”, the “-n 12” argument requests OSTRICH to be run on 12 processors. A “-hostfile” and/or “-rankfile” argument may also be required if running OSTRICH across multiple nodes is desired. Users should consult the documentation and man pages of a given launcher for details on using these and other command-line arguments.

5 Aborting an OSTRICH run

An OSTRICH run can be aborted by creating a file named OstQuit.txt and placing it in the working directory where the corresponding ostIn.txt file is located. OSTRICH will detect the presence of the OstQuit.txt file during the next iteration of search and will exit gracefully.

6 Restarting an OSTRICH Run

Some OSTRICH search algorithms can be restarted from previous runs of a potentially different algorithm. These algorithms are indicated by the shaded entries in the “Warm Start?” column of Overview. Users should include a line containing “OstrichWarmStart yes” in the ostIn.txt input file to activate an OSTRICH restart. OSTRICH will then read in the contents of previous output files to configure the restart state of the selected search algorithm.