BandPassQuarterWaveFilter#

class simpleEMS.quarterwave_stub_filter.BandPassQuarterWaveFilter(params: QuarterWaveFilterParams, sim: SimSetup)#

Bases: QuarterWaveFilter

Band-pass quarter-wave stub filter model.

Extends QuarterWaveFilter with the series transmission line sections, short-circuited shunt stubs, excitation ports, and FDTD mesh needed for a band-pass response. Each shunt stub is grounded at its far end by a row of plated vias (see create_shunt_line_short), which presents a high impedance at the junction near centre_freq and lets that band through while attenuating frequencies further away. Use build_band_pass_quarter_wave_filter to construct the full geometry, or call the individual create_* methods directly for finer control.

Methods Summary

`add_field_dump`(sim, params[, output_path, ...])	Add a field dump box to the simulation setup.
`build_band_pass_quarter_wave_filter`()	Construct the complete band-pass quarter-wave stub filter geometry.
`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_ground`()	Define and add the copper ground plane to the geometry.
`create_mesh`([manual_mesh])	Generate an FDTD mesh for the band-pass filter simulation domain.
`create_nf2ff`([sim])	Create the near-field-to-far-field (NF2FF) recording box.
`create_ports`()	Define the excitation lumped ports at both ends of the filter.
`create_series_line`()	Create the series transmission line sections.
`create_shunt_line`()	Create the shunt stub line sections.
`create_shunt_line_short`()	Create the row of grounding vias at the open end of each shunt stub.
`create_substrate`()	Define and add the dielectric substrate to the simulation.
`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

build_band_pass_quarter_wave_filter() → list[LumpedPort]#

Construct the complete band-pass quarter-wave stub filter geometry.

Orchestrates the creation of all filter components, including the substrate, ground plane, series transmission line sections, shunt stubs with their grounding shorts, and excitation ports. The mesh must be created separately via create_mesh.

Returns:: A list of two LumpedPort objects [port1, port2] for S-parameter extraction.
Return type:: list of LumpedPort

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

create_ground() → None#

Define and add the copper ground plane to the geometry.

Adds a metallic box (PEC) below the substrate. The ground plane thickness is defined by copper_thickness_mm and extends to the edges of the substrate.

Return type:: None

create_mesh(manual_mesh: bool = False) → None#

Generate an FDTD mesh for the band-pass filter simulation domain.

Defines mesh lines for x, y, and z directions based on the filter geometry, series and shunt line dimensions, and simulation box size. Uses SmoothMeshLines for stable grid transitions.

Parameters:: manual_mesh (bool, optional) – If True, use manual mesh line definitions instead of the automatic Mesh class. Default is False.
Return type:: None

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

create_ports() → list[LumpedPort]#

Define the excitation lumped ports at both ends of the filter.

Creates Port 1 (excited) at the input and Port 2 (unexcited) at the output for S-parameter measurement.

Returns:: A list of two LumpedPort objects [port1, port2].
Return type:: list of LumpedPort

create_series_line() → None#

Create the series transmission line sections.

Adds multiple rectangular metal boxes for the series line segments of the filter, separated by shunt stub locations.

Return type:: None

create_shunt_line() → None#

Create the shunt stub line sections.

Adds multiple rectangular metal boxes for the shunt stub elements of the band-pass filter, connecting from the series line to the point where it is grounded by create_shunt_line_short.

Return type:: None

create_shunt_line_short() → None#

Create the row of grounding vias at the open end of each shunt stub.

Adds plated vias, each drawn as a solid copper cylinder of diameter via_diameter_mm, in a row across the far end of each shunt stub. The row holds as many vias as fit with at least one via diameter of copper between neighbouring barrels, so a wider stub gets more vias. The outer barrels sit flush with the stub’s side edges (a single via sits in the middle), every barrel sits flush with the stub end, and each spans from the bottom of the ground plane to the top of the stub. The vias short each stub to ground, which turns it into a short-circuited quarter-wave stub, as the band-pass response needs.

Return type:: None
Raises:: ValueError – If the via is wider than any shunt stub it has to land on.

create_substrate() → None#

Define and add the dielectric substrate to the simulation.

This method creates a material using the permittivity and loss tangent.

Return type:: None

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.

BandPassQuarterWaveFilter#

This Page