From 15884e0c371723d795e853b030e8bce6955f3deb Mon Sep 17 00:00:00 2001
From: Gregor Weiss <hpcgweis@noreply.code.hlrs.de>
Date: Mon, 1 Jul 2024 10:08:58 +0000
Subject: [PATCH] =?UTF-8?q?Documentation=20hinzugef=C3=BCgt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Documentation.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 Documentation.md

diff --git a/Documentation.md b/Documentation.md
new file mode 100644
index 0000000..78b1e05
--- /dev/null
+++ b/Documentation.md
@@ -0,0 +1,65 @@
+<p align="center">
+    <img width="400" src="https://code.hlrs.de/TOPIO/BigWhoop/raw/branch/main/docs/img/Headline.svg" alt="Headline"
+</p>
+
+<h1 align="center">
+    Documentation
+</h1>
+
+<h2 align="center">
+ Disclaimer:
+ The API is currently under development and might be subject to slight changes. The general idea is still standing, as described below. Follow the changes in this documentation to stay on top of the newest changes.
+</h2>
+
+## Content
+- [Application Programming Interface](#application-programming-interface)
+    - [Compression](#compression)
+    - [Advanced Setting](#advanced-settings)
+    - [Decompression](#decompression)
+
+## Application Programming Interface
+
+The BigWhoop library presents its API as C functions prefixed with `bwc_*`. The usage for compression and decompression are symmetrized in the sequence of required function calls to set up either direction of the BWC codec. 
+
+### Compression
+
+Implement the following steps for compressing a floating point data array:
+
+```c
+bwc_codec *coder = bwc_alloc_coder(countDim1, countDim2 countDim3, countDim4, nPar, precision);
+bwc_stream *stream = bwc_init_stream(orig_in, comp_out, comp);
+bwc_create_compression(coder, stream, rate);
+bwc_compress(coder, stream);
+```
+
+The first line allocates an instance `coder` that holds the settings and operations for compression. The first four function arguments describe the number of elements in each dimension of the original data set, which can have up to four dimensions. Data sets with less than four dimensions pass `1` for the unused dimensionality. The parameter `nPar` is a count for the number of independent parameters that can be stacked inside the data set. The function argument `precision` passes the precision of the data set that can take one of three values `bwc_precision_half`, `bwc_precision_single`, and `bwc_precision_double`. After allocation, the `coder` can be reused for multiple data sets that are described by the same dimensionality, number of parameters, and floating point precision.
+
+The second line initializes the `bwc_stream` that handles the data set and the resulting compressed bitstream. The incoming pointers `orig_in` and `comp_out` must be managed by the user. This way, the BWC can be used on-the-fly for in-memory compression using readily existing pointers and buffers from the user applications. The argument `comp` is of type `bwc_mode` and classifies the `stream` to be input for compression.
+
+The last to lines combine `coder` and `stream` to compress the data set with the given `rate`.
+
+### Advanced Settings
+
+TBA
+
+### Decompression
+
+Implement the following steps for decompressing an BWC-compressed data set:
+
+```c
+bwc_codec *decoder = bwc_alloc_decoder();
+bwc_stream *stream = bwc_init_stream(comp_in, decomp_out, decomp);
+bwc_create_decompression(coder, stream, layer);
+bwc_compress(coder, stream);
+```
+
+Allocation of a `bwc_codec` for decompression, in the first line, is considerably simpler than for compression because the properties dimensionality, number of parameter, and precision of the original data set is encoded in the header of a compressed `bwc_stream`. 
+
+The second line passes the incoming, compressed stream as the pointer `comp_in` and provides a user defined buffer `decomp_out` for the decompressed output. The `decomp` flag signals the mode of the `stream` to be decompressed.
+
+The last to lines parse and decompress the data choosing a given quality layer.
+
+
+
+
+