schrodinger.application.matsci.jaguarworkflows module

Workflow and Step classes to aid in running a series of Jaguar jobs.

For each molecule, a Workflow object is established. The Steps the Workflow will run depend on the options chosen. Some Steps depend on other Steps to finish before starting. It is the job of the Workflow to submit jobs when all the required dependencies have finished successfully.

Workflow objects submit jobs to a JobDJ queue.

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.matsci.jaguarworkflows.is_ompi_allowed()

Check to see if the OMPI feature flag is enabled

Return type:bool
Returns:If the flag is enabled
schrodinger.application.matsci.jaguarworkflows.get_jaguar_max_atoms()

Get maximum number of atoms currently supported by Jaguar

Return type:int
Returns:Maximum number of atoms
schrodinger.application.matsci.jaguarworkflows.keyword_string_to_dict(keystring)

Return a dictionary whose keys are keywords and values are keyword values

Parameters:keystring (str) – The keywords are taken from this string - keywords must be in the keyword=value format and whitespace delimited.
Return type:dict
Returns:Dictionary of keyword/value pairs
Raises:ValueError – if any tokens do not match the keyword=value format
schrodinger.application.matsci.jaguarworkflows.keyword_dict_to_string(keydict)

Return a string of keywords specified by keydict.

Parameters:keydict (dict) – Dictionary - keys are Jaguar keywords, values are keyword values of str type
Return type:str
Returns:A string of space-separated keyword=value pairs
exception schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Bases: Exception

An exception that is thrown when either reading the Jaguar output file fails for some reason, or a successful reading shows that Jaguar failed.

__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.

schrodinger.application.matsci.jaguarworkflows.get_jaguar_output(path, step_info='')

Get a JaguarOutput object for the given path

Parameters:
  • path (str) – The path to the output file. May be just the base name of the output file (file instead of file.out)
  • step_info (str) – The step name - optional, and only used to create more informative error messages.
Return type:

schrodinger.application.jaguar.output.JaguarOutput

Returns:

The JaguarOutput object for path

Raises:

JaguarFailedException – If a problem is detected with the output

schrodinger.application.matsci.jaguarworkflows.get_jaguar_output_structure(path)

Get the structure associated with the .out results file indicated by path.

Parameters:path (str) – The path to the Jaguar output file - does not need to include the .out part of the output file name - can be absolute or relative
Return type:schrodinger.structure.Structure
Returns:The output structure object for the indicated .out file
schrodinger.application.matsci.jaguarworkflows.get_jaguar_out_mae(path)

Get the output Maestro structure for the jaguar calculation given by path

Parameters:path (str) – The path to the desired .mae or .out file or the base name of the Jaguar job
Return type:schrodinger.structure.Structure or None
Returns:The output structure, or None if the file doesn’t exist.
schrodinger.application.matsci.jaguarworkflows.add_jaguar_files_to_jc_backend(base_name, backend=None, spm=False, others=None, restart=True)

Add the typical jaguar files for a job to the backend so they are returned to the working directory.

Parameters:
  • base_name (str) – The base name of the files
  • backend (schrodinger.job.jobcontrol._Backend) – The jobcontrol backend (from jobcontrol.get_backend()). If not supplied, an attempt will be made to obtain one.
  • spm (bool) – Whether to add the _uvv_singlet.spm file
  • others (list) – List of additional extensions for files named base_name.extension that should be added to the job control backend. For example: others=[‘_vib.spm’, ‘_vcd.spm’] will add base_name_vib.spm and basename_vcd.spm. Note that any extensions need to include the leading ‘.’.
  • restart (bool) – Whether to include the .0x.in file. These files are very large, so it’s best not to keep them unless necessary.
class schrodinger.application.matsci.jaguarworkflows.RobustSubmissionJob(command, command_dir=None, name=None, max_retries=None, timeout=None, launch_timeout=None, launch_env_variables=None, **kwargs)

Bases: schrodinger.job.queue.JobControlJob

A JobControlJob object that will retry to submit multiple times for fizzled, jobs (if the queue setting is such) but will not attempt to retry a job that died.

retryFailure(max_retries=0)

Determine if the job should be retried or not. This overwrites the parent method to not retry jobs that have a status of “died” as that will indicate that Jaguar failed, which it almost certainly will again.

Parameters:max_retries (int) – The queue’s max_retries parameter
Return type:bool
Returns:True if the job should be retried, False if not
__init__(command, command_dir=None, name=None, max_retries=None, timeout=None, launch_timeout=None, launch_env_variables=None, **kwargs)

Job constructor.

