schrodinger.application.matsci.jobutils module

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.matsci.jobutils.add_outfile_to_backend(file_fn, backend, set_structure_output=False, stream=False)

Add output file to the backend.

Parameters:
  • file_fn (str) – Filename
  • backend (schrodinger.job._Backend or None) – Backend handle
  • set_structure_output (bool) – If True, set this structure as output
  • stream (bool) – If True, stream the file to the submission host
schrodinger.application.matsci.jobutils.log_structures_found(qjob, structure_files, log, jobstates_for_logging=None)

Log structures info for a job.

Parameters:
  • qjob (schrodinger.job.queue.JobControlJob) – The subjob to find structures
  • structure_files (dict) – Keys are subjobs, values are sets of structure file names
  • log (callable) – function(msg) writes msg to log file
  • jobstates_for_logging (None or list of str) – Log info for subjobs in these states
schrodinger.application.matsci.jobutils.run_jobdj_and_add_files(jobdj, log, expect_exts=None)

Run the subjobs currently queued up in the jobdj, adding their files to the current backend for copying back to the job directory and locating the expected structure output file for each job.

Parameters:
  • jobdj (schrodinger.job.queue.JobDJ) – The JobDJ with queued up jobs to run
  • log (callable) – function(msg) writes msg to log file
  • expect_exts (None or list of str) – The expected extensions of the output files
Return type:

list
Returns:

A list of structure output file names, sorted alphabetically
schrodinger.application.matsci.jobutils.finalize_subjob(subjob, backend, structure_files, structure_extensions, log)

Mark subjob output and log files for copying back to the job directory, and find the structure output file if there is one

Parameters:
  • subjob (schrodinger.job.queue.JobControlJob or None) – The subjob to mark files from
  • backend (schrodinger.job.jobcontrol._Backend or None) – The current backend or None if there isn’t one
  • structure_files (dict) – If an output structure file is found, it will be added to this dict. Keys are subjobs, values are sets of structure file names
  • structure_extensions (list of str) – The expected extension of the structure files
  • log (function) – function(msg) writes msg to log file
Return type:

bool
Returns:

True if the job has completed, False if not
schrodinger.application.matsci.jobutils.add_subjob_files_to_backend(subjob, path=None, backend=None)

Add all the output and log files from a subjob to the backend of this job so that they get copied back to the original job directory.

Note:

subjob log files are added as output files instead of log files. They will not be streamed back to the original job directory but instead copied back at the end of this job like a normal output file.
Parameters:

directory as this job

Parameters:backend (schrodinger.job.jobcontrol._Backend) – The backend if one exists
schrodinger.application.matsci.jobutils.set_source_path(struct, backend=None, job=None)

Set the source path property to the original job directory. This is obtained from the job control Job object for this process. If no Job object is found, the current directory is used.

Parameters:
  • struct (schrodinger.structure.Structure) – The structure to set the property on. Note that property setting works properly on both Structure and Cms objects.
  • backend (schrodinger.job.jobcontrol._Backend) – The job control backend. Will be used to obtain the job object if no job is supplied. If neither backend or job are supplied, the backend will be obtained from job control (if one exists).
  • job (schrodinger.job.jobcontrol.Job) – The job control job for this process. If not supplied, will be obtained from the backend (if one exists).
Return type:

str
Returns:

The directory set as the source path. Will be either the OrigLaunchDir property of the job or the current directory if not running under job control.
schrodinger.application.matsci.jobutils.get_source_path(source, existence_check=True)

Get the source path to the original job directory

Parameters:
  • source (schrodinger.structure.Structure or schrodinger.project.ProjectRow) – Either the ProjectRow or the structure to obtain the source information from. If a structure, can be either a Structure or a Cms object.
  • existence_check (bool) – If True (default), a blank string will be returned if the source path does not exist. If False, the path is returned regardless of whether it exists or not.
Return type:

str
Returns:

The original job directory or a blank string if none is found

Change the Jaguar file link properties to point to the original job directory instead of the subjob directory

