Interfaces Module

The interfaces module provides command-line interface and shell completion functionality.

Command Line Interface

Command Line Interface for XRayLabTool.

This module provides a comprehensive CLI for calculating X-ray optical properties of materials, including single material calculations, batch processing, utility functions for X-ray analysis, and shell completion installation.

Available Commands:

calc Calculate X-ray properties for a single material batch Process multiple materials from CSV file compare Compare X-ray properties between multiple materials convert Convert between energy and wavelength units formula Parse and analyze chemical formulas atomic Look up atomic data for elements bragg Calculate Bragg angles for diffraction list List available data and information install-completion Install shell completion for xraylabtool uninstall-completion Remove shell completion for xraylabtool

The CLI supports various output formats (table, CSV, JSON), field filtering, precision control, and comprehensive shell completion for enhanced usability.

class xraylabtool.interfaces.cli.MemoryMonitor

Bases: object

__init__()

Return type:

None

update()

Return type:

None

print_summary()

Return type:

None

class xraylabtool.interfaces.cli.PerformanceMetrics

Bases: object

__init__()

Return type:

None

time_operation()

Return type:

Any

record_operations(count)

Return type:

None

Parameters:

count (int)

print_summary(verbose=False)

Return type:

None

Parameters:

verbose (bool)

class xraylabtool.interfaces.cli.AdaptiveChunkSizer

Bases: object

__init__()

Return type:

None

calculate_chunk_size(total)

Return type:

int

Parameters:

total (int)

xraylabtool.interfaces.cli.create_batch_progress_tracker(**kwargs)

Return type:

Any

Parameters:

kwargs (Any)

xraylabtool.interfaces.cli.create_parser()

Create the main argument parser with all subcommands.

Return type:

ArgumentParser

xraylabtool.interfaces.cli.add_calc_command(subparsers)

Add the ‘calc’ subcommand for single material calculations.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_batch_command(subparsers)

Add the ‘batch’ subcommand for processing multiple materials.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_convert_command(subparsers)

Add the ‘convert’ subcommand for unit conversions.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_formula_command(subparsers)

Add the ‘formula’ subcommand for formula parsing.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_atomic_command(subparsers)

Add the ‘atomic’ subcommand for atomic data lookup.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_bragg_command(subparsers)

Add the ‘bragg’ subcommand for Bragg angle calculations.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_list_command(subparsers)

Add the ‘list’ subcommand for listing available data.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_install_completion_command(subparsers)

Add the ‘install-completion’ subcommand for shell completion setup.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_completion_command(subparsers)

Add the ‘completion’ subcommand for the new completion system.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_uninstall_completion_command(subparsers)

Add the ‘uninstall-completion’ subcommand for shell completion removal.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.add_compare_command(subparsers)

Add the ‘compare’ subcommand for material comparison.

Return type:

None

Parameters:

subparsers (Any)

xraylabtool.interfaces.cli.parse_energy_string(energy_str)

Parse energy string and return numpy array.

Return type:

ndarray

Parameters:

energy_str (str)

xraylabtool.interfaces.cli.format_xray_result(result, format_type, precision=6, fields=None)

Format XRayResult for output.

Return type:

str

Parameters:

• result (Any)

• format_type (str)

• precision (int)

• fields (list[str] | None)

xraylabtool.interfaces.cli.cmd_calc(args)

Handle the ‘calc’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_batch(args)

Handle the ‘batch’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_convert(args)

Handle the ‘convert’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_formula(args)

Handle the ‘formula’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_atomic(args)

Handle the ‘atomic’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_bragg(args)

Handle the ‘bragg’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_list(args)

Handle the ‘list’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_install_completion(args)

Handle the ‘install-completion’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_uninstall_completion(args)

Handle the ‘uninstall-completion’ command.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_completion(args)

Handle the ‘completion’ command for the new completion system.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.cmd_compare(args)

Handle the ‘compare’ command for material comparison.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.cli.main()

Execute the main CLI application.

Return type:

int

CLI Commands Overview

XRayLabTool provides 9 CLI commands:

Command	Description
calc	Calculate X-ray properties for a single material
batch	Process multiple materials from CSV file
convert	Convert between energy and wavelength units
formula	Parse and analyze chemical formulas
atomic	Look up atomic scattering factor data
bragg	Calculate Bragg diffraction angles
list	Display reference information and constants
install-completion	Install shell completion (bash, zsh, fish, PowerShell)
uninstall-completion	Remove shell completion

Command Examples

Single Material Calculation:

# Basic calculation
xraylabtool calc Si --density 2.33 --energy 8000

