chore(tidy3d-client): add practical tips to docstrings and consolidate agentic workflow guide (#3780)

Compute-RevId: 5157340979fd74af3dfa66186c2e1a0e421d0322
Flex-RevId: fe5ca928d71c11b04a846a2a89c1a11239dd664d

Author: tylerflex

docs/ai/index.rst

@@ -54,11 +54,42 @@ Watch these demonstration videos to see Tidy3D + AI capabilities in action. Each
 
 For more comprehensive tutorials and the complete video series, visit our `Tidy3D + AI Video Playlist <https://www.youtube.com/playlist?list=PL7kxN4u_N9HHb1QBPXhTlYEMjIt2SY1re>`_.
 
+Using Tidy3D with AI Coding Agents
+-----------------------------------
+
+The FlexAgent MCP works with any MCP-compatible AI coding agent — not just the Tidy3D IDE extensions. To get started:
+
+1. **Set up the MCP** — follow the instructions in `FlexAgent MCP — Standalone MCP Client <flex_agent.html#standalone-mcp-client>`_ for your client (Claude Code, Codex CLI, Cursor, Gemini CLI, etc.).
+2. **Add a bootstrap file** — save the markdown below as ``AGENTS.md`` (or ``CLAUDE.md`` for Claude Code) in your project root directory. This tells the agent how to use the MCP effectively.
+3. **Review the simulation tips** — the `Simulation Tips for AI Agents <simulation_tips.html>`_ page covers workflow patterns, parameter sweeps, inverse design, and common pitfalls.
+
+.. code-block:: markdown
+
+   # Tidy3D Agent Instructions
+
+   ## MCP Setup
+
+   If the Tidy3D MCP server is not already configured, see:
+   https://docs.flexcompute.com/projects/tidy3d/en/latest/ai/flex_agent.html#standalone-mcp-client
+
+   ## Workflow
+
+   Use `search_flexcompute_docs` and `fetch_flexcompute_doc` from the Tidy3D MCP as
+   your primary documentation source throughout the session. Before writing simulation
+   code:
+
+   1. Search for "Simulation Tips for AI Agents" — workflow patterns, pitfalls,
+      and checklists.
+   2. Search for the relevant class docstrings — they contain selection guides,
+      extraction patterns, and practical advice.
+   3. Search for example notebooks related to the device or workflow you are building.
+
 
 .. toctree::
 
     flex_agent
     3d_viewer
+    simulation_tips
     cursor_extension
     vscode_extension
 

docs/ai/simulation_tips.rst

@@ -0,0 +1,201 @@
+Simulation Tips for AI Agents
+=============================
+
+*Workflow patterns and runtime pitfalls for AI-assisted photonics simulation.*
+
+This page collects practical workflow guidance that spans multiple Tidy3D classes and doesn't belong in any single docstring. For API-level guidance (which source to use, how to set up materials, grid resolution), see the class docstrings — they contain selection guides and tips under **Practical Advice** headings.
+
+**Units**: length in micrometers, time in seconds, frequency in Hz.
+
+.. contents:: On this page
+   :local:
+   :depth: 2
+
+
+Documentation Lookups with MCP
+------------------------------
+
+The `FlexAgent MCP <flex_agent.html>`_ server is your primary source for API docs and examples. Always search it before writing simulation code.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Tool
+     - Purpose
+   * - ``search_flexcompute_docs``
+     - Search all Flexcompute docs and examples
+   * - ``fetch_flexcompute_doc``
+     - Fetch a specific documentation page by URL
+
+**Search patterns:**
+
+- Device type: ``"ring resonator tidy3d"``, ``"grating coupler SOI"``
+- API class: ``"ModeSource tidy3d"``, ``"FluxMonitor tidy3d"``
+- Workflow: ``"parameter sweep batch tidy3d"``, ``"adjoint inverse design tidy3d"``
+
+**Decompose the request before searching:**
+
+1. **Device** — what structure? Search ``"{device_type} tidy3d"``
+2. **FOM** — what to measure? Search ``"{monitor_type} tidy3d"``
+3. **Workflow** — single run, sweep, EME, or inverse design?
+
+
+Visualization-First Workflow
+----------------------------
+
+Never run a simulation you haven't visually inspected. Generate plots liberally and inspect them — this is the cheapest way to catch errors.
+
+1. **Plot geometry** — ``sim.plot_eps(x=0)``, ``sim.plot_eps(y=0)``, ``sim.plot_eps(z=0)``. Check: waveguides extend through PML, sources in straight sections, monitors correctly placed, dimensions look right.
+2. **Fix and re-plot** — if anything looks wrong, fix it and plot again. Do not skip to running the simulation.
+3. **After running, inspect results** — are T values physical (at most 1.0)? Do field profiles look reasonable? Any shutoff warnings? Do sweep trends make sense?
+4. **Stop if wrong** — do not continue to optimization or parameter sweeps on top of a broken setup.
+
+
+Parameter Sweeps
+----------------
+
+Use ``web.run_async()`` to run multiple simulations in parallel:
+
+.. code-block:: python
+
+   sims = {f"width_{w:.3f}": make_sim(w) for w in np.linspace(0.4, 0.6, 11)}
+   batch_data = web.run_async(sims)
+   for name, sim_data in batch_data.items():
+       T = sim_data["transmission"].flux.values
+
+
+S-Parameter Extraction
+----------------------
+
+Use the ``ModalComponentModeler`` plugin for multi-port S-parameters:
+
+.. code-block:: python
+
+   from tidy3d.plugins.smatrix import ModalComponentModeler, Port
+
+   import tidy3d.web as web
+
+   ports = [
+       Port(center=(-5, 1, 0), size=(0, 2, 2), mode_spec=td.ModeSpec(), direction="+", name="in1"),
+       Port(center=(5, 1, 0), size=(0, 2, 2), mode_spec=td.ModeSpec(), direction="-", name="out1"),
+   ]
+   modeler = ModalComponentModeler(simulation=sim, ports=ports, freqs=freqs)
+   modeler_data = web.run(modeler)
+   smatrix = modeler_data.smatrix()
+   S21 = smatrix.loc[dict(port_in="in1", mode_index_in=0, port_out="out1", mode_index_out=0)]
+
+
+Resonator Q Factor
+------------------
+
+Three methods:
+
+1. **Spectral fitting** — fit a Lorentzian to the transmission dip near resonance.
+2. **Time-domain decay** — place a ``FieldTimeMonitor`` at the cavity center, fit exponential decay to extract ``Q = omega * tau / 2``.
+3. **ResonanceFinder plugin** — ``from tidy3d.plugins.resonance import ResonanceFinder``.
+
+
+EME Simulations
+---------------
+
+EME (Eigenmode Expansion) is efficient for devices with slowly varying cross-sections — tapers, transitions, periodic structures.
+
+.. code-block:: python
+
+   eme_sim = td.EMESimulation(
+       size=(10, 4, 4),
+       structures=[...], monitors=[...],
+       grid_spec=td.GridSpec.auto(min_steps_per_wvl=20, wavelength=wavelength),
+       axis=0,
+       eme_grid_spec=td.EMEUniformGrid(
+           num_cells=20, mode_spec=td.EMEModeSpec(num_modes=10)
+       ),
+       freqs=[freq0],
+   )
+   eme_data = web.run(eme_sim, task_name="eme_taper")
+
+EME can sweep device length without re-solving modes using ``sweep_spec=td.EMELengthSweep(scale_factors=np.linspace(0.5, 2.0, 20))``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Use EME when...
+     - Use FDTD when...
+   * - Device is long (>20 wavelengths)
+     - Complex 3D scattering
+   * - Cross-section changes slowly
+     - Broadband response needed
+   * - Need length optimization
+     - Time-domain effects matter
+
+
+Inverse Design
+--------------
+
+Tidy3D uses **HIPS autograd**, not JAX. The old ``tidy3d.plugins.adjoint`` plugin has been removed. Regular ``td.Simulation`` and ``web.run()`` are differentiable — no special classes needed.
+
+.. code-block:: python
+
+   import autograd
+   import autograd.numpy as anp
+   # NOT: import jax
+   # NOT: from tidy3d.plugins.adjoint import ...
+
+For detailed patterns (filter and project, beta scheduling, learning rates, gradient sign conventions, traceable components, gotchas), see the autograd README in the Tidy3D source: ``tidy3d/plugins/autograd/README.md``.
+
+
+Pre-Flight Checklist
+--------------------
+
+Run through before every simulation:
+
+1. Waveguides extend through PML — use ``td.inf``
+2. Source/monitor in straight sections — not at bends or junctions
+3. Mode monitor sized 3-4x waveguide width
+4. Grid resolves features — at least 15-20 cells across smallest feature
+5. Transmission is physical — T at most 1.0
+6. ``RunTimeSpec`` or sufficient ``run_time`` — no shutoff warnings
+
+
+Common Failure Modes
+--------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 35 45
+
+   * - Symptom
+     - Likely Cause
+     - Fix
+   * - T = 0
+     - Source/monitor misaligned
+     - Check geometry plot
+   * - T > 1.0
+     - Monitor direction wrong
+     - Check ``direction`` parameter
+   * - NaN
+     - Simulation diverged
+     - Check PML, resolution, dispersive materials
+   * - Shutoff warning
+     - ``run_time`` too short
+     - Use ``RunTimeSpec`` with higher ``quality_factor``
+   * - Wrong wavelength
+     - ``n_eff`` guessed
+     - Use ModeSolver to compute it
+   * - Autograd TypeError
+     - ``float()`` on traced param
+     - Never cast traced params
+   * - 0 gradient
+     - Sim domain depends on params
+     - Only geometry should be traced
+
+
+Coding Discipline
+-----------------
+
+- **Never suppress warnings** — every Tidy3D warning tells you something is wrong. Read it, fix the root cause. Do not use ``warnings.filterwarnings("ignore")``.
+- **Never use try/except to mask failures** — if ``web.run()`` fails, the error tells you what's wrong. Catching and ignoring it means proceeding with garbage.
+- **Never guess physical parameters** — always compute ``n_eff``, grating periods, etc. using ModeSolver or equivalent. This is the number one source of wrong results.
+- **Fix warnings, don't work around them** — search the MCP for the warning text, understand the cause, fix it, verify it's gone.

tidy3d/components/boundary.py

@@ -802,8 +802,15 @@ class PML(AbsorberSpec):
     Note
     ----
 
-        For best results, structures that intersect with the PML or simulation edges should extend extend all the way
-        through. In many such cases, an “infinite” size ``td.inf`` can be used to define the size along that dimension.
+        **Practical Advice**
+
+        For best results, structures that intersect with the PML or simulation edges should extend all the way
+        through using ``td.inf``::
+
+            Structure(geometry=Box(size=(td.inf, width, height)), medium=core)
+
+        Structures that terminate inside PML can cause evanescent fields at the interface to be
+        amplified by the absorber, potentially leading to simulation divergence.
 
     Example
     -------
@@ -1373,6 +1380,16 @@ class BoundarySpec(Tidy3dBaseModel):
         x=False, y=False, z=False)``. This will put :class:`PML` along the dimensions defined as ``True``,
         and set periodic boundaries along the other dimensions.
 
