installation and docker guide

.dockerignore

@@ -0,0 +1,2 @@
+.git/*
+.github/*

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
 
   pre-commit:
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 4
 
     steps:
       - name: checkout code
@@ -20,8 +20,40 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: 3.8
+          cache: 'pip'
+
+      - name: install dependencies
+        run: |
+          python -m pip install --upgrade pip
+
+          pip install fire jupytext pytest loguru
 
       - name: run pre-commit action
         uses: pre-commit/[email protected]
         with:
           extra_args: --all-files
+
+  tests:
+    needs: pre-commit
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v3
+
+      - name: set up py3.8
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.8
+          cache: 'pip'
+
+      - name: install dependencies
+        run: |
+          python -m pip install --upgrade pip
+
+          pip install fire jupytext pytest loguru
+
+      - name: run tests
+        run: |
+          python -m pytest tests/ -vv

.github/workflows/test-docker.yml

@@ -0,0 +1,36 @@
+# Test docker for dev and listner
+name: test-docker
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ master ]
+
+jobs:
+
+  deploy_book:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: checkout branch for build
+        uses: actions/checkout@v2
+      - name: set up docker
+        uses: actions/setup-docker@v1
+      - name: build dev (qml-dev) docker
+        run: |
+          docker build . --tag qml-dev:latest --target dev
+      - name: test dev (qml-dev) docker
+        run: |
+          docker run -it qml-dev:latest /bin/bash
+          exit
+      - name: build listener (qmlcourse) docker
+        run: |
+          docker build . --tag qmlcourse:latest --target listener
+          docker run -it -p 8888:8888 qmlcourse:latest
+      - name: test listener (qmlcourse) docker
+        run: |
+          docker run -it -p 8888:8888 qmlcourse:latest
+          conda activate qmlcourse
+          jupyter --version
+          exit

.github/workflows/test-installation.yml

@@ -0,0 +1,46 @@
+name: test-listener-os
+# This repo testing instructions from lecture book/install/{ru/en}/intro.md
+
+on:
+  workflow_dispatch:
+    inputs:
+      os:
+        # TODO
+        description: 'Choose OS for test'
+        required: false
+        default: '"ubuntu-latest", "macos-latest", "windows-latest"'
+
+jobs:
+
+  test-listener-all:
+    name: Listener miniconda (${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest"]
+        python-version: ["3.8", "3.9"]
+
+    steps:
+      - uses: conda-incubator/setup-miniconda@v2
+        with:
+          auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: conda create and activate env
+        shell: bash -l {0}
+        run: |
+          conda create -n qmlcourse python=3.8 --yes
+          conda activate qmlcourse
+
+      - name: install psi-4 Non-Windows
+        shell: bash -l {0}
+        run: conda run -n qmlcourse conda install psi4 python=3.8 -c psi4 --yes
+
+      - name: install all other packages
+        run: |
+          conda run -n qmlcourse python -m pip install -r requirements.txt
+          conda run -n qmlcourse conda install -c conda-forge jupyterlab --yes
+
+      - name: test jupyter
+        run: conda run -n qmlcourse jupyter --version

.gitignore

@@ -511,6 +511,11 @@ _minted*
 # Jupyter Book
 _build*
 
-# VSCode settings dir
+# VSode settings dir
 .vscode
-_tmp_notebooks
+
+# Notebooks dir
+notebooks/
+
+# some tests data
+tests/data/lecture.ipynb

Dockerfile

@@ -0,0 +1,56 @@
+####
+# Purpose of this stage is to get all packages from lectures and jupyter lab to interact with lectures.
+####
+
+FROM continuumio/miniconda3:latest as listener
+WORKDIR qmlcourse
+COPY . .
+RUN conda create -n qmlcourse python=3.8 --yes
+RUN conda run -n qmlcourse conda install psi4 python=3.8 -c psi4 --yes
+RUN conda run -n qmlcourse python -m pip install -r requirements/requirements-listener.txt
+RUN conda run -n qmlcourse conda install -c conda-forge jupyterlab --yes
+
+# Configure environment
+ENV CONDA_DIR=/opt/conda \
+    SHELL=/bin/bash
+ENV PATH="${SHELL}:${PATH}"
+ENV PATH="${CONDA_DIR}/bin:${PATH}"
+EXPOSE 8888
+ENTRYPOINT ["bash"]
+
+# Starting jupyter lab in interactive docker shell:
+# docker run -it -p 8888:8888 qmlcourse:latest
+# conda activate qmlcourse
+# jupyter lab --ip='0.0.0.0' --port=8888 --no-browser --allow-root
+
+####
+# Purpose of the builder is to make all lectures, convert them into ipython notebooks (.ipynb). This operation is time costly and take a lot of space on the drive.
+# After that we could use lightweight environment
+####
+
+ARG GIT-BRANCH=master
+FROM ubuntu:20.04 as dev
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Europe/London
+RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
+RUN apt update && apt install -y build-essential git wget tzdata
+RUN apt update && apt install -y python3-pip
+RUN python3 -m pip install poetry
+RUN apt update && apt install -y
+
+# Needed if we pull from dockerhub without local repo.
+# RUN git clone https://github.com/quantum-ods/qmlcourse.git
+
+WORKDIR qmlcourse
+COPY . .
+# RUN git checkout ${GIT-BRANCH}
+RUN poetry install --no-interaction --no-root
+RUN apt update && apt install -y texlive-latex-extra texlive-fonts-extra texlive-xetex latexmk
+RUN poetry run python tools/convert.py md_to_ipynb
+RUN poetry run jupyter-book toc migrate ./qmlcourse/_toc.yml -o ./qmlcourse/_toc.yml
+RUN poetry run jupyter-book build ./qmlcourse --keep-going
+# Get latex file
+RUN poetry run jupyter-book build ./qmlcourse --builder latex --keep-going
+# TODO: Building pdf
+# xelatex -interaction nonstopmode qmlcourse.tex
+ENTRYPOINT ["/bin/bash"]

Makefile

@@ -13,22 +13,17 @@ install-python-poetry-ubuntu:
 	sudo apt install python3-distutils -y
 	curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3
 
-#	curl "http://vergil.chemistry.gatech.edu/psicode-download/Psi4conda-1.4rc3-py38-Linux-x86_64.sh" -o Psi4conda-1.4rc3-py38.sh --keepalive-time 2
-
 install-python-poetry-macos:
 	brew update
 	brew install zlib pyenv poetry
 
 	pyenv install 3.8.10
 	pyenv local 3.8.10
 
-#	curl "http://vergil.chemistry.gatech.edu/psicode-download/Psi4conda-1.4rc3-py38-MacOSX-x86_64.sh" -o Psi4conda-1.4rc3-py38.sh --keepalive-time 2
-
 install-python-dependencies:
 #	poetry env use python3.8
 	poetry env list
 	poetry install --no-interaction --no-root
 
 build-linux-macos:
-#	cd $(HOME)/psi4conda/etc/profile.d/ && source conda.sh && conda activate && cd - && poetry run psi4 --test
 	poetry run jupyter-book build ./qmlcourse

pyproject.toml

@@ -32,6 +32,10 @@ tensorflow-quantum = "0.6.0"
 
 Jinja2 = "3.0.3"
 # [tool.poetry.dev-dependencies]
+jupytext = "^1.13.8"
+fire = "^0.4.0"
+loguru = "^0.6.0"
+pre-commit = "^2.20.0"
 
 
 [build-system]

qmlcourse/_toc.yml

@@ -226,6 +226,15 @@
     - file: book/intro/en/prerequisite.md
       title: ⬜ Prerequisite
 
+- part: Installation
+  chapters:
+    - file: book/install/en/intro.md
+      title: 🟩 Basic installation
+    - file: book/install/en/docker.md
+      title: 🟩 Working with docker
+    - file: book/install/en/advanced.md
+      title: 🟧 Optimization environment for production or GPU use
+
 - part: Linear Algebra and Numpy
   chapters:
     - file: book/linalg/en/linalg_intro.md

qmlcourse/book/install/en/advanced.md

@@ -0,0 +1,53 @@
+# Advanced install of packages
+
+**NOTE**
+
+You could also install all packages from Intel optimized repositories, but for now, we don't test this approach. This could make sense in four cases:
+
+- if you are using a very old Intel/AMD processor (that does not have AVX2 instructions, for example). Then with high probability, you'll need to compile some packages by yourself. Intel® Distribution for Python contains many compilers and tools to help you with this non-trivial task.
+- if you are using an extra modern Intel CPU with AVX-512 or new AMX instructions. Or your CPU has more than eight cores.
+- if you are using cluster and don't want to install OpenMP and other libraries manually.
+  In the mean case scenario with 8 cores CPU, you probably get about a 10% increase in the speed of calculations that, in my opinion, do not cost additional efforts and space on your SSD/HDD. Some users review that this actually works with an AMD processor, so if you have an AMD CPU you could message @avpronkin in ODS.ai Slack about a successful installation or ask for help.
+
+### Intel® Distribution for Python
+
+First of all, update your conda:
+
+```shell
+conda update conda
+```
+
+Secondly, add the Intel channel for packages:
+
+```shell
+conda config --add channels intel
+```
+
+Finally, create intel based python environment and activate it:
+
+```shell
+conda create -n qmlcourse intelpython3_core python=3.8 --yes
+conda activate qmlcourse
+```
+
+After you could activate your environment and continue to install all other packages, conda automatically search all repositories with the preference of the intel repo.
+
+If you stack with problems, you could remove the Intel channel
+
+```shell
+conda config --remove channels intel
+```
+
+And remove `qmlcourse` environment:
+**WARNING**
+_This cannot be undone, so you remove all packages that you install in `qmlcourse` environment_
+
+```shell
+conda deactivate
+conda env remove -n qmlcourse
+```
+
+## GPU
+
+Before installation the main packages, you could install the GPU version of TensorFlow/JAX.
+See instructions here [_tensorflow-gpu_](https://www.tensorflow.org/install/gpu), [_JAX GPU_](https://github.com/google/jax#pip-installation-gpu-cuda).