Skip to content

Commit cd476e6

Browse files
e-g-meloe-g-melo
committed
Tidy3D + AI v0.
1 parent 2a0cc9f commit cd476e6

File tree

11 files changed

+889
-0
lines changed

11 files changed

+889
-0
lines changed

‎docs/ai/3DViewer.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# 3D Viewer
2+
3+
*Interactive visualization of Tidy3D simulations directly within your IDE*
4+
5+
The 3D Viewer is an interactive visualization tool that provides real-time, three-dimensional rendering of Tidy3D simulations directly within your code editor. Integrated seamlessly into the Tidy3D extensions for [Cursor](CursorExtension.md) and [VS Code](VSCodeExtension.md), the viewer automatically detects simulation objects in your Python scripts and notebooks, opening alongside your code to provide immediate visual feedback as you develop.
6+
7+
## Overview
8+
9+
The 3D Viewer transforms how you interact with electromagnetic simulations by bringing visualization directly into your development environment. Instead of switching between your code editor and external visualization tools, you can see your simulation geometry, sources, monitors, and boundary conditions update in real-time as you modify your code.
10+
11+
<img src="viewer.png" alt="Tidy3D 3D Viewer" style="max-height: 300px; width: auto; height: auto;">
12+
13+
## Key Features
14+
15+
- **Automatic Detection** – Automatically identifies `Simulation` objects in your code and opens the viewer
16+
- **Live Synchronization** – Updates instantly when you modify geometry, materials, sources, or monitors
17+
- **Interactive Navigation** – Rotate, zoom, and pan to explore your simulation from any angle
18+
- **AI-Controlled** – [FlexAgent MCP](FlexAgent.md) can navigate and explain the 3D scene through natural language
19+
- **Editor-Native** – No context switching; visualization happens right where you code
20+
- **Comprehensive Visualization** – View structures, sources, monitors, boundary conditions, and simulation domains
21+
22+
## Getting Started
23+
24+
The 3D Viewer is automatically available when you install the Tidy3D extension for [Cursor](CursorExtension.md) or [VS Code](VSCodeExtension.md). No additional setup is required.
25+
26+
1. **Create or open a Tidy3D simulation** in your Python script or Jupyter notebook.
27+
2. **Define a `Simulation` object** – The viewer automatically detects it.
28+
3. **Open Viewer** – Click the status bar, use the command palette (`Cmd/Ctrl+Shift+P -> Tidy3D: Open Tidy3D`), or ask the AI assistant to open the viewer.
29+
30+
The 3D Viewer is part of the comprehensive Tidy3D + AI ecosystem. For more information, see the [Tidy3D + AI overview](Tidy3DPlusAI.md).

