Stark effect calculations for molecules in dc electric fields
This repository is outdated, please see the latest code at https://gitlab.desy.de/CMI/CMI-public/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]
Computer: Any Macintosh, PC, or Linux/UNIX workstations with a modern Python
distribution.
The following external Python packages are also required:
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
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 thefollowing 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 thanone 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.
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
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
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.
In the output file
(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.
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 the00000 state from <moleculename>.molecule using PyTables:
import tablesimport numpystark_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.
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.