pytorch_optimizer 3.10.1__tar.gz → 4.0.0__tar.gz

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/ISSUE_TEMPLATE/bug_report.md

@@ -14,8 +14,8 @@ A clear and concise description of what the bug is.
 ## To Reproduce
 
 * OS : (e.g. Linux, Windows, MacOS)
-* PyTorch version : (e.g. 2.0.1, 1.13, >=1.8, <1.10)
-* Python version :  (e.g. 3.8, 3.11)
+* PyTorch version : (e.g. 2.1.0, 2.13.0)
+* Python version :  (e.g. 3.10, 3.12)
 * pytorch-optimizer version : (e.g. 3.3.0)
 * reproducible codes : please share your reproducible codes, scripts, or links. If sharing the code is complicated, you can manually write minimal code to reproduce bugs!
 

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/labeler.yml

@@ -2,6 +2,8 @@ documentation:
   - changed-files:
     - any-glob-to-any-file:
       - '**/*.md'
+      - zensical.toml
+      - docs/**
 
 github_actions:
   - changed-files:
@@ -14,7 +16,8 @@ dependencies:
       - pyproject.toml
       - requirements.txt
       - requirements-dev.txt
-      - requirements-docs.txt
+      - docs/requirements-docs.txt
+      - uv.lock
 
 optimizer:
   - changed-files:

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/pull_request_template.md

@@ -16,7 +16,7 @@ _Please note any questions, helps or contexts what maintainer(s) should know_
 
 ## Checklist
 
-- [ ] Make sure to run `make format` before commit
-- [ ] My code adheres to the style guidelines of this project (`make check` shows no errors)
-- [ ] Both new and existing unit tests pass successfully on my local environment by running `make test`
+- [ ] Make sure to run `just format` before commit
+- [ ] My code adheres to the style guidelines of this project (`just check` shows no errors)
+- [ ] Both new and existing unit tests pass successfully on my local environment by running `just test`
 - [ ] I have made the necessary changes to the documentation

pytorch_optimizer-4.0.0/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      ref:
+        description: Commit to validate
+        type: string
+        required: false
+        default: ''
+      skip_coverage_upload:
+        description: Skip coverage uploads during release validation
+        type: boolean
+        required: false
+        default: false
+
+env:
+  OMP_NUM_THREADS: 8
+  MKL_NUM_THREADS: 8
+  PYTHONDONTWRITEBYTECODE: 1
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: 3.12
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install dependencies
+        run: uv sync --frozen --no-editable
+
+      - name: Run lint
+        run: |
+          uv run ruff check pytorch_optimizer examples tests scripts hubconf.py
+
+  type_check:
+    name: Static Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: 3.12
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install dependencies
+        run: uv sync --frozen --no-editable
+
+      - name: Run type check
+        run: uv run --frozen ty check
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: 3.12
+          enable-cache: true
+
+      - name: Build documentation
+        run: uv run --no-project --python 3.12 --with-requirements docs/requirements-docs.txt zensical build --strict
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.15']
+
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        ref: ${{ inputs.ref || github.sha }}
+
+    - name: Setup uv
+      uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+        prune-cache: false
+
+    - name: Install dependencies
+      run: uv sync --frozen --no-editable
+
+    - name: Check test
+      run: uv run --frozen pytest
+
+    - name: Upload coverage
+      if: success() && !inputs.skip_coverage_upload
+      uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        directory: ./
+        files: ./coverage.xml
+        env_vars: OS,PYTHON
+        flags: ${{ matrix.python-version }}
+        fail_ci_if_error: true
+        verbose: false
+
+  ci-summary:
+    if: always()
+    needs: [lint, type_check, docs, test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check results
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1
+
+      - name: Report Summary
+        run: echo "✅ Lint, documentation, and tests completed for all targets"

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/workflows/pr_automerge.yml

@@ -5,7 +5,9 @@ on:
     types:
       - opened
       - synchronize
-  check_suite:
+      - labeled
+  workflow_run:
+    workflows: [CI]
     types:
       - completed
 
@@ -19,13 +21,15 @@ jobs:
 
     steps:
       - id: automerge
-        if: ${{ contains(github.event.pull_request.labels.*.name, 'automerge') }}
+        if: >-
+          contains(github.event.pull_request.labels.*.name, 'automerge') ||
+          (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
         name: automerge
-        uses: pascalgn/automerge-action@v0.16.4
+        uses: pascalgn/automerge-action@7961b8b5eec56cc088c140b56d864285eabd3f67 # v0.16.4
         env:
           MERGE_LABELS: "automerge"
           MERGE_METHOD_LABEL_REQUIRED: "false"
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          GITHUB_TOKEN: ${{ github.token }}
           MERGE_METHOD: "squash"
           MERGE_REQUIRED_APPROVALS: "0"
           MERGE_DELETE_BRANCH: "true"

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/workflows/pr_codeql.yml

@@ -35,14 +35,14 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v4
+      uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
       with:
         languages: ${{ matrix.language }}
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v4
+      uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
       with:
         category: "/language:${{matrix.language}}"

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/workflows/pr_labeler.yml

@@ -17,9 +17,9 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/labeler@v5
+      - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0
         if: ${{ github.event.action != 'labeled' && github.event.action != 'unlabeled' && !contains(github.event.pull_request.labels.*.name, 'automerge') }}
         with:
           configuration-path: '.github/labeler.yml'

pytorch_optimizer-4.0.0/.github/workflows/publish.yml

@@ -0,0 +1,231 @@
+name: Release
+run-name: Release / ${{ github.ref_name }}
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version component to increment
+        required: true
+        type: choice
+        default: patch
+        options: [major, minor, patch]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  guard:
+    name: Guard Release Ref
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require main for manual releases
+        run: |
+          if [[ "$GITHUB_EVENT_NAME" == 'workflow_dispatch' && "$GITHUB_REF" != 'refs/heads/main' ]]; then
+            echo "Run manual releases from main, not $GITHUB_REF" >&2
+            exit 1
+          fi
+
+  validate:
+    name: Validate
+    needs: guard
+    uses: ./.github/workflows/ci.yml
+    with:
+      ref: ${{ github.sha }}
+      skip_coverage_upload: true
+
+  prepare:
+    name: Prepare Release
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+      ref: ${{ steps.commit.outputs.ref }}
+      notes: ${{ steps.notes.outputs.body }}
+    steps:
+      - name: Checkout release ref
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          token: ${{ github.token }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: '3.12'
+
+      - name: Validate and bump package version
+        id: version
+        env:
+          BUMP: ${{ inputs.bump }}
+        run: |
+          uv lock --check
+          current="$(uv version --short)"
+          if [[ ! "$current" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo 'Package version must have the form MAJOR.MINOR.PATCH' >&2
+            exit 1
+          fi
+
+          if [[ "$GITHUB_EVENT_NAME" == 'workflow_dispatch' ]]; then
+            version="$(uv version --bump "$BUMP" --no-sync --short)"
+            tag="v$version"
+            if git rev-parse --verify --quiet "refs/tags/$tag"; then
+              echo "Tag $tag already exists" >&2
+              exit 1
+            fi
+          else
+            tag="$GITHUB_REF_NAME"
+            if [[ "$tag" != "v$current" ]]; then
+              echo "Tag $tag does not match package version $current" >&2
+              exit 1
+            fi
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Generate release notes and update changelogs
+        id: notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          gh api --method POST "repos/$GH_REPO/releases/generate-notes" \
+            -f tag_name="$RELEASE_TAG" -f target_commitish="$GITHUB_SHA" \
+            --jq .body > "$RUNNER_TEMP/release-notes.md"
+          uv run --no-project python scripts/update_changelog.py "$RELEASE_TAG" "$RUNNER_TEMP/release-notes.md"
+
+          delimiter="release_notes_${RANDOM}_${RANDOM}_${RANDOM}"
+          {
+            echo "body<<$delimiter"
+            cat "$RUNNER_TEMP/release-notes.md"
+            echo "$delimiter"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create release preparation pull request
+        id: release_pr
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          branch: release/prepare-${{ steps.version.outputs.tag }}
+          commit-message: 'build: prepare release ${{ steps.version.outputs.tag }}'
+          title: 'build: prepare release ${{ steps.version.outputs.tag }}'
+          body: >-
+            Prepare the package version, lockfile, and generated changelogs for ${{ steps.version.outputs.tag }}.
+            This pull request must merge before package publishing and GitHub release creation.
+          base: main
+          add-paths: |
+            pyproject.toml
+            uv.lock
+            CHANGELOG.md
+            docs/changelogs/${{ steps.version.outputs.tag }}.md
+            docs/changelogs/index.md
+          delete-branch: true
+          token: ${{ github.token }}
+
+      - name: Merge release preparation pull request and resolve release commit
+        id: commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ steps.release_pr.outputs.pull-request-number }}
+          PR_HEAD_SHA: ${{ steps.release_pr.outputs.pull-request-head-sha }}
+        run: |
+          if [[ -z "$PR_NUMBER" || -z "$PR_HEAD_SHA" ]]; then
+            echo 'No release preparation pull request was created' >&2
+            exit 1
+          fi
+          for attempt in {1..10}; do
+            mergeable="$(gh pr view "$PR_NUMBER" --json mergeable --jq .mergeable)"
+            if [[ "$mergeable" != 'UNKNOWN' ]]; then
+              break
+            fi
+            sleep 3
+          done
+          if [[ "$mergeable" == 'UNKNOWN' ]]; then
+            echo 'GitHub has not finished calculating PR mergeability' >&2
+            exit 1
+          fi
+          gh pr merge "$PR_NUMBER" --squash --delete-branch --match-head-commit "$PR_HEAD_SHA"
+          merged_ref="$(gh pr view "$PR_NUMBER" --json state,mergeCommit \
+            --jq 'if .state == "MERGED" then .mergeCommit.oid else empty end')"
+          if [[ -z "$merged_ref" ]]; then
+            echo 'The release preparation pull request must be merged before publishing' >&2
+            exit 1
+          fi
+          if [[ "$GITHUB_EVENT_NAME" == 'workflow_dispatch' ]]; then
+            ref="$merged_ref"
+          else
+            ref="$GITHUB_SHA"
+          fi
+          echo "ref=$ref" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    name: Publish Package
+    needs: prepare
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout release commit
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.prepare.outputs.ref }}
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: '3.12'
+
+      - name: Build package
+        run: uv build
+
+      - name: Create and push release tag
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+          RELEASE_REF: ${{ needs.prepare.outputs.ref }}
+        run: |
+          if git rev-parse --verify --quiet "refs/tags/$RELEASE_TAG"; then
+            if [[ "$(git rev-list -n 1 "$RELEASE_TAG")" != "$RELEASE_REF" ]]; then
+              echo "Tag $RELEASE_TAG points to a different commit" >&2
+              exit 1
+            fi
+          else
+            git config user.name 'github-actions[bot]'
+            git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+            git tag -a "$RELEASE_TAG" -m "pytorch-optimizer $RELEASE_TAG"
+            git push origin "refs/tags/$RELEASE_TAG"
+          fi
+
+      - name: Publish package to PyPI
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple
+
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    needs: [prepare, deploy]
+    permissions:
+      contents: write
+    steps:
+      - name: Create release with the prepared notes
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
+        with:
+          body: ${{ needs.prepare.outputs.notes }}
+          draft: false
+          prerelease: false
+          name: pytorch-optimizer ${{ needs.prepare.outputs.tag }}
+          tag_name: ${{ needs.prepare.outputs.tag }}
+          target_commitish: ${{ needs.prepare.outputs.ref }}
+          token: ${{ github.token }}

{pytorch_optimizer-3.10.1 → pytorch_optimizer-4.0.0}/.github/workflows/update_docs.yml

@@ -12,10 +12,10 @@ jobs:
   update-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: 3.12
 
@@ -23,7 +23,7 @@ jobs:
         run: python scripts/update_docs.py
 
       - name: Commit updated documentation
-        uses: stefanzweifel/git-auto-commit-action@v6
+        uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0
         id: auto-commit-action
         with:
           commit_message: "docs: update documentation"

pytorch_optimizer-4.0.0/AGENTS.md

@@ -0,0 +1,110 @@
+# Agent Instructions
+
+## Development workflow
+
+- Use `uv` for dependency resolution and execution. Prefer `uv run just <recipe>` to use the versions in `uv.lock`.
+- The repository `justfile` is cross-platform and works on Windows, macOS, and Linux/WSL.
+- Run the relevant checks after changes:
+  - `uv run just format`
+  - `uv run just check`
+  - `uv run just test`
+- Cover new and changed implementation code at 100%. Check coverage with `uv run coverage report -m`.
+- Use `uv run coverage report -m` to find uncovered lines, then add focused cases in the appropriate test module.
+- Run focused optimizer tests with `uv run pytest tests/optimizers/test_muon.py -sv -vv`.
+- Select a training recipe with `uv run pytest tests/test_optimizers.py::TestOptimizerTraining -k adammini -sv -vv`.
+- Use `uv run just docs` to serve the Zensical documentation. Build it with strict validation using
+  `uv run just docs-build`.
+- Run `uv run just update-docs` after changing public exports to regenerate the API reference.
+
+## Architecture
+
+- `pytorch_optimizer/base/` contains `BaseOptimizer`, scheduler bases, shared types, and exceptions.
+- `pytorch_optimizer/optimizer/` contains optimizers, wrappers, and shared gradient and update utilities.
+- Put schedulers in `pytorch_optimizer/lr_scheduler/` and loss functions in `pytorch_optimizer/loss/`.
+- Export public components from `pytorch_optimizer/__init__.py`. Use `load_optimizer()` to load a class by name and
+  `create_optimizer()` to configure an optimizer with common options and wrappers.
+- Optional integrations include `bitsandbytes`, `q-galore-torch`, and `torchao`.
+- `tests/test_optimizers.py` runs shared training and interface tests using `OPTIMIZER_RECIPES` from
+  `tests/recipes.py`. Focused optimizer and algorithm-helper cases live in `tests/optimizers/test_<module>.py`.
+  Parameter validation, variants, wrappers, losses, and schedulers have separate shared test modules.
+- `tests/fixtures.py` owns the shared training model and parameter builders. `tests/utils.py` supplies optimizer
+  construction and training helpers; `tests/conftest.py` supplies pytest fixtures, including training data.
+- `tests/optimizer_cases.py` derives constructor options and model-based APIs from signatures, and sparse/complex
+  support from cached CPU step probes. Explicit exclusions cover specialized protocols and numerical limitations.
+- `zensical.toml` owns documentation navigation and theme settings. Keep the home page separate from `README.md`.
+
+## Code style
+
+- Follow nearby repository code and tests before introducing new patterns.
+- Add comments only when code is difficult to understand; avoid redundant, meaningless, or excessive comments.
+- Use blank lines to separate logical steps and improve readability.
+- Do not add introductory comments or docstrings to scripts.
+- Use a maximum line length of 119 characters and single-quoted strings.
+- Use the repository's existing typing style. Do not add `from __future__ import annotations` or `TYPE_CHECKING`
+  imports unless the surrounding code requires them.
+- Optimizers inherit from `BaseOptimizer`, implement `init_group()` and `step()`, and reuse its validation and update
+  helpers where applicable.
+- All optimizer implementations must follow the algorithms and update rules in their original papers.
+- Follow Google-style docstrings. Reuse helpers such as `apply_weight_decay()`, `apply_cautious()`, `debias()`,
+  `validate_learning_rate()`, `validate_betas()`, and `validate_range()` before adding update or validation logic.
+- Keep implementations focused; remove redundant compatibility layers and abstractions.
+
+## Testing
+
+- For optimizer changes, add or update minimal recipes in `OPTIMIZER_RECIPES`, including affected variants. Each
+  recipe contains an optimizer name, options, and an iteration count. Use the shared runner for model-based
+  optimizers when their update protocol fits; avoid separate training or smoke tests that a recipe can replace.
+- Add focused cases for behavior the training recipes do not verify, such as numerical updates, checkpoint
+  restoration, validation, wrappers, and edge cases. Follow nearby patterns and preserve 100% implementation coverage.
+- Give focused cases an observable assertion. Compare numerical results with `torch.testing.assert_close()` and
+  check expected exceptions with `pytest.raises()`. Use stable inputs and a trusted reference for iterative algorithms.
+- Reuse `TrainingModel`, `build_model()`, and parameter builders from `tests/fixtures.py`. Use a parameter when a test
+  only calls optimizer methods, and create additional shapes or model features only when the behavior requires them.
+- Use `tests.utils.build_optimizer()` for ordinary optimizer setup. Use `load_optimizer()` for constructor
+  validation or APIs that accept an optimizer class, and `create_optimizer()` when testing that public factory.
+- Use pytest classes to group related behavior where useful. Parametrize only applicable combinations and run
+  shared interface checks once per optimizer rather than once per recipe.
+- Reuse capability detection from `tests/optimizer_cases.py` instead of maintaining optimizer name lists. Keep
+  protocol-specific exclusions explicit; probes must preserve random state and propagate unexpected failures.
+- Keep variant, scheduler, and loss case data beside their tests. Copy recipe options before attaching callbacks or
+  parameter groups, and avoid retaining model instances or optimizer state in shared case data.
+- Keep tensors and training iteration counts small while retaining meaningful assertions. Remove redundant cases
+  without losing behavior checks or coverage, and avoid session-wide performance overrides.
+
+## Adding an optimizer
+
+- Add the implementation under `pytorch_optimizer/optimizer/`.
+- Export it from the optimizer package and register it in `OPTIMIZER_LIST` so it is available through `OPTIMIZERS`
+  and `load_optimizer()`.
+- Add a training recipe and focused cases following the testing guidance above.
+- Update the relevant documentation and algorithm table in `README.md`.
+- Write clear PR titles and descriptions; the release workflow generates notes from merged PRs and syncs them to
+  `CHANGELOG.md`, `docs/changelogs/<tag>.md`, and the changelog index through an automated PR.
+- Register new loss functions and schedulers in their package exports and add them to the corresponding tests and
+  README tables.
+- Leave the root `CHANGELOG.md` to the release automation.
+
+## Commits and pull requests
+
+Start commit subjects with one of these prefixes:
+
+| Prefix | Use for |
+| --- | --- |
+| `feat:` | Add a feature or public API. |
+| `fix:` | Correct a bug or unintended behavior. |
+| `perf:` | Improve execution speed or resource use. |
+| `style:` | Change code formatting without changing behavior. |
+| `refactor:` | Restructure code without changing public behavior. |
+| `docs:` | Add, revise, or reorganize documentation. |
+| `chore:` | Maintain development tools, automation, or repository housekeeping. |
+| `build:` | Change build, packaging, or dependency configuration. |
+| `update:` | Refresh project content or metadata when no more specific prefix applies. |
+
+Keep the text after the prefix imperative, concise, and specific to the committed change.
+Do not use commit prefixes outside this list.
+
+- Write concise, specific PR titles that describe the actual change. Use a title tag only when it adds useful context
+  and accurately matches the work; do not derive it mechanically from the commit prefix.
+- Feature PR titles follow the existing format, such as `[Feature] Implement Magma optimizer`.
+- Keep commits focused and verify the branch and working tree before pushing. Use `--force-with-lease` when you need
+  to rewrite a pushed branch.