utils

environment

can_update_ipython_display()

Return True if IPython HTML display utilities are available.

This indicates we can safely construct IPython.display.HTML and update a display handle.

Source code in src/easydiffraction/utils/environment.py

def can_update_ipython_display() -> bool:
    """Return True if IPython HTML display utilities are available.

    This indicates we can safely construct ``IPython.display.HTML`` and
    update a display handle.
    """
    try:
        from IPython.display import HTML  # type: ignore[import-not-found]  # noqa: F401

        return True
    except Exception:
        return False

can_use_ipython_display(handle)

Return True if we can update the given IPython DisplayHandle.

Combines type checking of the handle with availability of IPython HTML utilities.

Source code in src/easydiffraction/utils/environment.py

def can_use_ipython_display(handle: object) -> bool:
    """Return True if we can update the given IPython DisplayHandle.

    Combines type checking of the handle with availability of IPython
    HTML utilities.
    """
    try:
        return is_ipython_display_handle(handle) and can_update_ipython_display()
    except Exception:
        return False

in_colab()

Determines if the current environment is Google Colab.

Returns:

Name	Type	Description
bool	bool	True if running in Google Colab, False otherwise.

Source code in src/easydiffraction/utils/environment.py

def in_colab() -> bool:
    """Determines if the current environment is Google Colab.

    Returns:
        bool: True if running in Google Colab, False otherwise.
    """
    try:
        return find_spec('google.colab') is not None
    except ModuleNotFoundError:  # pragma: no cover - importlib edge case
        return False

in_github_ci()

Return True when running under GitHub Actions CI.

Returns:

Name	Type	Description
bool	bool	True if env var GITHUB_ACTIONS is set, False
	bool	otherwise.

Source code in src/easydiffraction/utils/environment.py

def in_github_ci() -> bool:
    """Return True when running under GitHub Actions CI.

    Returns:
        bool: True if env var ``GITHUB_ACTIONS`` is set, False
        otherwise.
    """
    return os.environ.get('GITHUB_ACTIONS') is not None

in_jupyter()

Return True when running inside a Jupyter Notebook.

Returns:

Name	Type	Description
bool	bool	True if inside a Jupyter Notebook, False otherwise.

Source code in src/easydiffraction/utils/environment.py

def in_jupyter() -> bool:
    """Return True when running inside a Jupyter Notebook.

    Returns:
        bool: True if inside a Jupyter Notebook, False otherwise.
    """
    try:
        import IPython  # type: ignore[import-not-found]
    except ImportError:  # pragma: no cover - optional dependency
        ipython_mod = None
    else:
        ipython_mod = IPython
    if ipython_mod is None:
        return False
    if in_pycharm():
        return False
    if in_colab():
        return True

    try:
        ip = ipython_mod.get_ipython()  # type: ignore[attr-defined]
        if ip is None:
            return False
        # Prefer config-based detection when available (works with
        # tests).
        has_cfg = hasattr(ip, 'config') and isinstance(ip.config, dict)
        if has_cfg and 'IPKernelApp' in ip.config:  # type: ignore[index]
            return True
        shell = ip.__class__.__name__
        if shell == 'ZMQInteractiveShell':  # Jupyter or qtconsole
            return True
        if shell == 'TerminalInteractiveShell':
            return False
        return False
    except Exception:
        return False

in_pycharm()

Determines if the current environment is PyCharm.

Returns:

Name	Type	Description
bool	bool	True if running inside PyCharm, False otherwise.

Source code in src/easydiffraction/utils/environment.py

def in_pycharm() -> bool:
    """Determines if the current environment is PyCharm.

    Returns:
        bool: True if running inside PyCharm, False otherwise.
    """
    return os.environ.get('PYCHARM_HOSTED') == '1'

is_ipython_display_handle(obj)

Return True if obj is an IPython DisplayHandle instance.

Tries to import IPython.display.DisplayHandle and uses isinstance when available. Falls back to a conservative module name heuristic if IPython is missing. Any errors result in False.

Source code in src/easydiffraction/utils/environment.py

def is_ipython_display_handle(obj: object) -> bool:
    """Return True if ``obj`` is an IPython DisplayHandle instance.

    Tries to import ``IPython.display.DisplayHandle`` and uses
    ``isinstance`` when available. Falls back to a conservative
    module name heuristic if IPython is missing. Any errors result
    in ``False``.
    """
    try:  # Fast path when IPython is available
        from IPython.display import DisplayHandle  # type: ignore[import-not-found]

        try:
            return isinstance(obj, DisplayHandle)
        except Exception:
            return False
    except Exception:
        # Fallback heuristic when IPython is unavailable
        try:
            mod = getattr(getattr(obj, '__class__', None), '__module__', '')
            return isinstance(mod, str) and mod.startswith('IPython')
        except Exception:
            return False

logging

Project-wide logging utilities built on top of Rich.

Provides a shared Rich console, a compact/verbose logger with consistent formatting, Jupyter traceback handling, and a small printing façade tailored to the configured console.

ConsoleManager

Central provider for shared Rich Console instance.

Source code in src/easydiffraction/utils/logging.py

class ConsoleManager:
    """Central provider for shared Rich Console instance."""

    _MIN_CONSOLE_WIDTH = 130
    _instance: Console | None = None

    @staticmethod
    def _detect_width() -> int:
        """Detect a suitable console width for the shared Console.

        Returns:
            The detected terminal width, clamped at
            ``_MIN_CONSOLE_WIDTH`` to avoid cramped layouts.
        """
        min_width = ConsoleManager._MIN_CONSOLE_WIDTH
        try:
            width = shutil.get_terminal_size().columns
        except Exception:
            width = min_width
        return max(width, min_width)

    @classmethod
    def get(cls) -> Console:
        """Return a shared Rich Console instance."""
        if cls._instance is None:
            cls._instance = Console(
                width=cls._detect_width(),
                force_jupyter=False,
            )
        return cls._instance

get() classmethod

Return a shared Rich Console instance.

Source code in src/easydiffraction/utils/logging.py

@classmethod
def get(cls) -> Console:
    """Return a shared Rich Console instance."""
    if cls._instance is None:
        cls._instance = Console(
            width=cls._detect_width(),
            force_jupyter=False,
        )
    return cls._instance

ConsolePrinter

Printer utility that prints objects to the shared console with left padding.

Source code in src/easydiffraction/utils/logging.py

