diff --git a/README.md b/README.md index 9b3becc..9f9e0f2 100644 --- a/README.md +++ b/README.md @@ -48,14 +48,74 @@ For non MPI executables a wrapper application, `serial`, is provided. This wrapp ``` $ wraprun -n 1 serial ./foo.out -foo_args : ... ``` +### Standard output/error Redirection -The `stdout/err` for each task is directed to it's own unique file in the -current working directory. In early releases, this effect was accomplished -with the `--w-roe` flag. However, manually specifying this flag has not been -required since v0.1.11. +The `stdout/stderr` streams for each task are directed to a unique file. By +default, each task writes these streams to files in the task's own current +working directory named: + +``` +${JOBNAME}.${JOBID}_w${INSTANCE}.${TASKID}.out +${JOBNAME}.${JOBID}_w${INSTANCE}.${TASKID}.err +``` + +where `JOBNAME` is the batch job name (value of `$PBS_JOBNAME` for instance), +`JOBID` is the batch job number (or PID of parent shell if `$PBS_JOBID` is unavailable), +`INSTANCE` is the unique wraprun invocation called within the parent shell, and +`TASKID` is the task index among all bundled tasks. The instance index is +required so that multiple concurrent wraprun invocations in a single batch job +do not collide with each other. The task index is fixed in the order that tasks are +passed to wraprun such that for the following invocation: ``` -$ wraprun --w-roe -n 1 ./foo.out: ... +$ wraprun -n 1,2 ./foo.out : -n 3 ./bar.out +``` + +task '0' is the instance of `foo.out` having 1 PE; task '1' is the 2 PE split of +`foo.out`, and task '2' is the instance of `bar.out`. + +The default names can be overridden by supplying a basename path to the group flag `--w-oe`: + ``` +$ wraprun -n 1,2 --w-oe name_a ./a.out : \ + -n 1,2 --w-oe name_b1,name_b2 ./b.out : \ + -n 1 --w-oe name_c1,sub/name_c2 ./c.out : \ + -n 1,1 ./d.out : \ + -n 1 ./e.out +``` + +The names can be either relative or absolute paths to an `aprun`-writable +location. Relative names are taken from the task's CWD. Wraprun will not +create missing directories. Wraprun will add `.out` and `.err` extensions to +the given path for each stream. + +When ambiguous names are provided as for `a.out` in the above example, wraprun +will add `_w${SPLITID}` to the given path for each task split. To avoid this, a +specific filename can be given to each task as a comma-separated list for each +group split. The output of the above example would then be + +``` +. +├── name_a_w0.err +├── name_a_w0.out +├── name_a_w1.err +├── name_a_w1.out +├── name_b1.err +├── name_b1.out +├── name_b2.err +├── name_b2.out +├── name_c1.err +├── name_c1.out +├── sub/ +│   ├── name_c2.err +│   └── name_c2.out +├── nameofbatchjob.123456._w0.6.err +├── nameofbatchjob.123456._w0.6.out +├── nameofbatchjob.123456._w0.7.err +├── nameofbatchjob.123456._w0.7.out +├── nameofbatchjob.123456._w0.8.err +└── nameofbatchjob.123456._w0.8.out +``` + ## Python API @@ -93,6 +153,7 @@ group option. | Parameter | CLI Flag | API keyword | API format | | ----------------------------------------------:|:--------:|:---------------------:|:---------------- | | Task working directory | --w-cd | 'cd' | str or [str,...] | +| Task stdout/stderr file basename | --w-oe | 'oe' | str or [str,...] | | Number of processing elements (PEs). REQUIRED | -n | 'pes' | int or [int,...] | | Host architecture | -a | 'arch' | str | | CPU list | -cc | 'cpu_list' | str | diff --git a/python/wraprun/options.py b/python/wraprun/options.py index 2d129c6..8f7fb94 100644 --- a/python/wraprun/options.py +++ b/python/wraprun/options.py @@ -207,13 +207,13 @@ def __init__(self): split=True, unique=True, parser={ - 'metavar': "fname[,fname...]", + 'metavar': "oef[,oef...]", 'default': ['{name}.{job}_w{instance}'.format( name=os_env.get('PBS_JOBNAME', 'unnamed'), job=JOB_ID, instance=INSTANCE_ID)], 'action': OEAction, - 'help': 'STDOUT/STDERR file basename', + 'help': 'Task stdout/stderr file basename', }, ), )