Merge pull request #24 from paulromano/classmethod-naming

Adopt `from_*` naming convention for classmethods

README.md

@@ -69,11 +69,11 @@ for _ in range(3):
 solids = solids[1:]
 
 geometry = sm.Geometry(solids, material_names=["a", "a", "c"])
-mesh = sm.Mesh.mesh_geometry(geometry, min_mesh_size=50, max_mesh_size=50)
+mesh = sm.Mesh.from_geometry(geometry, min_mesh_size=50, max_mesh_size=50)
 mesh.write("test.msh")
 mesh.render("doc/torus-mesh-reversed.png", rotation_xyz=(90, 0, -90), normals=15)
 
-h5m = sm.MOABModel.make_from_mesh(mesh)
+h5m = sm.MOABModel.from_mesh(mesh)
 h5m.write("dagmc.h5m")
 h5m.write("dagmc.vtk")
 ```

examples/layered-torus.py

@@ -12,10 +12,10 @@
 solids = solids[1:]
 
 geometry = sm.Geometry(solids[::-1], material_names=["a", "a", "c"])
-mesh = sm.Mesh.mesh_geometry(geometry, min_mesh_size=50, max_mesh_size=50)
+mesh = sm.Mesh.from_geometry(geometry, min_mesh_size=50, max_mesh_size=50)
 mesh.write("test.msh")
 mesh.render("doc/torus-mesh-reversed.png", rotation_xyz=(90, 0, -90), normals=15)
 
-h5m = sm.MOABModel.make_from_mesh(mesh)
+h5m = sm.MOABModel.from_mesh(mesh)
 h5m.write("dagmc.h5m")
 h5m.write("dagmc.vtk")

examples/mesh-refinement.py

@@ -20,6 +20,6 @@
     bd.sweep()
 
 geom = sm.Geometry(my_part.solids(), material_names=["hi"])
-mesh = sm.Mesh.mesh_geometry(geom, min_mesh_size=0.5, max_mesh_size=0.5)
+mesh = sm.Mesh.from_geometry(geom, min_mesh_size=0.5, max_mesh_size=0.5)
 refined_mesh = mesh.refine(const_mesh_size=1, hausdorff_value=100)
 refined_mesh.write("refined.msh")

examples/stellarmesh-logo.py

@@ -10,5 +10,5 @@
 solids = [f.thicken(10) for f in cmp.faces()]
 
 geometry = sm.Geometry(solids, [""] * len(solids))
-mesh = sm.Mesh.mesh_geometry(geometry, min_mesh_size=1, max_mesh_size=2)
+mesh = sm.Mesh.from_geometry(geometry, min_mesh_size=1, max_mesh_size=2)
 mesh.render("doc/logo.png", rotation_xyz=(0, -2, 0), clipping=False)

src/stellarmesh/geometry.py

@@ -5,7 +5,10 @@
 
 desc: Geometry class represents a CAD geometry to be meshed.
 """
+from __future__ import annotations
+
 import logging
+import warnings
 from typing import Sequence, Union
 
 from OCP.BOPAlgo import BOPAlgo_MakeConnected
@@ -73,14 +76,14 @@ def _solids_from_shape(shape: TopoDS_Shape) -> list[TopoDS_Solid]:
                 explorer.Next()
         return solids
 
-    # TODO(akoen): import_step and import_brep are not DRY
+    # TODO(akoen): from_step and from_brep are not DRY
     # https://github.com/Thea-Energy/stellarmesh/issues/2
     @classmethod
-    def import_step(
+    def from_step(
         cls,
         filename: str,
         material_names: Sequence[str],
-    ) -> "Geometry":
+    ) -> Geometry:
         """Import model from a step file.
 
         Args:
@@ -107,11 +110,33 @@ def import_step(
         return cls(solids, material_names)
 
     @classmethod
-    def import_brep(
+    def import_step(
+        cls,
+        filename: str,
+        material_names: Sequence[str],
+    ) -> Geometry:
+        """Import model from a step file.
+
+        Args:
+            filename: File path to import.
+            material_names: Ordered list of material names matching solids in file.
+
+        Returns:
+            Model.
+        """
+        warnings.warn(
+            "The import_step method is deprecated. Use from_step instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return cls.from_step(filename, material_names)
+
+    @classmethod
+    def from_brep(
         cls,
         filename: str,
         material_names: Sequence[str],
-    ) -> "Geometry":
+    ) -> Geometry:
         """Import model from a brep (cadquery, build123d native) file.
 
         Args:
@@ -134,7 +159,29 @@ def import_brep(
         logger.info(f"Importing {len(solids)} from {filename}")
         return cls(solids, material_names)
 
-    def imprint(self) -> "Geometry":
+    @classmethod
+    def import_brep(
+        cls,
+        filename: str,
+        material_names: Sequence[str],
+    ) -> Geometry:
+        """Import model from a brep (cadquery, build123d native) file.
+
+        Args:
+            filename: File path to import.
+            material_names: Ordered list of material names matching solids in file.
+
+        Returns:
+            Model.
+        """
+        warnings.warn(
+            "The import_brep method is deprecated. Use from_brep instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return cls.from_brep(cls, filename, material_names)
+
+    def imprint(self) -> Geometry:
         """Imprint faces of current geometry.
 
         Returns:

src/stellarmesh/mesh.py

@@ -5,9 +5,12 @@
 
 desc: Mesh class wraps Gmsh functionality for geometry meshing.
 """
+from __future__ import annotations
+
 import logging
 import subprocess
 import tempfile
+import warnings
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Optional
@@ -73,13 +76,13 @@ def write(self, filename: str, *, save_all: bool = True):
             gmsh.write(filename)
 
     @classmethod
-    def mesh_geometry(
+    def from_geometry(
         cls,
         geometry: Geometry,
         min_mesh_size: float = 50,
         max_mesh_size: float = 50,
         dim: int = 2,
-    ):
+    ) -> Mesh:
         """Mesh solids with Gmsh.
 
         See Gmsh documentation on mesh sizes:
@@ -120,6 +123,32 @@ def mesh_geometry(
             mesh._save_changes(save_all=True)
             return mesh
 
+    @classmethod
+    def mesh_geometry(
+        cls,
+        geometry: Geometry,
+        min_mesh_size: float = 50,
+        max_mesh_size: float = 50,
+        dim: int = 2,
+    ) -> Mesh:
+        """Mesh solids with Gmsh.
+
+        See Gmsh documentation on mesh sizes:
+        https://gmsh.info/doc/texinfo/gmsh.html#Specifying-mesh-element-sizes
+
+        Args:
+            geometry: Geometry to be meshed.
+            min_mesh_size: Min mesh element size. Defaults to 50.
+            max_mesh_size: Max mesh element size. Defaults to 50.
+            dim: Generate a mesh up to this dimension. Defaults to 2.
+        """
+        warnings.warn(
+            "The mesh_geometry method is deprecated. Use from_geometry instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return cls.from_geometry(geometry, min_mesh_size, max_mesh_size, dim)
+
     def render(
         self,
         output_filename: Optional[str] = None,
@@ -199,7 +228,7 @@ def refine(  # noqa: PLR0913
         hausdorff_value: float = 0.01,
         gradation_value: float = 1.3,
         optim: bool = False,
-    ) -> "Mesh":
+    ) -> Mesh:
         """Refine mesh using mmgs.
 
         See mmgs documentation:

src/stellarmesh/moab.py

@@ -5,9 +5,12 @@
 
 desc: MOABModel class represents a MOAB model.
 """
+from __future__ import annotations
+
 import logging
 import subprocess
 import tempfile
+import warnings
 from dataclasses import dataclass, field
 
 import gmsh
@@ -33,7 +36,7 @@ class MOABSurface(_MOABEntity):
     """MOAB surface entity."""
 
     @property
-    def adjacent_volumes(self) -> list["MOABVolume"]:
+    def adjacent_volumes(self) -> list[MOABVolume]:
         """Get adjacent volumes.
 
         Returns:
@@ -47,7 +50,7 @@ class MOABVolume(_MOABEntity):
     """MOAB volume entity."""
 
     @property
-    def adjacent_surfaces(self) -> list["MOABSurface"]:
+    def adjacent_surfaces(self) -> list[MOABSurface]:
         """Get adjacent surfaces.
 
         Returns:
@@ -89,7 +92,7 @@ def __init__(self, core: pymoab.core.Core):
         self._core = core
 
     @classmethod
-    def read_file(cls, h5m_file: str) -> "MOABModel":
+    def from_h5m(cls, h5m_file: str) -> MOABModel:
         """Initialize model from .h5m file.
 
         Args:
@@ -102,6 +105,23 @@ def read_file(cls, h5m_file: str) -> "MOABModel":
         core.load_file(h5m_file)
         return cls(core)
 
+    @classmethod
+    def read_file(cls, h5m_file: str) -> MOABModel:
+        """Initialize model from .h5m file.
+
+        Args:
+            h5m_file: File to load.
+
+        Returns:
+            Initialized model.
+        """
+        warnings.warn(
+            "The read_file method is deprecated. Use from_h5m instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return cls.from_h5m(h5m_file)
+
     def write(self, filename: str):
         """Write MOAB model to .h5m, .vtk, or other file.
 
@@ -184,15 +204,14 @@ def _get_moab_tag_handles(core: pymoab.core.Core) -> dict[str, np.uint64]:
         return tag_handles
 
     @classmethod
-    def make_from_mesh(  # noqa: PLR0915
+    def from_mesh(  # noqa: PLR0915
         cls,
         mesh: Mesh,
-    ):
+    ) -> MOABModel:
         """Compose DAGMC MOAB .h5m file from mesh.
 
         Args:
             mesh: Mesh from which to build DAGMC geometry.
-            filename: Filename of the output .h5m file.
         """
         core = pymoab.core.Core()
 
@@ -303,14 +322,28 @@ def make_from_mesh(  # noqa: PLR0915
 
             return cls(core)
 
+    @classmethod
+    def make_from_mesh(cls, mesh: Mesh) -> MOABModel:
+        """Compose DAGMC MOAB .h5m file from mesh.
+
+        Args:
+            mesh: Mesh from which to build DAGMC geometry.
+        """
+        warnings.warn(
+            "The make_from_mesh method is deprecated. Use from_mesh instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        return cls.from_mesh(mesh)
+
     def _get_entities_of_geom_dimension(self, dim: int) -> list[np.uint64]:
         dim_tag = self._core.tag_get_handle(pymoab.types.GEOM_DIMENSION_TAG_NAME)
         return self._core.get_entities_by_type_and_tag(
             0, pymoab.types.MBENTITYSET, dim_tag, [dim]
         )
 
     @property
-    def surfaces(self):
+    def surfaces(self) -> list[MOABSurface]:
         """Get surfaces in this model.
 
         Returns:
@@ -320,7 +353,7 @@ def surfaces(self):
         return [MOABSurface(self._core, h) for h in surface_handles]
 
     @property
-    def volumes(self):
+    def volumes(self) -> list[MOABVolume]:
         """Get volumes in this model.
 
         Returns:

tests/test_geometry.py

@@ -51,26 +51,26 @@ def test_geometry_init_wrong_materials(geom_bd_layered_torus):
 
 def test_step_import_compound(geom_bd_layered_torus):
     bd.Compound.make_compound(geom_bd_layered_torus).export_step("model.step")
-    sm.Geometry.import_step("model.step", material_names=[""] * 3)
+    sm.Geometry.from_step("model.step", material_names=[""] * 3)
     with pytest.raises(ValueError):
-        sm.Geometry.import_step("model.step", material_names=[""] * 2)
+        sm.Geometry.from_step("model.step", material_names=[""] * 2)
 
 
 def test_step_import_solid(geom_bd_layered_torus):
     geom_bd_layered_torus[0].export_step("layer.step")
-    sm.Geometry.import_step("layer.step", material_names=[""])
+    sm.Geometry.from_step("layer.step", material_names=[""])
 
 
 def test_brep_import_compound(geom_bd_layered_torus):
     bd.Compound.make_compound(geom_bd_layered_torus).export_brep("model.brep")
-    sm.Geometry.import_brep("model.brep", material_names=[""] * 3)
+    sm.Geometry.from_brep("model.brep", material_names=[""] * 3)
     with pytest.raises(ValueError):
-        sm.Geometry.import_brep("model.brep", material_names=[""] * 2)
+        sm.Geometry.from_brep("model.brep", material_names=[""] * 2)
 
 
 def test_brep_import_solid(geom_bd_layered_torus):
     geom_bd_layered_torus[0].export_brep("layer.brep")
-    sm.Geometry.import_brep("layer.brep", material_names=[""])
+    sm.Geometry.from_brep("layer.brep", material_names=[""])
 
 
 def test_geometry_imprint(geom_bd_layered_torus):

tests/test_mesh.py

@@ -10,8 +10,8 @@ def geom_bd_sphere():
 
 
 def test_mesh_geometry_2d(geom_bd_sphere):
-    sm.Mesh.mesh_geometry(geom_bd_sphere, 5, 5, dim=2)
+    sm.Mesh.from_geometry(geom_bd_sphere, 5, 5, dim=2)
 
 
 def test_mesh_geometry_3d(geom_bd_sphere):
-    sm.Mesh.mesh_geometry(geom_bd_sphere, 5, 5, dim=3)
+    sm.Mesh.from_geometry(geom_bd_sphere, 5, 5, dim=3)