Oqtant Quickstart Guide
This Quickstart Guide assumes the user has some familiarity with Python
To get started with Oqtant you will need to have the following installed:
- Python >=3.10 and <3.12
User Account
To use Oqtant, you will need an account. Register and start for free!
Installation
Oqtant is compatible with Windows, Mac and Linux. Below are the steps needed to get Oqtant installed with instructions for each operating system
Python + Pip
If you do not already have a compatible version of python and pip installed on your system follow the instructions below:
Note: Depending on how python is installed on your system you may need to adjust which version of python to use in the following steps (ex: python3 or python3.11). This also applies to pip (ex: pip or pip3)
Terminal
In order to complete the installation of and use Oqtant you will need to open a terminal of your choice based on your operating system. The following have been confirmed to work with Oqtant:
- Windows Command Prompt
- Windows PowerShell
- Windows Terminal
- Linux Bash/Zsh Shell
- Mac Terminal
Windows
- Download the latest stable version of python here: https://www.python.org/downloads/windows/
- Open the executable to start the installation wizard
- Before proceeding with the wizard make sure to select the "Add Python to PATH" option
- Once finished, open your preferred terminal and verify python is installed using
python --version
- Ensure that pip is installed alongside python by running
py -m ensurepip --upgrade
- Run
pip --version
to confirm installation
Mac
- Download the latest stable version of python here: https://www.python.org/downloads/macos/
- Open the executable to start the installation wizard
- Once finished, open your preferred terminal and verify python is installed using
python --version
- If after running
python --version
you encounter an error similar to:xcode-select: note: no developer tools were found at '/Applications/Xcode.app', requesting install. Choose an option in the dialog to download the command line developer tools
, you will need to select the install option in the pop-up window that appears. Once the installation is complete you should now be able to runpython --version
- Ensure that pip is installed alongside python by running
python -m ensurepip --upgrade
- Run
pip --version
to confirm installation
Linux
Many distributions of linux already come with a version of python installed. To check run python --version
and verify if it is installed and within >=3.10 and <3.12. If python is not installed or you need to install a newer version you can run the following:
- Download the latest stable version of python here: https://www.python.org/downloads/source/
- Extract the tarball using
tar -xf
- Navigate to the now extracted file and execute
./configure
- If your system does not have an existing version of python installed run
sudo make install
, otherwise runsudo make altinstall
- Once finished, open your preferred terminal and verify python is installed using
python --version
- Ensure that pip is installed alongside python by running
python -m ensurepip --upgrade
- Run
pip --version
to confirm installation
Oqtant
As dependencies of the Oqtant package the following are downloaded automatically and do not need to be installed separately:
- Jupyter Notebook
- Matplotlib
- Numpy
- Scipy
- Scikit-learn
Below are the steps for installing Oqtant by operating system:
If you are using Anaconda/Miniconda you can follow these steps
Windows
Note: You can use either Command Prompt or PowerShell with Oqtant. The steps for each only differ slightly
- Create a python virtual environment to install Oqtant into:
python -m venv .venv
Note: You can name your virtual environment whatever makes sense to you. In the above example we use .venv
- Activate your virtual environment (from the directory where you created the .venv):
Command Prompt
.venv\Scripts\activate.bat
PowerShell
If this is your first time using PowerShell you will need to run the following command and answer the prompt with A
:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
Going forward you will not need to repeat the above command. Now you can activate your virtual environment with the following command (from the directory where you created the .venv):
.venv\Scripts\Activate.ps1
- Inside of the activated virtual environment run the following command to install Oqtant and it's dependencies:
pip install oqtant
Linux/Mac
- Create a python virtual environment to install Oqtant into:
python -m venv .venv
Note: You can name your virtual environment whatever makes sense to you. In the above example we use .venv
- Activate your virtual environment (from the directory where you created the .venv):
source .venv/bin/activate
- Once activated run the following command to install Oqtant and it's dependencies:
pip install oqtant
Using Conda
If you are using Anaconda/Miniconda to manage python environments you can follow the steps below:
- Create a conda environment to install Oqtant into:
conda create --name oqtant PYTHON=3.10
- Activate your virtual environment:
conda activate oqtant
- Once activated run the following command to install Oqtant and it's dependencies:
pip install oqtant
If your conda environment is missing pip you can install it and run the above again:
conda install pip
Oqtant Jupyter Notebooks
Getting started with Oqtant is easy using the walkthrough and demo notebooks. These notebooks will walk you through the basic functions of using Oqtant to interact with the Oqtant hardware. Feel free to use these as a starting point for your own code: edit, rename, share… they are yours.
Downloading Oqtant Jupyter Notebooks
All our example notebooks are publicly available for download on our GitLab repository.
We recommend that you download the notebooks to the same directory as that which includes your virtual environment.
Running Oqtant Jupyter Notebooks
With your virtual environment active, run the following command to start up Jupyter:
python -m oqtant.start_notebook
- This will open a tab in your default web browser with a file explorer type interface.
- Using this interface navigate to the location of the provided notebooks and select one to open.
- This will open another tab with the contents of the selected notebook.
- Each notebook has pre-populated examples you can then execute with instructions for each step
- For a more detailed explanation of the Oqtant REST API refer to our API Docs
If you run into ModuleNotFound
errors when running cells within the notebooks it can be a sign that the notebooks are not using the correct version of python. To fix this close the notebook server, run the following, then restart the notebooks:
python -m ipykernel install --user