diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3fa36ed0d34ebbffada0a5657b2d3f4516ae7b05
--- /dev/null
+++ b/README.md
@@ -0,0 +1,38 @@
+CfelPyUtils
+===========
+
+Utility functions and classes for CFEL software projects
+
+Copyright © 2018 Deutsches Elektronen-Synchrotron DESY,
+ a research centre of the Helmholtz Association.
+
+<http://www.cfel.de>
+
+CfelPyUtils is a library of several utility functions and classes used
+by several software projects developed at the Center For Free Electron
+Laser Science (CFEL) in Hamburg.
+
+Requirements
+------------
+
+ * NumPy
+
+Support
+-------
+
+ * Report issues on the [GitHub issue tracker](https://github.com/ondateam/cfelpyutils/issues)
+
+
+Installation Methods
+--------------------
+
+ * From pypi:
+ `pip install cfelpyutils`
+ * From source:
+ `python setup.py install`
+ * Simply copy the cfelpyutils subdirectory in your project.
+
+Documentation
+-------------
+
+The API documentation can be found on [Read The Docs](https://cfelpyutils.readthedocs.io/en/latest)
diff --git a/cfelpyutils/__init__.py b/cfelpyutils/__init__.py
index a6eda16daada1429d9f822def59bf522607e2b76..a3f69b94e2c87cb812fb42adc2d2c995e61cadc6 100644
--- a/cfelpyutils/__init__.py
+++ b/cfelpyutils/__init__.py
@@ -13,20 +13,21 @@
# You should have received a copy of the GNU General Public License
# along with cfelpyutils. If not, see <http://www.gnu.org/licenses/>.
"""
-Utilities for CFEL software projects.
+Utility functions and classes for CFEL software projects.
-This package contains the implementation of several utiliy functions
-and classes used by many projects developed at the Center For Free
-Electron Laser Science (CFEL) in Hamburg.
+This package contains the implementation of several utility functions
+and classes used by many software projects developed at the Center For
+Free Electron Laser Science (CFEL) in Hamburg.
(`Link CFEL: https://www.cfel.de`)
-The 'crystfel_utils' submodule contains python implementations of
+The 'crystfel_utils' submodule contains the python implementation of
some functions from the CrystFEL software package.
(`Link CrystFEL http://www.desy.de/~twhite/crystfel/`)
The 'geometry_utils' submodule contains the implementation of functions
used to manipulate detector geometry information.
-The 'parameter utils' submodule contains the implementation of
-functions used to manipulate detector geometry information.
+The 'parameter_utils' module contains the implementation of functions
+that are used to parse and manipulate options and parameters.
"""
+__version__ = "0.91"
diff --git a/cfelpyutils/crystfel_utils.py b/cfelpyutils/crystfel_utils.py
index 63566103b3082637e756d089abe04b358453c5a2..cf2b475d2bd2b03800f4f6c35d386014da313d1f 100644
--- a/cfelpyutils/crystfel_utils.py
+++ b/cfelpyutils/crystfel_utils.py
@@ -15,8 +15,9 @@
"""
CryystFEL utilities.
-This module contains the implementation of several functions used to
-interact with CrystFEL files and data (geometry files, stream files).
+This module contains the python implementation of some functions from
+the
+`CrystFEL software package <http://www.desy.de/~twhite/crystfel/>`_.
"""
from __future__ import (absolute_import, division, print_function,
unicode_literals)
@@ -26,6 +27,8 @@ import copy
import math
import re
+from future.utils import viewitems
+
def _assplode_algebraic(value):
# Reimplementation of assplode_algegraic from
@@ -90,7 +93,17 @@ def _set_dim_structure_entry(key, value, panel):
else:
dim = []
- dim_index = int(key[3])
+ try:
+ dim_index = int(key[3])
+ except IndexError:
+ raise RuntimeError(
+ "'dim' must be followed by a number, e.g. 'dim0')"
+ )
+ except ValueError:
+ raise RuntimeError(
+ "Invalid dimension number {}".format(key[3])
+ )
+
if dim_index > len(dim) - 1:
for _ in range(len(dim), dim_index + 1):
dim.append(None)
@@ -101,6 +114,7 @@ def _set_dim_structure_entry(key, value, panel):
dim[dim_index] = int(value)
else:
raise RuntimeError("Invalid dim entry: {}.".format(value))
+ panel['dim_structure'] = dim
def _parse_field_for_panel(key, value, panel):
@@ -218,7 +232,7 @@ def _parse_field_for_panel(key, value, panel):
panel=panel
)
else:
- raise RuntimeError("Unrecognised field: {}".format(key))
+ RuntimeError("Unrecognised field: {}".format(key))
def _parse_toplevel(key, value, detector, beam, panel):
@@ -228,13 +242,13 @@ def _parse_toplevel(key, value, detector, beam, panel):
try:
detector['mask_bad'] = int(value)
except ValueError:
- detector['mask_bad'] = int(x=value, base=16)
+ detector['mask_bad'] = int(value, base=16)
elif key == 'mask_good':
try:
detector['mask_good'] = int(value)
except ValueError:
- detector['mask_good'] = int(x=value, base=16)
+ detector['mask_good'] = int(value, base=16)
elif key == 'coffset':
panel['coffset'] = float(value)
@@ -396,13 +410,11 @@ def load_crystfel_geometry(filename):
CrystFEL in python. Return a dictionary with the geometry
information read from the file. Convert entries in the geometry
file to keys in the returned dictionary. For a full documentation
- on the CrystFEL geometry format, see:
-
- http://www.desy.de/~twhite/crystfel/manual-crystfel_geometry.html
-
- The code of this function is synced with the code of the function
- 'get_detector_geometry_2' in CrystFEL at commit
- 41a8fa9819010fe8ddeb66676fee717f5226c7b8.
+ of the CrystFEL geometry format, see `CrystFEL's geometry man page
+ <http://www.desy.de/~twhite/crystfel/manual-crystfel_geometry.
+ html>`_. The code of this function is synced with the code of the
+ function 'get_detector_geometry_2' in CrystFEL at commit
+ 41a8fa9819010.
Args:
@@ -448,14 +460,13 @@ def load_crystfel_geometry(filename):
'clen_for_centering': None,
'adu_per_eV': None,
'adu_per_photon': None,
- 'max_adu': float(x='inf'),
+ 'max_adu': float('inf'),
'mask': None,
'mask_file': None,
'satmap': None,
'satmap_file': None,
'data': None,
'dim_structure': None,
- 'name': ''
}
default_bad_region = {
@@ -468,7 +479,6 @@ def load_crystfel_geometry(filename):
'min_ss': 0,
'max_ss': 0,
'is_fsss': 99,
- 'name': ''
}
default_dim = [
@@ -543,7 +553,7 @@ def load_crystfel_geometry(filename):
num_placeholders_in_panels = None
for panel in detector['panels'].values():
if panel['dim_structure'] is not None:
- curr_num_placeholders = panel['dim_structure'].values().count('%')
+ curr_num_placeholders = panel['dim_structure'].count('%')
else:
curr_num_placeholders = 0
@@ -579,42 +589,53 @@ def load_crystfel_geometry(filename):
)
dim_length = None
- for panel in detector['panels'].values():
+ for panel_name, panel in viewitems(detector['panels']):
if panel['dim_structure'] is None:
panel['dim_structure'] = copy.deepcopy(default_dim)
- found_ss = False
- found_fs = False
- found_placeholder = False
- for entry in panel['dim_structure']:
+ found_ss = 0
+ found_fs = 0
+ found_placeholder = 0
+ for dim_index, entry in enumerate(panel['dim_structure']):
if entry is None:
raise RuntimeError(
- "Not all dim entries are defined for all panels."
+ "Dimension {} for panel {} is undefined.".format(
+ dim_index,
+ panel_name
+ )
)
-
elif entry == 'ss':
- if found_ss is True:
- raise RuntimeError(
- "Only one slow scan dim coordinate is allowed."
- )
- else:
- found_ss = True
-
+ found_ss += 1
elif entry == 'fs':
- if found_fs is True:
- raise RuntimeError(
- "Only one fast scan dim coordinate is allowed."
- )
- else:
- found_fs = True
-
+ found_fs += 1
elif entry == '%':
- if found_placeholder is True:
- raise RuntimeError(
- "Only one placeholder dim coordinate is allowed."
- )
- else:
- found_placeholder = True
+ found_placeholder += 1
+
+ if found_ss != 1:
+ raise RuntimeError(
+ "Exactly one slow scan dim coordinate is needed "
+ "(found {} for panel {})".format(
+ found_ss,
+ panel_name
+ )
+ )
+ if found_fs != 1:
+ raise RuntimeError(
+ "Exactly one fast scan dim coordinate is needed "
+ "(found {} for panel {})".format(
+ found_fs,
+ panel_name
+ )
+ )
+ if found_placeholder > 1:
+ raise RuntimeError(
+ "Only one placeholder dim coordinate is allowed."
+ "Maximum one placeholder dim coordinate is "
+ "allowed (found {} for panel {})".format(
+ found_placeholder,
+ panel_name
+ )
+ )
if dim_length is None:
dim_length = len(panel['dim_structure'])
@@ -628,59 +649,59 @@ def load_crystfel_geometry(filename):
"Number of dim coordinates must be at least two."
)
- for panel in detector['panels'].values():
+ for panel_name, panel in viewitems(detector['panels']):
if panel['origin_min_fs'] < 0:
raise RuntimeError(
"Please specify the minimum fs coordinate for "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['origin_max_fs'] < 0:
raise RuntimeError(
"Please specify the maximum fs coordinate for "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['origin_min_ss'] < 0:
raise RuntimeError(
"Please specify the minimum ss coordinate for "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['origin_max_ss'] < 0:
raise RuntimeError(
"Please specify the maximum ss coordinate for "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['cnx'] is None:
raise RuntimeError(
"Please specify the corner X coordinate for "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['clen'] is None and panel['clen_from'] is None:
raise RuntimeError(
"Please specify the camera length for "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['res'] < 0:
raise RuntimeError(
"Please specify the resolution or "
- "panel {}.".format(panel['name'])
+ "panel {}.".format(panel_name)
)
if panel['adu_per_eV'] is None and panel['adu_per_photon'] is None:
raise RuntimeError(
"Please specify either adu_per_eV or adu_per_photon "
- "for panel {}.".format(panel['name'])
+ "for panel {}.".format(panel_name)
)
if panel['clen_for_centering'] is None and panel['rail_x'] is not None:
raise RuntimeError(
"You must specify clen_for_centering if you specify the "
- "rail direction (panel {})".format(panel['name'])
+ "rail direction (panel {})".format(panel_name)
)
if panel['rail_x'] is None:
@@ -694,11 +715,11 @@ def load_crystfel_geometry(filename):
panel['w'] = panel['origin_max_fs'] - panel['origin_min_fs'] + 1
panel['h'] = panel['origin_max_ss'] - panel['origin_min_ss'] + 1
- for bad_region in detector['bad'].values():
+ for bad_region_name, bad_region in viewitems(detector['bad']):
if bad_region['is_fsss'] == 99:
raise RuntimeError(
"Please specify the coordinate ranges for bad "
- "region {}.".format(bad_region['name'])
+ "region {}.".format(bad_region_name)
)
for group in detector['rigid_groups']:
@@ -731,6 +752,6 @@ def load_crystfel_geometry(filename):
# The code of this function is synced with the code of the function
# 'get_detector_geometry_2' in CrystFEL at commit
- # 41a8fa9819010fe8ddeb66676fee717f5226c7b8
+ # dabbe320ff1d54d8ad24954b1e391f1b58ec0866
return detector
diff --git a/cfelpyutils/geometry_utils.py b/cfelpyutils/geometry_utils.py
index c280f73154e9438c071e33ba66683b0044c7c319..7aafc2fa18960d65a2cbc5beaf001e3df0a97e81 100644
--- a/cfelpyutils/geometry_utils.py
+++ b/cfelpyutils/geometry_utils.py
@@ -16,7 +16,8 @@
Geometry utilities.
This module contains the implementation of several functions used to
-manipulate geometry information."""
+manipulate geometry information.
+"""
from __future__ import (absolute_import, division, print_function,
unicode_literals)
@@ -27,16 +28,18 @@ import numpy
PixelMaps = collections.namedtuple( # pylint: disable=C0103
typename='PixelMaps',
- field_names=['x', 'y', 'r']
+ field_names=['x', 'y', 'z', 'r', 'phi']
)
"""
-Pixel maps storing data geometry.
-
-A namedtuple that stores the pixel maps describing the geometry of a
-dataset. The first two fields, named "x" and "y" respectively, store
-the pixel maps for the x coordinate and the y coordinate. The third
-field, named "r", is instead a pixel map storing the distance of each
-pixel in the data array from the center of the reference system.
+Pixel maps storing geometry information.
+
+The first three fields, named "x" "y" and "z" respectively, store the
+pixel maps for the x,the y and the z coordinates. The fourth field,
+named "r", is a pixel map storing the distance of each pixel in the
+data array from the center of the reference system. The fifth field,
+'phi', is instead a pixel map that stores the angles that vectors
+connecting each pixel with the center of the reference system make with
+respect to the x axis of the reference system.
"""
@@ -46,21 +49,21 @@ def compute_pix_maps(geometry):
Take as input a CrystFEL-style geometry object (A dictionary
returned by the function load_crystfel_geometry function in the
- crystfel_utils module) and return a PixelMap tuple . The origin the
- reference system used by the pixel maps is set at the beam
- interaction point.
+ crystfel_utils module) and return a :obj:`PixelMaps` tuple . The
+ origin the reference system used by the pixel maps is set at the
+ beam interaction point.
Args:
- geometry (dict): A CrystFEL geometry object (A dictionary
+ geometry (Dict): A CrystFEL geometry object (A dictionary
returned by the
:obj:`cfelpyutils.crystfel_utils.load_crystfel_geometry`
function).
Returns:
- PixelMaps: A PixelMaps tuple storing the pixel maps (ndarrays
- of type float).
+ PixelMaps: A :obj:`PixelMaps` tuple storing the pixel maps
+ (numpy.ndarrays of float).
"""
max_fs_in_slab = numpy.array([
geometry['panels'][k]['max_fs']
@@ -82,10 +85,21 @@ def compute_pix_maps(geometry):
dtype=numpy.float32 # pylint: disable=E1101
)
+ z_map = numpy.zeros(
+ shape=(max_ss_in_slab + 1, max_fs_in_slab + 1),
+ dtype=numpy.float32 # pylint: disable=E1101
+ )
+
# Iterate over the panels. For each panel, determine the pixel
# indices, then compute the x,y vectors. Finally, copy the
# panel pixel maps into the detector-wide pixel maps.
for pan in geometry['panels']:
+
+ if 'clen' in geometry['panels'][pan]:
+ pan_clen = geometry['panels'][pan]['clen']
+ else:
+ pan_clen = 0.0
+
ss_grid, fs_grid = numpy.meshgrid(
numpy.arange(
geometry['panels'][pan]['max_ss'] -
@@ -126,14 +140,22 @@ def compute_pix_maps(geometry):
geometry['panels'][pan]['max_fs'] + 1
] = y_panel
+ z_map[
+ geometry['panels'][pan]['min_ss']:
+ geometry['panels'][pan]['max_ss'] + 1,
+ geometry['panels'][pan]['min_fs']:
+ geometry['panels'][pan]['max_fs'] + 1
+ ] = pan_clen
+
r_map = numpy.sqrt(numpy.square(x_map) + numpy.square(y_map))
+ phi_map = numpy.arctan2(y_map, x_map)
- return PixelMaps(x_map, y_map, r_map)
+ return PixelMaps(x_map, y_map, z_map, r_map, phi_map)
def compute_min_array_size(pixel_maps):
"""
- Compute the minimum array size storing data with applied geometry.
+ Compute the minimum size of an array stroing the applied geometry.
Return the minimum size of an array that can store data on which
the geometry information described by the pixel maps has been
@@ -146,7 +168,7 @@ def compute_min_array_size(pixel_maps):
Args:
- pixel_maps [PixelMaps]: a PixelMaps tuple.
+ pixel_maps (PixelMaps): a :obj:`PixelMaps` tuple.
Returns:
@@ -173,7 +195,7 @@ def compute_visualization_pix_maps(geometry):
Args:
- geometry (dict): A CrystFEL geometry object (A dictionary
+ geometry (Dict): A CrystFEL geometry object (A dictionary
returned by the
:obj:`cfelpyutils.crystfel_utils.load_crystfel_geometry`
function).
@@ -181,10 +203,10 @@ def compute_visualization_pix_maps(geometry):
Returns:
PixelMaps: A PixelMaps tuple containing the adjusted pixel
- maps. The first two fields, named "x" and "y" respectively,
- store the pixel maps for the x coordinate and the y
- coordinates (as ndarrays of type int). The third field
- ("r") is just set to None.
+ maps. The first two fields, named "x" and "y" respectively,
+ store the pixel maps for the x coordinate and the y
+ coordinates (as ndarrays of type int). The third field
+ ("r") is just set to None.
"""
# Shift the origin of the reference system from the beam position
# to the top-left of the image that will be displayed. Compute the
diff --git a/cfelpyutils/parameter_utils.py b/cfelpyutils/parameter_utils.py
deleted file mode 100644
index dd5a0392320be2fb50f69e2e4b788e19bcb5347c..0000000000000000000000000000000000000000
--- a/cfelpyutils/parameter_utils.py
+++ /dev/null
@@ -1,154 +0,0 @@
-# This file is part of cfelpyutils.
-#
-# cfelpyutils is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# cfelpyutils is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with cfelpyutils. If not, see <http://www.gnu.org/licenses/>.
-"""
-Parameter parsing utilities.
-
-This module contains the implementation of several utilities used
-to parse and manipulate dictionaries that store options and parameters.
-"""
-from __future__ import (absolute_import, division, print_function,
- unicode_literals)
-
-import ast
-
-
-def _parsing_error(section, option):
- # Raise an exception after a parsing error.
- raise RuntimeError(
- "Error parsing parameter {0} in section [{1}]. Make sure that the "
- "syntax is correct: list elements must be separated by commas and "
- "dict entries must contain the colon symbol. Strings must be quoted, "
- "even in lists and dicts.".format(option, section)
- )
-
-
-def convert_parameters(config_dict):
- """
- Convert strings in parameter dictionaries to the correct data type.
-
- Convert a dictionary return by the configparse module to a
- dictionar contaning the same parameters converted from string to
- their correct type (int, float, string, etc.)
-
- Try to convert each entry in the dictionary according to the
- following rules. The first rule that applies to the entry
- determines the type.
-
- - If the entry starts and ends with a single quote or double quote,
- leave it as a string.
- - If the entry starts and ends with a square bracket, convert it to
- a list.
- - If the entry starts and ends with a curly braces, convert it to a
- dictionary or a set.
- - If the entry is the word None, without quotes, convert it to
- NoneType.
- - If the entry is the word False, without quotes, convert it to a
- boolean False.
- - If the entry is the word True, without quotes, convert it to a
- boolean True.
- - If none of the previous options match the content of the entry,
- try to interpret the entry in order as:
-
- - An integer number.
- - A float number.
- - A string.
-
- - If all else fails, raise an exception.
-
- Args:
-
- config (Dict): a dictionary containing strings (the dictionary
- returned by Config Parser).
-
- Returns:
-
- Dict: dictionary with the same structure as the input
- dictionary, but with correct types assigned to each entry.
-
- Raises:
-
- RuntimeError: if an entry cannot be converted to any supported
- type.
- """
-
- monitor_params = {}
-
- for section in config_dict.keys():
- monitor_params[section] = {}
- for option in config_dict[section].keys():
- recovered_option = config_dict[section][option]
- if (
- recovered_option.startswith("'") and
- recovered_option.endswith("'")
- ):
- monitor_params[section][option] = recovered_option[1:-1]
- continue
-
- if (
- recovered_option.startswith('"') and
- recovered_option.endswith('"')
- ):
- monitor_params[section][option] = recovered_option[1:-1]
- continue
-
- if (
- recovered_option.startswith("[") and
- recovered_option.endswith("]")
- ):
- try:
- monitor_params[section][option] = ast.literal_eval(
- recovered_option
- )
- continue
- except (SyntaxError, ValueError):
- _parsing_error(section, option)
-
- if (
- recovered_option.startswith("{") and
- recovered_option.endswith("}")
- ):
- try:
- monitor_params[section][option] = ast.literal_eval(
- recovered_option
- )
- continue
- except (SyntaxError, ValueError):
- _parsing_error(section, option)
-
- if recovered_option == 'None':
- monitor_params[section][option] = None
- continue
-
- if recovered_option == 'False':
- monitor_params[section][option] = False
- continue
-
- if recovered_option == 'True':
- monitor_params[section][option] = True
- continue
-
- try:
- monitor_params[section][option] = int(recovered_option)
- continue
- except ValueError:
- try:
- monitor_params[section][option] = float(
- recovered_option
- )
- continue
- except ValueError:
- _parsing_error(section, option)
-
- return monitor_params
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..fd5b18cc3f5d8bd2191bdf9358bd317642b03607
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+SPHINXPROJ = cfelpyutils
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
diff --git a/docs/cfelpyutils.crystfel_utils.rst b/docs/cfelpyutils.crystfel_utils.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7ffd29020430eea1ce615cea85ae092a46ecdb2a
--- /dev/null
+++ b/docs/cfelpyutils.crystfel_utils.rst
@@ -0,0 +1,7 @@
+cfelpyutils.crystfel\_utils module
+==================================
+
+.. automodule:: cfelpyutils.crystfel_utils
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/cfelpyutils.geometry_utils.rst b/docs/cfelpyutils.geometry_utils.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d75c71fe316f6b05bc18e2dacd03d6eefb1482dc
--- /dev/null
+++ b/docs/cfelpyutils.geometry_utils.rst
@@ -0,0 +1,7 @@
+cfelpyutils.geometry\_utils module
+==================================
+
+.. automodule:: cfelpyutils.geometry_utils
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/cfelpyutils.parameter_utils.rst b/docs/cfelpyutils.parameter_utils.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2eaa69209fe28514e4aad441968d0865417c3057
--- /dev/null
+++ b/docs/cfelpyutils.parameter_utils.rst
@@ -0,0 +1,7 @@
+cfelpyutils.parameter\_utils module
+===================================
+
+.. automodule:: cfelpyutils.parameter_utils
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/cfelpyutils.rst b/docs/cfelpyutils.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7637981210461912a1a82ac15500ff6b77fb19cc
--- /dev/null
+++ b/docs/cfelpyutils.rst
@@ -0,0 +1,17 @@
+cfelpyutils package
+===================
+
+.. automodule:: cfelpyutils
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+ cfelpyutils.crystfel_utils
+ cfelpyutils.geometry_utils
+ cfelpyutils.parameter_utils
+
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000000000000000000000000000000000000..7211d4272957cb99ef8b22875cd714920df76e5c
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,84 @@
+# pylint: disable=C0111
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('..'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+project = "cfelpyutils" # pylint: disable=C0103
+copyright = ( # pylint: disable=C0103, W0622
+ """
+ Copyright © 2018 Deutsches Elektronen-Synchrotron DESY,'
+ 'a research centre of the Helmholtz Association.'
+ """
+)
+author = "OnDA Team" # pylint: disable=C0103
+
+# The short X.Y version
+version = "0.9" # pylint: disable=C0103
+# The full version, including alpha/beta/rc tags
+release = "0.9" # pylint: disable=C0103
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [ # pylint: disable=C0103
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.viewcode',
+ 'sphinx.ext.todo',
+ 'sphinx.ext.napoleon',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates'] # pylint: disable=C0103
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = ".rst" # pylint: disable=C0103
+
+# The master toctree document.
+master_doc = "index" # pylint: disable=C0103
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en" # pylint: disable=C0103
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = [ # pylint: disable=C0103
+ '_build',
+ 'Thumbs.db',
+ '.DS_Store'
+]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx' # pylint: disable=C0103
+
+# -- Extension configuration -------------------------------------------------
+add_module_names = False # pylint: disable=C0103
+autodoc_member_order = 'bysource' # pylint: disable=C0103
+autoclass_content = 'init' # pylint: disable=C0103
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b4d8093dddb635d48dc5223eb0c1e9bbe8d19c3c
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,26 @@
+.. cfelpyutils documentation master file, created by
+ sphinx-quickstart on Tue Jul 10 12:10:05 2018.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to cfelpyutils's documentation!
+=======================================
+
+CfelPyUtils is a library of several utility functions and
+classes used by several software projects developed at the
+Center For Free Electron Laser Science (CFEL) in Hamburg.
+
+
+.. toctree::
+ :maxdepth: 4
+ :caption: Contents:
+
+ cfelpyutils
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000000000000000000000000000000000000..151ca6b129bd5c85c5f098bbcc60921091ebe630
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=cfelpyutils
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..24ce15ab7ead32f98c7ac3edcd34bb2010ff4326
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1 @@
+numpy
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000000000000000000000000000000000000..e85aa30b14a25132884e3f025d6ba8bf50b56513
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,65 @@
+# pylint: disable=C0111
+#
+# This file is part of cfelpyutils.
+#
+# cfelpyutils is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# cfelpyutils is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cfelpyutils. If not, see <http://www.gnu.org/licenses/>.
+from __future__ import (absolute_import, division, print_function,
+ unicode_literals)
+
+from setuptools import setup
+
+import cfelpyutils
+
+
+setup(
+ name='cfelpyutils',
+ version=cfelpyutils.__version__,
+ url="https://github.com/ondateam/cfelpyutils",
+ license="GNU General Public License v3.0",
+ author="OnDA Team",
+ author_email="valerio.mariani@desy.de",
+ description="Utility functions and classes for CFEL software "
+ "projects",
+ long_description=(
+ """
+ CfelPyUtils is a library of several utility functions and
+ classes used by several software projects developed at the
+ Center For Free Electron Laser Science (CFEL) in Hamburg.
+ """
+ ),
+ install_requires=['numpy'],
+ packages=['cfelpyutils'],
+ include_package_data=True,
+ platforms='any',
+ classifiers=[
+ "Programming Language :: Python",
+
+ "Development Status :: 4 - Beta",
+
+ "Programming Language :: Python :: 3",
+
+ "Programming Language :: Python :: 2",
+
+ "Operating System :: OS Independent",
+
+ "Topic :: Software Development :: Libraries :: Python Modules",
+
+ "License :: OSI Approved :: GNU General Public License v3 "
+ "or later (GPLv3+)",
+
+ "Natural Language :: English",
+
+ "Intended Audience :: Science/Research",
+ ],
+)