Project bundle: fairbeam.project/1

A bundle is one JSON file that describes one simulation: the model and its parameter values, the solver setup, the exact geometry, the mesh, the run statistics and the post-processed results. It is written by Simulation.to_bundle() (python/fairbeam/simulation.py) and read by the viewer (typed in src/types.ts) and the VBA macro exporter (src/export/cst.ts).

Files live in public/projects/<slug>.json. Each write also rebuilds public/projects/index.json (see Index file).

Conventions

• Coordinates are [x, y, z] triples (Vec3). Axis indices are 0 = x, 1 = y, 2 = z.
• Bounding boxes are [[xmin, ymin, zmin], [xmax, ymax, zmax]].
• The JSON is written compactly with allow_nan=False, so it never contains NaN or Infinity.
• Files are written atomically: the writer creates <slug>.json.tmp and then renames it.
• Rounding: mesh lines have 4 decimals, geometry 6, S11 5, Zin 3, far-field angles and directivity 2.

Top level

generator

model

This is the model file's MODEL dict (id, name, description, and optionally reference) spread into the object, plus:

Each Param is dataclasses.asdict(Param) plus the resolved value:

units

solver

excitation has one of two shapes:

• Default {"type": "gaussian-derivative", "f_min", "f_max", "expression", "dc_free": true}. expression is the fparser formula in t (seconds) passed to openEMS' custom excitation. The pulse has unit peak and is -20 dB at f_max.
• openEMS Gaussian {"type": "gaussian", "f0", "fc", "f_min", "f_max", "dc_free": false}, where f0 = (f_min + f_max) / 2 and fc = (f_max - f_min) / 2.

parts

Physical CSXCAD properties with their primitives, in order of first appearance. Helper properties (DumpBox, ProbeBox, Excitation) and the LumpedElement properties created by ports are excluded. Ports are listed in ports instead.

material:

material.dispersion is the model as simulated, with frequencies in Hz and times in s, in openEMS' conventions (e^{+jωt}):

Primitives

Every primitive has these fields:

The remaining fields depend on kind:

• box: start, stop (Vec3), which are opposite corners. A box with zero extent on one axis is a sheet, for example a patch or a ground plane.
• polygon: a planar polygon (zero thickness).
  • normal is the normal axis index n (0, 1 or 2).
  • elevation is the plane's coordinate along axis n.
  • points is a list of [a, b] pairs in the plane.
• linpoly: the same fields as polygon, plus length. The polygon is extruded along the normal from elevation to elevation + length (length may be negative).
• cylinder: start, stop (Vec3) are the axis end points, and radius is the radius.
• cylindricalshell: a tube (CSXCAD CylindricalShell). start, stop as for cylinder; radius is the radius of the middle of the wall and shell_width the wall thickness, so the tube spans radius - shell_width / 2 to radius + shell_width / 2.
• sphere: center (Vec3) and radius (CSXCAD Sphere).
• rotpoly: a solid of revolution (CSXCAD RotPoly turned a full circle; the designer's cone and torus). points are [radial, axial] pairs of a closed outline, turned about the line through origin (Vec3) along axis index axis (0, 1 or 2): a point is inside when its distance from that line and its coordinate along it, minus origin, lie in the outline. Radial values are never negative. The exporter computes bbox itself (CSXCAD's ignores the rotation) and writes full turns in the plane through the axis; an additional native affine transform is represented by a transformed wrapper.
• curve: a thin wire along a polyline (CSXCAD Curve). points is a list of Vec3. It has no radius: openEMS puts it on the nearest mesh edges, so its effective radius is a fraction of a cell. Viewers draw it as a tube of a nominal radius.
• wire: the same with a radius (CSXCAD Wire), rasterised as a volume.
• polyhedron: a closed solid (CSXCAD Polyhedron). vertices is a list of Vec3 and faces a list of vertex-index lists (triangles; CSXCAD only rasterises triangular faces correctly). Faces are oriented outward in Fairbeam's models, but readers should not rely on it.
• transformed: an exact affine instance of a supported primitive. primitive contains that exact local shape, matrix is a row-major 4×4 homogeneous matrix mapping column vectors from local to world coordinates, and bbox is the world-space axis-aligned bound. It is a separate kind so older readers cannot mistake local coordinates for world geometry. Readers that do not support the wrapper should use bbox as an explicitly approximate fallback.
• bbox: fallback for CSXCAD primitive types Fairbeam does not export exactly. source_kind holds the CSXCAD type name, and only bbox describes the shape. When the native type is understood but its exact local geometry is not, the bound is transformed into world coordinates and transformed: true is set.

Added later (additive): curve, wire and polyhedron. Older readers treat the new kinds as unknown and should fall back to bbox. The drawing shows polyhedra by their hull and feature edges and wires as polylines.

Added with exact arbitrary-angle designer transforms (additive): transformed. Older readers treat the wrapper as unknown and should fall back to its world-space bbox. Native simulation keeps the local CSXCAD primitive and applies its affine matrix. Zero-thickness metal sheets must remain parallel to the solver coordinate planes; lossy sheets must also retain their local normal because openEMS selects tangential loss from the local CSXCAD bounds. The VBA macro exporter skips transformed geometry with a warning.

Added with the designer's cylinder-shell and sphere shapes (additive): cylindricalshell and sphere. The viewer, the drawing and the VBA macro exporter (a Cylinder with an inner radius, a Sphere) rebuild them exactly; the fabrication export treats a vertical tube through the substrate as a plated via of its outer diameter and skips spheres with a warning.

Added with the designer's cones and tori (additive): rotpoly. The viewer turns the outline exactly (a lathe), the drawing shows a circle along the axis and the silhouette from the side, the VBA macro exporter writes a Cone (or a Cylinder for equal radii) or a Torus when the outline is one, and skips other outlines with a warning; the fabrication export skips it with a warning.

In-plane coordinate convention (polygon and linpoly). This follows CSXCAD. For normal axis n:

• the first coordinate of each point lies along axis (n + 1) % 3
• the second coordinate lies along axis (n + 2) % 3

Note the y-normal case: points are (z, x), not (x, z). The 3D position of point [a, b] is:

p[n] = elevation;  p[(n+1)%3] = a;  p[(n+2)%3] = b

ports

Grouped ports. This additive field preserves one logical port with N physical resistive feeds. R and the result key refer to the logical mode. For signed member signals sᵢUᵢ, sᵢIᵢ, Parallel reports U = ΣsᵢUᵢ/N and I = ΣsᵢIᵢ, with member resistance N·R; Series reports U = ΣsᵢUᵢ and I = ΣsᵢIᵢ/N, with member resistance R/N. Sources excite all members of the selected port, with signs and gap-length normalization. The existing incident/reflected-wave and S-matrix fields use these modal signals. Orthogonal modes are excluded from modal power; the physical power sum can differ when members are imbalanced. Absence of group keeps the ordinary port behavior. Malformed groups are refused on reopen instead of losing members.

Waveguide ports. The port excites one TE_mn mode with its analytic field profile and measures the mode voltage and current by projecting E and H in the probe plane onto the mode functions. The reference impedance is the frequency-dependent TE wave impedance Z_TE = η0 k / β = η0 / √(1 − (f_c/f)²), so u_inc, u_ref split the probe signals into forward and backward waves and S11 = u_ref / u_inc is the ratio of reflected to incident mode amplitude. results.ports[k].z_ref is Z_TE at the band center and z_ref_f holds it per frequency; there are no time signals (they need a scalar reference). Terminate the guide behind the port in a PML (run it through the boundary, auto_mesh(pad=[…, 0, …])) so the backward wave is absorbed. python/examples/waveguide_thru.py checks the implementation (docs/VALIDATION.md section 13). A Python model of a guide homogeneously filled with a real, nondispersive ε_r, μ_r can pass them to Simulation.waveguide_port(..., eps_r=, mu_r=). The port then uses β = √(k0² ε_r μ_r − k_c²) and Z_TE = η0 μ_r k0 / β, R, f_cutoff, z_ref and z_ref_f are those of the filled guide, and the port entry records eps_r and mu_r (both absent for the air reference). Designs always use the air reference.