Parameters:struct (schrodinger.structure.Structure) – The structure to fix
schrodinger.application.matsci.jobutils.prepare_job_spec_builder(argv, program_name, default_jobname, input_fn=None, set_driver_reserves_cores=False, schrodinger_product=None)

Prepare generic job specification builder. If set_driver_reserves_cores script (driver) is set to True, script is expected to use all the cores (cpus), similar to umbrella mode in multisim. For an example see stress-strain driver. For all other cases (such as in opto/hopping/amorphous) keep set_driver_reserves_cores to False.

Parameters:
  • argv (list) – The list of command line arguments, including the script name at [0], similar to that returned by sys.argv
  • program_name (str) – Program name
  • default_jobname (str) – Default job name
  • input_fn (str) – Input filename
  • set_driver_reserves_cores (bool) – If True, enable launchapi.setDriverReservesCores
  • schrodinger_product (str) – A product directory to search for the script/executable. This should be the name of a directory under SCHRODINGER without the trailing version (i.e. the “-v*” part).
Return type:

launchapi.JobSpecificationArgsBuilder
Returns:

Job specification builder object
schrodinger.application.matsci.jobutils.add_folder_to_job_builder(job_builder, folder_path)

Add folder (trajectory folder) to job directory.

Parameters:
  • job_builder (launchapi.JobSpecificationArgsBuilder) – Job specification builder object.
  • folder_path (str) – Full path to the folder that needs to copied.
schrodinger.application.matsci.jobutils.get_stripped_defaults(adict)

Remove dashes in the beginning of the keys. Used with ArgumentParser.

Parameters:adict (dict{string:any}) – Dictionary of defaults
Return type:dict{string:any}

@rparam: Dictionary of defaults with dashed stripped from the keys

schrodinger.application.matsci.jobutils.get_matsci_user_data_dir()

Get the absolute path to the user’s local MatSci data directory for storing custom templates, protocols, etc. Directory is created if it doesn’t exist.

Return type:str
Returns:The absolute path the Materials Science data parent directory
schrodinger.application.matsci.jobutils.parse_restart_parameters_file(path)

Parse parameters file.

Format of the file: 1st line is driver’s filename 2nd line is original arguments passed to the driver

Parameters:path (str) – Path to the file with original arguments
Return type:dict
Returns:Dictionary with parsed values
schrodinger.application.matsci.jobutils.write_restart_parameters_file(driver, args, outpath)

Write out original arguments to parameters file and add the file as an output file to any existing jobcontrol backend.

Parameters:
  • driver (str) – Driver’s filename
  • args (list) – Original arguments passed to driver
  • outpath (str) – Path to the parameters file to write original arguments
schrodinger.application.matsci.jobutils.get_restart_id_filename(jobname)

For the given restart jobname, return the name of the file containing the job id.

Return type:str
Returns:The name of the restart jobid file
schrodinger.application.matsci.jobutils.extract_job_data(options)

Unzip the archive in the current directory. All the error handling is on the caller function.

Parameters:options (argparse.Namespace) – The object holding all the option values
schrodinger.application.matsci.jobutils.archive_job_data(path, files_path)

Create a gzipped tar archive in the current directory from the provided list of file paths. All the error handling is on the caller function.

Parameters:
  • path (files_path) – Path to the new archive to be created
  • path – List of files to be archived
schrodinger.application.matsci.jobutils.create_restart_launcher(script, prog, input_name, output_name, zip_name, options, args)
schrodinger.application.matsci.jobutils.create_restart_jobcmd(driver_path, zip_fn, restart_options, args, default_jobname)

Generate command-line list for the job restart.

Parameters:
  • driver_path (str) – Path to the driver
  • zip_fn (str) – Filename of the archive with all restart files
  • restart_options (argparse.Namespace) – The object holding all the option values
  • args (list) – List of the arguments passed to the original run
  • default_jobname (str) – Default job name
Return type:

list

@rparam: List of parameters ready for job submission

schrodinger.application.matsci.jobutils.write_idfile(jobobj)

Store the job id in a file as a signal to the GUI that a new job has been launched.

