SimTools#

class simpleEMS.sim_tools.SimTools#

Bases: object

Namespace of static methods for simulation orchestration, plotting, and export.

This class is not meant to be instantiated; all methods are @staticmethod and are called directly on the class (e.g. SimTools.run_simulation(...)).

All structure classes (e.g. InsetFedPatchAntenna) inherit this class so its methods are available on structure instances too.

Methods Summary

`add_field_dump`(sim, params[, output_path, ...])	Add a field dump box to the simulation setup.
`compute_nf2ff_3d`(nf2ff, freq[, output_path, ...])	Compute the 3D far-field radiation pattern over a full theta/phi sweep (theta in [0, 180] deg, phi in [0, 360] deg, 2 deg steps).
`compute_sim_data`(sim, port[, output_path])	Compute S-parameters, impedance, VSWR, and port power/voltage/current from simulation results, for plotting and post-processing.
`create_nf2ff`([sim])	Create the near-field-to-far-field (NF2FF) recording box.
`export_csxcad_xml_to_step`(structure_xml_path)	Load a `structure.xml` file and export it to STEP AP242 format.
`export_gerber`(sim[, output_path, options, ...])	Export CSXCAD geometry to Gerber format, one file per copper layer.
`export_step`(sim[, output_path])	Export CSXCAD geometry to a colored, multi-layer STEP AP242 file using CadQuery.
`export_stl`(sim[, output_path])	Export the CSXCAD structure to STL files (FDTD backend only).
`export_touchstone`(freqs[, s11, s21, ...])	Export S-parameters to a Touchstone `.sNp` file.
`plot_2d_directivity`(nf2ff, freq[, ...])	Plot the 2D directivity pattern (xz-plane, phi=0) at a specified frequency, annotated with the half-power beamwidth (HPBW).
`plot_2d_rad_pattern`(nf2ff, freq[, ...])	Plot the 2D E-field radiation pattern at a specified frequency.
`plot_3d_directivity`(nf2ff_3d_result, freq[, ...])	Plot the 3D directivity pattern of an antenna at a specified frequency.
`plot_3d_gain`(nf2ff_3d_result, freq, input_power)	Plot the 3D gain pattern of an antenna at a specified frequency.
`plot_3d_power`(nf2ff_3d_result, freq[, ...])	Plot the 3D radiated power pattern of an antenna at a specified frequency.
`plot_group_delay`(freqs, s21[, x_label, ...])	Compute and plot the group delay as a function of frequency.
`plot_impedance`(freqs, z11[, x_label, ...])	Plot the input impedance (Z11) as a function of frequency.
`plot_phase`(freqs, s21[, x_label, y_label, title])	Plot the transmission phase (angle of S21) as a function of frequency.
`plot_s_param`(freqs, s11[, s21, x_label, ...])	Plot S-parameters (S11 and optionally S21) against frequency.
`plot_smith_chart`(freqs, s11[, label, charac_imp])	Plot S11 data on a Smith chart.
`plot_vswr`(freqs, vswr[, x_label, y_label, ...])	Plot the voltage standing wave ratio (VSWR) as a function of frequency.
`print_and_save_params`(params[, output_path])	Print the simulation parameters to the console and save them to `params/params.txt`.
`run_simulation`(sim[, output_path])	Run the simulation and write results to `output_path`.
`save_plots`([output_path, file_format])	Save all currently open matplotlib figures to `output_path / "plots"`.
`show_plots`()	Display all generated plots.
`write_and_show_structure`(sim[, output_path, ...])	Display the simulation geometry.

Methods Documentation

static add_field_dump(sim: SimSetup, params: SimParams, output_path: Path | None = None, dump_freq: float | None = None, dump_type: DumpType = DumpType.efield_frequency) → None#

Add a field dump box to the simulation setup.

Configures and attaches a field/current dump of the requested dump_type to the CSXCAD structure. The box follows the simulation box in x and y – params.simulation_box when defined, or the same geometry-padded box the FDTD mesher builds when it is None (see simpleEMS.fdtd_mesh.auto_simulation_bounds()) – and spans z from 0 to the top of the copper layer (substrate_thickness_mm + copper_thickness_mm).

Parameters:

