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.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.format_temperature(temp, decimal=8)

Return the Jaguar format of the given temperature.

Parameters

  • temp (float) – the temperature in K

  • decimal (int) – the number of decimal places to use

Return type

str

Returns

the formatted temperature

schrodinger.application.matsci.jaguarworkflows.format_pressure(press)

Return the Jaguar format of the given pressure.

Parameters

press (float) – the pressure in atm

Return type

str

Returns

the formatted pressure

schrodinger.application.matsci.jaguarworkflows.get_temp_press_key_ext(temp, press)

Return Jaguar’s temperature and pressure thermochemistry key extension.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

Return type

str

Returns

the key extension

schrodinger.application.matsci.jaguarworkflows.get_temperature(energy_key)

Return the temperature (K) for the given energy key.

Parameters

energy_key (str) – structure property energy key

Return type

float, None

Returns

the temperature (K) if there is one

schrodinger.application.matsci.jaguarworkflows.get_pressure(energy_key)

Return the pressure (atm) for the given energy key.

Parameters

energy_key (str) – structure property energy key

Return type

float, None

Returns

the pressure (atm) if there is one

schrodinger.application.matsci.jaguarworkflows.get_wildcard_energy_key(energy_key)

Return the wildcard version of the given energy key.

Parameters

energy_key (str) – structure property energy key

Return type

str, None

Returns

the wildcard version of the energy key if there is one, else None

schrodinger.application.matsci.jaguarworkflows.get_internal_energy_key(temp, press)

Return Jaguar’s thermochemistry internal energy key.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

Return type

str

Returns

the key

schrodinger.application.matsci.jaguarworkflows.get_enthalpy_key(temp, press, total=True)

Return Jaguar’s thermochemistry enthalpy key.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

  • total (bool) – If True, return key for total enthalpy, otherwise vibrational enthalpy key is returned

Return type

str

Returns

the key

schrodinger.application.matsci.jaguarworkflows.get_free_energy_key(temp, press, total=True)

Return Jaguar’s thermochemistry free energy key.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

  • total (bool) – If True, return key for free energy, otherwise vibrational free energy key is returned

Return type

str

Returns

the key

schrodinger.application.matsci.jaguarworkflows.get_entropy_key(temp, press)

Return Jaguar’s thermochemistry entropy key.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

Return type

str

Returns

the key

schrodinger.application.matsci.jaguarworkflows.get_lnq_key(temp, press)

Return Jaguar’s thermochemistry ln(Q) key.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

Return type

str

Returns

the key

schrodinger.application.matsci.jaguarworkflows.get_gas_phase_zpe_key(temp, press)

Return matsci gas phase + ZPE key.

Parameters

  • temp (float) – the temperature in K

  • press (float) – the pressure in atm

Return type

str

Returns

the key

schrodinger.application.matsci.jaguarworkflows.compute_real_moment_components(real, imaginary)

Given transition dipole moment components that have both real and imaginary parts, perform a rotation so that the components are entirely real.

Parameters

  • real (numpy.array) – The real part of the components

  • imaginary (numpy.array) – The imaginary part of the components

Return type

numpy.array

Returns

The rotated, entirely real, components. Each item is a float

schrodinger.application.matsci.jaguarworkflows.check_charge_and_multiplicity(astructure, charge, multiplicity)

Check the charge and multiplicity.

Parameters

  • astructure (schrodinger.structure.Structure) – the structure to check

  • charge (int) – net molecular charge

  • multiplicity (int) – net molecular multiplicity

Raise

ValueError if there is an issue

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.

exception schrodinger.application.matsci.jaguarworkflows.JaguarOutputNotFound

Bases: schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Raised when the .out file can’t be located

exception schrodinger.application.matsci.jaguarworkflows.JaguarOutputUnreadable

Bases: schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Raised when the .out file can’t be read for some reason

exception schrodinger.application.matsci.jaguarworkflows.JaguarStuckGeometry

Bases: schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Raised when a stuck geometry optimization is detected

exception schrodinger.application.matsci.jaguarworkflows.JaguarSCFNotConverged

Bases: schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Raised when the SCF did not converge

exception schrodinger.application.matsci.jaguarworkflows.JaguarGeomNotConverged

Bases: schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Raised when the Geometry did not converge (ran out of iterations)

exception schrodinger.application.matsci.jaguarworkflows.JaguarInvalidKeyword

Bases: schrodinger.application.matsci.jaguarworkflows.JaguarFailedException

Raised when the Geometry did not converge (ran out of iterations)

schrodinger.application.matsci.jaguarworkflows.is_jaguar_file_property(prop)

Check whether this structure property is one of the Jaguar properties and links to a file

Parameters

prop (str) – The property name

Return type

bool

Returns

True if it is, False if it isn’t

schrodinger.application.matsci.jaguarworkflows.remove_jaguar_file_properties(sts)

Remove all Jaguar file properties from the given structures.

Parameters

sts (list[schrodinger.structure.Structure]) – the structures to remove the properties from

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

Get a JaguarOutput object for the given path or structure.

