Release4.1

.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.gif binary

.github/workflows/actions.yaml

@@ -10,7 +10,7 @@ jobs:
     - uses: actions/checkout@master
     - uses: actions/setup-python@master
       with:
-        python-version: 3.8
+        python-version: "3.12"
     - run: |
         make install
         make lint
@@ -22,9 +22,10 @@ jobs:
     - uses: actions/checkout@master
     - uses: actions/setup-python@master
       with:
-        python-version: 3.8
+        python-version: "3.12"
     - run: |
         make install
+        make test-deps
         make tests
 
   examples:
@@ -34,7 +35,7 @@ jobs:
     - uses: actions/checkout@master
     - uses: actions/setup-python@master
       with:
-        python-version: 3.8
+        python-version: "3.12"
     - run: |
         make install
         make examples

.github/workflows/docs.yaml

@@ -0,0 +1,46 @@
+name: Build docs
+
+on: push
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    # We only execute this step if the commit is tagged, i.e., this is a release
+    if: startsWith(github.ref, 'refs/tags')
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@master
+      - name: Build docs
+        uses: actions/setup-python@master
+        with:
+          python-version: "3.12"
+      # We *need* to install projectq to generate documentation
+      # This is needed because sphinx analyzes SimulaQron's code to generate the HTML;
+      # this implies that the modules are imported (but not executed), which therefore
+      # imports projectq classes.
+      - name: Install simulaqron and build docs
+        run: |
+          make install-optional
+          cd docs
+          make install-deps
+          make build
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/build/html/
+
+  deploy:
+    name: Deploy docs
+    needs: build
+    runs-on: ubuntu-latest
+    # We only execute this step if the commit is tagged, i.e., this is a release
+    if: startsWith(github.ref, 'refs/tags')
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yaml

@@ -0,0 +1,46 @@
+name: Publish Python distributions to PyPI
+
+on: push
+jobs:
+  build-n-publish:
+    name: Build and publish Python distributions to PyPI
+    runs-on: ubuntu-latest
+    # We only execute this step if the commit is tagged, i.e., this is a release
+    if: startsWith(github.ref, 'refs/tags')
+    # Use the following for PyPI deployments
+    environment:
+      name: pypi
+      url: https://pypi.org/p/simulaqron
+    # Use the following for TestPyPI deployments
+#    environment:
+#      name: testpypi
+#      url: https://test.pypi.org/p/simulaqron
+    permissions:
+      id-token: write
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@master
+    - name: Set up Python 3.12
+      uses: actions/setup-python@master
+      with:
+        python-version: "3.12"
+    - name: Install pypa/build
+      run: >-
+        python3.12 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: >-
+        python3.12 -m
+        build
+        --sdist
+        --wheel
+        --outdir dist/
+        .
+#    - name: Publish distribution to Test PyPI
+#      uses: pypa/gh-action-pypi-publish@release/v1.14
+#      with:
+#        repository_url: https://test.pypi.org/legacy/
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1.14

.gitignore

@@ -1,6 +1,7 @@
 *.pyc
 .*.sw?
 *.DS_Store