Parameters:
  • command (List of strings.) – The command that runs the job.
  • command_dir (pathname) – The directory from which to run the command.
  • name (string) – The name of the job.
  • max_retries (int) – Number of allowed retries for this job. If this is set, it is never overridden by the SCHRODINGER_MAX_RETRIES environment variable. If it is not set, the value of max_retries defined in JobDJ is used, and SCHRODINGER_MAX_RETRIES can be used to override this value at runtime. To prevent this job from being restarted altogether, set max_retries to zero.
  • timeout (int | None) – Timeout (in seconds) after which the job will be killed. If None, the job is allowed to run indefinitely.
  • launch_env_variables (dict) – A dictionary with the environment variables to add when the jobcontrol job is launched. The name of any additional variables to set should be in the keyword of the dict and the value should be the corresponding value. These will be added to any environment variables already present, but removed after the job has been launched.
  • kwargs (dict) – Additional keyword arguments. Provided for consistency of interface in subclasses.
Param:

launch_timeout Timeout (in seconds) for the job launch process to complete. Will be capped at 400s unless a higher timeout is explicitly passed in.

addFinalizer(function, run_dir=None)

Add a function to be invoked when the job completes successfully.

See also the add_multi_job_finalizer function.

addGroupPrereq(job)

Make all jobs connected to job prerequisites of all jobs connected to this Job.

addPrereq(job)

Add a job that is an immediate prerequisite for this one.

cancelSubmitted()

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, local)

Launch job on specified host using jobcontrol.launch_job(). The -LOCAL flag is added to the job invocation command if local is True.

Parameters:
  • host (str) – Host on which the job will be executed.
  • local (bool) – Should “-LOCAL” be appended to the command?
finalize()

Clean up after a job successfully runs.

genAllJobs(seen=None)

A generator that yields all jobs connected to this one.

genAllPrereqs(seen=None)

A generator that yields all jobs that are prerequisites on this one.

getCommand()

A hook method that can allow for the command to be generated at run time.

getCommandDir()

Return the launch/command directory name. If None is returned, the job will be launched in the current directory.

getJob()

Return the job record as a schrodinger.job.jobcontrol.Job instance.

Returns None if the job hasn’t been launched.

getJobDJ()

Return the JobDJ instance that this job has been added to.

getPrereqs()

Return a set of all immediate prerequisites for this job.

getStatusStrings()

Return a tuple of status strings for printing by JobDJ.

The strings returned are (status, jobid, name, host).

hasStarted()

Returns True if this job has started (not waiting)

init_count = 0
isComplete()

Returns True if this job finished successfully

kill()

Send kill request to jobcontrol managed job

maxFailuresReached(msg)

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.

run(*args, **kwargs)

Run the job.

The steps taken are as follows:
  1. Execute the preCommand method for things like changing the working directory.
  2. Call the doCommand to do the actual work of computation or job launching.
  3. Call the postCommand method to undo the changes from the preCommand that need to be undone.
runsLocally()

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 before doCommand.

state

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 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 a RuntimeError if an unknown Job Status or ExitStatus is encountered.

usesJobServer()

Detect, by looking at the jobId, whether this job uses a job server. Since the jobId is only set once, cache the answer (_uses_job_server) once it is established.

schrodinger.application.matsci.jaguarworkflows.create_job(options, filename, jobclass=<class 'schrodinger.application.matsci.jaguarworkflows.RobustSubmissionJob'>, serial_only=False)

Create a job of class jobclass that will run the Jaguar input file filename with options

Parameters:
  • options (argparse.Namespace) – The input options.
  • filename (str) – The name of the input file
  • jobclass (schrodinger.job.JobControlJob) – The class used to create the job
  • serial_only (bool) – Whether to force the job to run in serial. If False (default), parallel options will be used if available in options.
Return type:

jobclass

Returns:

The created job

class schrodinger.application.matsci.jaguarworkflows.Results(path)

Bases: object

A low memory results object - because the driver ends up holding on to results for a long time and can be simultaneously holding results for a large number of calculations, we want to keep the memory footprint of each result low. Mainly, we don’t want to hold structures in memory, but also orbital eigenvectors, etc.

This class mimics a limited subset of the jaguar.output.JaguarResults class API. Future needs might increase which properties are kept, but do not keep any large-memory properties.

__init__(path)

Create a Results object.

Parameters:path (str) – path to the Jaguar Output file, or a path to the input file, as the JaguarOutput class can find the output file from that.
getResultWithThisEnergy(energy=None)

Return the JaguarResults object for the geometry optimization step with the given energy

Parameters:energy (float or None) – The gas phase energy of the desired step. If None, the gas_energy property of this Result object will be used. If that value is None, the energy of the last step in the geometry optimization will be used.
Return type:schrodinger.application.jaguar.output.JaguarResults
Returns:The results object with this energy, or the only results object if the output contains a single point.
getStructure()

