Package schrodinger :: Package application :: Package jaguar :: Module input :: Class JaguarInput

Class JaguarInput

object --+
         |
        JaguarInput

A class for specifying Jaguar input.

This is a thin wrapper to the mmjag library and carries very little internal information.

Instance Methods

[hide private]

__init__(self, input=None, name=None, handle=None, structure=None, genkeys=None, reload=None, run_kwargs=None, text=None)
There are three main ways to create a JaguarInput instance: from a Jaguar input file 'input', an mmjag handle 'handle', or a Structure instance 'structure'.

__del__(self)
Delete the mmjag handle and clean up the mmlibs.

__copy__(self)
Create a copy of the JaguarInput object, setting name to <jobname>_copy.

launch(self, *args, **kwargs)
Save the file and launch a job.

run(self, **kwargs)
Save the file and launch a job with the wait option.

save(self, follow_links=0, validate=None)
Write an input file to name.in.

saveAs(self, file_, follow_links=0, validate=None)
Write an input file to name.in and set the object's name attribute.

saveAsBatch(self, file_)
Write a batch file to file_.bat.

str

getInputText(self)
Return the text of the input file.

str

getZmatText(self, zmat=0)
Return the input file text corresponding to the specified Z matrix.

str or tuple

_getTempFile(self, return_handle=False)
Get a temporary file

str

_writeTempFile(self, text)
Write the specified text to a temporary file

_setNameFile(self, input)
Set the name and file properties from a named input file or jobname.

_getName(self)
Return the name of the job.

_setName(self, name)
Set the name of the job and update the filename.

getAtomCount(self, zmat=0)
Return the number of atoms for the specified zmat.

getValue(self, key)
Return the &gen section value for keyword 'key'.

getDefault(self, key)
Return the default value for &gen section keyword 'key'.

setValue(self, key, value)
Set the &gen section keyword 'key' to the value provided.

setValues(self, dict_)
Set multiple &gen section keywords from the provided dictionary 'dict_'.

__getitem__(self, key)
Return the &gen section value for keyword 'key'.

__setitem__(self, key, value)
Set the &gen section keyword 'key' to the value provided.

__delitem__(self, key)
Remove a key from the &gen section.

deleteKey(self, key)
Remove a key from the &gen section.

deleteKeys(self, keys)
Remove a list of keys from the &gen section.

getNonDefault(self)
Return a dictionary of all non-default keys except 'multip' and 'molchg', which must be retrieved explicitly since they are connected to the geometry.

bool

isNonDefault(self, key)
Has the specified key been set to a non-default value?

setDirective(self, name, value)
Set a file specification directive.

getDirective(self, name)
Get a file specification directive.

getDirectives(self)
Get all file specification directives, except for MAEFILE, which is weeded out by the mmjag function itself.

writeMaefile(self, filename=None, structs=None)
Write an associated .mae file and set the MAEFILE directive.

str or NoneType

getMaefilename(self, dont_create=False)
Get the filename of the Maestro file containing the input structure.

_getRestart(self)
Get the restart name associated with the input file.

getStructure(self, zmat=0)
Return a Structure representation of the specified zmat section.

getStructures(self)
Return a list of all available structure representations for zmat sections

setStructure(self, struct, zmat=0, set_molchg_multip=True)
Set one of the zmat sections from the provided Structure (or MMCT handle).

_checkStructures(self, structures)
Raise RuntimeError if structure with a lower number zmat structure is undefined when a higher number zmat structure is defined (e.g., zmat2 being defined when zmat1 is not).

bool

hasStructure(self, zmat=0)
Does this handle have a structure for the specified zmat section?

resetStructure(self, struct, molchg, multip, zmat=0)
Redefine the connectivity and formal charges for the input CT, and store the new structure in the current mmjag object, in the &zmat section indicated by the zmat argument.

deleteStructure(self, zmat=0)
Delete the specified structure

_setCounterpoise(self, atom, value, zmat=0)
Set the counterpoise status (True or False) for the specified atom.

str

preflight(self)
Run a preflight check and return any warnings.

