Added documentation (#17)

Added documentation --------- Co-authored-by: turquoisedragon2926 <[email protected]>
slimgroup · Apr 15, 2024 · f475855 · f475855
1 parent 4ec7e39
commit f475855
Show file tree

Hide file tree

Showing 31 changed files with 810 additions and 304 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/.github/workflows/DocCleanup.yml b/.github/workflows/DocCleanup.yml
@@ -0,0 +1,33 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}
diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml
@@ -0,0 +1,22 @@
+name: Documenter
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.9.4'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia --project=docs/ docs/make.jl
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,4 @@ examples/.ipynb_checkpoints
 *.svg
 *.png
 *.dot
+!logo.png
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 SLIM Group @ Georgia Institute of Technology
+Copyright (c) 2024 SLIM Group @ Georgia Institute of Technology
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/Project.toml b/Project.toml
@@ -1,23 +1,7 @@
 name = "ParametricOperators"
 uuid = "db9e0614-c73c-4112-a40c-114e5b366d0d"
 authors = ["Richard Rex <[email protected]>", "Thomas Grady <[email protected]>"]
-version = "1.1.2"
-
-[compat]
-julia = "1.9.4"
-CUDA = "5.2.0"
-ChainRulesCore = "1.23.0"
-Combinatorics = "1.0.2"
-DataStructures = "0.18.18"
-FFTW = "1.8.0"
-Flux = "0.14.15"
-GraphViz = "0.2.0"
-JSON = "0.21.4"
-LRUCache = "1.6.1"
-LaTeXStrings = "1.3.1"
-MPI = "0.20.19"
-Match = "2.0.0"
-OMEinsum = "0.8.1"
+version = "1.1.3"
 
 [deps]
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
@@ -35,3 +19,19 @@ Match = "7eb4fadd-790c-5f42-8a69-bfa0b872bfbf"
 OMEinsum = "ebe7aa44-baf0-506c-a96f-8464559b3922"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[compat]
+CUDA = "5.2.0"
+ChainRulesCore = "1.23.0"
+Combinatorics = "1.0.2"
+DataStructures = "0.18.18"
+FFTW = "1.8.0"
+Flux = "0.14.15"
+GraphViz = "0.2.0"
+JSON = "0.21.4"
+LRUCache = "1.6.1"
+LaTeXStrings = "1.3.1"
+MPI = "0.20.19"
+Match = "2.0.0"
+OMEinsum = "0.8.1"
+julia = "1.9.4"
diff --git a/README.md b/README.md
@@ -1,9 +1,15 @@
 # ParametricOperators.jl
 
-[![][license-img]][license-status] 
+[![][license-img]][license-status]
+[![Documenter](https://github.com/slimgroup/ParametricOperators.jl/actions/workflows/Documenter.yml/badge.svg)](https://github.com/slimgroup/ParametricOperators.jl/actions/workflows/Documenter.yml)
+[![TagBot](https://github.com/slimgroup/ParametricOperators.jl/actions/workflows/TagBot.yml/badge.svg)](https://github.com/slimgroup/ParametricOperators.jl/actions/workflows/TagBot.yml)
+
 <!-- [![][zenodo-img]][zenodo-status] -->
 
-ParametricOperators.jl is a Julia Language-based scientific library designed to facilitate the creation and manipulation of tensor operations involving large-scale data using Kronecker products. It provides an efficient and mathematically consistent way to express tensor programs and distribution in the context of machine learning.
+`ParametricOperators.jl` is a Julia Language-based scientific library designed to facilitate the creation and manipulation of tensor operations involving large-scale data using Kronecker products. It provides an efficient and mathematically consistent way to express tensor programs and distribution in the context of machine learning.
+
+> [!NOTE]  
+> [`ParametericDFNOs.jl`](https://github.com/slimgroup/ParametericDFNOs.jl/) is built on `ParametricOperators.jl`
 
 ## Features
 - <b>Kronecker Product Operations:</b> Implement tensor operations using Kronecker products for linear operators acting along multiple dimensions.
@@ -16,200 +22,15 @@ ParametricOperators.jl is a Julia Language-based scientific library designed to
 
    ```julia
    julia> using Pkg
-   julia> Pkg.activate("path/to/your/project")
+   julia> Pkg.activate("path/to/your/environment")
    julia> Pkg.add("ParametricOperators")
    ```
 
 This will add `ParametricOperators.jl` as dependency to your project
 
-## Examples
-
-### 1. FFT of 3D Tensor
-
-```julia
-using Pkg
-Pkg.activate("./path/to/your/environment")
-
-using ParametricOperators
-
-T = Float32
-
-gt, gx, gy = 100, 100, 100
-
-# Define a transform along each dimension
-Ft = ParDFT(T, gt)
-Fx = ParDFT(Complex{T}, gx)
-Fy = ParDFT(Complex{T}, gy)
-
-# Create a Kronecker operator than chains together the transforms
-F = Fy ⊗ Fx ⊗ Ft
-
-# Apply the transform on a random input
-x = rand(T, gt, gx, gy) |> gpu
-y = F * vec(x)
-```
-
-### 2. Distributed FFT of a 3D Tensor:
-
-Make sure to add necessary dependencies. You might also need to load a proper MPI implementation based on your hardware.
-
-```julia
-julia> using Pkg
-julia> Pkg.activate("path/to/your/project")
-julia> Pkg.add("MPI")
-julia> Pkg.add("CUDA")
-```
-
-Copy the following code into a `.jl` file
-```julia
-using Pkg
-Pkg.activate("./path/to/your/environment")
-
-using ParametricOperators
-using CUDA
-using MPI
-
-MPI.Init()
-
-comm = MPI.COMM_WORLD
-rank = MPI.Comm_rank(comm)
-size = MPI.Comm_size(comm)
-
-# Julia requires you to manually assign the gpus, modify to your case.
-CUDA.device!(rank % 4)
-partition = [1, 1, size]
-
-T = Float32
-
-# Define your Global Size and Data Partition
-gt, gx, gy = 100, 100, 100
-nt, nx, ny = [gt, gx, gy] .÷ partition
-
-# Define a transform along each dimension
-Ft = ParDFT(T, gt)
-Fx = ParDFT(Complex{T}, gx)
-Fy = ParDFT(Complex{T}, gy)
-
-# Create and distribute the Kronecker operator than chains together the transforms
-F = Fy ⊗ Fx ⊗ Ft
-F = distribute(F, partition)
-
-# Apply the transform on a random input
-x = rand(T, nt, nx, ny) |> gpu
-y = F * vec(x)
-
-MPI.Finalize()
-```
-
-You can run the above by doing:
-
-`srun -n N_TASKS julia code_above.jl`
-
-### 3. Parametrized Convolution on 3D Tensor
-
-Make sure to add necessary dependencies to compute the gradient
-
-```julia
-julia> using Pkg
-julia> Pkg.activate("path/to/your/project")
-julia> Pkg.add("Zygote")
-```
-
-```julia
-using Pkg
-Pkg.activate("./path/to/your/environment")
-
-using ParametricOperators
-using Zygote
-
-T = Float32
-
-gt, gx, gy = 100, 100, 100
-
-# Define a transform along each dimension
-St = ParMatrix(T, gt, gt)
-Sx = ParMatrix(T, gx, gx)
-Sy = ParMatrix(T, gy, gy)
-
-# Create a Kronecker operator than chains together the transforms
-S = Sy ⊗ Sx ⊗ St
-
-# Parametrize our transform
-θ = init(S) |> gpu
-
-# Apply the transform on a random input
-x = rand(T, gt, gx, gy) |> gpu
-y = S(θ) * vec(x)
-
-# Compute the gradient wrt some objective of our parameters
-θ′ = gradient(θ -> sum(S(θ) * vec(x)), θ)
-```
-
-### 4. Distributed Parametrized Convolution of a 3D Tensor:
-
-Make sure to add necessary dependencies. You might also need to load a proper MPI implementation based on your hardware.
-
-```julia
-julia> using Pkg
-julia> Pkg.activate("path/to/your/project")
-julia> Pkg.add("MPI")
-julia> Pkg.add("CUDA")
-julia> Pkg.add("Zygote")
-```
-
-Copy the following code into a `.jl` file
-```julia
-using Pkg
-Pkg.activate("./path/to/your/environment")
-
-using ParametricOperators
-using CUDA
-using MPI
-
-MPI.Init()
-
-comm = MPI.COMM_WORLD
-rank = MPI.Comm_rank(comm)
-size = MPI.Comm_size(comm)
-
-# Julia requires you to manually assign the gpus, modify to your case.
-CUDA.device!(rank % 4)
-partition = [1, 1, size]
-
-T = Float32
-
-# Define your Global Size and Data Partition
-gt, gx, gy = 100, 100, 100
-nt, nx, ny = [gt, gx, gy] .÷ partition
-
-# Define a transform along each dimension
-St = ParMatrix(T, gt, gt)
-Sx = ParMatrix(T, gx, gx)
-Sy = ParMatrix(T, gy, gy)
-
-# Create and distribute the Kronecker operator than chains together the transforms
-S = Sy ⊗ Sx ⊗ St
-S = distribute(S, partition)
-
-# Parametrize our transform
-θ = init(S) |> gpu
-
-# Apply the transform on a random input
-x = rand(T, nt, nx, ny) |> gpu
-y = S(θ) * vec(x)
-
-# Compute the gradient wrt some objective of our parameters
-θ′ = gradient(θ -> sum(S(θ) * vec(x)), θ)
-
-MPI.Finalize()
-```
-
-You can run the above by doing:
-
-`srun -n N_TASKS julia code_above.jl`
-<!-- ## Citation
+## Documentation
 
-If you use our software for your research, we appreciate it if you cite us following the bibtex in [CITATION.bib](CITATION.bib). -->
+Check out the [Documentation](https://slimgroup.github.io/ParametricOperators.jl) for more or get started by running some [examples](https://github.com/turquoisedragon2926/ParametricOperators.jl-Examples)!
 
 ## Issues
 

diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+build/
+site/
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ParametricOperators = "db9e0614-c73c-4112-a40c-114e5b366d0d"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,31 @@
+using Documenter
+using ParametricOperators
+
+makedocs(
+    sitename = "ParametricOperators.jl",
+    format = Documenter.HTML(),
+    # modules = [ParametricOperators],
+    pages=[
+        "Introduction" => "index.md",
+        "Quick Start" => "quickstart.md",
+        "Distribution" => "distribution.md",
+        "Examples" => [
+            "3D FFT" => "examples/3D_FFT.md",
+            "Distributed 3D FFT" => "examples/3D_DFFT.md",
+            "3D Conv" => "examples/3D_Conv.md",
+            "Distributed 3D Conv" => "examples/3D_DConv.md",
+        ],
+        "API" => "api.md",
+        "Future Work" => "future.md",
+        "Citation" => "citation.md"
+    ]
+)
+
+# Automatically deploy documentation to gh-pages.
+deploydocs(
+    repo = "github.com/slimgroup/ParametricOperators.jl.git",
+    push_preview=true,
+    devurl = "dev",
+    devbranch = "main",
+    versions = ["dev" => "dev", "stable" => "v^"],
+)
diff --git a/docs/src/.DS_Store b/docs/src/.DS_Store
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -0,0 +1,3 @@
+### API usage for different operators
+
+Coming soon...
diff --git a/docs/src/assets/.DS_Store b/docs/src/assets/.DS_Store
diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png
diff --git a/docs/src/citation.md b/docs/src/citation.md
@@ -0,0 +1,12 @@
+### Citation
+
+If you use `ParametricOperators.jl`, please cite the following:
+```
+@presentation {rex2023ML4SEISMIClsp,
+	title = {Large-scale parametric PDE approximations with model-parallel Fourier neural operators},
+	year = {2023},
+	month = {11},
+	url = {https://slim.gatech.edu/Publications/Public/Conferences/ML4SEISMIC/2023/rex2023ML4SEISMIClsp},
+	author = {Richard Rex and Thomas J. Grady II and Rishi Khan and Ziyi Yin and Felix J. Herrmann}
+}
+```