schrodinger.application.matsci.jaguar_multistage_workflow_utils module

Utilities for Jaguar multistage workflow.

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.matsci.jaguar_multistage_workflow_utils.set_up_logger(related_filename)

Set up the logger used in this module.

Parameters:related_filename (str) – the base name of this file name will be used as the base name of the log file name if not running under job control, otherwise the job name will be used
exception schrodinger.application.matsci.jaguar_multistage_workflow_utils.InvalidStageFileError

Bases: Exception

Class for any exception that occurs when reading in a settings file

__init__

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

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

class schrodinger.application.matsci.jaguar_multistage_workflow_utils.ParentStageData(line)

Bases: object

Holds and manipulates data about a parent stage

__init__(line)

Create a ParentStageData instance from a line of text

Expected tab-delimited format:
parent_stage_# [WAVEFUNCTION] [HESSIAN] [ANALYSIS]
Parameters:line (str) – The line of text to create the instance from
static writeInheritableParentDataToFile(parent, wavefunction, hessian, datafile)

Write inheritable parent stage data to a file in a format that this class can read in.

Parameters:
  • parent (int) – The stage number of the parent stage
  • wavefunction (bool) – Whether to use the wavefunction from the parent stage
  • hessian (bool) – Whether to use the hessian from the parent stage
  • datafile (file) – The file to write the data to
static writeNonInheritableParentDataToFile(parents, datafile)

Write noninheritable parent stage data to a file in a format that this class can read in.

Parameters:
  • parents (list) – the stage numbers of the parent stages
  • datafile (file) – the file to write the data to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.GeomConstraint(line)

Bases: object

Holds and manipulates data about geometry constraints

__init__(line)

Create a GeomConstraint instance from a line of text

Expected tab-delimited format:
entry_id target value index index …
Parameters:line (str) – The line of text to create the instance from
static writeData(eid, target, ctype, idxs, afile)

Write the given data to file.

Parameters:
  • eid (str) – the entry ID
  • target (float or None) – the target value for the constraint if there is one
  • ctype (int) – the Jaguar constraint type
  • idxs (list) – contains indices of atoms defining the constraint
  • afile (file) – the file to write the data to
static writeModelDataToFile(model, datafile, eid)

Write geometry constraint data from a model to a file in a format that this class can read in

Parameters:
  • model (schrodinger.application.jaguar.gui.tabs.optimization_tab. ContraintCoordinatesModel) – The model containing restraints to write
  • datafile (file) – The file to write the data to
  • eid (str) – The entry id for this geometry constraint
static writeDictDataToFile(adict, datafile)

Write geometry constraint data from a dictionary to a file in a format that this class can read in

Parameters:
  • adict (dictionary) – keys are entry IDs, values are lists of GeomConstraint
  • datafile (file) – The file to write the data to
applyToJaguarInput(jagin)

Apply this geometry constraint to a JaguarInput object

