Emport

Overview

This repo provides a FDTD (Finite Differences Time Domain) simulator called emport for solving RF circuits. Emport outputs its simulation results as s-parameters in the touchstone file format. It is not limited in the number of s-parameter ports it can excite, so it can be used for example to "port tune" a multielement filter. It can also run its simulations on a GPU, which other open source projects either do not support or if they do cannot generate s-parameters using a GPU.

The simulator is written in Python and requires the libraries numpy and pytorch in order to execute. To install them use:

$ pip install numpy torch
OR
$ conda create -y -n torch -c pytorch pytorch
$ conda install -y -n torch numpy

The geometry and material information needed to run a simulation are provided as OFF geometry files. The contents of the OFF file constitute the physical structure of the model while the name of the OFF file identifies the material the geometry represents. These OFF files can be zipped up into one or many ZIP files for your convenience.

Emport surrounds your model within a PEC cage. The software does not support any type of absorbing boundaries, such as PMLs. The simulator was constructed as a tool to help design devices such as filters or other circuits that will be placed inside an enclosure, not for antennas necessarily or solving "scattering" problems like radar or MRI.

Examples

To simulate the microstrip lowpass filter example included [1], run the following below. The simulator will use the OFF files in the ZIP file to construct the lowpass filter. The --df option sets the frequency step you want the s-parameter results to provide. The --pitch option sets the length of a side of a FDTD grid cell in millimeters to use. The --stop option tells emport which port it should excite last.

$ emport --df 5e9 --stop 1 --pitch .264 examples/lowpass.zip
Grid is 27.456 x 24.552 x 9.504 mm in size or 348192 cells
GPU Memory Usage: 0.015 GB allocated + 0.021 GB reserved
Running simulation: exciting port 1
N= 393 / 393
FDTD simulation time: 0.46 sec
# HZ S DB R 50
5.0048e+09     -9.850    50.07    -8.891   148.07     0.000     0.00     0.000     0.00
1.0010e+10     -6.888  -113.39    -9.955   -35.89     0.000     0.00     0.000     0.00
1.5014e+10     -3.927    85.87   -11.398   132.76     0.000     0.00     0.000     0.00
2.0019e+10     -6.406   -94.63   -12.901   -62.70     0.000     0.00     0.000     0.00
2.5024e+10     -4.896    85.06   -15.604    98.09     0.000     0.00     0.000     0.00
3.0029e+10    -15.132  -125.91   -18.439  -109.31     0.000     0.00     0.000     0.00
3.5033e+10     -9.220    42.12   -21.453    32.00     0.000     0.00     0.000     0.00
4.0038e+10    -10.064   117.21   -22.218   164.47     0.000     0.00     0.000     0.00
4.5043e+10     -9.769   -34.56   -20.953   -48.50     0.000     0.00     0.000     0.00

To simulate a 1296 MHz interdigital filter [2], run:

$ emport --df 5e9 --pitch 1 examples/fisher.zip
Grid is 90 x 28 x 68 mm in size or 171360 cells
GPU Memory Usage: 0.007 GB allocated + 0.021 GB reserved
Running simulation: exciting port 1
N= 260 / 260
FDTD simulation time: 0.28 sec
GPU Memory Usage: 0.007 GB allocated + 0.021 GB reserved
Running simulation: exciting port 2
N= 260 / 260
FDTD simulation time: 0.27 sec
# HZ S DB R 50
1.9971e+09     -1.875    22.16   -55.293   -56.97   -55.293   -56.97    -1.875    22.16
3.9943e+09     -0.182    -2.33   -59.472   154.44   -59.472   154.44    -0.182    -2.33
5.9914e+09     -1.047   -51.54   -60.071     2.45   -60.071     2.45    -1.047   -51.54
7.9886e+09    -16.478  -149.57   -58.951  -152.98   -58.951  -152.98   -16.478  -149.57
9.9857e+09     -3.156    25.46   -56.457    50.32   -56.457    50.32    -3.156    25.46
1.1983e+10     -2.501   -31.23   -52.593  -109.99   -52.593  -109.99    -2.501   -31.23

Also see the examples.ipynb Jupyter notebook in the repo for plots and more.

Usage

$ emport --help
usage: emport [-h] [--output OUTPUT] [--export EXPORT] [--start START] [--stop STOP]
              [--pitch PITCH] [--df DF] [--steps STEPS] [--ntau NTAU] [--ndelay NDELAY]
              [--zline ZLINE] [--dtype DTYPE] [--device DEVICE]
              filename [filename ...]

positional arguments:
  filename         OFF geometry file comprising the FDTD simulation, ZIP files accepted

optional arguments:
  -h, --help       show this help message and exit
  --output OUTPUT  write touchstone output to a file, instead of console (default: None)
  --export EXPORT  save voxelization as an OBJ file, no simulation (default: None)
  --start START    first port to excite, starting from 1 (default: None)
  --stop STOP      last port to excite, starting from 1 (default: None)
  --pitch PITCH    length of a side of a uniform cell in mm (default: 1.0)
  --df DF          frequency step in Hz to resolve, sets simulation steps (default: None)
  --steps STEPS    explicitly set number of simulation steps (default: None)
  --ntau NTAU      pulse width of excitation in units of simulation steps (default: 20)
  --ndelay NDELAY  time delay of excitation in units of pulse widths (default: 6.5)
  --zline ZLINE    line impedance of ports in ohms (default: 50)
  --dtype DTYPE    simulation data type of "half", "float", or "double" (default: float)
  --device DEVICE  simulation device of "cuda" or "cpu", will autodetect by default (default:
                   None)

