usel 1.0.4__py3-none-any.whl

usel/__init__.py

@@ -0,0 +1,22 @@
+"""usel: an open-source, CPU-only scientific computing framework.
+
+This package provides the mathematical and computational foundation for
+quantum mechanics, relativistic quantum mechanics, and computational
+electromagnetics:
+
+- Reusable matrix and linear algebra utilities
+- Numerical solvers (root finding, ODEs, integration)
+- FFT based frequency analysis
+- Schrödinger equation solvers (bound states, wave-packet propagation)
+- Dirac equation solvers (relativistic spinors, Pauli/Dirac matrices)
+- Maxwell equation solvers (2D FDTD, electrostatics)
+- Random number and matrix generation
+- Configuration, IO, logging, and validation utilities
+- A command line interface (``usel``)
+"""
+
+from __future__ import annotations
+
+__version__ = "1.1.0"
+__license__ = "MIT"
+__all__ = ["__version__", "__license__"]

usel/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command line interface for usel."""
+
+from __future__ import annotations
+
+from usel.cli.main import main
+
+__all__ = ["main"]

usel/cli/main.py

@@ -0,0 +1,151 @@
+"""usel command line interface.
+
+Commands
+--------
+usel version     Print the installed usel version.
+usel doctor       Check environment health (Python version, dependencies).
+usel benchmark    Run a quick matrix-multiplication benchmark.
+usel info         Print platform and package information.
+usel config       Show or validate a configuration file.
+usel test         Run the test suite via pytest.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import platform
+import subprocess
+import sys
+import time
+from collections.abc import Sequence
+
+import usel
+from usel.math.matrix import Matrix
+
+_REQUIRED_PACKAGES = ("numpy", "scipy", "sympy")
+
+
+def _cmd_version(_: argparse.Namespace) -> int:
+    print(f"usel version {usel.__version__}")
+    return 0
+
+
+def _cmd_info(_: argparse.Namespace) -> int:
+    print("usel Info")
+    print("-" * 40)
+    print(f"Version:        {usel.__version__}")
+    print(f"License:        {usel.__license__}")
+    print(f"Python:         {platform.python_version()}")
+    print(f"Platform:       {platform.platform()}")
+    print(f"Processor:      {platform.processor() or 'unknown'}")
+    return 0
+
+
+def _cmd_doctor(_: argparse.Namespace) -> int:
+    print("Running usel environment check...")
+    ok = True
+
+    major, minor = sys.version_info[:2]
+    if (major, minor) >= (3, 11):
+        print(f"[OK]   Python version {major}.{minor} >= 3.11")
+    else:
+        print(f"[FAIL] Python version {major}.{minor} < 3.11")
+        ok = False
+
+    for package in _REQUIRED_PACKAGES:
+        try:
+            importlib.import_module(package)
+            print(f"[OK]   Dependency '{package}' is importable")
+        except ImportError:
+            print(f"[FAIL] Dependency '{package}' is missing")
+            ok = False
+
+    if ok:
+        print("\nAll checks passed. usel is ready to use.")
+    else:
+        print("\nSome checks failed. Please review the output above.")
+    return 0 if ok else 1
+
+
+def _cmd_benchmark(args: argparse.Namespace) -> int:
+    size = args.size
+    print(f"Benchmarking {size}x{size} matrix multiplication...")
+    a = Matrix.random(size, size, seed=42)
+    b = Matrix.random(size, size, seed=43)
+
+    start = time.perf_counter()
+    _ = a @ b
+    elapsed = time.perf_counter() - start
+
+    print(f"Completed in {elapsed:.6f} seconds")
+    return 0
+
+
+def _cmd_config(args: argparse.Namespace) -> int:
+    from usel.config.loader import load_config
+
+    try:
+        data = load_config(args.path)
+    except Exception as exc:  # noqa: BLE001
+        print(f"[FAIL] Could not load configuration: {exc}")
+        return 1
+
+    print(f"[OK] Configuration file '{args.path}' loaded successfully")
+    print(f"Keys: {sorted(data.keys())}")
+    return 0
+
+
+def _cmd_test(args: argparse.Namespace) -> int:
+    cmd = [sys.executable, "-m", "pytest"]
+    if args.path:
+        cmd.append(args.path)
+    result = subprocess.run(cmd, check=False)  # noqa: S603
+    return result.returncode
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build and return the usel argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="usel", description="usel: CPU-only scientific computing framework"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("version", help="Print the installed usel version").set_defaults(
+        func=_cmd_version
+    )
+    subparsers.add_parser("info", help="Print platform and package information").set_defaults(
+        func=_cmd_info
+    )
+    subparsers.add_parser(
+        "doctor", help="Check environment health (Python version, dependencies)"
+    ).set_defaults(func=_cmd_doctor)
+
+    benchmark_parser = subparsers.add_parser(
+        "benchmark", help="Run a quick matrix-multiplication benchmark"
+    )
+    benchmark_parser.add_argument(
+        "--size", type=int, default=200, help="Matrix dimension for the benchmark (default: 200)"
+    )
+    benchmark_parser.set_defaults(func=_cmd_benchmark)
+
+    config_parser = subparsers.add_parser("config", help="Load and validate a configuration file")
+    config_parser.add_argument("path", help="Path to a .yaml, .json, or .toml configuration file")
+    config_parser.set_defaults(func=_cmd_config)
+
+    test_parser = subparsers.add_parser("test", help="Run the test suite via pytest")
+    test_parser.add_argument("path", nargs="?", default=None, help="Optional test path filter")
+    test_parser.set_defaults(func=_cmd_test)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """usel CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

usel/config/__init__.py

@@ -0,0 +1,7 @@
+"""Configuration loading and saving for YAML, JSON, and TOML formats."""
+
+from __future__ import annotations
+
+from usel.config.loader import load_config, save_config
+
+__all__ = ["load_config", "save_config"]

usel/config/loader.py

@@ -0,0 +1,70 @@
+"""Load and save configuration files in YAML, JSON, or TOML format.
+
+The format is inferred from the file extension: ``.yaml``/``.yml``,
+``.json``, or ``.toml``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from usel.exceptions import ConfigError
+
+_SUPPORTED_SUFFIXES = {".yaml", ".yml", ".json", ".toml"}
+
+
+def load_config(filepath: str | Path) -> dict[str, Any]:
+    """Load a configuration file, inferring the format from its extension."""
+    path = Path(filepath)
+    if not path.exists():
+        raise ConfigError(f"Configuration file not found: {path}")
+    if path.suffix not in _SUPPORTED_SUFFIXES:
+        raise ConfigError(
+            f"Unsupported configuration format '{path.suffix}'. "
+            f"Supported formats: {sorted(_SUPPORTED_SUFFIXES)}"
+        )
+
+    try:
+        text = path.read_text(encoding="utf-8")
+        if path.suffix in (".yaml", ".yml"):
+            import yaml
+
+            data = yaml.safe_load(text) or {}
+        elif path.suffix == ".json":
+            data = json.loads(text) if text.strip() else {}
+        else:  # .toml
+            import toml
+
+            data = toml.loads(text)
+    except Exception as exc:  # noqa: BLE001 - re-raised as ConfigError
+        raise ConfigError(f"Failed to parse configuration file {path}: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError(f"Configuration root must be a mapping/object, got {type(data).__name__}")
+    return data
+
+
+def save_config(data: dict[str, Any], filepath: str | Path) -> None:
+    """Save a configuration dictionary, inferring the format from its extension."""
+    path = Path(filepath)
+    if path.suffix not in _SUPPORTED_SUFFIXES:
+        raise ConfigError(
+            f"Unsupported configuration format '{path.suffix}'. "
+            f"Supported formats: {sorted(_SUPPORTED_SUFFIXES)}"
+        )
+
+    try:
+        if path.suffix in (".yaml", ".yml"):
+            import yaml
+
+            path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+        elif path.suffix == ".json":
+            path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        else:  # .toml
+            import toml
+
+            path.write_text(toml.dumps(data), encoding="utf-8")
+    except Exception as exc:  # noqa: BLE001 - re-raised as ConfigError
+        raise ConfigError(f"Failed to write configuration file {path}: {exc}") from exc

usel/exceptions/__init__.py

@@ -0,0 +1,45 @@
+"""Custom exception hierarchy for usel."""
+
+from __future__ import annotations
+
+
+class uselError(Exception):
+    """Base exception for all usel errors."""
+
+
+class MatrixError(uselError):
+    """Raised for invalid matrix operations (shape mismatch, singularity, etc.)."""
+
+
+class SolverError(uselError):
+    """Raised when a numerical solver fails to converge or receives bad input."""
+
+
+class ConfigError(uselError):
+    """Raised for configuration loading, parsing, or validation failures."""
+
+
+class ValidationError(uselError):
+    """Raised when input validation fails."""
+
+
+class IOError_(uselError):
+    """Raised for file input/output failures.
+
+    Named ``IOError_`` to avoid shadowing the Python builtin ``IOError``.
+    """
+
+
+class PhysicsError(uselError):
+    """Raised when a physics simulation encounters invalid parameters or diverges."""
+
+
+__all__ = [
+    "uselError",
+    "MatrixError",
+    "SolverError",
+    "ConfigError",
+    "ValidationError",
+    "IOError_",
+    "PhysicsError",
+]

usel/io/__init__.py

@@ -0,0 +1,17 @@
+"""File input/output utilities: CSV, JSON, NumPy binary, and plain text."""
+
+from __future__ import annotations
+
+from usel.io.readers import read_csv, read_json, read_npy, read_text
+from usel.io.writers import write_csv, write_json, write_npy, write_text
+
+__all__ = [
+    "read_csv",
+    "read_json",
+    "read_npy",
+    "read_text",
+    "write_csv",
+    "write_json",
+    "write_npy",
+    "write_text",
+]

usel/io/readers.py

@@ -0,0 +1,55 @@
+"""Readers for CSV, JSON, NumPy binary (.npy/.npz), and plain text files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from usel.exceptions import IOError_
+
+
+def read_csv(filepath: str | Path, delimiter: str = ",", skip_header: int = 0) -> np.ndarray:
+    """Read a CSV file into a NumPy array."""
+    path = Path(filepath)
+    if not path.exists():
+        raise IOError_(f"CSV file not found: {path}")
+    try:
+        return np.genfromtxt(path, delimiter=delimiter, skip_header=skip_header, dtype=float)
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to read CSV file {path}: {exc}") from exc
+
+
+def read_json(filepath: str | Path) -> Any:
+    """Read a JSON file and return the parsed object."""
+    path = Path(filepath)
+    if not path.exists():
+        raise IOError_(f"JSON file not found: {path}")
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to read JSON file {path}: {exc}") from exc
+
+
+def read_npy(filepath: str | Path) -> np.ndarray:
+    """Read a NumPy binary (.npy) file into an array."""
+    path = Path(filepath)
+    if not path.exists():
+        raise IOError_(f"NumPy binary file not found: {path}")
+    try:
+        return np.load(path, allow_pickle=False)
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to read .npy file {path}: {exc}") from exc
+
+
+def read_text(filepath: str | Path, encoding: str = "utf-8") -> str:
+    """Read a plain text file and return its contents as a string."""
+    path = Path(filepath)
+    if not path.exists():
+        raise IOError_(f"Text file not found: {path}")
+    try:
+        return path.read_text(encoding=encoding)
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to read text file {path}: {exc}") from exc

usel/io/writers.py

@@ -0,0 +1,47 @@
+"""Writers for CSV, JSON, NumPy binary (.npy), and plain text files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from usel.exceptions import IOError_
+
+
+def write_csv(data: np.ndarray, filepath: str | Path, delimiter: str = ",") -> None:
+    """Write a NumPy array to a CSV file."""
+    path = Path(filepath)
+    try:
+        np.savetxt(path, np.asarray(data), delimiter=delimiter)
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to write CSV file {path}: {exc}") from exc
+
+
+def write_json(data: Any, filepath: str | Path, indent: int = 2) -> None:
+    """Write a JSON-serializable object to a file."""
+    path = Path(filepath)
+    try:
+        path.write_text(json.dumps(data, indent=indent), encoding="utf-8")
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to write JSON file {path}: {exc}") from exc
+
+
+def write_npy(data: np.ndarray, filepath: str | Path) -> None:
+    """Write a NumPy array to a .npy binary file."""
+    path = Path(filepath)
+    try:
+        np.save(path, np.asarray(data))
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to write .npy file {path}: {exc}") from exc
+
+
+def write_text(content: str, filepath: str | Path, encoding: str = "utf-8") -> None:
+    """Write a string to a plain text file."""
+    path = Path(filepath)
+    try:
+        path.write_text(content, encoding=encoding)
+    except Exception as exc:  # noqa: BLE001
+        raise IOError_(f"Failed to write text file {path}: {exc}") from exc

usel/linalg/__init__.py

@@ -0,0 +1,14 @@
+"""Linear algebra utilities: eigen decompositions, SVD, QR, LU, Cholesky."""
+
+from __future__ import annotations
+
+from usel.linalg.decompositions import (
+    cholesky,
+    eigenvalues,
+    eigenvectors,
+    lu,
+    qr,
+    svd,
+)
+
+__all__ = ["eigenvalues", "eigenvectors", "svd", "qr", "lu", "cholesky"]

usel/linalg/decompositions.py

@@ -0,0 +1,42 @@
+"""Functional wrappers around common matrix decompositions.
+
+These functions accept and return :class:`usel.math.Matrix` instances
+(or raw NumPy arrays where noted), providing a functional API alongside the
+object-oriented methods already available on ``Matrix``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from usel.math.matrix import Matrix
+
+
+def eigenvalues(matrix: Matrix) -> np.ndarray:
+    """Return the eigenvalues of a square matrix."""
+    return matrix.eigenvalues()
+
+
+def eigenvectors(matrix: Matrix) -> tuple[np.ndarray, Matrix]:
+    """Return (eigenvalues, eigenvectors) of a square matrix."""
+    return matrix.eigenvectors()
+
+
+def svd(matrix: Matrix) -> tuple[Matrix, np.ndarray, Matrix]:
+    """Singular value decomposition. Returns (U, singular_values, Vt)."""
+    return matrix.decompose_svd()
+
+
+def qr(matrix: Matrix) -> tuple[Matrix, Matrix]:
+    """QR decomposition. Returns (Q, R)."""
+    return matrix.decompose_qr()
+
+
+def lu(matrix: Matrix) -> tuple[Matrix, Matrix, Matrix]:
+    """LU decomposition with partial pivoting. Returns (P, L, U)."""
+    return matrix.decompose_lu()
+
+
+def cholesky(matrix: Matrix) -> Matrix:
+    """Cholesky decomposition for symmetric positive-definite matrices."""
+    return matrix.decompose_cholesky()

usel/logging/__init__.py

@@ -0,0 +1,12 @@
+"""Logging utilities: console logger, file logger, debug mode, performance logger."""
+
+from __future__ import annotations
+
+from usel.logging.logger import (
+    PerformanceLogger,
+    get_console_logger,
+    get_file_logger,
+    set_debug_mode,
+)
+
+__all__ = ["get_console_logger", "get_file_logger", "set_debug_mode", "PerformanceLogger"]

usel/logging/logger.py

@@ -0,0 +1,74 @@
+"""Console and file loggers, debug mode toggling, and a performance logger."""
+
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+
+_DEFAULT_FORMAT = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+
+
+def get_console_logger(name: str = "usel", level: int = logging.INFO) -> logging.Logger:
+    """Return a logger configured to write formatted messages to the console."""
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    if not any(isinstance(h, logging.StreamHandler) for h in logger.handlers):
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT))
+        logger.addHandler(handler)
+    return logger
+
+
+def get_file_logger(
+    name: str = "usel", filepath: str | Path = "usel.log", level: int = logging.INFO
+) -> logging.Logger:
+    """Return a logger configured to write formatted messages to a file."""
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    path = Path(filepath)
+    if not any(
+        isinstance(h, logging.FileHandler) and h.baseFilename == str(path.resolve())
+        for h in logger.handlers
+    ):
+        handler = logging.FileHandler(path)
+        handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT))
+        logger.addHandler(handler)
+    return logger
+
+
+def set_debug_mode(logger: logging.Logger, enabled: bool = True) -> None:
+    """Toggle debug-level verbosity on the given logger."""
+    logger.setLevel(logging.DEBUG if enabled else logging.INFO)
+
+
+class PerformanceLogger:
+    """A simple named-checkpoint performance logger.
+
+    Examples
+    --------
+    >>> perf = PerformanceLogger()
+    >>> perf.checkpoint("start")
+    >>> perf.checkpoint("end")
+    >>> perf.report()['start'] >= 0
+    True
+    """
+
+    def __init__(self) -> None:
+        self._checkpoints: dict[str, float] = {}
+        self._start = time.perf_counter()
+
+    def checkpoint(self, label: str) -> float:
+        """Record a checkpoint and return elapsed seconds since construction."""
+        elapsed = time.perf_counter() - self._start
+        self._checkpoints[label] = elapsed
+        return elapsed
+
+    def report(self) -> dict[str, float]:
+        """Return a mapping of checkpoint labels to elapsed seconds."""
+        return dict(self._checkpoints)
+
+    def reset(self) -> None:
+        """Reset the performance logger's start time and checkpoints."""
+        self._checkpoints.clear()
+        self._start = time.perf_counter()

usel/math/__init__.py

@@ -0,0 +1,8 @@
+"""Reusable numerical utilities: matrix creation, algebra, norms, transforms."""
+
+from __future__ import annotations
+
+from usel.math.matrix import Matrix
+from usel.math.transforms import fft, frequency_analysis, ifft
+
+__all__ = ["Matrix", "fft", "ifft", "frequency_analysis"]