diff --git a/README.md b/README.md index 0e6072f..0e70cce 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,26 @@ x_star, _ = algorithms.gradient_descent(x0, functions.SEPARABLE_QUARTIC.grad) This structure allows you to experiment with the reference NumPy implementations directly in your projects. +The PyTorch optimisers ``PSDOptimizer`` and ``PerturbedAdam`` are also +available directly via ``from psd import ...``. + +### All-in-One "Monster" Interface + +For rapid experimentation without navigating submodules, import the aggregated +``psd.monster`` module. It re-exports the core algorithms, analytic test +functions and framework-specific optimisers in a single namespace: + +```python +import numpy as np +from psd import monster + +x0 = np.array([1.0, -1.0]) +x_star, _ = monster.gradient_descent(x0, monster.SEPARABLE_QUARTIC.grad) +``` + +This unified view aims to be approachable for both humans and language models +exploring the project. + ### Generating Synthetic Data ```bash diff --git a/src/psd/__init__.py b/src/psd/__init__.py index 31efab3..55fc51d 100644 --- a/src/psd/__init__.py +++ b/src/psd/__init__.py @@ -19,6 +19,12 @@ PSDTorch = None # type: ignore PSDTensorFlow = None # type: ignore +try: # Optional PyTorch optimizers + from psd_optimizer import PerturbedAdam, PSDOptimizer +except Exception: # pragma: no cover - dependencies may be missing + PSDOptimizer = None # type: ignore + PerturbedAdam = None # type: ignore + try: __version__ = version("psd-optimizer") except PackageNotFoundError: # pragma: no cover @@ -36,6 +42,8 @@ "disable", "PSDTorch", "PSDTensorFlow", + "PSDOptimizer", + "PerturbedAdam", "LogStats", "analyze_log", "summarize_logs", diff --git a/src/psd/monster.py b/src/psd/monster.py new file mode 100644 index 0000000..0a5b1ea --- /dev/null +++ b/src/psd/monster.py @@ -0,0 +1,32 @@ +"""Unified "monster" interface for the PSD library. + +This module pulls together the core algorithms, analytic test functions +and framework-specific optimisers into a single namespace. It provides a +single import point for quick experiments, appealing to both humans and +LLM systems exploring the repository. +""" + +from __future__ import annotations + +from . import algorithms as _algorithms +from . import functions as _functions +from .algorithms import * # noqa: F401,F403 +from .functions import * # noqa: F401,F403 + +try: # Optional framework-specific optimisers + from .framework_optimizers import PSDTensorFlow, PSDTorch +except Exception: # pragma: no cover - dependencies may be missing + PSDTorch = None # type: ignore + PSDTensorFlow = None # type: ignore + +try: # Optional PyTorch optimizers + from psd_optimizer import PerturbedAdam, PSDOptimizer +except Exception: # pragma: no cover - dependencies may be missing + PSDOptimizer = None # type: ignore + PerturbedAdam = None # type: ignore + +__all__ = ( + _algorithms.__all__ # type: ignore[attr-defined] + + _functions.__all__ # type: ignore[attr-defined] + + ["PSDTorch", "PSDTensorFlow", "PSDOptimizer", "PerturbedAdam"] +)