Waveguide port power. openEMS' mode-matching probes read the power of the mode low, by an amount set by the size of the mesh cells next to the guide walls (first order in that size: 4.3 % for the horn's WR-90 feed at 20 cells/λ, 8.6 % at 30, the same at every frequency): the template is normalized over the full node areas, but a node on a PEC wall carries half the air field. Simulation.evaluate computes the deficit from the mesh lines (fairbeam.wgport, the probe projection applied to the ideal mode on the Yee lattice) and multiplies the port's U and I by the square root of the factor, so pacc_w, the incident and reflected power and the efficiency are the mode's power. S11, Z_in and the S-parameters (ratios) do not change, except that in a multi-port run the amplitudes of ports with different wall cells now carry their own factors. The factor is stored as results.ports[k].probe_power_factor; sim.wg_probe_correction = False switches it off. Verified for TE10 against the exact flux through the guide; it is not applied when the probe box does not describe a closed guide (factor outside 0.9-1.3).

Guides sharing a wall. Where two guides are separated only by a zero-thickness PEC sheet (e.g. a branch-guide coupler), the probe nodes on that sheet interpolate the fields of both guides, so the neighbouring guide leaks into the port's U and I. fairbeam.wgport.inset_mode_probes(port, cells=1) (opt-in, rectangular TE10 ports on a Cartesian mesh) moves only the E/H probe boxes cells mesh intervals in from both broad walls; the excitation, mode origin, port corners and measurement plane stay where they are, and the power factor above is computed for the inset probes (TE10 is uniform along b). Call it on every port of the S-matrix after the mesh is final. Without it the probes span the full guide, as before.

lumped_elements

