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.

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 file or the base name of the Jaguar job
Return type:schrodinger.structure.Structure
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
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.

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

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.

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

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.

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