Enhance docs

gusto/core/configuration.py

@@ -311,11 +311,11 @@ def check_options(self):
 
 
 def convert_parameters_to_real_space(parameters, mesh):
-    """Convert the float type parameters attributes to real space.
+    """Convert parameters to functions in real space.
 
     Args:
-        parameters (:class:`Configuration`): the configuration object containing
-            the parameters to convert
+        parameters (:class:`Configuration`): the configuration object
+        containing the parameters to convert
         mesh (:class:`firedrake.Mesh`): the mesh object to use for the real space.
     """
     R = FunctionSpace(mesh, 'R', 0)

gusto/equations/boussinesq_equations.py

@@ -106,9 +106,10 @@ def __init__(self, domain, parameters,
                          active_tracers=active_tracers)
 
         self.parameters = parameters
-        # This function converts the parameters to real space.
-        # This is a preventive way to avoid adjoint issues when the parameters
-        # attribute are the control in the sensitivity computations.
+        # Convert the attributes of type ``float`` or ``firedrake.Constant``
+        # in the parameters to a function in real space. This conversion is a
+        # preventive to avoid issues with adjoint computations, particularly
+        # when the parameters  are used as controls in sensitivity analyses.
         convert_parameters_to_real_space(parameters, domain.mesh)
         self.compressible = compressible
 

gusto/equations/compressible_euler_equations.py

@@ -101,9 +101,10 @@ def __init__(self, domain, parameters, sponge_options=None,
                          active_tracers=active_tracers)
 
         self.parameters = parameters
-        # This function converts the parameters to real space.
-        # This is a preventive way to avoid adjoint issues when the parameters
-        # attribute are the control in the sensitivity computations.
+        # Convert the attributes of type ``float`` or ``firedrake.Constant``
+        # in the parameters to a function in real space. This conversion is a
+        # preventive to avoid issues with adjoint computations, particularly
+        # when the parameters  are used as controls in sensitivity analyses.
         convert_parameters_to_real_space(parameters, domain.mesh)
         g = parameters.g
         cp = parameters.cp

gusto/equations/shallow_water_equations.py

@@ -88,10 +88,10 @@ def __init__(self, domain, parameters, fexpr=None, topog_expr=None,
 
         self.parameters = parameters
         self.domain = domain
-        # This function converts the ``float`` and ``firedrake.Constant`` parameters
-        # attributes to a function in real space.
-        # This is a preventive way to avoid adjoint issues when the parameters
-        # attribute are the control in the sensitivity computations.
+        # Convert the attributes of type ``float`` or ``firedrake.Constant``
+        # in the parameters to a function in real space. This conversion is a
+        # preventive to avoid issues with adjoint computations, particularly
+        # when the parameters  are used as controls in sensitivity analyses.
         convert_parameters_to_real_space(parameters, self.domain.mesh)
         self.active_tracers = active_tracers
 
@@ -424,10 +424,7 @@ def _setup_residual(self, fexpr, topog_expr, u_transport_option):
         # label these as the equivalent pressure gradient term and
         # provide linearisation
         if self.equivalent_buoyancy:
-            try:
-                beta2 = self.parameters.beta2
-            except ValueError:
-                print("Oi")
+            beta2 = self.parameters.beta2
 
             qsat_expr = self.compute_saturation(self.X)
             qv = conditional(qt < qsat_expr, qt, qsat_expr)
@@ -658,9 +655,10 @@ def __init__(self, domain, parameters,
                          active_tracers=active_tracers)
 
         self.parameters = parameters
-        # This function converts the parameters to real space.
-        # This is a preventive way to avoid adjoint issues when the parameters
-        # attribute are the control in the sensitivity computations.
+        # Convert the attributes of type ``float`` or ``firedrake.Constant``
+        # in the parameters to a function in real space. This conversion is a
+        # preventive to avoid issues with adjoint computations, particularly
+        # when the parameters  are used as controls in sensitivity analyses.
         convert_parameters_to_real_space(parameters, domain.mesh)
         g = parameters.g
         H = parameters.H