First draft of Jupyter Book tutorial

.github/workflows/deploy.yml

@@ -0,0 +1,59 @@
+name: Jupyter Book (via myst) GitHub Pages Deploy
+on:
+  push:
+    branches: ['**']
+env:
+  BASE_URL: /${{ github.event.repository.name }}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages-${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24.x
+      - name: Install Jupyter Book (via myst)
+        run: npm install -g jupyter-book
+      - name: Build HTML Assets
+        working-directory: jupyterbook
+        run: jupyter-book build --html
+      - name: Upload Jupyter Book HTML artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: jupyter-book-html
+          path: jupyterbook/_build/html
+          if-no-files-found: error
+
+  deploy_pages:
+    name: Deploy GitHub Pages (main only)
+    runs-on: ubuntu-slim
+    needs: [build]
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Download Jupyter Book HTML
+        uses: actions/download-artifact@v7
+        with:
+          name: jupyter-book-html
+          path: public
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: public
+      - name: Deploy to Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

jupyterbook/.gitignore

@@ -0,0 +1,2 @@
+# MyST build outputs
+_build

jupyterbook/myst.yml

@@ -0,0 +1,34 @@
+# See docs at: https://mystmd.org/guide/frontmatter
+version: 1
+project:
+  numbering:
+    title: true
+    headings: true
+  id: 72d8ee77-e3e8-443f-a297-3a1131f0bb48
+  title: ALF Tutorial (draft)
+  description: A tutorial for the ALF project
+  # keywords: []
+  # authors: []
+  github: https://github.com/ALF-QMC/ALF_Tutorial
+  toc:
+    # Auto-generated by `myst init --write-toc`
+    - file: source/01-intro.md
+    - file: source/02-installation.md
+    - file: source/03-minimal_ALF_run.ipynb
+    - file: source/04-nice-physics.md
+      children:
+      - file: source/04-nice-physics/bec.ipynb
+    - file: source/05-caveats.md
+      children:
+      - file: source/05-caveats/warmup.ipynb
+      - file: source/05-caveats/autocorrelation.ipynb
+      - file: source/05-caveats/delta-tau.ipynb
+      - file: source/05-caveats/finite-size-effects.ipynb
+
+    - file: source/06-fortran.md
+
+site:
+  template: book-theme
+  options:
+  #   favicon: favicon.ico
+  #   logo: site_logo.png

jupyterbook/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "jupyterbook"
+version = "0.1.0"
+requires-python = ">=3.14"
+dependencies = [
+    "jupyter-book>=2.1.6",
+]

jupyterbook/source/01-intro.md

@@ -0,0 +1,19 @@
+# ALF Tutorial (work in progress)
+
+:::{attention} Work in progress
+This is an unfinished draft of a new version of the tutorial based on [Jupyter Book](https://jupyterbook.org).
+:::
+
+This is a tutorial for using [ALF](https://github.com/ALF-QMC/ALF/) and [pyALF](https://github.com/ALF-QMC/pyALF/) intended to get you started from zero up to your own first projects.
+
+Up until [Sec. 6](06-fortran.md), the documents revolves around [Jupyter Notebooks](https://jupyter.org/) that can be downloaded to run locally. They are interactive documents that combine code, narration and display of data in one file.
+
+
+## Outline of this document
+
+2. [](02-installation.md): Brief instructions to set up the prerequisites for this tutorial. For more details, see the documentation of [ALF](https://alf.physik.uni-wuerzburg.de/doc.pdf) and [pyALF](https://alf.physik.uni-wuerzburg.de/pyalf-doc/source/installation.html)
+3. [](03-minimal_ALF_run.ipynb): A simple example running ALF via pyALF. This is a [Jupyter Notebook](https://jupyter.org/) that can be downloaded to run locally.
+4. [](04-nice-physics.md): A few Jupyter Notebooks that display (py)ALF's capabilities by reproducing nice physics phenomena.
+5. [](05-caveats.md): A few Jupyter Notebooks that demonstrate common caveats and how to handle them.
+6. [](06-fortran.md): Here, we go beyond Jupyter Notebooks and write Fortran code to modify existing ALF Hamiltonians.
+

jupyterbook/source/02-installation.md

@@ -0,0 +1,40 @@
+# Installation
+ALF is pretty self-contained, you only need a LAPACK and a BLAS implementation as external libraries. For compiling the source code you need make and a Fortran 2003 compatible Compiler.
+
+pyALF, the Python interface for ALF, also demands only Python, Jupiter and a few basic Python packages: SciPy, NumPy and matplotlib.
+
+## Dependencies
+
+### Python
+
+If you do not yet have a Python environment with working pip, we recommend [miniforge](https://github.com/conda-forge/miniforge).
+
+The necessary Python packages can be easily installed on a variety of platforms — all that is needed is to issue the command:
+```bash
+conda install  ipython jupyterlab scipy numpy matplotlib
+```
+Miniforge is recommended due to its convenience, but the system's package management (e.g., apt-get) or Python's own package management, pip3, can be used instead if preferred.
+
+### ALF packages
+
+* **Linux**   
+  To install the relevant ALF packages.
+  - **Debian/Ubuntu/Linux Mint**:  `sudo apt-get install gfortran liblapack-dev make`
+  - **Red Hat/Fedora/CentOS**:  `sudo dnf install gcc-gfortran make liblapack-devel`
+  - **OpenSuSE/SLES**:  `sudo zypper install gcc-gfortran make lapack-devel`
+  - **Arch Linux**:  `pacman -S make gcc-fortran lapack`
+
+* **Other Unixes**   
+  gfortran and the lapack implementation from netlib.org should be available for your system. Consult the documentation of your system on how to install the relevant packages. The package names from linux should give good starting points for your search.
+
+* **MacOS**   
+  gfortran for MacOS can be found at https://gcc.gnu.org/wiki/GFortranBinaries#MacOS. Detailed information on how to install the package  can be found at: https://gcc.gnu.org/wiki/GFortranBinariesMacOS. You will need to have Xcode as well as the  Apple developer tools installed. 
+
+* **Windows**   
+  For Windows, we recommend using the Windows Subsystem for Linux, which can be installed following this guide https://learn.microsoft.com/en-us/windows/wsl/install and then proceed accoring to the instructions for Linux.
+
+## Building
+After you have obtained the source code of [ALF](https://git.physik.uni-wuerzburg.de/ALF/ALF/) and [pyALF](https://git.physik.uni-wuerzburg.de/ALF/pyALF/), and have set up the build environment, you need to build the source files. Executing `make` in the ALF's root directory does the job, and you can check the tutorial for more details.
+
+## Editors
+For the coding parts of the exercises we recommend to use a text editor. Linux usually have one installed like kwrite, kate or gedit(emacs and VI work great, too) and for the Windows users we recommend Notepad++. Jupyter notebooks of course can be edited in a browser.