makeInternalCoords(self, zmat=0)
Convert the specified Z-matrix to internal coordinates

makeCartesianCoords(self, zmat=0)
Convert the specified Z-matrix to Cartesian coordinates

dict

getUnknownKeywords(self)
Return a dictionary of all unknown keywords and their values

bool

sectionDefined(self, sect)
Determine if the specified section is defined

createSection(self, sect)
Create the specified section

deleteSection(self, sect)
Delete the specified section

clearAllConstraints(self)
Delete all constraints and their associated coord entries.

int

scanCount(self)
This function returns the total number of scan coordinates.

tuple

getScanCoordinate(self, i)
This function returns i-th scan coordinate.

setScanCoordinate(self, coord_type, atoms, initial_value, final_value, num_steps, step)
This function defines scan coordinate.

constrainAtomXYZ(self, index)
Constrain the XYZ coordinates of an atom.

constrainInternal(self, atom1, atom2, atom3=0, atom4=0)
Constrain an internal coordinate (bond, angle or torsion)

int

constraintCount(self)
This function returns the total number of constraints.

constraints(self)
Generator function that yields constraints instead of returning a list.

tuple or None

getConstraint(self, i)
This function returns i-th constraint.

setConstraint(self, coordinate_type, atoms, value)
This function defines constraint.

setActiveCoord(self, coordinate_type, atoms)
This function defines an active coordinate.

setAtomicBasis(self, atom_num, basis)
Set a per-atom basis set

str or NoneType

getAtomicBasis(self, atom_num)
Get the per-atom basis set for the specified atom

dict

getAllAtomicBases(self)
Get all per-atom basis sets

clearAtomicBases(self)
Clear all per-atom basis sets

getChargeConstraints(self)
Parse CDFT input file section to get charge constraints.

appendChargeConstraints(self, charge, weights)
Set charge constraints for CDFT.

setChargeConstraints(self, constraints)
Set charge constraints for CDFT.

clearChargeConstraints(self)
Clear all CDFT charge constraints

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables

[hide private]

reload = False
hash(x)

run_kwargs = {}

Properties

[hide private]

name
Return the name of the job.

restart
Get the restart jobname based on the current name.

Inherited from object: __class__

Method Details

[hide private]

init(self, input=None, name=None, handle=None, structure=None, genkeys=None, reload=None, run_kwargs=None, text=None)
(Constructor)

There are three main ways to create a JaguarInput instance: from a Jaguar input file 'input', an mmjag handle 'handle', or a Structure instance 'structure'.

The 'input' parameter will provide for initialization and job name from an existing Jaguar input file. (If no new name is provided, calling the save() method will overwrite the original file.)

Note that the structure and name parameters will modify the object status after loading from a file or initialization from a handle has completed. This can be utilized to get the settings from a Jaguar input file but replace the geometry for a new calculation.

Parameters:

input (str) - A jaguar input file; a default name will be derived from the input value.
name (str) - A jaguar job name that will override the name derived from 'input'.
handle (int) - An mmjag handle, pointing to an existing mmjag instance in memory.
structure (schrodinger.structure.Structure) - A structure that will populate a new mmjag instance. If specified with 'input' or 'handle' it will replace any structure provided by them.
genkeys (dict) - A dictionary of keyword/value pairs to set in the input &gen section. If keywords are specified in this mapping and the file, the genkeys value will be used.
reload (bool) - Specifies whether to reload the job from an output file in the run() method. Default value is False, but can be modified by setting JaguarInput.reload to a different value.
run_kwargs (dict) - The run_kwargs dictionary provides default keyword settings for the run function that is called from the launch and run methods. Default is to set no defaults, but this can be modified by setting JaguarInput.run_kwargs to a different value.
text (str) - The complete text of a Jaguar input file.

Overrides: object.__init__

launch(self, *args, **kwargs)

Save the file and launch a job. Returns a jobcontrol.Job object.

Uses the class run_kwargs value as base for keyword arguments to the run function.

run(self, **kwargs)

Save the file and launch a job with the wait option. Returns a JaguarOutput object. Raises an exception if the job failed.

Set the class (or instance) attribute reload to True to load existing output files of the same name.

