-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1 from NREL/refactor
Refactor
- Loading branch information
Showing
21 changed files
with
2,844 additions
and
580 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,78 @@ | ||
name: Build and Deploy Docs | ||
|
||
on: | ||
push: | ||
branches: | ||
- main | ||
pull_request: | ||
types: [closed, opened, synchronize] | ||
branches: | ||
- main | ||
|
||
jobs: | ||
build-and-deploy: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Checkout | ||
uses: actions/checkout@v4 | ||
|
||
- name: Set up Python | ||
uses: actions/setup-python@v5 | ||
with: | ||
python-version: "3.11.x" | ||
|
||
- name: Cache Python dependencies | ||
uses: actions/cache@v3 | ||
with: | ||
path: ~/.cache/pip | ||
key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py') }} | ||
restore-keys: | | ||
${{ runner.os }}-pip- | ||
- name: Install package | ||
run: pip install --upgrade . | ||
|
||
- name: Install dependencies | ||
run: | | ||
python -m pip install --upgrade pip | ||
pip install sphinx nbsphinx nbsphinx_link sphinx_rtd_theme | ||
- name: Install Pandoc | ||
run: | | ||
sudo apt-get update | ||
sudo apt-get install -y pandoc | ||
- name: Build documentation | ||
run: | | ||
cd Docs | ||
make html | ||
touch build/html/.nojekyll | ||
- name: Set TARGET_FOLDER and CLEAN | ||
run: | | ||
if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then | ||
echo "TARGET_FOLDER=docs/" >> $GITHUB_ENV | ||
echo "CLEAN=true" >> $GITHUB_ENV | ||
elif [ "${{ github.event_name }}" == "pull_request" ] && [ "${{ github.event.action }}" == "closed" ]; then | ||
echo "TARGET_FOLDER=pr-preview/${{ github.event.number }}" >> $GITHUB_ENV | ||
echo "CLEAN=true" >> $GITHUB_ENV | ||
else | ||
echo "TARGET_FOLDER=pr-preview/${{ github.event.number }}" >> $GITHUB_ENV | ||
echo "CLEAN=false" >> $GITHUB_ENV | ||
fi | ||
- name: Stage Cleanup for _downloads directory (files older than 10 days) | ||
if: github.event_name == 'pull_request' && github.event.action == 'closed' | ||
run: | | ||
find _downloads -type f -mtime +10 -delete | ||
git add _downloads | ||
- name: Deploy | ||
uses: JamesIves/github-pages-deploy-action@releases/v4 | ||
with: | ||
token: ${{ secrets.GITHUB_TOKEN }} | ||
branch: gh-pages | ||
folder: Docs/build/html | ||
single-commit: true | ||
target-folder: ${{ env.TARGET_FOLDER }} | ||
clean: ${{ env.CLEAN }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
# 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 | ||
import os | ||
import sys | ||
|
||
import sphinx_rtd_theme | ||
|
||
sys.path.insert(0, os.path.abspath("../..")) | ||
|
||
# -- Project information ----------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information | ||
|
||
project = "pt-melt" | ||
copyright = "2023, Alliance for Sustainable Energy" | ||
author = "Nicholas T. Wimer" | ||
|
||
# -- General configuration --------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration | ||
|
||
extensions = [ | ||
"sphinx.ext.autodoc", | ||
"sphinx.ext.napoleon", | ||
"sphinx.ext.viewcode", | ||
"sphinx.ext.autosummary", | ||
"sphinx.ext.autosectionlabel", | ||
"matplotlib.sphinxext.plot_directive", | ||
"sphinx_rtd_theme", | ||
] | ||
|
||
autosummary_generate = False | ||
|
||
templates_path = ["_templates"] | ||
exclude_patterns = [] | ||
|
||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output | ||
|
||
html_theme = "sphinx_rtd_theme" | ||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] | ||
html_theme_options = { | ||
"collapse_navigation": False, # Do not collapse the navigation bar | ||
"sticky_navigation": True, # Make the navigation bar sticky | ||
"navigation_depth": 5, # Maximum depth of the navigation tree | ||
"titles_only": False, # Show all titles in the navigation bar | ||
"includehidden": False, # Do not include hidden documents | ||
"display_version": True, # Display the version number | ||
"style_external_links": True, # Add icons to external links | ||
"style_nav_header_background": "#2980B9", # Set the navigation bar color | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
.. _examples: | ||
|
||
Example Notebooks | ||
================= | ||
|
||
The examples folder includes a collection of Jupyter notebooks that demonstrate the use | ||
of the ``PT-MELT`` package for different machine learning tasks. The examples included | ||
are: | ||
|
||
- **Regression (regression.ipynb)**: This notebook demonstrates how to use the | ||
``PT-MELT`` package for regression tasks. The notebook uses each of the models | ||
available in ``PT-MELT`` and showcases the use of uncertainty quantification for each | ||
of the model types. The notebook demonstrates the entire typical workflow for ML | ||
regression: | ||
|
||
- Data creation | ||
- Data preprocessing | ||
- Model creation | ||
- Model training | ||
- Model evaluation | ||
- Visualizing model results |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,112 @@ | ||
Welcome to PT-MELT's documentation! | ||
=================================== | ||
|
||
``PT-MELT`` (PyTorch Machine Learning Toolbox) is a collection of architectures, | ||
processing, and utilities that are transferable over a range of ML applications. | ||
|
||
``PT-MELT`` is a toolbox for researchers to use for machine learning applications in the | ||
PyTorch language. The goal of this software is to enable fast start-up of machine | ||
learning tasks and to provide a reliable and flexible framework for development and | ||
deployment. The toolbox contains generalized methods for every aspect of the machine | ||
learning workflow while simultaneously providing routines that can be tailored to | ||
specific application spaces. | ||
|
||
``PT-MELT`` is developed alongside the ``TF-MELT`` toolbox | ||
(https://github.com/NREL/tf-melt), with a similar design philosophy and structure. | ||
Because of this, the two toolboxes share many of the same features, capabilities, | ||
documentation, and examples. Eventually, the two toolboxes might be merged into a single | ||
toolbox or leverage a separate, shared library. | ||
|
||
The toolbox is structured with the following modules further described in the | ||
``PT-MELT`` :ref:`Package <ptmelt-package>` section: | ||
|
||
- ``PT-MELT`` :ref:`Models Module <ptmelt.models>` - Contains a collection of pre-built | ||
models that can be used for a variety of machine learning tasks. | ||
|
||
The models currently available are: | ||
|
||
- `Artificial Neural Network (ANN)` - A simple feedforward neural network with | ||
customizable layers and activation functions. | ||
- `Residual Neural Network (ResNet)` - A neural network architecture with | ||
customizable residual blocks. | ||
|
||
- ``PT-MELT`` :ref:`Blocks Module <ptmelt.blocks>` - Contains a collection of pre-built | ||
blocks that can be used to build custom models. These blocks are designed to be easily | ||
imported and used in custom models. Refer to the :ref:`Models <ptmelt.models>` module | ||
for examples of how to use these effectively. | ||
|
||
The blocks currently available are: | ||
|
||
- `DenseBlock` - A dense block for fully-connected models. | ||
- `ResidualBlock` - A residual block with skip connections. | ||
- `DefualtOutput` - A single dense layer for output. | ||
- `MixtureDensityOutput` - A dense layer with mixture model output for multiple | ||
means and variances with learnable mixture coefficients. | ||
|
||
- ``PT-MELT`` :ref:`Losses Module <ptmelt.losses>` - Contains a collection of pre-built | ||
loss functions that can be used for a variety of machine learning tasks. These loss | ||
functions are designed to be easily imported and used in custom models. Refer to the | ||
:ref:`Models <ptmelt.models>` module for examples of how to use these effectively. | ||
|
||
The loss functions currently available are: | ||
|
||
- `MixtureDensityLoss` - A negative log likelihood loss function for single and | ||
multiple mixture models. | ||
|
||
The toolbox also includes a :ref:`Utilities Subpackage <ptmelt.utils>`, which contains a | ||
collection of functions useful for data preprocessing, model evaluation, visualization, | ||
and other tasks. | ||
|
||
The utility modules currently available are: | ||
|
||
- :ref:`Evaluation Module <ptmelt.utils.evaluation>` - Contains a collection of | ||
functions for evaluating machine learning models. Useful for evaluating ``PT-MELT`` | ||
model performance and extracting uncertainty quantification metrics. | ||
|
||
- :ref:`Preprocessing Module <ptmelt.utils.preprocessing>` - Contains a collection of | ||
functions for preprocessing data for machine learning tasks. Leverages | ||
``Scikit-learn`` preprocessing functions and implements additional helper functions. | ||
|
||
- :ref:`Statistics Module <ptmelt.utils.statistics>` - Contains a collection of | ||
functions for calculating statistics and metrics for machine learning tasks. Designed | ||
to be utilized by the other utility functions. | ||
|
||
- :ref:`Visualization Module <ptmelt.utils.visualization>` - Contains a collection of | ||
functions for visualizing data and model performance. Designed to easily generate | ||
plots of model performance, but can also be customized for user preferences. | ||
|
||
|
||
Also included in the ``PT-MELT`` repo is an :ref:`Examples <examples>` directory, which | ||
contains a set of jupyter notebooks that demonstrate how to use the different modules in | ||
the toolbox for the full machine learning workflow (e.g., data preprocessing, model | ||
creation, training, evaluation, and visualization). | ||
|
||
|
||
Finally, these docs are contained in the **Docs** directory, which can be built using | ||
Sphinx. | ||
|
||
Contact | ||
======= | ||
|
||
If you have any questions, issues, or feedback regarding ``PT-MELT``, please feel free | ||
to contact the authors: | ||
|
||
- Email: [nwimer@nrel.gov] | ||
- GitHub: [https://github.com/NREL/pt-melt] | ||
|
||
We look forward to hearing from you! | ||
|
||
|
||
.. toctree:: | ||
:maxdepth: 2 | ||
:caption: Contents | ||
|
||
modules | ||
|
||
Indices and tables | ||
================== | ||
|
||
* :ref:`genindex` | ||
* :ref:`modindex` | ||
* :ref:`search` | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
pt-melt | ||
======= | ||
|
||
.. toctree:: | ||
:maxdepth: 4 | ||
|
||
ptmelt | ||
examples |
Oops, something went wrong.