sim (SimSetup) – Simulation setup named tuple returned by setup_simulation.
params (SimParams) – Parameter object supplying simulation_box, lambda0, substrate_thickness_mm, copper_thickness_mm and main_freq, used to size and configure the dump.
output_path (Path, optional) – Directory the dump data will be written under (a field_dump subdirectory is created). Defaults to cwd / "Sim_Path".
dump_freq (float, optional) – Frequency of a frequency-domain dump. Defaults to params.main_freq.
dump_type (DumpType, optional) – Type of field/current dump to add (time-domain or frequency-domain E-field, H-field, current, current density, or SAR). Default is DumpType.efield_frequency.

Return type:

None

static compute_nf2ff_3d(nf2ff: nf2ff, freq: float, output_path: Path | None = None, read_cached: bool = False) → nf2ff_results#

Compute the 3D far-field radiation pattern over a full theta/phi sweep (theta in [0, 180] deg, phi in [0, 360] deg, 2 deg steps).

The resulting far-field data can be used for visualization, directivity/gain/power analysis, and post-processing of antenna performance via plot_3d_directivity, plot_3d_gain, and plot_3d_power.

Parameters:

nf2ff (object) – The near-field-to-far-field (NF2FF) object containing the simulation data.
freq (float) – Frequency (in Hz) at which the 3D far-field pattern is evaluated. Must be a scalar.
output_path (Path, optional) – Path to the directory where the simulation result is saved. Defaults to cwd / "Sim_Path".
read_cached (bool, optional) – If True, read cached NF2FF results instead of re-computing. Default is False.

Returns:

The NF2FF result object for the full theta/phi sweep, holding (among other fields) E_norm, Dmax, Prad, theta, and phi.

Return type:

nf2ff_results

Raises:

TypeError – If freq is not a scalar (e.g. an array of frequencies).

static compute_sim_data(sim: SimSetup, port: LumpedPort | list[LumpedPort], output_path: Path | None = None) → SimData#

Compute S-parameters, impedance, VSWR, and port power/voltage/current from simulation results, for plotting and post-processing.

For the FDTD backend this calls CalcPort on the given port(s) and derives S11 (and S21 for two-port setups), Z11, VSWR, and input power from the port voltage/current waves. For the FEM backend the port argument is ignored and results are instead read from the GetDP sweep output previously written to output_path by run_simulation.

Parameters:

sim (SimSetup) – Simulation setup named tuple returned by setup_simulation; supplies freqs, backend_engine, and charac_imp.
port (LumpedPort or list of LumpedPort) – The openEMS port object representing a single-port simulation, or a two-element list [port1, port2] for a two-port simulation. Ignored when sim.backend_engine == "FEM".
output_path (Path, optional) – Directory the simulation results were written to. Defaults to cwd (FDTD backend) or cwd / "Sim_Path" (FEM backend, to match the default used by run_simulation).

Returns:

Named tuple containing:

freqsNDArray
Frequency points used in post-processing.
s11NDArray
Complex S11 values across the frequency range.
s21NDArray or None
Complex S21 values across the frequency range, or None for a single-port simulation.
z11NDArray
Complex Z11 values across the frequency range.
vswrNDArray
VSWR values across the frequency range, computed from S11 (clipped to |S11| <= 0.999 to avoid division by zero).
input_powerfloat
Time-averaged input power at the driven port.
port_voltageNDArray
Total complex voltage at the driven port across the frequency range.
port_currentNDArray
Total complex current at the driven port across the frequency range.
ref_impedancefloat
Reference impedance charac_imp (from sim) that S11 and Z11 were computed against.

Return type:

SimData

static create_nf2ff(sim: SimSetup | None = None) → nf2ff#

Create the near-field-to-far-field (NF2FF) recording box.

Parameters:: sim (SimSetup, optional) – Simulation setup named tuple returned by setup_simulation. Omit for the standalone STEP-FEM workflow (simulate_step_FEM), which has no SimSetup – None always returns a FEMNF2FF adapter.
Returns:: nf2ff – NF2FF object. For the FEM backend (or when sim is omitted) this is a FEMNF2FF adapter that exposes the same CalcNF2FF interface, so the radiation-plotting methods work identically for both backends.
Return type:: object

static export_csxcad_xml_to_step(structure_xml_path: str | Path, output_path: Path | None = None) → None#

Load a structure.xml file and export it to STEP AP242 format.

Useful for re-exporting a structure to STEP without re-running the simulation, given a structure.xml previously written by write_and_show_structure.

Parameters:

structure_xml_path (str or Path) – Path to the structure.xml file exported by CSXCAD / openEMS.
output_path (Path, optional) – Directory to save the step subdirectory under. Defaults to cwd / "Sim_Path".

Return type:

None

