From 117b0b3e2e4625e4ae23d66e3abc39f60f04ec4d Mon Sep 17 00:00:00 2001 From: Loic Pottier Date: Tue, 9 Dec 2025 18:13:48 -0800 Subject: [PATCH 1/6] First draft for a documentation Signed-off-by: Loic Pottier --- .github/workflows/docs.yml | 61 +++++++++++++++ docs/Doxyfile | 46 ++++++++++++ docs/Makefile | 35 +++++++++ docs/README.md | 20 +++++ docs/requirements.txt | 10 +++ docs/source/conf.py | 139 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 74 +++++++++++++++++++ docs/source/installation.rst | 74 +++++++++++++++++++ 8 files changed, 459 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/Doxyfile create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/requirements.txt create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..cf90c900 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,61 @@ +# Simple workflow for deploying static content to GitHub Pages +name: docs (gh-pages) + +on: + push: + branches: ["develop"] + + 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" + - 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..510c4ef4 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,74 @@ +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 training, testing, and deploying machine learning surrogate models in +scientific applications. With simple code modifications, developers can integrate +AMS into their scientific workflows to make multiphysics simulations: + +* **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 ML Workflow**: Training, testing, and deployment automation. +* **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. + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + installation + +.. toctree:: + :maxdepth: 2 + :caption: API Reference + + api/library_root + +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..e8e6b63a --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,74 @@ +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) + +Optional Dependencies +~~~~~~~~~~~~~~~~~~~~~ + +* **CUDA** >= 11.0 (for NVIDIA GPU support) +* **HIP** >= 6.4 (for AMD GPU support) +* **MPI** (for distributed computing) +* **PyTorch** >= 2.0 (for ML model support) +* **HDF5** (for data storage) +* **RabbitMQ/AMQP-CPP** (for message queue support) +* **Caliper** (for performance profiling) + +Installation Methods +-------------------- + +Using Spack (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The preferred method to install AMS is through Spack: + +.. code-block:: bash + + # Install via Spack + spack install ams + + # For developers + spack dev-build ams@develop + +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. From e8bfbeebb8e6a36b787e4b774719db46534cf79f Mon Sep 17 00:00:00 2001 From: Loic Pottier Date: Tue, 9 Dec 2025 18:18:00 -0800 Subject: [PATCH 2/6] Triggered doc building in CI Signed-off-by: Loic Pottier --- .github/workflows/docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cf90c900..6a2f9ffc 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,8 +2,9 @@ name: docs (gh-pages) on: - push: - branches: ["develop"] + # push: + # branches: ["develop"] + pull_request: workflow_dispatch: From d27a43d63ac2f7ce89a37ef7500c1efa5247c20b Mon Sep 17 00:00:00 2001 From: Loic Pottier Date: Tue, 9 Dec 2025 19:04:31 -0800 Subject: [PATCH 3/6] Ignore warning during compilation Signed-off-by: Loic Pottier --- .github/workflows/docs.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6a2f9ffc..98f15029 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,8 +2,10 @@ name: docs (gh-pages) on: - # push: - # branches: ["develop"] + push: + branches: ["develop"] + + # For testing only pull_request: workflow_dispatch: @@ -43,8 +45,8 @@ jobs: run: | cd docs make html - env: - SPHINXOPTS: "-W --keep-going" + # env: + # SPHINXOPTS: "-W --keep-going" - name: Check for broken links run: | cd docs From f48703efc8a5e62bc308c143de61a917a3a41b37 Mon Sep 17 00:00:00 2001 From: Loic Pottier Date: Tue, 9 Dec 2025 20:21:41 -0800 Subject: [PATCH 4/6] Trigger CI From a68aa5519683cd6f88b8d6e1a7dd54b11cab6452 Mon Sep 17 00:00:00 2001 From: Loic Pottier Date: Wed, 10 Dec 2025 12:07:01 -0800 Subject: [PATCH 5/6] Adding short time retention for the artifact to not use too much space Signed-off-by: Loic Pottier --- .github/workflows/docs.yml | 1 + docs/source/index.rst | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 98f15029..a9d0d112 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -59,6 +59,7 @@ jobs: 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/source/index.rst b/docs/source/index.rst index 510c4ef4..7c16ff8f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,9 +16,9 @@ Overview -------- AMS provides the end-to-end infrastructure to automate all steps in the process -from training, testing, and deploying machine learning surrogate models in +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 simulations: +AMS into their scientific workflows to make multiphysics codes: * **Faster** - by replacing expensive evaluations with reliable surrogate models backed by verified fallbacks. @@ -30,7 +30,7 @@ AMS into their scientific workflows to make multiphysics simulations: Key Features ------------ -* **Automated ML Workflow**: Training, testing, and deployment automation. +* **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. From f608e79d60f6f5745887a74cb3ac0723e4ee070d Mon Sep 17 00:00:00 2001 From: Loic Pottier Date: Wed, 10 Dec 2025 12:19:31 -0800 Subject: [PATCH 6/6] Updated text + minor tweaks Signed-off-by: Loic Pottier --- docs/source/index.rst | 12 ------------ docs/source/installation.rst | 24 ++++++++---------------- 2 files changed, 8 insertions(+), 28 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 7c16ff8f..e33f5a0e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -37,18 +37,6 @@ Key Features * **Surrogate Model Support**: PyTorch. * **Performance Monitoring**: Built-in Caliper support. -.. toctree:: - :maxdepth: 2 - :caption: Getting Started - - installation - -.. toctree:: - :maxdepth: 2 - :caption: API Reference - - api/library_root - Quick Links ----------- diff --git a/docs/source/installation.rst b/docs/source/installation.rst index e8e6b63a..694b63d9 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -11,9 +11,11 @@ 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) +* **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 ~~~~~~~~~~~~~~~~~~~~~ @@ -21,26 +23,16 @@ Optional Dependencies * **CUDA** >= 11.0 (for NVIDIA GPU support) * **HIP** >= 6.4 (for AMD GPU support) * **MPI** (for distributed computing) -* **PyTorch** >= 2.0 (for ML model support) -* **HDF5** (for data storage) * **RabbitMQ/AMQP-CPP** (for message queue support) * **Caliper** (for performance profiling) Installation Methods -------------------- -Using Spack (Recommended) -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The preferred method to install AMS is through Spack: - -.. code-block:: bash - - # Install via Spack - spack install ams +Using Spack +~~~~~~~~~~~ - # For developers - spack dev-build ams@develop +TBD Manual Build with CMake ~~~~~~~~~~~~~~~~~~~~~~~