API Reference

sciath

sciath.default_colors_set_use_bash(use_bash)

sciath.getVersion()

Returns major,minor,patch version as integers

Test

class sciath.test.Test(name, ranks, execute, expected_file)

appendKeywords(keywords)

clean()

compareFloatingPointAbsolute(key, tolerance)

compareFloatingPointRelative(key, tolerance, epsilon=None)

compareInteger(key, tolerance)

compareLiteral(key)

compareUnixDiff()

getErrorReport()

getErrorStatus()

getExitCode()

getExpected()

getOutput()

report(type)

setComparisonFile(fname)

setOutputPath(opath)

setVerbosityLevel(value)

setVerifyMethod(verify)

setWalltime(mins)

updateExpected(backup=True)

Copy the comparison file to the expected file. Back up the expected file if ‘backup’ is true.

updateStatus(status, err)

verify(junk)

verifyOutput()

sciath.test.compareFloatingPointAbsolute(input, tolerance, expected)

sciath.test.compareFloatingPointRelative(input, tolerance, expected, epsilon=None)

sciath.test.compareInteger(input, tolerance, expected)

sciath.test.compareLiteral(input, expected)

sciath.test.getKeyValues(contents, keyword)

sciath.test.getKeyValuesAsFloat(contents, keyword)

sciath.test.getKeyValuesAsInt(contents, keyword)

sciath.test.getKeyValuesNLinesExclusive(contents, keyword, numlines)

sciath.test.getKeyValuesNLinesInclusive(contents, keyword, numlines)

sciath.test.parseFile(filename, keywords)

Harness

class sciath.harness.Harness(registeredTests, subsetTestName=None)

clean()

execute()

Execute tests unless verifying (only) or purging output (only) Update expected output if in “replace_expected” mode

generate_sandbox_dirname(test)

reportAll()

setUseSandbox(val=True)

setVerbosityLevel(value)

verify()

Verify, unless we are running with a batch system and are not in verify(-only) mode

Additional modules and classes

class sciath.job.Job(cmd, **kwargs)

A SciATH job

Args:

cmd (string): The command used to execute your application. **kwargs (name=value): A keyword argument list.

The Job constructor will recognize the following names:

name (string): textual name you want to assign to the job. description (string): desciption of what the job does. exitCode (int): the exit code which should be used to infer success.

Examples:

job = Job(‘echo “hi”’) -> a new job which will simply execute $echo ‘hi’

job = Job(‘echo “hi”’,**kwargs,) -> a new job which will simply execute $echo “hi”

and with variables initialized with the name=value pairs

job = Job(‘echo “hi”’, name=’job-1’, description=’My first SciATH job’, exitCode=0)

createExecuteCommand()

Returns a list containing the command, resource tuple for a job.

getMaxResources()

Returns a dict() defining the maximum required counts / values. for each valid resource associated with a job. This functionality is required for batch queue systems.

getResources()

Returns a dict() defining the compute resources required for this job.

setResources(**kwargs)

Define job resources (e.g. number of mpi ranks) via “resource_name”=number keyword=value pairs. The keywords used to identify the number mpi ranks is [‘ranks’, ‘Ranks’, ‘mpiranks’, ‘MPIRanks’]. The keywords used to identify the number of threads is [‘threads’, ‘ompthreads’]. Unrecognized resource types will produce an error.

view()

Display the contents of an Job instance to stdout. The parent->child relationship will be reported. Uninitialized non-essential members will not be reported. This includes: self.name; self.description; self.child.

class sciath.job.JobDAG(cmd, **kwargs)

A SciATH job sequence defined by a directed acyclic graph (DAG) (inherits from Job). The job sequence is determininstic and defined by performing a depth first search (DFS) on the provided DAG.

Args:

cmd (string): The command used to execute your application. **kwargs (name=value): A keyword argument list.

The Job constructor will recognize the following names:

name (string): textual name you want to assign to the job. description (string): desciption of what the job does. exitCode (int): the exit code which should be used to infer success.

createExecuteCommand()

Returns a list of command, resource tuples associated with a job DAG. The commands should be executed in order from first to last.

createJobOrdering()

Returns a list of job names in the order they will be executed.

getMaxResources()

Returns the max. resources required for a job seqeunce defined by a DAG. The max is taken over all jobs defined by the DAG and the parent job.

insert(dag)

Insert a directed acyclic graph (DAG) defining the job sequence. The parent job (self) must be present in the DAG. The parent job will be implicitly used as the root of the DAG when performing the depth first search required to infer the order the jobs will be executed.