+        **Practical Advice**
+
+        Common boundary configurations:
+
+        - **PML on all sides**: Default for most devices (waveguides, resonators, scatterers).
+        - **Periodic in x/y, PML in z**: Infinite planar arrays (gratings, metasurfaces).
+        - **Bloch in x/y, PML in z**: Oblique incidence on periodic structures.
+
+        Use :meth:`BoundarySpec.pml` as a convenience to set PML along selected dimensions and periodic
+        along the rest.
 
     See Also
     --------

tidy3d/components/grid/grid_spec.py

@@ -894,6 +894,22 @@ def estimated_min_dl(
 class AutoGrid(AbstractAutoGrid):
     """Specification for non-uniform grid along a given dimension.
 
+    Notes
+    -----
+
+        **Practical Advice**
+
+        Recommended ``min_steps_per_wvl`` values:
+
+        - **10** (default): Quick estimates and sanity checks only.
+        - **15-20**: Good accuracy for most simulations. Verify convergence by comparing results
+          at two resolutions.
+        - **Higher**: Only if convergence tests show the result hasn't settled. Can be expensive —
+          use judiciously.
+
+        Ensure that geometric features (thin slabs, narrow gaps) are covered by at least 2 grid cells.
+        For a typical 220 nm SOI waveguide, fewer than 10 cells in z is often sufficient.
+
     Example
     -------
     >>> grid_1d = AutoGrid(min_steps_per_wvl=16, max_scale=1.4)
@@ -2422,6 +2438,17 @@ def _resolve_gaps(
 class GridSpec(Tidy3dBaseModel):
     """Collective grid specification for all three dimensions.
 
+    Notes
+    -----
+
+        **Practical Advice**
+
+        When using :class:`AutoGrid`, the ``wavelength`` parameter determines the scale for automatic meshing.
+        If omitted, it is inferred from sources in the simulation. For simulations without sources or where
+        finer control is needed, set it explicitly::
+
+            grid_spec = GridSpec.auto(min_steps_per_wvl=20, wavelength=1.55)
+
     Example
     -------
     >>> uniform = UniformGrid(dl=0.1)

tidy3d/components/medium.py

@@ -1360,6 +1360,33 @@ class Medium(AbstractMedium):
 
             D(t) = \\epsilon E(t)
 
+        The ``permittivity`` parameter is the relative permittivity (dimensionless). The ``conductivity``
+        parameter has units of S/μm (siemens per micrometer), consistent with Tidy3D's micrometer-based unit
+        system. To convert from standard S/m, divide by 1e6.
+
+        **Practical Advice**
+
+        **Choosing a Material Type**
+
+        - Material is in ``td.material_library``? → Use it directly
+          (e.g. ``td.material_library['cSi']['Li1993_293K']``).
+        - Lossless, wavelength-independent refractive index? → ``td.Medium(permittivity=n**2)``.
+        - Known n and k at a specific frequency? → ``td.Medium.from_nk(n=2.4, k=0.01, freq=freq0)``.
+          Note: when k > 0, the resulting medium has wavelength-independent n but wavelength-dependent k.
+        - You have n,k data vs wavelength? → Use ``FastDispersionFitter`` from
+          ``tidy3d.plugins.dispersion`` to fit a pole-residue model.
+        - Permittivity varies spatially? → Use ``CustomMedium`` with a ``SpatialDataArray``.
+        - Need an analytical dispersive model? → Use ``Sellmeier``, ``Lorentz``, ``Drude``,
+          ``Debye``, or ``PoleResidue`` directly.
+
+        **Common Library Materials (telecom, ~1.55 μm)**
+
+        - Silicon: ``td.material_library['cSi']['Li1993_293K']`` (n ≈ 3.48)
+        - SiO2: ``td.material_library['SiO2']['Palik_Lossless']`` (n ≈ 1.44)
+        - Si3N4: ``td.material_library['Si3N4']['Luke2015PMLStable']`` (n ≈ 2.0)
+        - Gold: ``td.material_library['Au']['JohnsonChristy1972']``
+        - Silver: ``td.material_library['Ag']['JohnsonChristy1972']``
+
     Example
     -------
     >>> dielectric = Medium(permittivity=4.0, name='my_medium')
@@ -1747,6 +1774,35 @@ def _sel_custom_data_inside(self, bounds: Bound) -> Self:
 class CustomMedium(AbstractCustomMedium):
     """:class:`.Medium` with user-supplied permittivity distribution.
 
+    Notes
+    -----
+
+        **Practical Advice**
+
+        Use ``CustomMedium`` when permittivity varies spatially — for example, graded-index
+        (GRIN) lenses or topology-optimized design regions. Define the permittivity on a
+        rectangular grid using ``SpatialDataArray``::
+
+            from tidy3d import SpatialDataArray
+            import numpy as np
+
+            x = np.linspace(-5, 5, 100)
+            y = np.linspace(-5, 5, 100)
+            z = [0]  # 2D variation
+            X, Y = np.meshgrid(x, y, indexing="ij")
+            eps_data = 1 + 3 * np.exp(-(X**2 + Y**2) / 4)
+            eps_data = eps_data[:, :, np.newaxis]
+
+            permittivity = SpatialDataArray(eps_data, coords=dict(x=x, y=y, z=z))
+            custom_medium = CustomMedium(permittivity=permittivity)
+
+        For uniform pixelated grids (e.g. topology optimization), consider the convenience method
+        :meth:`Structure.from_permittivity_array`, which creates a ``Structure`` with a ``CustomMedium``
+        directly from a 3D numpy array and a geometry.
+
+        For wavelength-independent homogeneous materials, use :class:`Medium` instead.
+        For dispersive materials, use :class:`FastDispersionFitter` or an analytical model.
+
     Example
     -------
     >>> Nx, Ny, Nz = 10, 9, 8