fermilink 0.3.1

Write a goal.md, FermiLink takes care of autonomous scientific simulations and optimization at both laptops and HPCs

Write a goal.md. Let AI handle the rest.

FermiLink reads a simple markdown file describing your scientific computing goal,
then autonomously runs and iterates on your laptop or HPC clusters,
so you can focus on the science, not the infrastructure.

---

What Can FermiLink Do?

🔬 Autonomous Scientific Simulations (stable)

Describe a simulation goal in plain language. FermiLink picks the right packages, generates input files, submits jobs, monitors progress, and analyzes the data, even across multi-day HPC campaigns with hundreds of tasks.

fermilink loop goal.md          # long-running simulations on workstations or HPC
fermilink research goal.md      # full research-paper-scale, multi-task campaigns

⚡ Autonomous Code Optimization (beta)

Apply FermiLink to your existing scientific code with a performance goal. It iteratively modifies hot paths and runs deterministic benchmarks.

At the end of the day, it provides optimized scientific code with improved speed while preserving computational accuracy.

fermilink optimize goal.md      # iterative code with correctness guarantees

Both features share the same interface: a single goal.md file.

---

How it works?

Step 1. You write a goal.md, a plain markdown file:

# Goal: Photonic crystal band structure

Simulate the band structure of a 2D triangular lattice of dielectric
rods (r=0.2a, ε=12) in air using MEEP/MPB.

## What to compute
- TM and TE band diagrams along Γ->M->K->Γ
- Extract the band gap ratio (Δω/ω_mid) for the first gap

## Success criteria
- At least 8 bands converged with resolution ≥ 32
- Band gap ratio within 5% of published values

## Deliverables
- Save final band diagram as `bands.png`

Step 2. Run one command:

fermilink loop goal.md

Step 3. FermiLink takes over. You come back to a finished bands.png and a summary report.

---

Quickstart (5 minutes)

# 1. Install
pip install fermilink

# 2. Set up an AI agent (pick one)
fermilink agent codex        # or: claude, gemini

# 3. Install a scientific package knowledge base
fermilink install meep       # 150+ packages available

# 4. (Optional) Configure the default SLURM HPC profile
fermilink hpc

# 5. Write your goal.md (see example above), then run
fermilink loop goal.md

That's it, you are all set!

First time? Just run fermilink with no arguments. Then, an interactive setup wizard will walk you through everything.

---

How It Works

FermiLink separates what you want (your goal.md) from how to do it (package knowledge + agent reasoning):

┌─────────────┐      ┌──────────────────┐      ┌──────────────────┐
│   goal.md   │ ───▸ │   AI Agent       │ ───▸ │   Simulation /   │
│  (your      │      │  (Claude, Codex, │      │   Optimization   │
│   intent)   │      │   Gemini)        │      │   Engine         │
└─────────────┘      └──────────────────┘      └──────────────────┘
                            │                          │
                     reads from                  runs on
                            ▼                          ▼
                   ┌──────────────────┐      ┌──────────────────┐
                   │  Package         │      │  Your laptop,    │
                   │  Knowledge Base  │      │  workstation,    │
                   │  (150+ packages) │      │  or HPC cluster  │
                   └──────────────────┘      └──────────────────┘

The agent doesn't just generate scripts. Instead, it sustains multi-task, multi-day computational campaigns without human intervention.

---

Workflows at Every Scale

FermiLink supports the following six major commands for various simulation workflows:

Command	Best for	Duration	Recommended Environment
exec	Quick one-off simulations	Minutes	Laptop / workstation
chat	Interactive conversation with agents	Hours	Laptop / workstation
loop	Iterative jobs with PID/SLURM monitoring	Hours -> days	Workstation / HPC
reproduce	Multi-task, paper-scale reproducation of papers	Days -> weeks	HPC clusters
research	Multi-task, paper-scale research	Days -> weeks	HPC clusters
optimize	Code performance tuning (beta)	Hours	Any

---

Three Ways to Interact

FermiLink isn't just a CLI tool. Pick the interface that fits you:

• Command line — fermilink exec/loop/reproduce/research/optimize goal.md for headless, scriptable autonomy
• Web UI — fermilink start launches a ChatGPT-style browser interface for interactive sessions
• Telegram bot — fermilink gateway connects to Telegram so you can run and monitor HPC jobs from your phone

---

150+ Built-in Scientific Packages

FermiLink ships with knowledge bases for packages spanning multiple scientific domains. Install any of them with a single command:

fermilink install <package>       # e.g., meep, lammps, pyscf, openfoam
fermilink list                    # see all installed packages

Don't see your package? Compile your own local knowledge base:

fermilink compile /path/to/your/code

Browse the full package list →

---

Build Your Own Package Knowledge Base

If you have a research pipeline described in a paper or group-specific workflow, you can turn them into a FermiLink-compatible knowledge base:

# Compile a local code into a knowledge base
fermilink compile /path/to/my-simulation-code

# Recompile after updating your code
fermilink recompile my-simulation-code

This means FermiLink can autonomously operate any scientific code, not just the 150+ that ship built-in.

---

Documentation

Resource	Link
Full documentation	fermilink.org
Installation guide	fermilink.org/installation
Laptop tutorial	fermilink.org/tutorial_laptop
HPC tutorial	fermilink.org/tutorial_hpc
Architecture	fermilink.org/architecture
API reference	fermilink.org/api

---

Citation

If FermiLink is useful in your research, please cite:

• Gang Meng†, Andres Felipe Bocanegra Vargas†, Xinwei Ji†, Federico Garcia-Gaitan, Felipe Reyes-Osorio, Jalil Varela-Manjarres, Yafei Ren, Mohammadhasan Dinpajooh, Branislav K. Nikolić, Tao E. Li. FermiLink: A Unified Agent Framework for Multidomain Autonomous Scientific Simulations. arXiv:2604.03460 (2026).

---

Contributing

We welcome contributions, from bug reports to new package knowledge bases. See CONTRIBUTING →

---

License

AGPL-3.0