cape.cfdx.options: Options module

The cape.cfdx.options provides tools to read, access, modify, and write settings for cape. The class is based off of the built-int dict class, so its default behavior, such as opts['RunControl'] or opts.get('RunControl') are also present. In addition, many convenience methods, such as opts.set_PhaseIters(n), which sets the number of iterations to run, are provided.

In addition, this module controls default values of each pyCart parameter in a two-step process. The precedence used to determine what the value of a given parameter should be is below.

  • Values directly specified in the input file, cape.json

  • Values specified in the default control file,

    $CAPE/settings/cape.default.json

  • Hard-coded defaults from this module

The strategy for the cape.options.Options class, or the derived pyCart.options.Options, pyFun.options.Options, or pyOver.options.Options classes, is that the user may get the options either from the parent options class or the subclass. For example, both of the following commands get the option of whether or not to submit PBS jobs.

opts.get_qsub()
opts['RunControl'].get_qsub()

Furthermore, there is a control to get options specifically for phase j. Each option can be called either with or without the phase number, for instance opts.get_qsub() or opts.get_qsub(j). If the option has different settings for each phase, this will return entry number j (0-based indexing) of the option (if j is greater than the length of the list, the last entry in the list is returned); but if the entry is a scalar, that scalar is returned regardless of the value of j.

Finally, this module is very closely tied with the JSON section, which often contains more useful descriptions.

class cape.cfdx.options.Options(fname=None, **kw)

Options structure, subclass of dict

Call:
>>> opts = Options(fname=None, **kw)
Inputs:
fname: str

File to be read as a JSON file with comments

kw: dict

Dictionary to be transformed into cape.options.Options

Outputs:
opts: Options

Options interface

Versions:

  • 2014-07-28 @ddalle: Version 1.0

AddPythonPath()

Add requested locations to the Python path

Call:
>>> opts.AddPythonPath()
Inputs:
opts: cape.options.Options

Options interface

Versions:

  • 2014-10-08 @ddalle: Version 1.0

WritePBSHeader(f, lbl, j=0, typ=None, wd=None)

Write common part of PBS script

Call:
>>> opts.WritePBSHeader(f, i=None, j=0, typ=None, wd=None)
Inputs:
opts: cape.options.Options

Options interface

f: file

Open file handle

lbl: str

Name of the PBS job

j: int

Phase number

typ: {None} | "batch" | "post"

Group of PBS options to use

wd: {None} | str

Folder to enter when starting the job

Versions:

  • 2015-09-30 @ddalle: Separated from WritePBS

  • 2016-09-25 @ddalle: Supporting “BatchPBS” and “PostPBS”

  • 2016-12-20 @ddalle: Created version in options interface

get_ShellCmds(typ=None)

Get shell commands, if any

Call:
>>> cmds = opts.get_ShellCmds(typ=None)
Inputs:
opts: cape.options.Options

Options interface

typ: {None} | "batch" | "post"

Add additional commands for batch or post-processing jobs

Outputs:
cmds: list[str]

List of initialization commands

Versions:

  • 2015-11-08 @ddalle: Moved to “RunControl”

get_dmask(sys=True)

Get the permissions to assign to new folders

Call:
>>> dmask = opts.get_dmask(sys=True)
Inputs:
opts pyCart.options.Options

Options interface

sys: {True} | False

Whether or not to use system setting as default

Outputs:
dmask: int | None

New folder permissions mask

Versions:

  • 2015-09-27 @ddalle: Version 1.0

get_nSubmit()

Return the maximum number of jobs to submit at one time

Call:
>>> nSub = opts.get_nSubmit()
Inputs:
opts: pyCart.options.Options

Options interface

Outputs:
nSub: int

Maximum number of jobs to submit

Versions:

  • 2015-01-24 @ddalle: Version 1.0

get_umask(sys=True)

Get the current file permissions mask

The default value is the read from the system

Call:
>>> umask = opts.get_umask(sys=True)
Inputs:
opts pyCart.options.Options

Options interface

sys: {True} | False

Whether or not to use system setting as default

Outputs:
umask: None | oct

File permissions mask (None only if sys is False)

Versions:

  • 2015-09-27 @ddalle: Version 1.0

mkdir(fdir, sys=False)

Make a directory with the correct permissions

Call:
>>> opts.mkdir(fdir, sys=False)
Inputs:
opts: cape.options.Options

Options interface

fdir: str

Directory to create

sys: True | {False}

Whether or not to replace None with system setting

Versions:

  • 2015-09-27 @ddalle: Version 1.0