static export_gerber(sim: SimSetup, output_path: Path | None = None, options: dict[str, list] | None = None, prefix: str = 'layout') → list[Path]#

Export CSXCAD geometry to Gerber format, one file per copper layer.

Parameters:

sim (SimSetup) – Simulation setup named tuple returned by setup_simulation.
output_path (Path, optional) – Directory to save the gerber subdirectory under. Defaults to cwd / "Sim_Path".
options (dict[str, list], optional) – Dictionary of export options. Supported key "ignore": a list of property names to skip. Defaults to {}.
prefix (str, optional) – File name prefix. Default "layout".

Returns:

The Gerber and drill files written.

Return type:

list of Path

Notes

CSXCAD carries no layer information, so layers are inferred from the Z position of the metal: the highest metal is the top layer (F_Cu), the lowest the bottom layer (B_Cu), and anything in between an inner layer. Z-axis cylinders (vias) are written to an Excellon drill file and the substrate footprint to the board outline. See simpleEMS.export_gerber.export_gerber().

static export_step(sim: SimSetup, output_path: Path | None = None) → None#

Export CSXCAD geometry to a colored, multi-layer STEP AP242 file using CadQuery.

Parameters:

sim (SimSetup) – Simulation setup named tuple returned by setup_simulation.
output_path (Path, optional) – Directory to save the step subdirectory under. Defaults to cwd / "Sim_Path".

Return type:

None

static export_stl(sim: SimSetup, output_path: Path | None = None) → None#

Export the CSXCAD structure to STL files (FDTD backend only).

Reads the structure.xml previously written by write_and_show_structure and exports it to STL via AppCSXCAD.

Parameters:: output_path (Path, optional) – Directory containing structure.xml. STL files are written to a stl subdirectory. Defaults to cwd / "Sim_Path".
Raises:: ValueError – If structure.xml does not exist in output_path (i.e. write_and_show_structure was not called first).

static export_touchstone(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], s11: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, *, s21: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, s_matrix: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, charac_imp: float = 50.0, output_path: Path | None = None, filename: str = 's_param') → Path#

Export S-parameters to a Touchstone .sNp file.

Writes the provided S-parameter data to output_path / "touchstone" in Touchstone version 1 format. Pass either s11 (plus s21 for a two-port) or the full s_matrix; the port count sets the file extension.

Parameters:

freqs (NDArray) – Frequency points (in Hz) to export.
s11 (NDArray, optional) – Complex S11 values across the frequency range. Required unless s_matrix is given.
s21 (NDArray, optional) – Complex S21 values across the frequency range. If provided, a two-port (.s2p) network is written; otherwise a single-port (.s1p) network is written. Default is None.
s_matrix (NDArray, optional) – Complex S-parameters of shape (F, P, P), with s_matrix[:, i, j] holding S(i+1)(j+1). Writes every S-parameter of a P-port network. Cannot be combined with s11 or s21. Default is None.
charac_imp (float, optional) – Reference impedance (in ohms) recorded in the Touchstone file. Default is 50.0.
output_path (Path, optional) – Directory to save the touchstone subdirectory under. Defaults to cwd / "Sim_Path".
filename (str, optional) – Base name of the exported file (extension is added automatically). Default is "s_param".

Returns:

Path of the written Touchstone file.

Return type:

Path

Raises:

ValueError – If neither s11 nor s_matrix is given, or if s_matrix is combined with s11 / s21.

Notes

With s11 and s21, only S11 and S21 are populated; S12 and S22 are written as zero (the reverse-direction parameters are not simulated). Pass s_matrix to export all of them.

static plot_2d_directivity(nf2ff: nf2ff, freq: float, output_path: Path | None = None, read_cached: bool = False) → None#

Plot the 2D directivity pattern (xz-plane, phi=0) at a specified frequency, annotated with the half-power beamwidth (HPBW).

Computes directivity (in dBi) from NF2FF E-field data, plots it as a polar pattern, and marks the -3 dB beamwidth, main-lobe direction, and peak magnitude around the pattern’s maximum.

Parameters:

nf2ff (object) – The near-field-to-far-field (NF2FF) object containing the simulation data.
freq (float) – Frequency (in Hz) at which the directivity is evaluated. Must be a scalar.
output_path (Path, optional) – Path to the directory where the simulation result is saved. Defaults to cwd / "Sim_Path".
read_cached (bool, optional) – If True, read cached NF2FF results instead of re-computing. Default is False.

Returns:

Plots the 2D directivity pattern; does not return a value.

