include landing page to docs

Guest400123064 · Oct 11, 2024 · 6263c37 · 6263c37
1 parent 60915b2
commit 6263c37
Show file tree

Hide file tree

Showing 21 changed files with 98 additions and 21 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -33,8 +33,7 @@ jobs:
             pdoc src/ezgatr \
                 -o docs \
                 -t docs/theme \
-                --docformat numpy \
-                --logo "https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png"
+                --docformat numpy
 
       - uses: actions/upload-pages-artifact@v3
         with:

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 <html>
     <h1 align="center">
-      <img src="./docs/images/ezgatr_logo.png" width="256"/>
+      <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" width="256"/>
     </h1>
     <h3 align="center">
       Geometric Algebra Transformer Made Easy

diff --git a/docs/ezgatr.html b/docs/ezgatr.html
@@ -17,11 +17,19 @@
         <label id="navtoggle" for="togglestate" class="pdoc-button"><svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'><path stroke-linecap='round' stroke="currentColor" stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/></svg></label>
         <input id="togglestate" type="checkbox" aria-hidden="true" tabindex="-1">
         <div>
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>
 
+            <h2>Contents</h2>
+            <ul>
+  <li><a href="#what-is-ezgatr">What is EzGATr?</a></li>
+  <li><a href="#installation">Installation</a></li>
+  <li><a href="#usage">Usage</a></li>
+  <li><a href="#api-references">API References</a></li>
+  <li><a href="#license">License</a></li>
+</ul>
+
 
             <h2>Submodules</h2>
             <ul>
@@ -45,8 +53,91 @@ <h2>Submodules</h2>
                     <h1 class="modulename">
 ezgatr    </h1>
 
+                        <div class="docstring"><html>
+    <h1 align="center">
+      <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" width="256"/>
+    </h1>
+    <h3 align="center">
+      Geometric Algebra Transformer Made Easy
+    </h3>
+</html>
+
+<p><a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+<a href="https://www.python.org/downloads/release/python-3100/"><img src="https://img.shields.io/badge/python-%203.10%20|%203.11%20|%203.12-blue.svg" alt="Python 3.10" /></a>
+<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" />
+<a href="https://guest400123064.github.io/ezgatr/ezgatr.html"><img src="https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fguest400123064.github.io/ezgatr" alt="Website" /></a></p>
+
+<h2 id="what-is-ezgatr">What is EzGATr?</h2>
+
+<p><strong>EzGATr</strong> (Easy Geometric Algebra Transformer) intends to be a simple-to-use and lightweight Python library for building 3D <a href="https://arxiv.org/abs/2305.18415">Geometric Algebra Transformers (GATr)</a>. It is a collection of operators, modules, utilities, etc. build on top of <a href="https://pytorch.org/">PyTorch</a>. In addition, EzGATr also seeks to bridge the gap between the mathematical formulations and corresponding implementations through extensive documentation and explanations to facilitate learning and potential future optimizations.</p>
+
+<h2 id="installation">Installation</h2>
+
+<p>EzGATr is currently in development and not yet available on PyPI. To install it, you can clone the repository and install it using <code>pip</code>. Use the <code>-e</code> flag to install it in editable mode for quick changes.</p>
+
+<div class="pdoc-code codehilite">
+<pre><span></span><code>$<span class="w"> </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/Guest400123064/ezgatr.git
+$<span class="w"> </span><span class="nb">cd</span><span class="w"> </span>ezgatr
+$<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.
+</code></pre>
+</div>
+
+<h2 id="usage">Usage</h2>
+
+<p>The quick start example shown below demonstrates how to use EzGATr to build a equivariant network with one input/output channel (e.g., a point cloud) and four hidden channels. The mock input data contains a batch of eight samples, each with 256 3D objects embedded as multi-vectors.</p>
+
+<div class="pdoc-code codehilite">
+<pre><span></span><code><span class="kn">import</span> <span class="nn">torch</span>
+<span class="kn">import</span> <span class="nn">torch.nn</span> <span class="k">as</span> <span class="nn">nn</span>
+
+<span class="kn">from</span> <span class="nn"><a href="ezgatr/nn.html">ezgatr.nn</a></span> <span class="kn">import</span> <span class="n">EquiLinear</span>
+<span class="kn">from</span> <span class="nn"><a href="ezgatr/nn/functional.html">ezgatr.nn.functional</a></span> <span class="kn">import</span> <span class="n">scaler_gated_gelu</span>
+
+
+<span class="k">class</span> <span class="nc">SimpleNet</span><span class="p">(</span><span class="n">nn</span><span class="o">.</span><span class="n">Module</span><span class="p">):</span>
+    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="nb">super</span><span class="p">(</span><span class="n">SimpleNet</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__init__</span><span class="p">()</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">fc1</span> <span class="o">=</span> <span class="n">EquiLinear</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>
+        <span class="bp">self</span><span class="o">.</span><span class="n">fc2</span> <span class="o">=</span> <span class="n">EquiLinear</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
+
+    <span class="k">def</span> <span class="nf">forward</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">):</span>
+        <span class="n">x</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">fc1</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
+        <span class="n">x</span> <span class="o">=</span> <span class="n">scaler_gated_gelu</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
+        <span class="n">x</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">fc2</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
+        <span class="k">return</span> <span class="n">x</span>
+
+
+<span class="n">net</span> <span class="o">=</span> <span class="n">SimpleNet</span><span class="p">()</span>
+<span class="n">in_</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">8</span><span class="p">,</span> <span class="mi">256</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">16</span><span class="p">)</span>
+<span class="n">out</span> <span class="o">=</span> <span class="n">net</span><span class="p">(</span><span class="n">in_</span><span class="p">)</span>
+</code></pre>
+</div>
+
+<p>One can refer to <a href="src/ezgatr/nets/mv_only_gatr.py">this example</a> for how to build a full-fledged GATr model with EzGATr, involving equivariant geometric attention and geometric MLP.</p>
+
+<h2 id="api-references">API References</h2>
+
+<p>The complete API references for EzGATr can be found <a href="https://guest400123064.github.io/ezgatr/ezgatr.html">here</a>. TL;DR, the package is organized as follows:</p>
+
+<ul>
+<li><code><a href="ezgatr/nn.html">ezgatr.nn</a></code>: Contains the core modules and layers for building GATr models. It is organized similarly to PyTorch's <code>torch.nn</code> package, where the functional submodule contains lower-level operators and transformations.</li>
+<li><code><a href="ezgatr/interfaces.html">ezgatr.interfaces</a></code>: Contains the utility functions that help encode and decode 3D objects to and from multi-vectors.</li>
+<li><code><a href="ezgatr/nets.html">ezgatr.nets</a></code>: Contains off-of-the-shelf networks built with EzGATr building blocks. It can also be used as references for building custom networks with EzGATr.</li>
+</ul>
+
+<h2 id="license">License</h2>
+
+<p>EzGATr is distributed under the terms of the <a href="https://opensource.org/licenses/MIT">MIT</a> license.</p>
+</div>
+
+                        <input id="mod-ezgatr-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
 
