Palace guide¶
Use gsim.palace for driven RF and microwave simulations, eigenmodes, electrostatics, magnetostatics, and
boundary modes.
This guide covers solver configuration, meshing, and result processing. Class and function links open the API reference.
Solver settings¶
Numerical and problem-specific settings live under sim.solver. Each simulation
exposes its applicable problem group alongside the common controls:
import gsim.palace as pa
sim = pa.EigenmodeSim()
sim.solver.order = 1
sim.solver.linear.tolerance = 1e-9
sim.solver.linear.max_iterations = 400
sim.solver.eigenmode.num_modes = 2
sim.solver.eigenmode.target = 4e9 # Hz; required before meshing/exporting
sim.solver.eigenmode.tolerance = 1e-9
sim.solver.eigenmode.save = 2
The linear tolerance controls each linear solve. The eigenmode tolerance controls
eigenvalue convergence. They are independent. All Palace simulation types default
to GMRES with complex MUMPS multigrid, field order 2, 400 maximum linear
iterations, and "CPU". Linear tolerance defaults to 1e-6, except for
EigenmodeSim, whose linear and eigenvalue tolerances both default to 1e-9.
MagnetostaticSim is the exception to the solver: its curl-curl operator is singular, so
it defaults to Palace's iterative choice, the AMS preconditioner with conjugate
gradients at a linear tolerance of 1e-8, and refuses a direct solver_type or the
BoomerAMG preconditioner.
An omitted linear tolerance uses the simulation-specific default through grouped
dictionaries, settings models, and legacy numerical constructors or assignments.
An explicitly supplied tolerance, including 1e-6, is preserved.
The configurable multigrid and error estimator controls live under sim.solver.linear:
| Setting | Default | Meaning |
|---|---|---|
solver_type |
"MUMPS" |
Coarse solver backend; "Default" asks Palace to choose. |
mg_max_levels |
100 |
Maximum multigrid levels; Palace uses the available hierarchy. Set 1 for a full-system solve. |
pc_mat_real |
False |
Set True to use a real approximation of the preconditioner matrix. |
complex_coarse_solve |
True |
Use a complex coarse solve for complex-valued problems. |
estimator_tolerance |
automatic: 1e-2 with AMR off, Palace's 1e-6 with AMR on |
PCG tolerance of the error estimator (the AMR indicator). |
estimator_max_iterations |
automatic: Palace's 10000 |
0 skips the projection solve; the indicator is then meaningless, and with AMR on gsim warns; pass estimator_disabled=True to validate_solution. |
estimator_mg |
automatic: Palace's False |
Multigrid preconditioner for the estimator; costs memory; worth it at field order 1. |
The three estimator settings default to None, which means automatic: gsim
chooses their values by AMR state when it writes config.json. AMR is on when
the refinement max_its, set with sim.set_refinement(max_its=...), is above
zero; the default 0 leaves it off. With AMR off, nothing reads the indicator
closely, so gsim writes EstimatorTol 1e-2. With AMR on, the indicator decides
where to refine and when to stop, so gsim writes no estimator key and Palace's
defaults apply. Explicit values win key by key; assign None to return to
automatic. To restore Palace's own estimator with AMR off, set
estimator_tolerance=1e-6. With AMR off, the error estimator never affects the
S-parameters or other results. With AMR on, the indicator decides the refined
mesh, and so the results computed on it.
AMR-off runs compute the indicator to this loose tolerance, so the
error_indicators of a result can read slightly higher than with Palace's default.
Real-only problems such as electrostatics still solve real equations. The complex controls do not turn materials or fields into complex quantities in those problems. MUMPS no longer forces one Krylov iteration, disables multigrid, or disables the mesh error estimator or divergence-free projection. Explicit settings are exported without backend-specific overrides.
sim.solver.linear.pc_mat_real = True
sim.solver.linear.complex_coarse_solve = False # lower-memory real approximation
sim.solver.linear.mg_max_levels = 1 # full-system solve; can need much more RAM
solver_type="SuperLU", "STRUMPACK", and "Default" remain available.
preconditioner="AMS" or "BoomerAMG" applies when solver_type="Default".
Use pc_mat_real=True and complex_coarse_solve=False to request a real
preconditioner with another backend. These settings can also be supplied to
set_solver(...) or in the constructor's solver={"linear": ...} group.
The defaults are a starting point. Check convergence and mesh resolution for each problem, especially when extracting quality factors. Driven adaptive-sweep controls are separate and retain their existing defaults.
You can also supply grouped settings at construction:
sim = pa.EigenmodeSim(
solver={
"order": 1,
"linear": {"tolerance": 1e-6, "max_iterations": 400},
"eigenmode": {"num_modes": 2, "target": 4e9, "tolerance": 1e-8, "save": 2},
}
)
Other simulation types expose their own problem group:
driven = pa.DrivenSim(solver={"driven": {"fmin": 1e9, "fmax": 10e9, "num_points": 40}})
driven.solver.driven.adaptive_tol = 0.01
electrostatic = pa.ElectrostaticSim()
electrostatic.solver.electrostatic.save_fields = 2
boundary = pa.BoundaryModeSim()
boundary.solver.boundary_mode.freq = 5e9
boundary.solver.boundary_mode.num_modes = 2
magnetostatic = pa.MagnetostaticSim()
magnetostatic.solver.magnetostatic.save_fields = 1
All five share twelve controls: order, device, and
linear.{solver_type, preconditioner, tolerance, max_iterations, mg_max_levels,
pc_mat_real, complex_coarse_solve, estimator_tolerance, estimator_max_iterations,
estimator_mg}.
| Simulation | Problem group | Problem settings | Total settings |
|---|---|---|---|
| DrivenSim | solver.driven |
13 | 25 |
| EigenmodeSim | solver.eigenmode |
8 | 20 |
| ElectrostaticSim | solver.electrostatic |
1 | 13 |
| BoundaryModeSim | solver.boundary_mode |
7 | 19 |
| MagnetostaticSim | solver.magnetostatic |
1 | 13 |
sim.set_solver(...) replaces the common controls using the same defaults as
the simulation constructor, including its linear tolerance, while preserving the problem-specific settings. Assign individual
attributes to retain other common values. The generated Palace JSON continues to
use Solver.Order, Solver.Device, Solver.Linear, and the applicable problem block.
Existing code¶
sim.numerical, NumericalConfig, set_numerical(...), the top-level problem
attributes, and legacy constructor arguments remain supported and emit
DeprecationWarning messages pointing to the grouped API. Problem-specific setters
such as set_eigenmode(...) remain available as convenience methods. Old serialized
inputs still load; simulation serialization uses the grouped solver field.
NumericalConfig retains its flat serialization format. Migrate direct access as follows:
| Previous access | Grouped access |
|---|---|
sim.numerical.order |
sim.solver.order |
sim.numerical.tolerance |
sim.solver.linear.tolerance |
sim.eigenmode.target |
sim.solver.eigenmode.target |
sim.driven.fmin |
sim.solver.driven.fmin |
sim.electrostatic.save_fields |
sim.solver.electrostatic.save_fields |
sim.boundary_mode.freq |
sim.solver.boundary_mode.freq |
Boundary-mode path integration¶
Starting with gsim 0.9.0, coordinate-path voltage and impedance postprocessing
omits NSamples. The cloud runtime uses Palace commit
0dd8d015034c0fc1f0cf4c9ff952b533f9cb91d5, which provides element-wise line
integration and contains
the removal:
from gsim.palace import BoundaryModeSim
sim = BoundaryModeSim()
sim.add_impedance_path("gap", voltage=[[0.0, 0.0], [1.0, 0.0]])
This omits NSamples from both Boundaries.Postprocessing.Impedance and
Boundaries.Postprocessing.Voltage. The paths, indices, and current loops are
unchanged. Palace controls the integration rule; no replacement sample count is
required.
Beginning in gsim 0.9.0, ModePath.nsamples and the nsamples= argument to
add_impedance_path, declare_impedance_paths, and declare_terminal_paths
are deprecated. Existing calls still work, but an explicit count emits
DeprecationWarning and is ignored. Calls that omit the count do not warn.
Old saved mode_paths records also load with a warning for explicit nsamples
values; the field is omitted when saved again. Remove the field or argument to
migrate. No replacement setting is needed because Palace determines the
integration rule. The deprecated inputs will be retained for at least two
feature releases and roughly 12 months after the first released warning, then
removed only in a release designated for incompatible changes.
The local auto-download remains pinned to Palace 0.18.0. It accepts these configurations, but uses its old sampled integration with the default count of 100; gsim no longer exposes a control for that count. The local runtime does not gain the cloud runtime's element-wise integration. There is no version-dependent configuration switch.
The nsamples settings on local field-integration routines such as
voltage_line_integral remain available; they control Python-side quadrature,
which is separate from Palace's path declarations.
MUMPS behavior change¶
Reloading a saved gsim settings model with solver_type="MUMPS" now uses the saved
iteration limit and the new multigrid defaults when multigrid controls are absent.
Previously, gsim forced MaxIts=1 and MGMaxLevels=1, regardless of the saved
iteration limit. Old settings still load, but their generated Palace configuration
and solve behavior can change. Explicit saved tolerances are retained.
For a full-system solve, set mg_max_levels=1; set max_iterations=1 to also
request the former iteration limit. This does not reproduce the entire old block:
gsim no longer writes the forced EstimatorMaxIts=0, EstimatorTol=1e-6,
DivFreeMaxIts=0, or DivFreeTol=1e-6. The error estimator controls are in the
sim.solver.linear table above; estimator_max_iterations=0 reproduces the old
estimator behavior, at a cost: the indicator is meaningless, Palace prints solver
warnings, and gsim warns when AMR is on. The divergence-free projection controls
are not exposed by the settings API, so Palace applies its defaults. There is no
automatic legacy-mode fallback.
Calling set_numerical() without an explicit order now uses 2, matching the
constructor and set_solver(). Pass order=1 to retain the previous setter behavior.
Such calls emit a temporary FutureWarning explaining this change. Explicit-order
calls emit the usual API deprecation warning. The new grouped API emits neither.
Update individual controls directly to preserve other settings:
sim.set_solver(...) replaces the common controls with the supplied values and
their defaults, preserving the existing problem group, such as the eigenmode
target. Assigning sim.solver = ... replaces the entire solver configuration,
including its problem group; a new eigenmode group defaults to target=None.
sim.numerical is a deprecated alias for sim.solver, so its model_dump() uses
the grouped format. NumericalConfig(**sim.numerical.model_dump()) accepts that
format and copies the nine common numerical controls into a flat legacy model.
For new code, use sim.solver.model_copy(deep=True) to copy all solver settings.
SolverConfigLinearSolverConfigDrivenConfigEigenmodeConfigElectrostaticConfigBoundaryModeConfigMagnetostaticConfigMagnetostaticSolverConfig
See result validation for independent solver, adaptive sampling, mode identity, wave-port mode continuity, and provenance checks.
Numeric wave-port boundaries¶
The default waveport_boundary="pec" approximates finite conductivity, impedance
and absorbing boundaries as PEC inside the port eigenproblem. Choose
"inherit" to retain those physical conditions when solving the port mode:
from gsim.palace import DrivenSim
sim = DrivenSim()
sim.set_driven(f=50e9, waveport_boundary="inherit")
# After geometry/ports are configured and the mesh is generated:
# config = json.loads(sim.write_config().read_text())
# "WavePortPEC" not in config["Boundaries"]
Only the generated Boundaries.WavePortPEC override changes. The physical 3D
conductivity, impedance and absorbing boundaries remain identical. Lumped ports
are unaffected. This controls a modeling approximation; it does not fix Palace
mode selection or establish lossy S-parameter normalization accuracy. Check the
port fields and solver convergence for the chosen Palace runtime.
The policies differ only when absorbing, conductivity or impedance boundaries
exist; without these Robin terms, both omit WavePortPEC. A later set_driven()
call rebuilds the driven settings, so repeat waveport_boundary="inherit" when
updating other sweep options if you want to retain it.
With wave ports, DrivenSim makes the outer wall of the 3D domain PEC
(Boundaries.PEC, no Absorbing) unless you set absorbing_boundary yourself.
Palace solves the port mode with PEC outer edges, so an absorbing wall makes the
domain and the port mode disagree, which shows up as fake loss, reflection and
mode conversion. To keep the absorbing wall, pass absorbing_boundary=True.
Lumped-port-only runs stay absorbing by default. This applies to wave ports
added with add_wave_port() and to those declared through
configure_wave_port() component metadata.
Default change in 0.9.0
Earlier releases left an unset absorbing_boundary absorbing even with wave
ports. The PEC default starts with 0.9.0. Saved
configurations and notebooks that relied on the old behavior should pass
absorbing_boundary=True.
Material override precedence is separate; see PR #277.
Result validation¶
Simulation Classes¶
Floquet eigenmodes¶
Set the signed cell phase in radians. The wave vector uses the measured donor-to-receiver mesh translation; the eigenvalue
search frequency does not determine the cell length. An optional periodic_length in mesh units (micrometers for generated
meshes) checks that the periodic faces have the expected separation:
from gsim.palace import EigenmodeSim
sim = EigenmodeSim()
sim.set_eigenmode(target=40e9, floquet=True, phi_target=-0.4, periodic_length=100.0)
sim.solver.eigenmode.compute_floquet_wave_vector(periodic_axis="x")
# [-0.004, 0.0, 0.0] rad/um
After setting geometry and stack, sim.mesh(periodic_axis="x") records the actual translation. sim.write_config() writes
it as Boundaries.Periodic.BoundaryPairs[0].Translation, and computes FloquetWaveVector from that measured length. A length
mismatch raises ValueError; omit periodic_length to use the measured value without an expected-length check. Domain
padding can change the separation of periodic faces. Generated translations use the CAD face planes rather than the
tolerance-padded OCC bounding boxes.
Zero, negative phases, and the Brillouin-zone endpoints +/-pi are supported without wrapping. With
Palace's phase convention, the receiver field is
exp(-1j * phi_target) times the donor field. The GDS mesher supports periodic axes x and y; the wave-vector helper and
config generation also support z for supplied mesh metadata.
n_eff_guess is retained as a deprecated compatibility argument and no longer affects the result. Passing it explicitly to
set_eigenmode() emits a DeprecationWarning. Direct calls to
compute_floquet_wave_vector() now require an explicit length on the config or as a periodic_length argument; the old l0
argument and frequency-based length estimate are removed. Old mesh results without translation metadata must be regenerated.
Electrostatic terminals¶
An ElectrostaticSim terminal selects conductors by connected net, by region or by
layer. A net is the metal that touches on one layer plus the metal that vias join on
other layers, so two electrodes on one layer are two nets (see sim.nets()).
sim.add_terminal("TOP", net="PLUS") # net by port name, or by its name in sim.nets()
sim.add_terminal("LEFT", region=(0, 0, 20, 20), layer="m1") # nets with an m1 shape in the box
sim.add_terminal("SHIELD", net="net3", floating=True) # solved, then eliminated
sim.add_terminal("T1", layer="metal5") # a whole layer, as before
sim.unassigned_conductors = "ground" # the default; or "floating"
print(sim.resolve_terminals()) # check the selection before meshing
cap = sim.load_capacitance(sim.run()) # floating terminals are eliminated
cap.between("TOP", "LEFT")
cap.to_ground("LEFT")
cap.pairs() # every pair and every terminal-to-ground value, as a table
- Net names are the names of the ports on the net joined by
+, ornet<k>(kcounts from 1 in layout order).net=matches the whole name or any one port name; if several nets carry the same port name they all go into that terminal.net<k>changes when the layout is edited, so prefer port names orregion=. GDS text labels are not used. region=is a box(xmin, ymin, xmax, ymax)or a list of at least three(x, y)points, in um. It selects every net with a conductor or via shape that overlaps the region, only onlayerwhen that is given. It always selects whole nets, because part of a conductor cannot be at another potential.layer=alone keeps the old behaviour while no terminal usesnet,regionorfloating: every shape on that layer, and vias by z-overlap. Once any terminal uses nets,layer=means every net with a shape on that layer, including the metal that vias join to it on other layers.net=cannot be combined withregion=orlayer=.- Conductors in no terminal are grounded, as before. With
unassigned_conductors="floating"each becomes an extra terminal named after its net. PEC blocks are always grounded. A net in two terminals is an error. - Floating conductors are solved as terminals, one extra Palace excitation each,
and
load_capacitanceremoves them with a Schur complement of the Maxwell matrix,C_tt - C_tf C_ff^-1 C_ft, which is exact for electrostatics. Passeliminate_floating=Falseto keep them. The rows are the terminals in the order they were added, then the automatic floating terminals in net order. - Vias and merging.
mesh()merges vias closer thanmerge_via_distance(2 um by default). If that would join the vias of two nets it raises aValueErrornaming the via layer and the nets; setmerge_via_distancebelow the gap between them. Merging also fills the gaps between vias, so their area grows; a warning names the layer and the area ratio when it grows by more than 5%. Passmerge_via_distance=0to keep every via as drawn.mesh(clip_merged_vias=True)keeps the merged volume inside the overlap of the metal directly above and below the via layer, and never drops a drawn cut. With no metal on one side (for example contacts on the substrate) the cuts stay as drawn. A slab that lies entirely between two continuous metals is unchanged by clipping, somerge_via_distance=0is still the way to mesh every cut there. With net terminalsmesh()raises when a clipped via volume lies nearer to the vias of another net than to those of its own net; setmerge_via_distancebelow the gap between them. - Changing the selection style. A mesh made for layer terminals cannot serve net
terminals and the other way round;
write_config()raises and asks you to callmesh()again. In net modewrite_config()also writesterminals.json, whichload_capacitancereads when the simulation object is new. - Reading the results.
cap.between(a, b)is the capacitance between two electrodes andcap.to_ground(a)the one to ground;cap.pairs()lists both kinds apart. If no conductor is grounded,to_groundcomes out near zero.
Capacitance¶
Magnetostatic current sources¶
A MagnetostaticSim drives a unit current around each
conductor loop in turn and returns the inductance matrix between the loops. Declare one
current source per loop between two ports on the same conductor:
from gsim.palace import MagnetostaticSim
sim = MagnetostaticSim() # PEC outer wall; metallic_boundaries=False for PMC
sim.set_geometry(transformer) # ports P1/P2 and S1/S2
sim.set_stack()
sim.set_airbox(margin_x=100, margin_y=100, z_above=150, z_below=150)
sim.add_current_source("primary", plus_port="P1", minus_port="P2")
sim.add_current_source("secondary", plus_port="S1", minus_port="S2")
print(sim.resolve_current_sources()) # sheet, Direction and net, before meshing
sim.set_output_dir("./palace-sim")
sim.mesh(refined_mesh_size=1.0, max_mesh_size=30)
inductance = sim.load_inductance(sim.run())
inductance.mutual_inductance("primary", "secondary") # in H, signed
inductance.coupling("primary", "secondary")
inductance.pairs() # every self and mutual inductance, as a table
assert not inductance.problems()
- Where the current enters. gsim bridges the gap between the two port faces with a
vertical sheet through the thickness of the conductor layer, which carries the source
current. The ports either face each other across a gap (a cut in a trace), or are
side-by-side leads that point the same way (the two leads of a coil); the sheet then
spans the gap between the inner edges of the leads. Both ports sit on one conductor
layer, inferred from their GDS layer unless
layer=is given. - The gap is part of the loop. The sheet takes the place of the metal across the gap, so the gap width changes the inductance. Keep it small against the loop.
- Sign convention. A unit current enters the conductor at
plus_portand leaves it atminus_port. A mutual inductance is positive when the two loops' fluxes add. Swappingplus_portandminus_portof one source flips the sign of its row and column; the self inductances do not change. The rows follow the order the sources were added in. - Return path. The drawn metal that joins the two ports closes the loop; it must be
one connected net, or
resolve_current_sources()reports an open loop. Every other conductor is a perfect conductor with no source, so a closed one (a ground ring, a patterned shield, an unconnected underpass) screens the field;validate_config()warns about each and the component should leave it out. The genericgf.components.inductorhas an unconnected metal1 underpass that triggers this warning. - Net names.
ResolvedCurrentSource.netis the namesim.nets()gives that metal, so it is named by the electrical ports only, even when a source sits on optical ports. - External inductance. Conductors are perfect conductors, as Palace's magnetostatic solver requires: the current flows on their surfaces, so the matrix is the high-frequency external inductance, without internal or kinetic inductance. Conductivities are not used. A perfect conductor crowds the current towards the inside of each loop, so filament formulas along the trace centrelines overestimate the |M| of nearby loops by about 10 %.
- Outer wall. The outer wall of the domain is a perfect electric conductor by
default (
metallic_boundaries=True).metallic_boundaries=Falsemakes it a perfect magnetic conductor. The two runs bracket the open-space value: an energy bound for the self inductances, a first-order bracket for the mutual inductances. Their mean cancels the first-order wall error. An absorbing wall is refused, since Palace ignores it in a magnetostatic solve. - Airbox and mesh. Keep every airbox extent (
margin_x,margin_y,z_above,z_below) at least as large as the larger lateral side of the meshed conductors; marker layers that are not meshed do not count.validate_config()warns otherwise. Setrefined_mesh_sizeto at most half the trace width, or passauto_size=True, and keepmax_mesh_sizecoarse in the large airbox.fmaxhas no effect on a static solve. - Convergence. A magnetostatic solve that did not converge still exits normally
and writes a plausible matrix.
load_inductancereads the run'spalace.logand raises if a solve did not converge;problems()checks physics only (reciprocity, energy, |k| ≤ 1). Local runs keeppalace.lognext to the result tables. - Solver. The linear solve is AMS-preconditioned conjugate gradients at a tolerance of 1e-8 (see Solver settings).
See the coupled-coil example for an IHP coil pair and an analytic check.
Inductance¶
Saved fields and S-parameters¶
load_fields accepts a simulation directory, Palace output directory, or results
dictionary. Driven, BoundaryMode, and Eigenmode volume and boundary outputs are
supported. Enable field saving with save_step >= 1 for driven simulations or
save >= 1 for eigenmode simulations.
from gsim.palace.results import load_fields
fields = load_fields("eigenmode_sim/output/palace", mode=1)
electric = fields["E_real"] + 1j * fields["E_imag"]
assert electric.shape == (fields.n_points, 3)
surface = load_fields("eigenmode_sim/output/palace", mode=1, boundary=True)
mode=1 selects Cycle000001 from Eigenmode or BoundaryMode output; a missing
mode or a mode containing only mesh metadata raises an error. Use cycle=N to
select an exact ParaView cycle instead, including metadata cycles. Omit both
selectors to load the last cycle containing solution fields, skipping final
Indicator, Rank, or attribute arrays. mode and cycle are mutually
exclusive. For driven output, excitation=N selects the excitation directory.
A missing excitation now raises FileNotFoundError instead of selecting another
excitation. Metadata-only output raises ValueError by default; explicit cycle=N
still permits inspecting that metadata. Mode/cycle selection was also checked
against saved Palace Floquet run palace-552ac5e8, in addition to synthetic tests.
load_sparams converts frequency, dB magnitude, and degree phase columns to
floating-point arrays. A whitespace-padded -inf dB value remains negative
infinity and converts to exact zero, without a magnitude floor:
from pathlib import Path
from tempfile import TemporaryDirectory
import numpy as np
from gsim.palace.results import load_sparams
with TemporaryDirectory() as directory:
output = Path(directory)
(output / "port-S.csv").write_text(
"f (GHz), |S[2][1]| (dB), arg(S[2][1]) (deg.)\n"
"1.0, -inf , 0.0\n"
)
parameters = load_sparams(output)
assert np.isneginf(parameters.s21.db[0])
assert parameters.s21.complex[0] == 0j
assert parameters.to_skrf().s[0, 1, 0] == 0j
Malformed numeric cells reject the entire CSV, including otherwise valid rows.
Errors report the path, column and one-based data row, excluding the header
and blank lines. NaN, positive infinity and empty numeric cells raise ValueError;
phase and frequency must be finite, while dB magnitudes permit negative infinity.
Mesh¶
Presets select mesh-size targets near conductors and in the bulk. Explicit
refined_mesh_size and max_mesh_size arguments override those targets.
auto_size=True only scales a preset when refined_mesh_size is omitted;
an explicit size is always preserved, even with auto_size=True.
Feature detection merges touching polygons on each conductor layer before checking trace/neck widths and gaps, including notches and holes. Distances below two layout database units are ignored as grid artifacts. Gap searches for sizing stop at the smallest width already found (and at 500 um); larger gaps cannot change the size. Cross-layer spacing and arbitrary tapered or curved widths are not measured.
Resolution warnings compare the effective size with the detected conductor
feature divided by cells_per_feature (2 by default). They suggest a smaller
explicit size when an override is present. This feature-based rule is a heuristic;
mesh validation and a lack of warnings do not establish convergence of resonance
frequencies, Q, or S-parameters. Compare results across mesh refinements.
sim.mesh() also reports Estimated Field DOFs for tetrahedral 3D driven and
eigenmode problems, using the configured field order. For order 2, the estimate
is 2 * unique_edges + 2 * unique_triangular_faces, counting interior and shared
entities once. Geometry order and field order are separate. This is the input
mesh count before Palace splits interior boundaries, applies periodic constraints
or refines the mesh; it is not a bound on the final solve size. Other problem
types and mixed/non-tetrahedral meshes have a null estimate.
Mesh results expose a JSON-compatible result.metadata dictionary, also written
to metadata.json beside the mesh and included in cloud input uploads:
result = sim.mesh()
metadata = result.metadata
metadata["schema_version"] # 1
metadata["mesh"]["topology"] # edges and triangular_faces
metadata["mesh"]["field_dofs"]["estimated_field_dofs"]
metadata["mesh"]["kappa"]["max"] # numerical distortion, not formatted text
sim.write_config() refreshes the file using the effective config's field order,
problem type, solver settings and refinement controls. The result object is a
snapshot from meshing. Consumers should accept additional metadata keys so new
measurements can be added. Allocation rules remain in DataLab; these are sizing
hints. gsim sends supported tetrahedron and field-DOF counts to DataLab before
upload, including with older SDK versions. See
cloud sizing metadata for the calibration assumptions.
The root-level metadata.json name is reserved for these diagnostics. It is
excluded from the Palace result-cache key so measurements can evolve without
rerunning identical mesh/config inputs. The full compute_dir_digest() includes
the metadata by default; the cache key is not a complete bundle-integrity hash.
sim.mesh() reports Worst element distortion, κ in its summary. The value is
also available in result.mesh_stats["kappa"]["max"] and sim.print_mesh_stats().
It uses Palace/MFEM's normalized Jacobian condition number: 1 is an ideal
equilateral tetrahedron; larger values indicate greater distortion. Curved
elements are sampled at their centers, so this is not a bound over their interiors.
Use it alongside SICN's signed validity check and solution convergence; κ alone
does not measure simulation accuracy. A numerically singular center is displayed
as infinite and stored as max=None with a nonzero singular_elements count.
Feature-based sizing¶
Automatic sizing uses a same-layer geometry heuristic. Touching and overlapping conductor polygons are merged before measuring widths and spacing. Nearly parallel opposing edges reveal narrow traces and necks; spacing checks also include notches and holes within one connected conductor. Polygon bounding boxes provide a fallback for shapes without suitable opposing edges.
Zero distances and distances below two layout database units are ignored. Gap searches are limited to 500 um; cross-layer gaps and arbitrary tapered or curved widths are not measured. These limitations make the estimate useful for choosing an initial mesh, rather than establishing simulation accuracy. Compare results across refinements before relying on resonance frequencies, Q, or S-parameters.
Reuse a mesh¶
An eigenmode solve and driven sweeps of the same device can run on one mesh, so
the resonances and the S-parameters come from the same discretization and Gmsh
runs once. Mesh one simulation, then call reuse_mesh on the others instead of
mesh(). Here component has lumped ports o1 and o2 on topmetal2, and
each driven sweep excites one of them:
from gsim.palace import DrivenSim, EigenmodeSim
eigen = EigenmodeSim(absorbing_boundary=False)
eigen.set_output_dir("./eigen")
eigen.set_geometry(component)
eigen.set_stack(substrate_thickness=2.0)
eigen.add_port("o1", layer="topmetal2", length=5.0)
eigen.add_port("o2", layer="topmetal2", length=5.0)
eigen.set_eigenmode(num_modes=4, target=8e9)
eigen.mesh(preset="default")
for port in ("o1", "o2"):
driven = DrivenSim(absorbing_boundary=False)
driven.set_output_dir(f"./driven_{port}")
driven.add_port(port, layer="topmetal2", length=5.0, excited=True)
driven.reuse_mesh(eigen) # copies the mesh; no Gmsh run
driven.set_driven(fmin=7e9, fmax=10e9)
driven.write_config()
The receiver copies the source's geometry, stack, airbox, PEC blocks, symmetry
plane and port declarations. A port it declares itself, with the source's
geometry, keeps its own excitation, impedance and R/L/C; the other ports keep
the source's settings but are not excited, whatever the source excites. A
driven receiver needs at least one port it excites itself, declared with
excited=True or set on the copied port config. The
solver settings and the outer wall stay per simulation: with
absorbing_boundary=False the outer boundary is Palace's natural magnetic wall
(PMC), which reflects. Each simulation needs its own output directory, neither
the source's nor nested with it; reuse_mesh copies the .msh into it.
The copy is a snapshot. Re-meshing or editing the source does not reach the
receiver; call reuse_mesh(source) again to pick up the new mesh. The receiver's
layout is a flat copy of the source's: same polygons and ports, no instances.
The mesh fixes what it was built from: the layout polygons and component ports,
the stack layers and dielectric regions, which materials are air-like, the
airbox, PEC blocks, the symmetry plane and the port geometry (kind, layers,
length, offset). Each write_config() of a receiver checks these and raises
ValueError naming what changed. Undo the change, call mesh() on the
receiver to mesh its current state, or call reuse_mesh(source) again.
A stack from set_stack(pdk_authoritative=True) is rebuilt from the active PDK
at each check. Activating another PDK is refused if it changes any of these
inputs, or fails with the PDK's own error if the stack cannot be rebuilt. Its
material values are free, like any other material value, and reach the config.
A mesh made with mesh(periodic_axis=...) keeps its periodic faces out of the
absorbing boundary, and only a Floquet eigenmode solve conditions them. A receiver
with an absorbing outer wall (absorbing_boundary=True, or left unset without
wave ports) and no Floquet solve is refused at write_config(), because those
faces would reflect. Use absorbing_boundary=False, a Floquet
eigenmode, or mesh() on the receiver.
On a receiver that already holds a reused mesh, reuse_mesh takes the port
geometry and kind back from the source: each port the source declares keeps the
receiver's excitation, impedance and R/L/C, and ports the source lacks are
dropped. On a receiver without a reused mesh, a declared port that does not
match the source is refused instead.
Port settings, solver settings, mesh sizes and material values (permittivity,
loss tangent, conductor conductivity) stay free. The receiver's mesh_config
holds the settings the source's mesh was made with, after presets and
auto-sizing. The mesh was sized for the source's values, so check that it still resolves the new ones,
for example against a fresh mesh().
Only driven and eigenmode simulations share meshes, in either direction.
ElectrostaticSim and BoundaryModeSim raise ValueError, and a mesh file or
MeshResult raises TypeError: a file alone has no physical-group or port
mappings. See
DrivenSim.reuse_mesh and
EigenmodeSim.reuse_mesh.
Nets¶
Stack¶
Circuit Synthesis¶
Fitting¶
Parameter Conversions¶
Transmission-line analysis¶
See Transmission-line analysis for using
load_sparams(...).to_skrf() with scikit-rf's multiline TRL calibration,
physical impedance normalization and independent-length checks.
Terminal S-parameters¶
See Terminal (multi-pin) Wave Ports for the conventions and a worked example.
terminal
¶
Modal to terminal S-parameters for multi-conductor (multi-pin) ports.
A field solver returns modal S-parameters: one port per propagating mode.
Circuit work (differential/common-mode analysis, bias lines, SPICE export)
needs terminal S-parameters: one port per conductor, referenced to a common
ground and a chosen reference impedance. This module converts one into the
other using, for every physical port, the matrix of terminal voltages
T_V and terminal currents T_I of its modes.
Conventions¶
Time convention exp(+j w t), as in the rest of gsim. A physical port p has
n_p terminals and n_p modes kept.
- Column
kofT_V[p]holds the terminal voltages (terminal minus the reference conductor) of modekfor a unit forward modal wave. ColumnkofT_I[p]holds the terminal currents flowing into the network for that wave. - Modal waves:
V = T_V (a + b)andI = T_I (a - b). - Terminal power waves for a real reference impedance
Zr:a_t = F (V + Zr I)andb_t = F (V - Zr I)withF = diag(1 / (2 sqrt(Zr))). For realZrthese equal pseudo waves. -
With block-diagonal
T = diag(T_V[p])andW = diag(T_I[p]), andA = F (T + Zr W),B = F (T - Zr W)::S_t = (B + A S_m) (A + B S_m)^-1 S_m = (A - S_t B)^-1 (S_t A - B)
-
Port ordering: physical port by physical port, terminals (or modes) in column order inside each port. A two-end line is ordered (A1, B1, A2, B2) and its modal S is (end 1 mode 1, end 1 mode 2, end 2 mode 1, end 2 mode 2).
Properties¶
- Joint per-mode scaling. Scaling column
kofT_VandT_Itogether by any complex constant leavesS_tunchanged whenS_mhas no cross-mode terms. The solver's modal normalisation therefore cancels; only the voltage/current shape of each mode matters. - Degenerate modes. If several modes share the same propagation constant,
any basis of their subspace gives the same
S_t. Mode identification can be unstable there; the terminal S is not. - Currents. For a reciprocal line
T_I^T T_Vis diagonal with entriesr_k = V_k^T I_k(the unconjugated reaction), soT_I = T_V^{-T} diag(r), see :func:currents_from_reaction. Replacingr_kby the real power2 P_kis only an approximation when the line is lossy. - Uniform line. The modal S of a uniform line is
[[0, E], [E, 0]]withE = diag(exp(-gamma_k * length)), see :func:uniform_line_modal_s.
Example::
import numpy as np
from gsim.palace.terminal import modal_to_terminal_s, uniform_line_modal_s
# t_v, t_i: (nf, 2, 2) for each end; gamma: (nf, 2) in 1/m
s_modal = uniform_line_modal_s(gamma, length=700e-6)
s_term = modal_to_terminal_s(s_modal, [t_v, t_v], [t_i, t_i], z_ref=50.0)
# s_term is ordered (A1, B1, A2, B2)
Limits: real positive reference impedances only; cross-mode terms in the modal S must come from the solver (a multi-mode port solve).
Functions:
-
currents_from_reaction–Terminal currents from terminal voltages and the modal reaction.
-
degenerate_mode_groups–Group modes whose propagation constants agree.
-
modal_to_terminal_s–Convert modal S-parameters to terminal (power-wave) S-parameters.
-
terminal_to_modal_s–Convert terminal S-parameters back to modal S-parameters.
-
uniform_line_modal_s–Modal S-parameters of a uniform multi-mode line, no cross-mode terms.
currents_from_reaction
¶
Terminal currents from terminal voltages and the modal reaction.
The reaction matrix is R = T_V^T T_I (unconjugated), so
T_I = T_V^{-T} R. Pass the full matrix R whenever the modes may be
mixed: within a degenerate group any basis is valid, and a mixed basis
has nonzero off-diagonal reactions.
A vector r is read as R = diag(r) with r_k = V_k^T I_k. This
holds only for a reaction-orthogonal basis (V_j^T I_k = 0 for
j != k): distinct modes of a reciprocal line, or degenerate modes
that were orthogonalised. Using the real power 2 P_k for r_k is
exact only without loss.
Parameters:
-
t_v(ArrayLike) –(n, n)or(nf, n, n)terminal voltages (column = mode). -
reaction(ArrayLike) –the full matrix
R,(n, n)for a 2-Dt_vor(nf, n, n); or the diagonal only,(n,)or(nf, n).
Returns:
-
NDArray[complex128]–T_Iwith the shape oft_v.
Raises:
-
ValueError–On shape mismatch, ill-conditioned
t_vor non-finite input.
degenerate_mode_groups
¶
Group modes whose propagation constants agree.
Modes i and j are linked when
|n_i - n_j| <= rtol * max(|n_i|, |n_j|); groups are the connected
components (single linkage). Within a group the terminal S does not depend
on the basis chosen for the modes.
Parameters:
-
n_eff(ArrayLike) –Effective indices (or propagation constants) at one frequency, shape
(n,). -
rtol(float, default:1e-06) –Relative tolerance.
Returns:
Raises:
-
ValueError–If
n_effis not 1-D or not finite.
modal_to_terminal_s
¶
modal_to_terminal_s(
s_modal: ArrayLike,
t_v: Sequence[ArrayLike],
t_i: Sequence[ArrayLike],
*,
z_ref: ArrayLike = 50.0,
) -> NDArray[complex128]
Convert modal S-parameters to terminal (power-wave) S-parameters.
Parameters:
-
s_modal(ArrayLike) –Modal S-parameters, shape
(nf, M, M). -
t_v(Sequence[ArrayLike]) –One terminal-voltage matrix per physical port, each
(n_p, n_p)or(nf, n_p, n_p). Columnkis modek. -
t_i(Sequence[ArrayLike]) –Terminal currents flowing into the network, same layout as
t_v. -
z_ref(ArrayLike, default:50.0) –Real positive reference impedance in ohm: a scalar, one value per terminal
(Nt,)or one per frequency and terminal(nf, Nt).
Returns:
-
NDArray[complex128]–Terminal S-parameters, shape
(nf, Nt, Nt)withNt = M. For real -
NDArray[complex128]–z_refpower waves and pseudo waves coincide.
Raises:
-
ValueError–On shape or port-count mismatch, non-square or ill-conditioned
t_v/t_iblocks (cond > 1e12, the modes do not span the terminals), non-positive or complexz_ref, or non-finite input.
terminal_to_modal_s
¶
terminal_to_modal_s(
s_terminal: ArrayLike,
t_v: Sequence[ArrayLike],
t_i: Sequence[ArrayLike],
*,
z_ref: ArrayLike = 50.0,
) -> NDArray[complex128]
Convert terminal S-parameters back to modal S-parameters.
Inverse of :func:modal_to_terminal_s; same arguments, conventions and
errors, with s_terminal of shape (nf, Nt, Nt).
uniform_line_modal_s
¶
uniform_line_modal_s(gamma: ArrayLike, length: float) -> NDArray[complex128]
Modal S-parameters of a uniform multi-mode line, no cross-mode terms.
S = [[0, E], [E, 0]] with E = diag(exp(-gamma_k * length)).
Parameters:
-
gamma(ArrayLike) –Propagation constants in 1/m, shape
(nf, n)(or(n,)). -
length(float) –Line length in m.
Returns:
-
NDArray[complex128]–(nf, 2n, 2n)ordered (end 1 modes, end 2 modes).
Raises:
-
ValueError–If
Re(gamma) < 0beyond round-off (a mode that grows along the line), ifgammais not finite, or iflengthis negative or not finite.