Help_function_library_yair module

Created on Mon Nov 22 18:17:17 2021 @author: Yair Reichman

class Help_function_library_yair.Constants(eVA=False)

Bases: object

A class that aims to handle constants and unit conversion. Sometimes it implemented as an instance attribute, and it appears at the initiation function, then it can be called as : <instance>.cons Other times it imported as an outer scope instance of the Constants class and then treated as just a class varibale.

set_eVA(eVA)

eV2J(ener_value)

Parameters

ener_value (float) – gets energy value in eV.

Returns

Float – returns energy value in J.

J2eV(ener_value)

Parameters

ener_value (float) – gets energy value in J.

Returns

Float – returns energy value in eV.

A2m(conver_value)

Parameters

conver_value (float) – Gets metric value in A.

Returns

float – returns metric value in m.

m2A(conver_value)

Parameters

conver_value (float) – Gets metric value in m.

Returns

float – returns metric value in A.

sec2fs(conver_value)

fs2sec(conver_value)

Help_function_library_yair.to_1D_vec(vec)

Parameters

vec (np.array) – This method enforce any 1D vector in any form into the shape of 1D vector in the shpae of (n,) while n is the number of rows. Pay attention that there is no another axis, and all opertations such as tranpose does not take any action on the resulted vector.

Returns

np.array – The original vector in a form of a 1D vector.

Help_function_library_yair.find_peak_half_max_width(locpot_vec)

Parameters

locpot_vec (numpy.ndarray, (N,2)) – Gets a 2d matrix with two columns represents [:,0] = positionscoords, and [:,1] represents the potential values (v(z)).

Returns

flaot – It returns the average width of the peaks.

Help_function_library_yair.to_column_vec(vec)

As oppose the to_1D_vec method, this function do the opposite, it enforce any 1D or a column vector into column vector in the form (n,1) where n is the number of rows. Pay attention that here we hve addtitonal axis where we can perform an actions like traspose. :param vec: The original vector we wish convert into a column vector :type vec: np.array

Returns

np.array – The original vector in a form of a coulmn vector.

Help_function_library_yair.to_row_vec(vec)

Similar to to_column_vec but it enforces the original vector into a row vector of the form (1,n) where n is the number of columns here. :param vec: The original vector we wish convert into a row vector :type vec: np.array

Returns

np.array – The original vector in a form of a row vector.

Help_function_library_yair.find_peaks(x, y, to_plot=False, dist=None)

Parameters

• x (np.array, array_like) – The Spatial coordinates vector.

• y (np.array, array_like) – The functional values of the spatial coordiantes vector. The definiion for f(x) = y. Usually will be the local potential vector.

• to_plot (bool, optional, default: False) – Flag that determines whether to enable plotting or not.

• dist (float, optional, default: None) – The distance between peaks.

Returns

numpy.ndarray – It returns a matrix of two columns. The first column is for the peaks position, and the second column is for and their heights. It also can plot.

Help_function_library_yair.find_peaks_maxima(x, y, ignore_local_maxima=False, to_plot=False, prominence=None)

Parameters

• x (np.array, array_like) – spatial coordinates vector.

• y (np.array, array_like) – Potential values v(z) vector.

• ignore_local_maxima (bool, optional, default: False) – It enables to turn on the option to ignore local maxima points.

• to_plot (bool, optional, default: False) – Flag that determines whether to enable plotting or not.

• prominence (float, optional, the default is None) – Input to detemine the prominence threshold for the find_peak.

Returns

numpy.ndarray – It returns a matrix of the maximum peaks. The first column is the maximum peaks position. The second column is the maximum peaks height. It also can plot.

Help_function_library_yair.get_prominence(z, v, num_of_min=None, is_max=False)

Parameters

• z (np.array, array_like) – The spatial coordinates vector.

• v (np.array, array_like) – The potential values (v(z)) vector

