wdata-format-concept.md

@@ -3,20 +3,22 @@
 * Binary data is stored in a **conceptually easy format** that allows a variety of tools/languages to be used.
 * Format provides storage for data with time stepping (frames/measurements/cycles).
 * Data format is suitable for parallel processing (preferably with MPI I/O).
-* Data is easy for processing via [VisIt](https://visit-dav.github.io/visit-website/index.html).
+* Data is easy to process via [VisIt](https://visit-dav.github.io/visit-website/index.html).
 * It provides an extensible framework - new variables can be created and easily added to the existing dataset.  
-* Data is convenient for copy between computing systems.  
-* It allows for easy extraction/copy of selected variables
+* Data is convenient for copying between computing systems.  
+* It allows for easy extraction/copying of selected variables.
+
+**W-data** format **is not a library**. It is only a **concept**. It specifies how the data should be saved or read. It means that you do not need to use any external libraries to be able to read or write. It is sufficient to use standard I/O functions to work with this format. We provide within this repository libraries written in C or in python just for convenience. 
 
 # W-data format concept  
-Data set will consist of a set of files, for example:
+The data set will consist of a set of files, for example:
 ```bash
 test.wtxt           # metadata file, this one should be indicated when opening in VisIt
 test_density_a.wdat # binary file with data
 test_delta.wdat     # binary file with data
 test_current_a.wdat # binary file with data
 ```  
-Content of test.wtxt may look like:
+The content of test.wtxt may look like this:
 ```bash
 # Comments with additional  info about the data set
 # Comments are ignored when reading by the parser  
@@ -49,12 +51,12 @@ link              current_b               current_a
 const                    eF                     0.5                     MeV
 const                    kF                       1                    1/fm
 ```  
-According to our experience, three [types of variables](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/wikis/Data%20types) (`real`, `complex`, `vector`) are sufficient and cover more than 90% of applications. However, we have implemented a single-precision (`float` in C notation) types denoted as `real4`, `complex8` and `vector4`, to be consistent with the notation one can use `real8`, `complex16` or `vector8` exchangeable for `real`, `complex`, `vector`. 
+According to our experience, three [types of variables](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/wikis/Data%20types) (`real`, `complex`, `vector`) are sufficient and cover more than 90% of applications. However, we have implemented single-precision (`float` in C notation) types denoted as `real4`, `complex8`, and `vector4`. To be consistent with the notation, one can use `real8`, `complex16` or `vector8` exchangeable for `real`, `complex`, `vector`. 
 
-Binary files store data as row arrays, called datablocks:  
+Binary files store data as row arrays called `datablocks`:  
 ![datablocks](uploads/4d9d6260250707f665bda6e6c4e921cf/datablocks.png)
 
-The size of `datablock` depends on variable type and data dimensionality.  
+The size of `datablock` depends on the variable type and the data dimensionality.  
 * *real*/*real8*: `blocksize=blocklength*8 Bytes`  
 * *real4*: `blocksize=blocklength*4 Bytes`
 * *complex*/*complex16*: `blocksize=blocklength*16 Bytes`  
@@ -67,32 +69,45 @@ where `blocklength` is
 * for datadim=2: `blocklength=nx*ny`  
 * for datadim=1: `blocklength=nx`
 
-Note that for vector variables we use following storage pattern:   
+Note that for vector variables, we use the following storage pattern:   
 ![vecvar](uploads/39114e8349cccd7fb5f2f514dfcbfa77/vecvar.png)
 
-To compute time associated with given cycle we use the `wdata_set_time()` function. Which takes as parameters `wdata_metadata` struct, `icycle` current number of cycle, and `current_time` which will be calculated.
-!Note
-If `dt` is positive (to be precise, non negative) then we assume evenly distributed times, according to formula: `current_time=t0 + icycle*dt`. Hovewer if `dt` is negative then `current_time` parameter has to be calculated by the user and parsed to the function in which binary file is created and the value is stored. For more information see [Example](Examples/Write#t_varying).
+To compute time associated with a given `icycle`, we use the formula
+```
+time = t0 + dt * icycle;
+``` 
+If `dt` is negative then `time` parameter has to be extracted from the additional binary file of the name `prefix__t.wdat`. For more information, see the implementation of function [`wdata_get_time`(...)](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/blob/master/c/wdata.c#L562) from our C library.
 
 Let's get back to the `*wtxt` file.
 
 W-data format allows for the representation of the following elements:
 * *variable*:  
 Each variable is represented by the binary file of name `prefix_varname.format`. The variable description has the following format:  
-`var         name          type          unit         format`  
-Following formats are allowed:  
+```
+var         name          type          unit         format
+```
+The following formats are allowed:  
   * `wdat`: default format for WSLDA codes. Binary files contain row data (no header).
-  * `dpca`: (*deprecated*) previous format of cold atomic codes. Binary file contains header of size 68B where additional info about file content is stored. For this format *wdata* lib provides only reading functionality.  
+  * `dpca`: (*deprecated*) previous format of cold atomic codes. The binary file contains a header of size 68B where additional info about file content is stored. For this format, *wdata* lib provides only reading functionality.  
   * `npy`: binary files are *numpy* arrays. **Functionality under construction**   
-   In order to switch WSLDA codes to writing in this format add to input file:  
-   `dataformat           npy`
 * *link*:
-It is an alternative name for a given variable. In the case of `WSLDA` codes in many cases, we do the computation for systems that exhibit some symmetries, like spin symmetry. Then densities for spin-a and spin-b particles are exactly the same. In order to save disk space we can save only one of them:  
-`var         density_a             real              none           wdat`  
-and for another one set link:  
-`link        density_b        density_a`  
+It is an alternative name for a given variable. The entry has a form
+```
+link        alternative-name  var-name
+```
+Frequently, users call the same variable differently. For example, the user creates a variable
+```
+var         density             real              none           wdat
+```
+while another user, in his/her code, uses the name `rho` for the same variable. To maintain the operativity of the code that uses the variable `rho`, the second user can add an entry to `*wtxt` file as a form
+```
+link        rho        density
+```
 * *constant*:  
-Typically besides variables, we have some constants that are useful during the data analysis process. For example, when making plots it is convenient to express variables in dimensionless form, like delta/eF. To provide user info what are values of selected constants we use `const` field:  
-`const              eF              0.5`  
+Typically, besides variables, we have some useful constants during the data analysis process. 
+To provide values of selected constants, we use `const` field. For example:
+```
+const              eF              0.5
+```
 
-See [here](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/wikis/Tags) for complete list of tags. 
+See [here](https://gitlab.fizyka.pw.edu.pl/wtools/wdata/-/wikis/Tags) for a complete list of tags. 
\ No newline at end of file