First Steps
What we Do
SimOS is a library for the simulation of open quantum systems consisting of spins, electronic levels and combinations thereoff. It can simulate the spin dynamics of conventional magnetic or electron paramagnetic resonance, but is further capable to simulate optically adressable spins or purely optical systems. ODMR combines electron spin resonance with optical measurements and is a highly sensitive technique to study systems possessing spin-dependent fluorescence. In our examples section, we feature two prototypical examples of optically adressable spins - the nitrogen vacancy center in diamond and photogenerated spin-correlated radical pairs.
Modelling the dynamics of open quantum system can be a non-trivial task. Their incoherent interaction with the system environment interferes with their coherent time evolution and an accurate simulation of their dynamics requires a quantum master equation. SimOS provides an interface for the construction of operators and super-operators of arbitrarily complex systems of spins and electronic levels and facilitates simulations of their dynamics on various levels of theory. Pythons popular numpy, scipy, qutip and sympy libraries are readily integrated and can be chosen as backends. We try to minimize high-level functions and keep the style of the simulations as close to a pen-and paper style as possible.
Our main focus lies on the QME in Lindblad form, for which we provide various engines for computationally efficient time propagation. In addition spatial dynamics such as rotational diffusion, linear flow or magic angle spinning can be simulated with our Fokker-Planck framework.
Installation Guide
The SimOS library is available at PyPI, the Python Package Index. It can be installed via pip, the Python package installer. As the backend structure is modular, packages for the backends have to be installed separately. To install the recommended set of dependencies, run the following command:
pip install simos[recommended]
To install the full set of dependencies, run the following command:
pip install simos[full]
This will install the recommended set of dependencies, the parament GPU integrator and the numba JIT compiler. Note that the NUMBA support is still experimental and might not work on all systems.
To install the minimal set of dependencies, run the following command:
pip install simos
Note, that if you install the minimal set of dependencies, executing the functions with the default backend method “qutip” will raise an error and you have to specify the backend method explicitly.
To install in developer mode (e.g. after cloning the Github repository manually), please refer to the developer guide. You will need this type of installation if you want to contribute to the development of SimOS or modify its components.
Note on versions
SimOS is developed for Python 3.9 and higher. Numpy must be installed in version 1.25 or higher. Scipy must be installed in version 1.12 or higher. To use the qutip backend, qutip should be installed in version 5.0 or higher. To use the sympy backend, sympy should be installed in version 1.11 or higher. To use the numba backend, numba should be installed in version 0.58.0 or higher.
Installation in an offline network
If you need to install SimOS in an offline (airgapped) network, you can download the required packages from PyPI and install them manually. To do this, you can use the pip download command:
pip download simos[recommended]
This will download all the required packages and their dependencies to your current directory. The downloaded files will be in the form of .whl (wheel) files, which are the standard format for Python packages. Note that you will need to have pip installed in the offline network (see here). Please ensure that the Python environment on the offline network is compatible with the downloaded packages. Typically it is a good idea to use the exact mirror of the online network, e.g. the same Python version and the same operating system. Please note that the [recommended] flag is optional but will ensure that you get the recommended set of dependencies. Afterwards, you can then transfer these files to the offline network and install them with the following command:
pip install --no-index --find-links=. simos[recommended]
Python beginners
If you are completely new to Python, we recommend that you install the Anaconda distribution, which includes Python, the Jupyter notebook environment and many scientific libraries. You can download Anaconda from the following link:
https://www.anaconda.com/products/distribution
We generally recommend that you use a distinct Python environment for SimOS, e.g. a virtual environment or a conda environment. This will prevent conflicts with other Python packages that you might have installed on your system. After installation, open the Anaconda prompt and create a new environment with the following command:
conda create --name spin python=3.12
This will create a new environment called “spin” with Python 3.12. To activate the environment, run the following command:
conda activate spin
Now you can install SimOS in this environment with the following command:
pip install simos[recommended]
This will automatically install the recommended set of dependencies. You can now start the Jupyter notebook environment with the following command:
jupyter notebook
If you prefer a non-browser-based environment, you can install e.g. Visual Studio Code, which is a popular code editor with Python support. You can download Visual Studio Code from the following link:
SimOS Virtual Lab
Due to the amazing work of the Pyodide team, we are able to provide a virtual lab for SimOS. This virtual lab is a Jupyter notebook environment running in your browser, which allows you to run SimOS without installing it on your local machine. Nonetheless, all code execution is done locally in your browser. This is possible due to the WebAssembly technology, which allows to run Python code in the browser. The virtual lab is available at the following link:
Start SimOS Virtual LabPlease note that the virtual lab is an order of magnitude slower than running SimOS natively on your machine. The initial import can take up to one minute. It is intended for educational purposes and quick testing of the library. For more complex simulations, we recommend to install SimOS on your local machine.
Installation using Docker
If you prefer a containerized environment, you can use the provided Docker image. The images are designed to be lightweight and easy to use, with different variants for CPU, MKL, and CUDA support. Additionally, there are overlay images that add Jupyter Notebook support for interactive computing. You will need to have Docker installed on your system to use these images. After installing Docker, you can pull the latest image from Docker Hub with the following command (pick variant as needed):
# Base images
docker pull kherb27/simos:cpu
docker pull kherb27/simos:mkl
# Jupyter overlays
docker pull kherb27/simos:cpu-jupyter
docker pull kherb27/simos:mkl-jupyter
Note: The CUDA images are not available on Docker Hub due to image size constraints. Please use the GitHub Container Registry (GHCR) images instead, or build the CUDA images locally using the provided Dockerfiles in the repository.
To run the images, use
# Base images
docker run --rm -it kherb27/simos:cpu python
docker run --rm -it kherb27/simos:mkl python
# Jupyter overlays
docker run --rm -it -p 8888:8888 kherb27/simos:cpu-jupyter
docker run --rm -it -p 8888:8888 kherb27/simos:mkl-jupyter
If you want a persistant workspace, mount a local directory as /workspace, e.g.
docker run --rm -it -p 8888:8888 -v ./persistent:/workspace/persistent kherb27/simos:cpu-jupyter
docker run --rm -it -p 8888:8888 -v ./persistent:/workspace/persistent kherb27/simos:mkl-jupyter
You can then access the Jupyter Notebook server in your browser at http://localhost:8888.