Usage guide

Workflow¶

1. Draw the device as a gdsfactory component (or import a .gds) with ports, plus a LayerStack assigning thickness and material per layer.

2. Define materials, frames, sources and monitors.

3. lumi.mesh(path, c, layer_stack, materials, zmin, zmax) writes 3D meshes into simulation folder path.

4. lumi.setup(path, ...) writes the simulation problem and solves port modes.

5. lumi.solve(path) runs FDTD. Runs on Lumi Colab server.

6. lumi.movie(path) shows the field movie; sol = lumi.load(path) loads results.

See bend for a minimal example.

Conventions¶

Units & frequency¶

• Length units are arbitrary but must be consistent: eg um for photonics, mm for RF.

• Photonics: wl (center) and wls (result wavelengths) in length units.

• RF: f and fs with c0, speed of light in your units, eg c0=300 for mm and GHz.

• Results are arrays over wls or fs, in the order given.

• Times (tmax, shot_every, t0) are in periods of the center frequency.

• One run computes the whole spectrum; more wavelengths add little runtime.

Grid & resolution¶

• nres: grid points per wavelength in material. 6 is a good start for photonics. Convergence typically <1% after nres=8

• Keep nres low! Due to subpixel smoothing tensors Lumi can achieve comparable accuracy at lower nres. Runtime scales O(N^4) and domain size O(N^3). High nres is useless and will breach free tier cell limit.

• Grid adapts to each material’s n; subpixel_smoothing averages material boundaries for accuracy; PEC boundaries use conformal (Yu–Mittra) edge weighting.

• Check convergence by increasing nres until results stop changing.

• Use symmetry to halve the domain: PMC or PEC boundary on one side, eg ("PMC", "PML").

Material properties¶

• lumi.material(n) or lumi.material(epsilon=...): relative permittivity, scalar or 3x3 tensor for anisotropic materials.

• Also mu, sigma (relative units: multiply S/m by 377 * (characteristic wavelength in m)), chi2, chi3, dispersion: list of lumi.lorentzian, lumi.drude or lumi.gain terms (Meep convention).

• n also sets mesh density relative to vacuum, default sqrt(epsilon * mu). Raise it, or set dx (max grid spacing in geometry units), to refine the grid in a material, eg thin metals. dx only refines, never coarsens.

• lumi.PEC_material(n): perfect conductor for metals.

• lumi.placeholder_material(n): meshed but no physical properties, eg design regions.

• materials is a dict of name to material; LayerStack layers and background refer to these names.

Frames¶

• Coordinate frame with sampling regions or points, reusable by any number of sources and monitors at different positions via frame="name". Pass all frames to setup(frames=...).

• Local coordinates: origin at the source or monitor origin, axes from its basis. mirrored=True flips local x, eg for a port on the opposite side of a symmetric device.

• Types and results:

  • plane_frame: port cross section with solved modes. Results modes, flux, power. Sources need one.

  • points_frame: fields at points, or sensor="voltage" / "current" integrals for RF.

  • box_frame: fields in a sampled volume.

  • cage_frame: closed box surface. Flux per face, power, far field.

  • spherical_frame: sphere of radius r. Flux, power, far field if closed.

• Results are frequency domain at wls or fs by default; time_domain=True records time signals instead.

Ports & S-parameters¶

• Source and monitor names match gdsfactory port names, eg "o1". gf_source and gf_monitor place them at ports.

• General constructors source monitor

• Port basis rows: local x, local y, outward normal. Sources inject bidirectional.

• Monitor results: sol["monitors"][name]["modes"][mode number]["+" or "-"], where "+" is outgoing (along normal), "-" incoming.

• S-parameters are ratios of mode amplitudes, eg

S21 = sol["monitors"]["o2"]["modes"][0]["+"] / sol["monitors"]["o1"]["modes"][0]["-"]
S11 = sol["monitors"]["o1"]["modes"][0]["+"] / sol["monitors"]["o1"]["modes"][0]["-"]

• Inverse design targets use "port@mode±", eg lumi.target("o1@0-", "o2@0+", 1).

Inverse design¶

Optimizes the material layout in design regions to meet S-parameter targets. Max tier only. See GC_invd.

1. Draw the design region on its own layer in the component.

2. Give that layer the material lumi.placeholder_material(n) in the LayerStack, with the lowest mesh_order so it overrides other layers, and the vertical extent to be patterned.

3. lumi.design(name, layer, lmin, fill_material, void_material, ...): region patterned with fill_material and void_material at minimum feature size lmin. repdims=[3] extrudes a planar pattern along z; symdims enforces symmetry.

4. lumi.target(src, dst, target, wl=...): one per objective, eg "o2@0-" to "o1@0+" with target=1 for full transmission. Loss is the weighted sum of target errors; use one target per wavelength for broadband.

5. lumi.optimizer(iters, stoploss, ...): stops after iters or below stoploss. contrast below 1 allows topology change and rises linearly to 1 (binary) as loss approaches lowloss, or by iteration 25.

6. Pass designs, targets, optimizer to setup, then solve runs the optimization.

Outputs in the run folder: history.json (loss per iteration) and designs/<name>/mask.npy (optimized boolean fill mask).

Run folder & files¶

One folder per simulation, eg runs/bend:

• geometry/: meshes from mesh

• problem.json, modes/, info.json, visualization.json: from setup

• solution.json: results from solve, read by load

• fields/, *.gif, *.webp: field snapshots and movies, if views set