schrodinger.application.matsci.qubec_utils module

Utilities for QUBEC.

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.matsci.qubec_utils.qubec_error(msg)

Return an error message flagged with QUBEC.

Parameters

msg (str) – the error message

Return type

str

Returns

the error message flagged with QUBEC

exception schrodinger.application.matsci.qubec_utils.QubecException

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

schrodinger.application.matsci.qubec_utils.write_input_file(base_name, adict)

Write the input json file.

Parameters

• base_name (str) – the base name of the input file to be written

• adict (dict) – job parameters

schrodinger.application.matsci.qubec_utils.read_input_file(base_name)

Read the input json file.

Parameters

base_name (str) – the base name of the input file to be read

Raises

QubecException – if there is an issue

Return type

dict

Returns

job parameters

schrodinger.application.matsci.qubec_utils.type_input(arg)

Validate the input.

Parameters

arg (str or unicode) – the input file to validate

Raises

argparse.ArgumentTypeError – if the given input is invalid

Return type

str

Returns

the str-ed input file

class schrodinger.application.matsci.qubec_utils.Job(*args, **kwargs)

Bases: schrodinger.job.jobcontrol.Job

Job class to handle cancelling a QUBEC job.

__init__(*args, **kwargs)

See parent class for documentation.

setQubecJob(qubec_job)

Set the QUBEC job.

Parameters

qubec_job (QubecJob) – the QUBEC job

cancel()

See parent class for documentation.

property BatchId: Optional[str]

Return the batch id, if running on an HPC queueing system. Otherwise return None.

property Commandline: str

Return the command used to launch the job.

Note that this may not be accurate when the job is called directly from a jobspec. In that case it will instead return the commandline of the parent process.

property Dir: str

Return the absolute path of the launch directory.

property DisplayStatus: Optional[schrodinger.job.jobcontrol.DisplayStatus]

Return a user-focused status that indicates the current state of the job.

Returns None in the case of non JOB_SERVER jobs.

property Envs: List[str]

Return a list of environment varaibles that are set by job, in addition to a default environment on a machine. The format is [“SPECIAL_VAR=0”, “SPECIAL_VAR2=yes”]

property Errors: List[str]

Return possible error messages associated with a job. This will only return values in legacy jobcontrol.

property ExitCode: Union[int, str]

Returns the exit code of a process. If the job is still running, or it was killed without collecting the exit code, return a string indicating unknown status.

property ExitStatus: str

Get the ExitStatus of the job. This is a string representation of a job. Consider using DisplayStatus instead.

Raises

RuntimeError if the job is not yet complete.

property Host: str

Return the hostname of the host which launched this job.

property HostEntry: str

Return the name of the host entry this job was launched to.

property InputFiles: List[str]

Return list of files that will be transferred to the job directory on launch.

property JobDB: str

Path to the Job Database in legacy jobcontrol. This is an empty str for JOB_SERVER jobs.

property JobDir: str

Return the directory where the job is run. This will be an empty string if the job has not yet started.

property JobHost: str

Return the hostname where the job is run. This will be an empty string if the job has not yet started.

property JobId: str

Return an identifier for a job.

property JobSchrodinger: str

Return the directory of Schrodinger installation where the job is running.

property LaunchTime: str

Return a string timestamp for the time that the job was launched. This will before the job starts running, as soon as it is registered with jobcontrol as a job to be run.

property Licenses: List[str]

Return a list of licenses needed for the job in the format ‘license_name:tokens’.

property LogFiles: List[str]

Get list of log files associated with a log. May be an empty list.

property Name: str

Returns a string representing -JOBNAME that was specified on launch. This may be an empty string.

property OrigLaunchDir: str

Return the launch directory of the oldest ancestor of this job.

property OrigLaunchHost: str

Return the hostname of the oldest ancestor of this job.

property OutputFiles: List[str]

Return a list of output filenames which will be copied back, if existing, at the end of a job.

Note that this list can grow while the backend is running, since output files can be registered by the backend.

property ParentJobId: Optional[str]

Return the jobid of a parent job. If the job does not have a parent, return None.

property Processors: int

For a batch job, returns the number of queue slots attached to this job. For a local job, return the number of CPU cores allowed to be used.

property Program: str

Return descriptive text for the name of the program running this job, e.g. Jaguar. This field is optional and may return an empty string.

property Project: str

Return the job’s project name field. This will be an empty string if no project is set.

property QueueHost: str

Return the hostname of the submission node of a HPC queueing system. If not an HPC host, this will be an empty string.

property StartTime: str

Return a string for the starting time of the job. Returns an empty string if the job is not yet started, for example, enqueued in an HPC environment.

property Status: str