+                        <label class="view-source-button" for="mod-ezgatr-view-source"><span>View Source</span></label>
 
+                        <div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos">1</span></a><span class="sa">r</span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-2"><a href="#L-2"><span class="linenos">2</span></a><span class="sd">.. include:: ../../README.md</span>
+</span><span id="L-3"><a href="#L-3"><span class="linenos">3</span></a><span class="sd">&quot;&quot;&quot;</span>
+</span></pre></div>
 
 
             </section>

diff --git a/docs/ezgatr/interfaces.html b/docs/ezgatr/interfaces.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/plane.html b/docs/ezgatr/interfaces/plane.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/point.html b/docs/ezgatr/interfaces/point.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/pseudoscalar.html b/docs/ezgatr/interfaces/pseudoscalar.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/reflection.html b/docs/ezgatr/interfaces/reflection.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/rotation.html b/docs/ezgatr/interfaces/rotation.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/scalar.html b/docs/ezgatr/interfaces/scalar.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/interfaces/translation.html b/docs/ezgatr/interfaces/translation.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.interfaces</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/nets.html b/docs/ezgatr/nets.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/nets/mv_only_gatr.html b/docs/ezgatr/nets/mv_only_gatr.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.nets</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/nn.html b/docs/ezgatr/nn.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/nn/functional.html b/docs/ezgatr/nn/functional.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.nn</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/nn/modules.html b/docs/ezgatr/nn/modules.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.nn</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/utils.html b/docs/ezgatr/utils.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/utils/debug.html b/docs/ezgatr/utils/debug.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.utils</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/ezgatr/utils/logger.html b/docs/ezgatr/utils/logger.html
@@ -22,7 +22,6 @@
   <path fill-rule="evenodd" d="M4.146 8.354a.5.5 0 0 1 0-.708l3-3a.5.5 0 1 1 .708.708L5.707 7.5H14.5a.5.5 0 0 1 0 1H5.707l2.147 2.146a.5.5 0 0 1-.708.708l-3-3z"/>
 </svg>                &nbsp;ezgatr.utils</a>
 
-            <img src="https://raw.githubusercontent.com/Guest400123064/ezgatr/refs/heads/main/docs/images/ezgatr_logo.png" class="logo" alt="project logo"/>
 
             <input type="search" placeholder="Search..." role="searchbox" aria-label="search"
                    pattern=".+" required>

diff --git a/docs/search.js b/docs/search.js
diff --git a/src/ezgatr/__init__.py b/src/ezgatr/__init__.py
@@ -0,0 +1,3 @@
+r"""
+.. include:: ../../README.md
+"""