diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..a9d0d112 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,65 @@ +# Simple workflow for deploying static content to GitHub Pages +name: docs (gh-pages) + +on: + push: + branches: ["develop"] + + # For testing only + pull_request: + + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build-docs: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout repository + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz + - name: Install Python dependencies + run: | + python3 -m pip install --upgrade pip + pip install -r docs/requirements.txt + - name: Build documentation + run: | + cd docs + make html + # env: + # SPHINXOPTS: "-W --keep-going" + - name: Check for broken links + run: | + cd docs + make linkcheck + continue-on-error: true + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + if: success() + with: + path: "docs/build/html" + retention-days: 3 # Custom retention for this artifact + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000..dd0cb503 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,46 @@ +# Doxyfile for AMS C++ Documentation + +PROJECT_NAME = "AMS" +PROJECT_BRIEF = "Autonomous MultiScale Library" +PROJECT_NUMBER = 0.1.0 + +OUTPUT_DIRECTORY = build +CREATE_SUBDIRS = NO + +INPUT = ../src +RECURSIVE = YES +FILE_PATTERNS = *.hpp *.h *.cpp + +EXCLUDE_PATTERNS = */tests/* */examples/* + +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_OUTPUT = xml + +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES + +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO + +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = NO +WARN_IF_DOC_ERROR = YES + +JAVADOC_AUTOBRIEF = YES +QT_AUTOBRIEF = YES + +CLASS_DIAGRAMS = YES +HAVE_DOT = YES +DOT_NUM_THREADS = 4 +UML_LOOK = YES +TEMPLATE_RELATIONS = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES + +BUILTIN_STL_SUPPORT = YES diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..dd6a5b65 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,35 @@ +# 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 clean doxygen + +# Generate Doxygen documentation for C++ code +doxygen: + @echo "Generating Doxygen XML..." + @mkdir -p build/xml + @doxygen Doxyfile + +# Clean all build artifacts +clean: + rm -rf $(BUILDDIR)/* + rm -rf build/xml + rm -rf source/api + +# Build HTML documentation with Doxygen +html: doxygen + @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile doxygen + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..af065655 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +# AMS Documentation + +## Build Instructions + +To get setup with a virtual environment run: + +```bash +python3 -m venv -m ams-doc +. ams-doc/bin/activate +cd AMS/docs +pip install -r requirements.txt +``` + +Then you can build the documention locally with: +```bash +make html +``` + +This step can take > 2 minutes due to the use of Exhale which reads all the Doxygen XML files +and generates a nice Sphinx-like documentation. \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..225a72aa --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,10 @@ +# Documentation build dependencies +sphinx>=7.0.0 +sphinx-rtd-theme>=2.0.0 +sphinx-copybutton>=0.5.2 +breathe>=4.35.0 +exhale>=0.3.0 +myst-parser>=2.0.0 +sphinx-autobuild>=2024.10.3 +sphinx-design>=0.6.1 +furo>=2025.9.25 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..4cf084c2 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,139 @@ +# 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 + +# -- Project information ----------------------------------------------------- +project = 'AMS' +copyright = '2023-2025, Lawrence Livermore National Security, LLC' +author = 'AMS Development Team' + +# The version info for the project +# Read from VERSION file or git +version = '0.1' +# release = '0.1.0' + +# -- General configuration --------------------------------------------------- +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', + 'sphinx.ext.graphviz', + 'breathe', # For C++ documentation + 'exhale', # For C++ search + integration + 'myst_parser', # For Markdown support + 'sphinx_copybutton', # Add copy button to code blocks + "sphinx_design" # Furo theme +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The suffix(es) of source filenames. +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +# The master toctree document. +master_doc = 'index' + +# -- Options for HTML output ------------------------------------------------- +# html_theme = 'sphinx_rtd_theme' +html_theme = "furo" +html_static_path = ['_static'] + + +# Tell sphinx what the primary language being documented is. +primary_domain = "cpp" +highlight_language = "cpp" + +html_context = { + "display_github": True, + "github_user": "LLNL", + "github_repo": "AMS", + "github_version": "develop", + "conf_py_path": "/docs/source/", +} + +# -- Options for autodoc ----------------------------------------------------- +autodoc_default_options = { + 'members': True, + 'member-order': 'bysource', + 'special-members': '__init__', + 'undoc-members': True, + 'exclude-members': '__weakref__' +} + +# -- Options for Napoleon (Google/NumPy style docstrings) ------------------- +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = False +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_preprocess_types = False +napoleon_type_aliases = None +napoleon_attr_annotations = True + +# -- Options for Breathe (C++ documentation) --------------------------------- +breathe_projects = { + "AMS": "../build/xml" +} +breathe_default_project = "AMS" + +# -- Options for intersphinx ------------------------------------------------- +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'numpy': ('https://numpy.org/doc/stable/', None), + 'torch': ('https://pytorch.org/docs/stable/', None), +} + +# Setup the exhale extension +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "library_root.rst", + "doxygenStripFromPath": "..", + # Heavily encouraged optional argument (see docs) + # "rootFileTitle": "API", + # "fullApiSubSectionTitle": "", + "createTreeView": True, + # TIP: if using the sphinx-bootstrap-theme, you need + # "treeViewIsBootstrap": True, + "exhaleExecutesDoxygen": True, + "exhaleDoxygenStdin": "INPUT = ../../src" +} + +# -- Options for MyST Parser ------------------------------------------------- +myst_enable_extensions = [ + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "linkify", + "replacements", + "smartquotes", + "strikethrough", + "substitution", + "tasklist", +] + +# -- Options for copybutton -------------------------------------------------- +copybutton_prompt_text = r">>> |\.\.\. |\$ " +copybutton_prompt_is_regexp = True diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..e33f5a0e --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,62 @@ +Autonomous MultiScale Library +============================= + +.. image:: https://img.shields.io/badge/license-Apache%202.0%20with%20LLVM%20exceptions-blue.svg + :target: https://github.com/LLNL/AMS/blob/develop/LICENSE + :alt: License + +.. image:: https://img.shields.io/github/stars/LLNL/AMS + :target: https://github.com/LLNL/AMS + :alt: GitHub Stars + +Autonomous MultiScale (AMS) is a framework designed to simplify the integration of machine learning (ML) surrogate models +in multiphysics high-performance computing (HPC) codes. + +Overview +-------- + +AMS provides the end-to-end infrastructure to automate all steps in the process +from testing and deploying ML surrogate models in +scientific applications. With simple code modifications, developers can integrate +AMS into their scientific workflows to make multiphysics codes: + +* **Faster** - by replacing expensive evaluations with reliable surrogate models + backed by verified fallbacks. +* **More Accurate** - by increasing the effective fidelity of subscale models + beyond what is currently feasible. +* **Portable** - by providing a general framework applicable to a wide range of + use cases. + +Key Features +------------ + +* **Automated Workflow**: Automation of ML surrogate models deployment and testing. +* **HPC Integration**: Designed for supercomputing environments. +* **Multiple Backend Support**: CPU, or GPU (CUDA and HIP). +* **Database Integration**: Support for HDF5 and RabbitMQ. +* **Surrogate Model Support**: PyTorch. +* **Performance Monitoring**: Built-in Caliper support. + +Quick Links +----------- + +* **GitHub Repository**: https://github.com/LLNL/AMS +* **Issue Tracker**: https://github.com/LLNL/AMS/issues + +Citation +-------- + +If you use this software, please cite it as: + +.. code-block:: bibtex + + @software{ams2023, + author = {Bhatia, Harsh and Patki, Tapasya A. and Brink, Stephanie and + Pottier, Loïc and Stitt, Thomas M. and Parasyris, Konstantinos and + Milroy, Daniel J. and Laney, Daniel E. and Blake, Robert C. and + Yeom, Jae-Seung and Bremer, Peer-Timo and Doutriaux, Charles}, + title = {Autonomous MultiScale Library}, + url = {https://github.com/LLNL/AMS}, + year = {2023}, + doi = {10.11578/dc.20230721.1} + } diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..694b63d9 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,66 @@ +Installation +============ + +This page provides detailed instructions for installing AMS on various systems. + +Requirements +------------ + +AMS has several dependencies that need to be installed before building: + +Core Dependencies +~~~~~~~~~~~~~~~~~ + +* **CMake** >= 3.25 +* **C++17** compatible compiler (GCC >= 8.5) +* **Python** >= 3.10 (for Python bindings) +* **PyTorch** >= 2.0 (for ML model support) +* **HDF5** (for data storage) + +Optional Dependencies +~~~~~~~~~~~~~~~~~~~~~ + +* **CUDA** >= 11.0 (for NVIDIA GPU support) +* **HIP** >= 6.4 (for AMD GPU support) +* **MPI** (for distributed computing) +* **RabbitMQ/AMQP-CPP** (for message queue support) +* **Caliper** (for performance profiling) + +Installation Methods +-------------------- + +Using Spack +~~~~~~~~~~~ + +TBD + +Manual Build with CMake +~~~~~~~~~~~~~~~~~~~~~~~ + +For a basic installation: + +.. code-block:: bash + + git clone https://github.com/LLNL/AMS.git + cd AMS + mkdir build && cd build + + cmake \ + -DWITH_RMQ=On \ + -Damqpcpp_DIR=$AMS_AMQPCPP_PATH \ + -DWITH_CALIPER=On \ + -DWITH_HDF5=On \ + -DHDF5_Dir=$AMS_HDF5_PATH \ + -DCMAKE_INSTALL_PREFIX=./install \ + -DCMAKE_BUILD_TYPE=Release \ + -DWITH_CUDA=On \ + -DWITH_MPI=On \ + -DWITH_TESTS=On \ + -DTorch_DIR=$AMS_TORCH_PATH + -DWITH_EXAMPLES=On \ + .. + + make -j 4 + make install + +For complete installation instructions, see the repository's INSTALL.md file.