save(self, follow_links=0, validate=None)

Write an input file to name.in.

Parameters:

follow_links (int) - Flag specifying whether to follow links in the structure to a Jaguar restart file, if present, to append additional sections. Options are:
- mm.MMJAG_APPEND_OFF: don't follow links to append additional sections (default)
- mm.MMJAG_APPEND_OVERWRITE: append sections from link, overwriting any that overlap
- mm.MMJAG_APPEND_NO_OVERWRITE: append sections from link, not overwriting any that overlap
- mm.MMJAG_APPEND_X_OVERWRITE: exclusively append sections from link, deleting any already present
- mm.MMJAG_APPEND_X_NO_OVERWRITE: append sections from link only if no such sections already present
validate (bool) - If True, sections dependent upon geometry, molecular state, basis set are removed if invalid. If not entered (None), default is to validate if "following links".

saveAs(self, file_, follow_links=0, validate=None)

Write an input file to name.in and set the object's name attribute.

Parameters:

follow_links (int) - Flag telling whether to follow links in the structure to a Jaguar restart file, if present, to append additional sections. Options are:
- mm.MMJAG_APPEND_OFF: don't follow links to append additional sections (default)
- mm.MMJAG_APPEND_OVERWRITE: append sections from link, overwriting any that overlap
- mm.MMJAG_APPEND_NO_OVERWRITE: append sections from link, not overwriting any that overlap
- mm.MMJAG_APPEND_X_OVERWRITE: exclusively append sections from link, deleting any already present
- mm.MMJAG_APPEND_X_NO_OVERWRITE: append sections from link only if no such sections already present
validate (bool) - If True, sections dependent upon geometry, molecular state, basis set are removed if invalid. If not entered (None), default is to validate if "following links".

saveAsBatch(self, file_)

Write a batch file to file_.bat. Note that the object's name attribute will not be set.

Parameters:

file_ (str) - The filename to save to. The ".bat" extension will be added if necessary.

getInputText(self)

Return the text of the input file. Note that the input file will not be saved to self._file.

Returns: str: The text of the input file

getZmatText(self, zmat=0)

Return the input file text corresponding to the specified Z matrix.

Parameters:

zmat - The z matrix to return the text for. Must be one of mm.MMJAG_ZMAT1, mm.MMJAG_ZMAT2, or mm.MMJAG_ZMAT3.

Returns: str

The text for the specified Z matrix

_getTempFile(self, return_handle=False)

Get a temporary file

Parameters:

return_handle (bool) - If True, an open file handle for writing to the temporary file will be returned. If False, no file handle will be returned.

Returns: str or tuple

If return_handle is True, then a file name (str) will returned. This file will already exist but will be empty. If return_handle is False, then a tuple of

A file name (str)
An open file handle for writing (file)

will be returned.

_writeTempFile(self, text)

Write the specified text to a temporary file

Parameters:

text (str) - The text to write to the file

Returns: str

The name of the file that text has been written to

_setNameFile(self, input)

Set the name and file properties from a named input file or jobname.

This method keeps the filename and jobname in sync.

getValue(self, key)

Return the &gen section value for keyword 'key'.

The return type is as defined by mmjag_key_type().

setValue(self, key, value)

Set the &gen section keyword 'key' to the value provided.

If value is None, the keyword will be unset.

setValues(self, dict_)

Set multiple &gen section keywords from the provided dictionary 'dict_'.

Note that one easy way to specify the dict_ argument is via the "dict(basis='6-31g**', igeopt=1)" syntax for constructing a dictionary.

getitem(self, key)
(Indexing operator)

Return the &gen section value for keyword 'key'.

The return type is as defined by mmjag_key_type().

setitem(self, key, value)
(Index assignment operator)

Set the &gen section keyword 'key' to the value provided.

If value is None, the keyword will be unset.

delitem(self, key)
(Index deletion operator)

Remove a key from the &gen section. Note that deleteKey will raise an error if key is not recognized as a Jaguar keyword. This function will successfully delete the key.

isNonDefault(self, key)

Has the specified key been set to a non-default value?

