Use Maxwell in WiTwin Studio

This guide is for WiTwin Studio users who want to run Maxwell without writing a solver script. The Maxwell Plugin adds components that describe a witwin.maxwell Scene, a Library of ready-made objects and parametric models, an "EM Design" Project template, and an FDTD solver that draws the field in the viewport. The last two sections show how each Studio object becomes a witwin.maxwell object and which Maxwell features still need the Python API.

What the Plugin adds#

The Plugin id is witwin.maxwell. Its Python distribution is wt-maxwell (import name wt_maxwell), and its source is at https://github.com/witwin-ai/wt_maxwell.

Get the Plugin#

WiTwin Plugins never come from PyPI. Use one of these sources.

# Run in the Project folder. Pick one.
witwin add git+https://github.com/witwin-ai/wt_maxwell
witwin add ../wt_maxwell          # a local checkout, installed editable

witwin add writes the dependency, pins first-party packages to the witwin index (never PyPI), runs uv lock and syncs the environment. It accepts --tag, --rev or --branch for a git source.

An installed Plugin that Studio does not trust yet shows Trust & Enable on its card; Studio runs its code only after you choose it.

Install the solver runtime#

The Plugin itself is light: Studio imports only its components and Library entries. The FDTD solve runs in a child process on the Project's Python: <project>/.venv when it exists, otherwise the interpreter Studio runs on (the WITWIN_PROJECT_PYTHON environment variable overrides both). That interpreter needs witwin-maxwell and a CUDA build of PyTorch, plus an NVIDIA GPU. Install them as described in Installation.

Create a Project from the EM Design template#

While no Project is open, Studio shows Project template cards in the Chat column. The Maxwell Plugin contributes the EM Design card. If the Plugin is not installed, the card shows a download mark, and clicking it opens the Plugins page filtered to the Plugin. Otherwise, clicking the card creates a new Project from the template and opens it.

The new Project is also an ordinary Python project:

The Scene holds no geometry. Maxwell Settings sets a domain from -0.6 m to 0.6 m on each axis, 7 points per wavelength at the 1 GHz solve frequency (a cell of about 4.3 cm), and PML on every face with 10 layers. Point Source is a z-polarised point dipole at the origin with a Gaussian pulse at 1 GHz and 0.2 GHz spectral width.

To solve it, select Maxwell Settings and press Solve in the Results group of its Maxwell Solver component. The radiated field appears in the viewport as a 3D volume.

You can change the template Scene from a terminal as well. The script edits scenes/main.wtscene, the same file Studio edits:

uv sync
uv run python scripts/prepare_em.py --frequency-ghz 1.5

Set up the Scene#

A Maxwell Scene in Studio is a set of objects. One object carries the Maxwell Solver component and holds the scene-wide settings. Every other object is a structure, a source, a monitor, a port or a material region, depending on its components.

To start a Scene by hand, drag Maxwell Settings from the Maxwell Library category into the Scene. "Maxwell 3D Field (Demo)" adds the same object plus a point source at the domain centre.

All lengths are in metres, frequencies in hertz, and times in seconds.

Domain#

The Domain group of the Maxwell Solver component sets the simulation box.

Both corners are relative to the Maxwell Settings object: the export adds the object's world position to them. You can also drag the domain box in the viewport.

Grid#

The grid is always uniform. You choose its density, not its cell size.

The cell size is c / f_max / ppw, where c is 299792458 m/s and f_max is the highest solve frequency (1 GHz when the list is empty). The wavelength is the free-space one, so raise ppw when the Scene contains high-permittivity material or features smaller than a few cells.

Boundary#

See Grids and boundaries for what each kind does.

Settings#

Materials#

Any object with geometry can carry Studio's Material component. Its Electromagnetic group feeds Maxwell:

The component's default eps_r is 10, not 1, so set the material of every structure. Maxwell does not combine dispersion with anisotropy, or Kerr with either of them, so the export stops with an error for those combinations. See Materials for the meaning of the poles.

MaterialRegion marks a box (an object with box PlatformGeometry) as a density-parameterized design region for topology optimization. Its fields are region_name, basis, bounds, eps_bounds, mu_bounds, the design grid density_nx, density_ny, density_nz, an optional blur filter (use_filter, filter_radius in m), an optional tanh projection (use_projection, projection_beta) and symmetry. Studio stores only the shape: the export always starts from a zero density, and the Plugin runs no optimization loop.

Structures#

Each visible object that is not a source, monitor, port or material region becomes a structure:

• An object with a mesh (an imported mesh, a primitive, a generated body) is exported as a mesh at its full world transform, including scale.
• An object with PlatformGeometry and no mesh is exported as that geometry.
• The object's Material component sets the material. Without one, the structure gets mw.Material() (vacuum).
• A StructureMeta component, when present, sets priority, enabled, tags and metadata.

Hidden objects are left out of the solve.

Sources#

Each source is an empty object with one source component.

Every source has a Source Time group:

If the Scene has no source when you press Solve, the Plugin adds an object named "Default FDTD Source": an Ez point dipole with a Gaussian pulse at the first solve frequency and 20 % of it as spectral width.