Materials

To identify your OFF geometry as being made out of a particular material, give the OFF file the same name as the material. For example, if the material is made out of silver, name it silver.off. Emport supports the following material names: pec, silver, copper, gold, aluminum, brass, steel, and air. Any material it does not know, emport will consider material as a PEC (Perfect Electrical Conductor). If you have several OFF geometries made out of the same materal, you can prefix the material name with a group name and then a dash.

For example the interdigital filter uses the following OFF files and file names:

$ unzip -l examples/fisher.zip
Archive:  examples/fisher.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
     2524  2022-01-12 08:16   rods0-brass.off
     2456  2022-01-12 08:16   rods1-brass.off
     2474  2022-01-12 08:16   rods2-brass.off
      492  2022-01-12 08:16   cover1-sigma62.11e6.off
      478  2022-01-12 08:16   cover2-silver.off
     1625  2022-01-12 08:16   openbox-silver.off
      479  2022-01-12 08:16   tap1-copper.off
      465  2022-01-12 08:16   tap2-copper.off
      479  2022-01-12 08:16   port1.off
      465  2022-01-12 08:16   port2.off
---------                     -------
    11937                     10 files

To support other materials, for example PCB substrates with a certain permittivity, use the following naming format for the material: er99.99e9 or er_99.99e9. The underscore can be replaced with a space if needed. For conductors, the naming convention, assuming a permittivity of 1, is: sigma99.99e9 or sigma_99.99e9. To define both permittivity and conductivity the naming format is er99.99e9_99.99e9 or er_99.99e9_99.99e9.

To create a port, use a material name of port99 or port_99, starting from port number 1. The port will be a "lumped" port. The opposite faces of the port should overlap a conductor. A port can only be represented by a cube or a plane, but not a cylinder for example.

The PEC boundary will abutt the bounding box of your model with a padding of one cell. To enlarge the bounding box use the air material. The air material will be dropped and ignored when the model is voxelized. However it will be considered when calculating the model's bounding box. See the lowpass and coupler examples.

OFF Files

Provided in the example directory are scripts for generating the OFF file simulation model examples. The scripts use the python library pycsg to generate these models. To install pycsg run:

$ pip install pycsg

In addition there is a utility python library file, named csgsave.py, provided in the same directory. It contains code for saving the CSG solids pycsg creates as OFF files. Of course, you can also use FreeCAD or OpenSCAD to generate your own OFF files and simulation models as well.

Voxelization

The simulator performs the voxelization using a "z-buffer" algorithm. This algorithm has the advantage that it will fill mesh geometries. Unfortunately it also has problems in that it might fill holes that it should not. This is especially so with hollowed cubes. To rectify this, any geometry with holes needs to be broken up. For example an interdigital filter inside a hollowed cube as an enclosure needs to have a cover. In addition this cover needs to be placed in a separate OFF file than the box. See the provided interdigital filter for an example of this.

To inspect how well the model is voxelized, use the --export option. This will output the voxel result as an OBJ file and skip the simulation.

$ emport --pitch 1 --export examples/fisher_voxel.obj examples/fisher.zip
Grid is 90 x 28 x 68 mm in size or 171360 cells

The export process fuses all similar material into one mesh. So to create a cover that can be hid in your CAD software, use a different material, but not very different, for the cover. See again the interdigital filter example.

Planes can also be voxelized. This is used to create microstrip models. Emport recognizes a geometry as a plane if uses an entire OFF file for itself and it has one dimension that is constant. Also only one rectangular plane per OFF file is supported at the moment. See the lowpass filter and microwave coupler in the example directory.

Installation

To build emport, run the following then copy it to the directory you want.

$ sh build.sh
SRC="__main__.py emport.py parseoff.py conf.py writeobj.py voxzbuf.py touchstone.py verbose.py"
(cd src; python -m zipfile -c ../emport.zip $SRC)
echo '#!/usr/bin/env python3' | cat - emport.zip > emport
rm emport.zip
chmod 755 emport

Notes

Pytorch does not support the M1 GPU yet. I could not use tensorflow, which does support the M1 GPU, because my code requires a mutable tensor which tensorflow does not provide.

Also I have issues with pytorch over reserving space on the GPU. Unfortunately I have not resolved the issue. I cannot find any memory leaks in the code.

Footnotes

[1] The Finite-Differnce Time-Domain Method for Electromagnetics with MATLAB Simulations, Elsherbeni and Demir. Section 6.2 contains two of the examples provided here: a lowpass filter and a microwave coupler. The examples are from Application of the Three-Dimensional Finite-Difference Time-Domain Method to the Analysis of Planar Microstrip Circuits, David Sheen, Sami Ali, IEEE MTT Vol 38, No 7, July 1990, p.849.

[2] Interdigital Bandpass Filters for Amateur V.H.F/U.H.F. Applications, High-Q Filter Construction Made Easy, Reed Fisher, March 1968 QST; reproduced in the ARRL Handbook 2017, p11.32, figure 11.63.