Parameters

  • path (str or None) – The path to the output file. May be just the base name of the output file (file instead of file.out). If None then an input structure must be specified.

  • step_info (str) – The step name - optional, and only used to create more informative error messages.

  • st (schrodinger.structure.Structure or None) – The structure from which to get the output file. If None then an input path must be specified.

Return type

schrodinger.application.jaguar.output.JaguarOutput

Returns

The JaguarOutput object for path

Raises

JaguarFailedException – If a problem is detected with the output. Subclasses of this exception are raised to specify what type of error

schrodinger.application.matsci.jaguarworkflows.get_out_mae_path(base)

Get the output Maestro structure path for the jaguar calculation

Parameters

base (str) – The base name of the jaguar job

Return str

The path to the mae file

schrodinger.application.matsci.jaguarworkflows.get_jaguar_out_mae(path, require_success=False)

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

  • require_success (bool) – Whether to check related Jaguar output for success

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.

schrodinger.application.matsci.jaguarworkflows.is_jag_license_needed(cmd, uses_jobdj=True, reserves_multiple_cores=False, uses_smart_distribution=True)

Check if a Jaguar license will be needed by a driver using the given command line.

Parameters

  • cmd (list) – The command line as a list of strings

  • uses_jobdj (bool) – Whether the driver uses JobDJ to launch subjobs. The logic in this function is only valid if the driver uses JobDJ or if reserves_mulitiple_cores is True.

  • reserves_multiple_cores (bool) – Whether the driver reserves multiple cores based on the TPP settings so it can run local jobs

  • uses_smart_distribution (bool) – Whether the driver uses Smart Distribution or not. Drivers that turn Smart Distribution on/off based on -TPP setting should use True for this value.

Return type

bool

Returns

True if a license should be reserved, False if not

Raises

RuntimeError – if uses_jobdj is False and reserves_multiple_cores is False, as the logic in this function is not applicable for non-jobdj drivers.

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

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.

  • path (str) – Set the subjob command directory to path (this is where the subjob will be run from)

  • robust (bool) – Use the robust Jaguar driver rather than Jaguar itself

  • max_retries (int or None) – see queue.JobControlJob

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, archive_files=False)

Bases: object

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

ARCHIVED_KEEPERS = {'.smap', '.spm', '.vib', '.vis'}
ARCHIVED_INPUT = ['.in', '.mae', '.maegz']
__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, archive_files=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

storeFilenames()

Store file names associated with this job before we delete the job object

calcsDone()

Check to see if the calculation finished

If finished and the job failed, self.ok will be set to False

Return type

bool

Returns

True if the calculation finished, 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.

periodicMaintenance()

This method is periodically called while the workflow is running

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, hierarchy=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.

  • hierarchy (list) – The project group hierarchy for this result - each item is a str

handleFileLinkProperties(struct)

Fix existing Jaguar file link properties and add any new ones

Parameters

struct (structure.Structure) – The structure with the properties

archiveFiles()

Create a tar.gz archive of all jaguar files and then removes any files that are no longer needed.

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.

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, archive_files=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, subhierarchy=None, robust=False, max_retries=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.

FALLBACK_BASE_NAME = 'structure'
__init__(struct, options, count, jobq, strcleaner=None, logger=None, subhierarchy=None, robust=False, max_retries=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.

  • 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 used to guarantee unique workflow base names

  • logger (logging.Logger) – The logger for this class

  • subhierarchy (str) – If given, the final structure for all steps other than the main step will be placed in a PT subgroup with this name.

  • robust (bool) – If True, use the robust Jaguar driver to run Jaguar jobs. If false, use Jaguar directly.

  • max_retries (int or None) – see queue.JobControlJob

generateBaseName(strcleaner, count)

Come up with a base name for this workflow based on the workflow structure title or a fallback name if the title can’t be used. Pass in a StringCleaner object to guarantee uniqueness.

Parameters
log(msg, prefix=True, level=20, pad=False, pad_below=False)

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

  • 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

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

periodicMaintenance()

The run_workflows function will call this method periodically - it can be used to perform operations while one of the workflow steps is running

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

recordFailureStatus()

Set properties based on the success/failure of each step, and write workflow structures to a summary failed file if any step failed

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

stepsInWriteOrder()

Generator for steps in the order they’re output structures should be written to the results file. Main step first, then all other steps in order of creation.

Return type

iterator

Returns

iterator of step objects

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

schrodinger.application.matsci.jaguarworkflows.parse_matrix(out_file)

Parse a matrix from a jaguar output file

Parameters

out_file (iterable) – An iterable such as the file handle. Should be at the beginning of the matrix part of the file.

Return type

numpy.array

Returns

Numpy array containing the correlation matrix

Change the Jaguar file link properties to point to the original job directory instead of the subjob directory. If not running under job control, the current working directory is used as the original job directory.

Parameters
schrodinger.application.matsci.jaguarworkflows.get_delta_energy(reactants, products)

Compute delta energy as: dE = E(Products) - E(Reactants) in kcal/mol

Parameters
Return type

float

Returns

Energy in kcal/mol