Add some more docstrings

Author: danshapero

src/icepack2/model/minimization.py

@@ -20,7 +20,7 @@
 
 
 def viscous_power(**kwargs):
-    r"""Return the viscous power dissipation"""
+    r"""Return the symbolic form of the viscous power dissipation rate"""
     # Get all the dynamical fields
     field_names = ("membrane_stress", "thickness")
     M, h = map(kwargs.get, field_names)
@@ -38,7 +38,7 @@ def viscous_power(**kwargs):
 
 
 def friction_power(**kwargs):
-    r"""Return the frictional power dissipation"""
+    r"""Return the symbolic form of the frictional power dissipation rate"""
     τ = kwargs["basal_stress"]
     parameter_names = ("sliding_coefficient", "sliding_exponent")
     K, m = map(kwargs.get, parameter_names)
@@ -48,7 +48,8 @@ def friction_power(**kwargs):
 
 
 def calving_terminus(**kwargs):
-    r"""Return the power dissipation from the terminus boundary condition"""
+    r"""Return the symbolic form of the power dissipation at the terminus
+    of a glacier that flows into a water body"""
     # Get all the dynamical fields and boundary conditions
     u, h, s = map(kwargs.get, ("velocity", "thickness", "surface"))
     outflow_ids = kwargs["outflow_ids"]
@@ -67,7 +68,7 @@ def calving_terminus(**kwargs):
 
 
 def momentum_balance(**kwargs):
-    r"""Return the momentum balance constraint"""
+    r"""Return the symbolic form of the momentum balance constraint"""
     field_names = (
         "velocity", "membrane_stress", "basal_stress", "thickness", "surface"
     )
@@ -84,7 +85,8 @@ def momentum_balance(**kwargs):
 
 
 def ice_shelf_momentum_balance(**kwargs):
-    r"""Return the momentum balance constraint for floating ice shelves
+    r"""Return the symbolic form of the momentum balance constraint for the
+    special case of floating ice shelves in hydrostatic balance
 
     Floating ice shelves are simpler because there is no basal shear stress
     and we assume the ice is hydrostatic, in which case the surface

src/icepack2/model/variational.py

@@ -20,6 +20,8 @@
 
 
 def flow_law(**kwargs):
+    r"""Return the symbolic form of the flow law, i.e. the relation between the
+    strain rate and membrane stress tensors"""
     field_names = ("thickness", "membrane_stress", "velocity", "test_function")
     h, M, u, N = map(kwargs.get, field_names)
     A, n = map(kwargs.get, ("flow_law_coefficient", "flow_law_exponent"))
@@ -34,6 +36,8 @@ def flow_law(**kwargs):
 
 
 def friction_law(**kwargs):
+    r"""Return the symbolic form of the sliding law, i.e. the relation between
+    the basal sliding velocity and the basal drag vectors"""
     τ, u, σ = map(kwargs.get, ("basal_stress", "velocity", "test_function"))
     K, m = map(kwargs.get, ("sliding_coefficient", "sliding_exponent"))
     τ_2 = inner(τ, τ)
@@ -42,6 +46,8 @@ def friction_law(**kwargs):
 
 
 def calving_terminus(**kwargs):
+    r"""Return the symbolic form of the pressure exerted at the terminus of a
+    glacier that flows into a water body"""
     h, s, v = map(kwargs.get, ("thickness", "surface", "test_function"))
     outflow_ids = kwargs["outflow_ids"]
 
@@ -58,6 +64,7 @@ def calving_terminus(**kwargs):
 
 
 def momentum_balance(**kwargs):
+    r"""Return the symbolic form of the constraint of momentum balance"""
     field_names = (
         "membrane_stress",
         "basal_stress",
@@ -78,6 +85,12 @@ def momentum_balance(**kwargs):
 
 
 def ice_shelf_momentum_balance(**kwargs):
+    r"""Return the symbolic form of the constraint of momentum balance for the
+    special case of floating ice shelves in hydrostatic balance
+
+    Floating ice shelves are simpler because there is no basal shear stress
+    and we assume the ice is hydrostatic, in which case the surface
+    elevation is proportional to the thickness."""
     field_names = ("membrane_stress", "thickness", "test_function")
     M, h, v = map(kwargs.get, field_names)
     ε = sym(grad(v))