Parameters:jagin (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to apply this constraint to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.ActiveCoord(line)

Bases: object

Holds and manipulates data about active coordinates

__init__(line)

Create an ActiveCoord instance from a line of text

Expected tab-delimited format:
entry_id type index index …
Parameters:line (str) – The line of text to create the instance from
static writeData(eid, ctype, idxs, afile)

Write the given data to file.

Parameters:
  • eid (str) – the entry ID
  • ctype (int) – the Jaguar active coordinate type
  • idxs (list) – contains indices of atoms defining the active coordinate
  • afile (file) – the file to write the data to
static writeModelDataToFile(model, datafile, eid)

Write active coordinate data using a geometry constraint model to a file in a format that this class can read in

Parameters:
  • model (schrodinger.application.jaguar.gui.tabs.optimization_tab. ContraintCoordinatesModel) – The model containing active coordinates to write
  • datafile (file) – The file to write the data to
  • eid (str) – The entry id for this active coordinate
static writeDictDataToFile(adict, datafile)

Write active coordinate data from the given dictionary to a file in a format that this class can read in

Parameters:
  • adict (dict) – keys are entry IDs, values are lists of ActiveCoord
  • datafile (file) – The file to write the data to
applyToJaguarInput(jagin)

Apply this active coordinate to a JaguarInput object

Parameters:jagin (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to apply this active coordinate to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.AtomBasis(line)

Bases: object

Holds and manipulates data about by-atom basis sets

__init__(line)

Create a AtomBasis instance from a line of text

Expected tab-delimited format:
entry_id index basis_set
Parameters:line (str) – The line of text to create the instance from
static writeData(eid, anum, basis, afile)

Write the given data to file.

Parameters:
  • eid (str) – the entry ID
  • anum (int) – the atom number
  • basis (str) – the basis
  • afile (file) – the file to write the data to
static writeModelDataToFile(model, datafile)

Write by-atom basis set data from a model to a file in a format that this class can read in

Parameters:
  • model (schrodinger.application.jaguar.gui.tabs.sub_tab_widgets. basis_set_widgets.BasisSetModel) – The model containing restraints to write
  • datafile (file) – The file to write the data to
static writeDictDataToFile(adict, datafile)

Write by-atom basis set data from a dictionary to a file in a format that this class can read in

Parameters:
  • adict (dict) – keys are entry IDs, values are lists of AtomBasis
  • datafile (file) – The file to write the data to
applyToJaguarInput(jagin)

Apply this basis set to a JaguarInput object

Parameters:jagin (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to apply this atom basis set to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.ChargeConstraint(line)

Bases: object

Holds and manipulates data about by-atom charge constraints

__init__(line)

Create a ChargeConstraint instance from a line of text

Expected tab-delimited format:
entry_id index basis_set
Parameters:line (str) – The line of text to create the instance from
static writeData(eid, charge, weights, afile)

Write the given data to file.

Parameters:
  • eid (str) – the entry ID
  • charge (float) – the charge
  • weights (dict) – keys are atom indices, values are float weights
  • afile (file) – the file to write the data to
static writeModelDataToFile(model, datafile)

Write by-atom charge constraint data from a model to a file in a format that this class can read in

Parameters:
  • model (schrodinger.application.jaguar.gui.tabs.sub_tab_widgets. basis_set_widgets.ChargeConstraintsModel) – The model containing restraints to write
  • datafile (file) – The file to write the data to
static writeDictDataToFile(adict, datafile)

Write by-atom charge constraint data from a dictionary to a file in a format that this class can read in

Parameters:
  • adict (dict) – keys are entry IDs, values are lists of ChargeConstraint
  • datafile (file) – The file to write the data to
applyToJaguarInput(jagin)

Apply this charge constraint to a JaguarInput object

Parameters:jagin (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to apply this constraint to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.StageKeywords(line)

Bases: object

Holds and manipulates data about keywords

__init__(line)

Create a StageKeywords instance from a line of text

Expected tab-delimited format:
entry_id keyword=value keyword=value …
Parameters:line (str) – The line of text to create the instance from
static writeKeywordsToFile(keywords, datafile)

Write keyword data to a file in a format that this class can read in

Parameters:
  • keywords (dict) – keys are entry IDs, values dicts with Jaguar (key, value) pairs
  • datafile (file) – The file to write the data to
static writeDictDataToFile(adict, datafile)

Write keyword data from the given dictionary to a file in a format that this class can read in

Parameters:
  • adict (dict) – keys are entry IDs, values are lists of StageKeywords
  • datafile (file) – The file to write the data to
applyToJaguarInput(jagin)

Apply these keywords to a JaguarInput object

Parameters:jagin (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to apply these keywords to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.ExtraSectionData

Bases: object

Holds and manipulates text for extra sections

__init__()

Create an ExtraSectionData instance

Use addLine to add a line of text

addLine(line)

Add a line of text to the extra section text block

Parameters:line (str) – The line of text to add to the extra section block
addToJaguarInput(input_file)

Add this block of text at the bottom of a jaguar input file

Parameters:input_file (file) – The input file to add the text to
static writeSectionsToFile(sections, datafile)

Write extra sections data to a file in a format that this class can read in

Parameters:
  • sections (str) – The extra text to add
  • datafile (file) – The file to write the data to
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.OverrideKeywords(line)

Bases: object

Holds and manipulates data about override keywords - these are keywords that either can’t be set by the GUI or override the values set in the GUI. They apply to all structures

__init__(line)

Create a OverrideKeywords instance from a line of text

Expected tab-delimited format:
keyword=value keyword=value …
Parameters:line (str) – The line of text to create the instance from
static writeKeyStringToFile(keystring, datafile)

Write override keyword data to a file in a format that this class can read in

Parameters:
  • keystring (str) – the string of keyword=value pairs to write
  • datafile (file) – The file to write the data to
applyToJaguarInput(jagin)

Apply these keywords to a JaguarInput object

Parameters:jagin (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to apply these keywords to
schrodinger.application.matsci.jaguar_multistage_workflow_utils.get_property_keys_from_keywords(keywords)

Return Jaguar output structure property keys that are created from the given input keywords.

Parameters:keywords (dict) – Jaguar keywords
Return type:list
Returns:structure property keys
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.AnalyzeStageData(line)

Bases: object

Holds and manipulates data about an analysis stage

__init__(line)

Create an Analyze instance from a line of text

Expected tab-delimited format:
stage_idx property_key property_key float str stage_idx stage_idx …
Parameters:line (str) – The line of text to create the instance from
static writeAnalyzeDataToFile(data, datafile)

Write analyze data to a file in a format that this class can read in.

Parameters:
  • data (list) – contains (parent_st_idx, key, parent_key, prefactor, function, parent_idx, parent_idx, …) tuples
  • datafile (file) – the file to write the data to
schrodinger.application.matsci.jaguar_multistage_workflow_utils.write_stages_file(stages, file_path)

Write stages to a file with the given path.

Parameters:
  • stages (list) – contains StageData
  • file_path (str) – the file path
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.StageData(index)

Bases: object

Hold and manipulate all the settings for a stage in the workflow

DATA_CLASSES = {'ACTIVE_COORDINATES': <class 'schrodinger.application.matsci.jaguar_multistage_workflow_utils.ActiveCoord'>, 'ATOM_BASIS': <class 'schrodinger.application.matsci.jaguar_multistage_workflow_utils.AtomBasis'>, 'CHARGE_CONSTRAINTS': <class 'schrodinger.application.matsci.jaguar_multistage_workflow_utils.ChargeConstraint'>, 'GEOM_CONSTRAINTS': <class 'schrodinger.application.matsci.jaguar_multistage_workflow_utils.GeomConstraint'>, 'KEYWORDS': <class 'schrodinger.application.matsci.jaguar_multistage_workflow_utils.StageKeywords'>}
__init__(index)

Create a StageData instance

Parameters:index (int) – The 1-based index of this stage
parseDataLine(line, ltype)

Parse a data line

Parameters:
  • line (str) – The line of data to parse
  • ltype (str) – The type of data in this line. Should be a module constant PARENT, EXTRA_SECTIONS, ANALYZE, or one of the DATA_CLASSES keys
applyEntryData(jagin, eid)

Apply all entry data for entry eid to the given JaguarInput object

Parameters:
getKeywords(eid=None)

Get the keywords for this stage for the given eid. If no eid is given, keywords for a random entry will be returned.

Parameters:eid (str or None) – If str, keywords for this entry will be supplied. If None, a random entry will be chosen.
Return type:dict
Returns:keys are keywords, values are values for that keyword
getPropertyKeys()

Return output structure property keys that are created by this stage.

Return type:list
Returns:structure property keys
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.JMSWorkFlow(*args, **kwargs)

Bases: schrodinger.application.matsci.jaguarworkflows.WorkFlow

A Jaguar Multistage WorkFlow object that controls all the steps for an entry

__init__(*args, **kwargs)

Create a JSMWorkFlow instance

Parameters:
  • stages (list) – A list of StageData objects, one for each step in the workflow
  • smap_name (str) – The name of the master smap file
  • hierarchical (bool) – in the output structure file hierarchically group structures by stage using a job name and original structure title header

See parent class for additional documentation

getSteps()

Create all the steps for this workflow, one for each stage

check(log_zero_steps=False)

Check if this workflow is complete. Also, submit the next step(s) if the previous step has finished.

Parameters:log_zero_steps (bool) – log a message if there are zero steps
Return type:bool
Returns:True if the workflow is complete, False if not
log(msg, prefix=True, level=20)

Add a message to the log file

Parameters:
  • msg (str) – The message to add
  • prefix (bool) – Whether to add information about the workflow and step name to the front of the message string
  • level (int) – A logging constant indicating the priority level of the message
write(writer)

Write out the structure for this workflow and all the child structures

Parameters:writer (schrodinger.StructureWriter) – The writer to use to write the structure
class schrodinger.application.matsci.jaguar_multistage_workflow_utils.JMSStep(stage, *args, **kwargs)

Bases: schrodinger.application.matsci.jaguarworkflows.Step

A step in the Jaguar Multistage Workflow

__init__(stage, *args, **kwargs)

Create a JMSStep instance

Parameters:stage (StageData) – The settings for this step

See parent class for additional documentation

start()

Start the job - create the input and write it, adding necessary output files to make sure they get copied back

getStructure()

Overwrite the parent class method to return the structure from the inheritable parent step if an inheritable parent exists, otherwise return the original structure

getInput()

Overwrite the parent class method to avoid setting default keywords values and to apply data from the StageData class for this step

Return type:schrodinger.application.jaguar.input.JaguarInput or None
Returns:The JaguarInput object for this step, or None if it could not be created.
getJaguarRestartFileName()

Get the name of the Jaguar restart file for this step - the restart file contains the wavefunction and hessian

Return type:str
Returns:The name of the Jaguar restart file for this step
writeInput()

Overwrite the parent class method to copy data from the parent step and add extra section data from the StageData object

finishProcessingJobControlJob()

Add any files to the backend that the Jaguar subjob preserved

write(writer, **kwargs)

In addition to the parent method, also compile any smap data into the master smap file.

See parent method for additional documentation

calcsDone()

Check to see if the calculation finished successfully

Return type:bool
Returns:True if the calculation finished and was successful, False if not
canStart()

Check to see if this job can start - if the parent job(s) have finished successfully.

Return type:bool
Returns:True if the job can start, False if not
createJob()

Submit a jaguar job under job control

Parameters:jaginput (schrodinger.application.jaguar.input.JaguarInput) – The JaguarInput object to submit
Return type:schrodinger.job.jobcontrol.Job object
Returns:The Job object for the launched job
finish()

Do any work required to create properties when the calculation has finished.

If property_name was provided to the constructor, this computes the energy difference between this step and the inherited parent step and stores it in the property name.

getOutput(quiet=False)

Read in the results of the calculation

Parameters:quiet (bool) – If True, no error messages will be printed. If False, (default) error messages will be printed. Also, if True, self.ok will not be set to False if the output file cannot be read.
Return type:None or JaguarOutput
Returns:None if the calculation failed, or JaguarOutput object for successful calculations.
log(msg, prefix=True, level=20)

Add a message to the parent workflow’s log file

Parameters:
  • msg (str) – The message to add
  • prefix (bool) – Whether to add information about the workflow and step name to the front of the message string
  • level (int) – A logging constant indicating the priority level of the message
setKeywords(input, keystring)

Set the keywords for this job

Parameters:
  • input (jaguar_input.JaguarInput) – The JaguarInput object to set the keywords on
  • keystring (str) – Space separated keyword=value pairs. Each pair must contain an equals sign
schrodinger.application.matsci.jaguar_multistage_workflow_utils.create_workflows(options, jobq, stages, smap_name, hierarchical=True)

Create a workflow for each structure

Parameters:
  • options (argparse.Namespace) – The command line options
  • jobq (schrodinger.job.queue.JobDJ) – The JobDJ to run subjobs with
  • stages (list) – A list of StageData objects to create JMSStep from
  • smap_name (str) – The name of the master smap file
  • hierarchical (bool) – in the output structure file hierarchically group structures by stage using a job name and original structure title header
schrodinger.application.matsci.jaguar_multistage_workflow_utils.read_stage_datafile(filename)

Read in a settings file. Logs an error and exists if an error occurs while reading the file.

Parameters:filename (str) – The name of the settings file to read
schrodinger.application.matsci.jaguar_multistage_workflow_utils.validate_stages(stages)

Validate stages.

Parameters:stages (list) – contains StageData
Raises:InvalidStageFileError – if there is an issue
schrodinger.application.matsci.jaguar_multistage_workflow_utils.log_error(msg)

Add a message to the log file and exit with an error code

Parameters:msg (str) – The message to log
schrodinger.application.matsci.jaguar_multistage_workflow_utils.log(msg, timestamp=False, pad=False, pad_below=False)

Add a message to the log file

Parameters:
  • msg (str) – The message to log
  • pad (bool) – Whether to pad above this message with a blank line
  • pad_below (bool) – Whether to pad below this message with a blank line
  • timestamp (bool) – Whether to print a timestamp with the message
schrodinger.application.matsci.jaguar_multistage_workflow_utils.create_smap(basename, output_name, smap_dict=None)

Create the master smap file that will map property files (.vib, .vis, etc) to structures in the compiled structure file

Parameters:
  • basename (str) – The base name of all job files
  • output_name (str) – The name of the output structure file
  • smap_dict (dict) – keys are file names, values are indices, the values are not entry IDs but rather the counting indices (1-based) of the structure in the given output_name file that the given file name key is associated with
Return type:

str

Returns:

The name of the smap file created

schrodinger.application.matsci.jaguar_multistage_workflow_utils.finalize_smap(smap_name, backend)

Finish the master smap file and add it to the jobcontrol backend if necessary

Parameters:
  • smap_name (str) – The name of the master smap file
  • backend (schrodinger.job.jobcontrol._Backend) – The job control backend or None if there is no backend