# Multiple energies
xraylabtool calc SiO2 --density 2.20 --energy 5000,8000,10000

# Energy range
xraylabtool calc Al --density 2.70 --energy 1000-20000:100

# Different output formats
xraylabtool calc Si --density 2.33 --energy 8000 --output csv
xraylabtool calc Si --density 2.33 --energy 8000 --output json

Batch Processing:

# Process CSV file
xraylabtool batch materials.csv --output results.csv

# Specify energy column
xraylabtool batch data.csv --energy-column "Energy (eV)"

# JSON output
xraylabtool batch materials.csv --output results.json --format json

Unit Conversions:

# Energy to wavelength
xraylabtool convert --energy 8000 --to wavelength

# Wavelength to energy
xraylabtool convert --wavelength 1.55 --to energy

# Multiple values
xraylabtool convert --energy 5000,8000,10000 --to wavelength

Formula Analysis:

# Parse chemical formula
xraylabtool formula SiO2

# Complex formula
xraylabtool formula "Ca5(PO4)3F"

# With molecular weight
xraylabtool formula SiO2 --molecular-weight

Atomic Data Lookup:

# Element information
xraylabtool atomic Si

# Scattering factors at specific energy
xraylabtool atomic Si --energy 8000

# Multiple elements
xraylabtool atomic Si,Al,O --energy 8000

Bragg Diffraction:

# Calculate Bragg angle
xraylabtool bragg --d-spacing 3.14 --energy 8000

# Multiple reflections
xraylabtool bragg --d-spacing 3.14,1.92,1.64 --energy 8000

Reference Information:

# List supported elements
xraylabtool list elements

# Physical constants
xraylabtool list constants

# Example formulas
xraylabtool list examples

Output Formats

All commands support multiple output formats:

• table (default): Human-readable tabular format

• csv: Comma-separated values for spreadsheet import

• json: JSON format for programmatic processing

Shell Completion (Legacy Bridge)

Shell completion system for XRayLabTool.

This module provides a backward-compatible interface to the new virtual environment-centric completion system while maintaining the same API that the existing CLI expects.

class xraylabtool.interfaces.completion.CompletionInstaller

Bases: object

Handles virtual environment-centric completion installation.

__init__()

Return type:

None

install(shell=None, target_env=None, force=False)

Install completion in virtual environment.

Parameters:

• shell (str | None) – Shell type (bash, zsh, fish, powershell). Auto-detected if None.

• target_env (str | None) – Target environment name. Current environment if None.

• force (bool) – Force reinstallation if already installed.

Return type:

bool

Returns:

True if installation succeeded, False otherwise.

uninstall(target_env=None, all_envs=False)

Uninstall completion from environment(s).

Parameters:

• target_env (str | None) – Target environment name. Current environment if None.

• all_envs (bool) – Remove from all environments if True.

Return type:

bool

Returns:

True if uninstallation succeeded, False otherwise.

list_environments()

List all detected environments with completion status.

Return type:

None

status()

Show completion status for current environment.

Return type:

None

install_bash_completion(**kwargs)

Install bash completion (backward compatibility).

Return type:

bool

uninstall_bash_completion(**kwargs)

Uninstall bash completion (backward compatibility).

Return type:

bool

uninstall_completion(shell_type=None, cleanup_session=True, **kwargs)

Uninstall completion (backward compatibility).

Return type:

bool

test_completion()

Test completion functionality (backward compatibility).

Return type:

bool

get_bash_completion_dir()

Get bash completion directory (backward compatibility).

Return type:

Path

get_user_bash_completion_dir()

Get user bash completion directory (backward compatibility).

Return type:

Path

xraylabtool.interfaces.completion.install_completion_main(args)

Legacy install completion main function with new system backend.

This function maintains backward compatibility with the existing CLI while using the new completion system internally.

Return type:

int

Parameters:

args (Namespace)

xraylabtool.interfaces.completion.uninstall_completion_main(args)

Legacy uninstall completion main function with new system backend.

Return type:

int

Parameters:

args (Any)

Shell Completion v2

The completion_v2 sub-package is the current virtual-environment-centric completion system, replacing the legacy bridge above.

Virtual environment-centric completion installer.

This module handles installation and management of shell completion that activates/deactivates with virtual environment changes.

class xraylabtool.interfaces.completion_v2.installer.CompletionInstaller

Bases: object

Handles virtual environment-centric completion installation.

__init__()

Return type:

None

install(shell=None, target_env=None, force=False)

Install completion in virtual environment.

Parameters:

• shell (str | None) – Shell type (bash, zsh, fish, powershell). Auto-detected if None.

• target_env (str | None) – Target environment name. Current environment if None.