Parameters:jobobj (schrodinger.job.jobcontrol.Job) – The object holding all the option values
schrodinger.application.matsci.jobutils.get_option(options, flag)

Return the option value associated with flag

Parameters:
  • options (argparse.Namespace) – The object holding all the option values
  • flag (str) – The flag for the desired option.
Return type:

any
Returns:

The value associated with flag, or None if flag (minus any leading dashes) is not found as a property on options
schrodinger.application.matsci.jobutils.set_option(options, flag, value)

Set the option value associated with flag

Parameters:
  • options (argparse.Namespace) – The object holding all the option values
  • flag (str) – The flag for the desired option. If the string starts with a ‘-‘, the ‘-‘ is removed.
  • value (any) – The value to set the option.flag value to
schrodinger.application.matsci.jobutils.add_restart_parser_arguments(parser)

Add restart arguments to the parser

Parameters:parser (argparse.ArgumentParser) – The parser to add arguments to
schrodinger.application.matsci.jobutils.get_restart_options(options)

Get the command line options from the -restart_x flags

Return type:tuple
Returns:tuple of strings (viewname, incorporation, project, host:cpu, jobname)
schrodinger.application.matsci.jobutils.add_keyword_parser_argument(parser, arghelp=None)

Add a keyword argument to the parser

Parameters:parser (argparse.ArgumentParser) – The parser to add this argument to
schrodinger.application.matsci.jobutils.parse_keyword_list(options, exit_on_error=True, logger=None, validate=False)

Adds keystring and keydict properties to the argparse options object that are the list of keyword arguments turned into, respectively, a string or a dictionary. Valid keyword syntax is checked for.

Typical usage:

jobutils.add_keyword_parser_argument(parser) options = parser.parse_args(args) jobutils.parse_keyword_list(options) print options.keystring, options.keydict

Parameters:
  • options (argparse.Namespace) – The parser Namespace object with a keywords attribute
  • exit_on_error (bool) – True if the ValueError for keyword syntax should result in a message being printed and sys.exit() being called, False if the error should just be raised.
  • logger (logging.Logger) – The logger to use for recording error messages, otherwise they’ll be printed.
  • validate (bool) – Whether keywords/values not recognized by Jaguar should be considered an error.
Raises:

ValueError – If an invalid keyword pair syntax is detected and handle_error is False
:raises schrodinger.application.jaguar.validation.JaguarKeywordException
if validate=True, exit_on_error=False and an invalid Jaguar keyword/value has been used.
schrodinger.application.matsci.jobutils.add_save_desmond_files_parser_argument(parser)

Add a SAVE_FLAG argument to the parser

Parameters:parser (argparse.ArgumentParser) – The parser to add this argument to
schrodinger.application.matsci.jobutils.add_desmond_parser_arguments(parser, args, defaults=None)

Add desmond related arguments to the parser

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add this argument to
  • args (list) – List of arguments to add to the parser
  • defaults (dict or None) – Default values for the arguments
schrodinger.application.matsci.jobutils.add_random_seed_parser_argument(parser)

Add the command line flag for the random number seed

Parameters:parser (argparse.ArgumentParser) – The parser to add this argument to
schrodinger.application.matsci.jobutils.seed_random_number_generator(options, log=None)

Seed the random number generator based on the command line options. If there is no seed in the command line options, a random value is used.

Parameters:
  • options (argparse.Namespace) – The command line options from argparse. Note that passing in None for options will have the same affect as if the seed flag does not exist on options (i.e. a random value will be generated).
  • log (function) – A function to log the seed value. Should take a single str argument.
Return type:

int
Returns:

The seed used for the generator
schrodinger.application.matsci.jobutils.check_license(panel=None, token=94, name='', as_validator=False)

Check if a valid token exists

