 ===============================================================================
 COLLECTIVE EFFECTS IN QUANTUM OPTICS WITHIN & WITHOUT CAVITIES
 ICTP-SAIFR School, Sao Paulo, 27 July - 7 August 2026

 HOW TO SET UP AND RUN THE EXERCISE NOTEBOOKS
===============================================================================

You do NOT need a Google account. Everything runs on your own computer.

Please do this BEFORE the hands-on session. The install takes a few minutes
the first time, and it is much less stressful outside of class.

If anything fails, jump to section 6 (TROUBLESHOOTING) or section 7
(FALLBACK: RUN IN YOUR BROWSER).


-------------------------------------------------------------------------------
0. WHAT YOU NEED
-------------------------------------------------------------------------------

- Python 3.10 or newer.
- About 500 MB of free disk space.
- An internet connection for the installation step only. Once installed,
  the notebooks run fully offline.

To check whether you already have Python, open a terminal and run:

    python3 --version

(On Windows, open "PowerShell" or "Command Prompt" and use "python --version"
instead of "python3 --version".)

If you see something like "Python 3.11.5", you are ready. If the command is
not found, or the version is older than 3.10, install Python first:

    https://www.python.org/downloads/

IMPORTANT for Windows users: during installation, tick the box
"Add Python to PATH" on the first screen of the installer. If you forget it,
the commands below will not be found.


-------------------------------------------------------------------------------
1. DOWNLOAD THE MATERIAL
-------------------------------------------------------------------------------

Download the lecture folder from the link provided by the lecturer and unzip
it somewhere easy to reach, for example your Desktop or Documents folder.

You should end up with a folder containing:

    README.txt                        <- this file
    requirements.txt                  <- list of Python packages needed
    qutip_basics_lecture_1.ipynb      <- QuTiP reference/reminder notebook
    L1_01_exercise.ipynb              <- Exercise 1: Dicke superradiance
    L1_02_exercise.ipynb              <- Exercise 2: collective resonance
                                         fluorescence

(File names differ from lecture to lecture; the setup below is identical.)


-------------------------------------------------------------------------------
2. OPEN A TERMINAL IN THAT FOLDER
-------------------------------------------------------------------------------

Linux / macOS:
    Open the Terminal application, then type "cd " (with a space) and drag the
    folder onto the terminal window, then press Enter. For example:

        cd ~/Desktop/sao_paulo_lecture_1

Windows:
    Open the folder in File Explorer, click on the address bar, type
    "powershell" and press Enter. A terminal opens already in that folder.

To confirm you are in the right place, list the files:

    ls          (Linux / macOS)
    dir         (Windows)

You should see requirements.txt and the .ipynb files.


-------------------------------------------------------------------------------
3. CREATE A VIRTUAL ENVIRONMENT
-------------------------------------------------------------------------------

A virtual environment is a private, self-contained Python installation for
this school. It keeps these packages separate from the rest of your system,
so nothing you install here can break anything else on your computer. You can
delete it afterwards by simply deleting the folder.

Run ONE of the following, depending on your system.

Linux / macOS:

    python3 -m venv venv
    source venv/bin/activate

Windows (PowerShell):

    python -m venv venv
    venv\Scripts\Activate.ps1

Windows (Command Prompt):

    python -m venv venv
    venv\Scripts\activate.bat

If it worked, your prompt now starts with "(venv)". That means the
environment is ACTIVE.

Windows note: if PowerShell refuses with a message about "running scripts is
disabled on this system", run this once and then retry the activate command:

    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned


-------------------------------------------------------------------------------
4. INSTALL THE PACKAGES
-------------------------------------------------------------------------------

With "(venv)" showing in your prompt, run:

    pip install --upgrade pip
    pip install -r requirements.txt

This installs NumPy, SciPy, Matplotlib, QuTiP and Jupyter. It takes a few
minutes and prints a lot of text. That is normal.

You only ever have to do sections 3 and 4 ONCE.


-------------------------------------------------------------------------------
5. LAUNCH THE NOTEBOOKS
-------------------------------------------------------------------------------

Still in the same terminal, with "(venv)" active:

    jupyter lab

Your web browser opens automatically with a file browser on the left.
Double-click a notebook, for example L1_01_exercise.ipynb, to open it.