class ConsolePrinter:
    """Printer utility that prints objects to the shared console with
    left padding.
    """

    _console = ConsoleManager.get()

    @classmethod
    def print(cls, *objects, **kwargs):
        """Print objects to the console with left padding.

        - Renderables (Rich types like Text, Table, Panel, etc.) are
          kept as-is.
        - Non-renderables (ints, floats, Path, etc.) are converted to
          str().
        """
        safe_objects = []
        for obj in objects:
            if isinstance(obj, RenderableType):
                safe_objects.append(obj)
            elif isinstance(obj, Path):
                safe_objects.append(str(obj))
            else:
                safe_objects.append(str(obj))

        # If multiple objects, join with spaces
        renderable = (
            ' '.join(str(o) for o in safe_objects)
            if all(isinstance(o, str) for o in safe_objects)
            else Group(*safe_objects)
        )

        cls._console.print(renderable, **kwargs)

    @classmethod
    def paragraph(cls, title: str) -> None:
        parts = re.split(r"('.*?')", title)
        text = Text()
        for part in parts:
            if part.startswith("'") and part.endswith("'"):
                text.append(part)
            else:
                text.append(part, style='bold blue')
        formatted = f'{text.markup}'
        if not in_jupyter():
            formatted = f'\n{formatted}'
        cls._console.print(formatted)

    @classmethod
    def section(cls, title: str) -> None:
        """Formats a section header with bold green text."""
        full_title = f'{title.upper()}'
        line = '━' * len(full_title)
        formatted = f'[bold green]{full_title}\n{line}[/bold green]'
        if not in_jupyter():
            formatted = f'\n{formatted}'
        cls._console.print(formatted)

    @classmethod
    def chapter(cls, title: str) -> None:
        """Formats a chapter header with bold magenta text, uppercase,
        and padding.
        """
        width = ConsoleManager._detect_width()
        symbol = '─'
        full_title = f' {title.upper()} '
        pad_len = (width - len(full_title)) // 2
        padding = symbol * pad_len
        line = f'[bold magenta]{padding}{full_title}{padding}[/bold magenta]'
        if len(line) < width:
            line += symbol
        formatted = f'{line}'
        if not in_jupyter():
            formatted = f'\n{formatted}'
        cls._console.print(formatted)

chapter(title) classmethod

Formats a chapter header with bold magenta text, uppercase, and padding.

Source code in src/easydiffraction/utils/logging.py

@classmethod
def chapter(cls, title: str) -> None:
    """Formats a chapter header with bold magenta text, uppercase,
    and padding.
    """
    width = ConsoleManager._detect_width()
    symbol = '─'
    full_title = f' {title.upper()} '
    pad_len = (width - len(full_title)) // 2
    padding = symbol * pad_len
    line = f'[bold magenta]{padding}{full_title}{padding}[/bold magenta]'
    if len(line) < width:
        line += symbol
    formatted = f'{line}'
    if not in_jupyter():
        formatted = f'\n{formatted}'
    cls._console.print(formatted)

print(*objects, **kwargs) classmethod

Print objects to the console with left padding.

• Renderables (Rich types like Text, Table, Panel, etc.) are kept as-is.
• Non-renderables (ints, floats, Path, etc.) are converted to str().

Source code in src/easydiffraction/utils/logging.py

@classmethod
def print(cls, *objects, **kwargs):
    """Print objects to the console with left padding.

    - Renderables (Rich types like Text, Table, Panel, etc.) are
      kept as-is.
    - Non-renderables (ints, floats, Path, etc.) are converted to
      str().
    """
    safe_objects = []
    for obj in objects:
        if isinstance(obj, RenderableType):
            safe_objects.append(obj)
        elif isinstance(obj, Path):
            safe_objects.append(str(obj))
        else:
            safe_objects.append(str(obj))

    # If multiple objects, join with spaces
    renderable = (
        ' '.join(str(o) for o in safe_objects)
        if all(isinstance(o, str) for o in safe_objects)
        else Group(*safe_objects)
    )

    cls._console.print(renderable, **kwargs)

section(title) classmethod

Formats a section header with bold green text.

Source code in src/easydiffraction/utils/logging.py

@classmethod
def section(cls, title: str) -> None:
    """Formats a section header with bold green text."""
    full_title = f'{title.upper()}'
    line = '━' * len(full_title)
    formatted = f'[bold green]{full_title}\n{line}[/bold green]'
    if not in_jupyter():
        formatted = f'\n{formatted}'
    cls._console.print(formatted)

ExceptionHookManager

Handles installation and restoration of exception hooks.

Source code in src/easydiffraction/utils/logging.py

class ExceptionHookManager:
    """Handles installation and restoration of exception hooks."""

    @staticmethod
    def install_verbose_hook(logger: logging.Logger) -> None:
        """Install a verbose exception hook that prints rich tracebacks.

        Args:
            logger: Logger used to emit the exception information.
        """
        if not hasattr(Logger, '_orig_excepthook'):
            Logger._orig_excepthook = sys.excepthook  # type: ignore[attr-defined]

        def aligned_excepthook(
            exc_type: type[BaseException],
            exc: BaseException,
            tb: 'TracebackType | None',
        ) -> None:
            original_args = getattr(exc, 'args', tuple())
            message = str(exc)
            with suppress(Exception):
                exc.args = tuple()
            try:
                logger.error(message, exc_info=(exc_type, exc, tb))
            except Exception:
                logger.error('Unhandled exception (logging failure)')
            finally:
                with suppress(Exception):
                    exc.args = original_args

        sys.excepthook = aligned_excepthook  # type: ignore[assignment]

    @staticmethod
    def install_compact_hook(logger: logging.Logger) -> None:
        """Install a compact exception hook that logs message-only.

        Args:
            logger: Logger used to emit the error message.
        """
        if not hasattr(Logger, '_orig_excepthook'):
            Logger._orig_excepthook = sys.excepthook  # type: ignore[attr-defined]

        def compact_excepthook(
            _exc_type: type[BaseException],
            exc: BaseException,
            _tb: 'TracebackType | None',
        ) -> None:
            logger.error(str(exc))
            raise SystemExit(1)

        sys.excepthook = compact_excepthook  # type: ignore[assignment]

    @staticmethod
    def restore_original_hook():
        """Restore the original sys.excepthook if it was overridden."""
        if hasattr(Logger, '_orig_excepthook'):
            sys.excepthook = Logger._orig_excepthook  # type: ignore[attr-defined]

    # Jupyter-specific traceback suppression (inlined here)
    @staticmethod
    def _suppress_traceback(logger):
        """Build a Jupyter custom exception callback that logs only the
        message.

        Args:
            logger: Logger used to emit error messages.

        Returns:
            A callable suitable for IPython's set_custom_exc that
            suppresses full tracebacks and logs only the exception
            message.
        """

        def suppress_jupyter_traceback(*args, **kwargs):
            try:
                _evalue = (
                    args[2] if len(args) > 2 else kwargs.get('_evalue') or kwargs.get('evalue')
                )
                logger.error(str(_evalue))
            except Exception as err:
                logger.debug('Jupyter traceback suppressor failed: %r', err)
            return None

        return suppress_jupyter_traceback

    @staticmethod
    def install_jupyter_traceback_suppressor(logger: logging.Logger) -> None:
        """Install a Jupyter/IPython custom exception handler that
        suppresses tracebacks.

        Args:
            logger: Logger used to emit error messages.
        """
        try:
            from IPython import get_ipython

            ip = get_ipython()
            if ip is not None:
                ip.set_custom_exc(
                    (BaseException,), ExceptionHookManager._suppress_traceback(logger)
                )
        except Exception as err:
            msg = f'Failed to install Jupyter traceback suppressor: {err!r}'
            logger.debug(msg)

