Metadata-Version: 2.4
Name: pyperch
Version: 0.4.0
Summary: PyTorch-native randomized optimization algorithms.
License-Expression: MIT
Keywords: pytorch,optimization,machine-learning,randomized-optimization
Author: John Mansfield
Requires-Python: >=3.10,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: notebooks
Provides-Extra: optuna
Requires-Dist: ipykernel (>=6.29,<8.0) ; extra == "notebooks"
Requires-Dist: matplotlib (>=3.8,<4.0)
Requires-Dist: nbconvert (>=7.16,<8.0) ; extra == "notebooks"
Requires-Dist: notebook (>=7.0,<8.0) ; extra == "notebooks"
Requires-Dist: numpy (>=1.24)
Requires-Dist: optuna (>=4.0,<5.0) ; extra == "notebooks"
Requires-Dist: optuna (>=4.0,<5.0) ; extra == "optuna"
Requires-Dist: scikit-learn (>=1.4,<2.0) ; extra == "notebooks"
Requires-Dist: torch (>=2.1,<3.0)
Project-URL: Homepage, https://github.com/jlm429/pyperch
Project-URL: Repository, https://github.com/jlm429/pyperch
Description-Content-Type: text/markdown

# pyperch

![PyPI](https://img.shields.io/pypi/v/pyperch.svg)
![Python Versions](https://img.shields.io/pypi/pyversions/pyperch.svg)
![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)
![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg)
![Linter: Ruff](https://img.shields.io/badge/lint-ruff-blue.svg)
[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/WH9eaoZnQRJ8SGFDrvqQAd/5meq6x5R3uDA3KSuHARdVk/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/circleci/WH9eaoZnQRJ8SGFDrvqQAd/5meq6x5R3uDA3KSuHARdVk/tree/master)

![PyPerch randomized optimization for PyTorch workflows](https://raw.githubusercontent.com/jlm429/pyperch/master/docs/assets/pyperch_repo_image3.png)

PyPerch provides randomized hill climbing (RHC), simulated annealing (SA), and
genetic algorithm (GA) optimizers for ordinary `torch.nn.Module` workflows. Pass
native PyTorch parameter iterables, define the loss in a closure, and keep model
architecture, data loading, forward passes, metrics, and training loops in PyTorch.

Plotting utilities included in the normal installation prepare recorded results and
render them on caller-owned Matplotlib Axes. A thin optional Optuna layer supports
hyperparameter studies without hiding native trials or studies. Start with the
[General Usage Guide](docs/general_usage_guide.md) for optimizer semantics and
complete examples.

## Installation

PyPerch supports Python 3.10 through 3.13.

Install from PyPI:

```bash
pip install pyperch
pip install "pyperch[optuna]"
```

The normal installation includes NumPy for curve preparation and Matplotlib for
rendering. The Optuna extra enables hyperparameter search. To run the repository's
notebooks from a source checkout, follow the [examples guide](examples/README.md).

---

## Development Setup

See [CONTRIBUTING.md](CONTRIBUTING.md) for source-checkout setup and validation.

---

## Examples

PyPerch's RHC, SA, and GA optimizers operate directly on the parameters of standard
PyTorch models. Bring your own `torch.nn.Module`, loss function, data tensors,
evaluation code, and training loop. If a model works in PyTorch, it should generally
work with PyPerch optimizers.

- [Native PyTorch training](examples/notebooks/01_native_training.ipynb): Use RHC in a
  PyTorch training loop, including frozen layers and separate Adam/RHC updates.
- [Optimizer convergence and cost](examples/notebooks/02_optimizer_comparison.ipynb):
  Compare RHC, SA, GA, and Adam across repeated runs.
- [Training, learning, and validation curves](examples/notebooks/03_learning_and_validation.ipynb):
  Explore optimization progress, training set size, model capacity, and generalization.
- [Optuna tuning](examples/notebooks/04_optuna_tuning.ipynb): Tune SA and GA settings
  with repeated Optuna trials and evaluate the selected refits.

See the [examples guide](examples/README.md) for notebook-running instructions and
reproducibility information.

---

## Documentation

- [General Usage Guide](docs/general_usage_guide.md): RHC, SA, and GA in ordinary
  PyTorch training loops
- [Examples guide](examples/README.md): optimizer, freezing, composition, and
  comparison workflows
- [Plotting API and terminology](docs/plotting.md): prepare and render recorded
  curves
- [Search Usage Guide](docs/search.md): optional Optuna studies

---

## Contributing

Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the project
philosophy, development checks, and review expectations.