Parameters:
  • panel (schrodinger.ui.qt.appframework.AppFramework) – panel to use to put up an error dialog if no license
  • token (schrodinger.utils.license constant) – A token type from the schrodinger.utils.license module, such as MATERIALSCIENCE_MAIN or MATERIALSCIENCE_GA
  • name (str) – The user-identifiable name for the token - used for error messages. If not provided, the string used in the license module for this token (if one exists) will be used.
  • as_validator (bool) – If True, this function will work as an AF2 validation method. Instead of posting a dialog or printing a message for a failed license check, it will return (False, error_message).
Return type:

bool or (bool, str)
Returns:

True if valid license exists. If no valid license exists, False will be returned by default, but (False, msg) will be returned if as_validator=True. Note that (False, msg) evalutes to True so must be handled by the calling routine as not a boolean if as_validator=True.
schrodinger.application.matsci.jobutils.create_run_dir(panel, jobname)

Create a subdirectory to run a job in, asking the user and removing existing directories if needed.

Parameters:
Return type:

str or None
Returns:

The path to the directory or None if an existing directory was found and the user elected not to remove it
schrodinger.application.matsci.jobutils.string_to_value(string)

Change a text string from a file to a value. Converts string values of special Python tokens such as True, False or None to the Python tokens. Converts numbers to int or float if possible.

Parameters:string (str) – The string to convert
Returns:string converted to, in order of preference: [True|False|None], int, float, or input type
schrodinger.application.matsci.jobutils.working_directory(path)

A context manager which changes the working directory to the given path, and then changes it back to its previous value on exit.

class schrodinger.application.matsci.jobutils.StringCleaner(extra_replacement_pairs=None, separator='-')

Bases: object

Manages the cleaning of strings.

__init__(extra_replacement_pairs=None, separator='-')

Populate an instance with some defaults. The replacement dictionary needs to be set such that the most specific replacements occur last. This is because the replacements should be done in a certain order, for example (‘C:’, ‘’) should be done before (‘:’, ‘’) and (‘’, ‘’), and because people tend to append to an iterable rather than prepend we will traverse the iterable backwards.

Parameters:
  • extra_replacement_pairs (list of tuples) – each tuple in this list contains a single replacement pair, i.e. a single substring to be replaced and a single substring to replace it.
  • separator (str) – in the case of non-unique strings this is the string that separates the non-unique part from the number of times used which is the unique part.
cleanAndUniquify(input_str, clear_prev=False, max_len=100)

Shorten if necessary, replace certain characters in an input string and then uniquify the string by comparing with a dictionary of previous names and number of times used.

Parameters:
  • input_str (str) – the input string we want cleaned and uniqified
  • clear_prev (bool) – specify if the dictionary of previous names should first be cleared
  • max_len (int) – maximum length of the input_str allowed, otherwise it will be shortened to the max_len value
Return type:

str
Returns:

the input string now cleaned and uniquified
schrodinger.application.matsci.jobutils.clean_string(string, default='title')

Cleans the given string by removing special characters to make it acceptable for a file name. If the string is blank, it will be replaced by the value of default.

Parameters:
  • string (str) – The string to clean.
  • default (str) – The name to use if string is blank
Return type:

str
Returns:

A string usable as a filename
schrodinger.application.matsci.jobutils.zip_and_set_incorporation(zipname, filelist)

Zip up all the requested files and set the resulting archive as the job control backend structure output file (if runnning under job control).

Parameters:
  • zipname (str) – The name of the archive to create
  • filelist (list) – Each item in filelist is the name of a file to add to file zipname
schrodinger.application.matsci.jobutils.escape_dollars_for_cmdline(pattern)

Make sure $ are escaped in the given pattern for command lines

Parameters:pattern (str) – A string to modify
Return type:str
Returns:pattern with a in front of $
class schrodinger.application.matsci.jobutils.CellRunInfo(structs, basename, replicate, multiple_cells, component=None, repeat_unit_info=None)

Bases: object

Holds the information for the run for a single cell

__init__(structs, basename, replicate, multiple_cells, component=None, repeat_unit_info=None)

Create a CellRunInfo object

