Newbie question, what did I do wrong to get "Warning: Unused primitive (type: Box) detected in property: port_excite_1!"

[KJ7LNW]

I just started using openEMS, and I am trying to simulate the far field of a Yagi antenna that I have simulated before in xnec2c. In case the version matters, I am building openEMS from git.

I started by modifying the helix tutorial in python, and this is the output that I get. Notice the warning about the excitation box being unused, and the "energy" value remains zero; I am sure that is not a coincidence... I read here that unused parameters are related to meshing, so any meshing hints that you can give me in this situation would be greatly appreciated.

The frequency is much lower than in other tutorial simulations, this has a 2-meter wavelength at 146 MHz. The python script is pasted below. Please notice the comments in the code labeled "HELP" and let me know what the best practices are for those values.

Thanks so much!

Create FDTD operator (compressed SSE + multi-threading)
FDTD simulation size: 60x38x46 --> 104880 FDTD cells 
FDTD timestep is: 6.06437e-13 s; Nyquist rate: 3351 timesteps @2.46042e+08 Hz
openEMS::SetupFDTD: Warning, the timestep seems to be very small --> long simulation. Check your mesh!?
Excitation signal length is: 47240 timesteps (2.86481e-08s)
Max. number of timesteps: 1000000000 ( --> 21168.5 * Excitation signal length)
Create FDTD engine (compressed SSE + multi-threading)
Warning: Unused primitive (type: Box) detected in property: port_excite_1!
Running FDTD engine... this may take a while... grab a cup of coffee?!?
[@        4s] Timestep:         3348 || Speed:   75.2 MC/s (1.395e-03 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
[@        9s] Timestep:         7533 || Speed:   97.8 MC/s (1.072e-03 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
[@       13s] Timestep:        12555 || Speed:  120.1 MC/s (8.733e-04 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
[@       18s] Timestep:        17577 || Speed:  112.1 MC/s (9.357e-04 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
Multithreaded Engine: Best performance found using 3 threads.
[@       22s] Timestep:        22599 || Speed:  115.9 MC/s (9.053e-04 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
[@       27s] Timestep:        27621 || Speed:  118.4 MC/s (8.856e-04 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
[@       31s] Timestep:        32643 || Speed:  119.3 MC/s (8.793e-04 s/TS) || Energy: ~0.00e+00 (- 0.00dB)
[@       36s] Timestep:        37665 || Speed:  118.0 MC/s (8.888e-04 s/TS) || Energy: ~0.00e+00 (- 0.00dB)

### Import Libraries
import os, tempfile
from pylab import *

from CSXCAD import CSXCAD

from openEMS import openEMS
from openEMS.physical_constants import *


### Setup the simulation
Sim_Path = os.path.join(tempfile.gettempdir(), 'Yagi_Ant')
post_proc_only = False

unit = 1e-3 # all length in mm

# 2m band
f0 = 146e6 # center frequency, frequency of interest!
lambda0 = round(C0/f0/unit) # wavelength in mm
fc = 100e6 # 20 dB corner frequency **** HELP: is this right? Do I need to calculate 146e6 less 20dB?
feed_R = 50

### Setup FDTD parameter & excitation function
FDTD = openEMS(EndCriteria=1e-4)
FDTD.SetGaussExcite( f0, fc )
FDTD.SetBoundaryCond( ['MUR', 'MUR', 'MUR', 'MUR', 'MUR', 'PML_8'] )

### Setup Geometry & Mesh
CSX = CSXCAD.ContinuousStructure()
FDTD.SetCSX(CSX)
mesh = CSX.GetGrid()
mesh.SetDeltaUnit(unit)

max_res = floor(C0 / (f0+fc) / unit / 20) # cell size: lambda/20

# Yagi dimensions
lengths = [ 1038., 995., 959., 949., 935. ]
spaces =  [ 0, 280, 150, 520, 530 ]
space_off = -sum(spaces)/2 # center the antenna in the Z dimension
excitation_length = 5 # mm

# HELP: This is the size of the "wire" in mm.  Can it be zero, ie, a line?  I had it set to 1mm (ie, 12 AWG) 
# but was concerned about mesh size issues so I set it to 5mm for testing.  
trace_width = 5

# size of the simulation box
SimBox = np.array([max(lengths)*2, lambda0, sum(spaces)*2])

### Generate properties, primitives and mesh-grid
#initialize the mesh with the "air-box" dimensions
mesh.AddLine('x', [-SimBox[0]/2, SimBox[0]/2])
mesh.AddLine('y', [-SimBox[1]/2, SimBox[1]/2])
mesh.AddLine('z', [-SimBox[2]/2, SimBox[2]/2])

# create a smooth mesh between specified fixed mesh lines
mesh.SmoothMeshLines('x', max_res, ratio=1.4)

# copy x-mesh to y-direction
mesh.SetLines('y', mesh.GetLines('x'))
mesh.SetLines('z', mesh.GetLines('x'))


# HELP: do I really need a new piece of metal (from AddMetal()) for each element?

for i in range(len(lengths)):
    space_off += spaces[i]

    yagi = CSX.AddMetal('yagi{}'.format(i))
    if i == 1: # driver
        # HELP: I added +/-1 to excitation_length to make sure the excitation wire
        # entered the yagi box, but that didn't seem to change anything.  Should it exactly
        # abut the yagi element box?
        ex_start = [ -excitation_length-1, 0, space_off ]
        ex_stop  = [  excitation_length+1, 0, space_off ]
        yagi_gnd = CSX.AddMetal('gnd')
        yagi_gnd.AddBox(priority=10,
            start = [     -lengths[i]/2, -trace_width/2, space_off - trace_width/2 ],
            stop  = [-excitation_length,  trace_width/2, space_off + trace_width/2 ],
            );
        FDTD.AddEdges2Grid(dirs='all', properties=yagi_gnd, metal_edge_res=max_res)

        yagi.AddBox(priority=10,
            start =  [excitation_length,  -trace_width/2, space_off - trace_width/2 ],
            stop   = [     lengths[i]/2,   trace_width/2, space_off + trace_width/2 ],
            );
    else:
        yagi.AddBox(priority=10,
            start = [-lengths[i]/2, -trace_width/2, space_off - trace_width/2 ],
            stop =  [ lengths[i]/2 , trace_width/2, space_off + trace_width/2 ],
            );

    # HELP: Is this the correct way to add meshing to the "yagi" element
    FDTD.AddEdges2Grid(dirs='all', properties=yagi, metal_edge_res=max_res)

port = FDTD.AddLumpedPort(1 ,feed_R, ex_start, ex_stop, 'x', 1.0, priority=5)

## Below here is unchanged from the Helix example

# nf2ff calc
nf2ff = FDTD.CreateNF2FFBox(opt_resolution=[lambda0/15]*3)

### Run the simulation
if 1:  # debugging only
    CSX_file = os.path.join(Sim_Path, 'yagi.xml')
    if not os.path.exists(Sim_Path):
        os.mkdir(Sim_Path)
    CSX.Write2XML(CSX_file)
    from CSXCAD import AppCSXCAD_BIN
    os.system(AppCSXCAD_BIN + ' "{}"'.format(CSX_file))

if not post_proc_only:
    FDTD.Run(Sim_Path, cleanup=True)

### Postprocessing & plotting
freq = linspace( f0-fc, f0+fc, 501 )
port.CalcPort(Sim_Path, freq)

Zin = port.uf_tot / port.if_tot
s11 = port.uf_ref / port.uf_inc

## Plot the feed point impedance
figure()
plot( freq/1e6, real(Zin), 'k-', linewidth=2, label=r'$\Re(Z_{in})$' )
grid()
plot( freq/1e6, imag(Zin), 'r--', linewidth=2, label=r'$\Im(Z_{in})$' )
title( 'feed point impedance' )
xlabel( 'frequency (MHz)' )
ylabel( 'impedance ($\Omega$)' )
legend( )

## Plot reflection coefficient S11
figure()
plot( freq/1e6, 20*log10(abs(s11)), 'k-', linewidth=2 )
grid()
title( 'reflection coefficient $S_{11}$' )
xlabel( 'frequency (MHz)' )
ylabel( 'reflection coefficient $|S_{11}|$' )

### Create the NFFF contour
## * calculate the far field at phi=0 degrees and at phi=90 degrees
theta = arange(0.,180.,1.)
phi = arange(-180,180,2)
disp( 'calculating the 3D far field...' )

nf2ff_res = nf2ff.CalcNF2FF(Sim_Path, f0, theta, phi, read_cached=True, verbose=True )

Dmax_dB = 10*log10(nf2ff_res.Dmax[0])
E_norm = 20.0*log10(nf2ff_res.E_norm[0]/np.max(nf2ff_res.E_norm[0])) + 10*log10(nf2ff_res.Dmax[0])

theta_HPBW = theta[ np.where(squeeze(E_norm[:,phi==0])<Dmax_dB-3)[0][0] ]

## * Display power and directivity
print('radiated power: Prad = {} W'.format(nf2ff_res.Prad[0]))
print('directivity: Dmax = {} dBi'.format(Dmax_dB))
print('efficiency: nu_rad = {} %'.format(100*nf2ff_res.Prad[0]/interp(f0, freq, port.P_acc)))
print('theta_HPBW = {} °'.format(theta_HPBW))

E_norm = 20.0*log10(nf2ff_res.E_norm[0]/np.max(nf2ff_res.E_norm[0])) + 10*log10(nf2ff_res.Dmax[0])
E_CPRH = 20.0*log10(np.abs(nf2ff_res.E_cprh[0])/np.max(nf2ff_res.E_norm[0])) + 10*log10(nf2ff_res.Dmax[0])
E_CPLH = 20.0*log10(np.abs(nf2ff_res.E_cplh[0])/np.max(nf2ff_res.E_norm[0])) + 10*log10(nf2ff_res.Dmax[0])

## * Plot the pattern
figure()
plot(theta, E_norm[:,phi==0],'k-' , linewidth=2, label='$|E|$')
plot(theta, E_CPRH[:,phi==0],'g--', linewidth=2, label='$|E_{CPRH}|$')
plot(theta, E_CPLH[:,phi==0],'r-.', linewidth=2, label='$|E_{CPLH}|$')
grid()
xlabel('theta (deg)')
ylabel('directivity (dBi)')
title('Frequency: {} GHz'.format(nf2ff_res.freq[0]/1e9))
legend()

show()

[thliebig]

I did not yet have the time to look at your script in detail, but yes unused objects are usually not good and in this case an unused excitation box indeed results in a simulation without any excitation and thus just iterating over zeros...

# HELP: do I really need a new piece of metal (from AddMetal()) for each element?
No you do not, just create every (unique) material once and just add any object to this one material.

Use the AppCSXCAD tool to review your structure and mesh...

[biergaizi]

I also like to point out that

Energy: ~0.00e+00 (- 0.00dB)

is an immediate red flag that shows the existence of the problem. An energy of 0.00e+00 means that openEMS is simulating an empty box without any electromagnetic field inside. The reason is that the excitation port is not turned on, which is already explained by @thliebig.

[thliebig]

Attached is a rough fixed version of your script. It's not pretty or efficient, but gets some initial results. I think the mesh still needs some improvements and for a first step I went with zero thickness wires... Should be good enough for this low frequencies...
But I think the meshing of the ends of the wires could be better...
yagi.zip

[LubomirJagos]

Sorry, just trying to help. Your initial post above showed 125 MHz resonance.

I'm not exactly new to FDTD, I work as EM support specialist for 20+ years now and use FDTD all the time, but openEMS seems to have some differences in some details.

just to narrow things, I was writing my answer in hurry since I was sitting in office and was suppose to do something else and have to move for shop and then home I was really fast typing thing, that one was not thought to offend you, I put it there in way do whatever you want with that model and it will handle all parameters changes and give you right results :D like I really believe now it's done right

since I saw many people here on forum write questions and answers I will just put like people labeling themselves:

• newbies - they are always putting it they are asking basic things, this is great and should be done on all stages of modelling, basic question must always have same basic answers and are great test for every model if it really doing all basics things right as is supposed by theory, almost everytime simplest questions are most complex :D like if ports should overlapped metals, what is difference between lumped and waveport, if field in lumped port is homogenous in all points, if E and H field are complex vectors and also if Ex, Ey, Ez are complex, how to compute S11, impedance... I don't even never trust myself when I'm doing something if yes I used to make beginner mistake and then used to spent hours to repair just one line and thing start running
• HW guys - they really know how to create real model to fullfill physical rules but have sometimes problems to write parametric model to be consistent, like complex programming tasks could be difficult
• SW guys - they really know how to write complex parametric models and how to make simulation run fast, but are not sure if the model is right from physic point of view and are not really sure what results should looks like
• years+ experience - these thorought life have seen many models, seems many results, have experience with different simulation software and have something like intuition what should be done and how and have expectation this is really helpful to easily spotted bugs in designs and even in simulation core
• @thorsten - he has ability to delete this whole discussion and openEMS repository :D

openEMS is great piece of SW and is like maybe only one open-source on its level of complexity, it's like assembler in programming view, everything is done on basic level, this is great since it's not doing any optimalization and it's not hiding everything on the other side it makes things little harder to put together simulation, best way is always modify some example

in the end of day we are not philosophers and EM field is conservative one so we must come to same conclusion from all points of view

this forum and questions are moving it rocket fast due that I already spotted and repaired at least 20 bugs which if I would be looking on myself I probably never spot them, reason why I'm correcting scripts is like I spent some months to figure out how openEMS is running and when somebody asks and I look and took me like 30min to narrow script it's faster and then they can move and solve their problem and as results we all have running model and openEMS itself can move forward it's already on basic level of CST or HFSS, I was helping some students from Germany on projects and it seems it used regulary on universities (sending greetings to Hannover Uni)

what I wrote was just in hurry, I'm sorry if it sounds offending I was just really writing fast, hopefully nobody is thinking things here offending and this forum would no need any censoring or something :)

[LubomirJagos]

I was looking on debug PEC in Paraview and they have same length in Y axis, there should be putting mesh lines using linspace(ymin, ymax, ycount) and do removing overlapping gridlines, I already have this done, can put it here later, for this it will maybe not due big difference, but should be done right to get proper results, just saying that there is still space to make proper Y axis meshing, right now all elements are same length due low resolution, it's visible using debug PEC and looking in Paraview

[VolkerMuehlhaus]

This is what the AppCSXCAD mesh preview (2D, xz plane) shows with air meshed at lambda/20: the different element lengths are properly meshed. It is strange that Paraview shows something different !?

[LubomirJagos42]

I think that somehow you have right model and I overlooked something, honestly I was copying stuff there and there and making modification according your observations to confirm it's right, so probably I removed grinding or whatever, but your image is right and meshing is right, I am wondering that I screwed something, but results were good, yes that meshing is right

[VolkerMuehlhaus]

this is root thing what I was correcting everybody model on this forum since I started used openEMS models were not excited when lumped port doesn't overlapped metals

To follow up on this, and proof myself wrong:
I have not had any issues when the port was exactly touching the metal (no overlap required for me), but I can confirm that openEMS tolerates the port-metal overlap. This is indeed different from the other FDTD solver that I use at work! My testcase is here.

Thanks for pointing out my misunderstanding!

[VolkerMuehlhaus]

I am trying to simulate the far field of a Yagi antenna that I have simulated before in xnec2c.

I'm curious why you want to use openEMS for this task? NEC codes are much more efficient for such wire-only structures. FDTD would be a good fit if you need to include 2D planes or 3D objects.

[biergaizi]

I'm curious why you want to use openEMS for this task? NEC codes are much more efficient for such wire-only structures.

Be observant. I'm pretty sure that the poster of this question, KJ7LNW (Eric Wheeler), is already an expert of NEC, you can see from his profile that he's currently the software maintainer of xnec2c, a modernized NEC fork.

As a good way of learning something is to associate it with your pre-existing knowledge, I'm pretty sure KJ7LNW is trying to replicate some well-known dipole antennas that he's personally highly familiar with as a way to expand his knowledge from static MoM to full-wave FDTD.

[LubomirJagos]

I think another interesting usage of FDTD is that you can literally model signal transfer from transmitter to receiver antenna, that could be interesting usage of custom signal definition, since FDTD model is digital twin of real model and you already have antenna or any structure you can put somewhere receiver and if you model input signal you can put anywehere receiver structure, put there E field probe or UI probe and sense electric field and you should got similar results to reality, this way you should be able to do digital model of AM signal transfer, haven't been trying this, this just come to my mind, I know it will take a lot of time to calculate but as I understand FDTD is universal method and time domain signal are modelled as they are, this shouldn't be possible with FEM which is restricted to exact frequency and MoM method probably doesn't have this capability.

[VolkerMuehlhaus]

Hi Lubomir, this is certainly possible but very inefficient. The usual way to model this is to simulate each antenna separately, and then insert the calculated gain of both antennas into free space path loss calculation.

Trying to model the entire path in one large model isn't a good idea, because that model size will be very many wavelength - and that cubed in xyz direction, with at least 10 cells/wavelength (20 is better). Compared to FEM, FDTD memory requirement scales nicer (linear), but still it will be a huge simulation model, with a lot of air volume to be solved ....

[LubomirJagos]

yeah I know :( they left us to do this as semestral project at university by hand and man such a monkey job :( :( I still think it's too "synthetic" solution due you are doing aproximation based on terrain or setup (but it's usable in 90% of cases, I know we are not talking about environment influence, I know there is Rayleigh and Rician channel), I just saying that it could be nice to be concerned just about model and everything else would be calculated :D my mind is already living in future where are infinite fast CPU and components with infinite IO writing speed and everything will be calculated in real time :D :D :D (I am aware this will never happen since even light has restricted speed)
:( I know this will not happen even in 100years :( we will be doing RF similar way for next 50 years :D :D that was just dreaming, but for simple horn antenna signal transfer where both antennas are aligned it should be possible do this as like "marketing example" to got people interest :D

[KJ7LNW]

As a good way of learning something is to associate it with your pre-existing knowledge, I'm pretty sure KJ7LNW is trying to replicate some well-known dipole antennas that he's personally highly familiar with as a way to expand his knowledge from static MoM to full-wave FDTD.

@biergaizi is exactly right, trying to figure it out. openEMS has many advantages over NEC2.