• num_of_min (int, optional, default : None) – Input to detemine how many kind of minima’s we have in our system.

• is_max (bool, optional, default : None) –

Returns

int – The prominence of out system regarding the main number of minima’s.

Help_function_library_yair.find_peaks_minima(x, y, ignore_local_minima=False, to_plot=False, prominence=None)

Parameters

• x (np.array, array_like) – The spatial coordinates vector.

• y (np.array, array_like) – The potential values (v(z)) vector

• ignore_local_minima (bool, optional, default: False) – It enables to turn on the option to ignore local minima points.

• to_plot (bool, optional, default: False) – This is a flag that determines whether to enable plotting or not.

• prominence (float, optional, the default is None) – Input to detemine the prominence threshold for the find_peak.

Returns

numpy.ndarray – It returns a matrix of the minimum peaks. The first column is the minimum peaks position. The second column is the minimum peaks height. It also can plot.

Help_function_library_yair.create_k_grid(N, L, dimention='1D')

Parameters

• N (int/float) – The number of measuerment sample. The number of the k-grid points.

• L (int/float) – The actual length of the system. Should be given in units of [m].

• dimention (str, {'1D', '2D'}, optional, default: '1D') – The choices are in the brackets. It defines the K-grid for 1D or 2D mesh.

Returns

K grid vector. Column vector. (numpy array with a shape of (N,1))

Help_function_library_yair.normalize_wave_function_numerically(z, wave_function, units='Meter')

Parameters

• z (np.array, array_like) – The spatial coordinates vector where the wave function spreads.

• wave_function (np.array, array_like) – The complex values of the wave function in at the relevant z positions.

• units (str, {'Meter', 'Angstrum'], optioanl, default: 'Meter') – The choices are in the brackets. It defines the units of the normilization factor.

Returns

A (flaat) – The numeric normaliztion factor.

Help_function_library_yair.normalize_wave_function(wave_equation, bound_up=inf, bound_down=0, units='Meter')

Parameters

• wave_equation (lambda) – It is in a lambda function format. It can be a static function or a lambda state. The equation of the wave function we wish to normalize. In this project, mainly supplied as a gaussian wave function.

• bound_up (int/float, optional, default: smp.oo) – The intgration boundaries. (default = inifinity)

• bound_down (int/float, optional, default: -smp.oo) – The intgration boundaries. (default = -inifinity)

• units (str, {'Meter', 'Angstrum'], optioanl, default: 'Meter') – The choices are in the brackets. It defines the units of the normilization factor.

Returns

A (int/float) – The normalization factor. Where psi(x) = A*f(x) -> it returns A.

Help_function_library_yair.normalize_wave_function_sym(wave_equation, bound_up=oo, bound_down=0, units='Meter')

Parameters

• wave_equation (lambda) – It is in a lambda function format. It can be a static function or a lambda state. The equation of the wave function we wish to normalize. In this project, mainly supplied as a gaussian wave function.

• bound_up (int/float, optional, default: smp.oo) – The intgration boundaries. (default = inifinity)

• bound_down (int/float, optional, default: -smp.oo) – The intgration boundaries. (default = -inifinity)

• units (str, {'Meter', 'Angstrum'], optioanl, default: 'Meter') – The choices are in the brackets. It defines the units of the normilization factor.

Returns

A (float) – The symbolic normaliztion factor.

Help_function_library_yair.is_normalized(z, psi_values, units='Meter')

Parameters

• z (np.array, array_like) – The spatial coordinates the wave function is specified at.

• psi_values (np.array, array_like) – The wavefunction values along the spatial coordinates. Must suit the units for angstrums.

• units (str, {'Meter', 'Angstrum'], optioanl, default: 'Meter') – The choices are in the brackets. It defines the units of the normilization factor.

Returns

bool – It checks if the wave function is normalized, True if it does, atherwise it returns False. It performs numerical integrarion and checks if it to be equal to 1.

