From be0f3965ba072cd8326bb3cf41ab108d782474e7 Mon Sep 17 00:00:00 2001
From: robinzyb <38876805+robinzyb@users.noreply.github.com>
Date: Sat, 14 Dec 2024 13:09:46 +0100
Subject: [PATCH] update doc for macro average

---
 cp2kdata/cube/cube.py       |  4 ++++
 docs/cube/README.md         |  7 ++++---
 jupyter-book/references.bib | 15 +++++++++++++++
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/cp2kdata/cube/cube.py b/cp2kdata/cube/cube.py
index 68d53fb..90ab9ab 100644
--- a/cp2kdata/cube/cube.py
+++ b/cp2kdata/cube/cube.py
@@ -149,6 +149,10 @@ def get_pav(self, axis='z', interpolate=False):
             return points, vals
 
     def get_mav(self, l1, l2=0, ncov=1, interpolate=False, axis="z"):
+        """
+        Get marcoaverage of the cube file
+        """
+
         cell_length = {
             "x": self.cell.get_cell_lengths()[0],
             "y": self.cell.get_cell_lengths()[1],
diff --git a/docs/cube/README.md b/docs/cube/README.md
index 78c557d..06b13d6 100644
--- a/docs/cube/README.md
+++ b/docs/cube/README.md
@@ -71,14 +71,15 @@ pav_x, pav = mycube.get_pav(axis="z", interpolate=True)
 ```
 
 ## Macro Averaging
-The `get_mav()` method allows you to compute macro average data with or without interpolation. Specify the length of the first and second periodicity (l1 and l2) and the system type (ncov) as parameters:
+The `get_mav()` method allows you to compute macro average data with or without interpolation.
+The method `get_mav()` is usually used for determining the electrostatic potential difference across two materials.cite`{Junquera.Rabe.2007.10.1088/0953-8984/19/21/213203}` Assume you have an atomic model of a heterojunction with SiO2 and Si with the interface normal to the `z` axis.  You can specify the length of the first and second periodicity (l1 and l2) for SiO2 and Si. The periodicity can be determined from their interlayer distances normal to the `z` axis. In practice, it is recommended to set periodicity to double minimum interlayer distances to obtain better plateau in the bulk regions of the materials. The `ncov` means the types of systems. `ncov=1` indicates one material with vacuum. In this case, `l2` can be None. `ncov=2` indicates two materials in the box, for example, the SiO2 and Si heterojunction. `l1` and `l2` are set to the periodicity of the two materials, respectively.
 
 ```python
 # Get macro average data without interpolation
-mav_x, mav = mycube.get_mav(l1=4.8, l2=4.8, ncov=1, interpolate=False)
+mav_x, mav = mycube.get_mav(l1=4.8, l2=4.8, ncov=1, interpolate=False, axis='z')
 
 # Get macro average data with interpolation
-mav_x, mav = mycube.get_mav(l1=4.8, l2=4.8, ncov=2, interpolate=True)
+mav_x, mav = mycube.get_mav(l1=4.8, l2=4.8, ncov=2, interpolate=True,  axis='z')
 
 ```
 
diff --git a/jupyter-book/references.bib b/jupyter-book/references.bib
index f9b78d1..0a34942 100644
--- a/jupyter-book/references.bib
+++ b/jupyter-book/references.bib
@@ -9,4 +9,19 @@ @article{wong2010points
   pages={573},
   year={2010},
   publisher={Nature Publishing Group}
+}
+
+
+@article{Junquera.Rabe.2007.10.1088/0953-8984/19/21/213203,
+year = {2007},
+title = {{Nanoscale smoothing and the analysis of interfacial charge and dipolar densities}},
+author = {Junquera, Javier and Cohen, Morrel H and Rabe, Karin M},
+journal = {Journal of Physics: Condensed Matter},
+issn = {0953-8984},
+doi = {10.1088/0953-8984/19/21/213203},
+eprint = {cond-mat/0701146},
+pages = {213203},
+number = {21},
+volume = {19},
+keywords = {},
 }
\ No newline at end of file