The contexts package#

Summary#

device

DEVICE finite-element IDE guideline topics.

fdtd

FDTD-specific guideline topics.

general

Product-agnostic Lumerical workflow guidance (workflow topic).

geometry

Dictionary-based addX syntax shared by FDTD, MODE, and DEVICE.

interconnect

INTERCONNECT-specific guideline topics.

materials

Material-selection guidance shared by FDTD and MODE (materials topic).

mode

MODE-specific guideline topics.

pic

Shared photonic-integrated-circuit guidance for optical solvers.

s_parameter_sweep

S-parameter matrix sweep guidance shared by FDTD and MODE (s_parameter_sweep).

sweeps

Product-agnostic sweep guidance (sweeps and nested_sweeps topics).

get_guidelines_for_device_materials

Material-library creation and database discovery for DEVICE finite-element solvers.

get_guidelines_for_device_simulation_region

Simulation-region setup shared by HEAT, CHARGE, FEEM, DGTD, and peers.

get_guidelines_for_device_workflow

Finite-element IDE workflow shared by HEAT, CHARGE, FEEM, and DGTD.

get_guidelines_for_fdtd_boundary_conditions

FDTD boundary conditions: PML profiles, symmetric/anti-symmetric, periodic, Bloch.

get_guidelines_for_fdtd_far_field_and_grating

FDTD far-field and grating projection: farfield2d/3d, farfieldexact, NA filtering.

get_guidelines_for_fdtd_mesh_and_convergence

FDTD mesh accuracy, conformal mesh, mesh overrides, auto-shutoff, divergence.

get_guidelines_for_fdtd_monitors_and_field_extraction

FDTD monitor catalog + field-extraction patterns (override-global, reduce-before-print).

get_guidelines_for_fdtd_run_and_results

FDTD run + results: solver args, run-once + switchtolayout, datasets, getresult.

get_guidelines_for_fdtd_source_types

FDTD source-type catalog: plane wave, Gaussian, dipole, TFSF, import, BFAST.

get_guidelines_for_fdtd_sources_monitors

Global source/monitor settings and the port-vs-mode-source decision.

get_guidelines_for_fdtd_workflow

FDTD-specific build/setup workflow: stages, PML extension, disambiguation defaults.

get_guidelines_for_fdtd_workflow_example

Worked end-to-end FDTD example: straight silicon waveguide with TE ports.

get_guidelines_for_workflow

Product-agnostic execution model, snippet structure, chunking, do-not rules.

get_guidelines_for_geometry

Dictionary-based addX syntax for Lumerical layout objects (FDTD/MODE/DEVICE).

get_guidelines_for_interconnect_commands

INTERCONNECT-specific lumapi command reference by category.

get_guidelines_for_interconnect_simulation

INTERCONNECT simulation config: root element, time/freq domain, result extraction.

get_guidelines_for_interconnect_workflow

INTERCONNECT-specific build/setup workflow: stages, element management, simulation config.

get_guidelines_for_materials

Built-in versus custom materials, anisotropic input. Applies to FDTD and MODE.

get_guidelines_for_mode_eme_workflow

MODE EME build/setup and analysis workflow.

get_guidelines_for_mode_fde_results

MODE FDE solve/result extraction guidance.

get_guidelines_for_mode_fde_workflow

MODE FDE build/setup workflow for straight and bent-waveguide tasks.

get_guidelines_for_mode_varfdtd_workflow

MODE varFDTD build/setup workflow.

get_guidelines_for_pic

Shared PIC simulation hygiene for FDTD, MODE, and FEEM optical tasks.

get_guidelines_for_s_parameter_sweep

S-parameter matrix sweep recipe and Y-branch example for FDTD and MODE.

get_guidelines_for_nested_sweeps

Product-agnostic nested sweep workflow based on insertsweep.

get_guidelines_for_sweeps

Product-agnostic sweep lifecycle: addsweep/setsweep/runsweep/getsweepresult.

get_guidelines_for

Fetch authoritative Lumerical scripting guidelines (markdown) for one topic.

GuidelinesContent

Description#

Curated Lumerical scripting guidance returned by get_guidelines_for.

This package powers a single MCP tool, get_guidelines_for(), that the LLM is expected to call BEFORE generating any Lumerical Python (lumapi) code. It returns authoritative markdown for a chosen topic so the model does not have to rely on whatever priors it picked up at training time.