Help_function_library_yair.gaussian_function_sym(k0, sigma, z0, dimention='1D', A=None)

Parameters

• k0 (float) – The initial momentum value,

• sigma (float) – The standard devaiation of the gaussian wave-function.

• z0 (float) – Initial poisition where the wave function is centered at.

• dimention (str, {'1D', '2D'}, optional, default: '1D') – The choices are in the brackets. It defines the K-grid for 1D or 2D mesh.

• A (float, optional, default: None) – If we already calculated the normaliztion factor we can supply it here. Otherwise it calculate from scratch here.

Returns

lambda – It returns a symbolic expression of the wavefunction, in lambda format.

Help_function_library_yair.gaussian_function(x, k0, sigma, z0, dimention='1D', A=None)

Parameters

• x (np.array) – The spatial coordinates vector.

• k0 (float) – The initial momentum value,

• sigma (float) – The standard devaiation of the gaussian wave-function.

• z0 (float) – Initial poisition where the wave function is centered at.

• dimention (str, {'1D', '2D'}, optional, default: '1D') – The choices are in the brackets. It defines the K-grid for 1D or 2D mesh.

• A (float, optional, default: None) – If we already calculated the normaliztion factor we can supply it here. Otherwise it calculate from scratch here.

Returns

np.array – The wave function vector.

Help_function_library_yair.get_psi0(k0, sigma, z0, z, dimention='1D', sqrd_psi=False, units='Meter')

Parameters

• k0 (float) – The initial momentum value,

• sigma (float) – The standard devaiation of the gaussian wave-function.

• z0 (float) – Initial poisition where the wave function is centered at.

• dimention (str, {'1D', '2D'}, optional, default: '1D') – The choices are in the brackets. It defines the K-grid for 1D or 2D mesh.

• sqrd_psi (bool, optional, default: False) – It gives an optiona to return also the absolute sqrd of the wave function.

• units (str, {'Meter', 'Angstrum'], optioanl, default: 'Meter') – The choices are in the brackets. It defines the units of the normilization factor.

Returns

np.array, np.array – The first vector represents the spatial coordinates grid and the second vector represnts the wave function value at this position. the values are complex numbers.

Help_function_library_yair.get_first_derivative_fft(x, y, L=None)

Parameters

• x (np.array) – The spatial coordinates vector.

• y (np.array) – The appropriate function-values corresponds the spatial coordinates vector.

• L (float, optional, default: None) – It should be supplied with the length of the system. It stands for the creation of the K-grid vector.

Returns

np.array, np.array – It returns the spatial coordinates vector and the first derivative vecotr.

Help_function_library_yair.get_second_derivative_fft(x, y, L=None)

Parameters

• x (np.array) – The spatial coordinates vector.

• y (np.array) – The appropriate function-values corresponds the spatial coordinates vector.

• L (float, optional, default: None) – It should be supplied with the length of the system. It stands for the creation of the K-grid vector.

Returns

np.array, np.array – It returns the spatial coordinates vector and the second derivative vecotr.

Help_function_library_yair.get_first_derivative(x, y)

Numerical derivative :param x: The spatial coordinates vector. :type x: np.array :param y: The appropriate function-values corresponds the spatial coordinates vector. :type y: np.array

Returns

np.array, np.array – It returns the spatial coordinates vector and the first derivative vector.

Help_function_library_yair.get_second_derivative(x, y)

Numerical derivative :param x: The spatial coordinates vector. :type x: np.array :param y: The appropriate function-values corresponds the spatial coordinates vector. :type y: np.array

Returns

np.array, np.array – It returns the spatial coordinates vector and the second derivative vector.

Help_function_library_yair.interpolate_pchip(N, *args)

The interpolant uses monotonic cubic splines to find the value of new points. (PCHIP stands for Piecewise Cubic Hermite Interpolating Polynomial).

Parameters