+*.whl
 /docs/build/*
 /build/*
 /dist/*
@@ -9,6 +10,9 @@
 
 .idea/*
 .vscode/*
+.claude/*
 
 cqc/backend/logFile*
 examples/**/log/*
+
+*.out.txt

CHANGELOG.md

@@ -5,6 +5,15 @@ For more details refer to the [documentation](https://softwarequtech.github.io/S
 
 Upcoming
 --------
+2026-03-13 (v4.0.1)
+-------------------
+- Migrated project specification to use modern TOML approach.
+- Tested working with Python versions 3.10, 3.11 and 3.12.
+- Added new SDK for easily creating SimulaQron applications. This new SDK allows to also create
+  client-server applications using event-based programming paradigm.
+- Updated the SimulaQron network configuration file format. This is done to align the network
+  configuration file with the data required by SimulaQron "native" mode and the "NetQASM" mode.
+- Updated documentation of most of the undocumented functions and to match the new developments.
 
 2021-11-18 (v4.0.0)
 -------------------

CLAUDE.md

@@ -0,0 +1,30 @@
+# SimulaQron Development Conventions
+
+## Hard Requirements
+
+### Examples
+- Examples MUST always use separate files per node (e.g. `nodeTest-client.py`, `nodeTest-server.py`), never single-file programs. Students must be able to run each node on a separate machine.
+- Follow the `new-sdk/template-client-server` structure: two node scripts + `run.sh` + `terminate.sh` + config JSONs.
+- All nodes should print their own output (not rely on return values visible only to the test harness).
+
+### Connection Pattern
+- Prefer creating a `NetQASMConnection` once and reusing it with `flush()` for multi-round quantum programs, rather than opening/closing with `with` each round.
+- `conn.flush()` is the sync point that makes measurement results readable via `int(m)`.
+
+### Backends
+- Use `stabilizer` backend by default in examples and tests unless non-Clifford gates are needed.
+- `projectq` is deprecated / hard to install. Prefer `qutip` when full state simulation is needed.
+
+## File Conventions
+- **Examples:** `examples/new-sdk/` — all new examples use the new SDK
+- **Tests:** `tests/slow/sdk/` — SDK-level integration tests
+- **Core code:** `simulaqron/` — simulator source
+- **Docs:** `docs/` — Sphinx documentation (currently outdated, being rewritten)
+
+## Git / Commit Policy
+- **Always run `make ci` before committing.** All linting, tests, and examples must pass before any commit is created.
+- Never commit or push without explicit user approval.
+
+## Virtual Environment
+- The project venv is at `.venv/` — activate with `source .venv/bin/activate`
+- Install with `pip install -e .` (skip `[test]` if projectq build fails)

Dockerfile

@@ -1,57 +1,88 @@
-## Dockerfile
-# This container provides a complete run-time environment for SimulaQron.
-#
-## Build:
-# From inside the top-level SimulaQron directory run
-#
-#     docker build -t <image_name> .
-#
-# where you should replace <image_name> with the name you want to give to the
-# docker image.
-#
-## Run:
-# To start the container and enter the shell prompt inside, run
-#
-#     docker run -it <image_name>
-#
-# This will start a docker container with SimulaQron inside the
-# /workspace/SimulaQron directory (this default can be changed, by changing the
-# WORKSPACE variable in this file). Note that this is only a COPY of the
-# SimulaQron directory that was made during the build step so if you make any
-# changes on the host system, they will not be reflected in the container until
-# you rebuild the image.
-#
-# However, if you wish, you can mount the host's SimulaQron directory into the
-# container rather than using a copy made during the build step, you need to
-# explicitly mount it when starting the container, e.g.
-#
-#     docker run -it -v /path/to/SimulaQron:/workspace/SimulaQron <image_name>
-#
-# This will mount /path/to/SimulaQron inside the container in
-# /workspace/SimulaQron. Note that on Linux systems with SELinux present, the
-# mount option has to be `-v /path/to/SimulaQron:/workspace/SimulaQron:z`.
-#
-## Multiple shells:
-# To attach to a running container with a new shell run
-#
-#     docker exec -it <container_name> bash
-#
-# where <container_name> is the name of the running container (this is in
-# general not the same as the image name). To find what name your container
-# has, run `docker ps`.
-
-FROM ubuntu:18.04
-LABEL author="Wojciech Kozlowski <w.kozlowski@tudelft.nl>"
-
-# Update docker image
-ENV DEBIAN_FRONTEND=noninteractive
-RUN apt-get update && apt-get upgrade -y
-
-# Install Python 3
-RUN apt-get install -y python3 python3-pip python3-tk
-
-# Set a UTF-8 locale - this is needed for some python packages to play nice
-RUN apt-get -y install language-pack-en
-ENV LANG="en_US.UTF-8"
-
-RUN pip3 install simulaqron
+# If you need a slim version, use "alpine" base instead of trixie (Debian)
+#FROM python:3.12-alpine AS base-image
+FROM ubuntu:24.04 AS base-image
+
+# Install packages
+
+#RUN apk add --no-cache bash vim nano libstdc++ libgomp
+RUN apt-get update
+RUN apt-get dist-upgrade -y
+RUN apt-get install -y bash vim nano libgomp1 adduser git openssl make software-properties-common
+
+RUN add-apt-repository ppa:deadsnakes/ppa
+RUN apt-get update
+
+# Install Python 3.12
+RUN apt-get install -y python3.12-full python3.12-dev
+
+# Switch to Bash
+SHELL ["/bin/bash", "-c"]
+
+# Delete the build-in user - not needed in alpine images
+RUN userdel -r ubuntu
+
+# Create student user
+ARG GNAME=student
+ARG GID=1000
+ARG UNAME=student
+ARG UID=1000
+ARG UHOME=/home/student
+ENV HOME=${UHOME}
+RUN set -o errexit -o nounset
+RUN addgroup --gid ${GID} "${GNAME}"
+RUN adduser --home "${UHOME}" --disabled-password --uid ${UID} --ingroup "${GNAME}" "${UNAME}"
+WORKDIR ${UHOME}
+
+# Remove unnecessary software
+RUN apt-get purge -y adduser software-properties-common
+RUN apt-get autoremove -y
+
+FROM base-image AS venv-image
+
+# Install build essentials, to correctly build python deps
+# We install it only for this stage, so we create a lighter docker image for executing
+#RUN apk add --no-cache alpine-sdk
+RUN apt-get update
+RUN apt-get install -y build-essential cmake linux-headers-generic
+
+# Create python virtual environment
+WORKDIR ${UHOME}
+RUN python3.12 -m venv simulaqron-venv
+# We have to "manually" activate the virtual environment
+ENV PATH="${UHOME}/simulaqron-venv/bin:$PATH"
+
+# Install SimulaQron
+# Option 1: Install from the wheel file
+# Copy the simulaqron wheel into the container
+COPY dist/*.whl ${UHOME}
+RUN pip install *.whl
+RUN rm *.whl
+
+# Install extra packages that need build-essential
+RUN pip install "qutip<5.0.0"
+RUN pip install "setuptools<81" pybind11
+RUN pip install "git+https://github.com/ProjectQ-Framework/ProjectQ.git@v0.8.0" --no-build-isolation
+
+# Option 2: (Recommended for release) Install from PyPI
+#RUN pip install "simulaqron[opt]>=4.0.1"
+
+FROM base-image AS run-image
+
+# Copy installed python packages from previous image
+COPY --from=venv-image --chown=${UNAME} ${UHOME}/simulaqron-venv "${UHOME}/.local"
+# Since these files come from a python virtual environment
+# we need to fix some absolute paths
+WORKDIR ${UHOME}/.local/bin
+RUN sed -i "s|${UHOME}/simulaqron-venv/|${UHOME}/.local/|g" *
+# Activate the "virtual environment" we just copied
+ENV PATH="${UHOME}/.local/bin:${UHOME}/.local:$PATH"
+
+# Configure libgomp to use a single thread to avoid deadlocks in simulaqron
+ENV OMP_NUM_THREADS=1
+
+# Switch to user student
+USER student
+WORKDIR ${UHOME}
+RUN echo 'export PS1="\[\e]0;\u@\h: \w\a\]${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ "' >> ~/.bashrc
+
+CMD bash