Written by Simulation.lumped_element(...) and its shortcuts lumped_resistor(...), lumped_inductor(...) and lumped_capacitor(...) (a Design's resistors/RLC loads use the same call). The element is an openEMS LumpedElement spread over the box start..stop, with current along direction. It is not a part (it is excluded from parts) and not a port.

The combined native series element has not passed its ideal-circuit check (rf-rlc-workflows (opens in a new tab)); a series LC built from a separate lumped_inductor and lumped_capacitor connected geometrically in series is the alternative.

Half space and mirror planes

half_space. When the z- boundary is PEC, the bundle carries:

{"axis": "z", "side": "min", "position": <first z mesh line>, "kind": "PEC"}

This means the physical problem is the half space z ≥ position above an infinite PEC ground plane (image theory). The ground is not a part in parts. The viewer draws it as a ground plane. The far-field surface and polar cuts show only θ ≤ 90°, because directions below the ground do not exist physically. For any other boundary setup, half_space is null. Only the z- PEC case is currently encoded here.

mirror_planes (per far-field entry) is the number of PEC or PMC boundaries, on any face. openEMS mirrors the NF2FF recording surface at such boundaries and integrates the image as well. The raw Prad therefore covers the full image space, and the Dmax derived from it is too low by the same factor. Fairbeam corrects both by 2^mirror_planes:

prad_w   = Prad_openEMS / 2^m
Dmax     = Dmax_openEMS · 2^m

so directivity, efficiency and gain refer to the physical half space (or quarter space when m = 2, and so on).

mesh

run

Statistics parsed from openEMS' captured stdout/stderr. null if the model was not simulated. Fields marked ? are absent if the pattern was not found in the log.

results

null if the model was not simulated.

If no port is excited, bands and farfield are empty and signals is {}. For multi-port runs, ports, bands and signals refer to the first excited port. ports holds only driven ports, each with its own reflection from the run in which it was driven.

ports[k]. All arrays are aligned with frequency.

Band. A band is a contiguous run of frequency samples with 20·log10|S11| < -10 dB.

The JSON band fields retain their original meanings. In the CSV export, f_center_GHz is the middle of the edges, f_best_GHz is the JSON f_center, and fractional_bw divides by the middle; edge_lo and edge_hi retain the open-edge flags.

FarField. The pattern frequencies are the bands' f_center values, the frequency of minimum S11 in each band (at most 4). If there are no bands, the frequency of minimum S11 is used. A model can choose its own (sim.pattern_freqs, e.g. the band edges and center of a broadband horn). --pattern overrides all of these.

cp. With the IEEE convention and openEMS' e^{jωt} phasors, the right- and left-hand circular components of the far field are E_R = (E_θ + jE_φ)/√2 and E_L = (E_θ − jE_φ)/√2 (for a wave along +z, RHCP rotates from x to y). Grids are indexed [theta][phi] like directivity_dbi.

The pattern CSV export adds rhcp_dBi, lhcp_dBi and axial_ratio_dB columns and the far-field CSV the boresight values.

prad_w and pacc_w are absolute values for the unit-amplitude excitation. They are typically very small numbers, and only their ratio is meaningful.

Lossless models. A model with no loss mechanism at all (PEC metals, loss-free materials, no resistors) radiates everything it accepts, so its radiation efficiency is 1 and prad_w / pacc_w only measures how well the two numerical powers agree. A Python model says so with sim.lossless = True (the pyramidal horn does); evaluate() checks the claim (a lossy material or a resistor voids it, with a warning) and then reports rad_efficiency 1, gain = directivity, while the simulated ratio is within 5 % of 1, keeping it in rad_efficiency_raw and a note; beyond 5 % the simulated value is reported with a warning. prad_w and pacc_w are never altered. The horn read Prad / Pacc 1.037 at cpw 20 and 1.08 at cpw 30. The NF2FF box was not the cause: an exact Poynting flux (raw E and H on the Yee lattice) through the feed guide, the five-face box and planes across the horn agree to 0.1-0.4 %, whereas the waveguide port's mode-matching probes read the guide power 4.3 % (cpw 20) and 8.6 % (cpw 30) low. The earlier "box +2.4 % / +5.8 % against the feed flux" compared with a node-interpolated flux, which has the same deficit at the metal walls. Simulation.evaluate now calibrates the waveguide port (below, probe_power_factor); the horn's Prad / Pacc is 0.992-0.995 (cpw 20) and 0.995-0.998 (cpw 30), and the 5 % rule above is kept as a guard. The diagnosis also found a mesh bug: polyhedron vertices, which CSXCAD stores in single precision, put a mesh line at y = 5.0799999 instead of the wall at 5.08, so the edges on it were not metal and the guide was a cell too tall (E_z at 6 % of E_y in the guide; fairbeam.automesh now snaps such coordinates back).

efficiency

EfficiencySweep. Optional (absent unless requested): the radiation efficiency as a 1D result over frequency. The NF2FF box records time-domain dumps, so after the run openEMS transforms them at N frequencies spread evenly from f_min to f_max (default 21, 3 to 201). Only the powers are kept, no patterns. One entry per driven port, with port set as for farfield[].port (a 1-port run has one entry).

Total efficiency is rad_efficiency · (1 − |S11|²) with S11 from ports[port] at f (interpolated on frequency). At a pattern frequency the sweep's Prad equals farfield[].prad_w.

Reliability. Away from the match the port reflects almost all of the incident power, and pacc_w = P_inc (1 − |S11|²) is a small difference of two large numbers. Stopping the run at the end criterion truncates the ring-down of the port signals, which leaves an error of about the same absolute size at every frequency; relative to a small pacc_w it is large, and the ratio zig-zags. pacc_error estimates it as the change of ½·Re(U·I*) when the last tenth of the ring-down (after the excitation pulse) is left out of the DFT; while the signals decay, what the run did not record is of that order or smaller. Simulated on the patch starter (11 frequencies, 1.47–3.19 GHz, GPU):

Prad moved by at most a few % between the three runs, pacc_w by up to 33 % above resonance (where 1 − |S11|² is 3 to 4 % and the excitation spectrum is weakest). The estimate was 2–51 % at −50 dB against 0.4–24 % actual and 0.2–20 % at −60 dB against 0.1–7 % (the actual taken against the −70 dB run), so it errs on the safe side. The NF2FF angular grid (90°/180° against 5°/10°: identical Prad) and the dump sampling (every Nyquist/4 = 37 timesteps, 8 samples per period at f_max, as for the port probes) are not the cause. The truncation error of Prad (a few %) is not included.

signals. Port time signals, downsampled by a constant stride to at most about 1500 points.

Multi-port runs

fairbeam run (and sweep/converge) build the model once per excited port inside fairbeam.simulation.excite_only(n). That run drives port n and leaves every other port in place, terminated in its resistance. Default: all ports for models with up to 4 ports, otherwise port 1. --excite all|1,3 overrides. A 1-port model runs exactly as before, but its bundle also gets a 1 × 1 sparams.

sparams

Definition. For port i with real reference Z_i, U_i and I_i are the frequency-domain port voltage and current (current flowing into the structure). The power waves are a_i = (U_i + Z_i I_i) / (2 sqrt(Z_i)) and b_i = (U_i − Z_i I_i) / (2 sqrt(Z_i)), which are openEMS' uf_inc and uf_ref divided by sqrt(Z_i). With the waves of the run that drives port j as column j of the matrices A and B, the complete matrix is S = B A^-1 at every frequency. This is exact even though a terminated FDTD port has a small nonzero incident wave. With a partial excitation, the known columns are S_ij = b_i / a_j. For equal Z_i these are the usual S-parameters; otherwise they are power-wave S-parameters referenced to each port's own Z_i. results.ports[k].s11_* equals S_kk for every driven port k.

qa.

element_patterns

Present for antennas (models with an NF2FF box) when several ports are driven, or when --element-patterns on is given. It holds the complex far field of each driven port per unit incident wave, with all other ports terminated, so mutual coupling is included. See Arrays and beam steering for how to combine them.

Units: E in V/m (peak phasor) at radius_m, for an incident power wave a = U_inc / sqrt(Z_ref) = 1 sqrt(W). Radiation intensity is U = r² (|E_θ|² + |E_φ|²) / (2 η0) and incident power is ½ |a|². The array field for weights w_j is Σ w_j E_j.

Element-pattern encodings

Each of e_theta_re, e_theta_im, e_phi_re, e_phi_im is a base64 string of n_θ · n_φ little-endian values, row-major [theta][phi].

• "i16le-base64-scaled" (the writer's default, python/fairbeam/multiport.py): signed int16 q = round(v / scale · 32767), and v = q · scale / 32767. scale is a number in each fields entry: the largest |value| over that entry's four arrays (one scale per port and frequency, so E_θ and E_φ share it; scale 0 means all zeros). The quantisation step is 1/32767 of the peak component, about −90 dB. On the 2×1 and 4×1 patch arrays this changes synthesized directivity by at most 0.01 dB where D > Dmax − 50 dB, for uniform, steered (0°, 30°, 60°) and tapered weights, with the same beam direction and HPBW within 0.003°.
• "f32le-base64" (bundles written before): float32, no scale. Twice the size; float32 noise hardly compresses, so gzip gains almost nothing on either form.

The viewer (src/lib/sparams.ts) and fairbeam.array read both. Non-finite far fields are written as "f32le-base64". fairbeam.multiport.reencode_element_patterns(bundle) converts an older bundle in place without touching anything else.

fields

Optional; present only for runs with fairbeam run --fields (python/fairbeam/fields.py). For every plane that holds zero-thickness metal (a box sheet or a polygon; at most 4 planes, smallest first), openEMS records a frequency-domain rot(H) dump exactly on the sheet's mesh plane. On a PEC sheet the in-plane components equal the surface current density divided by the constant normal dual-cell width, so the stored map is the surface current magnitude |J_s|, up to one constant per plane. It is resampled from the FDTD mesh onto a regular grid and normalized per plane and frequency.

FieldPlane

FieldFrequency

The peak value sits at the metal edges, where the current is singular and only as resolved as the mesh; compare shapes and relative levels, not the absolute peak.

field_planes

Optional; present only for runs with field planes (fairbeam run --field-plane, a design's monitors.field_planes; python/fairbeam/field_planes.py). One entry per plane and frequency. For each plane openEMS records a frequency-domain E (dump type 10) or H (type 11) dump with node interpolation on the mesh line nearest the requested position, across the whole simulation domain in the plane. The stored map is the phasor magnitude, resampled bilinearly from the FDTD mesh onto a regular grid (the step of the finest mesh cell in the plane, at most 200 samples along the longer side) and rounded to 3 significant digits. The complex components are stored beside it as an optional 8-bit phasor.

Normalization. openEMS' frequency-domain dumps are the single-sided Fourier transform 2 Δt Σ f(t) e^(−jωt), the same transform as its port voltages. Scaled by sqrt(1 W / P_inc(f)), with P_inc = |u_inc|² / (2 Re Z_ref) of the driven port, they become the peak phasor amplitude for 1 W incident (stimulated) power at the driven port. Without a single driven port they stay the raw transform (unit: "arb.", normalization: "none"). The maps come from one excitation, as for fields: a multi-port run records them in the first excited port's run only.

FieldPlaneMap

FieldPlanePhasor (optional). The complex components of the same resampled nu × nv grid, so a viewer can show the phase and the instantaneous field Re{F e^(jωt)} over one period (the designer's 2D field map tab and the 3D view animate it).

The values are scaled like magnitude (1 W incident power) and, with a driven port, turned by the phase of its incident voltage wave (× conj(u_inc) / |u_inc|): phase 0 is that wave at t = 0, not the arbitrary time origin of the excitation pulse. Without a driven port (normalization: "none") the phase is that of the raw transform and has no physical reference. The time convention is e^(+jωt): the field at phase φ is Re{F e^(jφ)}.

Size: about 80 kB of JSON per 106 × 106 map, about 150 kB at the 200-sample cap; with the design limits (4 planes × 4 frequencies) at most about 2.5 MB. The phasor adds 6 bytes per pixel for abs maps (2 for a single component) as base64: about 90 kB at 106 × 106 (abs), 320 kB at 200 × 200, so at most about 5 MB more for 16 full-size abs maps. Caveats: with node interpolation the normal E component right at a metal sheet or a dielectric interface is averaged over the two neighboring cells, so put the plane a cell away for clean fringing fields; the outer cells of a PML boundary hold absorbed, non-physical fields.

Index file

public/projects/index.json is rebuilt after every write, or by fairbeam index [folder]. It covers every *.json in the folder (except itself) whose schema starts with fairbeam.project/. Entries are sorted by model id, then name.

{
  "projects": [
    {"file": "patch-antenna.json", "name": "Rectangular patch antenna", "model": "patch-antenna",
     "created": "2026-09-24T22:24:15+0300", "simulated": true, "bands": [2.433], "cells": 97152}
  ],
  "updated": "2026-09-24T22:25:42+0300"
}

Versioning

Adding optional fields does not change the schema id: lumped_elements, results.sparams, results.element_patterns, farfield[].port, run.port_runs, fields.port, results.efficiency, run.efficiency_time_s, run.engine / engine_requested / exact_endcriteria, field_planes, efficiency[].pacc_error / reliable, rad_efficiency_raw and parts[].conductor and parts[].void were added this way. Removing or renaming fields, or changing units or indexing, bumps it to fairbeam.project/2. When the schema changes, src/types.ts changes in the same commit.