• N (int/float) – It rerpesents the number of the desired samples.

• *args (numpy.ndarray (N, 2)/ np.array, np.array) – It the first column is for the coords vector, and the second column is for the potential. It can handle an input in the form of a 2-column matrix or two different array_like arguments.

Returns

• new_coords (np.array,(n,)) – It is the bew coords divided into the number of the N partition given as input.

• v (np.array (n,)) – It is the new potential divided into the number of the N partitiongiven as an input.

Help_function_library_yair.interpolate_cubic(N, *args)

Cubic interpolation.

Parameters

• N (int/float) – It rerpesents the number of the desired samples.

• *args (numpy.ndarray (N, 2)/ np.array, np.array) – It the first column is for the coords vector, and the second column is for the potential. It can handle an input in the form of a 2-column matrix or two different array_like arguments.

Returns

• new_coords (np.array,(n,)) – It is the bew coords divided into the number of the N partition given as input.

• v (np.array (n,)) – It is the new potential divided into the number of the N partitiongiven as an input.

Help_function_library_yair.potential_expectation_nadav(psi0_values, dx, v)

Parameters

• psi0_values (np.array) – The wave-function values in a vector.

• dx (float) – The spatial grid spacing.

• v (np.array) – The local potential vector.

Returns

float – It returns the value of the Potential Energy expectation value.

Help_function_library_yair.kinetic_energy_operator(psi0_values, z, L=None)

Parameters

• psi0_values (np.array) – The wave-function values in a vector.

• z (float) – The spatial grid vector.

• L (float, optional, default: None) – The length of the system. if not suuplied it is calculated as the difference between the last value of z and its first value. L=z[-1]-z[0]

Returns

np.array – It returns a vector of the results that comes after operates the kinetic energy operator on the wave-function vector.

Help_function_library_yair.kinetic_energy_expectation_value(psi0_values, z)

Parameters

• psi0_values (np.array) – The wave-function values in a vector.

• z (float) – The spatial grid vector.

Returns

float – It returns the value of the Kinetic Energy expectation value.

Help_function_library_yair.initial_momentum_yair(sigma, E0, L, z0, A, T0)

Parameters

• sigma (float/int) – Standard deviation in spatial grid for the gaussin wave function.

• E0 (float/int) – Initial Energy. Usually stands for the energy value of an electorn located at the bootom of the conduction band.

• L (float/int) – The length of the system.

• z0 (float/int) – Initial position where the gaussian wave-packet is centered.

• A (float/int) – Normaliztion factor.

• T0 (float/int) – Initial Kinetic energy.

Returns

float – The initial momentum of an electorn.

Help_function_library_yair.find_closest_value_in_array(num, arr)

Parameters

• num (int/float) – The value we wish to locate in the given array.

• arr (np.array) – The array in which we wish to find the index of the closest value.

Returns

int, float – It returns an index of the closest value (An integer) . And the closest value, position (a float).

Help_function_library_yair.to_2_column_mat(vec)

Parameters

vec (numpy.ndarray) – The input vector we wish convert.

Returns

numpy.ndarray – It retruns the input matrix in a form of 2 columns.

Help_function_library_yair.find_adjacent_minima_maxima(z, v, start_peak_pos, reverse=False, prominence=None)

Very not elegnat and very complex method to find adjacent minima to maxima point in a locpot vector.

Parameters

• z (np.array) – The spatial coordinates vector.

• v (np.array) – The local potential vector.

• start_peak_pos (float) – The initial position where to start seaching for the minima point.

• reverse (bool, optional, default: None) – It enables to look for maxima to minima adjacent points. (The reverse order).

• prominence (float, optional, default: None) – The prominence of the peak. It helps to detemine what peaks we wish relate during the calculation. For more inforamtion about this mathematical entity it is recommended to look for it on web (it has to be with topology in mathematics)

Returns

