usel 1.0.4__tar.gz

usel-1.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goutam Parashuram Gotur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

usel-1.0.4/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: usel
+Version: 1.0.4
+Summary: An open-source, CPU-only scientific computing framework focused on quantum physics simulations and numerical methods.
+Author: Goutam Parashuram Gotur, K R Raaghavindhra
+License: MIT
+Project-URL: Homepage, https://github.com/goutam-tech/usel
+Project-URL: Repository, https://github.com/goutam-tech/usel
+Project-URL: Documentation, https://goutam-tech.github.io/usel
+Keywords: scientific-computing,numerical-methods,physics,linear-algebra,computational-physics,dirac-equation,mathematics,open-source,quantum-mechanics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: sympy>=1.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: matplotlib>=3.8
+Dynamic: license-file
+
+# USEL
+
+USEL () is an open-source, CPU-only scientific computing framework focused on
+quantum physics simulations and numerical methods.
+
+Version 1.0 establishes the mathematical and computational foundation —
+matrix and linear algebra utilities, numerical solvers, FFT-based frequency
+analysis, random number generation, configuration/IO/logging utilities, and a
+CLI — for future quantum mechanics, computational physics, and quantum
+information modules.
+
+## Features
+
+- Runs efficiently on standard consumer hardware, no GPU required
+- Operates within 8 GB RAM
+- Cross-platform (Windows, Linux, macOS)
+- Modular, extensible architecture
+- Fully typed, PEP 8 compliant codebase
+
+## Installation
+
+```bash
+uv sync
+uv run usel version
+```
+
+Or, for local development:
+
+```bash
+git clone https://github.com/usel/usel.git
+cd usel
+uv sync --group dev
+```
+
+See the [examples](examples/) directory for more, including eigenvalue
+solving, ODE integration, FFT analysis, and numerical integration.
+
+## Command Line Interface
+
+```bash
+uv run usel version
+uv run usel doctor
+uv run usel benchmark --size 200
+uv run usel info
+uv run usel config path/to/config.yaml
+uv run usel test
+```
+
+## Modules
+
+| Module         | Description                                      |
+| -------------- | ------------------------------------------------ |
+| `usel.math`    | Matrix creation, algebra, norms, FFT transforms  |
+| `usel.linalg`  | Eigenvalues/vectors, SVD, QR, LU, Cholesky       |
+| `usel.solvers` | Root finding, ODE solvers, numerical integration |
+| `usel.random`  | Random matrices, vectors, and distributions      |
+| `usel.utils`   | Timing, profiling, validation, precision control |
+| `usel.logging` | Console/file loggers, performance logger         |
+| `usel.config`  | YAML/JSON/TOML configuration loading             |
+| `usel.io`      | CSV/JSON/NumPy binary/text file I/O              |
+| `usel.cli`     | Command line interface                           |
+
+## Non-Goals (v1.0)
+
+This release intentionally excludes the Schrödinger equation, quantum
+circuits/gates/qubits, machine learning, chemistry simulation, GPU/cloud
+computing, and AI integration. These are planned for future releases (see
+[CHANGELOG.md](CHANGELOG.md) and the roadmap below).
+
+## Roadmap
+
+- v1.0 — Scientific Computing Foundation
+  - Core numerical engine
+  - Linear algebra utilities
+  - Matrix operations
+  - Numerical solvers
+  - FFT and mathematical utilities
+  - Configuration, logging, and CLI support
+
+- v2.0 — Quantum Physics Engine
+  - Schrödinger equation module
+  - Quantum wavefunction utilities
+  - Potential models
+  - Hamiltonian construction
+  - Time evolution and visualization
+
+- v3.0 — Relativistic & Computational Physics
+  - Dirac equation module
+  - Spinor algebra
+  - Gamma matrix operations
+  - Relativistic particle simulations
+  - Maxwell equation module
+  - Electromagnetic field simulations
+
+Still more planning is going on this.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv run black --check .
+uv run mypy src
+```
+
+## Documentation
+
+Full documentation is built with MkDocs:
+
+```bash
+uv run mkdocs serve
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for
+guidelines.
+
+## Security
+
+usel performs no telemetry, no network communication, and no data
+collection. It is fully offline capable.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

usel-1.0.4/README.md

