TL;DR:
PySide6GUI for optical coupler simulations (powered byWaveguideModalBPM1D).
Quick start (from the repository root, with a virtual environment active):
pip install -e .
waveguidelabFor setup with uv or Python's venv, see Installation.
Desktop application for simulating optical couplers with a graphical user interface.
This repository is intentionally focused on the interface layer. The scientific
core lives in the separate package WaveguideModalBPM1D, which is
declared as a dependency of this project.
WaveguideLab: desktop GUI, input forms, plotting tabs, and presentation logic;WaveguideModalBPM1D: modal analysis, BPM simulation, sweeps, and scientific plots.
The goal is to keep the GUI project decoupled from the scientific package so that both can evolve independently.
- Python 3.12 or newer
- Optional: uv — recommended for creating the virtual environment and installing dependencies quickly
You need Python 3.12+ and a virtual environment. Pick one of the options below.
uv manages the venv and installs dependencies from pyproject.toml. Install it once using the official installer for your OS (Windows, Linux, or macOS). After installation, open a new terminal and confirm with uv --version.
Get the project — pick one:
-
Git clone (recommended for updates and development):
git clone https://github.com/fzappa/WaveguideLab.git cd WaveguideLab -
Release archive — from GitHub Releases, download Source code (zip) or Source code (tar.gz), extract it, and open a terminal in the folder that contains
pyproject.toml(often namedWaveguideLab-1.x.xafter extraction).
All following uv commands assume you are at that repository root.
Simplest workflow — uv creates/updates .venv and runs the app without you activating anything:
uv sync
uv run waveguidelabuv sync reads pyproject.toml (and lockfile if present) and installs into the project’s .venv.
If you prefer activating the environment yourself — same result as above, but you run waveguidelab after activation:
uv venvThen activate .venv and install in editable mode:
| Platform | Activate |
|---|---|
| Windows (PowerShell) | .\.venv\Scripts\Activate.ps1 |
| Windows (Command Prompt) | .venv\Scripts\activate.bat |
| Linux / macOS | source .venv/bin/activate |
uv pip install -e .
waveguidelabUse uv pip (not plain pip) so packages go into the environment uv created.
Create and activate a venv with the standard library, for example python -m venv .venv and the same activation commands as in the table above. Then:
pip install -e .
waveguidelabpip fetches WaveguideModalBPM1D from GitHub as declared in pyproject.toml.
Linux (Ubuntu) note: install Python 3.12+ and venv if needed, e.g. sudo apt install -y python3.12 python3.12-venv, then python3.12 -m venv .venv. If your distro does not provide 3.12 in the default repos, use deadsnakes or another supported Python 3.12+ build.
If you are developing both projects side by side:
pip install -e /path/to/WaveguideModalBPM1D
pip install -e .Or with uv (installs into the project .venv; activate first, or run commands with uv run …):
uv pip install -e /path/to/WaveguideModalBPM1D
uv pip install -e .This keeps WaveguideLab attached to your local editable checkout of the
scientific package.
From the repository root (with the environment active if you are not using uv run):
python main.pyIf the package is already installed:
waveguidelabmain.py: application entry point;core.py: orchestration layer between the GUI andWaveguideModalBPM1D;ui/: widgets, controls, and the main window;pyproject.toml: package metadata and dependencies.
WaveguideLab expects WaveguideModalBPM1D to be importable in the current
Python environment.
- Install
WaveguideModalBPM1Das a dependency; - Keep the GUI project independent from the scientific package internals.
This repository does not ship an in-tree copy of the scientific package. To use a local checkout during development, install it explicitly in editable mode:
pip install -e /path/to/WaveguideModalBPM1DThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See the LICENSE file.