(int, float), (int, float) – It returns the values of the index and the position of the minima and maxima points with respect to the order in the reverse flag. If not supplied, the first index,position pair regards the minima point and the second index,position pair regards the maxima points. Otherwise - it is returned in the reveresed order. index - is an integer, and position is a float.

Help_function_library_yair.force_psi_units(psi, units='Meter')

Parameters

• psi (np.array) – The vector of the wave-function values to be forced into the desired units.

• units (str, {'Meter', 'Angstrum'], optioanl, default: 'Meter') – The choices are in the brackets. It defines the units of the normilization factor.

Returns

np.array – It returns a vector of the Wave-function values in the desired units.

Help_function_library_yair.run_one_time_step(wave_function, time_step, v, z, k)

Parameters

• wave_function (np.array) – Wave function values vector to be propagated.

• time_step (float) – dt. time step in which we wish perform the propagation proccess

• v (np.array) – Should be as the same size as wave_function vector. This is the local potential vector.

• z (np.array.) – Should be as the same size as wave_function vector. This is the spatial coordinates vector.

• k (np.array.) – Should be as the same size as wave_function vector. This the k grid axis vector.

Returns

np. array – It returns a vector of the one time-step propagated wave-fucntion.

Help_function_library_yair.calculate_probability_current(wave_function, k)

Parameters

• wave_function (np.array) – wave function values vector to be propagated.

• k (np.array.) – Should be as the same size as wave_function vector. This is the k grid axis vector.

Returns

float – It returns the probabilty current.

Help_function_library_yair.fft_first_drivative(wave_function, k)

Parameters

• wave_function (np.array) – The wave function values vector to be propagated.

• k (np.array) – Should be as the same size as wave_function vector. This is the k-grid axis vector.

Returns

np.array – It returns the first derivative of the wave_function

Help_function_library_yair.cumulative_probabilty(wave_function, z, z_cutoff, dz)

Parameters

• wave_function (np.array) – The Wave function values vector to be propagated.

• z (np.array) – The z spatial coordinates vector

• z_cutoff (float) – The maximum value of to calculate the accumulated probability.

• dz (float) – The spatial gird differnce between points.

Returns

float – The cumulative_probabilty value up to certain z value coordinate.

Help_function_library_yair.transmision_coeff(psi0, Nt, dt, v, z, k, z_position, path_to_save=None, final_time=None)

Integration for the all time of simulation, summing all the probabilty currents, for each time-step in the simulation.

Parameters

• psi0 (np.array) – The wave function values vector.

• Nt (int) – The number of time-step that are being made.

• dt (float) – The time-step magnitude.

• v (np.array) – The local potential vector.

• z (np.array) – The spatial coordinates vector.

• k (np.array) – K grid vector.

• z_position (float) – The position at which it calculates the transimission coefficient. Should be given in units of Meter.

• path_to_save (string, optional, default:None) – The absolute path to save the figure obtained from the calculation

• final_time (float, optional, default:None) – The top boundary for the integration as we can integrate until this given time of the simulation. It stands for t_f

Returns

float – It returns the calculated transmission coefficient.

Help_function_library_yair.adjust_grid_density(density, z, v)

Parameters

• density (float) – The grid density. A quantity that was determined through the convergence tests and is the number of the space steps divided by the length of the system.

• z (np.array) – The spatial coordinates vector.

• v (np.array) – The local potntial vector along the system.

Returns

np.array, np.array – It returns the new spatial coordinate vecor as z, and the new local potneital vector as v. They have been adjusted to the defined grid density supplied.

Help_function_library_yair.reach_plateau(x, y, critiria_plat=0.0001, tol_2=0.005)

Parameters

• x (np.array) – The independent variable, usually will be the spatial grid vector or time space vector.

• y (np.array) – The dependent variable. The matching value of a function to the respective x value. Can be the comulative probabilty.