Return type:

None

Raises:

TypeError – If freq is not a scalar (e.g. an array of frequencies).
ValueError – If the -3 dB HPBW crossings cannot be found on either side of the peak.

static plot_2d_rad_pattern(nf2ff: nf2ff, freq: float, output_path: Path | None = None, read_cached: bool = False) → None#

Plot the 2D E-field radiation pattern at a specified frequency.

Computes far-field E-field cuts in the xz-plane (phi=0) and xy-plane (theta=90) from NF2FF data and plots both as normalized polar patterns (in dB) side by side.

Parameters:

nf2ff (object) – The near-field-to-far-field (NF2FF) object containing the simulation data.
freq (float) – Frequency (in Hz) at which the radiation pattern is evaluated. Must be a scalar.
output_path (Path, optional) – Path to the directory where the simulation result is saved. Defaults to cwd / "Sim_Path".
read_cached (bool, optional) – If True, read cached NF2FF results instead of re-computing. Default is False.

Returns:

Generates the 2D radiation pattern plot; does not return a value.

Return type:

None

Raises:

TypeError – If freq is not a scalar (e.g. an array of frequencies).

static plot_3d_directivity(nf2ff_3d_result: nf2ff_results, freq: float, output_path: Path | None = None) → None#

Plot the 3D directivity pattern of an antenna at a specified frequency.

Visualizes the directivity pattern (in dBi) of the antenna in 3D space, based on the far-field results from compute_nf2ff_3d, and saves the mesh as a VTK file under output_path / "3D_plots".

Parameters:

nf2ff_3d_result (nf2ff_results) – The 3D far-field result object returned by compute_nf2ff_3d.
freq (float) – The frequency (in Hz) at which the 3D directivity pattern is evaluated. Must be a scalar; used only for plot/file labeling.
output_path (Path, optional) – Path to the directory where the simulation result is saved. Defaults to cwd / "Sim_Path".

Returns:

Opens an interactive 3D plot window and saves the mesh to 3D_plots/3D_directivity.vtk; does not return a value.

Return type:

None

Raises:

TypeError – If freq is not a scalar (e.g. an array of frequencies).

static plot_3d_gain(nf2ff_3d_result: nf2ff_results, freq: float, input_power: float, output_path: Path | None = None) → None#

Plot the 3D gain pattern of an antenna at a specified frequency.

Visualizes the realized gain pattern (in dBi) of the antenna in 3D space: gain is directivity (from compute_nf2ff_3d) scaled by the radiation efficiency Prad / input_power. Saves the mesh under output_path / "3D_plots".

Parameters:

nf2ff_3d_result (nf2ff_results) – The 3D far-field result object returned by compute_nf2ff_3d.
freq (float) – The frequency (in Hz) the pattern was computed at. Used only for plot/file labeling.
input_power (float) – Input power at the port (same units as Prad), used to normalize directivity into realized gain.
output_path (Path, optional) – Path to the directory where the simulation result is saved. Defaults to cwd / "Sim_Path".

Returns:

Opens an interactive 3D plot window and saves the mesh to 3D_plots/3D_Gain.vtk; does not return a value.

Return type:

None

static plot_3d_power(nf2ff_3d_result: nf2ff_results, freq: float, output_path: Path | None = None) → None#

Plot the 3D radiated power pattern of an antenna at a specified frequency.

Visualizes the normalized radiated power pattern (in dB) of the antenna in 3D space, based on the P_rad field of the far-field results from compute_nf2ff_3d. Saves the mesh under output_path / "3D_plots".

Parameters:

nf2ff_3d_result (nf2ff_results) – The 3D far-field result object returned by compute_nf2ff_3d.
freq (float) – The frequency (in Hz) the pattern was computed at. Used only for plot/file labeling.
output_path (Path, optional) – Path to the directory where the simulation result is saved. Defaults to cwd / "Sim_Path".

Returns:

Opens an interactive 3D plot window and saves the mesh to 3D_plots/3D_Power.vtk; does not return a value.

Return type:

None

static plot_group_delay(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], s21: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None, x_label: str = 'Frequency', y_label: str = 'Group Delay', title: str = 'Group Delay vs Frequency') → None#

Compute and plot the group delay as a function of frequency.

The group delay is computed from the frequency derivative of the unwrapped phase of S21 and displayed in seconds (via an engineering time-unit axis formatter).

Parameters:

