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 ``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. 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.
State labels of stored Stark curves
-----------------------------------
In the output file ``.molecule``, each Stark curve has a state
label (:math:`J`, :math:`K_a`, :math:`K_c`, :math:`M`, isomer), which represents
the adiabatic quantum number label of the rotational state in the field, as well
as the type of isomer. :math:`J`, :math:`K_a`, :math:`K_c`, :math:`M` are
integers, assuming no orbital angular momentum and spin of electrons and nuclear
spins involved. For all types of rotors, the value of :math:`J` is not less than
zero.
For asymmetric tops and linear rotors, only states with positive :math:`M` are
stored, as all curves of nonzero :math:`M` states are doubly degenerate. The
values of both :math:`K_a` and :math:`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 (:math:`J`, :math:`0`, :math:`0`, :math:`M`, isomer).
For symmetric tops, states having products of :math:`K` and :math:`M` equal to
:math:`+|KM|` and :math:`-|KM|` split in the DC electric field. In the output
file states, corresponding to negative :math:`|KM|` are stored with negative
:math:`K` (and positive :math:`M`); this is really an implementation detail and
the sign stored with :math:`K` in this case is always the sign of the product
:math:`KM`. We note that states with :math:`K>0` and :math:`M<0` also yield
:math:`-|KM|`. Thus, all curves of nonzero :math:`M` states in the output file
are also doubly degenerate. Finally, the state label for prolate tops is
(:math:`J`, :math:`K`, :math:`0`, :math:`M`, isomer), and (:math:`J`, :math:`0`,
:math:`K`, :math:`M`, isomer) for oblate tops.
Structure of .molecule
------------------------------------
For each state (:math:`J`, :math:`K_a`, :math:`K_c`, :math:`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 (:math:`J`, :math:`K_a`, :math:`K_c`, :math:`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 ``.molecule`` by using PyTables::
import tables
import numpy
stark_file = ".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
.. _github: https://github.com/CFEL-CMI/cmistark
.. comment
Local Variables:
coding: utf-8
fill-column: 100
truncate-lines: t
End: