Merge pull request #1 from NREL/refactor

Refactor

.github/workflows/docs.yml

@@ -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 }}

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)

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

Docs/source/conf.py

@@ -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
+}

Docs/source/examples.rst

@@ -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

Docs/source/index.rst

@@ -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`
+

Docs/source/modules.rst

@@ -0,0 +1,8 @@
+pt-melt
+=======
+
+.. toctree::
+   :maxdepth: 4
+
+   ptmelt
+   examples