CMIstark developer guide

Here are a few simple guidelines to please be obeyed when working on CMIdiffract

  • Document your code!
    • Use spinx-compatible docstrings to document all classs, methods, functions, etc.
  • Write code that is compatible with the latest stable Python 3.x version.
  • Make use of NumPy as much as possible.

Source code formatting

  • CMIstark uses the 4-spaces standard for indentation of blocks.
  • Do not use tabs, always expand to spaces.
  • Try to not extend lines beyond 100 characters
  • Keep the utf-8 coding directive in the first line
  • Keep the Emacs local variables section at the end of all files, and try to stick to the directives (manually) when not using Emacs.

Version control (git) details

  • CMIstark uses git (Stash) as a version control system with a central repositories in the DESY-CFEL-CMI stash server.
    • CMIstark uses the git-flow branching model
      • the principal development branch is develop
      • all new developments should be done on a feature/ branch and, once ready, be branched into develop
    • never touch the branch master – this is to be done by the maintainers.
      • the master branch is only for releases, which for CMIstark are rare and surely only after discussion with me. There should never be any development done on master, nor any release preparations. The latter is done on release/, then the release is put onto master, and possibly necessary fixes are done on hotfix/!
    • Do not repeatedly branch feature branches into develop instead merge develop into your feature/ branch.
    • General documentation work should always be made on develop (only)!
      • commit such doc-only updates as separate commits!
      • one can then merge these doc-only commits into feature/ branches
    • never implement a change twice manually! Implement it on the most appropriate branch, then merge it into whatever branch you want to have it!
  • make sure the git repo stays clean and one can follow it with our turning crazy!

State labels of stored Stark curves

In the output file <moleculename>.molecule, each Stark curve has a state label (\(J\), \(K_a\), \(K_c\), \(M\), isomer), which represents the adiabatic quantum number label of the rotational state in the field, as well as the type of isomer. \(J\), \(K_a\), \(K_c\), \(M\) are integers, 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 \(K_a\) and \(K_c\) are not less than zero for asymmetric tops, or 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|\) 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 doubly degenerate. Finally, the state label for prolate tops is (\(J\), \(K\), \(0\), \(M\), isomer), and (\(J\), \(0\), \(K\), \(M\), isomer) for oblate tops.

Structure of <moleculename>.molecule

For each state (\(J\), \(K_a\), \(K_c\), \(M\),isomer), the Stark energy as function of DC field strength is stored in the following structures:

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

The state label (\(J\), \(K_a\), \(K_c\), \(M\), isomer) is manifested as a dictionary strcuture here for storing state-specific information.

The following example source code of Python shows how to read the curve for the 00000 state from <moleculename>.molecule by 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 source code files in cmistark 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 are as follows:

  • molecule.py: perform the Stark effect calculation by calling functions from starkeffect.py and store results in an output file
  • moleculeparameter.py: contain all molecular parameters of individual molecules
  • starkeffect.py: contain all functions, equations and algorithms required for calculating the Stark effect.

(Only for stand-alone version) The descriptions of the rest of the files in the lib folder are as follows:

  • codata.py: store most scientific constants
  • const.py: call required math. and phys. constants from codata.py
  • convert.py: perform unit conversions
  • hdf5.py: read/write output files in the format of hdf5 via PyTables
  • moleculeproperty.py: create a molecule (as an object) from a list of atoms
  • state.py: create state labels and corresponding id numbers
  • util.py: provide array operations