How To Initialize Hamiltonian matrices

Hamiltonian operators in matrix form correspond to ham:type set to 'matrix' and are represented by the type op_matrix_t. There are different ways how these operator matrices can be initialized in qdyn, which are described below.

Initializing from file

The recommended workflow for using qdyn is to construct the Hamiltonian matrices by an external script, e.g. using the QDYN-pylib, and save them in a file. In your qdyn program, you can then load these via the config file, by setting ham:op_form to 'file' and specifying the filename in ham:filename. If your matrix is stored in a file matrix.dat that is present in the runfolder, the corresponding line in the config file could read:

ham: mass = 1, n_surf = 4
* type = matrix, op_form = file, filename = matrix.dat, &
  op_type = 'pot', sparsity_model = indexed

The file matrix.dat must be in a format that can be read by read_op_matrix().

Initializing a specific matrix

Some special operators are implemented in qdyn and can be directly initialized via the config file without the need of constructing them by yourself. In this case, you need to select the desired ham:op_form and provide certain additional parameters, which may be different for the specific operators. For example, if you want to initialize the operator for the dipole interaction of an asymmetric top molecule with an linearly z-polarised pulse, the corresponding line in the config file could read

ham: A = 3, B = 2, C = 1, mu_a = 1, mu_b = 1, mu_c = 1
* type = matrix, op_type = dip, op_form = asym_top, &
  jmax = 2, pulse_pol = z, pulse_id = 1

Only a very limited set of operators are available implemented in qdyn. See ham:op_form for an overview.

Initializing a matrix programmatically

Although it is not the recommended workflow, it is possible to construct Hamiltonian matrices in your fortran program by hand. In this case, you first need to initialize an empty operator matrix with init_empty_op_matrix() in indexed storage format. Then, you set the individual (non-zero) entries of the matrix with add_hm_entry(). When your matrix is complete, sort its values with sort_indexed_matrix() and add the matrix to the Hamiltonian using set_op_matrices().

If you for example want to initialize a Hamiltonian consisting of a single identity matrix of dimension n stored in 'banded' format, the code snippet in your program could look like this:

call init_empty_op_matrix(op_matrix, n, 'dip', (/1/), 1, '.false.'          &
&                         sparsity_model='indexed')
do i = 1, n
  call add_hm_entry(i, i, one)
end do
call sort_indexed_matrix(op_matrix%row, op_matrix%col, op_matrix%val,       &
&                        major='row')
call set_op_matrices(ham, op_matrix, pulses, grid, 1, 1,                    &
&                    sparsity_model='banded')

The subroutine sort_indexed_matrix() will ensure that you use the most efficient storage by automatically sorting the matrix and set_op_matrices() converts the matrix to the desired sparsity_model with convert_op_matrix() and adds it to the Hamiltonian. Additionally, set_op_matrices() performes several consistency checks and initializes all necessary fields in the given ham_t. This helps eliminating error that might occur when adding matrices to ham_t manually.