• critiria_plat (float. optional, default: 0.0001) – The value we decide to relate as no change in slope to determine the plateau region. The closer to zero the stricter critiria.

• tol_2 (float. optional, default: 0.005) – The value we decide to relate as no change in values of the cumulative probabilty. The smaller value - the stricter critiria.

Returns

bool – It checks whether we reached plateau, namely steady-state according to the vector supplied.

Help_function_library_yair.is_straight_line(y)

Check if the input vector repesents a straight line :param y: The vector values we wish to check. :type y: np.array

Returns

bool – It returns whether the input vector is a straight line or not.

Help_function_library_yair.find_interface(x, y)

This is a method that was duplicated from LOCPOT Class. It also appears there. It helps when we wish to allocate the interface position of the system, but have not created a locpot class instance. :param x: It stands for the spatial coordinates array. :type x: np.array :param y: The local potential vector. :type y: np.array

Returns

int, float – It returns the interface index in the locpot vector, and its z position If the system does not contain an interface, it just returns the last spatial grid coordinate position and its corresponded index. -> [index,position] ==> [len(z)-1,z[-1]]

Help_function_library_yair.integrate_trapz(vector, df)

Parameters

• vector (np.array) – The vector we wish the integrate numerically.

• df (float) – The step difference between adjacent steps. It assumes the the vector is spaced evenlly.

Returns

float – The numerical intgration result.

Help_function_library_yair.plateau_val(x, y, critiria=0.0001)

Parameters

• x (np.array) – The spatial coordinates array.

• y (np.array) – The relevent functional values that corresponds the spatial coordinates vector.

• critiria (float, optional, default: 0.0001) – It can be changed for more of less strict evalutaion where the plateau has come.

Returns

float – It returns the average value of the points that the plateau spread on.

Help_function_library_yair.is_peak_minimum(peaks, peak)

Notes

Pay attention - the peak is within the range of the peaks and not at its edges. Otherwise it will raise an index out-of-range error.

Parameters

• peaks (numpt.ndarray, (N,2)) – The first column stands for the spatial poisition of the peaks. The second column is for the height of the peaks.

• peak (list: [int,float,float]) – The first argument is for the index of the peak inside the peaks array, The second argument is for the position of the peak. The third argument is for the height of the peak.

Returns

bool – This function checks whether a given peak is a minimum point. (or at least a local minimum).

Help_function_library_yair.is_peak_maximum(peaks, peak)

Notes

Pay attention - the peak is within the range of the peaks and not at its edges. Otherwise it will raise an index out-of-range error.

Parameters

• peaks (numpy.ndarray, (N,2)) – The first column stands for the spatial poisition of the peaks. The second column is for the height of the peaks.

• peak (list: [int,float,float]) – The first argument is for the index of the peak inside the peaks array, The second argument is for the position of the peak. The third argument is for the height of the peak.

Returns

bool – This function checks whether a given peak is a maximum point. (or at least a local maximum).

Help_function_library_yair.is_peak_maximum_2(z, v, peak_pos)

Notes

Pay attention - the peak is within the range of the peaks and not at its edges. Otherwise it will raise an index out-of-range error.

Returns

bool – This function checks whether a given peak is a maximum point. (or at least a local maximum).

Help_function_library_yair.r_sqrd(v_original, v_fitted)

Notes

This function calculates the R square fitting parameter between two vectors.

Parameters

• v_original (np.array) – The vector contains the values whom we wish to compare to.

• v_fitted (np.array) – The vector contains the values whom we wish to fit .

Returns

float – The calculated R sqrd value.

Help_function_library_yair.smooth_function(z, v)

Notes

This function calculates the R square fitting parameter between two vectors.

Parameters

• z (np.array) – The spatial coordinates array.

• v (np.array) – The relevent function’s values that corresponds the spatial coordinates vector.

Returns

np.array, np.array – This function returns the smoothed local potential vector with the corresponding spatial coordinates.