Appendix A — Running the notebooks

A.1 Three ways to use this companion

  1. Read the website. The sliders (OJS panels) run in the browser with no installation. Open _book/index.html through a web server (e.g. quarto preview, or any static host such as GitHub Pages or the university web space). Some browsers block the interactive panels when the file is opened directly from disk.
  2. Run the code in Jupyter. Each chapter exists as a notebook in notebooks/ (generated with quarto convert chapter.qmd). The notebook notebooks/interactive_explorers.ipynb gathers ipywidgets versions of the main panels (fiber designer, b–V chart, dispersion, link simulator).
  3. Rebuild the book after editing a chapter.

A.2 Publishing the website (GitHub Pages)

The source lives at https://github.com/philippevelha/Optoelectronics-teaching (folder chapter2/) and the site at https://philippevelha.github.io/Optoelectronics-teaching/chapter2/. After editing a chapter:

cd notebooks && python build_notebooks.py && cd ..   # refresh the notebooks (Colab buttons point to them)
git add -A && git commit -m "Update chapter" && git push   # update the source on GitHub
bash ../publish.sh                                       # render and update the website

A.3 Installation

pip install -r requirements.txt     # numpy scipy matplotlib pandas jupyter ipywidgets (+ optional OptiCommPy)
quarto preview                      # live preview while editing
quarto render                       # builds _book/ (HTML)

Rendering executes every Python cell once. Results are cached in _freeze/ (freeze: auto), so later builds only re-run the chapters you changed.

A.4 Regenerating the notebooks

cd notebooks
python build_notebooks.py

The script converts every chapter, adds a setup cell that works both locally and in Colab (it downloads fiberlib.py from GitHub when running in Colab), and rebuilds interactive_explorers.ipynb.

The notebooks keep the Python cells. The OJS cells (browser panels) appear as non-executable cells. Use interactive_explorers.ipynb for their Python equivalents.

A.5 The fiberlib module

function purpose
slab_modes, slab_field, slab_penetration, slab_beta symmetric planar guide, TE/TM
LP_b, LP_all, LP_count, LP_field, b_approx step-index LP modes (exact, weak guidance)
mfd_marcuse, mfd_exact_gaussian, mfd_petermann2 mode-field diameter
n_doped, n_silica, group_index, D_material Sellmeier glasses and material dispersion
neff_smf, group_delay_smf, D_total_smf, D_waveguide_approx exact chromatic dispersion of an SMF
sigma_intermodal_grin Olshansky–Keck graded-index spread
rayleigh_alpha, attenuation_model loss
prbs, imdd_link, eye_metrics, Q_to_BER link simulation
fbg_reflectance, fbg_bandwidth, fabry_perot_T gratings and interferometers

Every function was checked against the worked examples of the slides (see the “recomputed” sections).