pibronic.vibronic.orthonormal package

Code involved in the creation of orthonormal matrices

Submodules

pibronic.vibronic.orthonormal.create module

this module creates an orthonormal matrix used in the creation of ‘artificial’ vibronic models

pibronic.vibronic.orthonormal.create.create_orthonormal_matrix_lambda_close_to_identity(order, tuning_parameter)

returns an orthonormal matrix U which is parameterized by the tuning_parameter If tuning_parameter is 0.0 then it returns Identity. For values > 0.0 it returns U’s of increasing ‘distance’ from Identity The ‘distance’ is defined as the matrix norm of the difference of U and Identity takes: the order of the matrix and tuning_parameter

pibronic.vibronic.orthonormal.create.main(args)

pibronic.vibronic.orthonormal.sequences module

this module handles sequences of (y, x) pairs which are used in the creation of orthonormal matrices,

# TODO - this section is out of date and should probably be modified

The orthonormal matrices are used to create ‘artificial’ vibronic models (S):

• To begin you choose any real square matrix (E), which we can consider the ‘eigenvalues’ of the desired output matrix (S).
• Next a orthonormal matrix (U) is generated, we can consider these the ‘eigenvectors’ of the desired output matrix (S).
• Finally we preform a unitary transformation on (E) using (U) which gives us (S).

Of importance is how (U) is generated. It would be optimal to have a function g(A, P) which generates an orthonormal matrix (U). The parameter (A) would define the order of (U). The ‘tuning’ parameter (P) would define the ‘distance’ of (U) from the identity matrix of the same order. The function g’s domain, for a fixed (A), would be the reals in [0.0, 1.0] and the range would be a matrix in [Identity, M], where (M) is the ‘farthest’ matrix from Identity. Thus as we increase the value of (P), for a fixed (A), the trace of (U) should decrease and the off-diagonal values should increase. A challenging problem is defining the meaning of ‘distance’ for an arbitrary square matrix? We chose to define the ‘distance’ as the Frobenius norm (AKA matrix norm) of the difference between (U) and Identity: ‘distance(P)’ = ||U(P) - Identity||

Our first attempt at solving this problem was: * Generate a random matrix (K) of order A * Create a skew symmetric matrix S = K - K.T * Calculate the orthonormal matrix U(P) = expm(P * S)

However because we randomly generated the matrix (K) this method suffers from periodicity issues. For a matrix of order 2, the ‘distance’ of (U) from Identity is periodic, and the period depends on the matrix (K). It behaves as follows:

• P = 0 : U is Identity
• P = period / 4 : U is maximally diagonal and has a trace of 0
• P = period / 2 : U is -Identity and has a trace of -2
• P = 3 period / 4 : U is maximally diagonal and has a trace of 0

For a matrix of order 3 or higher it is non trivial to determine the period

Therefore we have chosen to go with a repeatable solution: Instead of randomly generating the matrix (K) we always choose (K) to be a upper unitriangular matrix of order (A). This allows us to precalculate an estimate of the period of the ‘distance’ of the matrix (U). Our approach to finding the period, for a fixed (A), works as follows:

• Generate an upper unitriangular matrix (K) of order A
• Create a skew symmetric matrix S = K - K.T
• Calculate the ‘distance(x)’ = ||U(x) - Identity|| for x in [0, 1E6]
• Plot y=’distance(x)’ and visually or algorithmically select a continuous sequence of increasing y values, optimally the sequence begins very close to identity
• This sequence of pairs [(y_{i}, x_{i}) (y_{i+n}, y_{i+n}] is then saved to a file

For each choice of (A) we can then obtain a sequence which forms the range of the function g(A, P). We restrict the domain of (P) values to be [0.0, 1.0] and choose a mapping of any P > 0.0 to a given pair in the sequence (y, x).

Thus the code for creating an orthonormal matrix which is used to create an ‘artificial’ vibronic models (S) is:

• Generate an upper unitriangular matrix (K) of order A
• Create a skew symmetric matrix S = K - K.T
• If P = 0.0 then U = Identity, otherwise:
  • Retrieve a pair (y,x) using the tuning parameter (P)
  • Calculate the orthonormal matrix U = expm(x * S)

pibronic.vibronic.orthonormal.sequences.Pair

alias of pibronic.vibronic.orthonormal.sequences.pair

pibronic.vibronic.orthonormal.sequences.build_SKSM_and_identity(order)

returns the skew symmetric matrix and identity matrix for the given matrix order this is code that was factored out of other functions

pibronic.vibronic.orthonormal.sequences.check_minimum_length_of_sequence(sequence)

asserts that a sequence’s length is > the defined minimum length

pibronic.vibronic.orthonormal.sequences.debugging_matrix_checking_function(args)

for quick checking of the unitary transformation matrix which is generated using the sequence over a sample of lambda values

pibronic.vibronic.orthonormal.sequences.difference_function(skew_symmetric_matrix, identity)

returns a function which calculates the difference between the unitary matrix, parameterized by alpha, and identity

pibronic.vibronic.orthonormal.sequences.find_first_turn_around_point(SKSM, identity)

return a tuple (y, x) which are the values before the first turn around point

pibronic.vibronic.orthonormal.sequences.generate_and_save_x_pairs(order, p_list)

generates and saves a list of tuples (containing 2 floats) the 2 floats are lower and upper bounds on acceptable x values to use in generating a monotonic sequence saves them to a file named using the string x_pair_filename, in the directory that this module is located in

pibronic.vibronic.orthonormal.sequences.generate_full_monotonic_sequence(order)

saves two files, sequence_#.data and sequence_#.pairs sequence_#.pairs are the x pairs representing sequences where the frobenius norm is monotonic sequence_#.data is a list of x, y values this sequence is discontinuous and built up of x

pibronic.vibronic.orthonormal.sequences.generate_full_monotonic_sequence_for_plotting(order)

generates one data file for plotting with gnuplot

pibronic.vibronic.orthonormal.sequences.generate_monotonic_sequence_to_first_turn_around(order)

generates a sequence of the frobenius norm to the first turn around point which will be used when generating new matrices

pibronic.vibronic.orthonormal.sequences.generate_sequences_for_plotting(order)

this generates sequences of the 1,2 and infinity norm’s of the difference between identity and the skew symmetric matrix this provides data that can be plotted to analyze the periodic behaviour of the norm’s for different size of matrices

pibronic.vibronic.orthonormal.sequences.generate_turning_point_sequence_for_plotting(order)

this generates two sequences, the frobenius norm and the ‘turning points’ for plotting to visually confirm that those data points can be used to generate a monotonic sequence of x,y pairs which can be used to generate increasingly coupled matrices

pibronic.vibronic.orthonormal.sequences.list_of_turning_points(SKSM, identity)

return a list of tuples (y, x) which are the values before a turning point these are the last points before the function begins decreasing

pibronic.vibronic.orthonormal.sequences.load_sequence(order, delimiter=', ')

returns a list of [y, x] pairs (which are length 2 lists) throws an assert error if the file does not exist takes a integer parameter which specifies which file to load

pibronic.vibronic.orthonormal.sequences.main()

pibronic.vibronic.orthonormal.sequences.path_to_sequence_file(order)

returns the path to a sequence file associated with the order argument

pibronic.vibronic.orthonormal.sequences.path_to_x_pair_file(order)

returns the path to a x_pair file associated with the order argument

pibronic.vibronic.orthonormal.sequences.save_sequence(order, sequence, fmt='%.18e', delimiter=', ')

saves a list of iterables, commonly they are length 2 and contain floats, but the fmt parameter can be changed for flexibility pickles them to a file named using the string sequence_filename, in the directory that this module is located in

pibronic.vibronic.orthonormal.sequences.select_pair(sequence, tuning_parameter)

holds the logic for selecting a (y, x) pair from the sequence that matches the tuning parameter