Parameters:

key (str) - The key to check

Returns: bool

True if the specified key is set to a non-default value. False otherwise.

writeMaefile(self, filename=None, structs=None)

Write an associated .mae file and set the MAEFILE directive. If no name is provided, use jobname.mae. If no structs are provided, use self.getStructure().

If an absolute filename is not provided but the input file is known, write the mae file relative to the input file.

If no filename is given and no jobname is set, a random filename will be generated in the current directory.

Parameters:

structs - A list of structures
structures (list)

getMaefilename(self, dont_create=False)

Get the filename of the Maestro file containing the input structure. If no such file exists, it will be created unless c{dont_create} is True.

Parameters:

dont_create (bool) - If False, a Maestro file will be created if one does not yet exist. If True, None will be returned if no file exists.

Returns: str or NoneType

The requested filename as an absolute path. If no file exists and dont_create is True, None will be returned.

Raises:

RuntimeError - If no structure is present.

getStructure(self, zmat=0)


Return a Structure representation of the specified zmat section.

Note that if the JaguarInput instance was created from a Jaguar
input file that has no associated Maestro file (MAEFILE), the Lewis
structure is determined automatically based on atom distances.

Parameters

zmat (mmjag enum)
    The zmat to return (MMJAG_ZMAT1, MMJAG_ZMAT2, or MMJAG_ZMAT3).

getStructures(self)

Return a list of all available structure representations for zmat sections

The first call to getStructure is required because getStructure is guaranteed to return a structure, which might have been set in a different way

setStructure(self, struct, zmat=0, set_molchg_multip=True)


Set one of the zmat sections from the provided Structure (or MMCT
handle).

If set_molchg_multip is True, calling this method will update
the values of molchg and multip. molchg will be consistent
with the sum of formal charges in the provided CT, while
multip will be set according to the CT-level
i_m_Spin_multiplicity property.

Parameters

struct (schrodinger.structure.Structure)
    The structure to use for setting.

zmat (mmjag enum)
    The zmat to set (MMJAG_ZMAT1, MMJAG_ZMAT2, or MMJAG_ZMAT3).

set_molchg_multip
    Whether to update molecular charge and multiplicity
    (default is yes)

hasStructure(self, zmat=0)

Does this handle have a structure for the specified zmat section?

Parameters:

zmat (int) - The zmat to check (MMJAG_ZMAT1, MMJAG_ZMAT2, or MMJAG_ZMAT3)

Returns: bool

True if the specified structure is present. False otherwise.

resetStructure(self, struct, molchg, multip, zmat=0)


Redefine the connectivity and formal charges for the input CT,
and store the new structure in the current mmjag object, in the
&zmat section indicated by the zmat argument.

This function is used when the molecular geometry has changed such
that it may not be consistent with its original CT description in
terms of bond orders and formal charges, and we want to force the
creation of a new Lewis structure.

Parameters

struct (schrodinger.structure.Structure)
    The structure to use for setting.

molchg (integer)
    The value to use for the net molecular charge.

multip (integer)
    The value to use for the net molecular spin.

zmat (mmjag enum)
    The zmat to set (MMJAG_ZMAT1, MMJAG_ZMAT2, or MMJAG_ZMAT3).

deleteStructure(self, zmat=0)

Delete the specified structure

Parameters:

zmat - The z matrix to delete. Must be one of mm.MMJAG_ZMAT1, mm.MMJAG_ZMAT2, or mm.MMJAG_ZMAT3.

_setCounterpoise(self, atom, value, zmat=0)


Set the counterpoise status (True or False) for the specified atom.

Parameters

atom (int)
    The index of the atom to modify.

value (bool)
    Use True to make it counterpoise, False to make it real.

zmat (mmjag enum)
    The zmatrix to modify.

preflight(self)

Run a preflight check and return any warnings.

Returns: str: A string containing any warnings raised by the preflight check. If there were no warnings, an empty string is returned.

Note: As a side-effect, this function sets the mmjag error handler to mm.error_handler after running regardless of its previous value. If this leads to issues, a C function will have to be added and swig wrapped that return the current mmjag error handler so it can be restored.