install_compact_hook(logger) staticmethod

Install a compact exception hook that logs message-only.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger used to emit the error message.	required

Source code in src/easydiffraction/utils/logging.py

@staticmethod
def install_compact_hook(logger: logging.Logger) -> None:
    """Install a compact exception hook that logs message-only.

    Args:
        logger: Logger used to emit the error message.
    """
    if not hasattr(Logger, '_orig_excepthook'):
        Logger._orig_excepthook = sys.excepthook  # type: ignore[attr-defined]

    def compact_excepthook(
        _exc_type: type[BaseException],
        exc: BaseException,
        _tb: 'TracebackType | None',
    ) -> None:
        logger.error(str(exc))
        raise SystemExit(1)

    sys.excepthook = compact_excepthook  # type: ignore[assignment]

install_jupyter_traceback_suppressor(logger) staticmethod

Install a Jupyter/IPython custom exception handler that suppresses tracebacks.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger used to emit error messages.	required

Source code in src/easydiffraction/utils/logging.py

@staticmethod
def install_jupyter_traceback_suppressor(logger: logging.Logger) -> None:
    """Install a Jupyter/IPython custom exception handler that
    suppresses tracebacks.

    Args:
        logger: Logger used to emit error messages.
    """
    try:
        from IPython import get_ipython

        ip = get_ipython()
        if ip is not None:
            ip.set_custom_exc(
                (BaseException,), ExceptionHookManager._suppress_traceback(logger)
            )
    except Exception as err:
        msg = f'Failed to install Jupyter traceback suppressor: {err!r}'
        logger.debug(msg)

install_verbose_hook(logger) staticmethod

Install a verbose exception hook that prints rich tracebacks.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger used to emit the exception information.	required

Source code in src/easydiffraction/utils/logging.py

@staticmethod
def install_verbose_hook(logger: logging.Logger) -> None:
    """Install a verbose exception hook that prints rich tracebacks.

    Args:
        logger: Logger used to emit the exception information.
    """
    if not hasattr(Logger, '_orig_excepthook'):
        Logger._orig_excepthook = sys.excepthook  # type: ignore[attr-defined]

    def aligned_excepthook(
        exc_type: type[BaseException],
        exc: BaseException,
        tb: 'TracebackType | None',
    ) -> None:
        original_args = getattr(exc, 'args', tuple())
        message = str(exc)
        with suppress(Exception):
            exc.args = tuple()
        try:
            logger.error(message, exc_info=(exc_type, exc, tb))
        except Exception:
            logger.error('Unhandled exception (logging failure)')
        finally:
            with suppress(Exception):
                exc.args = original_args

    sys.excepthook = aligned_excepthook  # type: ignore[assignment]

restore_original_hook() staticmethod

Restore the original sys.excepthook if it was overridden.

Source code in src/easydiffraction/utils/logging.py

@staticmethod
def restore_original_hook():
    """Restore the original sys.excepthook if it was overridden."""
    if hasattr(Logger, '_orig_excepthook'):
        sys.excepthook = Logger._orig_excepthook  # type: ignore[attr-defined]

IconifiedRichHandler

Bases: RichHandler

RichHandler that uses icons for log levels in compact mode, Rich default in verbose mode.

Source code in src/easydiffraction/utils/logging.py

class IconifiedRichHandler(RichHandler):
    """RichHandler that uses icons for log levels in compact mode, Rich
    default in verbose mode.
    """

    _icons = {
        logging.CRITICAL: '💀',
        logging.ERROR: '❌',
        logging.WARNING: '⚠️',
        logging.DEBUG: '⚙️',
        logging.INFO: 'ℹ️',
    }

    def __init__(self, *args, mode: str = 'compact', **kwargs):
        super().__init__(*args, **kwargs)
        self.mode = mode

    def get_level_text(self, record: logging.LogRecord) -> Text:
        if self.mode == 'compact':
            icon = self._icons.get(record.levelno, record.levelname)
            if in_warp() and not in_jupyter() and icon in ['⚠️', '⚙️', 'ℹ️']:
                icon = icon + ' '  # add space to align with two-char icons
            return Text(icon)
        else:
            # Use RichHandler's default level text for verbose mode
            return super().get_level_text(record)

    def render_message(self, record: logging.LogRecord, message: str) -> Text:
        # In compact mode, let the icon come from get_level_text and
        # keep the message body unadorned. In verbose mode, defer to
        # RichHandler.
        if self.mode == 'compact':
            try:
                return Text.from_markup(message)
            except Exception:
                return Text(str(message))
        return super().render_message(record, message)

Logger

Centralized logging with Rich formatting and two modes.

Environment variables: ED_LOG_MODE: set default mode ('verbose' or 'compact') ED_LOG_LEVEL: set default level ('DEBUG', 'INFO', etc.)

Source code in src/easydiffraction/utils/logging.py

