Stop the mesh factories recommending a deprecated, broken API (#538)

src/underworld3/meshing/annulus.py

@@ -265,7 +265,10 @@ class boundary_normals(Enum):
         Right = new_mesh.CoordinateSystem.unit_e_1
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     return new_mesh
 
@@ -537,7 +540,10 @@ class boundary_normals(Enum):
         Upper = new_mesh.CoordinateSystem.unit_e_0
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     # Full annulus: rigid rotation about z-axis
     x, y = new_mesh.X
@@ -790,7 +796,10 @@ class boundary_normals(Enum):
         Upper = new_mesh.CoordinateSystem.unit_e_0
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     return new_mesh
 
@@ -1120,7 +1129,10 @@ class boundary_normals(Enum):
         )
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     # Full annulus with spokes: rigid rotation about z-axis
     x, y = new_mesh.X
@@ -1715,7 +1727,10 @@ class boundary_normals(Enum):
         Internal = new_mesh.CoordinateSystem.unit_e_0
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     # Full disc with internal boundaries: rigid rotation about z-axis
     x, y = new_mesh.X

src/underworld3/meshing/geographic.py

@@ -402,7 +402,10 @@ class boundary_normals(Enum):
             sympy.Piecewise((1.0, new_mesh.CoordinateSystem.R[0] > 0.99 * radiusOuter), (0.0, True))
         )
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     return new_mesh
 
@@ -840,6 +843,9 @@ class boundary_normals(Enum):
         East = new_mesh.CoordinateSystem.geo.unit_east  # Eastward at east boundary
         West = new_mesh.CoordinateSystem.geo.unit_west  # Westward at west boundary
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     return new_mesh

src/underworld3/meshing/segmented.py

@@ -675,7 +675,10 @@ class boundary_normals(Enum):
         )
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     # Full segmented spherical shell: 3 rigid rotation modes
     x, y, z = new_mesh.X
@@ -1094,7 +1097,10 @@ class boundary_normals(Enum):
         )
         Centre = None
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     # Solid sphere: 3 rigid rotation modes
     x, y, z = new_mesh.X

src/underworld3/meshing/spherical.py

@@ -1351,7 +1351,10 @@ class boundary_normals(Enum):
         Lower = new_mesh.CoordinateSystem.unit_e_0
         Upper = new_mesh.CoordinateSystem.unit_e_0
 
-    # boundary_normals deprecated — use mesh.Gamma_P1 for boundary normals
+    # boundary_normals deprecated — use mesh.Gamma inside integrands and BCs,
+    # or mesh.boundary_normal(boundary) for a per-boundary P1 normal field.
+    # NOT mesh.Gamma_P1: it is deprecated too, and off-kernel it falls back to
+    # a coordinate direction rather than a normal (#538).
 
     # Full cubed sphere: 3 rigid rotation modes
     x, y, z = new_mesh.X