Numerical Hyperpolarizabilities From Alpha

Hyperpolarizabilities Module

This module contains functions for extracting and calculating hyperpolarizabilities and related quantities from ORCA and Gaussian.

get_beta_quantities_from_alpha_orca get_beta_quantities_from_beta_gaussian Are the main functions which can be used to both extract beta and get beta quantities. Check those in the first place.

From ORCA it can generate files to compute alpha at different fields, and then use this output files to get numerical beta values. From Gaussian, it can extract beta from an .log file and it can can calculate beta values reported in this paper, https://doi.org/10.1021/jp107165k.

To install the library please check Installing of Python and Running the Code, and especially the chapter "Running from Python"

The version of the library should be >=0.1.15.

Then to use the library just do the following:

import girona_donostia as gd

And then just use the needed functions. For example:

gd.generate_input_files('path/to/template.inp', '/path/to/output', 5, 0.0005, 'central_diff')

alpha_tensor, diagonalized_tensor, P = gd.extract_polarizability_tensor(path/to/file.out) 

Below are the descriptions of the functions available in this module:

Functions

get_beta_quantities_from_alpha_orca
get_beta_quantities_from_beta_gaussian
Are the main functions which can be used to both extract beta and get beta quantities. Those might be the most useful.

generate_input_files(file_name, path_output=None, derivative_type='romberg', points=6, h=0.0005)

Generates input files for calculating hyperpolarizabilities using different derivative types.

Inputs:

• path_input (str): Path to the template input file in which fields will be changed. The displacements will be done to the field specified in the template files..
• path_output (str): Path to the directory where the generated files will be saved. If none is provided, it will be saved to the folder where the python file is.
• points (int): Number of points for romberg or central difference calculations. For romberg it is the number of points in one direction (i.e., if points = 7, then it will be 7 points in the positive direction, 7 in the negative direction + 0 0 0 field, i.e., 2*points + 1 points.), for central difference it is the total number of points.
• h (float): Step size for field for finite difference calculations. Do not need to specify this for Romberg.
• derivative_type (str): Type of derivative to use ('romberg' or 'central_diff').

Outputs:

• None. This function generates files in the specified output directory.

Example:

generate_input_files('path/to/template.inp', '/path/to/output', 5, 0.0005, 'central_diff')

extract_polarizability_tensor(path_file)

Extracts the polarizability tensor from an output file.

Inputs:

• path_file (str): Path to the ORCA output file containing the polarizability tensor.

Outputs:

• alpha_tensor (np.ndarray): The extracted polarizability tensor.
• diagonalized_tensor (np.ndarray): The diagonalized polarizability tensor.
• P (np.ndarray): The transformation matrix used for diagonalization.

Example:

alpha_tensor, diagonalized_tensor, P = extract_polarizability_tensor('/path/to/output/file')

extract_data_from_folder(path_folder, save_data=True)

Extracts data from all ORCA output files in a specified folder and optionally saves the extracted data. The files need to have .out extension.

Inputs:

• path_folder (str): Path to the folder containing the files to be processed.
• save_data (bool): Whether to save the extracted data. Default is True. It will be saved in the output folder.

Outputs:

• Extracted data from all files in the specified folder. The columns are 'x,y,z,alpha_xx,alpha_xy,alpha_xz,alpha_yx,alpha_yy,alpha_yz,alpha_zx,alpha_zy,alpha_zz' The first row in the 0 0 0 field, and then there are x, y, z contents in the increasing order. I.e., the order is -10, -9, ..., -1, 0, 1, ..., 9, 10. (or whatever fields were specified).

Example:

extracted_data = extract_data_from_folder('/path/to/folder')

calc_beta_from_alpha(data, derivative_type='romberg')

Calculates the numeric hyperpolarizability tensor (beta) from polarizabilities corresponding to different fields. Data can be extracted with extract_data_from_folder(path_folder, save_data=True) . Romberg and Central Difference Calculations are available.

Inputs:

• data (list): List containing polarizability data with the following header structure:
  • x, y, z, alpha_xx, alpha_xy, alpha_xz, alpha_yx, alpha_yy, alpha_yz, alpha_zx, alpha_zy, alpha_zz. And all polarizabilities corresponding to different field values. (Output of the extract_data_from_folder(path_folder, save_data=True) function).