class Logger:
    """Centralized logging with Rich formatting and two modes.

    Environment variables:
    ED_LOG_MODE: set default mode ('verbose' or 'compact')
    ED_LOG_LEVEL: set default level ('DEBUG', 'INFO', etc.)
    """

    # --- Enums ---
    class Mode(Enum):
        """Output modes (see :class:`Logger`)."""

        VERBOSE = 'verbose'  # rich traceback panel
        COMPACT = 'compact'  # single line; no traceback

        @classmethod
        def default(cls):
            return cls.COMPACT

    class Level(IntEnum):
        """Mirror stdlib logging levels."""

        DEBUG = logging.DEBUG
        INFO = logging.INFO
        WARNING = logging.WARNING
        ERROR = logging.ERROR
        CRITICAL = logging.CRITICAL

        @classmethod
        def default(cls):
            return cls.WARNING

    class Reaction(Enum):
        """Reaction to errors (see :class:`Logger`)."""

        RAISE = auto()
        WARN = auto()

        @classmethod
        def default(cls):
            return cls.RAISE

    # --- Internal state ---
    _logger = logging.getLogger('easydiffraction')
    _configured = False
    _mode: Mode = Mode.VERBOSE
    _reaction: Reaction = Reaction.RAISE  # TODO: not default?
    _console = ConsoleManager.get()

    # ===== CONFIGURATION =====
    @classmethod
    def configure(
        cls,
        *,
        mode: Mode | None = None,
        level: Level | None = None,
        reaction: Reaction | None = None,
        rich_tracebacks: bool | None = None,
    ) -> None:
        """Configure logger.

        mode: default COMPACT in Jupyter else VERBOSE
        level: minimum log level
        rich_tracebacks: override automatic choice

        Environment variables:
        ED_LOG_MODE: set default mode ('verbose' or 'compact')
        ED_LOG_LEVEL: set default level ('DEBUG', 'INFO', etc.)
        """
        env_mode = os.getenv('ED_LOG_MODE')
        env_level = os.getenv('ED_LOG_LEVEL')
        env_reaction = os.getenv('ED_LOG_REACTION')

        # Read from environment if not provided
        if mode is None and env_mode is not None:
            with suppress(ValueError):
                mode = Logger.Mode(env_mode.lower())
        if level is None and env_level is not None:
            with suppress(KeyError):
                level = Logger.Level[env_level.upper()]
        if reaction is None and env_reaction is not None:
            with suppress(KeyError):
                reaction = Logger.Reaction[env_reaction.upper()]

        # Set defaults if still None
        if mode is None:
            mode = Logger.Mode.default()
        if level is None:
            level = Logger.Level.default()
        if reaction is None:
            reaction = Logger.Reaction.default()

        cls._mode = mode
        cls._reaction = reaction

        if rich_tracebacks is None:
            rich_tracebacks = mode == Logger.Mode.VERBOSE

        LoggerConfig.configure(
            logger=cls._logger,
            mode=mode,
            level=level,
            rich_tracebacks=rich_tracebacks,
        )
        cls._configured = True

    @classmethod
    def _install_jupyter_traceback_suppressor(cls) -> None:
        """Install traceback suppressor in Jupyter, safely and lint-
        clean.
        """
        ExceptionHookManager.install_jupyter_traceback_suppressor(cls._logger)

    # ===== Helpers =====
    @classmethod
    def set_mode(cls, mode: Mode) -> None:
        cls.configure(mode=mode, level=cls.Level(cls._logger.level))

    @classmethod
    def set_level(cls, level: Level) -> None:
        cls.configure(mode=cls._mode, level=level)

    @classmethod
    def mode(cls) -> Mode:
        return cls._mode

    @classmethod
    def _lazy_config(cls) -> None:
        if not cls._configured:  # pragma: no cover - trivial
            cls.configure()

    # ===== Core Routing =====
    @classmethod
    def handle(
        cls,
        *messages: str,
        level: Level = Level.ERROR,
        exc_type: type[BaseException] | None = AttributeError,
    ) -> None:
        """Route a log message (see class docs for policy)."""
        cls._lazy_config()
        message = ' '.join(messages)
        # Prioritize explicit UserWarning path so pytest captures
        # warnings
        if exc_type is UserWarning:
            if in_pytest():
                warnings.warn(message, UserWarning, stacklevel=2)
            else:
                cls._logger.warning(message)
            return
        # Special handling for Reaction.WARN (non-warning cases)
        if cls._reaction is cls.Reaction.WARN:
            # Log as error/critical (keep icon) but continue execution
            cls._logger.log(int(level), message)
            return
        if exc_type is not None:
            if cls._mode is cls.Mode.VERBOSE:
                raise exc_type(message)
            if cls._mode is cls.Mode.COMPACT:
                raise exc_type(message) from None
        cls._logger.log(int(level), message)

    # ==================================================================
    # CONVENIENCE API
    # ==================================================================

    @classmethod
    def debug(cls, *messages: str) -> None:
        cls.handle(*messages, level=cls.Level.DEBUG, exc_type=None)

    @classmethod
    def info(cls, *messages: str) -> None:
        cls.handle(*messages, level=cls.Level.INFO, exc_type=None)

    @classmethod
    def warning(cls, *messages: str, exc_type: type[BaseException] | None = None) -> None:
        cls.handle(*messages, level=cls.Level.WARNING, exc_type=exc_type)

    @classmethod
    def error(cls, *messages: str, exc_type: type[BaseException] = AttributeError) -> None:
        cls.handle(*messages, level=cls.Level.ERROR, exc_type=exc_type)

    @classmethod
    def critical(cls, *messages: str, exc_type: type[BaseException] = RuntimeError) -> None:
        cls.handle(*messages, level=cls.Level.CRITICAL, exc_type=exc_type)

Level

Bases: IntEnum

Mirror stdlib logging levels.

Source code in src/easydiffraction/utils/logging.py

class Level(IntEnum):
    """Mirror stdlib logging levels."""

    DEBUG = logging.DEBUG
    INFO = logging.INFO
    WARNING = logging.WARNING
    ERROR = logging.ERROR
    CRITICAL = logging.CRITICAL

    @classmethod
    def default(cls):
        return cls.WARNING

Mode

Bases: Enum

Output modes (see :class:Logger).

Source code in src/easydiffraction/utils/logging.py

class Mode(Enum):
    """Output modes (see :class:`Logger`)."""

    VERBOSE = 'verbose'  # rich traceback panel
    COMPACT = 'compact'  # single line; no traceback

    @classmethod
    def default(cls):
        return cls.COMPACT

Reaction

Bases: Enum

Reaction to errors (see :class:Logger).

Source code in src/easydiffraction/utils/logging.py

class Reaction(Enum):
    """Reaction to errors (see :class:`Logger`)."""

    RAISE = auto()
    WARN = auto()

    @classmethod
    def default(cls):
        return cls.RAISE

configure(*, mode=None, level=None, reaction=None, rich_tracebacks=None) classmethod

Configure logger.

mode: default COMPACT in Jupyter else VERBOSE level: minimum log level rich_tracebacks: override automatic choice

Environment variables: ED_LOG_MODE: set default mode ('verbose' or 'compact') ED_LOG_LEVEL: set default level ('DEBUG', 'INFO', etc.)

Source code in src/easydiffraction/utils/logging.py

@classmethod
def configure(
    cls,
    *,
    mode: Mode | None = None,
    level: Level | None = None,
    reaction: Reaction | None = None,
    rich_tracebacks: bool | None = None,
) -> None:
    """Configure logger.

    mode: default COMPACT in Jupyter else VERBOSE
    level: minimum log level
    rich_tracebacks: override automatic choice

    Environment variables:
    ED_LOG_MODE: set default mode ('verbose' or 'compact')
    ED_LOG_LEVEL: set default level ('DEBUG', 'INFO', etc.)
    """
    env_mode = os.getenv('ED_LOG_MODE')
    env_level = os.getenv('ED_LOG_LEVEL')
    env_reaction = os.getenv('ED_LOG_REACTION')

    # Read from environment if not provided
    if mode is None and env_mode is not None:
        with suppress(ValueError):
            mode = Logger.Mode(env_mode.lower())
    if level is None and env_level is not None:
        with suppress(KeyError):
            level = Logger.Level[env_level.upper()]
    if reaction is None and env_reaction is not None:
        with suppress(KeyError):
            reaction = Logger.Reaction[env_reaction.upper()]

    # Set defaults if still None
    if mode is None:
        mode = Logger.Mode.default()
    if level is None:
        level = Logger.Level.default()
    if reaction is None:
        reaction = Logger.Reaction.default()

    cls._mode = mode
    cls._reaction = reaction

    if rich_tracebacks is None:
        rich_tracebacks = mode == Logger.Mode.VERBOSE

    LoggerConfig.configure(
        logger=cls._logger,
        mode=mode,
        level=level,
        rich_tracebacks=rich_tracebacks,
    )
    cls._configured = True

