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 intodevelop
- the principal development branch is
- 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 onmaster
, nor any release preparations. The latter is done onrelease/
, then the release is put ontomaster
, and possibly necessary fixes are done onhotfix/
!
- the
- Do not repeatedly branch feature branches into
develop
instead mergedevelop
into yourfeature/
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!
- CMIstark uses the git-flow branching model
- 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 fromstarkeffect.py
and store results in an output filemoleculeparameter.py
: contain all molecular parameters of individual moleculesstarkeffect.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 constantsconst.py
: call required math. and phys. constants from codata.pyconvert.py
: perform unit conversionshdf5.py
: read/write output files in the format of hdf5 via PyTablesmoleculeproperty.py
: create a molecule (as an object) from a list of atomsstate.py
: create state labels and corresponding id numbersutil.py
: provide array operations