freqs (NDArray) – A 1D array of frequencies (in Hz) to plot on the x-axis.
s21 (NDArray) – A 1D array of complex S21 values corresponding to each frequency.
x_label (str, optional) – Label for the x-axis. Default is "Frequency".
y_label (str, optional) – Label for the y-axis. Default is "Group Delay".
title (str, optional) – Title of the plot. Default is "Group Delay vs Frequency".

Returns:

Displays the group delay plot in a new figure; does not return a value.

Return type:

None

static plot_impedance(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], z11: ndarray[tuple[Any, ...], dtype[_ScalarT]], x_label: str = 'Frequency', y_label: str = 'Z11', title: str = 'Z11 vs Frequency') → None#

Plot the input impedance (Z11) as a function of frequency.

Opens a new figure and plots the real and imaginary parts of Z11, in ohms, as separate traces over the given frequency range.

Parameters:

freqs (NDArray) – A 1D array of frequencies (in Hz) to plot on the x-axis.
z11 (NDArray) – A 1D array of complex Z11 values (in ohms) corresponding to each frequency.
x_label (str, optional) – Label for the x-axis. Default is "Frequency".
y_label (str, optional) – Label for the y-axis. Default is "Z11".
title (str, optional) – Title of the plot. Default is "Z11 vs Frequency".

Returns:

Displays the impedance plot in a new figure; does not return a value.

Return type:

None

static plot_phase(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], s21: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None, x_label: str = 'Frequency', y_label: str = 'Phase (deg)', title: str = 'Phase vs Frequency') → None#

Plot the transmission phase (angle of S21) as a function of frequency.

Opens a new figure and plots the phase of S21, in degrees, over the given frequency range.

Parameters:

freqs (NDArray) – A 1D array of frequencies (in Hz) to plot on the x-axis.
s21 (NDArray) – A 1D array of complex S21 values corresponding to each frequency.
x_label (str, optional) – Label for the x-axis. Default is "Frequency".
y_label (str, optional) – Label for the y-axis. Default is "Phase (deg)".
title (str, optional) – Title of the plot. Default is "Phase vs Frequency".

Returns:

Displays the phase plot in a new figure; does not return a value.

Return type:

None

static plot_s_param(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], s11: ndarray[tuple[Any, ...], dtype[_ScalarT]], s21: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, x_label: str = 'Frequency', y_label: str = 'S-parameter (dB)', title: str = 'S-parameters vs Frequency', label_s11: str | None = None, label_s21: str | None = None) → None#

Plot S-parameters (S11 and optionally S21) against frequency.

Draws onto the current matplotlib axes (call plt.figure() beforehand to start a new figure). Both s11 and s21 are expected as complex/linear values; they are converted to dB (20*log10(|.|)) internally before plotting.

Parameters:

freqs (NDArray) – A 1D array of frequencies (in Hz) to plot on the x-axis.
s11 (NDArray) – A 1D array of complex (linear) S11 values.
s21 (NDArray, optional) – A 1D array of complex (linear) S21 values for two-port networks. If None (default), only S11 is plotted.
x_label (str, optional) – Label for the x-axis. Default is "Frequency".
y_label (str, optional) – Label for the y-axis. Default is "S-parameter (dB)".
title (str, optional) – Title of the plot. Default is "S-parameters vs Frequency".
label_s11 (str, optional) – Legend label for the S11 trace. Defaults to "S11".
label_s21 (str, optional) – Legend label for the S21 trace. Defaults to "S21".

Returns:

Draws the plot on the current axes; does not return a value.

Return type:

None

static plot_smith_chart(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], s11: ndarray[tuple[Any, ...], dtype[_ScalarT]], label: str = '', charac_imp: float = 50.0) → None#

Plot S11 data on a Smith chart.

Opens a new figure with a Smith-chart projection and plots the complex reflection coefficient (S11) over the given frequency range, marking the value at the midpoint frequency.

Parameters:

freqs (NDArray) – A 1D array of frequencies (in Hz) corresponding to the S11 data.
s11 (NDArray) – A 1D array of complex S11 (reflection coefficient) values.
label (str, optional) – Label used for the plot legend. Default is an empty string.
charac_imp (float, optional) – Characteristic (normalizing) impedance of the chart, in ohms. Default is 50.0.

Returns:

Displays the Smith chart in a new figure; does not return a value.

Return type:

None

Notes

pysmithchart is used to render the Smith chart.

static plot_vswr(freqs: ndarray[tuple[Any, ...], dtype[_ScalarT]], vswr: ndarray[tuple[Any, ...], dtype[_ScalarT]], x_label: str = 'Frequency', y_label: str = 'VSWR', label: str = 'VSWR', title: str = 'VSWR vs Frequency') → None#

