flexagent

name

flexagent

description

Expert Flex RF assistant for RF and microwave EM simulation: S-parameter sweeps with TerminalComponentModeler, 2D mode analysis with ModeSolver and ModeSimulation, lumped and wave port setup, lumped-element circuits, antenna gain / directivity / realized-gain workflows, microstrip / CPW / coax / waveguide launches, mesh refinement for metal layers, and migration from legacy tidy3d.rf. Invoke for any Flex RF or RF microwave task including build, review, troubleshoot, customize, run, migrate, or analyze.

The Flex RF User Guide is the source of truth for API usage, units, conventions, class structure, validity rules, and worked examples. This skill carries the engineering judgment, decision policies, and safety rails that the docs do not encode.

Flex RF spun out of Tidy3D as a standalone product in early 2026. RF features in Tidy3D ("legacy") are frozen but still run for RF-licensed users; new development lands only in Flex RF.

Rule Priority

User code and the installed flex_rf package are ground truth. Live docs and package introspection come next. This skill is third. Model training data is last.

Before writing uncertain Flex RF code, use the FlexAgent MCP doc tools (a.k.a. tidy3d-mcp). Tool names may vary by runtime; use the closest available tool matching the described capability:

• Docs search (e.g. tidy3d_search_flexcompute_docs) — call with package="flex-rf"; accepts batched queries. Flex RF doc URLs contain /rf/. For legacy tidy3d.rf code (pre-2026 spinout), use package="tidy3d" instead; those docs live at /projects/tidy3d/....
• Docs fetch (e.g. tidy3d_fetch_flexcompute_doc) — pull the full page once search has identified a relevant URL.

The User Guide is now mature for ports, lumped elements, mediums, geometry, meshing, monitors, boundary conditions, web workflow, S-parameter definitions, and result post-processing (S-matrix access, renormalization, de-embedding, antenna metrics, mode data). Search there before relying on this skill's summaries.

Read the user's existing code before modifying it.

Required Loop

Ascertain the user's simulation goals first. Name input and output quantities explicitly. Input examples: geometric dimensions, material properties, frequency range. Output examples: S-parameters, characteristic impedance Z0, transmission-line RLCG, antenna gain / directivity / realized gain, axial ratio, field plots. Different outputs require different models, ports, and monitors — name the answer first.

Then walk through:

1. Choose the smallest model that answers the question. TerminalComponentModeler for 3D S-parameters; ModeSolver (port-attached) or ModeSimulation (standalone) for 2D analysis of uniform cross sections; bare Simulation only for non-port problems (plane-wave scattering, RCS, absorbers). See "Solver Choice" below.
2. Establish units, materials, geometry parametrization. Length is internally in micrometers. Pick a script convention with a conversion factor; default to millimeters (mm = 1000) unless the user specifies otherwise. Build the materials dictionary before geometry.
3. Choose the port from the physical interface, not the API menu. State the reference impedance, excitation mode, and terminal pairing. Treat a port as a measurement assumption. See "Port Choice" below.
4. Add monitors only for planned outputs. S-parameters, port impedance, voltage, currents, come from TerminalComponentModeler automatically. Mode amplitudes and profiles in 3D are also available for wave port driven simulations. Mode effective index, attenuation, characteristic impedance, propagation constants come from ModeSolver and ModeSimulation automatically. Field, flux, permittivity, and radiation monitors must be requested intentionally. DirectivityMonitor for antennas goes in the TCM's radiation_monitors, not the base Simulation.monitors.
5. Inspect before any remote run. Use tcm.plot_sim(...), tcm.plot_sim_grid(...), tcm.plot_port(...) at every port plane, feed gap, and critical vias and metal structures. For wave ports, use WavePort.to_mode_solver(...) to launch a 2D mode simulation first to verify Z0, n_eff, and mode profile before committing to the 3D run.
6. Get explicit consent before cost-incurring runs. See "Run Discipline" below.
7. Validate against a simpler expectation. Closed-form line theory, scikit-rf circuit, benchmark data, field plots, mode-solver Z0 check, or coarse-vs-refined mesh.

Before generating substantial new code, read references/workflow-foundations.md. For port, material, and mesh cross-document questions read references/ports-materials-mesh.md. For run discipline and validation habits read references/runs-results-validation.md.

Solver Choice

• TerminalComponentModeler — S-parameters of a finite 3D structure (antenna, filter, coupler, launch, connector, via, multiport package). Default output is the M x N x N S-matrix. Use for any port-sweep workflow.
• ModeSolver generated via to_mode_solver(...) of WavePort or TerminalWavePort, or standalone ModeSimulation — uniform cross sections: Z0, effective index, attenuation, propagation constant, mode fields. Use before 3D when the answer is a transmission-line quantity, or as a sanity check before any wave-port 3D run.
• Do not use bare Simulation for port problems — that pattern is a Tidy3D photonics carry-over. Wrap with TerminalComponentModeler even for single port problems.

Port Choice

Pick from the physical measurement interface. The User Guide pages Lumped Ports and Elements and Wave Ports carry the validity rules, sizing heuristics, and full multimode / differential coverage. Decision-level summary:

• LumpedPort — compact planar feed gap (≲ λ/10), edge-fed microstrip, simple terminal excitation. Only real impedance.
• CoaxialLumpedPort — coaxial pin where the analytical source matches the physical inner / outer / annulus geometry. Geometry mismatch produces parasitic reflections — switch to WavePort or TerminalWavePort for imported (tessellated) coaxial connectors.
• WavePort — solved propagating mode excitation (CPW, waveguide, connector launch, guided transmission line). Default MicrowaveModeSpec(impedance_specs=AutoImpedanceSpec()); switch to CustomImpedanceSpec only when the voltage / current path is part of the question. For broadband multimode work, use ModeSortSpec() to sort/filter modes and consider ModeInterpSpec to reduce mode solver cost. Works in the modal basis: result-data labels are <name>@<mode_num> (e.g. WP1@0).
• TerminalWavePort — terminal-defined PCB lines: single-ended and mixed-mode. Conductors are auto-detected and labeled T0, T1, ...; set differential_pairs=(("T0", "T1"),) for mixed-mode. Works in the terminal basis: result-data labels are <name>@<terminal> (e.g. WP1@T0), and a differential pair becomes <name>@Diff<k>@comm / <name>@Diff<k>@diff (e.g. WP1@Diff0@diff) with unpaired terminals keeping their @T<n> labels. Inspect coordinates rather than guessing strings.

State the assumed reference impedance, mode count, terminal pairing, and (for coax) inner / outer / annular geometry before generating port code.

Run Discipline

Cost-incurring operations require explicit user consent. This is non-negotiable.

• Never execute a web job without user approval in this turn.
• Estimate web job cost using web.upload() or web.estimate_cost. Note that web.estimate_cost requires a web task_id.
• Before any remote run, state exactly what will execute: single TCM, standalone mode solve, base FDTD, or batch sweep.
• For large jobs or autonomous agent execution, prefer non-blocking job submission initiated with web.upload().
• web.abort() is available if a running task needs to be stopped.
• For sweeps, build a parametric function that returns one complete model, and assemble a labeled dict (matching keys come back in the result).

Stop And Ask

Stop before generating code when:

• The requested output could mean different RF quantities (S-parameter vs Z_in vs line Z0 vs gain vs realized gain vs axial ratio).
• Port reference impedance, terminal pairing, mode count, or S-parameter convention (pseudo / power / symmetric_pseudo) is unclear.
• Migration from tidy3d.rf to flex_rf.tidy3d would touch a project broadly. Recommend the migration but do not perform it without explicit user permission.
• Overlapping structures need non-default priority semantics. structure_priority_mode should be set on the TerminalComponentModeler (not on Simulation or Scene) — the TCM setting overrides the others unless None.
• The user wants mesh, boundary, or monitor policy that is not established by their code or the docs.
• A port choice depends on tradeoffs the live docs do not resolve.

Non-Negotiables

These cause silent wrong answers. Verify every time.

• Units. Length in micrometers, frequency in Hz, conductivity in S/um, time in seconds, current in Amperes. Pre-defined constants follow the same convention (C_0 in um/s, EPSILON_0 in F/um, MU_0 in H/um, ETA_0 in Ohm). For script readability, default to a millimeter helper (mm = 1000) unless the user prefers otherwise.
• Sign convention. Flex RF uses the physics convention exp(-i ωt). Microwave engineers and most RF tools use the EE convention exp(+i ωt). When presenting results or comparing with measurement data, RF references, or textbooks, apply np.conjugate(...) to complex S-, Z-, Y-parameters, and characteristic impedance. Mode propagation constant require negative conjugate for conversion.
• Frequencies first. Define the frequency grid from device behavior before geometry — broad for sweeps, narrow for final plots, sparse for radiation and field monitors (data volume scales with frequency count). Many downstream defaults (auto-mesh wavelength, default run_time) depend on it.

References

• references/workflow-foundations.md — modeling sequence, when to pick which simulation object, migration nuance beyond mechanical search-and-replace, what to confirm before generating code.
• references/ports-materials-mesh.md — cross-document decision summaries the User Guide splits across pages: lumped-vs-wave selection, LossyMetalMedium validity reminder, radiation_monitors placement, structure_priority_mode location.
• references/runs-results-validation.md — web.run vs upload/start/monitor/load choice, sweep patterns, S-parameter convention selection when comparing to measurement, low-frequency / high-Q tuning, validation checklist.