Introduction¶
This is the introduction page for the MJOLNIR software package. The main purpose of this document is to give an overview of different features of the software and how you can contribute to it.
The software is currently developed by Jakob Lass, PhD student at both the Niels Bohr Institute, Copenhagen - Denmark, and the Paul Scherrer Institute, Villigen - Switzerland, and is not developed by a professional team. The software is intended to be used for data treatment and visualization for the CAMEA upgrade at the RITA II instrument at SINQ, PSI Villigen - Switzerland.
The software is found at GitHub and is intended to be used together with Python versions (3.4,) 3.5, 3.6, 3.7 and (3.8). This compatibility is ensured by the use of automated unit test through the Travis project (Travis). Python 3.4 is no longer tested due to updates in the Travis testing framework. Further than just testing, as to ensure a thorough testing the coverage of these are monitored using Coveralls (Coveralls). However, certain algorithms and methods are not suited to be tested through simple tests. This includes graphical methods where one for example uses a plotting routine to generate a specific output. Though the visual inspection is far outside of the testing scope for this software, some of the methods are still tested by simple run through test. That is, if they can be run and generate a plot without crashing and throwing an error, it is believed that they work as intended. This is where actual user testing is needed.
IPython¶
The MJOLNIR software package makes use of many features of the interactive part of matplotlib. Thus, if the code/tutorials are run through an IPython kernel, these might be absent. However, including the following code snippet to the top of the scripts changes the IPython matplotlib back-end to be interactive:
try:
import IPython
shell = IPython.get_ipython()
shell.enable_matplotlib(gui='qt')
except:
pass
This block can in principal also be included for regular python kernels as it will then through an exception and pass. If the ‘qt’ back-end is not available, one could try a number of others; For a list run “matplotlib.rcsetup.interactive_bk” after import of matplotlib.
Software Structure¶
The software is divided into individual modules being Instrument, DataSet, and Statistics. With this division it is intended that each part of the software suit is to be fully independent of the others but may be used together. The same goes for the tutorials that are intended to cover all of the methods and workflow a user would come into contact with while using the software.
Installation¶
The MJOLNIR software package is available for download an installation through the python package installer PyPI. This then allows for an installation by simply writing in a terminal
pip install MJOLNIR
Depending on the set-up on the computer, one recomendation is to install MJOLNIR in a virtual environment through the use of e.g. conda or Anaconda with different packages. Currently, MJOLNIR is not installable through conda thus one needs to first set up the virtual environment and afterwards install the package through PyPI
conda create --name MJOLNIR python=3.6
conda activate MJOLNIR
pip install MJOLNIR
In the case that a Jupyter Notebook is wanted, add
pip install jupyter
The specific version of python is not a requirement but merely a suggestion. The same is valid for Spyder which is a recommendable IDE for python and more. The specific version is the last that supports running scripts in interactive python environments.
For a nightly-build version of MJOLNIR, that are currently being developed on the Develop branch one needs only to change an argument to PyPI
pip install -i https://test.pypi.org/simple/ MJOLNIR
Gui through pip¶
The graphical interface can be installed through pip, but with some caveats. Depending on the python version different distributions of PyQt5 and PyQt5-Sip are needed. If these are to be installed manually the flag ‘–user’ is to be used when running windows.
conda create --name MJOLNIR python=3.6
conda activate MJOLNIR
pip install MJOLNIR
pip install MJOLNIRGui
License¶
The software package is released under the software license Mozilla Public License Version 2.0 
to allow for redistribution and usage of the code. If this license file has not been shipped with your distribution of the code, please find it here: licence.
Bug Report¶
If an un error or unexpected behaviour of the software is observed, or if a feature is needed, you are more than welcome to create an issue or feature request at the GitHub page (Issues). Dealing and fixing the reported bugs will be most easily done if both operation system, software version, a minimal working example, and other relevant informations are provided. Further as time goes by, it is hoped that this page will also contain explanations and answers to the most frequently asked question of the software.
Currently there are the following open 
and closed 
issues.
Contribution¶
After the initial upstart phase you are more than welcome to contribute to the software. This is best done by:
First create an issue on the GitHub page describing the scope of the contribution
Title: Contribution: Title of contribution.
Short description of features.
List of package dependencies.
After discussion of feature scope you are welcome to start the programming
Suggested changes are submitted through a pull request
Each contribution needs to include:
source code in a suitable sub-folder (see Software structure)
Documentation of code located in the docs-folder having identical structure to the modules added
Suitable tests for the new functionality added to the .travis.yml-file
Needed packages added to the requirements.txt file
Contribution Example:¶
Title: Extension of fitting routine
Description: An extension of the fitting module is needed to allow users to incorporate Bayesian update of parameters fitted in 3D with given priors. This is to be done by adding a subroutine to the fit object.
Initial thoughts: It is believed that building upon the XXX package where this feature was already created.