From 99d3443d876769ba1b3fe75b95ac23b14d45b555 Mon Sep 17 00:00:00 2001
From: kautlenbachs <98521380+kautlenbachs@users.noreply.github.com>
Date: Mon, 8 Jan 2024 16:29:03 +0200
Subject: [PATCH] Documentation of SUM, ADD and release notes
---
README.md | 12 +-
RELEASE.md | 49 +++++++
doc/add/add_esa.md | 316 +++++++++++++++++++++++++++++++++++++++++++++
doc/sum/sum.md | 193 +++++++++++++++++++++++++++
doc/sum/sum_esa.md | 269 ++++++++++++++++++++++++++++++++++++++
5 files changed, 837 insertions(+), 2 deletions(-)
create mode 100644 doc/add/add_esa.md
create mode 100644 doc/sum/sum.md
create mode 100644 doc/sum/sum_esa.md
diff --git a/README.md b/README.md
index 9016416..365adab 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,18 @@ Developed during [IDEAS-QA4EO](https://qa4eo.org/) service operations lead by Te
## Out of the box usage
-Verified releases can be downloaded from - https://github.com/cgi-estonia-space/asar-focus/releases/
+Verified releases can be downloaded from - https://github.com/cgi-estonia-space/asar-focus/releases/. \
One can download docker image with all of the needed dependencies from dockerhub or simply `docker pull cgialus/alus-ootpa-devel`
-# License
+## Usage and requirements
+
+See [software user manual](doc/sum/sum.md)
+
+## Release history
+
+See [RELEASE.md](RELEASE.md)
+
+## License
[Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)](LICENSE.txt)
diff --git a/RELEASE.md b/RELEASE.md
index 2166e89..635d802 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,3 +1,52 @@
+# Release 0.2.0
+
+## Breaking changes
+
+## Known Caveats
+* Only IMS product processing
+* Not all the auxiliary files are utilized, currently processor configuration file (CON),
+ instrument characterization file (INS) and external calibration data (XCA) are in use
+* Azimuth compression windowing is yet to be done - https://github.com/cgi-estonia-space/asar-focus/issues/2
+* Processing speed (Vr) and Doppler centroid changes in azimuth direction yet to be done - https://github.com/cgi-estonia-space/asar-focus/issues/2
+* Packets' ISP sensing time handling might not be 100% correct
+ * It is observed for the reference products that it calculates new ISP sensing times based on PRI
+ * Therefore products by this processor differ in sensing start/stop and first/last line times (always inside the specified sensing filter)
+ * Best knowledge/effort basis changes has been implemented - https://github.com/cgi-estonia-space/asar-focus/issues/17 and https://github.com/cgi-estonia-space/asar-focus/issues/16
+* ERS time is not corrected according to PATM/N/C files - https://github.com/cgi-estonia-space/asar-focus/issues/15
+* Various metadata fields needs further work
+* Final results' scaling is yet to be determined, currently it is not matching exactly the reference processor
+ * With the current experience/knowledge there is a "best guess" implemented
+* See more shortcomings at https://cgi-estonia-space.github.io/asar-focus/posts/version-0-2-shortcomings/
+
+## Major Features and Improvements
+
+* Range and azimuth direction edge pixels are cut from the final result, [read more](https://cgi-estonia-space.github.io/asar-focus/posts/range-and-azimuth-window/)
+* CUDA device initialization, properties and check util
+* Storing results made faster with async IMS write and higher GPU utilization -
+ see https://github.com/cgi-estonia-space/asar-focus/pull/26 and https://cgi-estonia-space.github.io/asar-focus/posts/read-and-write-optimizations/
+* Complete refactor of parsing the input files, fetching measurements and processing - almost 3x of processing time
+ gains - https://github.com/cgi-estonia-space/asar-focus/pull/29 See more detailed description - https://cgi-estonia-space.github.io/asar-focus/posts/read-and-write-optimizations/
+* Better handling of missing packets and various fields for handling the missing measurements etc
+* Usage of external calibration file for scaling factor guess - https://github.com/cgi-estonia-space/asar-focus/pull/34
+* Final results without artifacts and 'nodata' pixels - see https://github.com/cgi-estonia-space/asar-focus/pull/33 and https://cgi-estonia-space.github.io/asar-focus/posts/range-and-azimuth-window/
+* Hamming window applied for range compression - https://github.com/cgi-estonia-space/asar-focus/pull/34
+* More metadata fields computed/assembled
+
+## Bug Fixes and Other Changes
+* Invalid read of single additional sample of Envisat measurement fixed - https://github.com/cgi-estonia-space/asar-focus/pull/30
+* Memory leak of the compressed sample block fixed - https://cgi-estonia-space.github.io/asar-focus/posts/read-and-write-optimizations/
+* Additional output for plot (`--plot`) that enables to analyze the geolocation of the scene and basic parameters
+* Fixed azimuth direction artifacts with padded lines for compression -
+ see https://github.com/cgi-estonia-space/asar-focus/pull/33 and https://cgi-estonia-space.github.io/asar-focus/posts/range-and-azimuth-window/
+* Envisat results scene geolocation inaccuracy fixed by applying gate bias/delay in the calculation - https://github.com/cgi-estonia-space/asar-focus/pull/33
+* More modules formed as CMake targets with unit tests
+
+## Thanks to our Contributors
+
+Kajal Haria, Fabiano Costantini from Telespazio UK\
+Sabrina Pinori, Marco Galli from SERCO\
+Andrea Recchia from aresys
+
# Release 0.1.2
## Breaking changes
diff --git a/doc/add/add_esa.md b/doc/add/add_esa.md
new file mode 100644
index 0000000..3811e4f
--- /dev/null
+++ b/doc/add/add_esa.md
@@ -0,0 +1,316 @@
+
+
+
+ASAR-FOCUS GPU processor
Architecture Design Document
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+CGI Estonia
Jan 8th 2024
Issue/Revision: 1/A
+
+
+Published (including this document) at Github
https://github.com/cgi-estonia-space/asar-focus
+
+
+
+
+CHANGE LOG
+
+
+
+| Issue/Revision | Date | Pages | Description |
+|----------------|------------|-------|------------------------------------|
+| 1/A | 08/01/2024 | All | Initial document for version 0.2.0 |
+
+
+
+
+
+TABLE OF CONTENTS
+
+
+* [1 Introduction](#1-introduction)
+* [1.1 Purpose](#11-purpose)
+* [1.2 Scope](#12-scope)
+* [2 System Overview](#2-system-overview)
+* [3 System Context](#3-system-context)
+* [4 System Design](#4-system-design)
+* [5 Component Description](#5-component-description)
+ * [5.1 DevicePaddedImage](#51-devicepaddedimage)
+ * [5.2 Envisat format module](#52-envisat-format-module)
+ * [5.3 Boost log](#53-boost-log)
+ * [5.4 Boost program arguments](#54-boost-program-arguments)
+ * [5.4 cuFFT](#54-cufft)
+* [6 Feasability and Resource Estimates](#6-feasability-and-resource-estimates)
+ * [6.1 Profiling analyze](#61-profiling-analyze)
+ * [6.2 GPU and RAM memory limit based on the dataset size](#62-gpu-and-ram-memory-limit-based-on-the-dataset-size)
+
+
+
+
+DEFINITIONS, ACRONYMS AND ABBREVIATIONS
+
+
+
+| Acronym/abbreviation | Definition |
+|----------------------|-------------------------------------|
+| CC | CUDA Compute Capability |
+| CLI | Command-line interface |
+| COTS | Component Off-the-Shelf |
+| CUDA | Compute Unified Device Architecture |
+| GPU | Graphics Processing Unit |
+| OS | Operating system |
+| RHEL | Red Hat Enterprise Linux |
+| SDK | Software Development Kit |
+| SNAP | Sentinel Application Platform |
+
+
+
+
+
+# 1 Introduction
+
+# 1.1 Purpose
+
+Using GPUs for earth observation (EO) data processing is a rather undeveloped method. At the same time this is not a
+novel way, because such approaches have been developed for more than 10 years. This was enabled by the
+NVIDIA's CUDA architecture which makes possible to process generic payloads besides graphical textures. The `asar_focus`
+processor is one of the attempts to reproduce the data quality of a legacy CPU based processor while enabling
+processing performance gains.
+
+This document aims to facilitate:
+* further development of the focusser
+* document the principles of efficient EO data processing using parallel processing paradigm
+
+
+# 1.2 Scope
+
+There is a single executable binary produced by the software package. It is built for Red Hat Enterprise Linux version
+8.x. All the other components required are detailed in the [software user manual](https://github.com/cgi-estonia-space/asar-focus/blob/documentation/doc/sum/sum.md).
+The project could be run on other Linux distributions as well, with possible tweaking of the required components.
+
+Current state of the focusser will be able to focus ERS-1/2 and Envisat's synthetic aperture radar (SAR) instrument's
+data for the imaging mode (IM) datasets only. It lacks some functionality in order to match the baseline PF-ASAR
+processor functionality:
+* PATC/PATN support for ERS time synchronization is missing
+* Sections of metadata is not appropriately formed (enough for products to be further processed in ESA SNAP)
+* Focussing quality is not matched (visually good, but histograms of focussed I/Q raster are not so well-formed)
+
+Current state of the developed functionality enables to:
+* Revisit details of the missions' instrument processing and document it properly for further developments
+* Implement all the other acquisition modes' (wave, alternating polarisation etc.)
+ parallel processing pipelines with less effort
+* Re-analyze baseline processor PF-ASAR data quality and develop further enhancements
+* Lower the costs of the instrument data processing facility by faster and more energy efficient processing
+
+# 2 System Overview
+
+The GPU accelerated processors greatly benefit from the parallel computing paradigm. Previous ESA activities developed
+by CGI Estonia together with CGI Italy and industry experts have produced set of GPU accelerated processors available
+on [Github](https://github.com/cgi-estonia-space/ALUs). The processing speed and data quality numbers are given in the
+repository and its [Wiki](https://github.com/cgi-estonia-space/ALUs/wiki). As a general outcome the processing speed
+could be increased from 10 to 100 times while enabling up to 10 times fewer costs than utilising traditional processors
+tha leverage CPU for computing.
+
+In order to achieve fast processing utilising GPU one has to focus on:
+* Minimising data transfers between storage, RAM and GPU
+* Utilise as fast as possible disk or RAM storage mechanisms
+* Utilise GPU as much and often as possible during the execution of the processor
+
+# 3 System Context
+
+This processor's general system has been kept simple which has been validated by the
+[ALUs](https://github.com/cgi-estonia-space/ALUs) processors. This has proven to enable further integration with other
+systems with possibility to add convenient functionality like graphical user interface or data fetching. Below are
+general blocks that define the approach.
+
+
+
+*Figure 3.0 - General system block scheme*
+
+The OS here facilitates:
+* Execution of binary on a system with the GPU
+* File input/output
+* Memory management
+* CPU threading
+
+The CUDA component enables:
+* Query and check the GPU properties
+* Command GPU
+* Transfer data between GPU and RAM
+
+The `asar_focus` processor:
+* Command line arguments handling
+* Dataset parsing and results formating
+* Focussing pipeline implementation
+* Efficient disk storage read and write strategies
+* Efficient GPU occupation strategies
+* System logs
+* Error checks for dataset and GPU
+
+# 4 System Design
+
+Main focus is on the efficient GPU processing pipeline where the time spent on I/O should be minimized or parallelized
+while processing calculations. Below is the general pipeline of the processor.
+
+
+
+*Figure 4.0 - General processing pipeline*
+
+The **measurements processing** step is generic focussing pipeline that is represented by the figure below.
+
+
+*Figure 4.1 - Generic focussing pipeline*
+
+Both of these figures above are tightly coupled. As can be seen on the last figure the "raw file decoding" and
+"processed file" are the steps that are mostly presented on the first figure. Based on current profiling results dataset
+parsing and writing takes 60 and more percent of the overall end to end time, depending heavily on the storage device
+capability.
+
+# 5 Component Description
+
+## 5.1 DevicePaddedImage
+
+SAR focusing requires forward and backwards Fourier transforms in range and azimuth directions, additionally the SAR
+datasets are quite large
+
+DevicePaddedImage is the core abstraction to facilitate efficient SAR transformations by embedding extra padding areas
+in the right and bottom of the image. This allows inplace FFTs in both range and azimuth direction, this alleviates
+the need for extra memory copies to fulfill FFT size requirements. Thus changing from time domain to frequency domain
+and back is done memory efficiently, without needlessly copying multi gigabyte signal data.
+
+Additional design consideration is the fact that GPU onboard memory is less than main board RAM, thus using this
+technique allows to keep the full DSP chain on the GPU memory, avoiding costly CPU <-> GPU transfers.
+Visual representation of the memory layout.
+```
+ RANGE
+ |------------------------|---------|
+ A | | |
+ Z | SAR SIGNAL DATA | RANGE |
+ I | | FFT |
+ M | | PADDING |
+ U | | |
+ T |------------------------|---------|
+ H | AZIMUTH FFT PADDING | |
+ |------------------------|---------|
+```
+
+## 5.2 Envisat format module
+
+The Envisat format support handling and support was implemented during this project. No libraries were used. This includes
+custom structures, little/big-endian conversions and data type handling. All the implementation is contained in
+`envisat_format` folder of the project. It applies to both the ERS and Envisat mission datasets
+
+It contains the following sub-functionality:
+* DORIS orbit file search and parsing
+* Auxiliary files' search and parsing
+* Level 0 imaging mode dataset parsing
+* Level 1 image mode single look complex dataset structure and writing
+* GPU computation kernels to condition the measurements
+
+## 5.3 Boost log
+
+Boost library's submodule implemented in C++ to enable console log handling. This enables structured logs with timestamps
+and different log levels.
+
+An extract of the curren log:
+```
+[2024-01-08 11:43:57.852098] [0x00007fa101e9b000] [debug] Doppler centroid constant term -568.25 and max aperture pixels 543
+[2024-01-08 11:43:57.852121] [0x00007fa101e9b000] [info] Need to remove 543 lines before requested sensing stop
+[2024-01-08 11:43:57.853812] [0x00007fa101e9b000] [debug] Azimuth compression time = 536 ms
+[2024-01-08 11:43:57.854107] [0x00007fa101e9b000] [trace] SWST change at line 19814 from 2024 to 2048
+[2024-01-08 11:43:57.854160] [0x00007fa101e9b000] [debug] Swath = IS2 idx = 1
+```
+
+## 5.4 Boost program arguments
+
+Boost library's submodule implemented in C++. Used to facilitate command line arguments handling. All the setup, help
+messages, validation and parsing is achieved using this module.
+
+Example of the interface built using the module.
+
+```
+asar_focus/0.2.0
+ -h [ --help ] Print help
+ -i [ --input ] arg Level 0 ERS or ENVISAT dataset
+ --aux arg Auxiliary files folder path
+ --orb arg Doris Orbit file or folder path
+ -o [ --output ] arg Destination path for focussed dataset
+ -t [ --type ] arg Focussed product type
+ --sensing_start arg Sensing start time in format '%Y%m%d_%H%M%S%F' e.g.
+ 20040229_212504912000. If "sensing_stop" is not
+ specified, product type based sensing duration is used
+ or until packets last.
+ --sensing_stop arg Sensing stop time in format '%Y%m%d_%H%M%S%F' e.g.
+ 20040229_212504912000. Requires "sensing_start" time
+ to be specified.
+ --log arg (=verbose) Log level, one of the following -
+ verbose|debug|info|warning|error
+```
+
+## 5.4 cuFFT
+
+Submodule of the umbrella CUDA SDK. While other functionality of the CUDA is rather generic and detailed on the NVIDIA
+developer sites, the usage of cuFFT is documented here.
+
+The SAR focussing pipeline uses the Fourier transforms in range and azimuth direction to generate the final focussed
+product. This library can highly perform massively parallelized FFT transforms of the whole signal data in one function
+call.
+
+
+# 6 Feasability and Resource Estimates
+
+## 6.1 Profiling analyze
+
+Example GPU profiling chart is presented below
+
+
+*Figure 6.1 - Processor profiling*
+
+Test setup:
+* RTX3060 Laptop GPU<
+* AMD Ryzen 7 5800H CPU
+* Fast NVMe SSD
+
+Test data - Envisat IM -> Envisat IMS. About 16 seconds of signal data. The whole chain is processed in less than 2 seconds.
+Summary of the time spent:
+1. File read, metadata parsing & signal data DISK -> CPU -> GPU (350 ms)
+2. Core SAR DSP chain (700 ms)
+3. Metadata assembly, file writing GPU -> CPU -> disk (750 ms)
+
+Steps 1 & 3 are heavily dependent on the performance of the storage and can be a major bottleneck. Step 2 is mostly done
+on the GPU and the most time-consuming steps are the FFTs calculated by cuFFT. The CPU speed is not relevant as no
+major focussing steps are bottleneck by the CPU.
+
+There still some optimizations that could be done:
+* Forecast level 0 dataset offsets and therefore no need to wait and read all the file
+* Deallocate GPU and RAM buffers earlier
+
+With this there could be nearly 1 second processing time when the RAM disk is a source and target disk storage.
+
+## 6.2 GPU and RAM memory limit based on the dataset size
+
+The baseline GPU memory requirement is estimated to be:\
+`Total memory usage = Range size * Azimuth size * 8 * 1.3 * 2`
+
+Where:
+* Range size is level 0 range size
+* Azimuth size is total number of processed packets
+* 8 is size of the complex float
+* 1.3 is rough estimate of the paddings required for range and azimuth compression and additional metadata
+* 2 is memory used for FFTs and output image generation (that includes back and forth buffer)
+
+On a standard 16 seconds IMS dataset, this results in about 3GB of GPU memory. CPU RAM memory usage is roughly
+the input file size plus the output file size. Other elements take insignificant amount of memory.
diff --git a/doc/sum/sum.md b/doc/sum/sum.md
new file mode 100644
index 0000000..df28ec3
--- /dev/null
+++ b/doc/sum/sum.md
@@ -0,0 +1,193 @@
+# 1 Introduction
+
+Following information describes the usage of the ERS and Envisat focusser utilizing GPU. It is implemented in C/C++/CUDA
+programming languages. Here is described how to install dependencies and build/compile and run the processor. Not all
+steps have to be executed in order to run focussing process. There are prebuilt container images and binaries available.
+The processor contains **hidden** functionality that could be invoked to
+analyze the internals of the processing results. They are described in the chapters below.
+
+Required datasets and auxiliary files are also described. Although for better and more complete overview following
+documents are suggested:
+* QA4EO-SER-REP-REP-4512
+* PO-RS-MDA-GS-2009 Chapter 8
+
+
+
+# 2 Prerequisites
+
+Currently tested target platforms are Ubuntu 22.04 LTS (codename Jammy and its flavours) and Red Hat Enterprise Linux
+version 8 (codename Ootpa). There are 2 set of requirements lists - for development (devel) and for running (runtime).
+Common components are NVIDIA GPU driver and CUDA SDK components that should be installed on the processing environment
+for both scenarios.
+
+The list of packages and installation scripts are available at [ALUS-platform Github repo](https://github.com/cgi-estonia-space/ALUs-platform).
+Based on target platform one can conveniently choose intended scripts. Subchapters consist summary of those.
+
+## 2.1 Common components
+
+| Name | Version | Description | Instructions |
+|---------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Nvidia driver | 525 >= | Component that manages the GPU(s) installed on the system. Also manages low level communication with the device(s). Exposes driver API which is utilized by CUDA Toolkit libraries. | [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/install_nvidia_driver.sh)/[Ootpa manual](https://gist.github.com/kautlenbachs/8c6d7966693668d94aa86085403f4821) \| [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy-aws/install_nvidia_container_base.sh) |
+| Cuda SDK | 11.2 >= 12.0 < | Enables GPU interfacing through the driver API. Also includes GPU tuned libraries for FFT, algebra, etc. | [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/install_cuda_base.sh)/[Ootpa manual](https://gist.github.com/kautlenbachs/8c6d7966693668d94aa86085403f4821#installation-of-cuda-sdk) \| [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy/install_cuda_base.sh) | |
+
+
+### 2.1.1 Enabling containers
+
+There are many options to choose from which are all summarized on Nvidia's official CDI page at https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html.
+The scenario could vary from the type of operating system to orchestration framework used. This means there could be
+different engines used - docker, containerd, CRI-O and podman - which all need customized setup.
+
+Currently utilized and tested approaches within this project are represented below:
+* [podman on Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/install_container_toolkit.sh)
+* [docker on Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy-aws/install_nvidia_container_base.sh)
+
+### 2.1.2 Prebuilt containers
+
+Below are listed published container images on Dockerhub
+
+| Platform | Development | Runtime |
+|----------|----------------------------|------------------------------|
+| Ootpa | `cgialus/alus-ootpa-devel` | `cgialus/alus-ootpa-runtime` |
+| Jammy | `cgialus/alus-devel` | `cgialus/alus-runtime` |
+
+## 2.2 Runtime COTS
+
+| Name | Version | Description |
+|-----------|-----------------|---------------------------------------------------------|
+| libstdc++ | == 6.0 | The GNU C++ standard library |
+| boost | == 1.71 <= 1.78 | Libraries for CLI arguments, date and time and logging |
+| GDAL | == 3.0.4 | Creates GeoTIFF files for analyzing purposes |
+
+Setup scripts:
+* [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/setup_runtime.sh)
+* [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy/setup_runtime.sh)
+
+## 2.3 Development COTS
+
+| Name | Version | Description |
+|-----------|-----------------|---------------------------------------------------------|
+| CMake | \>= 3.20 | Build files generation and build execution |
+| nvcc | \>= 11.2 < 12.0 | Compiler for GPU device code |
+| g++ | \>=8.5 < 12.0 | Compiler for C/C++ host code |
+| libstdc++ | == 6.0 | The GNU C++ standard library |
+| fmt | == 10.1 | String, integer and object text print utility |
+| gtest | == 1.10 | Automated test development - unit and integration tests |
+| boost | == 1.71 <= 1.78 | Libraries for CLI arguments, date and time and logging |
+| Eigen | == 3.4 | Algebra library, header only |
+| GDAL | == 3.0.4 | Creates GeoTIFF files for analyzing purposes |
+
+Setup scripts:
+* [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/setup_devel.sh)
+* [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy/setup_dev.sh)
+
+# 3 Usage
+
+The developed processor called `asar_focus` is a single executable GPU ERS and ENVISAT SAR focussing tool. No graphical
+user interface or any other hidden requirements are present. Below will be described the arguments, formats and input
+datasets/auxiliary files. All the produced files will be written to the location specified by the `output` argument.
+
+If the program has successfully processed the product the return code of the binary execution will be **0**. Any other
+exit code means error during processing which SHALL be accompanied by the message on the console. Unsuccessful
+processing could occur due to the invalid input(s), programming error or host machine's/OS errors/congestion.
+
+There is no distinction between ERS and ENVISAT instrument datasets. When there are modes/types given that are not
+present for given instrument then this is reported. Same goes for datasets - the processor makes decisions
+based on the given input arguments.
+
+## 3.1 CLI arguments
+
+All the processing input is given by the program arguments. No environment variables or configuration files are used.
+Somewhat exceptions are mission and instrument specific auxiliary files which are supplied with the directory from
+which the processor searches for specific files based on input dataset sensing time. For orbit files either directory or
+specific DORIS orbit file path could be given. When not specifying sensing time the processor will process all level 0
+input packets if there is sufficient GPU memory.
+
+```
+asar_focus/0.2.0
+ -h [ --help ] Print help
+ -i [ --input ] arg Level 0 ERS or ENVISAT dataset
+ --aux arg Auxiliary files folder path
+ --orb arg Doris Orbit file or folder path
+ -o [ --output ] arg Destination path for focussed dataset
+ -t [ --type ] arg Focussed product type
+ --sensing_start arg Sensing start time in format '%Y%m%d_%H%M%S%F' e.g.
+ 20040229_212504912000. If "sensing_stop" is not
+ specified, product type based sensing duration is used
+ or until packets last.
+ --sensing_stop arg Sensing stop time in format '%Y%m%d_%H%M%S%F' e.g.
+ 20040229_212504912000. Requires "sensing_start" time
+ to be specified.
+ --log arg (=verbose) Log level, one of the following -
+ verbose|debug|info|warning|error
+```
+
+As of release version 0.2 only single `type` is supported which is `IMS`. Any other value would result in termination
+of processing with accompanying message on console.
+
+### 3.1.1 Hidden CLI features
+
+For debugging and research possibilities couple of 'unofficial' command line arguments are present which are given below.
+* `--plot` - create HTML files consisting graphs of the following processing properties - processing velocity,
+ chirp signal, doppler centroid and scene geolocation properties on earth
+* `--intensity` - create GeoTIFF files of the raw measurements, range compressed results and fully compressed intensity
+
+All the created files would be saved in the same directory as the final product given by the `output` argument. They are
+prefixed with the level 0 dataset name pattern.
+
+### 3.1.3 Examples
+
+During the production and internal tests there are so called test datasets (TDS) packages used. This is not required
+and one could simply have manually assembled the collection of suitable orbit files and auxiliary files downloaded as
+a bundle on online at available ESA sites (see [ERS](https://earth.esa.int/eogateway/instruments/sar-ers/auxiliary-data)
+and [ENVISAT](https://earth.esa.int/eogateway/instruments/asar/auxiliary-data)).
+Both of the scenarios are supported. Below are given examples for both.
+
+**Manually assembled datasets**
+```
+asar_focus --input SAR_IM__0PWDSI19920904_101949_00000018C087_00294_05950_0000.E1
+--aux ers1_aux_dir
+--orb ers1_pds_orbit_dir -o /home/foo/ -t IMS
+```
+
+**TDS**
+```
+asar_focus --input
+TDS09/ASA_IMS_1PNESA20040229_212506_000000152024_00387_10461_0000.N1/
+ASA_IM__0PNPDK20040229_212454_000000492024_00387_10461_2585.N1
+--aux TDS09/ASA_IMS_1PNESA20040229_212506_000000152024_00387_10461_0000.N1
+--orb TDS09/ASA_IMS_1PNESA20040229_212506_000000152024_00387_10461_0000.N1/
+DOR_VOR_AXVF-P20120424_125300_20040228_215528_20040301_002328
+--type IMS --output /home/foo/ --sensing_start 20040229_212504912000
+--sensing_stop 20040229_212523002000
+```
+
+## 3.2 Input datasets
+
+Single level 0 **envisat format** ERS-1/2 and Envisat mission dataset is required. As of version 0.2 only imaging mode
+datasets are supported. The specification is given in document `PO-RS-MDA-GS-2009 4/C`.
+
+## 3.3 Auxiliary files
+
+As of version 0.2 the following auxiliary files are used:
+* DORIS orbit files in envisat format, see [DOR_VOR_AX](https://earth.esa.int/eogateway/catalog/envisat-doris-precise-orbit-state-vectors-dor-vor_ax-)
+* Processor configuration file (ASA_CON_AX/ER_CON_AX)
+* Instrument characterization file (AUX_INS_AX/ER_INS_AX)
+* External calibration data (ASA_XCA_AX/ER_XCA)
+
+For auxiliary file access and documentation please visit [ERS aux](https://earth.esa.int/eogateway/instruments/sar-ers/auxiliary-data)
+and [ENVISAT aux](https://earth.esa.int/eogateway/instruments/asar/auxiliary-data) pages at ESA.
+
+# 4 Requirements
+
+Below are specified minimum requirements for hardware. It is based on the resources needed to focus 16 seconds of
+level 0 imaging mode dataset. Resource like CPU is out of scope, because all modern CPUs are suitable. Disk storage
+resource is dismal, since only level 1 dataset storage is required also no intermediate files are stored
+(except for debugging features discussed in [3.1.1 Hidden CLI features](#311-hidden-cli-features)).
+
+| Property | Value |
+|------------------------|--------|
+| RAM | 4 GB |
+| GPU (V)RAM | 4 GB |
+| NVIDIA CUDA generation | CC 6.0 |
+
+For specific compute capability and NVIDIA GPU models, please see [CUDA wikipedia page](https://en.wikipedia.org/wiki/CUDA#GPUs_supported).
diff --git a/doc/sum/sum_esa.md b/doc/sum/sum_esa.md
new file mode 100644
index 0000000..90b84de
--- /dev/null
+++ b/doc/sum/sum_esa.md
@@ -0,0 +1,269 @@
+
+
+
+ASAR-FOCUS GPU processor
Software User Manual
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+CGI Estonia
Jan 8th 2024
Issue/Revision: 1/A
+
+
+Published (including this document) at Github
https://github.com/cgi-estonia-space/asar-focus
+
+
+
+
+CHANGE LOG
+
+
+
+| Issue/Revision | Date | Pages | Description |
+|----------------|------------|-------|------------------------------------|
+| 1/A | 08/01/2024 | All | Initial document for version 0.2.0 |
+
+
+
+
+
+TABLE OF CONTENTS
+
+
+* [1 Introduction](#1-introduction)
+* [2 Prerequisites](#2-prerequisites)
+ * [2.1 Common components](#21-common-components)
+ * [2.1.1 Enabling containers](#211-enabling-containers)
+ * [2.1.2 Prebuilt containers](#212-prebuilt-containers)
+ * [2.2 Runtime COTS](#22-runtime-cots)
+ * [2.3 Development COTS](#23-development-cots)
+* [3 Usage](#3-usage)
+ * [3.1 CLI arguments](#31-cli-arguments)
+ * [3.2 Input datasets](#32-input-datasets)
+ * [3.3 Auxiliary files](#33-auxiliary-files)
+
+
+
+
+DEFINITIONS, ACRONYMS AND ABBREVIATIONS
+
+
+
+| Acronym/abbreviation | Definition |
+|----------------------|-------------------------------------|
+| CC | CUDA Compute Capability |
+| CLI | Command-line interface |
+| COTS | Component Off-the-Shelf |
+| CUDA | Compute Unified Device Architecture |
+| GPU | Graphics Processing Unit |
+| RHEL | Red Hat Enterprise Linux |
+| SDK | Software Development Kit |
+
+
+
+
+
+# 1 Introduction
+
+Following information describes the usage of the ERS and Envisat focusser utilizing GPU. It is implemented in C/C++/CUDA
+programming languages. Here is described how to install dependencies and build/compile and run the processor. Not all
+steps have to be executed in order to run focussing process. There are prebuilt container images and binaries available.
+The processor contains **hidden** functionality that could be invoked to
+analyze the internals of the processing results. They are described in the chapters below.
+
+Required datasets and auxiliary files are also described. Although for better and more complete overview following
+documents are suggested:
+* QA4EO-SER-REP-REP-4512
+* PO-RS-MDA-GS-2009 Chapter 8
+
+
+
+# 2 Prerequisites
+
+Currently tested target platforms are Ubuntu 22.04 LTS (codename Jammy and its flavours) and Red Hat Enterprise Linux
+version 8 (codename Ootpa). There are 2 set of requirements lists - for development (devel) and for running (runtime).
+Common components are NVIDIA GPU driver and CUDA SDK components that should be installed on the processing environment
+for both scenarios.
+
+The list of packages and installation scripts are available at [ALUS-platform Github repo](https://github.com/cgi-estonia-space/ALUs-platform).
+Based on target platform one can conveniently choose intended scripts. Subchapters consist summary of those.
+
+## 2.1 Common components
+
+| Name | Version | Description | Instructions |
+|---------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Nvidia driver | 525 >= | Component that manages the GPU(s) installed on the system. Also manages low level communication with the device(s). Exposes driver API which is utilized by CUDA Toolkit libraries. | [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/install_nvidia_driver.sh)/[Ootpa manual](https://gist.github.com/kautlenbachs/8c6d7966693668d94aa86085403f4821) \| [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy-aws/install_nvidia_container_base.sh) |
+| Cuda SDK | 11.2 >= 12.0 < | Enables GPU interfacing through the driver API. Also includes GPU tuned libraries for FFT, algebra, etc. | [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/install_cuda_base.sh)/[Ootpa manual](https://gist.github.com/kautlenbachs/8c6d7966693668d94aa86085403f4821#installation-of-cuda-sdk) \| [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy/install_cuda_base.sh) | |
+
+
+### 2.1.1 Enabling containers
+
+There are many options to choose from which are all summarized on Nvidia's official CDI page at https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html.
+The scenario could vary from the type of operating system to orchestration framework used. This means there could be
+different engines used - docker, containerd, CRI-O and podman - which all need customized setup.
+
+Currently utilized and tested approaches within this project are represented below:
+* [podman on Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/install_container_toolkit.sh)
+* [docker on Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy-aws/install_nvidia_container_base.sh)
+
+### 2.1.2 Prebuilt containers
+
+Below are listed published container images on Dockerhub
+
+| Platform | Development | Runtime |
+|----------|----------------------------|------------------------------|
+| Ootpa | `cgialus/alus-ootpa-devel` | `cgialus/alus-ootpa-runtime` |
+| Jammy | `cgialus/alus-devel` | `cgialus/alus-runtime` |
+
+## 2.2 Runtime COTS
+
+| Name | Version | Description |
+|-----------|-----------------|---------------------------------------------------------|
+| libstdc++ | == 6.0 | The GNU C++ standard library |
+| boost | == 1.71 <= 1.78 | Libraries for CLI arguments, date and time and logging |
+| GDAL | == 3.0.4 | Creates GeoTIFF files for analyzing purposes |
+
+Setup scripts:
+* [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/setup_runtime.sh)
+* [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy/setup_runtime.sh)
+
+## 2.3 Development COTS
+
+| Name | Version | Description |
+|-----------|-----------------|---------------------------------------------------------|
+| CMake | \>= 3.20 | Build files generation and build execution |
+| nvcc | \>= 11.2 < 12.0 | Compiler for GPU device code |
+| g++ | \>=8.5 < 12.0 | Compiler for C/C++ host code |
+| libstdc++ | == 6.0 | The GNU C++ standard library |
+| fmt | == 10.1 | String, integer and object text print utility |
+| gtest | == 1.10 | Automated test development - unit and integration tests |
+| boost | == 1.71 <= 1.78 | Libraries for CLI arguments, date and time and logging |
+| Eigen | == 3.4 | Algebra library, header only |
+| GDAL | == 3.0.4 | Creates GeoTIFF files for analyzing purposes |
+
+Setup scripts:
+* [Ootpa](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/rhel/8/ootpa/setup_devel.sh)
+* [Jammy](https://github.com/cgi-estonia-space/ALUs-platform/blob/main/ubuntu/22_04/jammy/setup_dev.sh)
+
+# 3 Usage
+
+The developed processor called `asar_focus` is a single executable GPU ERS and ENVISAT SAR focussing tool. No graphical
+user interface or any other hidden requirements are present. Below will be described the arguments, formats and input
+datasets/auxiliary files. All the produced files will be written to the location specified by the `output` argument.
+
+If the program has successfully processed the product the return code of the binary execution will be **0**. Any other
+exit code means error during processing which SHALL be accompanied by the message on the console. Unsuccessful
+processing could occur due to the invalid input(s), programming error or host machine's/OS errors/congestion.
+
+There is no distinction between ERS and ENVISAT instrument datasets. When there are modes/types given that are not
+present for given instrument then this is reported. Same goes for datasets - the processor makes decisions
+based on the given input arguments.
+
+## 3.1 CLI arguments
+
+All the processing input is given by the program arguments. No environment variables or configuration files are used.
+Somewhat exceptions are mission and instrument specific auxiliary files which are supplied with the directory from
+which the processor searches for specific files based on input dataset sensing time. For orbit files either directory or
+specific DORIS orbit file path could be given. When not specifying sensing time the processor will process all level 0
+input packets if there is sufficient GPU memory.
+
+```
+asar_focus/0.2.0
+ -h [ --help ] Print help
+ -i [ --input ] arg Level 0 ERS or ENVISAT dataset
+ --aux arg Auxiliary files folder path
+ --orb arg Doris Orbit file or folder path
+ -o [ --output ] arg Destination path for focussed dataset
+ -t [ --type ] arg Focussed product type
+ --sensing_start arg Sensing start time in format '%Y%m%d_%H%M%S%F' e.g.
+ 20040229_212504912000. If "sensing_stop" is not
+ specified, product type based sensing duration is used
+ or until packets last.
+ --sensing_stop arg Sensing stop time in format '%Y%m%d_%H%M%S%F' e.g.
+ 20040229_212504912000. Requires "sensing_start" time
+ to be specified.
+ --log arg (=verbose) Log level, one of the following -
+ verbose|debug|info|warning|error
+```
+
+As of release version 0.2 only single `type` is supported which is `IMS`. Any other value would result in termination
+of processing with accompanying message on console.
+
+### 3.1.1 Hidden CLI features
+
+For debugging and research possibilities couple of 'unofficial' command line arguments are present which are given below.
+* `--plot` - create HTML files consisting graphs of the following processing properties - processing velocity,
+chirp signal, doppler centroid and scene geolocation properties on earth
+* `--intensity` - create GeoTIFF files of the raw measurements, range compressed results and fully compressed intensity
+
+All the created files would be saved in the same directory as the final product given by the `output` argument. They are
+prefixed with the level 0 dataset name pattern.
+
+### 3.1.3 Examples
+
+During the production and internal tests there are so called test datasets (TDS) packages used. This is not required
+and one could simply have manually assembled the collection of suitable orbit files and auxiliary files downloaded as
+a bundle on online at available ESA sites (see [ERS](https://earth.esa.int/eogateway/instruments/sar-ers/auxiliary-data)
+and [ENVISAT](https://earth.esa.int/eogateway/instruments/asar/auxiliary-data)).
+Both of the scenarios are supported. Below are given examples for both.
+
+**Manually assembled datasets**
+```
+asar_focus --input SAR_IM__0PWDSI19920904_101949_00000018C087_00294_05950_0000.E1
+--aux ers1_aux_dir
+--orb ers1_pds_orbit_dir -o /home/foo/ -t IMS
+```
+
+**TDS**
+```
+asar_focus --input
+TDS09/ASA_IMS_1PNESA20040229_212506_000000152024_00387_10461_0000.N1/
+ASA_IM__0PNPDK20040229_212454_000000492024_00387_10461_2585.N1
+--aux TDS09/ASA_IMS_1PNESA20040229_212506_000000152024_00387_10461_0000.N1
+--orb TDS09/ASA_IMS_1PNESA20040229_212506_000000152024_00387_10461_0000.N1/
+DOR_VOR_AXVF-P20120424_125300_20040228_215528_20040301_002328
+--type IMS --output /home/foo/ --sensing_start 20040229_212504912000
+--sensing_stop 20040229_212523002000
+```
+
+## 3.2 Input datasets
+
+Single level 0 **envisat format** ERS-1/2 and Envisat mission dataset is required. As of version 0.2 only imaging mode
+datasets are supported. The specification is given in document `PO-RS-MDA-GS-2009 4/C`.
+
+## 3.3 Auxiliary files
+
+As of version 0.2 the following auxiliary files are used:
+* DORIS orbit files in envisat format, see [DOR_VOR_AX](https://earth.esa.int/eogateway/catalog/envisat-doris-precise-orbit-state-vectors-dor-vor_ax-)
+* Processor configuration file (ASA_CON_AX/ER_CON_AX)
+* Instrument characterization file (AUX_INS_AX/ER_INS_AX)
+* External calibration data (ASA_XCA_AX/ER_XCA)
+
+For auxiliary file access and documentation please visit [ERS aux](https://earth.esa.int/eogateway/instruments/sar-ers/auxiliary-data)
+and [ENVISAT aux](https://earth.esa.int/eogateway/instruments/asar/auxiliary-data) pages at ESA.
+
+# 4 Requirements
+
+Below are specified minimum requirements for hardware. It is based on the resources needed to focus 16 seconds of
+level 0 imaging mode dataset. Resource like CPU is out of scope, because all modern CPUs are suitable. Disk storage
+resource is dismal, since only level 1 dataset storage is required also no intermediate files are stored
+(except for debugging features discussed in [3.1.1 Hidden CLI features](#311-hidden-cli-features)).
+
+| Property | Value |
+|------------------------|--------|
+| RAM | 4 GB |
+| GPU (V)RAM | 4 GB |
+| NVIDIA CUDA generation | CC 6.0 |
+
+For specific compute capability and NVIDIA GPU models, please see [CUDA wikipedia page](https://en.wikipedia.org/wiki/CUDA#GPUs_supported).