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 as a version control system with a central repositories on github.
CMIstark uses the git-flow branching model
the principal development branch is
all new developments should be done on a
feature/branch and, once ready, be branched into
never touch the branch
master– this is to be done by the maintainers.
masterbranch is only for releases. 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
Do not repeatedly branch feature branches into
General documentation work should always be made on
commit such doc-only updates as separate commits!
one can then merge these doc-only commits into
never implement a change twice manually. Implement it on the most appropriate branch, then merge it into whatever branch you want to have it.
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
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:
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())
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
molecule.py: perform the Stark effect calculation by calling functions from
starkeffect.pyand 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