handle(*messages, level=Level.ERROR, exc_type=AttributeError) classmethod

Route a log message (see class docs for policy).

Source code in src/easydiffraction/utils/logging.py

@classmethod
def handle(
    cls,
    *messages: str,
    level: Level = Level.ERROR,
    exc_type: type[BaseException] | None = AttributeError,
) -> None:
    """Route a log message (see class docs for policy)."""
    cls._lazy_config()
    message = ' '.join(messages)
    # Prioritize explicit UserWarning path so pytest captures
    # warnings
    if exc_type is UserWarning:
        if in_pytest():
            warnings.warn(message, UserWarning, stacklevel=2)
        else:
            cls._logger.warning(message)
        return
    # Special handling for Reaction.WARN (non-warning cases)
    if cls._reaction is cls.Reaction.WARN:
        # Log as error/critical (keep icon) but continue execution
        cls._logger.log(int(level), message)
        return
    if exc_type is not None:
        if cls._mode is cls.Mode.VERBOSE:
            raise exc_type(message)
        if cls._mode is cls.Mode.COMPACT:
            raise exc_type(message) from None
    cls._logger.log(int(level), message)

LoggerConfig

Facade for logger configuration, delegates to helpers.

Source code in src/easydiffraction/utils/logging.py

class LoggerConfig:
    """Facade for logger configuration, delegates to helpers."""

    @staticmethod
    def setup_handlers(
        logger: logging.Logger,
        *,
        level: int,
        rich_tracebacks: bool,
        mode: str = 'compact',
    ) -> None:
        """Install Rich handler and optional Jupyter traceback support.

        Args:
            logger: Logger instance to attach handlers to.
            level: Minimum log level to emit.
            rich_tracebacks: Whether to enable Rich tracebacks.
            mode: Output mode name ("compact" or "verbose").
        """
        logger.handlers.clear()
        logger.propagate = False
        logger.setLevel(level)

        if in_jupyter():
            traceback.install(
                show_locals=False,
                suppress=['easydiffraction'],
            )

        console = ConsoleManager.get()
        handler = IconifiedRichHandler(
            rich_tracebacks=rich_tracebacks,
            markup=True,
            show_time=False,
            show_path=False,
            tracebacks_show_locals=False,
            tracebacks_suppress=['easydiffraction'],
            tracebacks_max_frames=10,
            console=console,
            mode=mode,
        )
        handler.setFormatter(logging.Formatter('%(message)s'))
        logger.addHandler(handler)

    @staticmethod
    def configure(
        logger: logging.Logger,
        *,
        mode: 'Logger.Mode',
        level: 'Logger.Level',
        rich_tracebacks: bool,
    ) -> None:
        """Configure the logger with RichHandler and exception hooks.

        Args:
            logger: Logger instance to configure.
            mode: Output mode (compact or verbose).
            level: Minimum log level to emit.
            rich_tracebacks: Whether to enable Rich tracebacks.
        """
        LoggerConfig.setup_handlers(
            logger,
            level=int(level),
            rich_tracebacks=rich_tracebacks,
            mode=mode.value,
        )

        if rich_tracebacks and mode == Logger.Mode.VERBOSE:
            ExceptionHookManager.install_verbose_hook(logger)
        elif mode == Logger.Mode.COMPACT:
            ExceptionHookManager.install_compact_hook(logger)
            ExceptionHookManager.install_jupyter_traceback_suppressor(logger)
        else:
            ExceptionHookManager.restore_original_hook()

configure(logger, *, mode, level, rich_tracebacks) staticmethod

Configure the logger with RichHandler and exception hooks.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger instance to configure.	required
mode	'Logger.Mode'	Output mode (compact or verbose).	required
level	'Logger.Level'	Minimum log level to emit.	required
rich_tracebacks	bool	Whether to enable Rich tracebacks.	required

Source code in src/easydiffraction/utils/logging.py

@staticmethod
def configure(
    logger: logging.Logger,
    *,
    mode: 'Logger.Mode',
    level: 'Logger.Level',
    rich_tracebacks: bool,
) -> None:
    """Configure the logger with RichHandler and exception hooks.

    Args:
        logger: Logger instance to configure.
        mode: Output mode (compact or verbose).
        level: Minimum log level to emit.
        rich_tracebacks: Whether to enable Rich tracebacks.
    """
    LoggerConfig.setup_handlers(
        logger,
        level=int(level),
        rich_tracebacks=rich_tracebacks,
        mode=mode.value,
    )

    if rich_tracebacks and mode == Logger.Mode.VERBOSE:
        ExceptionHookManager.install_verbose_hook(logger)
    elif mode == Logger.Mode.COMPACT:
        ExceptionHookManager.install_compact_hook(logger)
        ExceptionHookManager.install_jupyter_traceback_suppressor(logger)
    else:
        ExceptionHookManager.restore_original_hook()

setup_handlers(logger, *, level, rich_tracebacks, mode='compact') staticmethod

Install Rich handler and optional Jupyter traceback support.

Parameters:

Name	Type	Description	Default
logger	Logger	Logger instance to attach handlers to.	required
level	int	Minimum log level to emit.	required
rich_tracebacks	bool	Whether to enable Rich tracebacks.	required
mode	str	Output mode name ("compact" or "verbose").	'compact'

Source code in src/easydiffraction/utils/logging.py

@staticmethod
def setup_handlers(
    logger: logging.Logger,
    *,
    level: int,
    rich_tracebacks: bool,
    mode: str = 'compact',
) -> None:
    """Install Rich handler and optional Jupyter traceback support.

    Args:
        logger: Logger instance to attach handlers to.
        level: Minimum log level to emit.
        rich_tracebacks: Whether to enable Rich tracebacks.
        mode: Output mode name ("compact" or "verbose").
    """
    logger.handlers.clear()
    logger.propagate = False
    logger.setLevel(level)

    if in_jupyter():
        traceback.install(
            show_locals=False,
            suppress=['easydiffraction'],
        )

    console = ConsoleManager.get()
    handler = IconifiedRichHandler(
        rich_tracebacks=rich_tracebacks,
        markup=True,
        show_time=False,
        show_path=False,
        tracebacks_show_locals=False,
        tracebacks_suppress=['easydiffraction'],
        tracebacks_max_frames=10,
        console=console,
        mode=mode,
    )
    handler.setFormatter(logging.Formatter('%(message)s'))
    logger.addHandler(handler)

