openEMS

class openEMS.openEMS

This class is the main control class for the FDTD options and setup and to run the final simulation.

Examples

>>> CSX = CSXCAD.ContinuousStructure()
>>>
>>> grid = CSX.GetGrid()
>>> grid.SetLines('x', np.arange(-50,50,1))
>>> grid.SetLines('y', np.arange(-50,50,1))
>>> grid.SetLines('z', np.arange(-2,2.1,1))
>>> grid.SetDeltaUnit(1e-3)
>>>
>>> FDTD = openEMS(NrTS=1e4, EndCriteria=1e-4)
>>>
>>> FDTD.SetCSX(CSX)
>>> FDTD.SetBoundaryCond(['PML_8', 'PML_8', 'PML_8', 'PML_8', 'PEC', 'PEC'])
>>> FDTD.SetGaussExcite(0, 10e9)
>>>
>>> FDTD.AddLumpedPort(port_nr=1, R=50, start=[10, 0, -2], stop=[10, 0, 2], p_dir='z', excite=1)
>>>
>>> FDTD.Run(sim_path='/tmp/test')
Parameters:

  • NrTS – max. number of timesteps to simulate (e.g. default=1e9)

  • EndCriteria – end criteria, e.g. 1e-5, simulations stops if energy has decayed by this value (<1e-4 is recommended, default=1e-5)

  • MaxTime – max. real time in seconds to simulate

  • OverSampling – nyquist oversampling of the time domain dumps and probes (default 4). Frequency-domain dumps/probes accumulate at the plain Nyquist rate unless a box sets its own over_sampling (CSXCAD AddDump/AddProbe).

  • CoordSystem – choose coordinate system (0 Cartesian, 1 Cylindrical)

  • MultiGrid – define a cylindrical sub-grid radius

  • TimeStep – force to use a given timestep (dangerous!)

  • TimeStepFactor – reduce the timestep by a given factor (>0 to <=1)

  • TimeStepMethod – 1 or 3 chose timestep method (1=CFL, 3=Rennigs (default))

  • CellConstantMaterial – set to 1 to assume a material is constant inside a cell (material probing in cell center). Required for SAR, see SetCellConstantMaterial().

AddCPWPort(port_nr, metal_prop, start, stop, prop_dir, exc_dir, gap_width, excite=0, **kw)

Add a coplanar waveguide port.

See also

openEMS.ports.CPWPort
AddCircWaveGuidePort(port_nr, start, stop, exc_dir, radius, mode_name, pol_ang=0, excite=0, **kw)

Add a circular waveguide port.

See also

openEMS.ports.CircWGPort
AddCoaxialPort(port_nr, pec_prop, mat_prop, start, stop, prop_dir, r_i, r_o, r_os, excite=0, **kw)

Add a coaxial port.

See also

openEMS.ports.CoaxialPort
AddCurvePort(port_nr, R, start, stop, excite=0, **kw)

Add a curve (wire) port.

See also

openEMS.ports.CurvePort
AddEdges2Grid(primitives, dirs, **kw)

Add the edges of the given primitives to the FDTD grid.

Parameters:

  • dirs – primitives – one or more primitives

  • dirs – str – ‘x’,’y’,’z’ or ‘xy’, ‘yz’ or ‘xyz’ or ‘all’

AddLumpedPort(port_nr, R, start, stop, p_dir, excite=0, **kw)

Add a lumped port with the given values and location.

See also

openEMS.ports.LumpedPort
AddMSLPort(port_nr, metal_prop, start, stop, prop_dir, exc_dir, excite=0, **kw)

Add a microstrip transmission line port.

See also

openEMS.ports.MSLPort
AddRectWaveGuidePort(port_nr, start, stop, p_dir, a, b, mode_name, excite=0, **kw)

Add a rectilinear waveguide port.

See also

openEMS.ports.RectWGPort
AddStripLinePort(port_nr, metal_prop, start, stop, prop_dir, exc_dir, height, excite=0, **kw)

Add a stripline port.

See also

openEMS.ports.StripLinePort
AddWaveGuidePort(self, port_nr, start, stop, p_dir, E_func=None, H_func=None, kc=0.0, excite=0, excite_type=0, E_file=None, H_file=None, **kw)

Add a arbitrary waveguide port.

See also

openEMS.ports.WaveguidePort
CreateNF2FFBox(name='nf2ff', start=None, stop=None, **kw)

Create a near-field to far-field box.

This method will automatically adept the recording box to the current FDTD grid and boundary conditions.

The automatically derived directions and mirror settings can be overruled by passing them explicitly, e.g. to skip a face the antenna feed passes through:

>>> FDTD.CreateNF2FFBox(directions=[1, 1, 1, 1, 0, 1])

See also

openEMS.nf2ff.nf2ff

Notes

  • Make sure the mesh grid and all boundary conditions are finially defined.

GetCSX()
ReadFromXML(file)

Read the openEMS FDTD setup and CSX data from an *.xml file. Warning: Will call reset before reading the file!

Parameters:

file – xml file name

Reset()
Run(sim_path, cleanup=False, setup_only=False, verbose=None)

Run the openEMS FDTD simulation.

