Mdbook

.github/workflows/Book.yml

@@ -0,0 +1,51 @@
+name: Book
+on:
+  pull_request:
+    branches: main
+  push:
+    branches: main
+env:
+  CARGO_TERM_COLOR: always
+jobs:
+  mdbook:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          default: true
+          toolchain: stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: mdbook
+        run: cargo install mdbook mdbook-katex
+      - name: pancax
+        run: pip install -e .[cpu,docs] pancax
+      # - name: test
+      #   run: mdbook test --library-path target/release/deps/
+      - name: pydoc-markdown
+        run: |
+          pip install pydoc-markdown
+          mkdir book/api
+          pydoc-markdown -I . -p pancax --render-toc > book/api/pancax.md
+      - name: build
+        run: mdbook build
+      - name: move
+        run: mkdir -p _site/ && cp -r book/build/* _site/
+      - name: upload
+        uses: actions/upload-pages-artifact@v3
+  deploy:
+    if: github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: mdbook
+    permissions:
+      id-token: write
+      pages: write
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/Docs.yml

@@ -1,31 +1,31 @@
-name: Documentation
+# name: Documentation
 
-on:
-  push:
-    branches: main
-permissions:
-  contents: write
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    container: mrbuche/exodus
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
-      with:
-          python-version: '3.11'
-    - name: Install
-      run: |
-        python -m venv venv
-        . venv/bin/activate
-        pip install .[cpu,docs]
-        cd docs
-        sphinx-apidoc -o source/ ../pancax -P
-        make html
-    - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        publish_branch: gh-pages
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/build/html
-        force_orphan: true
+# on:
+#   push:
+#     branches: main
+# permissions:
+#   contents: write
+# jobs:
+#   docs:
+#     runs-on: ubuntu-latest
+#     container: mrbuche/exodus
+#     steps:
+#     - uses: actions/checkout@v4
+#     - uses: actions/setup-python@v5
+#       with:
+#           python-version: '3.11'
+#     - name: Install
+#       run: |
+#         python -m venv venv
+#         . venv/bin/activate
+#         pip install .[cpu,docs]
+#         cd docs
+#         sphinx-apidoc -o source/ ../pancax -P
+#         make html
+#     - name: Deploy
+#       uses: peaceiris/actions-gh-pages@v3
+#       with:
+#         publish_branch: gh-pages
+#         github_token: ${{ secrets.GITHUB_TOKEN }}
+#         publish_dir: docs/build/html
+#         force_orphan: true

.gitignore

@@ -11,6 +11,8 @@
 *.vtm
 *.vtu
 .coverage
+book/api/*
+book/build
 docs/source/modules.rst
 docs/source/pancax.*
 dead_code/

README.md

@@ -1,3 +1,4 @@
+[![book](https://img.shields.io/badge/pancax-Book-blue?logo=mdbook&logoColor=000000)](https://sandialabs.github.io/pancax)
 [![Build Status](https://github.com/sandialabs/pancax/workflows/CI/badge.svg)](https://github.com/sandialabs/pancax/actions?query=workflow%3ACI)
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://sandialabs.github.io/pancax/) 
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://sandialabs.github.io/pancax/dev/) 

book.toml

@@ -0,0 +1,22 @@
+[book]
+authors = ["Craig M. Hamel"]
+language = "en"
+multilingual = false
+src = "book/"
+title = "pancax"
+
+[build]
+build-dir = "book/build/"
+create-missing = false
+
+[rust]
+edition = "2021"
+
+[output.html]
+edit-url-template = "https://github.com/sandialabs/pancax/edit/main/{path}"
+git-repository-url = "https://github.com/sandialabs/pancax"
+
+# [preprocessor.cmdrun]
+
+[preprocessor.katex]
+after = ["links"]

book/SUMMARY.md

@@ -0,0 +1,5 @@
+# pancax
+Welcome to the pancax book
+
+- [Introduction](./introduction.md)
+- [API Documentation](./api/pancax.md)

book/introduction.md

@@ -0,0 +1,7 @@
+Welcome to the pancax book!
+
+# Description
+Pancax is a set of tool written on top of jax and equinox to facilitate research that leverages physics informed neural networks (PINNs) in challenging application domains such as computational solid mechanics. 
+
+# Remainder of the book
+The remainder of the book is outlined as follows...

pancax/constitutive_models/base.py

@@ -34,10 +34,11 @@ def I1(self, F: Tensor) -> Scalar:
     r"""
     Calculates the first invariant
 
-    :param F: the deformation gradient
+    - **F**: the deformation gradient
 
-    .. math::
-      I_1 = tr\left(\mathbf{F}^T\mathbf{F}\right)
+    $$
+    I_1 = tr\left(\mathbf{F}^T\mathbf{F}\right)
+    $$
     """
     I1 = jnp.trace(F @ F.T)
     return I1
@@ -46,10 +47,11 @@ def I1_bar(self, F: Tensor) -> Scalar:
     r"""
     Calculates the first distortional invariant
 
-    :param F: the deformation gradient
-
-    .. math::
-      \bar{I}_1 = J^{-2/3}tr\left(\mathbf{F}^T\mathbf{F}\right)
+    - **F**: the deformation gradient
+
+    $$
+    \bar{I}_1 = J^{-2/3}tr\left(\mathbf{F}^T\mathbf{F}\right)
+    $$
     """
     I1 = jnp.trace(F @ F.T)
     J = self.jacobian(F)
@@ -76,11 +78,11 @@ def jacobian(self, F: Tensor) -> Scalar:
     to return nonsensical numbers if a non-positive jacobian
     is encountered during training.
 
-    :param F: the deformation gradient
+    - **F**: the deformation gradient
 
-    .. math::
-      J = det(\mathbf{F})
-
+    $$
+    J = det(\mathbf{F})
+    $$
     """
     J = jnp.linalg.det(F)
     J = jax.lax.cond(

pancax/constitutive_models/gent.py

@@ -8,9 +8,9 @@ class Gent(BaseConstitutiveModel):
   r"""
 	Gent model with the following model form
 
-	.. math::
-		\psi(\mathbf{F}) = \frac{1}{2}K\left[\frac{1}{2}\left(J^2 - \ln J\right)\right] -
-						           \frac{1}{2}GJ_m\ln\left(1 - \frac{\bar{I}_1 - 3}{J_m}\right)
+	$$
+  \psi(\mathbf{F}) = \frac{1}{2}K\left[\frac{1}{2}\left(J^2 - \ln J\right)\right] - \frac{1}{2}GJ_m\ln\left(1 - \frac{\bar{I}_1 - 3}{J_m}\right)
+  $$
 	"""
   bulk_modulus: Property
   shear_modulus: Property

pancax/constitutive_models/neohookean.py

@@ -7,9 +7,9 @@ class NeoHookean(BaseConstitutiveModel):
   r"""
 	NeoHookean model with the following model form
 
-	.. math::
-		\psi(\mathbf{F}) = \frac{1}{2}K\left[\frac{1}{2}\left(J^2 - \ln J\right)\right] +
-						   \frac{1}{2}G\left(\bar{I}_1 - 3\right)
+	$$
+  \psi(\mathbf{F}) = \frac{1}{2}K\left[\frac{1}{2}\left(J^2 - \ln J\right)\right] + \frac{1}{2}G\left(\bar{I}_1 - 3\right)
+  $$
 	"""
   bulk_modulus: Property
   shear_modulus: Property

pancax/constitutive_models/swanson.py

@@ -8,10 +8,11 @@ class Swanson(BaseConstitutiveModel):
   r"""
 	Swanson model truncated to 4 parameters
 
-	.. math::
-		\psi(\mathbf{F}) = K\left(J\ln J - J + 1\right) +
-							         \frac{3}{2}A_1\left(\frac{\bar{I}_1}{3} - 1\right)^{P_1} + 
-                       \frac{3}{2}C_1\left(\frac{\bar{I}_1}{3} - 1\right)^{R_1}
+	$$
+  \psi(\mathbf{F}) = K\left(J\ln J - J + 1\right) +
+                     \frac{3}{2}A_1\left(\frac{\bar{I}_1}{3} - 1\right)^{P_1} + 
+                     \frac{3}{2}C_1\left(\frac{\bar{I}_1}{3} - 1\right)^{R_1}
+  $$
 	"""
   bulk_modulus: Property
   A1: Property