Parameters:
  • structs (list) – The list of structures to include in the cell
  • basename (str) – The generic basename for job files. This will be modified based on the value of replicate, component and multiple_cells to form the base name for files for this specific cell.
  • replicate (int) – Which replicate this is for - 1-based
  • multiple_cells (bool) – Whether there will be multiple replicates of this cell
  • component (int or None) – The structure number this cell is for, or None if this is a mixed structure cell
  • repeat_unit_info (list or None) – Each item of the list is a tuple. The first item of the list is the sequence of monomer one-letter codes that give the repeat unit sequence. The second item is a tag to be added to the polymer name for that sequence (used for enumerated sequences)
class schrodinger.application.matsci.jobutils.MultijobDriver(runlist, options, args, log, remote_script, default_jobname, basename=None)

Bases: object

Resubmit the driver as subjobs

COMPOSITION_FLAG = '-composition'
COMPOSITION_FLAG_SHORT = '-c'
__init__(runlist, options, args, log, remote_script, default_jobname, basename=None)

Create multiple cells in parallel running a subjob for each cell. Zip up the resulting cms files into a jobname.zip file and set it as the structure output file to be incorporated.

Parameters:
  • runlist (list of CellRunInfo) – Each item of runlist will generate a subjob and a single cell
  • options (argparse.Namespace) – The command line options
  • args (iterable) – The command line arguments as passed in by sys
  • log (function) – function(msg) writes msg to log file
  • remote_script (string) – the dir and name for driver to resubmit
  • default_jobname (string) – Default job name
  • basename (str or None) – The generic basename defined from inputfile.
remove_flag(args, flag, and_value=False)

Remove a flag from the comand line flags

Parameters:
  • args (list) – The list of command line arguments
  • flag (str) – The flag to remove
  • and_value (bool) – Also remove the value associated with the flag - it is assumed that this is the following list item
replace_value(args, old_value, new_value)

Replace the list item with value=old_value with the new value

Parameters:
  • args (list) – The list of command line arguments
  • old_value (str) – The value to replace
  • new_value (str) – The value to replace old_value with
multijob_driver(runlist, options, args, basename, log, remote_script)

Create multiple cells in parallel running a subjob for each cell. Zip up the resulting cms files into a jobname.zip file and set it as the structure output file to be incorporated.

Parameters:
  • runlist (list of CellRunInfo) – Each item of runlist will generate a subjob and a single cell
  • options (argparse.Namespace) – The command line options
  • args (iterable) – The command line arguments as passed in by sys
  • basename (str) – The zipped .zip or . maegz filename for all job files.
  • log (function) – function(msg) writes msg to log file
  • remote_script (string) – the dir and name for driver to resubmit
schrodinger.application.matsci.jobutils.get_jobname(default_jobname)

Return a the jobname from backend, command line (-NAMEJOB / environment), DEFAULT_JOBNAME

Parameters:default_jobname (str) – default_jobname of the current module
Return type:string
Returns:Jobname
schrodinger.application.matsci.jobutils.get_procs()

Get number of processors from backend or command-line arguments.

Return type:int
Returns:Number of processors
schrodinger.application.matsci.jobutils.memory_usage_psutil()

return the memory usage in MB

Return type:float
Rparam:memory usage in MB
schrodinger.application.matsci.jobutils.get_size_of(an_object, size_unit='megabytes')

Return the size of an object in size_unit. The object can be any type of object. All built-in objects will return correct results, but this does not have to hold true for third-party extensions as it is implementation specific.

Parameters:an_object (any type of python object) –
Returns:the size of an object in size_unit
Return type:float
schrodinger.application.matsci.jobutils.get_jobhost_name()

Return the job host name from backend or command line.

Return type:str or None
Rparam:the host name
schrodinger.application.matsci.jobutils.is_hostname_known(hostname)

Check whether hostname is defined in the host file.

Parameters:hostname (str) – the hostname to check against
Return type:bool
Rparam:True, if the hostname is defined in the host file
schrodinger.application.matsci.jobutils.is_jobhost_gpu_available()

Check whether the gpu is available on the host. First check SUBHOST, if defined. Then, check HOST, if defined. At last, check localhost.

Return type:bool
Rparam:True means gpu is available.