@@ -0,0 +1,127 @@
+# USEL
+
+USEL () is an open-source, CPU-only scientific computing framework focused on
+quantum physics simulations and numerical methods.
+
+Version 1.0 establishes the mathematical and computational foundation —
+matrix and linear algebra utilities, numerical solvers, FFT-based frequency
+analysis, random number generation, configuration/IO/logging utilities, and a
+CLI — for future quantum mechanics, computational physics, and quantum
+information modules.
+
+## Features
+
+- Runs efficiently on standard consumer hardware, no GPU required
+- Operates within 8 GB RAM
+- Cross-platform (Windows, Linux, macOS)
+- Modular, extensible architecture
+- Fully typed, PEP 8 compliant codebase
+
+## Installation
+
+```bash
+uv sync
+uv run usel version
+```
+
+Or, for local development:
+
+```bash
+git clone https://github.com/usel/usel.git
+cd usel
+uv sync --group dev
+```
+
+See the [examples](examples/) directory for more, including eigenvalue
+solving, ODE integration, FFT analysis, and numerical integration.
+
+## Command Line Interface
+
+```bash
+uv run usel version
+uv run usel doctor
+uv run usel benchmark --size 200
+uv run usel info
+uv run usel config path/to/config.yaml
+uv run usel test
+```
+
+## Modules
+
+| Module         | Description                                      |
+| -------------- | ------------------------------------------------ |
+| `usel.math`    | Matrix creation, algebra, norms, FFT transforms  |
+| `usel.linalg`  | Eigenvalues/vectors, SVD, QR, LU, Cholesky       |
+| `usel.solvers` | Root finding, ODE solvers, numerical integration |
+| `usel.random`  | Random matrices, vectors, and distributions      |
+| `usel.utils`   | Timing, profiling, validation, precision control |
+| `usel.logging` | Console/file loggers, performance logger         |
+| `usel.config`  | YAML/JSON/TOML configuration loading             |
+| `usel.io`      | CSV/JSON/NumPy binary/text file I/O              |
+| `usel.cli`     | Command line interface                           |
+
+## Non-Goals (v1.0)
+
+This release intentionally excludes the Schrödinger equation, quantum
+circuits/gates/qubits, machine learning, chemistry simulation, GPU/cloud
+computing, and AI integration. These are planned for future releases (see
+[CHANGELOG.md](CHANGELOG.md) and the roadmap below).
+
+## Roadmap
+
+- v1.0 — Scientific Computing Foundation
+  - Core numerical engine
+  - Linear algebra utilities
+  - Matrix operations
+  - Numerical solvers
+  - FFT and mathematical utilities
+  - Configuration, logging, and CLI support
+
+- v2.0 — Quantum Physics Engine
+  - Schrödinger equation module
+  - Quantum wavefunction utilities
+  - Potential models
+  - Hamiltonian construction
+  - Time evolution and visualization
+
+- v3.0 — Relativistic & Computational Physics
+  - Dirac equation module
+  - Spinor algebra
+  - Gamma matrix operations
+  - Relativistic particle simulations
+  - Maxwell equation module
+  - Electromagnetic field simulations
+
+Still more planning is going on this.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv run black --check .
+uv run mypy src
+```
+
+## Documentation
+
+Full documentation is built with MkDocs:
+
+```bash
+uv run mkdocs serve
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for
+guidelines.
+
+## Security
+
+usel performs no telemetry, no network communication, and no data
+collection. It is fully offline capable.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

usel-1.0.4/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "usel"
+version = "1.0.4"
+description = "An open-source, CPU-only scientific computing framework focused on quantum physics simulations and numerical methods."
+
+authors = [
+    { name = "Goutam Parashuram Gotur" },
+    { name = "K R Raaghavindhra" }
+]
+
+license = { text = "MIT" }
+readme = "README.md"
+
+keywords = [
+    "scientific-computing",
+    "numerical-methods",
+    "physics",
+    "linear-algebra",
+    "computational-physics",
+    "dirac-equation",
+    "mathematics",
+    "open-source",
+    "quantum-mechanics"
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Chemistry"
+]
+
+requires-python = ">=3.11"
+
+dependencies = [
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "sympy>=1.12",
+    "pyyaml>=6.0",
+    "toml>=0.10.2",
+    "matplotlib>=3.8"
+]
+
+[project.urls]
+Homepage = "https://github.com/goutam-tech/usel"
+Repository = "https://github.com/goutam-tech/usel"
+Documentation = "https://goutam-tech.github.io/usel"
+
+[project.scripts]
+usel = "usel.cli.main:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.4.0",
+    "black>=24.3.0",
+    "mypy>=1.9.0",
+    "pytest>=8.1.0",
+    "pytest-cov>=5.0.0"
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311", "py312"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=usel --cov-report=term-missing"

usel-1.0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

usel-1.0.4/src/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-1.0.4/src/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-1.0.4/src/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-1.0.4/src/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-1.0.4/src/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