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_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.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__(*args, **kwargs)

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.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.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: List[str], command_dir: Optional[str] = None, name: Optional[str] = None, max_retries: Optional[int] = None, timeout: Optional[int] = None, launch_timeout: Optional[int] = None, launch_env_variables: Optional[Dict[str, str]] = 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: List[str], command_dir: Optional[str] = None, name: Optional[str] = None, max_retries: Optional[int] = None, timeout: Optional[int] = None, launch_timeout: Optional[int] = None, launch_env_variables: Optional[Dict[str, str]] = None, **kwargs)

Job constructor.

Parameters
  • command – The command that runs the job.

  • command_dir – The directory from which to run the command.

  • name – The name of the job.

  • max_retries – 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 – Timeout (in seconds) after which the job will be killed. If None, the job is allowed to run indefinitely.

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

  • launch_env_variables – 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 – Additional keyword arguments. Provided for consistency of interface in subclasses.

addFinalizer(function: Callable[[BaseJob], None], run_dir: str = None)

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

See also the add_multi_job_finalizer function.

addGroupPrereq(job: schrodinger.job.queue.BaseJob)

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

addPrereq(job: schrodinger.job.queue.BaseJob)

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

cancel()

Send kill request to jobcontrol managed job. This method will eventually deprecate JobControlJob.kill

cancelSubmitted() → bool

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: str, local: bool = False)

Launch job on specified host using jobcontrol.launch_job().

Parameters
  • host – Host on which the job will be executed.

  • local – Removed in JOB_SERVER.

finalize()

Clean up after a job successfully runs.

genAllJobs(seen: Set[BaseJob] = None) → Generator[schrodinger.job.queue.BaseJob, None, None]

A generator that yields all jobs connected to this one.

genAllPrereqs(seen=None) → Generator[schrodinger.job.queue.BaseJob, None, None]

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

getCommand() → List[str]

Return the command used to run this job.

getCommandDir() → str

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

getJob() → Optional[schrodinger.job.jobcontrol.Job]

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

Returns None if the job hasn’t been launched.

getJobDJ()schrodinger.job.queue.JobDJ

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

getPrereqs()

Return a set of all immediate prerequisites for this job.

getStatusStrings() → Tuple[str, str, str]

Return a tuple of status strings for printing by JobDJ.

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

hasExited() → bool

Returns True if this job finished, successfully or not.

hasStarted() → bool

Returns True if this job has started (not waiting)

init_count = 0
isComplete() → bool

Returns True if this job finished successfully

kill()

Send kill request to jobcontrol managed job

maxFailuresReached(msg: str)

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() → bool

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.

property 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 JobState.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

RuntimeError – if an unknown Job Status or ExitStatus is encountered.

usesJobServer() → bool

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, path=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)

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.

ARCHIVED_INPUT = ['.in', '.mae', '.maegz']
ARCHIVED_KEEPERS = {'.smap', '.spm', '.vib', '.vis'}
archiveFiles()

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

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

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

handleFileLinkProperties(struct)

Fix existing Jaguar file link properties and add any new ones

Parameters

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

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

periodicMaintenance()

This method is periodically called while the workflow is running

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

storeFilenames()

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

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

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

Bases: schrodinger.application.matsci.jaguarworkflows.Step

A step that performs a geometry optimization

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

archiveFiles()

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

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

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

handleFileLinkProperties(struct)

Fix existing Jaguar file link properties and add any new ones

Parameters

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

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

periodicMaintenance()

This method is periodically called while the workflow is running

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

storeFilenames()

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

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

writeInput()

Write the input file for the step

class schrodinger.application.matsci.jaguarworkflows.WorkFlow(struct, options, count, jobq, strcleaner=None, logger=None, subhierarchy=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, subhierarchy=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

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

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

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

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