makeInternalCoords(self, zmat=0)

Convert the specified Z-matrix to internal coordinates

Parameters:

zmat (int) - The Z-matrix to modify. Must be one of mm.MMJAG_ZMAT1, mm.MMJAG_ZMAT2, or mm.MMJAG_ZMAT3.

makeCartesianCoords(self, zmat=0)

Convert the specified Z-matrix to Cartesian coordinates

Parameters:

zmat (int) - The Z-matrix to modify. Must be one of mm.MMJAG_ZMAT1, mm.MMJAG_ZMAT2, or mm.MMJAG_ZMAT3.

getUnknownKeywords(self)

Return a dictionary of all unknown keywords and their values

Returns: dict: A dictionary of all unknown keywords and their values

sectionDefined(self, sect)

Determine if the specified section is defined

Parameters:

sect (str) - The section to check for

Returns: bool

True if the specified section is defined. False otherwise.

createSection(self, sect)

Create the specified section

Parameters:

sect (str) - The section to create

deleteSection(self, sect)

Delete the specified section

Parameters:

sect (str) - The section to delete

Raises:

ValueError - If the specified section does not exist

clearAllConstraints(self)

Delete all constraints and their associated coord entries. (Note that mm.mmjag_constraint_delete_all() does not delete the associated coord entries.)

scanCount(self)

This function returns the total number of scan coordinates.

Returns: int: scan count

getScanCoordinate(self, i)

This function returns i-th scan coordinate.

Returns: tuple: tuple that contains coordinate type, list of atoms, initial and final coordinate values, number of steps and step.

setScanCoordinate(self, coord_type, atoms, initial_value, final_value, num_steps, step)

This function defines scan coordinate. If atoms list size is less than 4, we add zeros to the list.

Parameters:

coord_type (int) - coordinate type
atoms (list) - list of atom indices
initial_value (float) - coordinate initial value
final_value (float) - coordinate final value
num_steps (int) - number of steps
step (float) - step value

constrainAtomXYZ(self, index)

Constrain the XYZ coordinates of an atom.

Parameters:

index (int) - The index of the atom to constrain

constrainInternal(self, atom1, atom2, atom3=0, atom4=0)

Constrain an internal coordinate (bond, angle or torsion)

Parameters:

atom1 (int) - The index of the first atom in the internal coordinate definition
atom2 (int) - The index of the second atom in the internal coordinate definition
atom3 (int) - The index of the third atom in the internal coordinate definition (0 if this coordinate is a bond)
atom4 (int) - The index of the fourth atom in the internal coordinate definition (0 if this coordinate is a bond or angle)

constraintCount(self)

This function returns the total number of constraints.

Returns: int: constraint count

getConstraint(self, i)

This function returns i-th constraint.

Returns: tuple or None: tuple that contains coordinate type, list of atoms and target value (may be None if cosntraint is not dynamic). If constraint type is MMJAG_SCAN_CONSTRAINT return None, so that we scan coordinates don't appear as constraints.

setConstraint(self, coordinate_type, atoms, value)

This function defines constraint. If atoms list size is less than 4, we add zeros to the list. If value is not None, we set this constraint as 'dynamic'.

Parameters:

coordinate_type (int) - coordinate type
atoms (list) - list of atom indices
value (float) - target value (for dynamic constraints only)

setActiveCoord(self, coordinate_type, atoms)

This function defines an active coordinate. If atoms list size is less than 4, we add zeros to the list.

Parameters:

coordinate_type (int) - coordinate type
atoms (list) - list of atom indices

setAtomicBasis(self, atom_num, basis)

Set a per-atom basis set

Parameters:

atom_num (int) - The atom number to set the basis set for
basis (str) - The basis set

getAtomicBasis(self, atom_num)

Get the per-atom basis set for the specified atom

Parameters:

atom_num (int) - The atom index to get the basis set for

Returns: str or NoneType

The basis set, or None if no basis set has been set for this atom

getAllAtomicBases(self)

Get all per-atom basis sets

Returns: dict: A dictionary of {atom index: basis set}. Atoms which do not have a per-atom basis set are not included in this dictionary.