Plot the voltage standing wave ratio (VSWR) as a function of frequency.

Opens a new figure and plots VSWR over the given frequency range, to evaluate impedance matching performance.

Parameters:

freqs (NDArray) – A 1D array of frequencies (in Hz) to plot on the x-axis.
vswr (NDArray) – A 1D array of VSWR values corresponding to each frequency.
x_label (str, optional) – Label for the x-axis. Default is "Frequency".
y_label (str, optional) – Label for the y-axis. Default is "VSWR".
label (str, optional) – Label used for the plot legend. Default is "VSWR".
title (str, optional) – Title of the plot. Default is "VSWR vs Frequency".

Returns:

Displays the VSWR plot in a new figure; does not return a value.

Return type:

None

static print_and_save_params(params: SimParams, output_path: Path | None = None) → None#

Print the simulation parameters to the console and save them to params/params.txt.

Parameters:

params (SimParams) – Parameter object whose dataclass fields are printed and saved.
output_path (Path, optional) – Directory to save the params subdirectory under. Defaults to cwd / "Sim_Path".

Returns:

Does not return a value.

Return type:

None

static run_simulation(sim: SimSetup, output_path: Path | None = None) → None#

Run the simulation and write results to output_path.

Dispatches to the FDTD engine (FDTD.Run) or, for the FEM backend, to the adaptive GetDP frequency sweep (fem_backend.run_sweep), which performs up to sim.FEM_options.num_solve_points full solves. For the FEM backend this always (re-)meshes first, reusing the existing mesh if sim.CSX/sim.FEM_options haven’t changed since the last mesh in this output_path (e.g. a prior write_and_show_structure call) and rebuilding if they have – so a sweep/optimize loop that calls this directly, varying the geometry across iterations into the same output_path, still gets a fresh mesh each time the geometry actually changes.

Parameters:

sim (SimSetup) – Simulation setup named tuple returned by setup_simulation.
output_path (Path, optional) – Directory to write simulation results to. Defaults to cwd / "Sim_Path".

static save_plots(output_path: Path | None = None, file_format: str = 'png') → None#

Save all currently open matplotlib figures to output_path / "plots".

Each open figure is resized to 12x6 inches and saved as plot_<n>.<file_format>, in figure order.

Parameters:

output_path (Path, optional) – Directory to save the plots subdirectory under. Defaults to cwd / "Sim_Path".
file_format (str, optional) – File format to save the plots as (e.g. "png", "jpg", "pdf"). Default is "png".

Return type:

None

Notes

Call this before show_plots, since show_plots blocks until the plot windows are closed.

static show_plots() → None#

Display all generated plots. Blocks until the plot window(s) are closed.

If no matplotlib figures are open and a Qt application instance is already running (e.g. a PyVista/FEM mesh viewer opened by write_and_show_structure), blocks on that Qt event loop instead and exits the process once it closes. Otherwise calls matplotlib.pyplot.show() to display any open matplotlib figures.

Returns:: Does not return a value.
Return type:: None

static write_and_show_structure(sim: SimSetup, output_path: Path | None = None, mesh_style: str = 'wireframe', theme: str | None = None) → None#

Display the simulation geometry.

For the FDTD backend this opens the structure in AppCSXCAD. For the FEM backend it (re-)meshes the current CSX/FEM_options with Gmsh – reusing the existing mesh instead of rebuilding if neither has changed since the last call on this output_path – and renders it with PyVista, coloring cells by their Gmsh physical-group id.

Parameters:

sim (SimSetup) – Simulation setup named tuple returned by setup_simulation.
output_path (Path, optional) – Directory to write/read the structure XML (FDTD) or mesh files (FEM). Defaults to cwd / "Sim_Path", created if missing.
mesh_style (str) – FEM mesh only. PyVista add_mesh representation: "surface", "wireframe" (default), or "points". Mesh cells are colored by their Gmsh physical-group id (CellEntityIds: dielectric, PEC, port, absorbing boundary, …).
theme (str, optional) – FEM mesh only. None (default) keeps the active simpleEMS theme (see simpleEMS.plot_theme.use_dark_theme()). A PyVista theme name – "dark", "default", "document" or "paraview" – is applied globally via pyvista.set_plot_theme().

Raises:

ValueError – If theme is not one of PyVista’s native theme names.

SimTools#

This Page