Topic taxonomy:

  • workflow – product-agnostic execution model, snippet structure, chunking, parameter management, and the do-not-assume / do-not-invent rules. Applies to every Lumerical product. Lives in ansys.lumerical.mcp.contexts.general.

  • sweeps – product-agnostic lifecycle of analysis tasks created with addsweep (parameter sweep, optimization, Monte Carlo, S-parameter, corner sweep). Applies to FDTD, MODE, and INTERCONNECT. Lives in ansys.lumerical.mcp.contexts.sweeps.

  • pic – shared guided-wave photonic simulation hygiene for optical elements: PML extension of continuing guided structures, mode-solver / port span padding, and avoiding accidental substrate-mode selection. Applies to FDTD, MODE, and FEEM. Lives in ansys.lumerical.mcp.contexts.pic.

  • nested_sweeps – product-agnostic hierarchical sweep guidance: build the inner sweep first, wrap it with insertsweep, then run the outer parent sweep for all parameter combinations. Lives in ansys.lumerical.mcp.contexts.sweeps.

  • materials and geometry – shared between FDTD and MODE (and, for geometry, DEVICE), since those products share the same material database and layout-object lumapi calls. Live in ansys.lumerical.mcp.contexts.materials and ansys.lumerical.mcp.contexts.geometry.

  • s_parameter_sweep – shared FDTD and MODE recipe for the addsweep(3) S-parameter matrix sweep, with a Y-branch worked example. Lives in ansys.lumerical.mcp.contexts.s_parameter_sweep.

  • fdtd_workflow, fdtd_workflow_example, fdtd_sources_monitors, fdtd_run_and_results, fdtd_boundary_conditions, fdtd_mesh_and_convergence, fdtd_source_types, fdtd_monitors_and_field_extraction, fdtd_far_field_and_grating – FDTD-specific topics split into a build/setup half (fdtd_workflow + fdtd_workflow_example + fdtd_sources_monitors), a run/results half (fdtd_run_and_results), and four deep-dive topics on boundary conditions, mesh/convergence, non-port source types, monitors and field extraction, and far-field/grating projections, all owned by ansys.lumerical.mcp.contexts.fdtd.

  • interconnect_workflow and interconnect_commands – INTERCONNECT-specific topics covering build/setup workflow and command reference, both owned by ansys.lumerical.mcp.contexts.interconnect.

  • device_workflow, device_materials, and device_simulation_region – finite-element IDE (DEVICE) topics covering the shared HEAT / CHARGE / FEEM / DGTD build/run workflow, model-material creation, and simulation-region setup. Owned by ansys.lumerical.mcp.contexts.device.

  • mode_fde_workflow, mode_fde_results, and mode_eme_workflow and mode_varfdtd_workflow – MODE-specific topics covering FDE setup, FDE solve/results, EME setup/analysis workflow, and varFDTD setup/run guidance, all owned by ansys.lumerical.mcp.contexts.mode.

  • The system prompt (ansys.lumerical.mcp.prompts) is itself product-agnostic and does not need to change for new product topics.

Module detail#

contexts.get_guidelines_for(content: GuidelinesContent) → str#

Fetch authoritative Lumerical scripting guidelines (markdown) for one topic.

Call this tool BEFORE writing any Lumerical Python (lumapi) code, once per topic you need. Always fetch "workflow" first (the product-agnostic execution model and do-not-assume rules), then add the product-specific topics that match the task.

Parameters:
contentstr