Get the structure associated with these results

Return type:schrodinger.structure.Structure
Returns:The output structure object for this step
getMaeStructure()

Get the structure associated with these results from the .01.mae file - this may have some associated properties on it.

Return type:schrodinger.structure.Structure
Returns:The output structure object for this step
class schrodinger.application.matsci.jaguarworkflows.Step(workflow, parent=None, noninheritable_parents=None, optimization=True, charge=0, multiplicity=1, property_name=None, step_name='', job_name='', kcal=True, solvent=None, keystring='', serial_only=False, keep_jag_restart=True, need_spm=False)

Bases: object

Manages the start, monitoring and finish of a single step in a workflow

__init__(workflow, parent=None, noninheritable_parents=None, optimization=True, charge=0, multiplicity=1, property_name=None, step_name='', job_name='', kcal=True, solvent=None, keystring='', serial_only=False, keep_jag_restart=True, need_spm=False)

Create a Step object

Parameters:
  • workflow (Workflow) – The workflow that owns this step
  • parent (Step) – The parent job that must finish successfully before this job can start, this parent has information that is inherited
  • noninheritable_parents (list of Step) – The parent jobs that must finish successfully before this job can start, these parents do not have information that is inherited
  • optimization (bool) – True if this step should optimize the geometry, False if not
  • charge (int) – The molecular charge for this step
  • multiplicity (int) – The spin multiplicity for this step
  • property_name (str) – The name of the property this step should create when finished, None if no property will be created
  • step_name (str) – The user-readable name of this step to use in messages
  • job_name (str) – The base name of the file.
  • kcal (bool) – True if the property should be in kcal/mol, False if not
  • solvent (dict) – Dictionary of keyword/value pairs for solvent keywords. If not given, a gas phase calculation will be run
  • keystring (str) – Space separated keyword=value pairs. Each pair must contain an equals sign
  • serial_only (bool) – If True, do not use any parallel options when running Jaguar
  • keep_jag_restart (bool) – If True, add .01.in files Jaguar restart files to the backend (that will get them copied to the original folder)
  • need_spm (bool) – If True, add Jaguar spm file to the backend (that will get them copied to the original folder)
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
getStructure()

Get the starting structure for this step

Return type:schrodinger.structure.Structure
Returns:The starting structure for this step
getInput(override_uhf=True, override_solvent=True)

Get the JaguarInput object for this step, setting the keywords as required.

Return type:None or jaguar_input.JaguarInput
Returns:None if an error occured, or the jaguar_input.JaguarInput object to use for this step
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
writeInput()

Write the input file for the step

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
start()

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

calcsDone()

Check to see if the calculation finished successfully

Return type:bool
Returns:True if the calculation finished and was successful, False if not
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.
finishProcessingJobControlJob()

Finish processing the job control job object before we release our handle to it

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.

write(writer, props=None)

Add the final structure for this step to the output structure file

Parameters:
  • writer (schrodinger.StructureWriter) – The writer to use to write the structure
  • props (dict) – A dictionary of property/value pairs to add to the property dictionary of this object.
class schrodinger.application.matsci.jaguarworkflows.FrozenStep(*args, **kwargs)

Bases: schrodinger.application.matsci.jaguarworkflows.Step

A step that does not perform geometry optimization but just runs a calculation at the geometry of the parent step.

__init__(*args, **kwargs)

Create a Vertical Step object.

Overwrites any value of optimization that is passed in.

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.

finishProcessingJobControlJob()

Finish processing the job control job object before we release our handle to it

getInput(override_uhf=True, override_solvent=True)

Get the JaguarInput object for this step, setting the keywords as required.

Return type:None or jaguar_input.JaguarInput
Returns:None if an error occured, or the jaguar_input.JaguarInput object to use for this step
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.
getStructure()

Get the starting structure for this step

Return type:schrodinger.structure.Structure
Returns:The starting structure for this step
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
start()

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

write(writer, props=None)

Add the final structure for this step to the output structure file

Parameters:
  • writer (schrodinger.StructureWriter) – The writer to use to write the structure
  • props (dict) – A dictionary of property/value pairs to add to the property dictionary of this object.
writeInput()

Write the input file for the step

class schrodinger.application.matsci.jaguarworkflows.OptStep(workflow, parent=None, noninheritable_parents=None, optimization=True, charge=0, multiplicity=1, property_name=None, step_name='', job_name='', kcal=True, solvent=None, keystring='', serial_only=False, keep_jag_restart=True, need_spm=False)

Bases: schrodinger.application.matsci.jaguarworkflows.Step

A step that performs a geometry optimization

__init__(workflow, parent=None, noninheritable_parents=None, optimization=True, charge=0, multiplicity=1, property_name=None, step_name='', job_name='', kcal=True, solvent=None, keystring='', serial_only=False, keep_jag_restart=True, need_spm=False)

Create a Step object

Parameters:
  • workflow (Workflow) – The workflow that owns this step
  • parent (Step) – The parent job that must finish successfully before this job can start, this parent has information that is inherited
  • noninheritable_parents (list of Step) – The parent jobs that must finish successfully before this job can start, these parents do not have information that is inherited
  • optimization (bool) – True if this step should optimize the geometry, False if not
  • charge (int) – The molecular charge for this step
  • multiplicity (int) – The spin multiplicity for this step
  • property_name (str) – The name of the property this step should create when finished, None if no property will be created
  • step_name (str) – The user-readable name of this step to use in messages
  • job_name (str) – The base name of the file.
  • kcal (bool) – True if the property should be in kcal/mol, False if not
  • solvent (dict) – Dictionary of keyword/value pairs for solvent keywords. If not given, a gas phase calculation will be run
  • keystring (str) – Space separated keyword=value pairs. Each pair must contain an equals sign
  • serial_only (bool) – If True, do not use any parallel options when running Jaguar
  • keep_jag_restart (bool) – If True, add .01.in files Jaguar restart files to the backend (that will get them copied to the original folder)
  • need_spm (bool) – If True, add Jaguar spm file to the backend (that will get them copied to the original folder)
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.

finishProcessingJobControlJob()

Finish processing the job control job object before we release our handle to it

getInput(override_uhf=True, override_solvent=True)

Get the JaguarInput object for this step, setting the keywords as required.

Return type:None or jaguar_input.JaguarInput
Returns:None if an error occured, or the jaguar_input.JaguarInput object to use for this step
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.
getStructure()

Get the starting structure for this step

Return type:schrodinger.structure.Structure
Returns:The starting structure for this step
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
start()

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

write(writer, props=None)

Add the final structure for this step to the output structure file

Parameters:
  • writer (schrodinger.StructureWriter) – The writer to use to write the structure
  • props (dict) – A dictionary of property/value pairs to add to the property dictionary of this object.
writeInput()

Write the input file for the step

class schrodinger.application.matsci.jaguarworkflows.WorkFlow(struct, options, count, jobq, strcleaner=None, logger=None)

Bases: object

A class to hold the data for and shepherd a single structure through all the jobs required to gather its data.

For a typical workflow, the job dependency tree may look like:
Neutral Optimization

| | | | |
Cation Opt Cation Froz Anion Opt Anion Froz Triplet Opt TD-DFT
Solution Cat Solution An

Final Reorg Step Final Reorg Step

Any job may be submitted by the Workflow to the Queue as long as the jobs above it on its branch of the tree have completed successfully.

__init__(struct, options, count, jobq, strcleaner=None, logger=None)

Create a Workflow object

Parameters:
  • struct (schrodinger.structure.Structure) – The initial structure to use for the workflow
  • options (argparse Namespace object) – The input options. The only options used by this module is options.host, which are used by Step objects. Other options may be used by custom classes.
  • count (int) – A serial number to distinguish this workflow from other workflows. May be used to create a unique base name.
  • jobq (JobDJ) – The queue to submit jobs to
  • strcleaner (schrodinger.application.matsci.jobutils.StringCleaner or None) – a StringCleaner instance
  • logger (logging.Logger) – The logger for this class
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
getSteps()

Create all the steps required for this workflow

This method should almost certainly be overridden by any child class. The example given here is just that - an example

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
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
schrodinger.application.matsci.jaguarworkflows.create_queue(options=None, host=None, **kwargs)

Create a JobDJ job with some default values and the given keyword arguments Current defaults:

  • verbosty: normal
  • max_failures: NOLIMIT
  • max_retries: 3
Parameters:
  • options (argparse Namespace object) – the hostlist will be formed from the options.host property if not supplied by the host argument
  • host (str) – The host string to use to create the queue

All other keyword arguments will be passed on to the JobDJ object

Return type:schrodinger.job.queue.JobDJ
Returns:The JobDJ object
schrodinger.application.matsci.jaguarworkflows.run_workflows(jobq, active_workflows, writer)

Run all the workflows and return when they are finished. At the end of this function, active_workflows will be empty. Returns True if at least one job did not fail (or there were no jobs to run), otherwise False.

Parameters:
Return type:

bool

Returns:

True if at least one job did not fail, otherwise False