‎docs/ai/CursorExtension.md‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
# Tidy3D for Cursor
2+
3+
*Bringing Tidy3D's electromagnetic simulation platform directly to your code editor*
4+
5+
Build, visualize, and iterate on electromagnetic simulations seamlessly within Cursor. The extension automatically detects simulations in [Tidy3D](https://www.flexcompute.com/tidy3d/) Python scripts and notebooks, opens an interactive 3D viewer alongside your code, and enables the AI assistant to leverage the integrated FlexAgent MCP server for an intelligent, context‑aware assistance experience.
6+
7+
<img src="extension_cursor.png" alt="Tidy3D Extension for Cursor" style="max-height: 300px; width: auto; height: auto;">
8+
9+
## 📋 Table of Contents
10+
11+
- [🚀 Quick Start Guide](#-quick-start-guide)
12+
- [🌟 Highlights](#-highlights)
13+
- [🤖 AI-Powered Assistance](#-ai-powered-assistance)
14+
- [🖥️ 3D Viewer](#️-3d-viewer)
15+
- [📦 Installation & Setup](#-installation--setup)
16+
- [📚 Technical Reference](#-technical-reference)
17+
- [🔧 Troubleshooting & Support](#-troubleshooting--support)
18+
- [📄 License](#-license)
19+
20+
## 🚀 Quick Start Guide
21+
22+
*From zero to first simulation in a few minutes*
23+
24+
- Install [Cursor](https://cursor.com/home?from=agents)
25+
- In the Extensions view panel (`View → Extensions`), search and install the "Tidy3D" extension.
26+
- Create a new folder, download and open the [Tidy3D Quickstart Notebook](https://docs.flexcompute.com/projects/tidy3d/en/latest/_sources/notebooks/StartHere.ipynb)
27+
- Run `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup`
28+
- Paste your Tidy3D API key when prompted. Get a FREE account and API key [here](https://tidy3d.simulation.cloud/signup)
29+
- Ask the assistant to modify the box dimensions: "Change the box dimension to (2, 1, 1)."
30+
31+
## 🌟 Highlights
32+
33+
*Unique value within the Tidy3D ecosystem*
34+
35+
- **AI-Enhanced Workflows** – AI assistance with Tidy3D expertise through integrated FlexAgent MCP server
36+
- **Structured Assistance** – Step-by-step guidance from learning to optimization
37+
- **Trusted Knowledge Base** – Direct integration with [Tidy3D's comprehensive documentation](https://docs.flexcompute.com/projects/tidy3d/en/latest/index.html)
38+
- **Editor-Native Viewer** – No context switching between tools
39+
- **Live Code Synchronization** – See geometry changes instantly as you type
40+
- **AI-Controlled Visualization** – Let the AI assistant navigate and explain the 3D scene
41+
42+
## 🤖 AI-Powered Assistance
43+
44+
*Physics-informed assistance through Cursor and FlexAgent MCP integration*
45+
46+
The extension integrates with Cursor's AI assistant to provide physics-aware assistance for electromagnetic simulations. Unlike generic coding assistants, this integration understands Tidy3D workflows and can control the 3D viewer.
47+
48+
### FlexAgent Scenarios
49+
50+
The command `Tidy3D: Run Tidy3D Workspace Setup` deploys FlexAgent rules under `.cursor/rules/` that transform the AI assistant into a physics-aware simulation partner. These are structured workflows relying on Tidy3D's trusted documentation.
51+
52+
- **Learning** - *"Explain me how Tidy3D FDTD updates the fields in this notebook"*
53+
- **Troubleshooting** - *"I want to fix the structure related validation error"*
54+
- **Customization** - *"Replace the FluxMonitor with a ModeMonitor"*
55+
- **Build from Scratch** - *"Create a basic y-junction waveguide simulation setup"*
56+
- **Result Analysis** - *"Plot all the electric field components"*
57+
58+
### AI Collaboration Best Practices
59+
60+
- **Leverage FlexAgent rules for optimal results** – For best performance, explicitly reference the integrated rules: *"Follow the rules in `flexagent.mdc` for all responses. These rules take priority over other instructions."*
61+
62+
- **Start simple, build incrementally** – Begin with basic simulations and add complexity step by step for easier debugging and understanding.
63+
64+
- **Provide rich context in your prompts** – The more specific you are, the better the agent's assistance. Instead of "help with mode analysis," try: *"I'm studying photonic integrated circuits. How can I use Tidy3D to analyze the fundamental TE mode of a 220 nm thick silicon strip waveguide?"*
65+
66+
- **Use the viewer for real-time iteration** – Keep the 3D viewer open while editing your simulation code. Changes to geometry, materials, sources, or monitors update automatically, letting you immediately visualize the impact of parameter tweaks without re-running the code.
67+
68+
- **Be specific when troubleshooting** – Instead of "fix all errors," provide targeted information: *"Fix the boundary condition warning for structure[0]"* or *"Resolve the mesh refinement issue near the waveguide core."*
69+
70+
- **Understand before proceeding** – Take time to comprehend the generated code and simulation setup. Ask the agent to explain concepts you're unfamiliar with before building upon them.
71+
72+
- **Use incremental validation** – After each major change, ask the agent to *"validate and explain the simulation changes"* before proceeding to ensure physical accuracy.
73+
74+
- **Document your simulation intent** – Add comments explaining the physics you're trying to model: `# Modeling evanescent coupling between two strip waveguides separated by 200 nm`
75+
76+
- **Specify your Python environment** – Tell the agent which environment to use: *"Run this code using my `tidy3d_latest` conda environment located at `/home/user/miniconda3/envs/tidy3d_latest`."*
77+
78+
### Prompt Examples
79+
80+
- **Learning**
81+
- *"How to set up a GaussianBeam source"*
82+
- *"Explain how the FDTD method works"*
83+
- *"How can I perform a mode analysis?"*
84+
85+
- **Troubleshooting**
86+
- *"Fix the warning related to 'structures[0]' extending exactly to simulation edges"*
87+
- *"Fix the code to avoid the warning related to Bloch vector"*
88+
- *"Clear the validation error related to ModeSolver plane"*
89+
90+
- **Customization**
91+
- *"Add a mode source at the position (-4, 0, 0) to inject the fundamental TE waveguide mode at 1.55 micrometers"*
92+
- *"Build a mode simulation setup to analyze the dispersion parameters of the first 2 optical modes at the source plane of my FDTD simulation setup"*
93+
- *"Perform a parameter sweep to vary the unit cell period between 0.3 to 0.5 micrometers"*
94+
95+
- **Build From Scratch**
96+
- *"Create a simple FDTD simulation setup to simulate a silicon strip waveguide with dimensions (0.5, 0.22, 10) and refractive index of 3.47"*
97+
- *"I am interested in PIC devices. Build a setup to obtain the modal power at the outputs of a y-junction waveguide. Add s-bends to the output waveguides"*
98+
- *"I want to build a simulation setup to investigate structural color generation"*
99+
100+
- **Analysis**
101+
- *"Plot the field intensity profile obtained from the FieldMonitor at the central frequency"*
102+
- *"Considering my parameter sweep simulation, plot the |E|^2 field profile for all the modes in the largest waveguide"*
103+
- *"Plot the reflectance spectrum of all unit cell period values in the parameter sweep simulation in a single chart"*
104+
105+
## 🖥️ 3D Viewer
106+
107+
### Opening and Using the Viewer
108+
109+
The Tidy3D viewer automatically detects simulation objects in your Python files and notebooks. No code execution required – the viewer parses your `td.Simulation(...)` definitions directly from the source code.
110+
111+
**Access Methods:**
112+
- *Status Bar*: Click "Tidy3D: N simulations" entry
113+
- *Command Palette*: `Tidy3D: Open Tidy3D`
114+
- *Context Menu*: Right-click in Python editor (`.py` files)
115+
116+
**Real-Time Updates:**
117+
- Geometry changes reflect instantly in the viewer
118+
- Material property modifications update colors
119+
- Source and monitor positioning updates automatically
120+
- No need to re-execute cells or restart kernels
121+
122+
**Multi-Simulation Support:**
123+
- Navigate between multiple simulations in the same file
124+
- Quick picker for simulation selection
125+
- Independent viewer instances for comparison
126+
127+
### AI-Controlled Viewer Operations
128+
129+
The agent can control the viewer programmatically through integrated MCP tools:
130+
131+
**Viewer Navigation:**
132+
- `tidy3d_start_viewer(file, symbol)` – Open live 3D viewer
133+
- Automatic camera positioning and scene setup
134+
- Structure visibility toggling and material highlighting
135+
136+
**Screenshot & Documentation:**
137+
- `tidy3d_capture(viewer_id)` – Capture viewer images
138+
- Automatic annotation of sources (green) and monitors (yellow)
139+
- Integration with reports and documentation workflows
140+
141+
**Structure Analysis:**
142+
- `tidy3d_show_structures(viewer_id, visibility)` – Toggle structure visibility
143+
- Layer-by-layer analysis of complex geometries
144+
- Material property visualization and validation
145+
146+
**Simulation Validation:**
147+
- `tidy3d_check_simulation(viewer_id)` – Surface viewer reports
148+
- Physics validation and warning detection
149+
- Automatic re-checking after code modifications
150+
151+
## 📦 Installation & Setup
152+
153+
### Prerequisites & System Requirements
154+
155+
- **Cursor**: Desktop version compatible with VS Code API 1.99.3 or newer
156+
- **Python Support**: Python language features enabled in Cursor for notebooks and Python files
157+
- **Internet Access**: Required for initial downloads and cloud connectivity
158+
- **Operating System**: Windows, macOS, or Linux
159+
160+
### Extension Installation
161+
162+
1. **From Cursor Extensions View**
163+
- Open Cursor and go to Extensions view (`View → Extensions`)
164+
- Search for **"Tidy3D"** by Flexcompute
165+
- Click Install on the official extension
166+
167+
2. **Direct Installation**
168+
- Visit [Open VSX: Tidy3D Extension](https://open-vsx.org/extension/Flexcompute/tidy3d)
169+
- Click "Install" and follow prompts to open in Cursor
170+
171+
3. **Post-Installation**
172+
- Ensure Python support is enabled
173+
- Restart Cursor if prompted
174+
175+
### Tidy3D Account Setup
176+
177+
1. **Create Free Account**
178+
- Visit [tidy3d.simulation.cloud/signup](https://tidy3d.simulation.cloud/signup)
179+
- Complete registration
180+
- Verify your email address
181+
182+
2. **Get API Key**
183+
- Login to [SimCloud](https://tidy3d.simulation.cloud)
184+
- Navigate to Account → API Key tab
185+
- Copy your personal API key
186+
187+
3. **Configure Extension**
188+
- In Cursor: `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup`
189+
- Paste your API key when prompted
190+
- Extension will verify connectivity and setup MCP server
191+
- Modify the API key anytime at `Files → Preferences → VS Code Settings → Extensions → Tidy3D (Cmd/Ctrl+,)`.
192+
193+
### Agent Instruction Files
194+
195+
After running `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup`, the extension creates instruction files under `.cursor/rules/`.
196+
197+
**Cursor automatically loads these rules** - no additional configuration needed. The rules enhance the agent with Tidy3D-specific knowledge and capabilities, including:
198+
- Documentation integration and search
199+
- Simulation validation and troubleshooting
200+
- Viewer control and visualization guidance
201+
202+
### Python Environment Setup (Optional)
203+
204+
While you can view simulations without a local Python setup, notebook execution requires a configured environment. Visit the [Tidy3D Python installation](https://docs.flexcompute.com/projects/tidy3d/en/latest/install.html) for detailed instructions.
205+
206+
**Environment Managers Supported:**
207+
- `uv` (recommended for new projects)
208+
- `conda` / `micromamba`
209+
- `poetry`, `rye`, `hatch`
210+
- `venv` (Python standard library)
211+
212+
**Example with uv:**
213+
```bash
214+
# Install uv from https://docs.astral.sh/uv/getting-started/installation/
215+
uv init my-tidy3d-project
216+
cd my-tidy3d-project
217+
uv add tidy3d jupyter numpy matplotlib
218+
uv sync
219+
```
220+
221+
**Environment Selection in Cursor:**
222+
1. Open Command Palette (`Cmd/Ctrl+Shift+P`)
223+
2. Type "Python: Select Interpreter"
224+
3. Choose your Tidy3D environment
225+
4. Verify with `import tidy3d` in a notebook cell
226+
227+
## 📚 Technical Reference
228+
229+
### Extension Commands & Shortcuts
230+
231+
**Primary Commands:**
232+
- `Tidy3D: Open Tidy3D` (`tidy3d.openViewer`)
233+
- **Access**: Command Palette, Python editor context menu, status bar
234+
- **Function**: Opens 3D viewer for detected simulations
235+
- **Shortcut**: Click status bar "Tidy3D: N simulations"
236+
237+
- `Tidy3D: Run Tidy3D Workspace Setup` (`tidy3d.installWorkspaceSetup`)
238+
- **Access**: Command Palette
239+
- **Function**: Configures API key, MCP server, agent instructions
240+
- **Auto-trigger**: Prompts on first `.py`/`.ipynb` file with Tidy3D code
241+
242+
### Configuration Settings
243+
244+
**Core Settings:**
245+
- `tidy3d.apiKey` (default: empty) – API key for authentication (workspace-scoped)
246+
- `tidy3d.pythonVersion` (default: `3.12`) – Python version for built-in runtime
247+
248+
**Viewer Configuration:**
249+
- `tidy3d.viewer.remoteUrl` (default: `https://tidy3d.simulation.cloud/simulation-viewer`)
250+
- `tidy3d.viewer.tidyVersion` (default: empty) – Override Tidy3D package version
251+
- `tidy3d.screenshotsDir` (default: `reports/.tidy3d-screenshots`) – Screenshot folder
252+
253+
**Advanced Settings:**
254+
- `tidy3d.viewerBridge.port` (default: `0`) – Local bridge port (0 = auto-select)
255+
- `tidy3d.viewerBridge.bindAddress` (default: `127.0.0.1`) – Bind interface
256+
- `tidy3d.mcp.remoteUrl` (advanced) – Base URL for MCP service
257+
- `tidy3d.mcp.runCommand` (advanced) – Custom MCP server launch command
258+
- `tidy3d.mcp.enableViewer` (default: `true`) – Enable viewer tooling in MCP
259+
260+
### MCP Tools & Capabilities
261+
262+
**Documentation Integration:**
263+
- `tidy3d_search_flexcompute_docs(queries, max_results)` – Batch documentation search
264+
- `tidy3d_fetch_flexcompute_doc(url)` – Fetch specific documentation pages
265+
- Real-time API validation and version checking
266+
267+
**Viewer Control:**
268+
- `tidy3d_start_viewer(file, symbol)` – Launch live 3D viewer
269+
- `tidy3d_capture(viewer_id)` – Capture screenshots with annotations
270+
- `tidy3d_show_structures(viewer_id, visibility)` – Toggle structure visibility
271+
- `tidy3d_check_simulation(viewer_id)` – Physics validation and reporting
272+
273+
## 🔧 Troubleshooting & Support
274+
275+
### Common Issues & Solutions
276+
277+
- **The assistant doesn't understand the Tidy3D contexts**: For best performance, explicitly reference the integrated rules: *"Follow the FlexAgent rules in `flexagent.mdc` for all responses. These rules take priority over other instructions."* (See [AI Collaboration Best Practices](#ai-collaboration-best-practices))
278+
- **No simulations detected** – ensure a variable receives `td.Simulation(...)` (or another supported solver type) in the active file.
279+
- **Workspace setup missing** – confirm the Python extension is active and the file uses the python language mode.
280+
- **Slow first run** – wait for initial downloads; you’ll see "Tidy3D Kernel: ready" in the status bar when ready.
281+
- **Viewer cannot connect** – verify your API key and outbound access to `tidy3d.simulation.cloud`.
282+
283+
### Getting Help
284+
285+
**Before Requesting Support:**
286+
1. Try the agent: *"Help me troubleshoot this Tidy3D simulation issue"*
287+
2. [FAQ](https://www.flexcompute.com/tidy3d/learning-center/faq)
288+
3. [Tidy3D Learning Center](https://www.flexcompute.com/tidy3d/learning-center/)
289+
4. [Technical Support](https://www.flexcompute.com/tidy3d/technical-support/)
290+
291+
## 📄 License
292+
293+
**Proprietary** – Flexcompute Inc.
294+
295+
The Tidy3D for Cursor extension is proprietary software developed and maintained by Flexcompute Inc. All rights reserved.

0 commit comments

Comments
 (0)