Get the Status of the job. This is used by legacy jobcontrol API, but is superseded by DisplayStatus for JOB_SERVER jobs.

property StatusChangeReason: str

Returns a human-readable reason that a job entered its current state, such as “job canceled by the user.” If the reason was not recorded or is not particularly interesting (e.g. normal transition from waiting to running) it may be the empty string.

property StatusTime: str

Return a string for the time when the job was last updated.

property StopTime: str

Return a string for the completion time of the job. Returns an empty string if the job is not yet completed.

property StructureOutputFile: str

Return the name of the file returned by the job that will get incorporated into a project of Maestro. Returns an empty string if no file is specified.

property SubJobs: List[str]

Return list of subjob job ids.

property User: str

Return the username of user who launched the job.

property Version: str

Return the build number.

property Viewname: str

Return a representation of name used to filter jobs in maestro. May be empty.

download()

Download the output of the job into job’s launch directory. No-op in legacy jobcontrol.

get(attr, default=None)

This function will always raise an error, but is provided to guide users to a new syntax.

getApplicationHeaderFields(default=None) → Dict[str, str]

Returns a dictionary of commonly used jobcontrol keyword:value pairs used to standardize application log files.

Parameters

default (any) – Value assigned to a keyword if the corresponding attribute is not defined.

getApplicationHeaderString(field_sep: str = ' : ') → str

Returns a formatted string, suitable for printing at the top of a log file printing helpful information about the state of the job.

Parameters

field_sep – String that delimits the keyword and value.

Example:

backend = schrodinger.job.jobcontrol.get_backend()
if backend:
    print backend.getJob().getApplicationHeaderString()

getDuration() → Optional[int]

Returns the wallclock running time of the job if it is complete. This does not include time is submission status. Returns time in seconds. If the job is not complete, returns None.

getInputFiles() → List[str]

getOutputFiles() → List[str]

getProgressAsPercentage() → float

Get the value of backend job progress in terms of percentage (values from 0.0 - 100.0)

Return 0.0 when a job is not yet in running state.

getProgressAsSteps() → Tuple[int, int]

Get the value of backend job progress in terms of steps and totalsteps. Return (0,1) when a job is not yet in ‘running’ state.

getProgressAsString() → str

Get the value of backend job progress in terms of descriptive text. Return “The job has not yet started.” when a job is not yet in running state.

isComplete(wait_for_exited=False) → bool

Returns True if the job is complete.

Note that this does not necessarily mean the output files have been downloaded.

Parameters

wait_for_exited – If set, wait for the job to be completed, as long as the job’s ExitStatus is set. (This only makes sense for legacy jobcontrol jobs.)

isDownloaded()

Check if output files were downloaded. For legacy job control, identical to isComplete().

Returns

Whether the job files were downloaded.

Return type

bool

isQueued() → bool

Returns True if the job runs on a HPC queueing system.

kill()

Kill the job if it is running. This cancels a running job and does not return output files.

kill_for_smart_distribution() → bool

Kill the job for smart distribution. This method cancels a job successfully when waiting or sitting in the queue.

Return True if canceled, False otherwise.

purgeRecord()

Purge the job record for the job from the database.

readAgain()

Reread the database. Calling this routine is necessary to get fresh values.

stop()

Kill the job while collecting output files.

succeeded() → bool

Returns False if the job was killed, died or fizzled. Returns True if ExitStatus is finished.

Raises

RuntimeError – if the job isn’t completed, so use isComplete() before calling.

summary() → str

Return a string summarizing all current Job attributes.

wait(max_interval: int = 60, throw_on_failure: bool = False)

Wait for the job to complete; sleeping up to ‘max_interval’ seconds between each database check. (Interval increase gradually from 2 sec up to the maximum.)

NOTE: Do not use if your program is running in Maestro, as this

will make Maestro unresponsive while the job is running.

Parameters

throw_on_failure (bool) – whether to raise an exception if not succeeded

Raises

RuntimeError – if the job did not succeed. The error message will contain the last 20 lines of the job’s logfile (if available).

wait_before_kill()

class schrodinger.application.matsci.qubec_utils.Qubec(st, params, logger=None)

Bases: object

Manage a QUBEC job.

__init__(st, params, logger=None)

Create an instance.

Parameters

• st (schrodinger.structure.Structure) – the structure

• params (dict) – the QUBEC job parameters

• logger (logging.Logger or None) – output logger or None if there isn’t one

login()

Log in.

Raises

QubecException – if there is an issue

getParams()

Return the job parameters.

Return type

dict

Returns

the job parameters

prepareOutput()

Prepare the output.

run()

Run the job.

Raises

QubecException – if there is an issue