Skip to content

Commit 32f1944

Browse files
dreamer2368dreamer2368
authored
Sphinx API documentation framework (#11)
* initial loading of sphinx api documentation * docker container and ci workflow * pip install fix * custom build command instead of github action * another try.. * without docker * check resulting file * fix artifact path * deploy only when pushed to main * updating front page * deploy only when pushed to main * added references * added a reference * example comments on timing.py * v2.0.0 tag
1 parent 4932179 commit 32f1944

File tree

12 files changed

+377
-3
lines changed

12 files changed

+377
-3
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: CI
2+
on:
3+
push:
4+
branches:
5+
- main
6+
workflow_dispatch: {}
7+
pull_request:
8+
types: [opened, synchronize]
9+
branches:
10+
- main
11+
12+
jobs:
13+
# docker-image:
14+
# uses: ./.github/workflows/docker.yml
15+
api-doc:
16+
# needs: [docker-image]
17+
uses: ./.github/workflows/sphinx.yml

‎.github/workflows/docker.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: docker-image
2+
on:
3+
workflow_call:
4+
5+
env:
6+
REGISTRY: ghcr.io
7+
# github.repository as <account>/<repo>
8+
IMAGE_NAME: LLNL/GPLaSDI/lasdi_env
9+
DOCKERPATH: docker
10+
11+
jobs:
12+
docker-ci:
13+
runs-on: ubuntu-latest
14+
name: "docker env"
15+
env:
16+
DOCKERPATH: docker
17+
steps:
18+
- name: test command
19+
run: echo "docker-ci command"
20+
- uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
- name: Set up QEMU
24+
uses: docker/setup-qemu-action@v3
25+
- name: Set up Docker Buildx
26+
uses: docker/setup-buildx-action@v3
27+
- uses: Ana06/get-changed-files@v2.2.0
28+
id: files
29+
- name: DockerPATH configuration
30+
run: echo "DOCKERPATH=$DOCKERPATH"
31+
- name: DockerPATH - check if files in docker path changed
32+
if: contains(steps.files.outputs.all,env.DOCKERPATH) || contains(steps.files.outputs.all,'docker.yml')
33+
run: |
34+
echo "CI container needs rebuilding..."
35+
echo "CI_NEEDS_REBUILD=true" >> $GITHUB_ENV
36+
- name: Log into registry ${{ env.REGISTRY }}
37+
if: env.CI_NEEDS_REBUILD
38+
uses: docker/login-action@v3
39+
with:
40+
registry: ${{ env.REGISTRY }}
41+
username: ${{ github.actor }}
42+
password: ${{ secrets.GITHUB_TOKEN }}
43+
- name: Extract metadata (tags, labels) for Docker
44+
id: meta
45+
if: env.CI_NEEDS_REBUILD
46+
uses: docker/metadata-action@v4
47+
with:
48+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
49+
tags: type=sha
50+
flavor: latest=true
51+
- name: Build Container motd
52+
if: env.CI_NEEDS_REBUILD
53+
run: |
54+
echo "#!/bin/bash" > ${{env.DOCKERPATH}}/motd.sh
55+
echo "echo --------------------------" >> ${{env.DOCKERPATH}}/motd.sh
56+
echo "echo lasdi_env/CI Development Container" >> ${{env.DOCKERPATH}}/motd.sh
57+
echo "echo \"Revision: `echo ${GITHUB_SHA} | cut -c1-8`\"" >> ${{env.DOCKERPATH}}/motd.sh
58+
echo "echo --------------------------" >> ${{env.DOCKERPATH}}/motd.sh
59+
chmod 755 ${{env.DOCKERPATH}}/motd.sh
60+
cat ${{env.DOCKERPATH}}/motd.sh
61+
- name: Docker Image - Build and push
62+
if: env.CI_NEEDS_REBUILD
63+
uses: docker/build-push-action@v5
64+
with:
65+
push: true
66+
context: ${{ env.DOCKERPATH }}
67+
tags: ${{ steps.meta.outputs.tags }}
68+
# platforms: linux/amd64,linux/arm64
69+
platforms: linux/amd64

‎.github/workflows/sphinx.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: "Sphinx: Render docs"
2+
3+
# on: push
4+
on:
5+
workflow_call:
6+
7+
jobs:
8+
build:
9+
runs-on: ubuntu-latest
10+
# container:
11+
# image: ghcr.io/llnl/gplasdi/lasdi_env:latest
12+
# options: --user 1001 --privileged
13+
# volumes:
14+
# - /mnt:/mnt
15+
permissions:
16+
contents: write
17+
steps:
18+
- name: Cancel previous runs
19+
uses: styfle/cancel-workflow-action@0.11.0
20+
with:
21+
access_token: ${{ github.token }}
22+
- uses: actions/checkout@v4
23+
- name: Build HTML
24+
uses: ammaraskar/sphinx-action@master
25+
with:
26+
docs-folder: "docs/"
27+
build-command: "sphinx-build -b html source build"
28+
pre-build-command: "pip install --upgrade pip && pip install sphinx-autoapi sphinx_rtd_theme"
29+
# run: |
30+
# sphinx-build --version
31+
# cd ${GITHUB_WORKSPACE}/docs
32+
# mkdir build
33+
# sphinx-build -b html source/ build/
34+
- name: check resulting files
35+
run: |
36+
ls ${GITHUB_WORKSPACE}/docs/build
37+
- name: Upload artifacts
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: html-docs
41+
path: docs/build/
42+
- name: Deploy
43+
uses: peaceiris/actions-gh-pages@v3
44+
# if: github.ref == 'refs/heads/main'
45+
with:
46+
github_token: ${{ secrets.GITHUB_TOKEN }}
47+
publish_dir: docs/build

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ examples/results
77
examples/checkpoint
88
*.npy
99
build
10+
docs/build

‎docker/Dockerfile‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
FROM ubuntu:22.04
2+
3+
ENV ENVDIR=env
4+
5+
# install sudo
6+
RUN apt-get -yq update && apt-get -yq install sudo
7+
8+
WORKDIR /$ENVDIR
9+
10+
# install packages
11+
RUN sudo apt-get install -yq git
12+
RUN sudo apt-get install --no-install-recommends -yq make gcc gfortran libssl-dev cmake
13+
RUN sudo apt-get install -yq libopenblas-dev libmpich-dev libblas-dev liblapack-dev libscalapack-mpi-dev libhdf5-mpi-dev hdf5-tools
14+
# RUN sudo apt-get install -yq vim
15+
RUN sudo apt-get install -yq git-lfs
16+
# RUN sudo apt-get install -yq valgrind
17+
RUN sudo apt-get install -yq wget
18+
# RUN sudo apt-get install -yq astyle
19+
20+
# install python
21+
RUN sudo apt-get install -yq python3
22+
RUN sudo apt-get install -yq python3-dev
23+
RUN sudo apt-get install -yq python3-pip
24+
RUN sudo apt-get install python-is-python3
25+
RUN sudo python -m pip install --upgrade pip
26+
RUN sudo python -m pip install sphinx sphinx-autoapi sphinx_rtd_theme
27+
#RUN sudo pip3 install numpy scipy argparse tables PyYAML h5py pybind11 pytest mpi4py merlin
28+
#
29+
RUN sudo apt-get clean -q
30+
31+
# create and switch to a user
32+
ENV USERNAME=test
33+
RUN echo "$USERNAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
34+
RUN useradd --no-log-init -u 1001 --create-home --shell /bin/bash $USERNAME
35+
RUN adduser $USERNAME sudo
36+
USER $USERNAME
37+
WORKDIR /home/$USERNAME

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
import os, sys
10+
sys.path.insert(0, os.path.abspath('.'))
11+
sys.path.insert(0, os.path.abspath('..'))
12+
sys.path.insert(0, os.path.abspath('../../src'))
13+
14+
project = 'LaSDI'
15+
copyright = '2023-2024, Lawrence Livermore National Security, LLC and other LaSDI project developers.'
16+
author = 'Christophe Bonneville, Kevin Chung, Youngsoo Choi'
17+
release = '2.0'
18+
19+
# -- General configuration ---------------------------------------------------
20+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
21+
22+
extensions = [
23+
'autoapi.extension',
24+
'sphinx.ext.napoleon',
25+
]
26+
27+
autoapi_dirs = ['../../src']
28+
29+
napoleon_google_docstring = False
30+
napoleon_use_param = False
31+
napoleon_use_ivar = True
32+
33+
templates_path = ['_templates']
34+
exclude_patterns = []
35+
36+
37+
38+
# -- Options for HTML output -------------------------------------------------
39+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
40+
41+
html_theme = 'sphinx_rtd_theme'
42+
html_static_path = ['_static']

‎docs/source/index.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. LaSDI documentation master file, created by
2+
sphinx-quickstart on Wed Oct 16 22:11:53 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
LaSDI documentation
7+
===================
8+
9+
LaSDI is a light-weight python package for Latent Space Dynamics Identification.
10+
LaSDI maps full-order PDE solutions to a latent space using autoencoders and learns the system of ODEs governing the latent space dynamics.
11+
By interpolating and solving the ODE system in the reduced latent space, fast and accurate ROM predictions can be made by feeding the predicted latent space dynamics into the decoder.
12+
It also supports parametric interpolation of latent dynamics according to uncertainties evaluated via Gaussian process.
13+
14+
.. toctree::
15+
:maxdepth: 2
16+
:caption: Contents:
17+
18+
References
19+
===================
20+
21+
* Bonneville, Christophe, Xiaolong He, April Tran, Jun Sur Park, William Fries, Daniel A. Messenger, Siu Wun Cheung et al. "A Comprehensive Review of Latent Space Dynamics Identification Algorithms for Intrusive and Non-Intrusive Reduced-Order-Modeling." arXiv preprint arXiv:2403.10748 (2024).
22+
* Fries, William D., Xiaolong He, and Youngsoo Choi. "LaSDI: Parametric latent space dynamics identification." Computer Methods in Applied Mechanics and Engineering 399 (2022): 115436.
23+
* He, Xiaolong, Youngsoo Choi, William D. Fries, Jonathan L. Belof, and Jiun-Shyan Chen. "gLaSDI: Parametric physics-informed greedy latent space dynamics identification." Journal of Computational Physics 489 (2023): 112267.
24+
* Tran, April, Xiaolong He, Daniel A. Messenger, Youngsoo Choi, and David M. Bortz. "Weak-form latent space dynamics identification." Computer Methods in Applied Mechanics and Engineering 427 (2024): 116998.
25+
* Park, Jun Sur Richard, Siu Wun Cheung, Youngsoo Choi, and Yeonjong Shin. "tLaSDI: Thermodynamics-informed latent space dynamics identification." arXiv preprint arXiv:2403.05848 (2024).
26+
* Bonneville, Christophe, Youngsoo Choi, Debojyoti Ghosh, and Jonathan L. Belof. "Gplasdi: Gaussian process-based interpretable latent space dynamics identification through deep autoencoder." Computer Methods in Applied Mechanics and Engineering 418 (2024): 116535.
27+
* He, Xiaolong, April Tran, David M. Bortz, and Youngsoo Choi. "Physics-informed active learning with simultaneous weak-form latent space dynamics identification." arXiv preprint arXiv:2407.00337 (2024).

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "lasdi"
3-
version = "2.0.0-dev"
3+
version = "2.0.0"
44
authors = [
55
{ name="Christophe Bonneville", email="cpb97@cornell.edu" },
66
{ name="Kevin (Seung Whan) Chung", email="chung28@llnl.gov" },

0 commit comments

Comments
 (0)