To run a cell: click on it and press SHIFT+ENTER.
Run the cells in order from the top.

To check that everything works, run this in the first code cell of any
notebook:

    import numpy, scipy, matplotlib, qutip
    print("qutip", qutip.__version__)
    print("all good")

If that prints a version number and "all good", you are ready for the session.

To stop Jupyter when you are finished: go back to the terminal and press
CTRL+C, then confirm with "y".

--- COMING BACK ON A LATER DAY -------------------------------------------------

You do NOT repeat the installation. Just open a terminal in the folder
(section 2), reactivate the environment, and launch Jupyter:

    source venv/bin/activate        (Linux / macOS)
    venv\Scripts\Activate.ps1       (Windows PowerShell)

    jupyter lab

The single most common problem in these sessions is forgetting to activate
the environment. If Python suddenly cannot find qutip, check that your prompt
shows "(venv)".

--- USING THE SAME ENVIRONMENT FOR ALL LECTURES ---------------------------------

You can reuse one environment for the whole school instead of creating a new
one per lecture. Create it once in a parent folder, then activate it from
wherever your notebooks are. For example, on Linux/macOS:

    cd ~/Desktop/sao_paulo_school
    python3 -m venv venv
    source venv/bin/activate
    pip install -r lecture_1/requirements.txt

and on later days simply reactivate that same venv before running
"jupyter lab" in the relevant lecture folder. If a later lecture ships a
requirements.txt with extra packages, just run "pip install -r" on it again
inside the same environment.


-------------------------------------------------------------------------------
6. TROUBLESHOOTING
-------------------------------------------------------------------------------

"python3: command not found" / "python: command not found"
    Python is not installed, or not on your PATH. Install it from
    python.org and, on Windows, tick "Add Python to PATH".
    On some Linux systems you may also need: sudo apt install python3-venv

"pip: command not found" or pip installs to the wrong place
    Use the safer form, which always uses the Python of your environment:
        python -m pip install -r requirements.txt

"ModuleNotFoundError: No module named 'qutip'"
    Almost always means the virtual environment is not active. Check that
    your prompt shows "(venv)". If not, reactivate it (section 3) and
    relaunch "jupyter lab" FROM THAT SAME TERMINAL.
    Note: launching Jupyter from a different terminal, or from a desktop
    icon, will not see the environment.

"jupyter: command not found"
    The install did not finish, or the environment is not active. Reactivate
    and rerun: pip install -r requirements.txt

Notebook opens but a cell hangs / the kernel keeps restarting
    Check the value of N in that cell. Large N is slow and memory-hungry.
    Start with the smallest N suggested in the notebook and increase it
    gradually.

A cell says "%pip install ..." at the top
    That line is harmless but redundant once you have installed things with
    requirements.txt. You can leave it or delete it; it will simply report
    that the packages are already present.

Plots do not appear
    Make sure the cell ends with plt.show(), and that you ran the import
    cell at the top of the notebook first.


-------------------------------------------------------------------------------
7. FALLBACK: RUN IN YOUR BROWSER (NO INSTALLATION AT ALL)
-------------------------------------------------------------------------------

If the local installation cannot be made to work in time, you can run the
notebooks entirely inside your web browser, with no account and no install:

    https://qutip.org/try-qutip.html

Use a recent Firefox or Chrome. When it loads, upload the .ipynb file using
the upload button in the file browser on the left, open it, and select the
XPython kernel if prompted. The first imports are slow; after that it behaves
much like a local installation.

Two warnings:

  - Delete or skip any "%pip install" line in the notebook; the packages are
    already provided there.
  - Your work is stored only in the browser. DOWNLOAD THE NOTEBOOK before
    closing the tab, or you will lose your edits.

This route is fine for the Lecture 1 exercises. It is noticeably slower for
the larger simulations in later lectures, so prefer the local installation
if you can.

And if all else fails: pair up with a neighbour who has a working setup.
Discussing the physics with someone else is not a consolation prize.


-------------------------------------------------------------------------------
8. REMOVING EVERYTHING AFTERWARDS
-------------------------------------------------------------------------------

Deactivate the environment with:

    deactivate

Then simply delete the "venv" folder. Nothing was installed anywhere else on
your system.

===============================================================================
