diff --git a/CalibPPS/AlignmentGlobal/BuildFile.xml b/CalibPPS/AlignmentGlobal/BuildFile.xml
new file mode 100644
index 0000000000000..4148559a502f3
--- /dev/null
+++ b/CalibPPS/AlignmentGlobal/BuildFile.xml
@@ -0,0 +1,5 @@
+
+
+
+
+
diff --git a/CalibPPS/AlignmentGlobal/README.md b/CalibPPS/AlignmentGlobal/README.md
index 2ed157af113b5..30e7c0e67717e 100644
--- a/CalibPPS/AlignmentGlobal/README.md
+++ b/CalibPPS/AlignmentGlobal/README.md
@@ -1,133 +1,22 @@
-# PPSAlignmentWorker
-## Parameters:
-| Name | Type | Description |
-|-------------|----------------|--------------------------------------------------------------------------|
-| `tagTracks` | `cms.InputTag` | Should be set to `"ctppsLocalTrackLiteProducer"`. |
-| `folder` | `cms.string` | Should be the same as the `folder` parameter in DQM configuration. |
-| `label` | `cms.string` | Label for EventSetup |
-| `debug` | `cms.bool` | When set to `True`, the worker will produce some extra debug histograms. |
+# PPS Global Alignment
-# PPSAlignmentHarvester
-## Parameters:
-| Name | Type | Description |
-|-------------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `folder` | `cms.string` | Should be the same as the `folder` parameter in DQM configuration. |
-| `sequence` | `cms.vstring` | Determines order of the alignment methods: `"x_alignemnt"`, `"x_alignment_relative"`, `"y_alignment"`. |
-| `overwrite_sh_x` | `cms.bool` | If set to `True`, `x alignment` will overwrite horizontal shift passed in the configuration. |
-| `test_results_path` | `cms.string` | Path of a file with the results. If empty (`""`), the file will not be created. |
-| `write_sqlite_results` | `cms.bool` | When set to `True`, the harvester will try to use PoolDBOutputService to save the final results. |
-| `x_ali_rel_final_slope_fixed` | `cms.bool` | `True`: the harvester will use the x relative alignment results with fixed slope to prepare final merged results. `False`: results without fixed slope. |
-| `y_ali_final_slope_fixed` | `cms.bool` | `True`: the harvester will use the y alignment results with fixed slope to prepare final merged results. `False`: results without fixed slope. |
-| `debug` | `cms.bool` | When set to `True`, the harvester will produce an extra ROOT file with debug plots. |
+## Description
-# Event Setup
-Default values come from the `fillDescriptions` method in `CalibPPS/ESProducers/plugins/PPSAlignmentConfigESSource.cc`.
-NB: Parameters here are written in snake_case. Many of them are in camelCase in the code (as PPSAlignmentConfig getters).
-| Name | Type | Default | Description |
-|------------------------|---------------|----------------------------------------|------------------------------------------------------------------------------------------------------------|
-| `debug` | `cms.bool` | `False` | When set to `True`, the ESProducer will produce an extra ROOT file with debug plots (from reference run). |
-| `label` | `cms.string` | `""` | label to distinguish reference and test fill configs. Should be set either to `""` (test) or `"reference"` |
-| `sector_45` | `cms.PSet` | [details below](#Sector-config) | Configuration of sector 45. [Details below](#Sector-config) |
-| `sector_56` | `cms.PSet` | [details below](#Sector-config) | Configuration of sector 56. [Details below](#Sector-config) |
-| `x_ali_sh_step` | `cms.double` | `0.01` | Step for x alignment algorithm [mm] |
-| `y_mode_sys_unc` | `cms.double` | `0.03` | Squared is an element of y mode uncertainty in y alignment. |
-| `chiSqThreshold` | `cms.double` | `50.` | Chi-square threshold of y mode |
-| `y_mode_unc_max_valid` | `cms.double` | `5.` | Maximum valid y mode uncertainty |
-| `y_mode_max_valid` | `cms.double` | `20.` | Maximum valid y mode |
-| `min_RP_tracks_size` | `cms.uint32` | `1` | Minimum number of tracks in each RP |
-| `max_RP_tracks_size` | `cms.uint32` | `1` | Maximum number of tracks in each RP |
-| `n_si` | `cms.double` | `4.` | Element of checking whether the cuts passed |
-| `matching` | `cms.PSet` | [details below](#matching) | Reference dataset parameters. [Details below](#matching) |
-| `x_alignment_meth_o` | `cms.PSet` | [details below](#x_alignment_meth_o) | X alignment parameters. [Details below](#x_alignment_meth_o) |
-| `x_alignment_relative` | `cms.PSet` | [details below](#x_alignment_relative) | Relative x alignment parameters. [Details below](#x_aligmment_relative) |
-| `y_alignment` | `cms.PSet` | [details below](#y_alignment) | Y alignment parameters. [Details below](#y_alignment) |
-| `binning` | `cms.PSet` | [details below](#binning) | Binning parameters for worker. [Details below](#binning) |
-| `extraParams` | `cms.vdouble` | empty vector | Extra vector of doubles added in case new parameters need to be added in the future |
+This package is responsible for PPS global alignment, that is alignment of high-luminosity physics runs based on the data from a low-luminosity reference run.
-## Sector config
-| Name | Type | Default (s_45) | Default (s_56) | Description |
-|---------------|--------------|-----------------------------|-----------------------------|----------------------------------------------------|
-| `rp_N` | `cms.PSet` | [details below](#RP-config) | [details below](#RP-config) | Near RP configuration. [Details below](#RP-config) |
-| `rp_F` | `cms.PSet` | [details below](#RP-config) | [details below](#RP-config) | Far RP configuration. [Details below](#RP-config) |
-| `slope` | `cms.double` | `0.006` | `-0.015` | Base slope value |
-| `cut_h_apply` | `cms.bool` | `True` | `True` | If set to `True`, cut_h is applied |
-| `cut_h_a` | `cms.double` | `-1.` | `-1.` | cut_h parameter |
-| `cut_h_c` | `cms.double` | `-38.55` | `-39.26` | cut_h parameter |
-| `cut_h_si` | `cms.double` | `0.2` | `0.2` | cut_h parameter |
-| `cut_v_apply` | `cms.bool` | `True` | `True` | If set to `True`, cut_v is applied |
-| `cut_v_a` | `cms.double` | `-1.07` | `-1.07` | cut_v parameter |
-| `cut_v_c` | `cms.double` | `1.63` | `1.49` | cut_v parameter |
-| `cut_v_si` | `cms.double` | `0.15` | `0.15` | cut_v parameter |
+The structure of this software is based on the DQM framework:
+1. `PPSAlignmentWorker` - takes tracks of particles produced by `ctppsLocalTrackLiteProducer` as input. It processes them by applying some cuts in order to reduce noise, and uses these data to fill the histograms that will be later used in the next module. Note that filling the histograms can be done in parallel.
+2. `PPSAlignmentHarvester` - it analyses the plots filled by the worker, runs the alignment algorithms, and outputs horizontal and vertical corrections.
-### RP config
-| Name | Type | Default (s_45, rp_N) | Default (s_45, rp_F) | Default (s_56, rp_N) | Default (s_56, rp_F) | Description |
-|------------------|--------------|----------------------|----------------------|----------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------|
-| `name` | `cms.string` | `"L_1_F"` | `"L_2_F"` | `"R_1_F"` | `"R_2_F"` | Name of the RP |
-| `id` | `cms.int32` | `3` | `23` | `103` | `123` | ID of the RP |
-| `slope` | `cms.double` | `0.19` | `0.19` | `0.40` | `0.39` | Base slope value |
-| `sh_x` | `cms.double` | `-3.6` | `-42.` | `-2.8` | `-41.9` | Base sh_x value [mm]. X alignment method overwrites it. |
-| `x_min_fit_mode` | `cms.double` | `2.` | `2.` | `2.` | `2.` | Mode graph parameter. See [buildModeGraph](plugins/PPSAlignmentHarvester.cc#L648). |
-| `x_max_fit_mode` | `cms.double` | `7.` | `7.5` | `7.4` | `8.` | Mode graph parameter. See [buildModeGraph](plugins/PPSAlignmentHarvester.cc#L648). |
-| `y_max_fit_mode` | `cms.double` | `7.` | `7.5` | `7.4` | `8.` | Mode graph parameter (in 2018 the same value as x_max_fit_mode). See [buildModeGraph](plugins/PPSAlignmentHarvester.cc#L654). |
-| `y_cen_add` | `cms.double` | `-0.3` | `-0.3` | `-0.8` | `-0.8` | The value is added to y_cen (mean of y) while constructing a graph in x alignment. |
-| `y_width_mult` | `cms.double` | `1.1` | `1.1` | `1.0` | `1.` | y_width (RMS of y) is multiplied by the value when constructing a graph in x alignment. |
-| `x_slice_min` | `cms.double` | `7.` | `46.` | `6.` | `45.` | Min x for slice plots (x alignment) |
-| `x_slice_max` | `cms.double` | `19.` | `58.` | `17.` | `57.` | Max x for slice plots (x alignment) |
-| `x_slice_w` | `cms.double` | `0.2` | `0.2` | `0.2` | `0.2` | X width for slice plots (x alignment) |
+This package makes use of some modules from other packages:
+- `PPSAlignmentConfiguration` in *CondFormats/PPSObjects* - a conditions format used as a configuration input for the alignment procedure,
+- `PPSAlignmentConfigurationESSource` in *CalibPPS/ESProducers* - an ESSource module for `PPSAlignmentConfiguration`.
-## matching
-| Name | Type | Default | Description |
-|---------------------|--------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `reference_dataset` | `cms.string` | `""` | Directory of the file with reference dataset histograms. Should be empty when running the worker for the reference dataset. After that, should be set to the name of the created ROOT file (in the reference config). |
-| `rp_L_F` | `cms.PSet` | `-43.` - `-41.` | Left far RP. Contains two parameters of type `cms.double`: `sh_min` and `sh_max` - shift range for x alignment [mm] |
-| `rp_L_N` | `cms.PSet` | `-4.2` - `-2.4` | Left near RP. Contains two parameters of type `cms.double`: `sh_min` and `sh_max` - shift range for x alignment [mm] |
-| `rp_R_N` | `cms.PSet` | `-3.6` - `-1.8` | Right near RP. Contains two parameters of type `cms.double`: `sh_min` and `sh_max` - shift range for x alignment [mm] |
-| `rp_R_F` | `cms.PSet` | `-43.2` - `-41.2` | Right far RP. Contains two parameters of type `cms.double`: `sh_min` and `sh_max` - shift range for x alignment [mm] |
+For more information about the alignment algorithms and procedure, detailed instructions on how to run it, and possible use cases check out **[the TWiki page](https://twiki.cern.ch/twiki/bin/viewauth/CMS/PPSAlign)**.
-## x_alignment_meth_o
-| Name | Type | Default | Description |
-|--------------------------------|--------------|----------------|------------------------------------------------------------------------------------------------------------|
-| `rp_L_F` | `cms.PSet` | `47.` - `56.5` | Left far RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for x alignment |
-| `rp_L_N` | `cms.PSet` | `9.` - `18.5` | Left near RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for x alignment |
-| `rp_R_N` | `cms.PSet` | `7.` - `15.` | Right near RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for x alignment |
-| `rp_R_F` | `cms.PSet` | `46.` - `54.` | Right far RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for x alignment |
-| `fit_profile_min_bin_entries` | `cms.uint32` | `5` | Minimum number of entries in each bin in fitProfile method |
-| `fit_profile_min_N_reasonable` | `cms.uint32` | `10` | Minimum number of valid bins in fitProfile method |
-| `meth_o_graph_min_N` | `cms.uint32` | `5` | Minimum number of points in each of reference and test graph |
-| `meth_o_unc_fit_range` | `cms.double` | `0.5` | Fit range for chi-square graph. |
+## Contents of the package
-## x_alignment_relative
-| Name | Type | Default | Description |
-|------------------------|--------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `rp_L_N` | `cms.PSet` | `7.5` - `12.` | Sector 45 alignment x relative ranges configuration. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for relative x alignment |
-| `rp_R_N` | `cms.PSet` | `6.` - `10.` | Sector 56 alignment x relative ranges configuration. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for relative x alignment |
-| `near_far_min_entries` | `cms.uint32` | `100` | Minimum number of entries in n+A97:D100ear_far histograms |
-
-## y_alignment
-| Name | Type | Default | Description |
-|-------------------------------|--------------|----------------|------------------------------------------------------------------------------------------------------------|
-| `rp_L_F` | `cms.PSet` | `44.5` - `49.` | Left far RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for y alignment |
-| `rp_L_N` | `cms.PSet` | `6.7` - `11.` | Left near RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for y alignment |
-| `rp_R_N` | `cms.PSet` | `5.9` - `10.` | Right near RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for y alignment |
-| `rp_R_F` | `cms.PSet` | `44.5` - `49.` | Right far RP. Contains two parameters of type `cms.double`: `x_min` and `x_max` - x range for y alignment |
-| `mode_graph_min_N` | `cms.uint32` | `5` | Minimum number of points in mode graph |
-| `mult_sel_proj_y_min_entries` | `cms.uint32` | `300` | Minimum number of entries in y projection of multiplicity selection histograms |
-
-## binning
-| Name | Type | Default | Description |
-|-------------------|--------------|---------------|------------------------------------------|
-| `bin_size_x` | `cms.double` | `142.3314E-3` | X bin size |
-| `n_bins_x` | `cms.uint32` | `210` | Number of bins in many histograms |
-| `pixel_x_offset` | `cms.double` | `40.` | Pixel x offset |
-| `n_bins_y` | `cms.uint32` | `400` | Number of bins in many histograms |
-| `y_min` | `cms.double` | `-20.` | Min y for 2D histograms |
-| `y_max` | `cms.double` | `20.` | Max y for 2D histograms |
-| `diffFN_n_bins_x` | `cms.uint32` | `100` | Number of bins in near-far profiles |
-| `diffFN_x_min` | `cms.double` | `0.` | X axis min for near-far profiles |
-| `diffFN_x_max` | `cms.double` | `20.` | X axis max for near-far profiles |
-| `slice_n_bins_x` | `cms.uint32` | `100` | Number of bins in x axis for slice plots |
-| `slice_x_min` | `cms.double` | `-10.` | X axis min for slice plots |
-| `slice_x_max` | `cms.double` | `10.` | X axis max for slice plots |
-| `slice_n_bins_y` | `cms.uint32` | `100` | Number of bins in y axis for slice plots |
-| `slice_y_min` | `cms.double` | `-2.` | Y axis min for slice plots |
-| `slice_y_max` | `cms.double` | `2.` | Y axis max for slice plots |
\ No newline at end of file
+- *interface* and *src* - declarations and definitions of auxiliary functions
+- *plugins* - implementation of the main modules: `PPSAlignmentWorker` and `PPSAlignmentHarvester`
+- *python* - configuration files used by the PPS alignment matrix test and the PCL
+- *test* - example configuration files, instructions on how to run them, and expected results
diff --git a/CalibPPS/AlignmentGlobal/interface/utils.h b/CalibPPS/AlignmentGlobal/interface/utils.h
new file mode 100644
index 0000000000000..43d7b5fd4fb4a
--- /dev/null
+++ b/CalibPPS/AlignmentGlobal/interface/utils.h
@@ -0,0 +1,25 @@
+/****************************************************************************
+* Authors:
+* Jan Kašpar (jan.kaspar@gmail.com)
+* Mateusz Kocot (mateuszkocot99@gmail.com)
+****************************************************************************/
+
+#ifndef CalibPPS_AlignmentGlobal_utils_h
+#define CalibPPS_AlignmentGlobal_utils_h
+
+#include "TProfile.h"
+
+namespace alig_utils {
+
+ // Fits a linear function to a TProfile.
+ int fitProfile(TProfile* p,
+ double x_mean,
+ double x_rms,
+ unsigned int minBinEntries,
+ unsigned int minNBinsReasonable,
+ double& sl,
+ double& sl_unc);
+
+} // namespace alig_utils
+
+#endif
diff --git a/CalibPPS/AlignmentGlobal/plugins/BuildFile.xml b/CalibPPS/AlignmentGlobal/plugins/BuildFile.xml
index aa1c70dbc725d..447dba4a45165 100644
--- a/CalibPPS/AlignmentGlobal/plugins/BuildFile.xml
+++ b/CalibPPS/AlignmentGlobal/plugins/BuildFile.xml
@@ -10,6 +10,7 @@
+
diff --git a/CalibPPS/AlignmentGlobal/plugins/PPSAlignmentHarvester.cc b/CalibPPS/AlignmentGlobal/plugins/PPSAlignmentHarvester.cc
index d8b52504193be..2418dd15b9dae 100644
--- a/CalibPPS/AlignmentGlobal/plugins/PPSAlignmentHarvester.cc
+++ b/CalibPPS/AlignmentGlobal/plugins/PPSAlignmentHarvester.cc
@@ -23,14 +23,16 @@
#include "CondFormats/PPSObjects/interface/PPSAlignmentConfiguration.h"
#include "CondFormats/DataRecord/interface/PPSAlignmentConfigurationRcd.h"
+#include "CalibPPS/AlignmentGlobal/interface/utils.h"
+
#include
#include