schrodinger.test.scival module¶
Tools used by SciVal test writers. Of most common use will be’
JobControlJob
and Reporter
. Every group of SciVal tests should
probably have a Reporter
.
- class schrodinger.test.scival.JobControlJob(command: List[str], suite: str, name: str, command_dir: Optional[str] = None, max_retries: Optional[int] = None, launch_env_variables: Optional[Dict[str, str]] = None, **kwargs)¶
Bases:
schrodinger.job.queue.JobControlJob
- __init__(command: List[str], suite: str, name: str, command_dir: Optional[str] = None, max_retries: Optional[int] = None, launch_env_variables: Optional[Dict[str, str]] = None, **kwargs)¶
Initialize a job object for SciVal jobs, which also includes suite and name attributes.
- Parameters
command – commandline for launching job
suite – name of scival suite
name – job name, for annotation for JobDJ before job is running
command_dir – directory to launch job from, default to CWD
max_retries – Number of times to retry failed jobs, default is globally controlled by JobDJ.
launch_env_variabes – Extra environment variables to add to existing environment for job launching.
- kill(*args, **kwargs)¶
Send kill request to jobcontrol managed job
- addFinalizer(function: Callable[[schrodinger.job.queue.BaseJob], None], run_dir: Optional[str] = None)¶
Add a function to be invoked when the job completes successfully.
See also the add_multi_job_finalizer function.
- addGroupPrereq(job: schrodinger.job.queue.BaseJob)¶
Make all jobs connected to
job
prerequisites of all jobs connected to this Job.
- addPrereq(job: schrodinger.job.queue.BaseJob)¶
Add a job that is an immediate prerequisite for this one.
- cancel()¶
Send kill request to jobcontrol managed job. This method will eventually deprecate JobControlJob.kill
- cancelSubmitted() bool ¶
If the job is still in the ‘submitted’ state, cancel it, purge the jobrecord and set the job handle to None.
Return True if this was successful, False otherwise.
- doCommand(host: str, local: bool = False)¶
Launch job on specified
host
using jobcontrol.launch_job().- Parameters
host – Host on which the job will be executed.
local – Removed in JOB_SERVER.
- finalize()¶
Clean up after a job successfully runs.
- genAllJobs(seen: Optional[Set[schrodinger.job.queue.BaseJob]] = None) Generator[schrodinger.job.queue.BaseJob, None, None] ¶
A generator that yields all jobs connected to this one.
- genAllPrereqs(seen=None) Generator[schrodinger.job.queue.BaseJob, None, None] ¶
A generator that yields all jobs that are prerequisites on this one.
- getCommand() List[str] ¶
Return the command used to run this job.
- getCommandDir() str ¶
Return the launch/command directory name. If None is returned, the job will be launched in the current directory.
- getDuration() Optional[int] ¶
Return the duration of the Job as recorded by job server. The duration does not include queue wait time.
If the job is running or has not launched, returns None.
Note that this method makes a blocking call to the job server.
- getJob() Optional[schrodinger.job.jobcontrol.Job] ¶
Return the job record as a schrodinger.job.jobcontrol.Job instance.
Returns None if the job hasn’t been launched.
- getJobDJ() schrodinger.job.queue.JobDJ ¶
Return the JobDJ instance that this job has been added to.
- getPrereqs()¶
Return a set of all immediate prerequisites for this job.
- getStatusStrings() Tuple[str, str, str] ¶
Return a tuple of status strings for printing by
JobDJ
.The strings returned are (status, jobid, host).
- hasExited() bool ¶
Returns True if this job finished, successfully or not.
- hasStarted() bool ¶
Returns True if this job has started (not waiting)
- init_count = 0¶
- isComplete() bool ¶
Returns True if this job finished successfully
- maxFailuresReached(msg: str)¶
Print an error summary, including the last 20 lines from each log file in the LogFiles list of the job record.
- postCommand()¶
A method to restore things to the pre-command state.
- preCommand()¶
A method to make pre-command changes, like cd’ing to the correct directory to run the command in.
- retryFailure(max_retries: int = 0) bool ¶
This method will be called when the job has failed, and JobDJ needs to know whether the job should be retried or not.
JobDJ’s value for the max_retries parameter is passed in, to be used when the job doesn’t have its own max_retries value.
Return True if this job should be retried, otherwise False.
- run(*args, **kwargs)¶
Run the job.
- The steps taken are as follows:
Execute the preCommand method for things like changing the working directory.
Call the doCommand to do the actual work of computation or job launching.
Call the postCommand method to undo the changes from the preCommand that need to be undone.
- runsLocally() bool ¶
Return True if the job runs on the
JobDJ
control host, False if not. Jobs that run locally don’t need hosts.There is no limit on the number of locally run jobs.
- setup()¶
A method to do initial setup; executed after
preCommand
, just beforedoCommand
.
- property state: schrodinger.job.queue.JobState¶
Return the current state of the job.
Note that this method can be overridden by subclasses that wish to provide for restartability at a higher level than unpickling
BaseJob
instances. For example, by examining some external condition (e.g. presence of output files) the state JobState.DONE could be returned immediately and the job would not run.
- update()¶
Checks for changes in job status, and updates the object appropriately (marks for restart, etc).
- Raises
RuntimeError – if an unknown Job Status or ExitStatus is encountered.
- usesJobServer() bool ¶
Detect, by looking at the jobId, whether this job uses a job server.
- class schrodinger.test.scival.Reporter(buildtype: Optional[str] = None, build_id: Optional[str] = None)¶
Bases:
abc.ABC
Report results to the performance database when all jobs are complete. Based on queue._MultiJobFinalizer.
- NAME = None¶
- PRODUCT = None¶
- DESCRIPTION = None¶
- __init__(buildtype: Optional[str] = None, build_id: Optional[str] = None)¶
- Parameters
buildtype – NB or OB, or None if reporting not enabled
build_id – build-XXX or None if reporting not enabled
- addJob(job: schrodinger.test.scival.JobControlJob)¶
Add a job to the reporter.
- addAsFinalizer(job: schrodinger.job.queue.BaseJob)¶
- addResult(name: str, value: Union[int, float], units: Optional[str] = None)¶
Print the result. And report them when running under automated build either as NB or OB.
- Parameters
name – name of metric to report
value – value of metric
units – Optional units for value
- analyze(jobs: List[schrodinger.test.scival.JobControlJob])¶
If all jobs completed, loop over self.tests and use self.addResult() to generate data to be reported.
- class schrodinger.test.scival.JobDJ(*args, **kwargs)¶
Bases:
schrodinger.job.queue.JobDJ
- __init__(*args, **kwargs)¶
Constructor.
- Parameters
hosts – A list of hosts to run on. Items of the list can be a (<hostname>, <maximum_concurrent_subjobs>) tuple that gives a host name and the maximum number of processors that can be used on that host. Or, items of the list can be a
ResourceHost
object that provides a detailed listing of the number of processors on each host that can be used for jobs requesting specific resources. The list can mix tuple andResourceHost
items. If a host appears more than once (whether as a tuple orResourceHost
), the information in the multiple entries is added together. Processors in the tuple form are only considered usable by jobs that have resource_requirement=None (The default state for jobs). The default value of None for this parameter means the host information is determined automatically from the command line and is usually desired.local – No longer functional in JOB_SERVER.
max_retries – Number of allowed retries per subjob. If this is set, it is never overridden by the
SCHRODINGER_MAX_RETRIES
environment variable. If it is not set, the value in default_max_retries is used, andSCHRODINGER_MAX_RETRIES
is allowed to override. If you wish to disable restarting altogether, set this value to zero.default_max_retries – Number of allowed retries per subjob. This value can always be overridden by the
SCHRODINGER_MAX_RETRIES
environment variable. Default is zero.max_failures – Total number of allowed subjob failures before
JobDJ
exits. If it is not defined, a default of zero will be used (exit on any failure after attempting to restart), but this can be overridden with theSCHRODINGER_MAX_FAILURES
environment variable. To allow an unlimited number of subjob failures, set max_failures to the module level NOLIMIT constant.verbosity – There are three allowed verbosity levels: “quiet” - only warnings and errors are printed; “normal” -
JobDJ
progress is printed; and “verbose” - additional debugging info is printed. Default is “quiet”.job_class – The class to use as the default job constructor when the
addJob
argument is not aBaseJob
instance.update_delay – The number of seconds to wait between job control database reads for
JobControlJob
jobs. (This delay is for an individual job, not for any job database read.) Default is None, which causes the module level constant UPDATE_DELAY to be used.smart_dist_resources – Custom resources that the localhost provides for smart distribution. Jobs that require a custom resource that is not included in this list will not be run on the localhost even if smart distribution is turned on. This information is unused if smart distribution is off. Each item of the list is a string that defines a custom resource.
- Raises
HostTypeError – if the host argument or one of its items is of the wrong type
- run()¶
Call this method to run all jobs that have been added. The method will return control when all jobs have completed.
- Parameters
status_change_callback – A function to call every time a job status changes. For example, JobState.RUNNING->JobState.DONE. This function takes a single argument of a schrodinger.job.queue.BaseJob object.
periodic_callback – A command to call periodically, regardless of whether job status has changed or not. The function will be called without any arguments.
callback_interval – The interval at which the periodic interval will be called. This time is only approximately enforced and will depend on the timing delay settings (e.g. MONITOR_DELAY).
restart_failed – True (default) if previously failed jobs should be restarted, False if not.
- printStatus(job: Optional[schrodinger.job.queue.BaseJob] = None, action: Optional[str] = None)¶
Override base printStatus. Change formatting, replace printing the jobname with printing the test name (usually the same, but…), add printing of suite.
- Parameters
job – job object to print the status of, otherwise prints general status
action – custom string to print as status of a job, otherwise use standard status
- addJob(job: schrodinger.test.scival.JobControlJob, add_connected: bool = False, **kwargs)¶
Add a job to run. If
job
is not aBaseJob
instance, aBaseJob
instance is constructed withjob
as the first argument. The defaultBaseJob
class for theJobDJ
instance can be specified in the constructor forJobDJ
.Additional keyword arguments are passed on to the job constructor.
All job prerequisites and dependencies need to be specified before adding a job to
JobDJ
.- Parameters
add_connected – If True, for jobs with dependencies only one job per connected group should be added and all connected jobs will be discovered and added automatically. If False, it is the user’s responsibility to make sure that any prerequisites of a job are also added.
- addTests(item: _pytest.nodes.Item, build_id: Optional[str] = None, buildtype: Optional[str] = None)¶
Call the add_tests function in the Pytest Item.
- Parameters
item – Current node that represents an add_tests function
build_id – build-XXX matching current build, can be None if not reporting
buildtype – NB or OB, can be None if not reporting
- setItem(pytest_item: _pytest.nodes.Item)¶
Set the current Pytest Item.
Jobs added to the jobdj while the pytest_item is set to pytest_item will be associated with it for error reporting &c.
- clearItem()¶
Clear the current Pytest Item.
- getCommandDir() Optional[str] ¶
The default job launching directory
(matches BaseJob interface)
- Returns
directory of job launching, or None if CWD
- killAllJobsForSuite(suite: str)¶
Kill all running jobs using the named suite, remove all waiting jobs for with the named suite.
- property active_jobs: List[schrodinger.job.queue.BaseJob]¶
- property all_jobs: List[schrodinger.job.queue.BaseJob]¶
- static createResourceHost(host_info: Tuple[str, int], resource: Optional[str] = None) schrodinger.job.queue.ResourceHost ¶
Given a tuple of (hostname, procs), return a ResourceHost.
- Parameters
host_info (tuple) – The hostname and number of processors it has
resource (str) – The resource the host provides, if any. If not given, the host will only run jobs that have no resource_requirement.
- Return type
- Returns
The ResourceHost created from in the input data
- Raises
HostTypeError – If the provided host_info has the wrong format
- disableSmartDistribution()¶
Disable smart distribution of jobs.
Smart distribution allows subjobs to run on the machine that JobDJ is running on when JobDJ itself is running under a queuing system. This is usually desirable since the JobDJ process doesn’t generally consume significant computational resources and you don’t want to leave a queue slot mostly idle.
- property done_jobs: List[schrodinger.job.queue.BaseJob]¶
Successfully completed jobs, sorted into the order they were marked as completed by JobDJ.
- property failed_jobs: List[schrodinger.job.queue.BaseJob]¶
- getActiveProcCounts() Dict[str, int] ¶
Return a dictionary containing the number of active jobs on each host.
Any resource requirement of the active jobs is ignored.
- getActiveProcsOnHost(hostname: str, requirement: Optional[Union[str, schrodinger.job.resource.ComputeType]]) int ¶
Get the current number of processors on the given host that are currently occupied by jobs that request the given requirement
- Parameters
hostname – The host to check
requirement – The job requirement to check
- Returns
The number of currently used processors on hostname that provide requirement
- getFirstHost()¶
Get first host from the lists of hosts.
- Return type
str
- Returns
First host
- hasStarted() bool ¶
Returns True if JobDJ has started already
- isComplete() bool ¶
Returns True if JobDJ has completed, False otherwise.
- killJobs()¶
Kill all active jobs
- markForRestart(job: schrodinger.job.queue.BaseJob, action: str)¶
Mark a job as dead, but make sure that it gets restarted.
- Parameters
action – Describes the reason the job is being restarted.
- setHostList(host_list: List[Union[Tuple[str, int], schrodinger.job.queue.ResourceHost]])¶
Define compute hosts to run subjobs on.
Active jobs are not affected by a change in the host list.
- Parameters
host_list – A list of hosts to run on. See the documentation for the hosts parameter to the __init__ method of this class for additional information.
- Raises
HostTypeError – If one of the host_list items is not of the correct type
- setSmartDistribution(state: bool)¶
Set smart distribution of jobs.
- Parameters
state (bool) – Whether to enable smart distribution
- property total_active: int¶
The number of jobs currently running.
- property total_added: int¶
The number of individual jobs that have been added to the JobDJ instance.
- property total_failed: int¶
The number of jobs that have failed.
- property total_finished: int¶
The number of jobs that have finished successfully.
- property waiting_jobs: List[schrodinger.job.queue.BaseJob]¶
Jobs waiting to be started.
- schrodinger.test.scival.call_and_report(item: _pytest.nodes.Item, when: str, fxn: Callable, *args)¶
Execute a function and report its result to pytest.
A slightly modified version from _pytest.runner to deal with functions that don’t return the word “passed”.