refactor: Populate pydrex namespace and adjust some symbol names

- adjust `src/pydrex/__init__.py` to populate top-level namespace (i.e.
  what symbols you get from simply doing `import pydrex`)
- `LOGGER_CONSOLE` -> `CONSOLE_LOGGER` to match our documentation
- `pydrex.diagnostics.symmetry` -> `pydrex.diagnostics.symmetry_pgr` to
  avoid future namespace conflicts
- delete useless `meshio.read` wrapper, just use `meshio.read` directly

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