From 777bf8511ac355113c4bae4d625e24b247ace00c Mon Sep 17 00:00:00 2001
From: Sjoerd Bouma <sjoerdbouma@xs4all.nl>
Date: Thu, 21 Nov 2024 10:06:39 +0100
Subject: [PATCH] Do not use refractive index of ice at LOFAR/Auger

---
 NuRadioMC/utilities/medium.py                 |  8 +++
 NuRadioReco/utilities/ice.py                  | 51 +++++++++++++++++--
 .../NuRadioMC/pages/Manuals/icemodels.rst     |  2 +-
 3 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/NuRadioMC/utilities/medium.py b/NuRadioMC/utilities/medium.py
index e886a0e67..b3ce82d36 100644
--- a/NuRadioMC/utilities/medium.py
+++ b/NuRadioMC/utilities/medium.py
@@ -1,3 +1,11 @@
+"""
+Module providing the ice models in NuRadioMC.
+
+For more details on the implementation, and the available modules,
+see the documentation :doc:`here </NuRadioMC/pages/Manuals/icemodels>`.
+
+"""
+
 from NuRadioMC.utilities import medium_base
 import itertools
 import numpy as np
diff --git a/NuRadioReco/utilities/ice.py b/NuRadioReco/utilities/ice.py
index 9597a86ad..8f211e9ce 100644
--- a/NuRadioReco/utilities/ice.py
+++ b/NuRadioReco/utilities/ice.py
@@ -1,11 +1,52 @@
-
 """
-implementation of ice models
+(old) implementation of ice models
+
+Only returns one of two values depending on whether the depth is below
+or above 0 (assumed to be the ice-air) interface.
+
+.. Warning::
+    This function is used internally in some modules, but should not
+    be used in new user code. Please use the `NuRadioMC.utilities.medium`
+    module instead
+
 """
+import logging
 
+logger = logging.getLogger('NuRadioReco.utilities.ice')
 
 def get_refractive_index(depth, site='southpole'):
-    if(depth <= 0):
-        return 1.3
-    else:
+    """
+    Get refractive index for depth
+
+    For sites that are not at the poles, always returns the refractive index
+    of air (1.000293). Otherwise, returns 1.3
+
+    .. Warning::
+        This function is only used internally. New user code should
+        use the ice models in `NuRadioMC.utilities.medium` instead
+
+    Parameters
+    ----------
+    depth : float
+        The depth
+    site : str, optional
+        The site to use. For sites on land (not in-ice),
+        the refractive index returned is always that for air.
+
+    Returns
+    -------
+    n : float
+        The refractive index. For land-based sites,
+        this is always n_air=1.000293; for in-ice sites,
+        returns n_ice=1.3 or n_air depending on the depth.
+
+    """
+    if site.lower() in ['lofar', 'auger']:
         return 1.000293
+    else:
+        if not site.lower() in ['southpole', 'mooresbay', 'summit']:
+            logger.warning(f"site '{site}' unknown, assuming in-ice detector")
+        if(depth <= 0):
+            return 1.3
+        else:
+            return 1.000293
\ No newline at end of file
diff --git a/documentation/source/NuRadioMC/pages/Manuals/icemodels.rst b/documentation/source/NuRadioMC/pages/Manuals/icemodels.rst
index 8fafbdb1e..9987d6596 100644
--- a/documentation/source/NuRadioMC/pages/Manuals/icemodels.rst
+++ b/documentation/source/NuRadioMC/pages/Manuals/icemodels.rst
@@ -114,7 +114,7 @@ _________________
 In the table below we can find the different parameters for the simple ice refractive index models available in NuRadioMC.
 
     .. csv-table:: Simple Ice Models
-        :header: "Name", ":math:`n_{ice}`", ":math:`\Delta_n`", ":math:`z_0$ [m]`"
+        :header: "Name", ":math:`n_{ice}`", ":math:`\Delta_n`", ":math:`z_0 [m]`"
 
         `southpole_simple <https://iopscience.iop.org/article/10.1088/1475-7516/2018/07/055>`__ (RICE2014/SP), 1.78, 0.425, 71
         `southpole_2015 <https://iopscience.iop.org/article/10.1088/1475-7516/2018/07/055>`__ (SPICE2015/SP), 1.78, 0.423, 77