• derivative_type (str): Type of derivative to use ('romberg' or 'central_diff'). Default is 'romberg'.

Outputs:

• beta (np.ndarray): The calculated hyperpolarizability tensor. The structure of beta is np.array([beta_xxx, beta_xyy, beta_xzz, beta_yxx, beta_yyy, beta_yzz, beta_zxx, beta_zyy, beta_zzz, beta_xyz])

Example:

data = extract_data_from_folder('/path/to/folder')
    # Add more data as needed
]

beta = calc_beta_from_alpha(data, 'central_diff')

extract_beta_from_gaussian_output(path_file)

Extracts the hyperpolarizability tensor (beta) from a Gaussian output file. The beta is extracted in the input orientation.

Inputs:

• path_file (str): Path to the Gaussian output file.

Outputs:

• beta (np.ndarray): The extracted hyperpolarizability tensor, in the input orientation. The structure of the beta file is. np.array([beta_xxx, beta_xyy, beta_xzz, beta_yxx, beta_yyy, beta_yzz, beta_zxx, beta_zyy, beta_zzz, beta_xyz])

Example:

beta = extract_beta_from_gaussian_output('/path/to/gaussian/output/file')

get_beta_quantities_from_beta_vector(beta)

Calculates various quantities from the hyperpolarizability tensor.

Inputs:

• beta (np.ndarray): The hyperpolarizability tensor. Can be obtained using extract_beta_from_gaussian_output or calc_beta_from_alpha Returns [var_avg_beta_zzz_sqr, var_avg_beta_zxx_sqr, var_DR, var_beta_hrs, var_beta_j_one, var_beta_j_three, var_anisotropy_parameter] Paper where all the quantities are defined https://doi.org/10.1021/jp107165k

Outputs:

• quantities (dict): A dictionary containing various calculated quantities derived from the hyperpolarizability tensor.

Example:

quantities = get_beta_quantities_from_beta_vector(beta)

get_beta_quantities_from_alpha_orca(path_to_folder, path_to_save, derivative_type='romberg')

Calculates beta quantities from alpha values using ORCA output files. This is a function which combines all previous functions to automatically extract Beta, and using it to calculate beta quantities and save it into an output file.

Inputs:

• path_to_folder (str): Path to the folder containing ORCA output files.
• path_to_save (str): Path to save the results.
• derivative_type (str): Type of derivative to use ('romberg' or 'central_diff'). Default is 'romberg'.

Outputs:

• None. This function saves the results to the specified file.

Example:

get_beta_quantities_from_alpha_orca('/path/to/folder', '/path/to/save/file', 'central_diff')

get_beta_quantities_from_beta_gaussian(path_to_file, path_to_save, derivative_type='romberg')

Calculates beta quantities from a Gaussian output file and saves the results. This is a function which combines all previous functions to automatically extract Beta, and using it to calculate beta quantities and save it into an output file.

Inputs:

• path_to_file (str): Path to the Gaussian output file.
• path_to_save (str): Path to save the results.
• derivative_type (str): Type of derivative to use ('romberg' or 'central_diff'). Default is 'romberg'.

Outputs:

• None. This function saves the results to the specified file.

Example:

get_beta_quantities_from_beta_gaussian('/path/to/gaussian/output/file', '/path/to/save/file', 'romberg')

Conversion Table of Beta between Gaussian output File and the ones reported here.

Index	Here	Gaussian Output
0	XXX	XXX
1	XYY	YXY
2	XZZ	ZXZ
3	YXX	XXY
4	YYY	YYY
5	YZZ	ZYZ
6	ZXX	XXZ
7	ZYY	YYZ
8	ZZZ	ZZZ
9	XYZ	YXZ

This table can be used to check that data is extracted correctly + to compare beta values calculted with this program to ones obtained by Gaussian.

Examples

In the Examples/Numerical_Hyperpolarizabilities/*

You can find three examples of calculations. For HCl, phenol, and piridine. There are present both input and output orca files, and gaussian output files. Those can be used to test the functions presented in this paragraph.

The formulas were testes by checking numerical beta values with analytical beta values obtained by Gaussian, and beta quantities were checked by using Nachsos library.