refactor: Populate pydrex namespace and adjust some symbol names

src/pydrex/__init__.py

@@ -115,6 +115,10 @@
 
 """
 
+# Set up the top-level pydrex namespace for convenient usage.
+# To keep it clean, we don't want every single symbol here, especially not those from
+# `utils` or `visualisation` modules, which should be explicitly imported instead.
+import pydrex.axes  # Defines the 'pydrex.polefigure' Axes subclass.
 from pydrex.core import (
     DeformationRegime,
     MineralFabric,
@@ -125,24 +129,42 @@
 from pydrex.diagnostics import (
     bingham_average,
     coaxial_index,
+    elasticity_components,
     finite_strain,
     misorientation_index,
     misorientation_indices,
     smallest_angle,
-    symmetry,
+    symmetry_pgr,
 )
 from pydrex.geometry import (
+    LatticeSystem,
     lambert_equal_area,
     misorientation_angles,
     poles,
     shirley_concentric_squaredisk,
+    symmetry_operations,
     to_cartesian,
     to_spherical,
 )
+from pydrex.io import DEFAULT_PARAMS, data, read_scsv, save_scsv
 from pydrex.minerals import (
+    OLIVINE_PRIMARY_AXIS,
     OLIVINE_SLIP_SYSTEMS,
     OLIVINE_STIFFNESS,
     Mineral,
     voigt_averages,
 )
-from pydrex.stats import resample_orientations
+from pydrex.pathlines import get_pathline
+from pydrex.stats import (
+    misorientation_hist,
+    misorientations_random,
+    resample_orientations,
+)
+from pydrex.tensors import (
+    elastic_tensor_to_voigt,
+    rotate,
+    voigt_decompose,
+    voigt_matrix_to_vector,
+    voigt_to_elastic_tensor,
+    voigt_vector_to_matrix,
+)

src/pydrex/cli.py

@@ -1,4 +1,9 @@
-"""> PyDRex: Entry points for command line tools."""
+"""> PyDRex: Entry points and argument handling for command line tools.
+
+All CLI handlers should be registered in the `CLI_HANDLERS` namedtuple,
+which ensures that they will be installed as executable scripts alongside the package.
+
+"""
 
 import argparse
 import os
@@ -13,8 +18,6 @@
 from pydrex import stats as _stats
 from pydrex import visualisation as _vis
 
-# NOTE: Register all cli handlers in the namedtuple at the end of the file.
-
 
 @dataclass
 class NPZFileInspector:

src/pydrex/diagnostics.py

@@ -226,7 +226,7 @@ def finite_strain(deformation_gradient, driver="ev"):
     return np.sqrt(B_λ[-1]) - 1, B_v[:, -1]
 
 
-def symmetry(orientations, axis="a"):
+def symmetry_pgr(orientations, axis="a"):
     r"""Compute texture symmetry eigenvalue diagnostics from grain orientation matrices.
 
     Compute Point, Girdle and Random symmetry diagnostics

src/pydrex/io.py

@@ -284,7 +284,7 @@ def parse_config(path):
 
     # Input option 1: velocity gradient mesh + final particle locations.
     if "mesh" in _input:
-        _input["mesh"] = read_mesh(resolve_path(_input["mesh"], path.parent))
+        _input["mesh"] = meshio.read(resolve_path(_input["mesh"], path.parent))
         _input["locations_final"] = read_scsv(
             resolve_path(_input["locations_final"], path.parent)
         )
@@ -401,11 +401,6 @@ def parse_config(path):
     return toml
 
 
