diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..8e8f160 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,14 @@ +version: 2 +updates: + + - package-ecosystem: 'github-actions' + directory: '/' + schedule: + # Check for updates once a week + interval: 'weekly' + groups: + actions: + patterns: + - "*" + cooldown: + default-days: 7 diff --git a/.github/workflows/python-package-conda.yml b/.github/workflows/python-package-conda.yml index 105356c..fc53f88 100644 --- a/.github/workflows/python-package-conda.yml +++ b/.github/workflows/python-package-conda.yml @@ -12,7 +12,7 @@ jobs: shell: bash -l {0} steps: - uses: actions/checkout@v4 - - uses: conda-incubator/setup-miniconda@v3 + - uses: conda-incubator/setup-miniconda@v4.0.1 with: miniforge-version: latest channel-priority: true diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index bdaab28..6c2ceec 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -1,4 +1,4 @@ -# This workflow will upload a Python Package using Twine when a release is created +# This workflow will upload a Python Package to PyPI when a release is created # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries # This workflow uses actions that are not certified by GitHub. @@ -16,24 +16,61 @@ permissions: contents: read jobs: - deploy: + release-build: + name: Build and upload distribution + runs-on: ubuntu-latest + + steps: + - name: Checkout repo + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + + - name: Setup Python + uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + with: + python-version: "3.11" + - name: Build release distributions + run: | + # NOTE: put your own distribution build steps here. + python -m pip install build + python -m build + + - name: Upload distributions + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: release-dists + path: dist/ + + pypi-publish: + name: Upload to PyPI runs-on: ubuntu-latest + needs: + - release-build + permissions: + # IMPORTANT: this permission is mandatory for trusted publishing + id-token: write + + # Dedicated environments with protections for publishing are strongly recommended. + # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules + environment: + name: pypi + # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status: + # url: https://pypi.org/p/YOURPROJECT + # + # ALTERNATIVE: if your GitHub Release name is the PyPI project version string + # ALTERNATIVE: exactly, uncomment the following line instead: + # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }} steps: - - uses: actions/checkout@v3 - - name: Set up Python - uses: actions/setup-python@v3 - with: - python-version: '3.x' - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install build - - name: Build package - run: python -m build - - name: Publish package - uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29 - with: - user: __token__ - password: ${{ secrets.PYPI_API_TOKEN }} + - name: Retrieve release distributions + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: release-dists + path: dist/ + + - name: Publish release distributions to PyPI + uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0 + with: + packages-dir: dist/ diff --git a/.gitignore b/.gitignore index b6e4761..5b721a5 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ __pycache__/ # Distribution / packaging .Python +echo/_version.py build/ develop-eggs/ dist/ diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..2abaac5 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,37 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - method: "pip" + path: "." + extra_requirements: + - docs diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/echo_logo.png b/docs/source/_static/echo_logo.png new file mode 100644 index 0000000..8fc4af1 Binary files /dev/null and b/docs/source/_static/echo_logo.png differ diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ca5428b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'ECHO' +copyright = '2026, University Corporation for Atmospheric Research' +author = 'John Schreck' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.napoleon", "autoapi.extension"] + +templates_path = ['_templates'] +exclude_patterns = [] +autoapi_dirs = ["../../echo/"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] +html_logo = "_static/echo_logo.png" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..51f745b --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,16 @@ +.. ECHO documentation master file, created by + sphinx-quickstart on Wed May 6 11:25:55 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +ECHO documentation +================== + +ECHO is a package for distributed hyperparameter optimization on HPC systems built on optuna. +The package provides both a way to generate lots of hyperparameter combos, track them, and +analyze the importance of different hyperparameter choices. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + diff --git a/environment.yml b/environment.yml index 2071995..af54aae 100644 --- a/environment.yml +++ b/environment.yml @@ -1,23 +1,17 @@ name: echo channels: - conda-forge - - pytorch dependencies: - python=3.12 - sphinx - pytest - setuptools - - optuna<4.0 + - optuna>=3.0 - numpy - scipy - matplotlib - scikit-learn - - jupyter - - jupyterlab - - jupyter_server - - distributed - pip - pyarrow - - xgboost - pip: - . diff --git a/pyproject.toml b/pyproject.toml index 855cbbc..c3b854a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["setuptools"] +requires = ["setuptools", "setuptools-scm"] build-backend = "setuptools.build_meta" [project] @@ -35,6 +35,8 @@ dependencies = [ "scikit-learn", "pyarrow", "pyyaml", + "setuptools", + "setuptools_scm" ] [project.urls] @@ -52,5 +54,5 @@ include-package-data = true [tool.setuptools.packages.find] include = ["echo", "echo.src"] -[tool.setuptools.dynamic] -version = {file = "echo/VERSION"} +[tool.setuptools_scm] +version_file = "echo/_version.py" diff --git a/requirements.txt b/requirements.txt index 9290a99..c048154 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,6 +4,7 @@ matplotlib pandas optuna>=3.0 setuptools +setuptools_scm pyyaml scikit-learn pyarrow