diff --git a/docs/ai/3DViewer.md b/docs/ai/3DViewer.md new file mode 100644 index 00000000..61c579b5 --- /dev/null +++ b/docs/ai/3DViewer.md @@ -0,0 +1,30 @@ +# 3D Viewer + +*Interactive visualization of Tidy3D simulations directly within your IDE* + +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. + +## Overview + +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. + +Tidy3D 3D Viewer + +## Key Features + +- **Automatic Detection** – Automatically identifies `Simulation` objects in your code and opens the viewer +- **Live Synchronization** – Updates instantly when you modify geometry, materials, sources, or monitors +- **Interactive Navigation** – Rotate, zoom, and pan to explore your simulation from any angle +- **AI-Controlled** – [FlexAgent MCP](FlexAgent.md) can navigate and explain the 3D scene through natural language +- **Editor-Native** – No context switching; visualization happens right where you code +- **Comprehensive Visualization** – View structures, sources, monitors, boundary conditions, and simulation domains + +## Getting Started + +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. + +1. **Create or open a Tidy3D simulation** in your Python script or Jupyter notebook. +2. **Define a `Simulation` object** – The viewer automatically detects it. +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. + +The 3D Viewer is part of the comprehensive Tidy3D + AI ecosystem. For more information, see the [Tidy3D + AI overview](Tidy3DPlusAI.md). \ No newline at end of file diff --git a/docs/ai/CursorExtension.md b/docs/ai/CursorExtension.md new file mode 100644 index 00000000..3624598e --- /dev/null +++ b/docs/ai/CursorExtension.md @@ -0,0 +1,295 @@ +# Tidy3D for Cursor + +*Bringing Tidy3D's electromagnetic simulation platform directly to your code editor* + +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. + +Tidy3D Extension for Cursor + +## 📋 Table of Contents + +- [🚀 Quick Start Guide](#-quick-start-guide) +- [🌟 Highlights](#-highlights) +- [🤖 AI-Powered Assistance](#-ai-powered-assistance) +- [🖥️ 3D Viewer](#️-3d-viewer) +- [📦 Installation & Setup](#-installation--setup) +- [📚 Technical Reference](#-technical-reference) +- [🔧 Troubleshooting & Support](#-troubleshooting--support) +- [📄 License](#-license) + +## 🚀 Quick Start Guide + +*From zero to first simulation in a few minutes* + +- Install [Cursor](https://cursor.com/home?from=agents) +- In the Extensions view panel (`View → Extensions`), search and install the "Tidy3D" extension. +- Create a new folder, download and open the [Tidy3D Quickstart Notebook](https://docs.flexcompute.com/projects/tidy3d/en/latest/_sources/notebooks/StartHere.ipynb) +- Run `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup` +- Paste your Tidy3D API key when prompted. Get a FREE account and API key [here](https://tidy3d.simulation.cloud/signup) +- Ask the assistant to modify the box dimensions: "Change the box dimension to (2, 1, 1)." + +## 🌟 Highlights + +*Unique value within the Tidy3D ecosystem* + +- **AI-Enhanced Workflows** – AI assistance with Tidy3D expertise through integrated FlexAgent MCP server +- **Structured Assistance** – Step-by-step guidance from learning to optimization +- **Trusted Knowledge Base** – Direct integration with [Tidy3D's comprehensive documentation](https://docs.flexcompute.com/projects/tidy3d/en/latest/index.html) +- **Editor-Native Viewer** – No context switching between tools +- **Live Code Synchronization** – See geometry changes instantly as you type +- **AI-Controlled Visualization** – Let the AI assistant navigate and explain the 3D scene + +## 🤖 AI-Powered Assistance + +*Physics-informed assistance through Cursor and FlexAgent MCP integration* + +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. + +### FlexAgent Scenarios + +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. + +- **Learning** - *"Explain me how Tidy3D FDTD updates the fields in this notebook"* +- **Troubleshooting** - *"I want to fix the structure related validation error"* +- **Customization** - *"Replace the FluxMonitor with a ModeMonitor"* +- **Build from Scratch** - *"Create a basic y-junction waveguide simulation setup"* +- **Result Analysis** - *"Plot all the electric field components"* + +### AI Collaboration Best Practices + +- **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."* + +- **Start simple, build incrementally** – Begin with basic simulations and add complexity step by step for easier debugging and understanding. + +- **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?"* + +- **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. + +- **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."* + +- **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. + +- **Use incremental validation** – After each major change, ask the agent to *"validate and explain the simulation changes"* before proceeding to ensure physical accuracy. + +- **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` + +- **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`."* + +### Prompt Examples + +- **Learning** + - *"How to set up a GaussianBeam source"* + - *"Explain how the FDTD method works"* + - *"How can I perform a mode analysis?"* + +- **Troubleshooting** + - *"Fix the warning related to 'structures[0]' extending exactly to simulation edges"* + - *"Fix the code to avoid the warning related to Bloch vector"* + - *"Clear the validation error related to ModeSolver plane"* + +- **Customization** + - *"Add a mode source at the position (-4, 0, 0) to inject the fundamental TE waveguide mode at 1.55 micrometers"* + - *"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"* + - *"Perform a parameter sweep to vary the unit cell period between 0.3 to 0.5 micrometers"* + +- **Build From Scratch** + - *"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"* + - *"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"* + - *"I want to build a simulation setup to investigate structural color generation"* + +- **Analysis** + - *"Plot the field intensity profile obtained from the FieldMonitor at the central frequency"* + - *"Considering my parameter sweep simulation, plot the |E|^2 field profile for all the modes in the largest waveguide"* + - *"Plot the reflectance spectrum of all unit cell period values in the parameter sweep simulation in a single chart"* + +## 🖥️ 3D Viewer + +### Opening and Using the Viewer + +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. + +**Access Methods:** +- *Status Bar*: Click "Tidy3D: N simulations" entry +- *Command Palette*: `Tidy3D: Open Tidy3D` +- *Context Menu*: Right-click in Python editor (`.py` files) + +**Real-Time Updates:** +- Geometry changes reflect instantly in the viewer +- Material property modifications update colors +- Source and monitor positioning updates automatically +- No need to re-execute cells or restart kernels + +**Multi-Simulation Support:** +- Navigate between multiple simulations in the same file +- Quick picker for simulation selection +- Independent viewer instances for comparison + +### AI-Controlled Viewer Operations + +The agent can control the viewer programmatically through integrated MCP tools: + +**Viewer Navigation:** +- `tidy3d_start_viewer(file, symbol)` – Open live 3D viewer +- Automatic camera positioning and scene setup +- Structure visibility toggling and material highlighting + +**Screenshot & Documentation:** +- `tidy3d_capture(viewer_id)` – Capture viewer images +- Automatic annotation of sources (green) and monitors (yellow) +- Integration with reports and documentation workflows + +**Structure Analysis:** +- `tidy3d_show_structures(viewer_id, visibility)` – Toggle structure visibility +- Layer-by-layer analysis of complex geometries +- Material property visualization and validation + +**Simulation Validation:** +- `tidy3d_check_simulation(viewer_id)` – Surface viewer reports +- Physics validation and warning detection +- Automatic re-checking after code modifications + +## 📦 Installation & Setup + +### Prerequisites & System Requirements + +- **Cursor**: Desktop version compatible with VS Code API 1.99.3 or newer +- **Python Support**: Python language features enabled in Cursor for notebooks and Python files +- **Internet Access**: Required for initial downloads and cloud connectivity +- **Operating System**: Windows, macOS, or Linux + +### Extension Installation + +1. **From Cursor Extensions View** + - Open Cursor and go to Extensions view (`View → Extensions`) + - Search for **"Tidy3D"** by Flexcompute + - Click Install on the official extension + +2. **Direct Installation** + - Visit [Open VSX: Tidy3D Extension](https://open-vsx.org/extension/Flexcompute/tidy3d) + - Click "Install" and follow prompts to open in Cursor + +3. **Post-Installation** + - Ensure Python support is enabled + - Restart Cursor if prompted + +### Tidy3D Account Setup + +1. **Create Free Account** + - Visit [tidy3d.simulation.cloud/signup](https://tidy3d.simulation.cloud/signup) + - Complete registration + - Verify your email address + +2. **Get API Key** + - Login to [SimCloud](https://tidy3d.simulation.cloud) + - Navigate to Account → API Key tab + - Copy your personal API key + +3. **Configure Extension** + - In Cursor: `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup` + - Paste your API key when prompted + - Extension will verify connectivity and setup MCP server + - Modify the API key anytime at `Files → Preferences → VS Code Settings → Extensions → Tidy3D (Cmd/Ctrl+,)`. + +### Agent Instruction Files + +After running `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup`, the extension creates instruction files under `.cursor/rules/`. + +**Cursor automatically loads these rules** - no additional configuration needed. The rules enhance the agent with Tidy3D-specific knowledge and capabilities, including: +- Documentation integration and search +- Simulation validation and troubleshooting +- Viewer control and visualization guidance + +### Python Environment Setup (Optional) + +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. + +**Environment Managers Supported:** +- `uv` (recommended for new projects) +- `conda` / `micromamba` +- `poetry`, `rye`, `hatch` +- `venv` (Python standard library) + +**Example with uv:** +```bash +# Install uv from https://docs.astral.sh/uv/getting-started/installation/ +uv init my-tidy3d-project +cd my-tidy3d-project +uv add tidy3d jupyter numpy matplotlib +uv sync +``` + +**Environment Selection in Cursor:** +1. Open Command Palette (`Cmd/Ctrl+Shift+P`) +2. Type "Python: Select Interpreter" +3. Choose your Tidy3D environment +4. Verify with `import tidy3d` in a notebook cell + +## 📚 Technical Reference + +### Extension Commands & Shortcuts + +**Primary Commands:** +- `Tidy3D: Open Tidy3D` (`tidy3d.openViewer`) + - **Access**: Command Palette, Python editor context menu, status bar + - **Function**: Opens 3D viewer for detected simulations + - **Shortcut**: Click status bar "Tidy3D: N simulations" + +- `Tidy3D: Run Tidy3D Workspace Setup` (`tidy3d.installWorkspaceSetup`) + - **Access**: Command Palette + - **Function**: Configures API key, MCP server, agent instructions + - **Auto-trigger**: Prompts on first `.py`/`.ipynb` file with Tidy3D code + +### Configuration Settings + +**Core Settings:** +- `tidy3d.apiKey` (default: empty) – API key for authentication (workspace-scoped) +- `tidy3d.pythonVersion` (default: `3.12`) – Python version for built-in runtime + +**Viewer Configuration:** +- `tidy3d.viewer.remoteUrl` (default: `https://tidy3d.simulation.cloud/simulation-viewer`) +- `tidy3d.viewer.tidyVersion` (default: empty) – Override Tidy3D package version +- `tidy3d.screenshotsDir` (default: `reports/.tidy3d-screenshots`) – Screenshot folder + +**Advanced Settings:** +- `tidy3d.viewerBridge.port` (default: `0`) – Local bridge port (0 = auto-select) +- `tidy3d.viewerBridge.bindAddress` (default: `127.0.0.1`) – Bind interface +- `tidy3d.mcp.remoteUrl` (advanced) – Base URL for MCP service +- `tidy3d.mcp.runCommand` (advanced) – Custom MCP server launch command +- `tidy3d.mcp.enableViewer` (default: `true`) – Enable viewer tooling in MCP + +### MCP Tools & Capabilities + +**Documentation Integration:** +- `tidy3d_search_flexcompute_docs(queries, max_results)` – Batch documentation search +- `tidy3d_fetch_flexcompute_doc(url)` – Fetch specific documentation pages +- Real-time API validation and version checking + +**Viewer Control:** +- `tidy3d_start_viewer(file, symbol)` – Launch live 3D viewer +- `tidy3d_capture(viewer_id)` – Capture screenshots with annotations +- `tidy3d_show_structures(viewer_id, visibility)` – Toggle structure visibility +- `tidy3d_check_simulation(viewer_id)` – Physics validation and reporting + +## 🔧 Troubleshooting & Support + +### Common Issues & Solutions + +- **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)) +- **No simulations detected** – ensure a variable receives `td.Simulation(...)` (or another supported solver type) in the active file. +- **Workspace setup missing** – confirm the Python extension is active and the file uses the python language mode. +- **Slow first run** – wait for initial downloads; you’ll see "Tidy3D Kernel: ready" in the status bar when ready. +- **Viewer cannot connect** – verify your API key and outbound access to `tidy3d.simulation.cloud`. + +### Getting Help + +**Before Requesting Support:** +1. Try the agent: *"Help me troubleshoot this Tidy3D simulation issue"* +2. [FAQ](https://www.flexcompute.com/tidy3d/learning-center/faq) +3. [Tidy3D Learning Center](https://www.flexcompute.com/tidy3d/learning-center/) +4. [Technical Support](https://www.flexcompute.com/tidy3d/technical-support/) + +## 📄 License + +**Proprietary** – Flexcompute Inc. + +The Tidy3D for Cursor extension is proprietary software developed and maintained by Flexcompute Inc. All rights reserved. \ No newline at end of file diff --git a/docs/ai/FlexAgent.md b/docs/ai/FlexAgent.md new file mode 100644 index 00000000..603e5734 --- /dev/null +++ b/docs/ai/FlexAgent.md @@ -0,0 +1,207 @@ +# FlexAgent MCP + +*AI-powered simulation assistance for Tidy3D through Model Context Protocol* + +FlexAgent MCP is a Model Context Protocol (MCP) server that brings physics-aware AI assistance to Tidy3D workflows. Unlike generic coding assistants, FlexAgent understands electromagnetic simulation concepts, Tidy3D's API, and can interact with the [3D Viewer](3DViewer.md) to provide comprehensive, context-aware support for your simulation projects. + +📹 **Watch the demo**: [FlexAgent MCP Introduction Video](https://youtu.be/KU6QP-gqUGA?list=PL7kxN4u_N9HHb1QBPXhTlYEMjIt2SY1re) + +## Overview + +FlexAgent enables natural language interaction with Tidy3D simulations across multiple platforms, including [Cursor](CursorExtension.md), [VS Code](VSCodeExtension.md), and other MCP-compatible environments. Through structured workflows that leverage Tidy3D's trusted documentation, FlexAgent transforms your AI assistant into a knowledgeable simulation partner capable of: + +- **Learning** – Understanding Tidy3D concepts and workflows: *"Explain how Tidy3D FDTD updates the fields in this notebook"* +- **Troubleshooting** – Diagnosing and resolving simulation issues: *"I want to fix the structure-related validation error"* +- **Customization** – Modifying existing simulations: *"Replace the FluxMonitor with a ModeMonitor"* +- **Build from Scratch** – Creating new simulation setups: *"Create a y-junction waveguide simulation setup"* +- **Result Analysis** – Interpreting and visualizing simulation data: *"Plot all the electric field components"* + +For a comprehensive introduction to the Tidy3D + AI ecosystem, see the [Tidy3D + AI overview](Tidy3DPlusAI.md). + +## Installation + +FlexAgent MCP can be installed in two ways: as part of the Tidy3D IDE extensions (recommended) or as a standalone MCP server for use with other MCP-compatible clients. + +### Tidy3D Extensions + +**Recommended for most users**: FlexAgent MCP is seamlessly integrated within the Tidy3D extensions for Cursor and Visual Studio Code. When you install and configure these extensions, FlexAgent is automatically set up and ready to use. + +For detailed installation and setup instructions, see: +- [Tidy3D for Cursor](CursorExtension.md) – Complete guide for Cursor users +- [Tidy3D for VS Code](VSCodeExtension.md) – Complete guide for Visual Studio Code users + +The extensions handle all FlexAgent configuration automatically, including API key management, MCP server deployment, and integration with the [3D Viewer](3DViewer.md). + +### Standalone MCP Client + +For users who want to use FlexAgent with other MCP-compatible clients (without the full Tidy3D extension), you can install the `tidy3d-mcp` server directly. + +**Prerequisites:** +- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager installed +- A Tidy3D API key ([get one free here](https://tidy3d.simulation.cloud/signup)) + +**Register the server with your MCP client** – Use the configuration block below that matches your MCP client: + +
+Codex CLI / IDE + +```bash +codex mcp add tidy3d -- uvx tidy3d-mcp --api-key "YOUR_TIDY3D_API_KEY" +``` + +
+ +
+Claude CLI / Desktop / Code + +```bash +claude mcp add tidy3d -- uvx tidy3d-mcp --api-key "YOUR_TIDY3D_API_KEY" +``` + +
+ +
+Gemini CLI + +Create or edit `.gemini/settings.json` (project) or `~/.gemini/settings.json` (global): + +```json +{ + "mcpServers": { + "tidy3d": { + "command": "uvx", + "args": ["tidy3d-mcp", "--api-key", "YOUR_TIDY3D_API_KEY"] + } + } +} +``` + +
+ +
+Cursor CLI / IDE + +Cursor reuses the same schema across the editor and `cursor-agent`. Configure `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (global) and then run `cursor-agent mcp list` to verify: + +```json +{ + "mcpServers": { + "tidy3d": { + "command": "uvx", + "args": ["tidy3d-mcp", "--api-key", "YOUR_TIDY3D_API_KEY"] + } + } +} +``` + +
+ + +## AI Collaboration Best Practices + +To get the most out of FlexAgent, follow these proven strategies for effective AI-assisted simulation development: + +### Leverage FlexAgent Rules + +**For optimal results**, explicitly reference the integrated FlexAgent rules in your prompts. When using the Tidy3D extensions, these rules are automatically loaded: +- **Cursor**: Rules are in `.cursor/rules/` (automatically loaded) +- **VS Code**: Rules are in `.github/instructions/` (enable in Copilot settings) + +Example: *"Follow the FlexAgent rules in `flexagent.mdc` for all responses. These rules take priority over other instructions."* + +### Start Simple, Build Incrementally + +Begin with basic simulations and gradually add complexity. This approach makes debugging easier and helps you understand each component before moving to the next level. Ask FlexAgent to explain concepts as you build. + +### Provide Rich Context + +The more specific your prompts, the better FlexAgent's assistance. Instead of generic requests like "help with mode analysis," provide detailed context: + +**Better prompt**: *"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?"* + +### Use the Viewer for Real-Time Iteration + +Keep the [3D Viewer](3DViewer.md) 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. This creates a powerful feedback loop for rapid iteration. + +### Be Specific When Troubleshooting + +Instead of vague requests like "fix all errors," provide targeted information: +- *"Fix the boundary condition warning for structure[0]"* +- *"Resolve the mesh refinement issue near the waveguide core"* +- *"Clear the validation error related to ModeSolver plane"* + +### Understand Before Proceeding + +Take time to comprehend the generated code and simulation setup. Ask FlexAgent to explain concepts you're unfamiliar with before building upon them. This ensures you maintain control and understanding of your simulation. + +### Use Incremental Validation + +After each major change, ask FlexAgent to *"validate and explain the simulation changes"* before proceeding. This helps ensure physical accuracy and catches issues early. + +### Document Your Simulation Intent + +Add comments explaining the physics you're trying to model. This helps both you and FlexAgent understand the simulation goals: + +```python +# Modeling evanescent coupling between two strip waveguides separated by 200 nm +``` + +### Specify Your Python Environment + +When working with multiple Python environments, explicitly tell FlexAgent which one to use: + +*"Run this code using my `tidy3d_latest` conda environment located at `/home/user/miniconda3/envs/tidy3d_latest`."* + +## Prompt Examples + +The following examples demonstrate effective ways to interact with FlexAgent across different use cases. These prompts leverage FlexAgent's understanding of Tidy3D workflows and its ability to access documentation and control the [3D Viewer](3DViewer.md). + +### Learning + +Use FlexAgent to understand Tidy3D concepts, methods, and best practices: + +- *"How to set up a GaussianBeam source"* +- *"Explain how the FDTD method works"* +- *"How can I perform a mode analysis?"* +- *"What's the difference between a FluxMonitor and a ModeMonitor?"* +- *"Explain the relationship between mesh refinement and simulation accuracy"* + +### Troubleshooting + +Get help diagnosing and fixing simulation issues: + +- *"Fix the warning related to 'structures[0]' extending exactly to simulation edges"* +- *"Fix the code to avoid the warning related to Bloch vector"* +- *"Clear the validation error related to ModeSolver plane"* +- *"Why is my simulation diverging, and how do I fix it?"* +- *"Help me resolve the boundary condition warning for my periodic structure"* + +### Customization + +Modify existing simulations to explore different configurations: + +- *"Add a mode source at the position (-4, 0, 0) to inject the fundamental TE waveguide mode at 1.55 micrometers"* +- *"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"* +- *"Perform a parameter sweep to vary the unit cell period between 0.3 to 0.5 micrometers"* +- *"Replace the FluxMonitor with a ModeMonitor and update the analysis code"* +- *"Change the simulation boundary conditions from PML to periodic in the x-direction"* + +### Build From Scratch + +Create complete simulation setups from natural language descriptions: + +- *"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"* +- *"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"* +- *"I want to build a simulation setup to investigate structural color generation"* +- *"Create a ring resonator simulation with a 5 μm radius and 220 nm waveguide thickness"* +- *"Build a metasurface simulation for beam steering at 1.55 μm wavelength"* + +### Analysis + +Interpret results and create visualizations: + +- *"Plot the field intensity profile obtained from the FieldMonitor at the central frequency"* +- *"Considering my parameter sweep simulation, plot the |E|² field profile for all the modes in the largest waveguide"* +- *"Plot the reflectance spectrum of all unit cell period values in the parameter sweep simulation in a single chart"* +- *"Analyze the transmission spectrum and identify the resonance frequencies"* +- *"Create a 2D plot showing the electric field distribution in the x-y plane at z=0"* diff --git a/docs/ai/Tidy3DPlusAI.md b/docs/ai/Tidy3DPlusAI.md new file mode 100644 index 00000000..251a91f8 --- /dev/null +++ b/docs/ai/Tidy3DPlusAI.md @@ -0,0 +1,45 @@ +# Tidy3D + AI + +*Ushering in a new era of AI-assisted photonic design* + +We are pleased to announce the release of the new Tidy3D Extension, which enables seamless building, visualization, and iteration on electromagnetic simulations within Visual Studio Code or Cursor. The extension automatically detects simulations in Tidy3D Python scripts and notebooks, opens an interactive 3D viewer alongside your code, and enables the IDE AI assistant to leverage the integrated FlexAgent MCP server for an intelligent, physics‑aware assistance experience. + +Tidy3D Extension + +## Key Components + +### FlexAgent MCP + +[FlexAgent MCP](FlexAgent.md) is a physics-aware AI assistant that understands Tidy3D workflows and electromagnetic simulation concepts. Unlike generic coding assistants, FlexAgent provides specialized knowledge and can control the 3D Viewer to provide comprehensive, context-aware support. + +**Key Capabilities:** +- **Natural Language Interaction** – Build, modify, and analyze simulations using plain English +- **Physics-Aware** – Understands electromagnetic simulation concepts and Tidy3D's API +- **Learning & Troubleshooting** – Get explanations and fix simulation issues +- **Code Generation** – Create complete simulation setups from scratch +- **Result Analysis** – Interpret and visualize simulation data + +### 3D Viewer + +The [3D Viewer](3DViewer.md) provides interactive, real-time visualization of Tidy3D simulations directly within your IDE. It automatically detects simulation objects in your code and opens alongside your editor, providing immediate visual feedback as you develop. + +**Key Features:** +- **Automatic Detection** – Identifies `Simulation` objects and opens automatically +- **Live Synchronization** – Updates instantly when you modify code +- **Interactive Navigation** – Rotate, zoom, and pan to explore simulations +- **AI-Controlled** – FlexAgent can navigate and explain the 3D scene +- **Comprehensive Visualization** – View structures, sources, monitors, and boundaries + +## Video Demos + +Watch these demonstration videos to see Tidy3D + AI capabilities in action. Each video showcases specific workflows and features that highlight how FlexAgent MCP and the 3D Viewer can accelerate your photonic design process. + +- **[Mode Analysis](https://youtu.be/dQMGgQr_6KE?si=fUXlMEjk2RHCEWjF)** – Learn how to use AI assistance to perform mode analysis and understand waveguide modes + +- **[Data Analysis](https://youtu.be/CLFoePrHcjM?si=j7izF3RF1rV7HpO_)** – See how FlexAgent helps analyze simulation results and extract meaningful insights from your data + +- **[Convergence Test](https://youtu.be/fhfi4U2HKbo?si=rLo9Fgg-Zv-pJUKV)** – Discover how to set up and run convergence tests with AI guidance to ensure simulation accuracy + +- **[Cost Estimation](https://youtu.be/ZuZVu7yA6DQ?si=YNWn9RB3Thmph62a)** – Understand how to estimate simulation costs and optimize your computational resources with AI assistance + +For more comprehensive tutorials and the complete video series, visit our [Tidy3D + AI Video Playlist](https://www.youtube.com/playlist?list=PL7kxN4u_N9HHb1QBPXhTlYEMjIt2SY1re). diff --git a/docs/ai/VSCodeExtension.md b/docs/ai/VSCodeExtension.md new file mode 100644 index 00000000..985731e1 --- /dev/null +++ b/docs/ai/VSCodeExtension.md @@ -0,0 +1,296 @@ +# Tidy3D for VS Code + +*Bringing Tidy3D's electromagnetic simulation platform directly to your code editor* + +Build, visualize, and iterate on electromagnetic simulations seamlessly within Visual Studio Code. 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 GitHub Copilot to leverage the integrated FlexAgent MCP server for an intelligent, context‑aware assistance experience. + +Tidy3D Extension for VS Code + +## 📋 Table of Contents + +- [🚀 Quick Start Guide](#-quick-start-guide) +- [🌟 Highlights](#-highlights) +- [🤖 AI-Powered Assistance](#-ai-powered-assistance) +- [🖥️ 3D Viewer](#️-3d-viewer) +- [📦 Installation & Setup](#-installation--setup) +- [📚 Technical Reference](#-technical-reference) +- [🔧 Troubleshooting & Support](#-troubleshooting--support) +- [📄 License](#-license) + +## 🚀 Quick Start Guide + +*From zero to first simulation in a few minutes* + +- Install [Visual Studio Code](https://code.visualstudio.com/) and set up [GitHub Copilot](https://code.visualstudio.com/docs/copilot/setup). +- In the Extensions view panel (`View → Extensions`), search and install the "Tidy3D" extension. +- Create a new folder, download and open the [Tidy3D Quickstart Notebook](https://docs.flexcompute.com/projects/tidy3d/en/latest/_sources/notebooks/StartHere.ipynb) +- Run `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup` +- Paste your Tidy3D API key when prompted. Get a FREE account and API key [here](https://tidy3d.simulation.cloud/signup) +- Ask GitHub Copilot to modify the box dimensions: "Change the box dimension to (2, 1, 1)." + +## 🌟 Highlights + +*Unique value within the Tidy3D ecosystem* + +- **AI-Enhanced Workflows** – AI assistance with Tidy3D expertise through integrated FlexAgent MCP server +- **Structured Assistance** – Step-by-step guidance from learning to optimization +- **Trusted Knowledge Base** – Direct integration with [Tidy3D's comprehensive documentation](https://docs.flexcompute.com/projects/tidy3d/en/latest/index.html) +- **Editor-Native Viewer** – No context switching between tools +- **Live Code Synchronization** – See geometry changes instantly as you type +- **AI-Controlled Visualization** – Let the AI assistant navigate and explain the 3D scene + +## 🤖 AI-Powered Assistance + +*Physics-informed assistance through GitHub Copilot and FlexAgent MCP integration* + +The extension integrates with VS Code GitHub Copilot to provide physics-aware assistance for electromagnetic simulations. Unlike generic coding assistants, this integration understands Tidy3D workflows and can control the 3D viewer. + +### FlexAgent Scenarios + +The command `Tidy3D: Run Tidy3D Workspace Setup` deploys FlexAgent rules under `.github/instructions/` that transform the AI assistant into a physics-aware simulation partner. There are structured workflows relaying on Tidy3D's trusted documentation. + +- **Learning** - *"Explain me how Tidy3D FDTD updates the fields in this notebook"* +- **Troubleshooting** - *"I want to fix the structure related validation error"* +- **Customization** - *"Replace the FluxMonitor with a ModeMonitor"* +- **Build from Scratch** - *"Create a basic y-junction waveguide simulation setup"* +- **Result Analysis** - *"Plot all the electric field components"* + +### AI Collaboration Best Practices + +- **Leverage FlexAgent rules for optimal results** – For best performance, explicitly reference the integrated rules: *"Follow the rules in `copilot-instructions.md` for all responses. These rules take priority over other instructions."* + +- **Start simple, build incrementally** – Begin with basic simulations and add complexity step by step for easier debugging and understanding. + +- **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?"* + +- **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. + +- **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."* + +- **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. + +- **Use incremental validation** – After each major change, ask the agent to *"validate and explain the simulation changes"* before proceeding to ensure physical accuracy. + +- **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` + +- **Specify your Python environment** – Tell FlexAgent which environment to use: *"Run this code using my `tidy3d_latest` conda environment located at `/home/user/miniconda3/envs/tidy3d_latest`."* + +### Prompt Examples + +- **Learning** + - *"How to set up a GaussianBeam source"* + - *"Explain how the FDTD method works"* + - *"How can I perform a mode analysis?"* + +- **Troubleshooting** + - *"Fix the warning related to 'structures[0]' extending exactly to simulation edges"* + - *"Fix the code to avoid the warning related to Bloch vector"* + - *"Clear the validation error related to ModeSolver plane"* + +- **Customization** + - *"Add a mode source at the position (-4, 0, 0) to inject the fundamental TE waveguide mode at 1.55 micrometers"* + - *"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"* + - *"Perform a parameter sweep to vary the unit cell period between 0.3 to 0.5 micrometers"* + +- **Build From Scratch** + - *"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"* + - *"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"* + - *"I want to build a simulation setup to investigate structural color generation"* + +- **Analysis** + - *"Plot the field intensity profile obtained from the FieldMonitor at the central frequency"* + - *"Considering my parameter sweep simulation, plot the |E|^2 field profile for all the modes in the largest waveguide"* + - *"Plot the reflectance spectrum of all unit cell period values in the parameter sweep simulation in a single chart"* + +## 🖥️ 3D Viewer + +### Opening and Using the Viewer + +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. + +**Access Methods:** +- *Status Bar*: Click "Tidy3D: N simulations" entry +- *Command Palette*: `Tidy3D: Open Tidy3D` +- *Context Menu*: Right-click in Python editor (`.py` files) + +**Real-Time Updates:** +- Geometry changes reflect instantly in the viewer +- Material property modifications update colors +- Source and monitor positioning updates automatically +- No need to re-execute cells or restart kernels + +**Multi-Simulation Support:** +- Navigate between multiple simulations in the same file +- Quick picker for simulation selection +- Independent viewer instances for comparison + +### AI-Controlled Viewer Operations + +Copilot can control the viewer programmatically through integrated MCP tools: + +**Viewer Navigation:** +- `tidy3d_start_viewer(file, symbol)` – Open live 3D viewer +- Automatic camera positioning and scene setup +- Structure visibility toggling and material highlighting + +**Screenshot & Documentation:** +- `tidy3d_capture(viewer_id)` – Capture viewer images +- Automatic annotation of sources (green) and monitors (yellow) +- Integration with reports and documentation workflows + +**Structure Analysis:** +- `tidy3d_show_structures(viewer_id, visibility)` – Toggle structure visibility +- Layer-by-layer analysis of complex geometries +- Material property visualization and validation + +**Simulation Validation:** +- `tidy3d_check_simulation(viewer_id)` – Surface viewer reports +- Physics validation and warning detection +- Automatic re-checking after code modifications + +## 📦 Installation & Setup + +### Prerequisites & System Requirements + +- **Visual Studio Code**: Version 1.99.3 or newer +- **Python Extension**: [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) enabled for notebooks and Python files +- **Internet Access**: Required for initial downloads and cloud connectivity +- **Operating System**: Windows, macOS, or Linux + +### Extension Installation + +1. **From VS Code Extensions View** + - Open Visual Studio Code and go to Extensions view (`View → Extensions`) + - Search for **"Tidy3D"** by Flexcompute + - Click Install on the official extension + +2. **Direct Installation** + - Visit [Visual Studio Marketplace: Tidy3D Extension](https://marketplace.visualstudio.com/items?itemName=Flexcompute.tidy3d) + - Click "Install" and follow prompts to open in VS Code + +3. **Post-Installation** + - Ensure Python extension is enabled + - Restart VS Code if prompted + +### Tidy3D Account Setup + +1. **Create Free Account** + - Visit [tidy3d.simulation.cloud/signup](https://tidy3d.simulation.cloud/signup) + - Complete registration + - Verify your email address + +2. **Get API Key** + - Login to [SimCloud](https://tidy3d.simulation.cloud) + - Navigate to Account → API Key tab + - Copy your personal API key + +3. **Configure Extension** + - In VS Code: `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup` + - Paste your API key when prompted + - Extension will verify connectivity and setup MCP server + - Modify the API key anytime at `Files → Preferences → Settings → Extensions → Tidy3D (Cmd/Ctrl+,)`. + +### Enable Copilot Chat Instructions + +After running `Cmd/Ctrl+Shift+P → Tidy3D: Run Tidy3D Workspace Setup`, the extension creates instruction files under `.github/instructions/`. + +**Enable Instructions in Copilot:** +1. Open VS Code Settings (`Cmd/Ctrl+,`) +2. Search for "copilot chat instructions" +3. Enable: `github.copilot.chat.codeGeneration.useInstructionFiles` +4. Verify by sending a chat message and expanding "References" to see loaded instruction files + +### Python Environment Setup (Optional) + +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. + +**Environment Managers Supported:** +- `uv` (recommended for new projects) +- `conda` / `micromamba` +- `poetry`, `rye`, `hatch` +- `venv` (Python standard library) + +**Example with uv:** +```bash +# Install uv from https://docs.astral.sh/uv/getting-started/installation/ +uv init my-tidy3d-project +cd my-tidy3d-project +uv add tidy3d jupyter numpy matplotlib +uv sync +``` + +**Environment Selection in VS Code:** +1. Open Command Palette (`Cmd/Ctrl+Shift+P`) +2. Type "Python: Select Interpreter" +3. Choose your Tidy3D environment +4. Verify with `import tidy3d` in a notebook cell + +## 📚 Technical Reference + +### Extension Commands & Shortcuts + +**Primary Commands:** +- `Tidy3D: Open Tidy3D` (`tidy3d.openViewer`) + - **Access**: Command Palette, Python editor context menu, status bar + - **Function**: Opens 3D viewer for detected simulations + - **Shortcut**: Click status bar "Tidy3D: N simulations" + +- `Tidy3D: Run Tidy3D Workspace Setup` (`tidy3d.installWorkspaceSetup`) + - **Access**: Command Palette + - **Function**: Configures API key, MCP server, Copilot instructions + - **Auto-trigger**: Prompts on first `.py`/`.ipynb` file with Tidy3D code + +### Configuration Settings + +**Core Settings:** +- `tidy3d.apiKey` (default: empty) – API key for authentication (workspace-scoped) +- `tidy3d.pythonVersion` (default: `3.12`) – Python version for built-in runtime + +**Viewer Configuration:** +- `tidy3d.viewer.remoteUrl` (default: `https://tidy3d.simulation.cloud/simulation-viewer`) +- `tidy3d.viewer.tidyVersion` (default: empty) – Override Tidy3D package version +- `tidy3d.screenshotsDir` (default: `reports/.tidy3d-screenshots`) – Screenshot folder + +**Advanced Settings:** +- `tidy3d.viewerBridge.port` (default: `0`) – Local bridge port (0 = auto-select) +- `tidy3d.viewerBridge.bindAddress` (default: `127.0.0.1`) – Bind interface +- `tidy3d.mcp.remoteUrl` (advanced) – Base URL for MCP service +- `tidy3d.mcp.runCommand` (advanced) – Custom MCP server launch command +- `tidy3d.mcp.enableViewer` (default: `true`) – Enable viewer tooling in MCP + +### MCP Tools & Capabilities + +**Documentation Integration:** +- `tidy3d_search_flexcompute_docs(queries, max_results)` – Batch documentation search +- `tidy3d_fetch_flexcompute_doc(url)` – Fetch specific documentation pages +- Real-time API validation and version checking + +**Viewer Control:** +- `tidy3d_start_viewer(file, symbol)` – Launch live 3D viewer +- `tidy3d_capture(viewer_id)` – Capture screenshots with annotations +- `tidy3d_show_structures(viewer_id, visibility)` – Toggle structure visibility +- `tidy3d_check_simulation(viewer_id)` – Physics validation and reporting + +## 🔧 Troubleshooting & Support + +### Common Issues & Solutions + +- **The assistant doesn't understand the Tidy3D contexts**: For best performance, explicitly reference the integrated rules: *"Follow the FlexAgent rules in `copilot-instructions.md` for all responses. These rules take priority over other instructions."* (See [AI Collaboration Best Practices](#ai-collaboration-best-practices)) +- **No simulations detected** – ensure a variable receives `td.Simulation(...)` (or another supported solver type) in the active file. +- **Workspace setup missing** – confirm the Python extension is active and the file uses the python language mode. +- **Slow first run** – wait for initial downloads; you’ll see "Tidy3D Kernel: ready" in the status bar when ready. +- **Viewer cannot connect** – verify your API key and outbound access to `tidy3d.simulation.cloud`. + +### Getting Help + +**Before Requesting Support:** +1. Try the assistant: *"Help me troubleshoot this Tidy3D simulation issue"* +2. [FAQ](https://www.flexcompute.com/tidy3d/learning-center/faq) +3. [Tidy3D Learning Center](https://www.flexcompute.com/tidy3d/learning-center/) +4. [Technical Support](https://www.flexcompute.com/tidy3d/technical-support/) + +## 📄 License + +**Proprietary** – Flexcompute Inc. + +The Tidy3D for VS Code extension is proprietary software developed and maintained by Flexcompute Inc. All rights reserved. \ No newline at end of file diff --git a/docs/ai/extension_cursor.png b/docs/ai/extension_cursor.png new file mode 100644 index 00000000..03fde7c7 Binary files /dev/null and b/docs/ai/extension_cursor.png differ diff --git a/docs/ai/extension_vscode.png b/docs/ai/extension_vscode.png new file mode 100644 index 00000000..39c7e2d3 Binary files /dev/null and b/docs/ai/extension_vscode.png differ diff --git a/docs/ai/index.rst b/docs/ai/index.rst new file mode 100644 index 00000000..78ed7bb0 --- /dev/null +++ b/docs/ai/index.rst @@ -0,0 +1,15 @@ +Tidy3D + AI +----------- + +This section covers AI-powered tools and extensions that enhance the Tidy3D workflow, including IDE extensions, AI agents, and interactive visualization tools. + +.. toctree:: + :class: example-notebook-toc + :maxdepth: 1 + + Tidy3DPlusAI + FlexAgent + 3DViewer + CursorExtension + VSCodeExtension + diff --git a/docs/ai/tidy3d_extension.png b/docs/ai/tidy3d_extension.png new file mode 100644 index 00000000..68652077 Binary files /dev/null and b/docs/ai/tidy3d_extension.png differ diff --git a/docs/ai/viewer.png b/docs/ai/viewer.png new file mode 100644 index 00000000..e15fb24f Binary files /dev/null and b/docs/ai/viewer.png differ diff --git a/docs/index.rst b/docs/index.rst index 4642f59a..d2918cd3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,4 +7,5 @@ Example Library |:books:| basics/index features/index case_studies/index + ai/index