Reference-scales.md

@@ -7,14 +7,17 @@ During the computation process, W-SLDA codes exploit information about typical s
 
 Other reference scales computed automatically from $`k_F`$ are:
 * $`\varepsilon_F=\frac{1}{2}k_F^2`$ - Fermi energy,
-* $`E_{\textrm{ffg}}=\frac{3}{5}N\varepsilon_F`$ - energy of free Fermi gas.  
+* $`E_{\textrm{ffg}}=c_E N\varepsilon_F`$ - energy of free Fermi gas, where the coefficient in front depends on dimensionality:
+  - $`c_E^{(1D)}=\frac{1}{3}`$,
+  - $`c_E^{(2D)}=\frac{1}{2}`$,
+  - $`c_E^{(3D)}=\frac{3}{5}`$.
 
 Finally, chemical potentials also serve as reference scales for static problems:  
 * $`\mu_{\uparrow}`$ - chemical potential is spin-up particles (particles of type `a`),
 * $`\mu_{\downarrow}`$ - chemical potential is spin-down particles (particles of type `b`).
 
 # Defining reference scales for static calculation 
-## Fermi momentum
+## Fermi momentum `kF`
 There are the following methods of  defining the $`k_F`$ reference scale: 
 * *via input file*: $`k_F`$ is provided by user in input file. To activate this mode you need to **uncomment** tag `referencekF`:     
 ```bash
@@ -54,7 +57,39 @@ double referencekF(int it, wslda_density h_densities, double *params, size_t ext
     return kF;
 }
 ```
-## Chemical potentials
+## Fermi energy `eF`
+Over the entire code, it is defined as $`\varepsilon_F=\frac{1}{2}k_F^2`$. 
+
+## Free Fermi gas energy `Effg`
+**API_VERSION>=20221120**  
+The quantity is used only for reporting values of the energy. The definition can be controlled via `logger.h` file, by changing the body of the function `energy_unit(...)`. Default values are computed as:
+```c
+/**
+ * This function defines the unit in which energies are printed in stdout.
+ * @param kF typical Fermi momentum scale of the problem, value returned by referencekF() function.
+ * @param mu array with chemical potentials: mu[SPINA], mu[SPINB].
+ * @param npart array with computed particle numbers: npart[SPINA] and npart[SPINB].
+ * @param params array of input parameters, before call of this routine the params array is processed by process_params() routine
+ * @param extra_data_size size of extra_data in bytes, if extra_data size=0 the optional data is not uploaded
+ * @param extra_data optional set of data uploaded by load_extra_data()
+ * */
+double energy_unit(double kF, double *mu, double *npart,
+           double *params, size_t extra_data_size, void *extra_data)
+{
+    double Effg;
+    double eF = kF*kF/2.0; // Fermi energy
+    double N = npart[SPINA]+npart[SPINB]; // total number of particles
+
+    // depending on dimensionality of the problem
+    if(NY==1 && NZ==1) Effg=(1./3.)*N*eF;   // 1D
+    else if(NZ==1)     Effg=(1./2.)*N*eF;   // 2D
+    else               Effg=(3./5.)*N*eF;   // 3D
+
+    return Effg;
+}
+```
+
+## Chemical potentials `mu`
 Chemical potentials are adjusted automatically when mode with fixed particle number is executed. For mode with fixed chemical potential see [here](Chemical potentials control). 
 
 ## Examples