Arg:

dag (dict): A dictionary defining vertex to vertex relationships.

Each vertex must be identified by a string, matching the job name (e.g. Job.name). Neighbour vertices (child jobs) must be iteratable, so put them in a list,e.g. [‘a’,’b’], or a tuple, e.g. (‘a’,’b’). Leaf vertices must be identified with the variable None. Leaf jobs must also be iteratable, e.g. use {“jobA” : [None] }.

Examples:

1. Consider the graph:

A –> B

The corresponding DAG using a dictionary is given by

dag = { ‘A’: [ ‘B’ ],

‘B’: [None] }

Note that in the above we used a list (e.g. []) to define the neighbour vertices.

2. Consider the graph:

   C

   /

A — B E

/

/

D —- F

The corresponding DAG using a dictionary is given by

dag = { ‘A’: ( ‘B’ ),

‘B’: ( ‘C’ , ‘D’ ), ‘D’: ( ‘E’ , ‘F’ ), ‘E’: (None), ‘F’: (None) }

Note that in the above we used tuples (e.g. ()) to define the neighbour vertices.

registerJob(job)

Register a dependent job. All jobs which will appear in your DAG must be registered. The dependent job is required to have the member job.name to be set. If a value has not been set, this function will modify job and define a default value for job.name.

view()

Display the contents of the job sequence via the DAG. The provided DAG will be displayed, along with the specific ordering in which the jobs will be executed.

class sciath.job.JobSequence(cmd, **kwargs)

A SciATH linear job sequence (inherits from Job)

A linear job sequence defines a parent job (job_0) and N depdendent jobs: job_1, job_2, …, job_N. A dependency graph is assumed from the order above; specifically we assume that job_{i} depends on the result of job_{i+1}, hence job_{i+1} will be executed before job_{i}. An arbitrary number of dependent jobs (N) may be defined.

Args:

cmd (string): The command used to execute your application. **kwargs (name=value): A keyword argument list.

The Job constructor will recognize the following names:

name (string): textual name you want to assign to the job. description (string): desciption of what the job does. exitCode (int): the exit code which should be used to infer success.

append(job)

Append a job into the sequence. The parent job is always first in the list. Dependent jobs appear after the parent.

createExecuteCommand()

Returns a list of command, resource tuples for a job sequence. The reverse order of the parent->child relationship is captured in the tuple returned. The commands should thus be executed in order from first to last.

getMaxResources()

Returns the max. resources required for a job sequence. The max is taken over all jobs registered via JobSequence.append() and the parent job.

view()

Display the contents of an job sequence to stdout. The parent will be reported first followed by its dependencies. Uninitialized non-essential members will not be reported. This includes: self.name; self.description; self.child.

sciath.launcher.FormattedHourMin(seconds)

sciath.launcher.FormattedHourMinSec(seconds)

class sciath.launcher.Launcher(confFileName=None)

clean(test)

configure()

createSubmissionFile(testname, commnd, ranks, ranks_per_node, walltime, outfile)

defaultConfFileName = 'SciATHBatchQueuingSystem.conf'

loadDefinition()

setBatchConstraint(argstring)

setHPCAccountName(name)

setMPILaunch(name)

setMaxRanksPerNode(n)

setQueueName(name)

setQueueSystemType(type)

setVerbosityLevel(value)

setup()

submitJob(test)

view()

static writeDefaultDefinition(confFileNameIn=None)

writeDefinition()

exception sciath.launcher.SciATHLoadException

sciath.launcher.formatMPILaunchCommand(mpiLaunch, ranks, corespernode)

sciath.launcher.generateLaunch_LSF(accountname, queuename, testname, mpiLaunch, execute, ranks, rusage, walltime, outfile)

sciath.launcher.generateLaunch_LoadLevelerBG(accountname, queuename, testname, execute, total_ranks, machine_ranks_per_node, walltime)

sciath.launcher.generateLaunch_PBS(accountname, queuename, testname, mpiLaunch, executable, ranks, ranks_per_node, walltime, outfile)

sciath.launcher.generateLaunch_SLURM(accountname, queuename, testname, constraint, mpiLaunch, execute, ranks, ranks_per_node, walltime, outfile)

sciath.launcher.setBlockingIOStdout()

class sciath._io.NamedColors

set_colors(use_bash=True)

sciath._io.dictView(d)

sciath._io.printv(level, verbosityLevel, *vargs)

sciath._io.py23input(prompt)