getChargeConstraints(self)


Parse CDFT input file section to get charge constraints.
Assume &cdft section takes the form:

&cdft
net-charge
weight1 first-atom1 last-atom1
weight2 first-atom2 last-atom2
net-charge
weight3 first-atom3 last-atom3
weight4 first-atom4 last-atom4
&

@rtype constraints: list
@return constraints: list of CDFT constraints in the form
    [ (charge1, weights1), (charge2, weights2), ...]
where:
    charge: The target charge value for the specified atoms
    weights: A dictionary of {atom index: weight}

Return empty list if keyword icdft!=1 (i.e. not CDFT done)

@raise InvalidCDFTError if &cdft section invalid or not found
    when icdft keyword is 1

appendChargeConstraints(self, charge, weights)

Set charge constraints for CDFT. Append to existing constraints if previously set.

Parameters:

charge (float) - The target charge value for the specified atoms
weights (dict) - A dictionary of {atom index: weight}

setChargeConstraints(self, constraints)

Set charge constraints for CDFT. Overwrite existing constraints if previously set.

Parameters:

contraints - List of CDFT constraints. Each item of the list should be a (charge, weights) tuple, where weights is a dictionary with atom index as key and weight as value.
constraints (list)

Property Details

[hide private]

name

Return the name of the job.

Get Method:

_getName(self) - Return the name of the job.

Set Method:

_setName(self, name) - Set the name of the job and update the filename.

Delete Method:

'Set the jobname; also updates the filename based on the jobname.'

restart

Get the restart jobname based on the current name.

Get Method:: _getRestart(self) - Get the restart name associated with the input file.

Class JaguarInput

__init__(self, input=None, name=None, handle=None, structure=None, genkeys=None, reload=None, run_kwargs=None, text=None) (Constructor)

launch(self, *args, **kwargs)

run(self, **kwargs)

save(self, follow_links=0, validate=None)

saveAs(self, file_, follow_links=0, validate=None)

saveAsBatch(self, file_)

getInputText(self)

getZmatText(self, zmat=0)

_getTempFile(self, return_handle=False)

_writeTempFile(self, text)

_setNameFile(self, input)

getValue(self, key)

setValue(self, key, value)

setValues(self, dict_)

__getitem__(self, key) (Indexing operator)

__setitem__(self, key, value) (Index assignment operator)

__delitem__(self, key) (Index deletion operator)

isNonDefault(self, key)

writeMaefile(self, filename=None, structs=None)

getMaefilename(self, dont_create=False)

getStructure(self, zmat=0)

getStructures(self)

setStructure(self, struct, zmat=0, set_molchg_multip=True)

hasStructure(self, zmat=0)

resetStructure(self, struct, molchg, multip, zmat=0)

deleteStructure(self, zmat=0)

_setCounterpoise(self, atom, value, zmat=0)

preflight(self)

makeInternalCoords(self, zmat=0)

makeCartesianCoords(self, zmat=0)

getUnknownKeywords(self)

sectionDefined(self, sect)

createSection(self, sect)

deleteSection(self, sect)

clearAllConstraints(self)

scanCount(self)

getScanCoordinate(self, i)

setScanCoordinate(self, coord_type, atoms, initial_value, final_value, num_steps, step)

constrainAtomXYZ(self, index)

constrainInternal(self, atom1, atom2, atom3=0, atom4=0)

constraintCount(self)

getConstraint(self, i)

setConstraint(self, coordinate_type, atoms, value)

setActiveCoord(self, coordinate_type, atoms)

setAtomicBasis(self, atom_num, basis)

getAtomicBasis(self, atom_num)

getAllAtomicBases(self)

getChargeConstraints(self)

appendChargeConstraints(self, charge, weights)

setChargeConstraints(self, constraints)

name

restart

init(self, input=None, name=None, handle=None, structure=None, genkeys=None, reload=None, run_kwargs=None, text=None)
(Constructor)

getitem(self, key)
(Indexing operator)

setitem(self, key, value)
(Index assignment operator)

delitem(self, key)
(Index deletion operator)