• force (bool) – Force reinstallation if already installed.

Return type:

bool

Returns:

True if installation succeeded, False otherwise.

uninstall(target_env=None, all_envs=False)

Uninstall completion from environment(s).

Parameters:

• target_env (str | None) – Target environment name. Current environment if None.

• all_envs (bool) – Remove from all environments if True.

Return type:

bool

Returns:

True if uninstallation succeeded, False otherwise.

list_environments()

List all detected environments with completion status.

Return type:

None

status()

Show completion status for current environment.

Return type:

None

install_bash_completion(**kwargs)

Install bash completion (backward compatibility).

Return type:

bool

uninstall_bash_completion(**kwargs)

Uninstall bash completion (backward compatibility).

Return type:

bool

uninstall_completion(shell_type=None, cleanup_session=True, **kwargs)

Uninstall completion (backward compatibility).

Return type:

bool

test_completion()

Test completion functionality (backward compatibility).

Return type:

bool

get_bash_completion_dir()

Get bash completion directory (backward compatibility).

Return type:

Path

get_user_bash_completion_dir()

Get user bash completion directory (backward compatibility).

Return type:

Path

Shell-specific completion script generators.

This module provides modular completion script generation for different shells, replacing the large hardcoded strings with template-based generation.

class xraylabtool.interfaces.completion_v2.shells.CompletionGenerator(command_name='xraylabtool')

Bases: ABC

Base class for shell completion generators.

Parameters:

command_name (str)

__init__(command_name='xraylabtool')

Parameters:

command_name (str)

abstractmethod generate(commands, global_options)

Generate completion script for this shell.

Return type:

str

Parameters:

• commands (dict[str, dict[str, Any]])

• global_options (list[str])

abstract property shell_name: str

Name of the shell this generator supports.

abstract property file_extension: str

File extension for completion scripts.

class xraylabtool.interfaces.completion_v2.shells.BashCompletionGenerator(command_name='xraylabtool')

Bases: CompletionGenerator

Generates Bash completion scripts.

Parameters:

command_name (str)

property shell_name: str

Name of the shell this generator supports.

property file_extension: str

File extension for completion scripts.

generate(commands, global_options)

Generate Bash completion script.

Return type:

str

Parameters:

• commands (dict[str, dict[str, Any]])

• global_options (list[str])

class xraylabtool.interfaces.completion_v2.shells.ZshCompletionGenerator(command_name='xraylabtool')

Bases: CompletionGenerator

Generates native Zsh completion scripts.

Parameters:

command_name (str)

property shell_name: str

Name of the shell this generator supports.

property file_extension: str

File extension for completion scripts.

generate(commands, global_options)

Generate native Zsh completion script.

Return type:

str

Parameters:

• commands (dict[str, dict[str, Any]])

• global_options (list[str])

class xraylabtool.interfaces.completion_v2.shells.FishCompletionGenerator(command_name='xraylabtool')

Bases: CompletionGenerator

Generates Fish shell completion scripts.

Parameters:

command_name (str)

property shell_name: str

Name of the shell this generator supports.

property file_extension: str

File extension for completion scripts.

generate(commands, global_options)

Generate Fish completion script.

Return type:

str

Parameters:

• commands (dict[str, dict[str, Any]])

• global_options (list[str])

class xraylabtool.interfaces.completion_v2.shells.PowerShellCompletionGenerator(command_name='xraylabtool')

Bases: CompletionGenerator

Generates PowerShell completion scripts.

Parameters:

command_name (str)

property shell_name: str

Name of the shell this generator supports.

property file_extension: str

File extension for completion scripts.

generate(commands, global_options)

Generate PowerShell completion script.

Return type:

str

Parameters:

• commands (dict[str, dict[str, Any]])

• global_options (list[str])

class xraylabtool.interfaces.completion_v2.shells.CompletionManager

Bases: object

Manages completion script generation for all supported shells.

__init__()

Return type:

None

get_supported_shells()

Get list of supported shell types.

Return type:

list[str]

generate_completion(shell, commands, global_options)

Generate completion script for specified shell.

Return type:

str

Parameters:

• shell (str)

• commands (dict[str, dict[str, Any]])

• global_options (list[str])

get_filename(shell, command_name='xraylabtool')

Get the appropriate filename for a completion script.

Return type:

str

Parameters:

• shell (str)

• command_name (str)

xraylabtool.interfaces.completion_v2.shells.get_xraylabtool_commands()

Get the XRayLabTool command definitions for completion.

Return type:

dict[str, dict[str, Any]]

xraylabtool.interfaces.completion_v2.shells.get_global_options()

Get global options available for all commands.

