schema for vibrational analysis

[loriab]

Description

propose data structures for conveying a harmonic vibrational analysis

• based upon https://github.com/psi4/psi4/blob/master/psi4/driver/qcdb/vib.py#L331-L359 . notable change is no complex frequencies to humor json.
• there's some non-atomic units in there. they're pretty industry standard, but could be replaced by au equivalents (frequency and force constant)
• vibanal will need to own a molecule. haven't worked out how json does that yet
• I've listed dimension as nvib. in practice could be ndof for full Hessian, nvib for only vibrations (rotations/translations discarded or never computed), ? for partial solutions (e.g., A2 only)

Status

• Ready to go

[berquist]

turnin -> turning

[berquist]

My questions are:

• What is the distinction between properties and procedures? Is a property something calculated ab inito, and a procedure something derived from a property?
• What about intensities? I think [km/mol] is standard, rather than au.
• What about isotopic masses?
• Regarding the Hessian itself, will it only appear as return_result after "driver": "Hessian"? What happens when q is present, but want to convert to get w, but don't know what kind of Hessian is present?

For reference, from #32, given the Q-Chem input

$rem
jobtype freq
method hf
basis sto-3g
$end

$molecule
0 1
H         0.0000000000    0.0000000000   -0.9325440499
F         0.0000000000    0.0000000000    0.0229640499
$end

the Jmol QCJSON output is

["QCJSON 0-0-0.Jmol_14.29.17__2018-06-15_14:15",
{
	"__jmol_created":"Thu Aug 30 14:36:03 EDT 2018",
	"__jmol_source":"/home/eric/Dropbox/research/cclib/calculations/frequencies/hydrogen_fluoride/qchem.out"
},
{
	"__jmol_block":"Job 1",
	"metadata":{
		"__jmol_info":{
			"modelLoadNote":"E(Total) = -98.57284734\n4474.34 cm^-1\n",
			"calculationType":"STO-3G"
		}
	},
	"steps":[
		{
			"__jmol_block":"Model 1",
			"topology":{
				"atoms":{
					"coords_units":["angstroms",1.8897261254578281],
					"coords":[
						 0.00000E+0,	 0.00000E+0,	-8.59957E-1,
						 0.00000E+0,	 0.00000E+0,	 9.55508E-2
					],
					"symbol":["_RLE_",1,"H",1,"F"],
					"atom_number":["_RLE_",1,1,1,9]

				}
			},
			"metadata":{
				"__jmol_info":{
					"name":"E(Total) = -98.57284734",
					"modelNumberDotted":"1.1",
					"modelNumber":1,
					"modelFileNumber":1000001,
					"modelName":"E(Total) = -98.57284734",
					"initialAtomCount":2,
					"Energy":-98.572845,
					"modelProperties":{
						"PATH":"Job 1",
						"Energy":"-98.572845",
						".PATH":"Job 1"
					},
					"initialBondCount":0,
					"EnergyString":"-98.57284734",
					"modelIndex":0,
					"fileType":"qchem"
				}
			}
		}
		,
		{
			"__jmol_block":"Model 2",
			"topology":{
				"atoms":{
					"coords_units":["angstroms",1.8897261254578281],
					"coords":[
						 0.00000E+0,	 0.00000E+0,	-8.59957E-1,
						 0.00000E+0,	 0.00000E+0,	 9.55508E-2
					],
					"symbol":["_RLE_",1,"H",1,"F"],
					"atom_number":["_RLE_",1,1,1,9]

				}
			},
			"vibrations":[
				{
					"__jmol_block":"Vibration 1",
					"frequency":{"value":4474.34,"units":["cm^-1",4.55633590401805E-6]},
					"vectors":[
						 0.00000E+0,	 0.00000E+0,	 9.99000E-1,
						 0.00000E+0,	 0.00000E+0,	-5.30000E-2
					]					
				}
			],
			"metadata":{
				"__jmol_info":{
					"name":"4474.34 cm^-1",
					"modelNumberDotted":"1.2",
					"modelNumber":2,
					"modelFileNumber":1000002,
					"modelName":"4474.34 cm^-1",
					"initialAtomCount":2,
					"modelProperties":{
						"PATH":"Job 1:FrequenciesFrequencies",
						"FreqValue":"4474.34",
						"Mode":"1",
						"Frequency":"4474.34 cm^-1",
						".PATH":"Job 1:FrequenciesFrequencies"
					},
					"initialBondCount":0,
					"vibrationalMode":1,
					"modelIndex":1,
					"fileType":"qchem"
				}
			}
		}
	]
}
]