-def read_mesh(meshfile, *args, **kwargs):
-    """Wrapper of `meshio.read`, see <https://github.com/nschloe/meshio>."""
-    return meshio.read(resolve_path(meshfile), *args, **kwargs)
-
-
 def resolve_path(path, refdir=None):
     """Resolve relative paths and create parent directories if necessary.
 

src/pydrex/logger.py

@@ -94,11 +94,11 @@ def format(self, record):
 # To allow for multiple handlers at different levels, default level must be DEBUG.
 LOGGER.setLevel(logging.DEBUG)
 # Set up console handler.
-LOGGER_CONSOLE = logging.StreamHandler()
-LOGGER_CONSOLE.setFormatter(ConsoleFormatter(datefmt="%H:%M"))
-LOGGER_CONSOLE.setLevel(logging.INFO)
+CONSOLE_LOGGER = logging.StreamHandler()
+CONSOLE_LOGGER.setFormatter(ConsoleFormatter(datefmt="%H:%M"))
+CONSOLE_LOGGER.setLevel(logging.INFO)
 # Turn on console logger by default.
-LOGGER.addHandler(LOGGER_CONSOLE)
+LOGGER.addHandler(CONSOLE_LOGGER)
 
 
 def handle_exception(exec_type, exec_value, exec_traceback):
@@ -117,14 +117,14 @@ def handle_exception(exec_type, exec_value, exec_traceback):
 
 
 @cl.contextmanager
-def handler_level(level, handler=LOGGER_CONSOLE):
+def handler_level(level, handler=CONSOLE_LOGGER):
     """Set logging handler level for current context.
 
     Args:
     - `level` (string) — logging level name e.g. "DEBUG", "ERROR", etc.
       See Python's logging module for details.
     - `handler` (optional, `logging.Handler`) — alternative handler to control instead
-      of the default, `LOGGER_CONSOLE`.
+      of the default, `CONSOLE_LOGGER`.
 
     """
     default_level = handler.level

tests/conftest.py

@@ -70,8 +70,8 @@ def __init__(self, config, *args, **kwargs):
         terminal_reporter = config.pluginmanager.get_plugin("terminalreporter")
         capture_manager = config.pluginmanager.get_plugin("capturemanager")
         handler = _LiveLoggingStreamHandler(terminal_reporter, capture_manager)
-        handler.setFormatter(_log.LOGGER_CONSOLE.formatter)
-        handler.setLevel(_log.LOGGER_CONSOLE.level)
+        handler.setFormatter(_log.CONSOLE_LOGGER.formatter)
+        handler.setLevel(_log.CONSOLE_LOGGER.level)
         self.log_cli_handler = handler
 
     # Override original, which tries to delete some silly globals that we aren't
@@ -102,8 +102,8 @@ def pytest_configure(config):
         terminal_reporter = config.pluginmanager.get_plugin("terminalreporter")
         capture_manager = config.pluginmanager.get_plugin("capturemanager")
         handler = _LiveLoggingStreamHandler(terminal_reporter, capture_manager)
-        handler.setFormatter(_log.LOGGER_CONSOLE.formatter)
-        handler.setLevel(_log.LOGGER_CONSOLE.level)
+        handler.setFormatter(_log.CONSOLE_LOGGER.formatter)
+        handler.setLevel(_log.CONSOLE_LOGGER.level)
         _log.LOGGER_PYTEST = handler
         config.pluginmanager.register(
             PytestConsoleLogger(config), PytestConsoleLogger.name
@@ -148,7 +148,7 @@ def console_handler(request):
         return request.config.pluginmanager.get_plugin(
             "pytest-console-logger"
         ).log_cli_handler
-    return _log.LOGGER_CONSOLE
+    return _log.CONSOLE_LOGGER
 
 
 @pytest.fixture

tests/test_diagnostics.py

@@ -88,14 +88,14 @@ def test_pointX(self):
             .as_matrix()
         )
         np.testing.assert_allclose(
-            _diagnostics.symmetry(orientations, axis="a"), (1, 0, 0), atol=0.05
+            _diagnostics.symmetry_pgr(orientations, axis="a"), (1, 0, 0), atol=0.05
         )
 
     def test_random(self):
         """Test diagnostics of random grain orientations."""
         orientations = Rotation.random(1000).as_matrix()
         np.testing.assert_allclose(
-            _diagnostics.symmetry(orientations, axis="a"), (0, 0, 1), atol=0.15
+            _diagnostics.symmetry_pgr(orientations, axis="a"), (0, 0, 1), atol=0.15
         )
 
     def test_girdle(self):
@@ -107,7 +107,7 @@ def test_girdle(self):
         d = rng.normal(0, 1.0, size=1000)
         orientations = Rotation.from_quat(np.column_stack([a, b, c, d])).as_matrix()
         np.testing.assert_allclose(
-            _diagnostics.symmetry(orientations, axis="a"), (0, 1, 0), atol=0.1
+            _diagnostics.symmetry_pgr(orientations, axis="a"), (0, 1, 0), atol=0.1
         )