Return type:

list[str]

Environment detection and management for shell completion.

This module provides robust detection of Python virtual environments and manages completion activation/deactivation based on environment state.

class xraylabtool.interfaces.completion_v2.environment.EnvironmentType

Bases: object

Constants for environment types.

SYSTEM = 'system'

VENV = 'venv'

VIRTUALENV = 'virtualenv'

CONDA = 'conda'

MAMBA = 'mamba'

PIPENV = 'pipenv'

POETRY = 'poetry'

class xraylabtool.interfaces.completion_v2.environment.EnvironmentInfo(env_type, path, name, is_active=False, python_version=None, has_completion=False)

Bases: object

Information about a detected environment.

Parameters:

• env_type (str)

• path (Path)

• name (str)

• is_active (bool)

• python_version (str | None)

• has_completion (bool)

__init__(env_type, path, name, is_active=False, python_version=None, has_completion=False)

Parameters:

• env_type (str)

• path (Path)

• name (str)

• is_active (bool)

• python_version (str | None)

• has_completion (bool)

to_dict()

Convert to dictionary for serialization.

Return type:

dict[str, Any]

classmethod from_dict(data)

Create from dictionary.

Return type:

EnvironmentInfo

Parameters:

data (dict[str, Any])

class xraylabtool.interfaces.completion_v2.environment.EnvironmentDetector

Bases: object

Detects and manages Python virtual environments.

__init__()

Return type:

None

get_current_environment()

Get information about the currently active environment.

Return type:

EnvironmentInfo | None

discover_all_environments(use_cache=True)

Discover all available Python environments.

Return type:

list[EnvironmentInfo]

Parameters:

use_cache (bool)

clear_cache()

Clear the environment cache.

Return type:

None

Performance optimizations and caching for shell completion.

This module provides caching mechanisms and performance optimizations to make completion faster and more responsive.

class xraylabtool.interfaces.completion_v2.cache.CompletionCache(cache_dir=None)

Bases: object

Fast caching system for completion data.

Parameters:

cache_dir (Path | None)

__init__(cache_dir=None)

Parameters:

cache_dir (Path | None)

get_cache_key(data)

Generate cache key from data.

Return type:

str

Parameters:

data (Any)

get(key, timeout=None)

Get cached data by key.

Return type:

Any | None

Parameters:

• key (str)

• timeout (int | None)

set(key, data, metadata=None)

Cache data with optional metadata.

Return type:

None

Parameters:

• key (str)

• data (Any)

• metadata (dict[str, Any] | None)

invalidate(key)

Invalidate cached data.

Return type:

None

Parameters:

key (str)

clear()

Clear all cached data.

Return type:

None

get_cache_stats()

Get cache statistics.

Return type:

dict[str, Any]

class xraylabtool.interfaces.completion_v2.cache.CompletionDataManager

Bases: object

Manages and caches completion data for fast access.

__init__()

Return type:

None

get_commands(force_refresh=False)

Get command definitions with caching.

Return type:

dict[str, dict[str, Any]]

Parameters:

force_refresh (bool)

get_global_options(force_refresh=False)

Get global options with caching.

Return type:

list[str]

Parameters:

force_refresh (bool)

get_completion_script(shell, force_refresh=False)

Get cached completion script for shell.

Return type:

str | None

Parameters:

• shell (str)

• force_refresh (bool)

cache_completion_script(shell, script)

Cache completion script for shell.

Return type:

None

Parameters:

• shell (str)

• script (str)

invalidate_command_cache()

Invalidate command-related caches.

Return type:

None

class xraylabtool.interfaces.completion_v2.cache.FastCompletionProvider

Bases: object

Optimized completion provider for runtime performance.

__init__()

Return type:

None

get_command_completions(partial_command)

Get command completions for partial input.

Return type:

list[str]

Parameters:

partial_command (str)

get_option_completions(command, partial_option)

Get option completions for a command.

Return type:

list[str]

Parameters:

• command (str)

• partial_option (str)

get_file_completions(partial_path)

Get file path completions (optimized).

Return type:

list[str]

Parameters:

partial_path (str)

warm_cache()

Pre-warm caches for better performance.

Return type:

None

class xraylabtool.interfaces.completion_v2.cache.PerformanceMonitor

Bases: object

Monitor completion performance for optimization.

__init__()

Return type:

None

record_completion_time(duration)

Record completion timing.

Return type:

None

Parameters:

duration (float)

record_cache_hit()

Record cache hit.

Return type:

None

record_cache_miss()

Record cache miss.

Return type:

None

get_stats()

Get performance statistics.

Return type:

dict[str, Any]

