diff --git a/README.md b/README.md
index 219b9f9..3215a9c 100644
--- a/README.md
+++ b/README.md
@@ -13,9 +13,7 @@ Hyperelastic Surrogates
## Installation
-```bash
-pip install hyper-surrogate
-```
+- Read the [installation guide](https://jpsferreira.github.io/hyper-surrogate/installation.html) for more information.
## Usage
diff --git a/docs/custom.js b/docs/custom.js
new file mode 100644
index 0000000..5900142
--- /dev/null
+++ b/docs/custom.js
@@ -0,0 +1,10 @@
+document.addEventListener("DOMContentLoaded", function () {
+ renderMathInElement(document.body, {
+ delimiters: [
+ { left: "$$", right: "$$", display: true },
+ { left: "$", right: "$", display: false },
+ { left: "\\[", right: "\\]", display: true },
+ { left: "\\(", right: "\\)", display: false },
+ ],
+ });
+});
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..ee19d20
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,54 @@
+# Installation
+
+## From source
+
+- Clone the repository
+
+```zsh
+git clone https://github.com/jpsferreira/hyper-surrogate.git
+cd hyper-surrogate
+```
+
+- Install dependencies
+
+```zsh
+poetry install
+```
+
+or
+
+```zsh
+uv install
+```
+
+- Load python environment
+
+```zsh
+poetry shell
+```
+
+or
+
+```zsh
+source .venv/bin/activate
+```
+
+- Run tests
+
+```zsh
+pytest
+```
+
+## From PyPI
+
+```zsh
+pip install hyper-surrogate
+```
+
+```zsh
+poetry add hyper-surrogate
+```
+
+```zsh
+uv add hyper-surrogate
+```
diff --git a/docs/tutorial1.ipynb b/docs/tutorial1.ipynb
new file mode 100644
index 0000000..b428916
--- /dev/null
+++ b/docs/tutorial1.ipynb
@@ -0,0 +1,338 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "**Import required libraries**"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import matplotlib.pyplot as plt\n",
+ "import numpy as np\n",
+ "import pandas as pd\n",
+ "import seaborn as sns\n",
+ "\n",
+ "from hyper_surrogate.deformation_gradient import DeformationGradientGenerator\n",
+ "from hyper_surrogate.kinematics import Kinematics as K"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def create_dataframe(f):\n",
+ " # initialize the kinematics calculator\n",
+ " kk = K()\n",
+ " pstr = kk.principal_stretches(f)\n",
+ " return pd.DataFrame({\n",
+ " \"I1\": kk.invariant1(f),\n",
+ " \"I2\": kk.invariant2(f),\n",
+ " \"I3\": kk.invariant3(f),\n",
+ " \"Max Principal Stretch\": np.max(pstr, axis=1),\n",
+ " \"Min Principal Stretch\": np.min(pstr, axis=1),\n",
+ " })\n",
+ "\n",
+ "\n",
+ "def plot_invariants_distribution(df):\n",
+ " plt.figure(figsize=(10, 5))\n",
+ " plt.subplot(1, 2, 1)\n",
+ " # with probs instead of counts. kernel density estimation. bars without outline\n",
+ " sns.histplot(df[\"I1\"], kde=True, stat=\"probability\", color=\"blue\", alpha=0.5, legend=True)\n",
+ " # overlap I2 plot\n",
+ " sns.histplot(df[\"I2\"], kde=True, stat=\"probability\", color=\"red\", alpha=0.5, legend=True)\n",
+ " # add legend\n",
+ " plt.legend([\"I1\", \"I2\"])\n",
+ " plt.xlabel(\"value\")\n",
+ " plt.subplot(1, 2, 2)\n",
+ " # I1-I2 plot\n",
+ " sns.scatterplot(x=\"I1\", y=\"I2\", data=df, alpha=0.5, color=\"black\")\n",
+ " # label axes only subplot 2\n",
+ " plt.xlabel(\"I1\")\n",
+ " plt.ylabel(\"I2\")\n",
+ " plt.tight_layout()\n",
+ " plt.show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "**Define the number of test cases**"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "SIZE = 1000"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "**Generate N random Deformation Gradients**"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "(1000, 3, 3)"
+ ]
+ },
+ "execution_count": 10,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "f = DeformationGradientGenerator(seed=42, size=SIZE).generate()\n",
+ "f.shape"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "With the deformation gradients generated, we can calculate a few kinematic quantities that may useful as simulation data for a machine learning model. \n",
+ "\n",
+ "Current `DeformationGradientGenerator` can directly calculate the following quantities:\n",
+ "\n",
+ "- Invariants of the deformation gradient tensor: $I_1 = \\text{tr}(\\mathbf{F}), I_2 = \\frac{1}{2}(\\text{tr}(\\mathbf{F})^2 - \\text{tr}(\\mathbf{F}^2)), I_3 = \\text{det}(\\mathbf{F})$\n",
+ "\n",
+ "- Left Cauchy-Green tensor: $\\mathbf{B} = \\mathbf{F}^T\\mathbf{F}$\n",
+ "\n",
+ "- Right Cauchy-Green tensor: $\\mathbf{C} = \\mathbf{F}\\mathbf{F}^T$\n",
+ "\n",
+ "- Principal stretches (Sqrt of Eigenvalues of $\\mathbf{C}$): $\\lambda_1, \\lambda_2, \\lambda_3$\n",
+ "\n",
+ "- Principal directions: $\\mathbf{n}_1, \\mathbf{n}_2, \\mathbf{n}_3$\n",
+ "\n",
+ "- Right Stretch tensor: $\\mathbf{U} = \\mathbf{F}\\mathbf{F}^T$\n",
+ "\n",
+ "- Left Stretch tensor: $\\mathbf{V} = \\mathbf{F}^T\\mathbf{F}$\n",
+ "\n",
+ "- Rotation tensor: $\\mathbf{R} = \\mathbf{F}\\mathbf{U}^{-1}$"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " I1 | \n",
+ " I2 | \n",
+ " I3 | \n",
+ " Max Principal Stretch | \n",
+ " Min Principal Stretch | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " 3.555173 | \n",
+ " 3.702095 | \n",
+ " 1.0 | \n",
+ " 2.068815 | \n",
+ " 0.417534 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " 7.886864 | \n",
+ " 6.119132 | \n",
+ " 1.0 | \n",
+ " 7.092200 | \n",
+ " 0.229114 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " 7.291135 | \n",
+ " 6.003618 | \n",
+ " 1.0 | \n",
+ " 7.910614 | \n",
+ " 0.183201 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " 4.053322 | \n",
+ " 4.221559 | \n",
+ " 1.0 | \n",
+ " 2.845594 | \n",
+ " 0.305125 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " 3.532698 | \n",
+ " 3.637500 | \n",
+ " 1.0 | \n",
+ " 1.912890 | \n",
+ " 0.367945 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "