This repository is outdated, please see the latest code at https://gitlab.desy.de/CMI/CMI-public/cmistark

CMIstark

This program can calculate, view, and analyze the energy levels of adiabatic Stark energy curves of linear, symmetric top, and asymmetric top molecules.

The program package is developed and maintained by the Controlled Molecule Imaging group (CMI) at the Center for Free-Electron Laser Science (CFEL), DESY and Universität Hamburg, Hamburg, Germany.

Program documentation is available online and (for version 1.0) in "CMIstark: Python package for the Stark-effect calculation and symmetry classification of linear, symmetric and asymmetric top wavefunctions in dc electric fields" by Yuan-Pin Chang, Frank Filsinger, Boris Sartakov, and Jochen Küpper, published as Computer Physics Communications 185, 339-349 (2014), DOI: 10.1016/j.cpc.2013.09.001; preprint available at arXiv:1308.4076 [physics]

Prerequisities:

Computer: Any Macintosh, PC, or Linux/UNIX workstations with a modern Python distribution.

The following external Python packages are also required:

• matplotlib
• numpy
• scipy
• sympy
• tables

Installation:

Installation is performed by executing the generic Python install command:

python setup.py install

in the unpacked source code directory.

In order to install this extension module in user-space, set up your environment for python to find it, e.g.,

setenv PYTHONUSERBASE=$HOME/.local

and run the install command

python setup.py install --user

Usage:

cmistark_calculate_energy

A (command line) script file called cmistark_calculate_energy is provided as a driver for the calculation of Stark curves. Its command-line options are the following:

--help:           this help
--<moleculename>: specify which molecule is used in the calculation.
--dc-fields=:     specify the range of the DC electric field (in kV/cm) by the
                  following way: start:end:step, example: --dc-fields=0:150:151.
--Jmax_calc=:     specify the maximum value of J included in the calculation.
--Jmax_save=:     specify the maximum value of J of Stark curves saved in the output file.
--Jmin=:          specify the minimum value of J included in the calculation.
--Mmax=:          specify the maximum value of M included in the calculation. [TM: Default value?]
--isomer=:        specify which isomer is used, when <moleculename> have more than
                  one isomers defined in moleculeparameter.py

Example of using cmistark_calculate_energy with options:

cmistark_calculate_energy --isomer=0 --Jmax_calc=40 --Jmax_save=20 --3-aminophenol --dc-fields=0:150:151

After executing this command line, the script will use cmistark packages to calculate stark energies of isomer 0 of 3-aminophenol up to J = 40, and save results up to J = 20 in an output file called 3-aminophenol.molecule. The Stark curve of each quantum state starts from 0 to 150 kV/cm with a step of 1 kV/cm.

The output file <moleculename>.molecule stores Stark curve of individual quantum states in a data format called HDF5. Such a file format can be read directly by using PyTables packages in Python. Two scripts in this program, cmistark_plot_energy and cmistark_print_energy are provided to easily access these <moleculename>.molecule files. Their options and descriptions are provided below.

cmistark_plot_energy

The script file called cmistark_plot_energy can access existing Stark files (<moleculename>.molecule) and plot the stored curves.

It offers the following options:

--help: help
--energy-unit=: specify the unit of energy, options: MHz, invcm, J
--Jmin=, --Jmax=: specify min. or max. value of J
--Mmin=, --Mmax=: specify min. or max. value of M
--Kamax=: specify max. value of Ka
--states=: specify states to plot, format: "0000,1010"
--dipole: plot the effective dipole moments
--isomer=: specify which isomer to plot

example of using cmistark_plot_energy with options:

    cmistark_plot_energy --Jmin=0 --Jmax=2 --Mmin=1 --Mmax=1 <moleculename>.molecule

cmistark_print energy

The script file called cmistark_print_energy can access existing Stark files (<moleculename>.molecule) and print the stored curves on the screen.

It offers the following options:

--help: help
--Jmin=, --Jmax=: specify min. or max. value of J
--Kamax=: specify max. value of Ka
--Mmin=, --Mmax=: specify min. or max. value of M
--isomer=: specify which isomer to print

Example of using acmistark_print_energya with options:

    cmistark_print_energy --Jmin=0 --Jmax=2 --Mmin=1 --Mmax=1 <moleculename>.molecule

How to add a new molecule

Firstly, in the file called moleculeparameter.py (in the cmistark/ folder), add all relevant molecular constants/parameters as a function. See the examples provided in this file.

Next, in the script file cmistark_calculate_energy (in script folder), add an option for calling the above added function for the mew molecule. See the examples provided in this file.

State labels of stored Stark curves

In the output file .molecule, each Stark curve has a state label (J,Ka,Kc,M,isomer), which represents the adiabatic quantum number label of the rotational state in the field, as well as the type of isomer. J, Ka, Kc, M are integer, assuming no orbital angular momentum and spin of electrons and nuclear spins involved. For all types of rotors, the value of J is not less than zero.

For asymmetric tops and linear rotors, only states with positive M are stored, as all curves of nonzero M states are doubly degenerate. The values of both Ka and Kc are not less than zero for symmetric and asymmetric tops, one is kept at zero for symmetric tops, and both are set to zero for linear rotors. The state lable for linear rotors is thus (J,0,0,M,isomer).

For symmetric tops, states having products of K and M equal to +|KM| and -|KM| are split in the DC electric field. In the output file states corresponding to negative |KM| are stored with negative K (and positive M); this is really an implementation detail and the sign stored with K in this case is always the sign of the product KM. We note that states with K > 0 and M < 0 also yield -|KM|. Thus, all curves of nonzero M states in the output file are also double degenerate. Finally, the state label for prolate tops is (J,K,0,M,isomer), or (J,0,K,M,isomer) for oblate tops.

Structure of data storage files

The storage files <moleculename>.molecule are HDF5 files in which for every state (J,Ka,Kc,M,isomer) the Stark energy as a function of the DC field strength is stored in the following structure:

    /_J/_Ka/_Kc/_M/_isomer/dcfield
    /_J/_Ka/_Kc/_M/_isomer/dcstarkenergy

The following example source code of Python shows how to read the curve for the 00000 state from <moleculename>.molecule using PyTables:

import tables
import numpy
stark_file = "<moleculename>.molecule"
f = tables.openFile(stark_file)
array = f.getNode("/_0/_0/_0/_0/_0/dcstarkenergy")
print(numpy.array(array.read()))

A script cmistark_print_energies that provides ASCII output for specified conditions and states is provided in the package for convenience.

Descriptions of source code files

Three files in the lib folder provide all functions used to calculate and then write/read Stark curves. The above script files perform the calculations by calling these functions. The basic descriptions of each file in lib folder as follows:

molecule.py

Performs Stark effect calculation by calling functions from starkeffect.py and store results in an output file

moleculeparameter.py

Contains all molecular parameters of individual molecules

starkeffect.py

Contains all functions, equations and algorithms required for calculating Stark effect.