Logger.md

-For reporting basic quantities (like particle number, energy, etc) W-SLDA code used `wlog` file. It is txt file produced by function `int logger( )` from [logger.h](https://gitlab.fizyka.pw.edu.pl/wtools/wslda/-/blob/public/st-project-template/logger.h) file.   This file can be modified by the user depending on a specifics of a given problem.  
+[[_TOC_]]
 
-# Example
-In addition to defined by default variables, the user needs to print out variable:  
+# Customizing wlog file
+For reporting basic quantities (like particle number, energy, etc) W-SLDA code uses `wlog` file. It is a txt file produced by the function `int logger( )` from [logger.h](https://gitlab.fizyka.pw.edu.pl/wtools/wslda/-/blob/public/st-project-template/logger.h) file.   The user can modify this file depending on the specifics of a given problem.  
+
+## Example
+Suppose that in addition to defined by default variables, the user needs to print out a new variable:  
 ```math
 \Delta_{\textrm{avg}}(t) = \dfrac{\int |\Delta(\bm{r},t)|(n_a(\bm{r},t)+n_b(\bm{r},t))\,d\bm{r}}{\int (n_a(\bm{r},t)+n_b(\bm{r},t))\,d\bm{r}}
 ```
-which is (weighted) average value of delta. This can be done by adding to `logger(..)`:
+In the first step, we define the new variable
+```c
+int add_custom_variable_to_wdata_metadata(wdata_metadata *wdmd,
+           double *params, size_t extra_data_size, void *extra_data)
+{
+    // To add a variable use this template
+    //                       var_name       type    unit
+    wdata_variable var1 = {"E_flow", "real", "none", "wdat"}; // scalar variable
+    wdata_add_variable(wdmd, &var1);
+
+    return 0;
+}
+```
+which is (weighted) average value of the delta. This can be done by adding to `logger(..)`:
 ```c
 int ixyz;
 int lNXYZ = h_potentials.blocklength;
@@ -14,7 +30,7 @@ for(ixyz=0; ixyz<lNXYZ; ixyz++) delta_avg+=cabs(h_potentials.delta[ixyz])*(h_den
 for(ixyz=0; ixyz<lNXYZ; ixyz++) Ntot+=h_densities.rho_a[ixyz]+h_densities.rho_b[ixyz];
 delta_avg /= Ntot;
 ```  
-and supplementing `printf` statement appropriate entry, like:
+and supplementing `printf` statement with appropriate entry, like:
 ```c
     // add entry
     fprintf(log, "%6d %18.10g %18.10g 
@@ -46,4 +62,67 @@ and supplementing `printf` statement appropriate entry, like:
         buffer
     );
 
+```
+
+# Customizing wdata files
+**Functionality introduced with API_VERSION>=20231218**
+
+The logger allows also to define new variables of results [W-data set](https://gitlab.fizyka.pw.edu.pl/wtools/wdata). It is done in two steps:
+1. Adding a definition of a new variable via `add_custom_variable_to_wdata_metadata` function.
+2. Adding a body of function `write_custom_variable_to_wdata_set` that creates and writes the new variable to wdata set. 
+
+## Example
+To demonstrate the functionality of extending wdata set by new variables, let us add new variable which is density of the flow energy
+```math
+E_{flow}(\bm{r}) = \frac{\bm{j}_a^2(\bm{r})}{2n_a(\bm{r})} + \frac{\bm{j}_b^2(\bm{r})}{2n_b(\bm{r})}
+```
+In the first step, we define the new variable with the name `E_flow`
+```c
+int add_custom_variable_to_wdata_metadata(wdata_metadata *wdmd,
+           double *params, size_t extra_data_size, void *extra_data)
+{
+    wdata_variable var1 = {"E_flow", "real", "none", "wdat"}; // scalar variable
+    wdata_add_variable(wdmd, &var1);
+
+    return 0;
+}
+```
+
+Next, we construct the variable and write it to the wdata set
+```c
+int write_custom_variable_to_wdata_set(wdata_metadata *wdmd,
+           int it,
+           wslda_density h_densities, wslda_potential h_potentials,
+           double kF, double *mu,
+           double *params, size_t extra_data_size, void *extra_data)
+{
+    // DETERMINE LOCAL SIZES OF ARRAYS (CODE DIMENSIONALITY DEPENDENT)
+    int lNX=h_densities.nx, lNY=h_densities.ny, lNZ=h_densities.nz; // local sizes
+    int ix, iy, iz, ixyz;
+
+    double *E_flow = (double *)malloc(lNX*lNY*lNZ*sizeof(double)); // allocate memory for the variable
+
+    // ITERATE OVER ALL POINTS
+    ixyz=0;
+    for(ix=0; ix<lNX; ix++) for(iy=0; iy<lNY; iy++) for(iz=0; iz<lNZ; iz++)
+    {
+        double x = DX*(ix-lNX/2);
+        double y = DY*(iy-lNY/2); // for 1d code y will be always 0
+        double z = DZ*(iz-lNZ/2); // for 1d and 2d codes z will be always 0
+
+        // construst the variable
+        double ja2 = pow(h_densities.j_a_x[ixyz],2) + pow(h_densities.j_a_y[ixyz],2) + pow(h_densities.j_a_z[ixyz],2);
+        double jb2 = pow(h_densities.j_b_x[ixyz],2) + pow(h_densities.j_b_y[ixyz],2) + pow(h_densities.j_b_z[ixyz],2);
+        E_flow[ixyz] = ja2 / (2.*h_densities.rho_a[ixyz]) + jb2 / (2.*h_densities.rho_b[ixyz]);
+
+        ixyz++; // go to the next point, it should be the last line of the triple loop
+    }
+
+    // to add variable to binary file use this function
+    wdata_write_cycle(wdmd, "E_flow", E_flow);
+
+    free(E_flow); // clear memory
+
+    return 0;
+}
 ```
\ No newline at end of file