`shave`

Note

The uwtools drivers are idempotent, meaning that actions they successfully complete during one invocation are not repeated in subsequent invocations. For example, an asset like a configuration file will not be recreated when the driver is run again, even if its UW YAML configuration changes. To force recreation, remove the asset(s) in question – up to and including the entire provisioned run directory – then re-run the driver, which will recreate any missing assets based on the current configuration.

The uw mode for configuring and running the UFS Utils preprocessing component shave. Documentation for this UFS Utils component is here.

uw shave --help

usage: uw shave [-h] [--version] TASK ...

Execute shave tasks

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit

Positional arguments:
  TASK
    provisioned_rundir
      Run directory provisioned with all required content
    run
      A run
    runscript
      The runscript
    validate
      Validate the UW driver config

All tasks take the same arguments. For example:

uw shave run --help

usage: uw shave run [-h] [--version] [--config-file PATH] [--batch]
                    [--dry-run] [--graph-file PATH] [--key-path KEY[.KEY...]]
                    [--quiet] [--verbose]

A run

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --config-file PATH, -c PATH
      Path to UW YAML config file (default: read from stdin)
  --batch
      Submit run to batch scheduler
  --dry-run
      Only log info, making no changes
  --graph-file PATH
      Path to Graphviz DOT output [experimental]
  --key-path KEY[.KEY...]
      Dot-separated path of keys leading through the config to the driver's
      configuration block
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages

Examples

The examples use a configuration file named config.yaml with contents similar to:

shave:
  config:
    input_grid_file: /path/to/input/grid/file
    nh4: 1
    nx: 214
    ny: 128
  execution:
    batchargs:
      cores: 1
      walltime: "00:01:00"
    executable: /path/to/shave
  rundir: /path/to/run/dir
platform:
  account: me
  scheduler: slurm

Its contents are described in section shave.

Run shave on an interactive node
```
$ uw shave run --config-file config.yaml
```
The driver creates a runscript.shave file in the directory specified by rundir: in the config and runs it, executing shave.
Run shave via a batch job
```
$ uw shave run --config-file config.yaml --batch
```
The driver creates a runscript.shave file in the directory specified by rundir: in the config and submits it to the batch system. Running with --batch requires a correctly configured platform: block in config.yaml, as well as appropriate settings in the execution: block under shave:.
Specifying the --dry-run flag results in the driver logging messages about actions it would have taken, without actually taking any.
```
$ uw shave run --config-file config.yaml --batch --dry-run
```

The --key-path option can be used to navigate from the top of the config to the driver’s configuration block. For example, specifying --key-path foo.bar with config
```
foo:
  bar:
    driver:
      # driver config block
```
is equivalent to using config
```
driver:
  # driver config block
```
without specifying --key-path.

shave

Examples

`shave`