stripped_package_version(package_name)

Get the installed version of the specified package, stripped of any local version part.

Returns only the public version segment (e.g., '1.2.3' or '1.2.3.post4'), omitting any local segment (e.g., '+d136').

Parameters:

Name	Type	Description	Default
package_name	str	The name of the package to query.	required

Returns:

Type	Description
str | None	str | None: The public version string, or None if the package
str | None	is not installed.

Source code in src/easydiffraction/utils/utils.py

def stripped_package_version(package_name: str) -> str | None:
    """Get the installed version of the specified package, stripped of
    any local version part.

    Returns only the public version segment (e.g., '1.2.3' or
    '1.2.3.post4'), omitting any local segment (e.g., '+d136').

    Args:
        package_name (str): The name of the package to query.

    Returns:
        str | None: The public version string, or None if the package
        is not installed.
    """
    v_str = package_version(package_name)
    if v_str is None:
        return None
    try:
        v = Version(v_str)
        return str(v.public)
    except Exception:
        return v_str

utils

download_all_tutorials(destination='tutorials', overwrite=False)

Download all available tutorial notebooks.

Example

paths = download_all_tutorials(destination="tutorials")

Parameters:

Name	Type	Description	Default
destination	str	Directory to save the files into (created if missing).	'tutorials'
overwrite	bool	Whether to overwrite files if they already exist.	False

Returns:

Type	Description
list[str]	list[str]: List of full paths to the downloaded files.

Source code in src/easydiffraction/utils/utils.py

def download_all_tutorials(
    destination: str = 'tutorials',
    overwrite: bool = False,
) -> list[str]:
    """Download all available tutorial notebooks.

    Example:
        paths = download_all_tutorials(destination="tutorials")

    Args:
        destination: Directory to save the files into (created if
            missing).
        overwrite: Whether to overwrite files if they already exist.

    Returns:
        list[str]: List of full paths to the downloaded files.
    """
    index = _fetch_tutorials_index()
    if not index:
        console.print('❌ No tutorials available to download.')
        return []

    version = _get_version_for_url()
    console.print(f'📥 Downloading all tutorials for easydiffraction v{version}...')

    downloaded_paths = []
    for tutorial_id in sorted(index.keys(), key=lambda x: int(x) if x.isdigit() else x):
        try:
            path = download_tutorial(
                id=tutorial_id,
                destination=destination,
                overwrite=overwrite,
            )
            downloaded_paths.append(path)
        except Exception as e:
            log.warning(f'Failed to download tutorial #{tutorial_id}: {e}')

    console.print(f'✅ Downloaded {len(downloaded_paths)} tutorials to "{destination}/"')
    return downloaded_paths

download_data(id, destination='data', overwrite=False)

Download a dataset by numeric ID using the remote diffraction index.

Example

path = download_data(id=12, destination="data")

Parameters:

Name	Type	Description	Default
id	int | str	Numeric dataset id (e.g. 12).	required
destination	str	Directory to save the file into (created if missing).	'data'
overwrite	bool	Whether to overwrite the file if it already exists.	False

Returns:

Name	Type	Description
str	str	Full path to the downloaded file as string.

Raises:

Type	Description
KeyError	If the id is not found in the index.
ValueError	If the resolved URL is not HTTP/HTTPS.

Source code in src/easydiffraction/utils/utils.py

def download_data(
    id: int | str,
    destination: str = 'data',
    overwrite: bool = False,
) -> str:
    """Download a dataset by numeric ID using the remote diffraction
    index.

    Example:
        path = download_data(id=12, destination="data")

    Args:
        id: Numeric dataset id (e.g. 12).
        destination: Directory to save the file into (created if
            missing).
        overwrite: Whether to overwrite the file if it already exists.

    Returns:
        str: Full path to the downloaded file as string.

    Raises:
        KeyError: If the id is not found in the index.
        ValueError: If the resolved URL is not HTTP/HTTPS.
    """
    index = _fetch_data_index()
    key = str(id)

    if key not in index:
        # Provide a helpful message (and keep KeyError semantics)
        available = ', '.join(
            sorted(index.keys(), key=lambda s: int(s) if s.isdigit() else s)[:20]
        )
        raise KeyError(f'Unknown dataset id={id}. Example available ids: {available} ...')

    record = index[key]
    url = record['url']
    _validate_url(url)

    known_hash = _normalize_known_hash(record.get('hash'))
    fname = _filename_for_id_from_url(id, url)

    dest_path = pathlib.Path(destination)
    dest_path.mkdir(parents=True, exist_ok=True)
    file_path = dest_path / fname

    description = record.get('description', '')
    message = f'Data #{id}'
    if description:
        message += f': {description}'

    console.paragraph('Getting data...')
    console.print(f'{message}')

    if file_path.exists():
        if not overwrite:
            console.print(
                f"✅ Data #{id} already present at '{file_path}'. Keeping existing file."
            )
            return str(file_path)
        log.debug(f"Data #{id} already present at '{file_path}', but will be overwritten.")
        file_path.unlink()

    # Pooch downloads to destination with our controlled filename.
    pooch.retrieve(
        url=url,
        known_hash=known_hash,
        fname=fname,
        path=str(dest_path),
    )

    console.print(f"✅ Data #{id} downloaded to '{file_path}'")
    return str(file_path)

download_tutorial(id, destination='tutorials', overwrite=False)

Download a tutorial notebook by numeric ID.

Example

path = download_tutorial(id=1, destination="tutorials")

Parameters:

Name	Type	Description	Default
id	int | str	Numeric tutorial id (e.g. 1).	required
destination	str	Directory to save the file into (created if missing).	'tutorials'
overwrite	bool	Whether to overwrite the file if it already exists.	False

Returns:

Name	Type	Description
str	str	Full path to the downloaded file as string.

Raises:

Type	Description
KeyError	If the id is not found in the index.
ValueError	If the resolved URL is not HTTP/HTTPS.

Source code in src/easydiffraction/utils/utils.py

