Tutorial: Laptop Simulations
===============================

This tutorial shows how to run **FermiLink** locally on a laptop/workstation
(macOS/Linux). It is designed to be **self-contained**, so you can follow it end-to-end without
reading other pages.

For using **FermiLink** optimization features, see :doc:`optimize` for a separate optimization tutorial.

This tutorial assumes the default **FermiLink** runtime location is located at:

- ``~/.fermilink``

.. note::

   If you want a different runtime location later, see :doc:`configuration`. This tutorial intentionally sticks to the
   defaults for a quick laptop use.

Prerequisites
~~~~~~~~~~~~~~~~

You need:

- Python ``>= 3.11``
- ``git`` on ``PATH`` (workspaces are git repos)
- Node.js + ``npm`` (or Homebrew on macOS) for local agent provider CLIs


Step 1. Create a clean Python environment (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use conda environment so your laptop test does not modify your system Python:

.. code-block:: bash

   conda create -n fermilink python=3.11 -y
   conda activate fermilink


Step 2. Install agent provider CLI and authenticate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**FermiLink** currently supports **OpenAI Codex**, **Claude**, **Gemini**, and
**OpenCode** as the agent providers.
Install and authenticate the provider you want to use:

.. code-block:: bash

   # Codex option
   npm i -g @openai/codex
   codex login
   # Please read the official documentation of Claude, Gemini, and OpenCode for installation.
   # Claude login
   claude 
   # Gemini login
   gemini
   # OpenCode login
   opencode auth login

.. note::

   On macOS, you can also install the Codex CLI via Homebrew (if preferred)::

     brew install codex

Step 3. Install **FermiLink**
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clone the repo and install the CLI into your active Python environment:

.. code-block:: bash

   pip install fermilink

Quick check:

.. code-block:: bash

   fermilink --help


Step 4. Install a scientific package knowledge base
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**FermiLink** routes each user request to an installed scientific package knowledge base, so
**install at least one package knowledge base** before you run anything.

This laptop tutorial uses ``qutip`` because it runs well locally and is a good
fit for small "hello world" quantum simulations:

.. code-block:: bash

   # discover packages in the default curated channel
   fermilink avail qutip

   # install and set a default package for new sessions
   fermilink install qutip --activate

   # verify installed packages
   fermilink list

.. note::

   ``fermilink install`` downloads the **knowledge base** (source + skills) into
   ``~/.fermilink/scientific_packages``. It does not necessarily install the
   underlying runtime library used for execution.

You can optionally install in Python to **really install** the package:

.. code-block:: bash

   pip install qutip

Of course, the agent can do this installation on its own, but it is recommended to have the software already installed for better performance and reliability.

If you want to use a different scientific package, see the built-in catalog:
:doc:`built_in_scientific_packages`.


Step 5. Set agent runtime policy (sandbox)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, **FermiLink** runs in a restricted sandbox, but you can also relax the sandbox for more flexible agent execution (for example, when running local MPI jobs). 

.. code-block:: bash

   # show current policy
   fermilink agent --json

   # enforce sandbox mode (default) for codex
   fermilink agent codex --sandbox --model gpt-5.3-codex --reasoning-effort xhigh

   # relax sandbox for codex (for better performance)
   fermilink agent codex --bypass-sandbox --model gpt-5.3-codex --reasoning-effort high

   # relax sandbox for claude, gemini, or opencode
   fermilink agent claude --bypass-sandbox --model sonnet --reasoning-effort high
   fermilink agent gemini --bypass-sandbox --model auto-gemini-3 --reasoning-effort high
   fermilink agent opencode --bypass-sandbox --model openai/gpt-5.5 --reasoning-effort xhigh

.. warning::

   If you bypass the sandbox (i.e., replacing ``--sandbox`` with ``--bypass-sandbox``), **never run as root**. Use a dedicated non-root
   account and keep regular backups of your data.


Step 6. Hello world on a laptop (``exec``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run a single prompt in a clean project directory.

.. code-block:: bash

   mkdir -p ~/fermilink_laptop_demo/run_qutip_demo
   cd ~/fermilink_laptop_demo/run_qutip_demo

   fermilink exec "Use qutip to simulate the Jaynes-Cummings model (two-level system + single cavity mode). Plot the excited-state population vs time." 

.. figure:: _static/img/fermilink_laptop_exec_qutip.png
   :alt: FermiLink exec snapshot on a laptop.
   :align: center
   :width: 95%

What ``exec`` does:

- overlays the selected package knowledge base into the current repo
- initializes or updates ``projects/memory.md``
- runs the agent locally (no SLURM / no ``--hpc-profile``)


Step 7. Interactive terminal chat (``chat``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use ``chat`` for multi-turn interaction in the terminal:

.. code-block:: bash

   cd ~/fermilink_laptop_demo/run_qutip_demo
   fermilink chat

Then ask follow-ups like:

.. code-block:: text

   For the previous simulations, refine the plot styling with Nature publication quality and save the figure as jc_population_refined.png.

.. figure:: _static/img/fermilink_laptop_chat_qutip.png
   :alt: FermiLink chat snapshot on a laptop.
   :align: center
   :width: 95%

As this is run in the same workspace as the previous ``exec`` run, the agent can refer to the previous context and files in the repo using the shared memory at ``projects/memory.md``.

The generated figure is as follows:

.. figure:: _static/img/jc_population_refined.png
   :alt: Refined Jaynes-Cummings population plot.
   :align: center
   :width: 60%

Step 8. Web UI on a laptop (``start``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you prefer a ChatGPT-style interface, start the local runner + web UI:

.. code-block:: bash

   fermilink start

Then your browser will automatically open the following webpage:

.. figure:: _static/img/web_ui_entry.png
   :alt: FermiLink web UI.
   :align: center
   :width: 95%

**Sign UP** with an account and then **Sign In**. You can then enjoy a ChatGPT-style interface with the same agent capabilities as the terminal, but with better interactivity and visualization support.

Step 9. Longer local runs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some scientific simulations take hours or days. For these longer runs, use the ``loop`` command to let the agent iterate until the goal is met.

On a laptop, you can perform iterative runs with local PID monitoring.

.. code-block:: bash

   cd ~/fermilink_laptop_demo/run_qutip_demo
   fermilink loop goal.md --max-iterations 5 --max-wait-seconds 3600

The **goal.md** file can be replaced by a string prompt directly (just like the `exec` mode).

See :doc:`writing_goal_md` regarding how to write effective ``goal.md`` files.


.. note::

   ``research`` and ``reproduce`` are expensive. Prefer ``exec``/``loop`` first
   to debug your prompt and environment.


Where your data lives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, **FermiLink** stores runtime data under ``~/.fermilink``:

- ``scientific_packages/``: installed package knowledge bases
- ``workspaces/``: per-session workspaces (web UI, workflows, some CLI runs)
- ``runtime/logs/``: service logs (runner/web/gateway)


Troubleshooting quick checks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- **Provider CLI not found**: confirm install/PATH for the selected provider
  (``codex``, ``claude``, ``gemini``, or ``opencode``), then run the
  corresponding login command.
- **No packages installed**: run ``fermilink install <package_id> --activate``,
  then verify with ``fermilink list``.
- **Runtime package missing**: install the underlying package (for example
  ``pip install qutip``); **FermiLink** only installs the knowledge base.


Further reading (optional)
----------------------------

- :doc:`installation` for installation details.
- :doc:`usage` for CLI modes and flags.
- :doc:`scientific_packages` for package management and dependencies.
- :doc:`tutorial_hpc` for SLURM-based HPC workflows.
