vibrational_analysis_step package#
Submodules#
vibrational_analysis_step.fermi module#
The variational treatment of Fermi resonances in generalized VPT2 (GVPT2).
The deperturbed VPT2 energies of the states in a resonance – a fundamental and the overtone or combination band it is resonant with – are the diagonal of a small effective Hamiltonian, and the cubic force constant that couples them its off-diagonal elements. States joined by any chain of resonances form one polyad, whose Hamiltonian is diagonalized; each state takes the eigenvalue of the eigenvector it dominates.
Adapted from pyVPT2’s fermi_solver.py (Copyright 2021-2024 Philip Nelson,
BSD-3-Clause; see THIRD_PARTY_LICENSES.rst).
- class vibrational_analysis_step.fermi.Interaction(left: State, right: State, phi: float, ftype: int)[source]#
Bases:
objectA Fermi resonance between two states.
- Parameters:
left (State) – The fundamental, and the overtone or combination band.
right (State) – The fundamental, and the overtone or combination band.
phi (float) – The cubic force constant coupling them, in cm^-1.
ftype (int) – 1 for a fundamental and an overtone (i = 2j), 2 for a fundamental and a combination band (i = j + k).
- ftype: int#
- phi: float#
- class vibrational_analysis_step.fermi.Polyad(interaction)[source]#
Bases:
objectStates coupled by Fermi resonances, and their effective Hamiltonian.
- class vibrational_analysis_step.fermi.State(state: tuple, nu: float)[source]#
Bases:
objectA vibrational state and its (deperturbed) frequency.
- Parameters:
state (tuple of int) – The modes excited:
(i,)a fundamental,(j, j)an overtone,(j, k)a combination band.nu (float) – Its frequency in cm^-1.
- nu: float#
- state: tuple#
- vibrational_analysis_step.fermi.fermi_solver(interactions)[source]#
The variationally corrected frequencies of the states in resonance.
- Parameters:
interactions ([Interaction])
- Returns:
Each state in a resonance (a tuple of mode indices) and its frequency.
- Return type:
dict
vibrational_analysis_step.metadata module#
This file contains metadata describing the results from VibrationalAnalysis
- vibrational_analysis_step.metadata.metadata = {'results': {'G0': {'description': 'The constant term G0 of the VPT2 zero-point energy', 'dimensionality': 'scalar', 'format': '.3f', 'type': 'float', 'units': '1/cm'}, 'ZPE': {'description': 'The anharmonic (VPT2) zero-point energy, with its constant G0', 'dimensionality': 'scalar', 'format': '.4f', 'property': 'ZPE#VPT2#{model}', 'type': 'float', 'units': 'kJ/mol'}, 'ZPE correction': {'description': 'The anharmonic correction to the zero-point energy', 'dimensionality': 'scalar', 'format': '.4f', 'property': 'ZPE correction#VPT2#{model}', 'type': 'float', 'units': 'kJ/mol'}, 'chi': {'description': 'The anharmonicity constants', 'dimensionality': '[n_modes, n_modes]', 'format': '.3f', 'property': 'anharmonicity constants#VPT2#{model}', 'type': 'json', 'units': '1/cm'}, 'combination bands': {'description': 'The combination bands nu_i + nu_j', 'dimensionality': '[n_modes, n_modes]', 'format': '.2f', 'property': 'combination bands#VPT2#{model}', 'type': 'json', 'units': '1/cm'}, 'energy': {'description': 'The energy at the structure analyzed', 'dimensionality': 'scalar', 'format': '.6f', 'type': 'float', 'units': 'kJ/mol'}, 'flagged modes': {'description': 'The modes VPT2 should not be trusted for (1-based)', 'dimensionality': '[n_flagged]', 'type': 'json'}, 'fundamentals': {'description': 'The anharmonic fundamental frequencies', 'dimensionality': '[n_modes]', 'format': '.2f', 'property': 'anharmonic fundamentals#VPT2#{model}', 'type': 'json', 'units': '1/cm'}, 'harmonic ZPE': {'description': 'The harmonic zero-point energy from the same Hessian', 'dimensionality': 'scalar', 'format': '.4f', 'property': 'harmonic ZPE#VPT2#{model}', 'type': 'float', 'units': 'kJ/mol'}, 'harmonic frequencies': {'description': 'The harmonic frequencies', 'dimensionality': '[n_modes]', 'format': '.2f', 'property': 'harmonic frequencies#VPT2#{model}', 'type': 'json', 'units': '1/cm'}, 'n_modes': {'description': 'The number of vibrational modes', 'dimensionality': 'scalar', 'type': 'integer'}, 'overtones': {'description': 'The first overtones, 2 nu_i', 'dimensionality': '[n_modes]', 'format': '.2f', 'property': 'overtones#VPT2#{model}', 'type': 'json', 'units': '1/cm'}, 'resonances': {'description': 'The Fermi resonances treated, as text', 'dimensionality': 'scalar', 'type': 'string'}}}#
Description of the computational models for VibrationalAnalysis.
Hamiltonians, approximations, and basis set or parameterizations, only if appropriate for this code. For example:
metadata["computational models"] = { "Hartree-Fock": { "models": { "PM7": { "parameterizations": { "PM7": { "elements": "1-60,62-83", "periodic": True, "reactions": True, "optimization": True, "code": "mopac", }, "PM7-TS": { "elements": "1-60,62-83", "periodic": True, "reactions": True, "optimization": False, "code": "mopac", }, }, }, }, }, }
vibrational_analysis_step.tk_vibrational_analysis module#
The graphical part of a Vibrational Analysis step
- class vibrational_analysis_step.tk_vibrational_analysis.TkVibrationalAnalysis(tk_flowchart=None, node=None, canvas=None, x=None, y=None, w=200, h=50)[source]#
Bases:
TkNodeThe graphical part of a Vibrational Analysis step in a flowchart.
- tk_flowchart#
The flowchart that we belong to.
- Type:
TkFlowchart = None
- node#
The corresponding node of the non-graphical flowchart
- Type:
Node = None
- namespace#
The namespace of the current step.
- Type:
str
- tk_subflowchart#
A graphical Flowchart representing a subflowchart
- Type:
TkFlowchart
- canvas#
The Tk Canvas to draw on
- Type:
tkCanvas = None
- dialog#
The Pmw dialog object
- Type:
Dialog
- x#
The x-coordinate of the center of the picture of the node
- Type:
int = None
- y#
The y-coordinate of the center of the picture of the node
- Type:
int = None
- w#
The width in pixels of the picture of the node
- Type:
int = 200
- h#
The height in pixels of the picture of the node
- Type:
int = 50
- self[widget]#
A dictionary of tk widgets built using the information contained in Vibrational Analysis_parameters.py
- Type:
dict
See also
VibrationalAnalysis,TkVibrationalAnalysis,VibrationalAnalysisParameters- create_dialog()[source]#
Create the dialog: the optimization, the route and derivatives, the displacement and the treatment of resonances and low modes.
vibrational_analysis_step.vibrational_analysis module#
Non-graphical part of the Vibrational Analysis step in a SEAMM flowchart
- class vibrational_analysis_step.vibrational_analysis.VibrationalAnalysis(flowchart=None, title='Vibrational Analysis', extension=None, logger=<Logger vibrational_analysis_step.vibrational_analysis (WARNING)>)[source]#
Bases:
NodeThe non-graphical part of a Vibrational Analysis step in a flowchart.
- parser#
The parser object.
- Type:
configargparse.ArgParser
- options#
It contains a two item tuple containing the populated namespace and the list of remaining argument strings.
- Type:
tuple
- subflowchart#
A SEAMM Flowchart object that represents a subflowchart, if needed.
- Type:
seamm.Flowchart
- parameters#
The control parameters for Vibrational Analysis.
See also
TkVibrationalAnalysis,VibrationalAnalysis,VibrationalAnalysisParameters- NOISE = {'quartic': 5.0}#
The spreads between equivalent finite-difference routes (cm^-1) above which the force constants are too noisy to trust to a few cm^-1. Only the quartic spread: it grows with noise as 1/step^2 (Hessians) or 1/step^3 (gradients), while the cubic spread at the default steps is mostly the higher-order (truncation) error, harmless (propane, 0.20: cubic 6.6, quartic 3.4 cm^-1, ZPE within 0.2 cm^-1 of Gaussian’s).
- STEP = {'Hessians': 0.2, 'gradients': 0.1}#
The default steps, dimensionless (2026-11-05, against Gaussian 09)
- property git_revision#
The git version of this module.
- property version#
The semantic version of this module.
- vpt2_analysis(P, configuration, directory)[source]#
Optimize (optionally), take the Hessian, the derivatives at the displaced structures and the VPT2 results for the configuration.
- Parameters:
P (dict) – The step’s parameter values.
configuration (molsystem._Configuration) – Updated by the optimization.
directory (pathlib.Path) – Where vpt2.json is written.
- Returns:
As
vibrational_analysis_step.vpt2.vpt2(), plus ‘hessian’, ‘derivatives’, ‘spread’ and ‘energy’ (kJ/mol).- Return type:
dict
vibrational_analysis_step.vibrational_analysis_parameters module#
Control parameters for the Vibrational Analysis step in a SEAMM flowchart
- class vibrational_analysis_step.vibrational_analysis_parameters.VibrationalAnalysisParameters(defaults={}, data=None)[source]#
Bases:
ParametersThe control parameters for Vibrational Analysis.
You need to replace the “time” entry in dictionary below these comments with the definitions of parameters to control this step. The keys are parameters for the current plugin,the values are dictionaries as outlined below.
Examples
parameters = { "time": { "default": 100.0, "kind": "float", "default_units": "ps", "enumeration": tuple(), "format_string": ".1f", "description": "Simulation time:", "help_text": ("The time to simulate in the dynamics run.") }, }
- parameters{str: {str: str}}
A dictionary containing the parameters for the current step. Each key of the dictionary is a dictionary that contains the the following keys:
- parameters[“default”] :
The default value of the parameter, used to reset it.
- parameters[“kind”]enum()
Specifies the kind of a variable. One of “integer”, “float”, “string”, “boolean”, or “enum”
While the “kind” of a variable might be a numeric value, it may still have enumerated custom values meaningful to the user. For instance, if the parameter is a convergence criterion for an optimizer, custom values like “normal”, “precise”, etc, might be adequate. In addition, any parameter can be set to a variable of expression, indicated by having “$” as the first character in the field. For example, $OPTIMIZER_CONV.
- parameters[“default_units”]str
The default units, used for resetting the value.
- parameters[“enumeration”]tuple
A tuple of enumerated values.
- parameters[“format_string”]str
A format string for “pretty” output.
- parameters[“description”]str
A short string used as a prompt in the GUI.
- parameters[“help_text”]str
A longer string to display as help for the user.
See also
VibrationalAnalysis,TkVibrationalAnalysis,VibrationalAnalysisParameters,VibrationalAnalysisStep- parameters = {'derivatives': {'default': 'automatic', 'default_units': '', 'description': 'At the displaced structures:', 'enumeration': ('automatic', 'Hessians', 'gradients'), 'format_string': '', 'help_text': 'What is computed at the structures displaced along the normal modes: Hessians (2 per mode) when the engine has an analytic Hessian, else gradients (about 2n^2 for n modes, but each is cheap and they can run as parallel tasks). Hessians by finite differences of forces are possible but cost more than the gradients.', 'kind': 'enum'}, 'displacement': {'default': 'automatic', 'default_units': '', 'description': 'Displacement:', 'enumeration': ('automatic', 'mass-weighted'), 'format_string': '.3f', 'help_text': "The step along each normal mode, in dimensionless (reduced) normal coordinates. 'automatic' is 0.20 for Hessians and 0.10 for gradients (whose quartic constants use steps up to 3 times as large); 'mass-weighted' is Gaussian's 0.025 Å amu^1/2 for every mode. Smaller steps amplify the noise in the Hessians or gradients, larger ones add higher-order error. Against Gaussian 09 for propane, 0.05 gave a ZPE 44 cm^-1 off, 0.20 0.2 cm^-1.", 'kind': 'float'}, 'fmax': {'default': 0.0005, 'default_units': 'eV/Å', 'description': 'Converge to forces below:', 'enumeration': (), 'format_string': '.5f', 'help_text': 'The largest force at which the optimization stops.', 'kind': 'float'}, 'hessian route': {'default': 'automatic', 'default_units': '', 'description': 'Calculations via:', 'enumeration': ('automatic', 'warm engine over MDI', 'separate tasks'), 'format_string': '', 'help_text': 'How the Model Chemistry is driven: automatically (the warm MDI engine when the program has one and is installed here, else separate tasks where the job runs them); the warm engine, which also allows the optimization; or separate tasks, which run in parallel but cannot optimize the structure.', 'kind': 'enum'}, 'low frequency': {'default': 200.0, 'default_units': '1/cm', 'description': 'Flag modes below:', 'enumeration': (), 'format_string': '.1f', 'help_text': 'Modes below this frequency are flagged: VPT2 is unreliable for torsions and other large-amplitude motions. They stay in the anharmonic zero-point energy.', 'kind': 'float'}, 'max steps': {'default': 500, 'default_units': '', 'description': 'Maximum optimization steps:', 'enumeration': (), 'format_string': 'd', 'help_text': 'The most steps the optimization may take.', 'kind': 'integer'}, 'optimize': {'default': 'yes', 'default_units': '', 'description': 'Optimize the structure first:', 'enumeration': ('yes', 'no'), 'format_string': 's', 'help_text': "Optimize the structure over the Model Chemistry's engine before the analysis. VPT2 needs a tight minimum: the cubic and quartic force constants are differences of Hessians or gradients, and a residual force shows up in them.", 'kind': 'boolean'}, 'resonance threshold': {'default': 1.0, 'default_units': '1/cm', 'description': 'Resonance threshold:', 'enumeration': (), 'format_string': '.2f', 'help_text': "Martin's second criterion: the smallest second-order shift that counts as a resonance.", 'kind': 'float'}, 'resonance window': {'default': 200.0, 'default_units': '1/cm', 'description': 'Resonance window:', 'enumeration': (), 'format_string': '.1f', 'help_text': "Martin's first criterion: how close a fundamental must be to an overtone or combination band to be checked for a resonance.", 'kind': 'float'}, 'resonances': {'default': 'GVPT2 (variational)', 'default_units': '', 'description': 'Fermi resonances:', 'enumeration': ('GVPT2 (variational)', 'deperturbed VPT2', 'none (plain VPT2)'), 'format_string': '', 'help_text': "How Fermi resonances are treated: found by Martin's criteria, removed from the perturbation sums, then the resonant states mixed variationally (GVPT2, the default); only removed (deperturbed VPT2); or not treated, which can give wildly wrong frequencies near a resonance.", 'kind': 'enum'}, 'results': {'default': {}, 'default_units': '', 'description': 'results', 'enumeration': (), 'format_string': '', 'help_text': 'The results to save to variables or in tables.', 'kind': 'dictionary'}}#
vibrational_analysis_step.vibrational_analysis_step module#
- class vibrational_analysis_step.vibrational_analysis_step.VibrationalAnalysisStep(flowchart=None, gui=None)[source]#
Bases:
objectHelper class needed for the stevedore integration.
This must provide a description() method that returns a dict containing a description of this node, and create_node() and create_tk_node() methods for creating the graphical and non-graphical nodes.
The dictionary for the description is the class variable just below these comments. The felds are as follows:
- my_description{str, str}
A human-readable description of this step. It can be several lines long, and needs to be clear to non-expert users. It contains the following keys: description, group, name.
- my_description[“description”]tuple
A description of the Vibrational Analysis step. It must be clear to non-experts.
- my_description[“group”]str
Which group in the menus to put this step. If the group does not exist it will be created. Common groups are “Building”, “Control”, “Custom”, “Data”, and “Simulations”.
- my_description[“name”]str
The name of this step, to be displayed in the menus.
- create_node(flowchart=None, **kwargs)[source]#
Create and return the new node object.
- Parameters:
flowchart (seamm.Node) – A non-graphical SEAMM node
**kwargs (keyword arguments) – Various keyword arguments such as title, namespace or extension representing the title displayed in the flowchart, the namespace for the plugins of a subflowchart and the extension, respectively.
- Return type:
- create_tk_node(canvas=None, **kwargs)[source]#
Create and return the graphical Tk node object.
- Parameters:
canvas (tk.Canvas) – The Tk Canvas widget
**kwargs (keyword arguments) – Various keyword arguments such as tk_flowchart, node, x, y, w, h representing a graphical flowchart object, a non-graphical node for a step, and dimensions of the graphical node.
- Return type:
- description()[source]#
Return a description of what this step does.
- Returns:
description
- Return type:
dict(str, str)
- my_description = {'description': 'Anharmonic vibrational analysis (VPT2) with any Model Chemistry', 'group': 'Properties', 'name': 'Vibrational Analysis'}#
vibrational_analysis_step.vpt2 module#
Second-order vibrational perturbation theory (VPT2), independent of any code.
The anharmonic frequencies and zero-point energy of a molecule at a minimum, from
its Cartesian Hessian there (
Harmonic: the normal modes and harmonic frequencies, rotational constants and Coriolis coupling constants);Hessians, or gradients, at geometries displaced along the normal modes (
displacements()), whatever code or model computes them;the cubic and semi-diagonal quartic force constants by finite differences (
force_constants_from_hessians(),force_constants_from_gradients());VPT2 with Fermi resonances deperturbed, optionally treated variationally (GVPT2) (
vpt2()).
Units: atomic units in, except masses in amu; the force constants and all results in cm^-1, in dimensionless (reduced) normal coordinates q_i = sqrt(omega_i) Q_i.
Only molecules without degenerate modes (asymmetric tops) are handled: the
formulas for degenerate modes, needed by linear molecules and symmetric and
spherical tops, are not yet in, so Harmonic refuses those molecules.
The VPT2 formulas, the detection of Fermi resonances and the finite-difference assembly are adapted from pyVPT2 (Copyright 2021-2024 Philip Nelson, BSD-3-Clause; see THIRD_PARTY_LICENSES.rst).
- exception vibrational_analysis_step.vpt2.DegenerateModesError[source]#
Bases:
ValueErrorThe molecule has degenerate vibrations, which VPT2 here cannot treat.
- class vibrational_analysis_step.vpt2.Harmonic(hessian, masses, coordinates, degenerate_tolerance=0.001, allow_degenerate=False)[source]#
Bases:
objectThe harmonic analysis at a minimum.
- Parameters:
hessian (array (3N, 3N)) – The Cartesian Hessian, E_h/bohr^2.
masses (array (N,)) – The atomic masses, amu.
coordinates (array (N, 3)) – The coordinates, bohr.
degenerate_tolerance (float) – Relative tolerance for equal principal moments of inertia, which mark a linear molecule or a symmetric or spherical top.
allow_degenerate (bool) – Accept symmetric and spherical tops, whose degenerate vibrations need formulas not implemented yet: only the zero-point energy is then right (it does not depend on how the components of a degenerate mode are chosen). Linear molecules are always refused.
- omega#
Harmonic frequencies, cm^-1, ascending.
- Type:
array (n,)
- L#
Orthonormal mass-weighted normal modes.
- Type:
array (3N, n)
- modes#
The Cartesian displacement, bohr, for a unit step in each dimensionless normal coordinate.
- Type:
array (3N, n)
- B#
Rotational constants, cm^-1, A >= B >= C.
- Type:
array (3,)
- zeta#
Coriolis coupling constants about the principal axes of B.
- Type:
array (3, n, n)
- degenerate#
Whether the molecule is a symmetric or spherical top.
- Type:
bool
- degenerate_sets#
The modes of each degenerate vibration (two or three components).
- Type:
[[int]]
- gradient_to_normal(gradient)[source]#
A Cartesian gradient (E_h/bohr) in dimensionless normal coordinates, cm^-1.
- to_normal(hessian)[source]#
A Cartesian Hessian (E_h/bohr^2) in dimensionless normal coordinates, cm^-1.
- property zpe#
The harmonic zero-point energy, cm^-1.
- exception vibrational_analysis_step.vpt2.NotAMinimumError[source]#
Bases:
ValueErrorThe structure has imaginary or vanishing vibrational frequencies.
- vibrational_analysis_step.vpt2.STEPS = {'gradients': {'pair': ((-1, -1), (1, -1), (-1, 1), (1, 1)), 'single': (-3, -1, 1, 3)}, 'hessians': {'pair': (), 'single': (-1, 1)}}#
The steps, in units of the displacement, for each finite-difference route
- vibrational_analysis_step.vpt2.displacements(harmonic, route='hessians', step=0.05)[source]#
The displaced geometries for the finite differences.
- Parameters:
harmonic (Harmonic)
route (str) – ‘hessians’ (2n geometries) or ‘gradients’ (2n^2 + 2n).
step (float or array (n,)) – The displacement in dimensionless normal coordinates, the same for every mode or one per mode (see
mass_weighted_steps()).
- Returns:
keyis a tuple of (mode, steps) pairs, e.g.((3, 1),)or((1, -1), (4, 1)); coordinates (N, 3) in bohr.- Return type:
[(key, coordinates)]
- vibrational_analysis_step.vpt2.find_resonances(omega, phi_ijk, omega_threshold=200.0, k_threshold=1.0)[source]#
The Fermi resonances, by Martin’s criteria.
- Returns:
Each with ‘type’ (1: omega_j ~ 2 omega_i; 2: omega_k ~ omega_i + omega_j), ‘fundamental’ (the mode), ‘states’ (the pair of modes), ‘delta’ (the mismatch, cm^-1) and ‘K’ (the second-order shift, cm^-1).
- Return type:
[dict]
- vibrational_analysis_step.vpt2.force_constants_from_gradients(harmonic, gradients, step=0.05, reference=None)[source]#
The cubic and semi-diagonal quartic force constants from the gradients at the displaced geometries.
- Parameters:
harmonic (Harmonic)
gradients (dict) – Cartesian gradients (E_h/bohr) by the keys from
displacements()with route ‘gradients’.step (float or array (n,)) – The displacement(s) used.
reference (array, optional) – The gradient at the reference geometry (zero at the minimum by default).
- Return type:
- vibrational_analysis_step.vpt2.force_constants_from_hessians(harmonic, hessians, step=0.05, reference=None)[source]#
The cubic and semi-diagonal quartic force constants from the Hessians at the displaced geometries.
- Parameters:
harmonic (Harmonic)
hessians (dict) – Cartesian Hessians (E_h/bohr^2) by the keys from
displacements().step (float or array (n,)) – The displacement(s) used.
reference (array, optional) – The Hessian at the reference geometry at the same level as the displaced ones (mixed levels); by default the harmonic one’s diagonal, omega.
- Returns:
phi_ijk (array (n, n, n))
phi_iijj (array (n, n)) – In cm^-1, symmetrized.
spread (dict) – The largest difference between finite-difference routes that should agree (‘cubic’, ‘quartic’), cm^-1: a measure of the numerical noise.
- vibrational_analysis_step.vpt2.mass_weighted_steps(harmonic, size=0.025)[source]#
Steps of the same size in mass-weighted Cartesian coordinates for every mode (Gaussian’s convention, 0.025 Å amu^1/2), as dimensionless steps: q_i = Q sqrt(omega_i), so stiff modes get larger dimensionless steps and floppy ones smaller. Against Gaussian 09 (2026-11-05) a uniform 0.05 was too small for C-H stretches: Hessian noise dominated the quartic constants (propane ZPE 44 cm^-1 off; 0.2 cm^-1 at a step like Gaussian’s).
- vibrational_analysis_step.vpt2.vpt2(harmonic, phi_ijk, phi_iijj, fermi=True, gvpt2=True, omega_threshold=200.0, k_threshold=1.0, low_mode=200.0)[source]#
VPT2 frequencies and zero-point energy.
- Parameters:
harmonic (Harmonic)
phi_ijk (arrays) – The cubic and semi-diagonal quartic force constants, cm^-1.
phi_iijj (arrays) – The cubic and semi-diagonal quartic force constants, cm^-1.
fermi (bool) – Deperturb Fermi resonances (Martin’s criteria).
gvpt2 (bool) – Then treat them variationally (GVPT2). Needs
fermi.omega_threshold (float) – Martin’s criteria for a resonance, cm^-1.
k_threshold (float) – Martin’s criteria for a resonance, cm^-1.
low_mode (float) – Modes below this, cm^-1, are flagged: VPT2 is unreliable for torsions and other large-amplitude motions.
- Returns:
‘omega’, ‘nu’ (fundamentals), ‘nu_deperturbed’, ‘overtones’, ‘combinations’ (n x n), ‘chi’ (n x n), ‘zpe_harmonic’, ‘zpe’ (the anharmonic ZPE including the constant term), ‘g0’ (the constant term), ‘resonances’, ‘flagged’ (mode indices); all cm^-1.
- Return type:
dict
Module contents#
vibrational_analysis_step A SEAMM plug-in for Vibrational Analysis