def download_tutorial(
    id: int | str,
    destination: str = 'tutorials',
    overwrite: bool = False,
) -> str:
    """Download a tutorial notebook by numeric ID.

    Example:
        path = download_tutorial(id=1, destination="tutorials")

    Args:
        id: Numeric tutorial id (e.g. 1).
        destination: Directory to save the file into (created if
            missing).
        overwrite: Whether to overwrite the file if it already exists.

    Returns:
        str: Full path to the downloaded file as string.

    Raises:
        KeyError: If the id is not found in the index.
        ValueError: If the resolved URL is not HTTP/HTTPS.
    """
    index = _fetch_tutorials_index()
    key = str(id)

    if key not in index:
        available = ', '.join(
            sorted(index.keys(), key=lambda s: int(s) if s.isdigit() else s)[:20]
        )
        raise KeyError(f'Unknown tutorial id={id}. Available ids: {available}')

    record = index[key]
    url_template = record['url']
    url = _resolve_tutorial_url(url_template)
    _validate_url(url)

    fname = f'ed-{id}.ipynb'

    dest_path = pathlib.Path(destination)
    dest_path.mkdir(parents=True, exist_ok=True)
    file_path = dest_path / fname

    title = record.get('title', '')
    message = f'Tutorial #{id}'
    if title:
        message += f': {title}'

    console.paragraph('Getting tutorial...')
    console.print(f'{message}')

    if file_path.exists():
        if not overwrite:
            console.print(
                f"✅ Tutorial #{id} already present at '{file_path}'. Keeping existing file."
            )
            return str(file_path)
        log.debug(f"Tutorial #{id} already present at '{file_path}', but will be overwritten.")
        file_path.unlink()

    # Download the notebook
    with _safe_urlopen(url) as resp:
        file_path.write_bytes(resp.read())

    console.print(f"✅ Tutorial #{id} downloaded to '{file_path}'")
    return str(file_path)

get_value_from_xye_header(file_path, key)

Extracts a floating point value from the first line of the file, corresponding to the given key.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the input file.	required
key	str	The key to extract ('DIFC' or 'two_theta').	required

Returns:

Name	Type	Description
float		The extracted value.

Raises:

Type	Description
ValueError	If the key is not found.

Source code in src/easydiffraction/utils/utils.py

def get_value_from_xye_header(file_path, key):
    """Extracts a floating point value from the first line of the file,
    corresponding to the given key.

    Parameters:
        file_path (str): Path to the input file.
        key (str): The key to extract ('DIFC' or 'two_theta').

    Returns:
        float: The extracted value.

    Raises:
        ValueError: If the key is not found.
    """
    pattern = rf'{key}\s*=\s*([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)'

    with pathlib.Path(file_path).open('r') as f:
        first_line = f.readline()

    match = re.search(pattern, first_line)
    if match:
        return float(match.group(1))
    else:
        raise ValueError(f'{key} not found in the header.')

list_tutorials()

Display a table of available tutorial notebooks.

Shows tutorial ID, filename, title, and description for all tutorials available for the current version of easydiffraction.

Source code in src/easydiffraction/utils/utils.py

def list_tutorials() -> None:
    """Display a table of available tutorial notebooks.

    Shows tutorial ID, filename, title, and description for all
    tutorials available for the current version of easydiffraction.
    """
    index = _fetch_tutorials_index()
    if not index:
        console.print('❌ No tutorials available.')
        return

    version = _get_version_for_url()
    console.print(f'Tutorials available for easydiffraction v{version}:')
    console.print('')

    columns_headers = ['id', 'file', 'title', 'description']
    columns_alignment = ['right', 'left', 'left', 'left']
    columns_data = []

    for tutorial_id in sorted(index.keys(), key=lambda x: int(x) if x.isdigit() else x):
        record = index[tutorial_id]
        filename = f'ed-{tutorial_id}.ipynb'
        title = record.get('title', '')
        description = record.get('description', '')
        columns_data.append([tutorial_id, filename, title, description])

    render_table(
        columns_headers=columns_headers,
        columns_data=columns_data,
        columns_alignment=columns_alignment,
    )

package_version(package_name)

Get the installed version string of the specified package.

Parameters:

Name	Type	Description	Default
package_name	str	The name of the package to query.	required

Returns:

Type	Description
str | None	str | None: The raw version string (may include local part,
str | None	e.g., '1.2.3+abc123'), or None if the package is not installed.

Source code in src/easydiffraction/utils/utils.py

def package_version(package_name: str) -> str | None:
    """Get the installed version string of the specified package.

    Args:
        package_name (str): The name of the package to query.

    Returns:
        str | None: The raw version string (may include local part,
        e.g., '1.2.3+abc123'), or None if the package is not installed.
    """
    try:
        return version(package_name)
    except PackageNotFoundError:
        return None

render_cif(cif_text)

Display the CIF text as a formatted table in Jupyter Notebook or terminal.

Parameters:

Name	Type	Description	Default
cif_text		The CIF text to display.	required

Source code in src/easydiffraction/utils/utils.py

def render_cif(cif_text) -> None:
    """Display the CIF text as a formatted table in Jupyter Notebook or
    terminal.

    Args:
        cif_text: The CIF text to display.
    """
    # Split into lines
    lines: List[str] = [line for line in cif_text.splitlines()]

    # Convert each line into a single-column format for table rendering
    columns: List[List[str]] = [[line] for line in lines]

    # Render the table using left alignment and no headers
    render_table(
        columns_headers=['CIF'],
        columns_alignment=['left'],
        columns_data=columns,
    )

show_version()

Print the installed version of the easydiffraction package.

Source code in src/easydiffraction/utils/utils.py

def show_version() -> None:
    """Print the installed version of the easydiffraction package.

    Args:
        None
    """
    current_ed_version = package_version('easydiffraction')
    console.print(f'Current easydiffraction v{current_ed_version}')

str_to_ufloat(s, default=None)

Parse a CIF-style numeric string into a ufloat with an optional uncertainty.

Examples of supported input: - "3.566" → ufloat(3.566, nan) - "3.566(2)" → ufloat(3.566, 0.002) - None → ufloat(default, nan)

Behavior: - If the input string contains a value with parentheses (e.g. "3.566(2)"), the number in parentheses is interpreted as an estimated standard deviation (esd) in the last digit(s). - If the input string has no parentheses, an uncertainty of NaN is assigned to indicate "no esd provided". - If parsing fails, the function falls back to the given default value with uncertainty NaN.

Parameters

s : str or None Numeric string in CIF format (e.g. "3.566", "3.566(2)") or None. default : float or None, optional Default value to use if s is None or parsing fails. Defaults to None.

Returns:

UFloat An uncertainties.UFloat object with the parsed value and uncertainty. The uncertainty will be NaN if not specified or parsing failed.

Source code in src/easydiffraction/utils/utils.py