xraylabtool.interfaces.completion_v2.cache.get_data_manager()

Get global completion data manager instance.

Return type:

CompletionDataManager

xraylabtool.interfaces.completion_v2.cache.get_performance_monitor()

Get global performance monitor instance.

Return type:

PerformanceMonitor

Integration layer for the new completion system.

This module provides backward compatibility and integration with the existing CLI while gradually migrating to the new virtual environment-centric completion system.

xraylabtool.interfaces.completion_v2.integration.legacy_install_completion_main(args)

Legacy install completion main function with new system backend.

This function maintains backward compatibility with the existing CLI while using the new completion system internally.

Return type:

int

Parameters:

args (Namespace)

xraylabtool.interfaces.completion_v2.integration.legacy_uninstall_completion_main(args)

Legacy uninstall completion main function with new system backend.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.completion_v2.integration.test_completion_installation()

Test if completion is working in the current environment.

Return type:

int

xraylabtool.interfaces.completion_v2.integration.handle_new_completion_command(args)

Handle new ‘completion’ subcommand.

Return type:

int

Parameters:

args (list[str])

xraylabtool.interfaces.completion_v2.integration.install_completion_main(args)

Legacy install completion main function with new system backend.

This function maintains backward compatibility with the existing CLI while using the new completion system internally.

Return type:

int

Parameters:

args (Namespace)

xraylabtool.interfaces.completion_v2.integration.uninstall_completion_main(args)

Legacy uninstall completion main function with new system backend.

Return type:

int

Parameters:

args (Any)

Command-line interface for the new completion system.

This module provides CLI commands for managing the virtual environment-centric shell completion system.

xraylabtool.interfaces.completion_v2.cli.create_completion_parser()

Create argument parser for completion commands.

Return type:

ArgumentParser

xraylabtool.interfaces.completion_v2.cli.handle_completion_command(args)

Handle completion subcommands.

Return type:

int

Parameters:

args (Namespace)

xraylabtool.interfaces.completion_v2.cli.show_completion_info()

Show information about the completion system.

Return type:

None

xraylabtool.interfaces.completion_v2.cli.completion_main(args=None)

Main entry point for completion commands.

Return type:

int

Parameters:

args (Any)

xraylabtool.interfaces.completion_v2.cli.install_completion_main(args)

Legacy install completion main function.

Return type:

int

Parameters:

args (Namespace)

xraylabtool.interfaces.completion_v2.cli.uninstall_completion_main(args)

Legacy uninstall completion main function.

Return type:

int

Parameters:

args (Any)

Bash Completion Features

The shell completion system provides:

• Command completion: All 9 CLI commands

• Option completion: Command flags and parameters

• File completion: Input/output file paths

• Element completion: Chemical element symbols

• Unit completion: Energy and wavelength units

Installation

# Install completion for current user
xraylabtool install-completion

# Install system-wide (requires sudo)
sudo xraylabtool install-completion --system

# Custom completion script location
xraylabtool install-completion --path /custom/path

Usage

After installation, completion is available by pressing Tab:

xraylabtool [TAB]          # Shows all commands
xraylabtool calc [TAB]     # Shows calc command options
xraylabtool atomic S[TAB]  # Completes to supported elements starting with 'S'

Uninstallation

# Remove completion
xraylabtool uninstall-completion

# Remove system-wide completion
sudo xraylabtool uninstall-completion --system

Platform Support

Shell completion is supported for:

• Bash: Full support on Linux and macOS (requires bash-completion)

• Zsh: Full support on Linux and macOS (requires zsh-completions)

• Fish: Native support with built-in completion system

• PowerShell: Full support on Windows, macOS, and Linux

Error Handling

The CLI provides error handling with helpful messages:

# Invalid formula
$ xraylabtool calc XYZ --density 1.0 --energy 8000
Error: Unknown element 'XYZ' in formula

# Missing required parameter
$ xraylabtool calc Si --energy 8000
Error: --density is required

# Invalid energy range
$ xraylabtool calc Si --density 2.33 --energy 0
Error: Energy must be positive

Integration Examples

With Python Scripts:

import subprocess
import json

# Call CLI from Python
result = subprocess.run([
    "xraylabtool", "calc", "Si",
    "--density", "2.33",
    "--energy", "8000",
    "--output", "json"
], capture_output=True, text=True)

data = json.loads(result.stdout)
print(f"Critical angle: {data[0]['critical_angle_degrees']}")

With Shell Scripts:

#!/bin/bash

# Process multiple materials
for material in Si Al Cu; do
    echo "Processing $material..."
    xraylabtool calc $material --density 2.33 --energy 8000 --output csv >> results.csv
done