Parameters:

  • sim_path – str – path to run in and create result data

  • cleanup – bool – delete known openEMS output files from sim_path before running (only whitelisted file patterns are removed)

  • setup_only – bool – only perform FDTD setup, do not run simulation

One can also pass almost all command-line options supported by the main openEMS executable via keyword parameters (replace dashes with underscores). Supported options may vary from versions to versions, see ./openEMS –help). Examples are:

  • verbose (int) – set the openEMS verbosity level 0..3

  • numThreads (int) – set the number of threads (default 0 –> max)

  • disable_dumps (bool) – disable all field dumps for faster simulation

  • debug_material (bool) - dump material distribution to a vtk file for debugging.

  • debug_PEC (bool) - dump metal distribution to a vtk file for debugging

  • debug_operator (bool) - dump operator to vtk file for debugging

  • debug_boxes (bool) - Dump e.g. probe boxes to vtk file for debugging

  • debug_CSX (bool) - Write CSX geometry file to debugCSX.xml

  • dump_statistics (bool) - dump simulation statistics to openEMS_run_stats.txt and openEMS_stats.txt

  • showProbeDiscretization (bool) - show probe discretization information for debugging

  • nativeFieldDumps (bool) - dump all fields using the native field components

SetAbort(val)
SetBoundaryCond(BC)

Set the boundary conditions for all six FDTD directions.

Options:

  • 0 or ‘PEC’ : perfect electric conductor (default)

  • 1 or ‘PMC’ : perfect magnetic conductor, useful for symmetries

  • 2 or ‘MUR’ : simple MUR absorbing boundary conditions

  • 3 or ‘PML_8’ : PML absorbing boundary conditions

Parameters:

BC – (8,) array or list – see options above

SetCSX(CSX)

Set the CSXCAD Continuous Structure for CAD data handling.

See also

CSXCAD.ContinuousStructure

Notes

Ownership is transferred: the C++ structure is destroyed by this class, as is any structure set before. The python object stays usable, and is invalidated once it is destroyed.

SetCellConstantMaterial(val)

Set cell material averaging to assume constant material inside each primary cell. (Advanced option)

By default the material of a Yee cell is probed at four quarter-cell positions per field component, so a cell crossing a material boundary gets a blended effective permittivity and conductivity. Enabling this option probes at the cell center instead, making every cell materially homogeneous.

This must be enabled for SAR simulations. The SAR calculation uses a single cell-center conductivity and density per cell, which only matches what the FDTD run actually stepped with when the cells are homogeneous. IEC/IEEE 62704-1 additionally requires a voxel model with one material per voxel.

Parameters:

val – bool – Enable or Disable (default disabled)

SetCoordSystem(val)

Set the coordinate system. 0 –> Cartesian (default), 1 –> cylindrical

SetCustomExcite(_str, f0, fmax)

Set a custom function as excitation signal. The custom function is supplied as a string which gets parsed using Function Parser for C++.

Parameters:

  • _str – str – Custom function as string literal

  • f0 – – Base frequency.

  • fmax – – Maximum frequency.

SetCylinderCoords()

Enable use of cylindircal coordinates.

See also

openEMS.SetMultiGrid
SetDiracExcite(f_max)

Set a dirac pulse as excitation signal.

Parameters:

f_max – float – maximum simulated frequency in Hz.

SetEndCriteria(val)

Set the end criteria value. E.g. 1e-6 for -60dB

SetGaussExcite(f0, fc)

Set a Gaussian pulse as excitation signal.

Parameters:

  • f0 – float – Center frequency in Hz.

  • fc – float – -20dB bandwidth in Hz.

SetMaxTime(val)

Set max simulation time for a max. number of timesteps.

SetMultiGrid(radii)

Define radii at which a cylindrical multi grid should be defined.

Parameters:

radii – array like, multigrid radii

See also

openEMS.SetCylinderCoords
SetNumberOfTimeSteps(val)

Set the number of timesteps. E.g. 5e4 (default is 1e9)

SetOverSampling(val)

Set the sampling of the time domain dumps and probes as a multiple of the Nyquist rate (default 4). Frequency-domain dumps/probes accumulate at the plain Nyquist rate unless a box sets its own over_sampling via CSXCAD’s AddDump/AddProbe.

SetSinusExcite(f0)

Set a sinusoidal signal as excitation signal.

Parameters:

f0 – float – frequency in Hz.

SetStepExcite(f_max)

Set a step function as excitation signal.

Parameters:

f_max – float – maximum simulated frequency in Hz.

SetTimeStep(val)

Set/force the timestep. (Advanced option)

It is highly recommended to not use this method! You may use the SetTimeStepFactor instead to reduce the time step if necessary!

SetTimeStepFactor(val)

Set a time step factor (>0..1) to increase FDTD stability.

Parameters:

val – float – >0..1

SetTimeStepMethod(val)

Set the time step calculation method. (Advanced option)

Options:

  • 1: CFL criteria

  • 3: Advanced Rennings criteria (default)

Parameters:

val – int – 1 or 3 (See above)

static WelcomeScreen()

Show the openEMS welcome screen.

Write2XML(file)

Write the openEMS FDTD setup and CSX data into an *.xml file. Can be run by the standalone openEMS binary.

Parameters:

file – xml file name