See Sources for how to choose a source and its time profile.

Monitors#

Each monitor is an empty object with one monitor component. Every frequencies field lists frequencies in Hz; an empty list means a broadband DFT.

Ports#

ModePort couples a mode source and a mode monitor on one plane. Its fields are size (one axis zero), mode_index, direction, polarization, frequencies, monitor_offset (m along the normal) and normal_direction. Turn on is_source to make the port inject; it then shows the same Source Time fields as a source. The port stays one object in Studio; Maxwell splits it into a source and a monitor when it solves. See Mode ports.

Add geometry from the generators#

The generators are parametric model files that ship with the Plugin. Each one is a Library item:

1. Drop the model

   Drag a generator from the Library into the Scene. Studio adds an empty group with a Script Geometry component whose source is the Plugin model, and builds it once with the default parameters. The defaults are a working design, not a placeholder.

2. Change the parameters

   The model parameters appear as fields of the Script Geometry component, shown in the model's units. Changing one rebuilds the group. Regenerate approves the model's current code and runs it again. Each generated body is a child object with a mesh and a Material component, so it becomes a Maxwell structure.

3. Size it from a specification

   Most models have a design(spec) function that turns a target (for example a centre frequency and a substrate) into parameter values from textbook formulas. Studio's Library drop does not ask for a spec; ask the Agent to place the model with a design spec (the geometry.place Tool), or run the model from Python as below.

4. Copy it into the Project (optional)

   Copy to Project copies the model file and its helper modules into the Project's models/ folder so you can edit the code.

Model files use millimetres (micrometres for the photonic crystal slab) with z up; Studio converts them to metres when it places them. Conductors use the material "PEC" and dielectrics carry eps_r and sigma_e. Each model has port anchors (for example feed, or port1 and port2) that mark where to put a port or source.

You can build and check a model without Studio:

from witwin.studio.geometry import run_model
 
run = run_model("models/lines/microstrip.py", params={"w": 2.9})

The export also ignores the fill and surface_thickness of generated bodies: a copper sheet drawn as a single surface is exported as that surface mesh, with no thickness.

Run the solve#

1. Set the solve frequencies

   Add at least one value to frequencies in the Settings group. Make the source frequency match one of them.

2. Check the grid and boundary

   Choose ppw and the boundary. The dashed grey box in the viewport shows where the PML starts.

3. Press Solve

   Solve is in the Results group. You can cancel a running solve.

When you press Solve, the Plugin:

1. adds the default source if the Scene has none, and applies the current timeline pose to the Scene;
2. sends the Scene to the witwin.maxwell.fdtd solver, which rebuilds a witwin.maxwell.Scene from it and runs Simulation.fdtd(...).run() with full_field_dft=True;
3. keeps the solver's result, then updates the field slice and, when show_3d_field is on, the 3D volume.

The solver process stays running between solves (it stops after 300 s idle) and runs one solve at a time. A notification reports success or the error message. The Plugin solves with FDTD only.

View 2D slices and 3D volumes#

The Results group of the Maxwell Solver component controls what you see:

• Update Slice draws the slice in the "Field Slice" figure of the component.
• Show 3D Volume loads the whole component volume onto the Maxwell Settings object and switches its Rendering tab to Volume. The Rendering tabs (None, Slices, Volume, SDF, Vector) choose how the viewport draws that field.

Both buttons need a solve first. They query the last result, so you can change the component, value mode or frequency index without solving again. The field data is runtime state and is not saved in the Scene file.

How the Studio Scene maps to witwin.maxwell#

The Plugin rebuilds a witwin.maxwell.Scene from the Studio Scene each time you solve.

Object names become the name of the Maxwell object. time_steps becomes run_time=mw.TimeConfig(time_steps=...); with time_steps_auto on, run_time is None.

For example, the EM Design template Scene is equivalent to this script:

import witwin.maxwell as mw
 
scene = mw.Scene(
    domain=mw.Domain(bounds=((-0.6, 0.6), (-0.6, 0.6), (-0.6, 0.6))),
    grid=mw.GridSpec.uniform(299792458.0 / 1e9 / 7),   # ppw = 7 at 1 GHz
    boundary=mw.BoundarySpec.pml(num_layers=10, strength=1e6),
    device="cuda",
)
scene.add_source(mw.PointDipole(
    position=(0.0, 0.0, 0.0), polarization="Ez", width=0.02, profile="gaussian",
    source_time=mw.GaussianPulse(frequency=1e9, fwidth=2e8, delay=4.7746482323418604e-09),
    name="Point Source"))
result = mw.Simulation.fdtd(scene, frequencies=(1e9,), absorber="cpml", full_field_dft=True).run()

The Plugin also translates in the other direction, from a witwin.maxwell.Scene into Studio objects. That direction loses what the Studio components cannot hold: an anisotropic grid comes back as a uniform grid, with the ppw of its finest spacing rounded and clamped to 4 to 20. Source, monitor and port types other than those above are not supported, and thin wires, lumped elements, networks and circuits are left out.

What needs the Python API#

The Plugin covers the FDTD setup above. Use witwin.maxwell directly, in a Project Script or your own code, for everything else: