diff --git a/docs/how-to/apptainer.md b/docs/how-to/apptainer.md new file mode 100644 index 00000000..12ce814f --- /dev/null +++ b/docs/how-to/apptainer.md @@ -0,0 +1,58 @@ +Running Virtual Accelerator +============================= + +Virtual accelerators are available as [Apptainer](https://apptainer.org/) containers. +Instructions for how to install and run Apptainer on different OS are available here. +The instructions for how to run a specific virtual accelerator are available in the [examples folder](https://github.com/python-accelerator-middle-layer/pyaml/tree/main/examples). + +## Linux + +Installation instructions are available at [https://apptainer.org/docs/admin/main/installation.html#installation-on-linux](https://apptainer.org/docs/admin/main/installation.html#installation-on-linux). + +Try to first install using the [pre-build packages](https://apptainer.org/docs/admin/main/installation.html#install-from-pre-built-packages) for your Linux distribution. + +If that doesn't work (for example if it requires root permissions which you don't have), do an [unprivileged installation](https://apptainer.org/docs/admin/main/installation.html#install-from-pre-built-packages) instead. + +You should then be able to run Apptainer in a terminal. + +## Windows + +For Windows you need to install and run in [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/). Follow the instructions at [https://apptainer.org/docs/admin/main/installation.html#windows](https://apptainer.org/docs/admin/main/installation.html#windows). + +You can then start the Ubuntu app which opens a Linux terminal where you can run Apptainer. + +## Mac + +For Mac you need to use Lima. Instructions are available at [https://apptainer.org/docs/admin/main/installation.html#mac](https://apptainer.org/docs/admin/main/installation.html#mac) but more detailed instructions are below since some additonal steps are required. + +For ARM-based MacOS server: + +``` +brew install qemu lima + +limactl start –rosetta –vm-type=vz –network=vzNAT template://apptainer +``` + +For Intel-based MacOS server: + +``` +brew install lima + +limactl start –vm-type=vz –network=vzNAT template://apptainer +``` + +To run the container you need to first do: + +``` +limactl shell apptainer +``` + +before you can run Apptainer. + +To stop the container you need to do: + +``` +limactl stop apptainer + +limactl delete apptainer +``` diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index f5bfdbef..a9252c9b 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -20,4 +20,4 @@ Advanced .. toctree:: :maxdepth: 1 - Run tests using virtual accelerator <../notebooks/run_bessy_virtual_accelerator> + apptainer diff --git a/docs/notebooks/run_bessy_virtual_accelerator.ipynb b/docs/notebooks/run_bessy_virtual_accelerator.ipynb deleted file mode 100644 index 171ace55..00000000 --- a/docs/notebooks/run_bessy_virtual_accelerator.ipynb +++ /dev/null @@ -1,104 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "cdbd7321", - "metadata": {}, - "source": [ - "# Instruction to run example scripts using the BESSYII virtual accelerator" - ] - }, - { - "cell_type": "markdown", - "id": "712267c5", - "metadata": {}, - "source": [ - "instruction to install apptainer (and run the bessy virutal accelerator)\n", - "\n", - "if ARM-based macos (M1, M2, M3....)\n", - "server:\n", - "1) brew install qemu lima\n", - "2) limactl start --rosetta --vm-type=vz --network=vzNAT template://apptainer\n", - "3) press enter\n", - "\n", - "if Intel-based macos\n", - "server:\n", - "1) brew install lima\n", - "2) limactl start --vm-type=vz --network=vzNAT template://apptainer\n", - "3) press enter\n", - "\n", - "To start container:\n", - "1) limactl shell apptainer \n", - "2) apptainer run oras://registry.hzdr.de/digital-twins-for-accelerators/containers/pyat-softioc-digital-twin:v0-1-2-bessy.2475331\n", - "\n", - "\n", - "Stopping container:\n", - "1) limactl stop apptainer\n", - "2) limactl delete apptainer\n" - ] - }, - { - "cell_type": "markdown", - "id": "157e78da", - "metadata": {}, - "source": [ - "to get address we need pvlist. On another terminal:\n", - "1) limactl shell apptainer # to go in VM\n", - "2) apptainer run oras://registry.hzdr.de/digital-twins-for-accelerators/epics-tools:v0-1-0.2028728`\n", - "3) pvlist\n", - "4) pvlist 192.168.5.15:5075 (replace the address with the one printed by the command above after tcp@)" - ] - }, - { - "cell_type": "markdown", - "id": "78eca7cd", - "metadata": {}, - "source": [ - "create an environment\n", - "\n", - "python -m venv bessy2_pyaml\n", - "source bessy2_pyaml/bin/activate\n", - "\n", - "clone repositories from main (not latest release)\n", - "\n", - "git clone https://github.com/python-accelerator-middle-layer/pyaml.git\n", - "git clone https://github.com/python-accelerator-middle-layer/pyaml-cs-oa.git\n", - "\n", - "install locally (need to modify the pyaml configuration)\n", - "\n", - "cd pyaml\n", - "pip install -e . \n", - "\n", - "cd pyaml-cs-oa\n", - "pip install -e . \n", - "\n", - "pip install aioca\n", - "\n", - "change the pyaml configuration file ./pyaml/examples/BESSY2_example/BESSY2Orbit.yaml at line 11 with the correct prefix (replace pons: by your prefix)\n", - "change the pyaml configuration file ./pyaml/examples/BESSY2_example/BESSY2Tune.yaml at line 11 with the correct prefix (replace pons: by your prefix)\n", - "change the pyaml configuration file ./pyaml/examples/BESSY2_example/BESSY2Chroma.yaml at line 11 with the correct prefix (replace pons: by your prefix)\n" - ] - }, - { - "cell_type": "markdown", - "id": "c4af7f1f", - "metadata": {}, - "source": [ - "navigate to the folder ./pyaml/examples/BESSY2_example/\n", - "\n", - "run the file bessy2-orbit.py\n", - "(this will take sometime to compute the ORM)\n", - "\n", - "run the file bessy2-tune.py\n", - "run the file bessy2-chroma.py" - ] - } - ], - "metadata": { - "language_info": { - "name": "python" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/examples/BESSY2_example/README.md b/examples/BESSY2_example/README.md index 74996e8e..6f42e200 100644 --- a/examples/BESSY2_example/README.md +++ b/examples/BESSY2_example/README.md @@ -12,7 +12,8 @@ ## Start the BESSY II virtual accelerator -1. Install [Apptainer](https://apptainer.org/docs/admin/main/installation.html) in case you don't already have it. +1. Install [Apptainer](https://apptainer.org/docs/admin/main/installation.html) by following the instructions in the [documentation](https://pyaml.readthedocs.io/en/latest/how-to/apptainer.html). + 2. Open a terminal and start the container.