JobRunner API

This module allows running CREDO jobs using various approaches - e.g. via MPI locally, via PBS scripts in a queueing system, or via grid submission.

credo.jobrunner.api

System Message: WARNING/2 (/home/docs/sites/readthedocs.org/checkouts/readthedocs.org/user_builds/credo/checkouts/latest/doc/api/jobrunner.rst, line 11)

Could not execute ‘dot’. Are you sure you have ‘graphviz’ installed?

class credo.jobrunner.api.JobMetaInfo(simtime)

A simple class for recording meta info about a job, such as walltime, memory usage, etc.

simtime

Simulated time the model ran for.

readFromXMLNode(xmlNode)

verbPlatformString()

Returns a useful string about the platform, for printing.

writeInfoXML(xmlNode)

Writes information about this class into an existing, open XML doc node

class credo.jobrunner.api.JobRunner

Class used for running ModelRun instances. This is an abstract base class, user code will need to choose a concrete implementation. Is designed to allow both serial, and parallel non-blocking job submission and reporting.

runSuiteNonBlockingDefault

Determines that for a given job runner, whether suites should be run in non-blocking mode by default, or

profilers

List of PerformanceProfiler that will be applied to report on any ModelRuns that this JobRunner is used for.

defaultProfiler

Profiler that will be used to provide “default” results in the JobMetaInfo.

attachPerformanceInfo(jobMI)

Attach relevant performance information to the jobMI (JobMetaInfo), such as time use, memory use, etc

attachPlatformInfo(jobMI)

Attach provenance info relevant to the platform used to run the job to the JobMetaInfo object.

blockResult(modelRun, jobMetaInfo)

Block on a modelRun until the result is completed ... requires appropriate info to be passed in the jobMetaInfo object.

blockSuite(modelSuite, jobMetaInfos)

Blocks on each ModelRun in a Suite, given a list of JobMetaInfos for each run.

runModel(modelRun, prefixStr=None, extraCmdLineOpts=None, dryRun=False, maxRunTime=None)

Run the specified modelRun, and return the ModelResult.

Parameters:

• modelRun – the ModelRun to be run.
• prefixStr – optional precursor string for running the model, e.g. for timing.
• extraCmdLineOpts – if specified, these extra cmd line opts will be passed through on the command line to the run, extra to any ModelRun.simParams or ModelRun.paramOverrides.
• dryRun – If set to True, just print out what would be run, but don’t actually run anything.
• maxRunTime – maximum time (in seconds) a model should be allowed to run for before killing the job.

Returns:

A ModelResult recording the results of the run.

runSuite(modelSuite, prefixStr=None, extraCmdLineOpts=None, dryRun=False, maxRunTime=None, runSuiteNonBlocking=None, writeRecords=True)

Run each ModelRun in the suite - with optional extra cmd line opts. Will also write XML records of each ModelRun and ModelResult in the suite.

Input arguments same as for runModel(), except those listed below:

Parameters:

• runSuiteNonBlocking – controls whether the suite will be run “non-blocking”, i.e. all modelRuns submitted initially, then a separate phase to block until they’re all completed.
• writeRecords – sets whether you want each ModelRun in the suite, and each ModelResult generated, to automatically write an XML record of itself in default location as it is run/produced.

Returns:

a reference to the resultsList containing all the ModelResults generated.

setup()

Does any necessary setup checks to run models.

By default, does nothing - sub-classes need to override.

submitRun(modelRun, prefixStr=None, extraCmdLineOpts=None, dryRun=False, maxRunTime=None)

Submit the job to be run. TODO: comment on parameters ... Returns: a jobMetaInfo (that can later be attached ... )

submitSuite(modelSuite, prefixStr=None, extraCmdLineOpts=None, dryRun=False, maxRunTime=None, writeRecords=True)

Submits each modelRun in a suite to be run, and returns a list of all jobMetaInfos for the submitted jobs.

exception credo.jobrunner.api.ModelRunError(modelName)

Bases: exceptions.Exception

Base class of ModelRunError exception hierarchy.

exception credo.jobrunner.api.ModelRunLaunchError(modelName, runExecCmd, launchHint=None)

Bases: credo.jobrunner.api.ModelRunError

An Exception for when Models fail to run due to being unable to launch the run process in some way.

runExecCmd

command used to launch the job.

exception credo.jobrunner.api.ModelRunRegularError(modelName, retCode, stdOutFilename, stdErrFilename)

Bases: credo.jobrunner.api.ModelRunError

An Exception for when Models fail to run.

exception credo.jobrunner.api.ModelRunTimeoutError(modelName, stdOutFilename, stdErrFilename, maxRunTime)

Bases: credo.jobrunner.api.ModelRunRegularError

An Exception for when Models fail to run due to timing out.

maxRunTime

maximum time to run that the model exceeded, in seconds.

class credo.jobrunner.api.PerformanceProfiler(typeStr)

Class to use to attach to JobRunner instances, which will then profile performance of each ModelRun ran by given JobRunner.

This is an abstract base class, user code will have to select a concrete instantiation.

attachPerformanceInfo(jobMetaInfo, modelResult)

modifyRun(modelRun, modelRunCommand, jobMetaInfo)

setup(modelName, modelBasePath, modelOutputPath, jobMetaInfo)

Do any necessary setup functions.

credo.jobrunner.mpijobrunner

System Message: WARNING/2 (/home/docs/sites/readthedocs.org/checkouts/readthedocs.org/user_builds/credo/checkouts/latest/doc/api/jobrunner.rst, line 21)

Could not execute ‘dot’. Are you sure you have ‘graphviz’ installed?

class credo.jobrunner.mpijobrunner.MPIJobMetaInfo

Bases: credo.jobrunner.api.JobMetaInfo

writeInfoXML(xmlNode)

class credo.jobrunner.mpijobrunner.MPIJobRunner

Bases: credo.jobrunner.api.JobRunner

archiveRunCommand(modelRun, runCommand)

Save the given runCommand to a file in output directory.

attachPlatformInfo(jobMI)

blockResult(modelRun, jobMI)

setup()

submitRun(modelRun, prefixStr=None, extraCmdLineOpts=None, dryRun=False, maxRunTime=None)

See credo.jobrunner.api.JobRunner.submit().

credo.jobrunner.pbsjobrunner

System Message: WARNING/2 (/home/docs/sites/readthedocs.org/checkouts/readthedocs.org/user_builds/credo/checkouts/latest/doc/api/jobrunner.rst, line 31)

Could not execute ‘dot’. Are you sure you have ‘graphviz’ installed?

class credo.jobrunner.pbsjobrunner.PBSJobMetaInfo

Bases: credo.jobrunner.api.JobMetaInfo

writeInfoXML(xmlNode)

class credo.jobrunner.pbsjobrunner.PBSJobRunner

Bases: credo.jobrunner.api.JobRunner

A JobRunner to submit CREDO jobs via creating PBS script files, and submitting these via command-line utils like qsub.

Note

this module is currently still in development, and needs tuning for different HPC machines.

blockResult(modelRun, jobMetaInfo)

setup()

submitRun(modelRun, prefixStr=None, extraCmdLineOpts=None, dryRun=False, maxRunTime=None)

See credo.jobrunner.api.JobRunner.submit().

credo.jobrunner.unixTimeCmdProfiler

System Message: WARNING/2 (/home/docs/sites/readthedocs.org/checkouts/readthedocs.org/user_builds/credo/checkouts/latest/doc/api/jobrunner.rst, line 41)

Could not execute ‘dot’. Are you sure you have ‘graphviz’ installed?

class credo.jobrunner.unixTimeCmdProfiler.UnixTimeCmdHandle(resFName)

class credo.jobrunner.unixTimeCmdProfiler.UnixTimeCmdProfiler(fmtEls=None)

Bases: credo.jobrunner.api.PerformanceProfiler

A performance profiler that uses the Unix ‘time’ command.

fmtEls

Format elements to be used in determining what gets profiled.

attachPerformanceInfo(jobMetaInfo, modelResult)

modifyRun(modelRun, oldModelRunCommand, jobMetaInfo)

setup(modelName, modelBasePath, modelOutputPath, jobMetaInfo)

credo.jobrunner.unixTimeCmdProfiler.getFmtString(fmtEls, fmtSpec=', ', fmtSep='\n')

Return the format string to use, given a list of format elements, using standard separators, so it can be parsed later on.

Parameters:fmtEls –

a list of Tuples, of form (nameStr, fmtItem) - where nameStr is the name of the entry to return, and fmtItem is the ‘resource specifier’ character as specified in ‘man time’.

e.g. [(“runTime”, “E”)] - where “E” is the specifier for Elapsed time

credo.jobrunner.unixTimeCmdProfiler.getResDict(resFName, fmtSpec=', ', fmtSep='\n')

Get a dictionary of results, contained in the given resFName, formatted in the standard way as done by getFmtString.

credo.jobrunner.unixTimeCmdProfiler.getRunPrefix(resFName, fmtStr)

Get the prefix for a run that will apply the time command.

Do “man time” for more info.

Parameters:

• resFName – filename that ‘time’ profiling results should be saved to.
• fmtStr – format string to use.

credo.jobrunner.unixTimeCmdProfiler.parseUnixTimeElapsed(timeElapsedStr)