where the normal mode vectors are just whatever is parsed from the output file.

[dgasmith]

The other issue is I don't think there is a middle ground on units. Either we say unequivocally we are atomic units or we need to implement a full unit spec similar to above. I still think atomic units are safer and simpler for quantum chemistry (pretty much the only CMS area where this applies), but it is controversial.

[loriab]

I'm going to have to run soon. I agree the units issue is particularly messed up in vib-land. problem is no one recognizes au in this space. even frequency is this and this. question is really for the viz-ppl --- do we prepare stuff that's ready to display or stick with basic results and minimal value added.

Also pursuant to Eric's comments, I think the thing to do is actually both. Prepare the basics (plain un-mass-wtd Hessian) and that becomes the basic json transaction but also have an interpreted area with the symm, force constants, etc. that they want. similar to EFP (where jmol can't be expected to interpret basic EFP hints)

[langner]

Either we say unequivocally we are atomic units or we need to implement a full unit spec similar to above. I still think atomic units are safer and simpler for quantum chemistry (pretty much the only CMS area where this applies), but it is controversial.

Even if atomic units are the default or the only option, wouldn't it still be good to specify them?

[dgasmith]

@langner Absolutely.

[dgasmith]

@cryos @wadejong Can you give this a review in comparison to cjson?

[loriab]

I should add that since original posting

• I'm entirely converted to the notion of atomic units -- any convenience units (cm^-1, km/mol) can be taught to pint for user accessibility
• Better to teach pydantic (or other intermediary class) to serialize complex and so keep omega as real/imag rather than +/– compromise?
• agree on inclusion of IR intensity, also Raman activity
• I'd rather type this up in pydantic and export to schema than schema directly.
• proposed schema is roughly from the table below, if that's easier to scan

    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | key           | description (lbl & comment)                | units     | data (real/imaginary modes)                          |
    +===============+============================================+===========+======================================================+
    | omega         | frequency                                  | cm^-1     | nd.array(ndof) complex (real/imag)                   |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | q             | normal mode, normalized mass-weighted      | a0 u^1/2  | ndarray(ndof, ndof) float                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | w             | normal mode, un-mass-weighted              | a0        | ndarray(ndof, ndof) float                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | x             | normal mode, normalized un-mass-weighted   | a0        | ndarray(ndof, ndof) float                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | degeneracy    | degree of degeneracy                       |           | ndarray(ndof) int                                    |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | TRV           | translation/rotation/vibration             |           | ndarray(ndof) str 'TR' or 'V' or '-' for partial     |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | gamma         | irreducible representation                 |           | ndarray(ndof) str irrep or None if unclassifiable    |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | mu            | reduced mass                               | u         | ndarray(ndof) float (+/+)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | k             | force constant                             | mDyne/A   | ndarray(ndof) float (+/-)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | DQ0           | RMS deviation v=0                          | a0 u^1/2  | ndarray(ndof) float (+/0)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | Qtp0          | Turning point v=0                          | a0 u^1/2  | ndarray(ndof) float (+/0)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | Xtp0          | Turning point v=0                          | a0        | ndarray(ndof) float (+/0)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | theta_vib     | char temp                                  | K         | ndarray(ndof) float (+/0)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+
    | IR_intensity  | infrared intensity                         | km/mol    | ndarray(ndof) float (+/+)                            |
    +---------------+--------------------------------------------+-----------+------------------------------------------------------+