Tutorial harmonic oscillator configuration space

.github/workflows/docs-publish.yaml

@@ -30,7 +30,7 @@ jobs:
         with:
           poetry-version: 1.3.2
       - name: Install Packages
-        run: poetry install --with docs
+        run: poetry install --with docs,tutorial
       - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
       - name: Deploy
         run: poetry run mkdocs gh-deploy --force

.github/workflows/publish.yaml

@@ -24,7 +24,7 @@ jobs:
         with:
           poetry-version: 1.3.2
       - name: Install Packages
-        run: poetry install --with docs,test
+        run: poetry install --with docs,test,tutorial
       - name: Build coverage file
         run: |
           pytest --cache-clear --cov=hamiltonian_flow tests/ > pytest-coverage.txt

.github/workflows/tests.yaml

@@ -34,7 +34,7 @@ jobs:
         with:
           poetry-version: 1.3.2
       - name: Install Packages
-        run: poetry install --with docs
+        run: poetry install --with docs,tutorial
       - name: Build coverage file
         run: |
           poetry run pytest --cache-clear --cov=hamiltonian_flow tests/ > pytest-coverage.txt

.gitignore

@@ -160,3 +160,4 @@ cython_debug/
 #.idea/
 
 .vscode
+*.ipynb

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 exclude: "^notebooks/|^notes/"
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.2.0
+    rev: v4.5.0
     hooks:
       - id: check-added-large-files
       - id: debug-statements
@@ -10,19 +10,19 @@ repos:
       - id: requirements-txt-fixer
       - id: trailing-whitespace
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.960
+    rev: v1.8.0
     hooks:
       - id: mypy
         args: [--no-strict-optional, --ignore-missing-imports]
         files: ^(hamiltonian_flow/|tests/)
   - repo: https://github.com/ambv/black
-    rev: 22.10.0
+    rev: 24.2.0
     hooks:
     - id: black
       language: python
   - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
         name: isort (python)
-        args: ["--multi-line", "3", "--profile", "black"]
+        args: ["--multi-line", "3", "--profile", "black", "--treat-comment-as-code", "# %%", "--float-to-top"]

docs/tutorials/harmonic_oscillator.py

@@ -0,0 +1,91 @@
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:percent
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.16.1
+#   kernelspec:
+#     display_name: .venv
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Harmonic Oscillators
+#
+# In this tutorial, we demo how to generate data of harmonic oscillators.
+
+# %%
+import pandas as pd
+import plotly.express as px
+
+from hamiltonian_flow.models.harmonic_oscillator import HarmonicOscillator
+
+# %%
+n_periods = 3
+n_samples_per_period = 200
+
+# %% [markdown]
+# ## Simple Harmonic Oscillator
+
+# %%
+sho_omega = 0.5
+
+sho = HarmonicOscillator(system={"omega": sho_omega})
+
+# %%
+df_sho = sho(n_periods=n_periods, n_samples_per_period=n_samples_per_period)
+df_sho.head()
+
+# %%
+px.line(
+    df_sho,
+    x="t",
+    y="x",
+    title=rf"Simple Harmonic Oscillator (omega = {sho_omega})",
+    labels={
+        "x": r"Displacement $x(t)$",
+        "t": r"$t$",
+    },
+)
+
+# %% [markdown]
+# ## Damped Harmonic Oscillator
+
+# %%
+dho_systems = {
+    "Underdamped": {"omega": 0.5, "zeta": 0.2},
+    "Critical Damped": {"omega": 0.5, "zeta": 1},
+    "Overdamped": {
+        "omega": 0.5,
+        "zeta": 1.2,
+    },
+}
+
+dfs_dho = []
+
+for s_name, s in dho_systems.items():
+
+    dfs_dho.append(
+        HarmonicOscillator(system=s)(
+            n_periods=n_periods, n_samples_per_period=n_samples_per_period
+        ).assign(system=rf"{s_name} (omega = {s.get('omega')}, zeta = {s.get('zeta')})")
+    )
+
+fig = px.line(
+    pd.concat(dfs_dho),
+    x="t",
+    y="x",
+    color="system",
+    title=rf"Damped Harmonic Oscillator",
+    labels={
+        "x": r"Displacement $x(t)$",
+        "t": r"$t$",
+    },
+)
+fig.update_layout(legend={"yanchor": "top", "y": -0.2, "xanchor": "left", "x": 0})
+
+# %%

docs/tutorials/index.md

@@ -1 +1,3 @@
 # Tutorials
+
+We provide some tutorials to help you get started.

mkdocs.yml

@@ -69,6 +69,10 @@ plugins:
       watch:
         - docs
         - hamiltonian_flow
+  - mkdocs-jupyter:
+      execute: True
+      allow_errors: false
+      include_requirejs: true
 
 extra_javascript:
   - javascripts/mathjax.js
@@ -79,6 +83,7 @@ nav:
   - "Home": index.md
   - "Tutorials":
     - "Introduction": tutorials/index.md
+    - "Harmonic Oscillator": tutorials/harmonic_oscillator.py
   - References:
     - "Introduction": references/index.md
     - "Models":