Topic to retrieve. One of:

  • "workflow" – product-agnostic execution model: chunked execute_python_code snippets against the persistent subprocess, the seeded _lum_get / _lum_print_json helpers, per-product .run() calling conventions, and the do-not-assume / do-not-invent / do-not-re-run rules. Applies to FDTD, MODE, DEVICE, INTERCONNECT.

  • "sweeps" – product-agnostic addsweep lifecycle (parameter sweep, optimization, Monte Carlo, S-parameter, corner sweep), the dict-as-struct payload convention for addsweepparameter / addsweepresult, the deletesweep idempotent-rebuild pattern, and result extraction via getsweepresult. Applies to FDTD, MODE, INTERCONNECT.

  • "pic" – shared photonic simulation hygiene for optical elements: extending continuing guided structures through PML, giving ports / mode-solver windows enough wavelength-scale padding around the confined mode, and avoiding accidental substrate-mode selection. Applies to FDTD, MODE, and FEEM.

  • "nested_sweeps" – product-agnostic hierarchical sweep workflow: build the inner sweep first, wrap it with insertsweep, configure the outer sweep, then run the outer parent sweep to evaluate all parameter combinations.

  • "materials" – built-in vs. custom material selection, the addmaterial() / setmaterial() handle pattern, and anisotropic material input (diagonal + grid-attribute general anisotropy). Shared by FDTD and MODE.

  • "geometry" – dictionary-based addrect / addX syntax for Lumerical layout objects and the "x span" (not "x_span") property-naming convention. Shared by FDTD, MODE, and DEVICE.

  • "fdtd_workflow" – FDTD-specific build/setup stages, disambiguation defaults (3D, PML on all open boundaries, SI units, built-in materials), and the PML boundary-extension rule. Pair with "fdtd_run_and_results" for the run/results half.

  • "fdtd_workflow_example" – full worked example (straight silicon waveguide with TE port S-parameter extraction): pre-flight default-confirmation checklist followed by Steps 1-8 with the exact execute_python_code snippet for each chunk.

  • "fdtd_sources_monitors" – setglobalsource / setglobalmonitor usage (and the no-dict-syntax exception); prefer addport() over addmode() for S-parameter extraction; port direction convention.

  • "fdtd_run_and_results" – FDTD-specific run() arguments (solver / resource / GPU / Ansys Cloud Burst), the run()-once + switchtolayout rule, the dataset-is-a-dict contract for getresult, mandatory _lum_print_json inspection before indexing, the per-port S vs. full S-matrix distinction, and the fdtd.eval(";") escape hatch.

  • "fdtd_boundary_conditions" – BC decision guide and the four FDTD BC families: PML profiles (standard / stabilized / steep angle / custom), symmetric and anti-symmetric, periodic, and Bloch (plus when to switch to the BFAST plane-wave source for broadband angled incidence).

  • "fdtd_mesh_and_convergence" – "mesh accuracy" semantics (ppw vs. integer 1-8), conformal-mesh refinement variants, addmesh overrides for thin features and metals, simulation time / auto-shutoff interplay, and divergence diagnostics via the FDTD solver STATUS result.

  • "fdtd_source_types" – non-port source catalog with a decision tree: addplane / BFAST plane-wave, addgaussian, adddipole, addtfsf, and addimportedsource; gotchas (TFSF interface crossings, broadband-angle injection, dipole homogeneous validation).

  • "fdtd_monitors_and_field_extraction" – monitor type decision table (DFT power / profile / time / movie / index / mode-expansion), "override global monitor settings" pattern, mode-expansion analysis, and the reduce-before-print pattern that keeps 3D fields from blowing through the _lum_print_json truncation guard.

  • "fdtd_far_field_and_grating" – turning near-field monitor data into farfield2d / farfield3d / farfieldexact projections, grating-order analysis (gratingn1 / gratingn2 / grating / gratingangle / gratingpolar), and NA / cone filtering via farfield3dintegrate.

  • "s_parameter_sweep" – full N x N S-matrix extraction via addsweep(3) / runsweep / getsweepresult("s-parameter sweep", "S matrix"), with a Y-branch worked example (auto symmetry) and Touchstone / INTERCONNECT export. Shared by FDTD and MODE; fetch whenever the user asks for the full S-matrix of a multi-port device.

  • "mode_fde_workflow" – MODE FDE-specific build/setup workflow: safe addfde() + setnamed() configuration, bent-waveguide keys, active-property caveats, and sweep-safe reuse of clean pre-run setup files.

  • "mode_fde_results" – MODE FDE solve/result guidance: when to use findmodes(), common getdata() fields such as neff / loss / TE polarization fraction / ng, and robust TE/TM classification across sweeps.

  • "mode_eme_workflow" – MODE EME-specific build/setup and analysis workflow: cell-group setup, matrix-style group spans / cells payloads, layout-vs-analysis mode rules, emepropagate() / emesweep(), port hygiene, and user-S-matrix interpretation.

  • "mode_varfdtd_workflow" – MODE varFDTD-specific build/setup workflow: when to use the 2.5D propagator, effective-index setup, bandwidth choices, supported source / monitor classes, and validation of generated effective materials.

  • "interconnect_workflow" – INTERCONNECT-specific build/setup workflow: chunked stages for library validation, element addition and naming, port discovery, connections, property discovery, and save/run sequencing. Fetch for any INTERCONNECT photonic circuit task.

  • "interconnect_simulation" – INTERCONNECT root element simulation configuration ("simulation input" mode selector, time-domain property sets, ONA frequency-domain workflow) and getresult discovery pattern for analyzers. Fetch alongside "interconnect_workflow" for any simulation setup or result extraction task.

  • "interconnect_commands" – INTERCONNECT-specific lumapi command reference: element library, design kits, measurements, scripted elements, optimization, and export commands. Fetch when you need the exact command name or signature for an INTERCONNECT operation.

  • "device_workflow" – finite-element IDE (DEVICE) workflow shared by HEAT, CHARGE, FEEM, and DGTD: chunked stages for model-material creation, geometry, solver addition, simulation- region linkage, boundary conditions (children of the solver’s boundary conditions object), monitors (children of the solver object), run, and result collection from both monitors and the solver object itself.

  • "device_materials" – model-material creation via addmodelmaterial / addmaterialproperties, property families (EM / CT / HT), selection hygiene after each addmaterialproperties call, and database discovery. Shared by HEAT, CHARGE, FEEM, and DGTD.

  • "device_simulation_region" – simulation-region ownership model (region is separate from the solver object), per-face boundary types (Open / Closed / Shell), background material, and linking the region to a solver via setnamed(solver, "simulation region", region_name). Shared by HEAT, CHARGE, FEEM, and DGTD.

contexts.GuidelinesContent#