def str_to_ufloat(s: Optional[str], default: Optional[float] = None) -> UFloat:
    """Parse a CIF-style numeric string into a `ufloat` with an optional
    uncertainty.

    Examples of supported input:
    - "3.566"       → ufloat(3.566, nan)
    - "3.566(2)"    → ufloat(3.566, 0.002)
    - None          → ufloat(default, nan)

    Behavior:
    - If the input string contains a value with parentheses (e.g.
      "3.566(2)"), the number in parentheses is interpreted as an
      estimated standard deviation (esd) in the last digit(s).
    - If the input string has no parentheses, an uncertainty of NaN is
      assigned to indicate "no esd provided".
    - If parsing fails, the function falls back to the given `default`
      value with uncertainty NaN.

    Parameters
    ----------
    s : str or None
        Numeric string in CIF format (e.g. "3.566", "3.566(2)") or None.
    default : float or None, optional
        Default value to use if `s` is None or parsing fails.
        Defaults to None.

    Returns:
    -------
    UFloat
        An `uncertainties.UFloat` object with the parsed value and
        uncertainty. The uncertainty will be NaN if not specified or
        parsing failed.
    """
    if s is None:
        return ufloat(default, np.nan)

    if '(' not in s and ')' not in s:
        s = f'{s}(nan)'
    try:
        return ufloat_fromstr(s)
    except Exception:
        return ufloat(default, np.nan)

stripped_package_version(package_name)

Get the installed version of the specified package, stripped of any local version part.

Returns only the public version segment (e.g., '1.2.3' or '1.2.3.post4'), omitting any local segment (e.g., '+d136').

Parameters:

Name	Type	Description	Default
package_name	str	The name of the package to query.	required

Returns:

Type	Description
str | None	str | None: The public version string, or None if the package
str | None	is not installed.

Source code in src/easydiffraction/utils/utils.py

def stripped_package_version(package_name: str) -> str | None:
    """Get the installed version of the specified package, stripped of
    any local version part.

    Returns only the public version segment (e.g., '1.2.3' or
    '1.2.3.post4'), omitting any local segment (e.g., '+d136').

    Args:
        package_name (str): The name of the package to query.

    Returns:
        str | None: The public version string, or None if the package
        is not installed.
    """
    v_str = package_version(package_name)
    if v_str is None:
        return None
    try:
        v = Version(v_str)
        return str(v.public)
    except Exception:
        return v_str

tof_to_d(tof, offset, linear, quad, quad_eps=1e-20)

Convert time-of-flight (TOF) to d-spacing using a quadratic calibration.

Model

TOF = offset + linear * d + quad * d²

The function

• Uses a linear fallback when the quadratic term is effectively zero.
• Solves the quadratic for d and selects the smallest positive, finite root.
• Returns NaN where no valid solution exists.
• Expects tof as a NumPy array; output matches its shape.

Parameters:

Name	Type	Description	Default
tof	ndarray	Time-of-flight values (µs). Must be a NumPy array.	required
offset	float	Calibration offset (µs).	required
linear	float	Linear calibration coefficient (µs/Å).	required
quad	float	Quadratic calibration coefficient (µs/Ų).	required
quad_eps	float	Threshold to treat quad as zero. Defaults to 1e-20.	1e-20

Returns:

Type	Description
ndarray	np.ndarray: d-spacing values (Å), NaN where invalid.

Raises:

Type	Description
TypeError	If tof is not a NumPy array or coefficients are not real numbers.

Source code in src/easydiffraction/utils/utils.py

def tof_to_d(
    tof: np.ndarray,
    offset: float,
    linear: float,
    quad: float,
    quad_eps=1e-20,
) -> np.ndarray:
    """Convert time-of-flight (TOF) to d-spacing using a quadratic
    calibration.

    Model:
        TOF = offset + linear * d + quad * d²

    The function:
      - Uses a linear fallback when the quadratic term is effectively
        zero.
      - Solves the quadratic for d and selects the smallest positive,
        finite root.
      - Returns NaN where no valid solution exists.
      - Expects ``tof`` as a NumPy array; output matches its shape.

    Args:
        tof (np.ndarray): Time-of-flight values (µs). Must be a NumPy
            array.
        offset (float): Calibration offset (µs).
        linear (float): Linear calibration coefficient (µs/Å).
        quad (float): Quadratic calibration coefficient (µs/Ų).
        quad_eps (float, optional): Threshold to treat ``quad`` as zero.
            Defaults to 1e-20.

    Returns:
        np.ndarray: d-spacing values (Å), NaN where invalid.

    Raises:
        TypeError: If ``tof`` is not a NumPy array or coefficients are
            not real numbers.
    """
    # Type checks
    if not isinstance(tof, np.ndarray):
        raise TypeError(f"'tof' must be a NumPy array, got {type(tof).__name__}")
    for name, val in (
        ('offset', offset),
        ('linear', linear),
        ('quad', quad),
        ('quad_eps', quad_eps),
    ):
        if not isinstance(val, (int, float, np.integer, np.floating)):
            raise TypeError(f"'{name}' must be a real number, got {type(val).__name__}")

    # Output initialized to NaN
    d_out = np.full_like(tof, np.nan, dtype=float)

    # 1) If quadratic term is effectively zero, use linear formula:
    #    TOF ≈ offset + linear * d =>
    #    d ≈ (tof - offset) / linear
    if abs(quad) < quad_eps:
        if linear != 0.0:
            d = (tof - offset) / linear
            # Keep only positive, finite results
            valid = np.isfinite(d) & (d > 0)
            d_out[valid] = d[valid]
        # If B == 0 too, there's no solution; leave NaN
        return d_out

    # 2) If quadratic term is significant, solve the quadratic equation:
    #    TOF = offset + linear * d + quad * d² =>
    #    quad * d² + linear * d + (offset - tof) = 0
    discr = linear**2 - 4 * quad * (offset - tof)
    has_real_roots = discr >= 0

    if np.any(has_real_roots):
        sqrt_discr = np.sqrt(discr[has_real_roots])

        root_1 = (-linear + sqrt_discr) / (2 * quad)
        root_2 = (-linear - sqrt_discr) / (2 * quad)

        # Pick smallest positive, finite root per element
        # Stack roots for comparison
        roots = np.stack((root_1, root_2), axis=0)
        # Replace non-finite or negative roots with NaN
        roots = np.where(np.isfinite(roots) & (roots > 0), roots, np.nan)
        # Choose the smallest positive root or NaN if none are valid
        chosen = np.nanmin(roots, axis=0)

        d_out[has_real_roots] = chosen

    return d_out

twotheta_to_d(twotheta, wavelength)

Convert 2-theta to d-spacing using Bragg's law.

Parameters:

Name	Type	Description	Default
twotheta	float or ndarray	2-theta angle in degrees.	required
wavelength	float	Wavelength in Å.	required

Returns:

Name	Type	Description
d	float or ndarray	d-spacing in Å.

Source code in src/easydiffraction/utils/utils.py

def twotheta_to_d(twotheta, wavelength):
    """Convert 2-theta to d-spacing using Bragg's law.

    Parameters:
        twotheta (float or np.ndarray): 2-theta angle in degrees.
        wavelength (float): Wavelength in Å.

    Returns:
        d (float or np.ndarray): d-spacing in Å.
    """
    # Convert twotheta from degrees to radians
    theta_rad = np.radians(twotheta / 2)

    # Calculate d-spacing using Bragg's law
    d = wavelength / (2 * np.sin(theta_rad))

    return d