opan.utils.execute

Functions to enable Open Anharmonic to execute external software packages.

Functions

opan.utils.execute.execute_orca(inp_tp, work_dir, exec_cmd, subs=None, subs_delims=('<', '>'), sim_name='orcarun', inp_ext='txt', out_ext='out', wait_to_complete=True, bohrs=False)

Executes ORCA on a dynamically constructed input file.

Warning

Function is still under active development! Execution with wait_to_complete == True should be robust, however.

Execution

Generates an ORCA input file dynamically from information passed into the various arguments, performs the run, and returns with exit info and computation results (in some fashion; still under development). Any required resources (.gbw, .xyz, etc.) MUST already be present in work_dir. No check for pre-existing files of the same base name is made; any such will be overwritten.

ORCA MUST be called using a wrapper script; this function does not implement the redirection necessary to send output from a direct ORCA call to a file on disk.

If wait_to_complete is True, the subprocess.call() syntax will be used and the function will not return until execution of the wrapper script completes. If False, [indicate what will be returned if not waiting].

Todo

execute_orca: The different output modes, depending on waiting or not.

The command to call ORCA must be specified in the parameter list syntax of the args argument to the subprocess.Popen constructor. The implementation is flexible and general, to allow interface with local scripts for, e.g., submission to a job queue in a shared-resource environment.

Valid ORCA input syntax of the resulting text is NOT checked before calling ORCA.

No mechanism is implemented to detect hangs of ORCA. Periodic manual oversight is recommended.

Template Substitution

See utils.template_subst for implementation details of the tag substitution mechanism.

Here, in addition to performing any substitutions on the input file template as indicated by subs, the special tags INP and OUT, enclosed with the subs_delims delimiters, will be replaced with sim_name + '.' + inp_ext and sim_name + '.' + out_ext, respectively, in the input template and in all elements of exec_cmd before executing the call. In the special case of inp_ext == None, the INP tag will be replaced with just sim_name (no extension), and similarly for OUT if out_ext == None. The tag NAME will be replaced just with sim_name in all cases.

inp_ext and out_ext must be different, to avoid collisions.

Return Values

The information returned depends on the value of wait_to_complete:

If wait_to_complete == True:

A tuple of objects is returned, with elements of type

(OrcaOutput, OpanXYZ, OrcaEngrad, OrcaHess)

These objects contain the corresponding results from the computation, if the latter exist, or None if they are missing.

If wait_to_complete == False:

TBD, but current intention is to return the PID of the spawned subprocess.

Signature

Parameters:
  • inp_tp – str – Template text for the input file to be generated.
  • work_dir – str – Path to base working directory. Must already exist and contain any resource files (.gbw, .xyz, etc.) required for the calculation.
  • exec_cmd – list of str – Sequence of strings defining the ORCA execution call in the syntax of the Popen constructor. This call must be to a local script; stream redirection of the forked process is not supported in this function.
  • subs – dict of str, optional – Substitutions to be performed in the template (see Template Substitution, above).
  • subs_delims – 2-tuple of str, optional – Tag delimiters passed directly to template_subst(). Defaults to ('<','>').
  • sim_name – str, optional – Basename to use for the input/output/working files. If omitted, “orcarun” will be used.
  • inp_ext – str, optional – Extension to be used for the input file generated (default is ‘txt’).
  • out_ext – str, optional – Extension to be used for the output file generated (default is ‘out’).
  • wait_to_complete – bool, optional – Whether to wait within this function for ORCA execution to complete (True), or to spawn/fork a child process and return (False). Default is True. False IS NOT YET IMPLEMENTED.
  • bohrs – bool, optional – Flag to indicate the units (Bohrs or Angstroms) of the coordinates in .xyz and .trj files.
Returns:

[varies] – tuple of objects or int PID. Varies depending on wait_to_complete; see Return Values above
Raises:
  • ValueError – If inp_ext and out_ext are identical.
  • KeyError – If special tag names INP, OUT, or NAME are defined in subs
  • TypeError – If any elements in subs are not tuples