Options, Flows, and Programs

Programs generally follow a fairly standard flow. First you read in parameters from the command line, then process these parameters, potentially creating new parameters, and finally you run the algorithm. You can think of a flow as series of programs, where you run through these basic steps for each program. An example is wave-equation migration. To perform wave-equation migration a typical flow would be to choose the reference velocities, convert the data to the frequency domain, migrate the data, transpose the data, and create angle gathers. All of these steps could be independent programs, combined into a single program, or a multitude of other possible variations. The advantage of combining these steps into a single program is that many times they share parameters, so you are simplifying the user's jobs. The disadvantage is the code becomes more difficult to manage.

The options, flow, and program objects attempt to allow the simplicity of simple programs that perform a single operation, with the advantage of a shared parameter space. A SEP.opt_base.options is an extension of the SEP.args.basic class. It has several additional abilities:

• It can output self-documentation based on its set of parameters.
• It introduces five additional functions:
  • The read_params(args,prefix) extracts from the SEP.args.basic object all of the parameters that the options group has been initialized with. If the parameter is required and doesn't exist it returns an error with the self-doc for the parameter. The prefix argument will limit the search of args to parameters that begin with prefix, everything after the prefix will be assumed to be the name of the parameter for the object.
  • build_check_params() which builds additional parameters and checks parameter validity based on command line arguments.
  • The function prep_run(restart) runs the task associated with the parameter group. Examples might be running a serial code or a parallel job.
  • Finally clean_files() is meant to remove any unneeded files after the execution of the job.

The SEP.opt_base.options is currently inherited by four classes. The SEP.opt_none.options is for a group of options that aren't associated with a job. The prep_run and clean_files routines are by default empty. The SEP.opt_prog.options is for a set of options associated with a serial code. The prep_run function executes the code with the parameters associated with the object. The final two children, SEP.par_job.par_job and SEP.solv_base.solver, are discussed later.

The SEP.flow.flow object is a collection of parameter groups and flows. In the migration example we might have the velocity selection and migration as independent programs, where each has a parameter group associated with them. The angle gathers might be a flow composed of transposing the data and then creating the angle gathers. The SEP.opt_flow.flow object is initialized with a set of flows, a set of parameter groups, the order in which to run them, and potentially prefixes associated with the individual flows and parameter groups. The prefixes argument is a dictionary linking a given parameter group or flow to the prefix that all of its parameters will be initialized with.

The flow object has two basic functions: add_options and prep_run. The first function takes in a set of parameters args and runs read_params(args,prefix). It then runs build_check_params on each parameter group and flow.

The prep_run call in a flow prep_run and clean_files parameter groups and flows. It is also regulated by a SEP.stat_sep.status object that allows that job to be restarted.

The final object, SEP.prog.prog inherits from the flow object. In addition, it has the concept of description and usage blocks for documentation, and by default uses the command line arguments when parsing parameters.