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 --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.