Configuration file architecture#

PyEDB configuration files let you describe design setup, modeling content, excitations, and post-processing options in a single JSON or TOML document. The same data model can be consumed from a file or built entirely in Python through the programmatic API described in Configuration API guide and complete example under pyedb.configuration.

This page explains how the configuration file is organized, what each top-level section is used for, and which fields are supported by each section.

Note

While this guide uses JSON fragments for readability, the same hierarchy can also be written as TOML. The section names and nested field names are identical in both formats.

Tip

A machine-readable JSON Schema is available for the complete configuration file. You can use it to validate your config files in any JSON-schema-aware editor (VS Code, PyCharm, etc.) or with tools such as jsonschema.

Download pyedb_config.schema.json

Two ways to configure a design#

Approach	When to use	How to apply
File-based (this page)	Reproducible, human-readable artifacts kept in version control.	`edb.configuration.run("my_config.json")`
Programmatic API (Configuration API guide and complete example)	Scripted workflows, templates, conditional logic.	`cfg = edb.configuration.create_config_builder()` → `edb.configuration.run(cfg)`

Tip

edb.configuration.run() accepts a file path, a plain dictionary, or a CfgData instance, so you can mix and match approaches in the same script.

How a configuration file is consumed#

At runtime, PyEDB parses the file (or builder) into a dictionary, maps each top-level key to an internal section model, and then applies those models to the active EDB design.

Top-level architecture#

A configuration file is a single dictionary. Every top-level key is optional. If a section is omitted, PyEDB leaves that area unchanged.

Top-level sections#
Section	JSON type	Purpose	Typical content
`general`	object	Global library paths and design flags.	SPICE library path, S-parameter library path, pad options.
`stackup`	object	Material definitions and layer stack.	`materials[]`, `layers[]`.
`nets`	object	Net classification.	`signal_nets[]`, `power_ground_nets[]`.
`components`	array	Component model and package settings.	RLC, S-parameter, SPICE, die, solder-ball, port properties.
`padstacks`	object	Padstack definitions and placed instances.	`definitions[]`, `instances[]`.
`pin_groups`	array	Named groups of pins for ports and sources.	Explicit pin lists or groups derived from nets.
`terminals`	array	Low-level EDB terminal definitions.	Padstack, pin-group, point, edge, and bundle terminals.
`ports`	array	Port definitions.	Circuit, coax, wave, gap, and differential wave ports.
`sources`	array	Current and voltage sources.	Positive and negative terminal specifiers, magnitude, impedance.
`probes`	array	Voltage probes.	Positive and negative terminal specifiers.
`setups`	array	Simulation setups.	HFSS, SIwave AC, SIwave DC, sweeps, mesh operations.
`boundaries`	object	HFSS region and dielectric extent settings.	Radiation/PML, air-box extents, dielectric extent.
`operations`	object	Layout operations applied after import.	Cutout and auto HFSS region generation.
`s_parameters`	array	S-parameter model assignments.	Touchstone path, component definition, reference net mapping.
`spice_models`	array	SPICE model assignments.	Model path, subcircuit, target components.
`package_definitions`	array	Thermal package definitions.	Theta values, power, geometry, heat sink.
`variables`	array	Design and project variables.	Name, value, description.
`modeler`	object	Geometry-driven construction and cleanup.	Traces, planes, padstacks, components, primitive deletion.

Minimal file shape#

The following skeleton shows the overall shape of a complete configuration payload:

{
  "general": {},
  "stackup": {
    "materials": [],
    "layers": []
  },
  "nets": {
    "signal_nets": [],
    "power_ground_nets": []
  },
  "components": [],
  "padstacks": {
    "definitions": [],
    "instances": []
  },
  "pin_groups": [],
  "terminals": [],
  "ports": [],
  "sources": [],
  "probes": [],
  "setups": [],

  "boundaries": {},
  "operations": {},
  "s_parameters": [],
  "spice_models": [],
  "package_definitions": [],
  "variables": [],
  "modeler": {}
}

Supported sections and fields#

`general`#

Use this section for design-wide paths and a small number of global options.

`general` fields#
Field	Type	Purpose
`spice_model_library`	string	Base folder used to resolve relative paths in `spice_models`.
`s_parameter_library`	string	Base folder used to resolve relative paths in `s_parameters`.
`anti_pads_always_on`	Boolean	Controls the design option that keeps anti-pads enabled.
`suppress_pads`	Boolean	Controls the design option that suppresses pads where supported.

`stackup`#

This section defines materials and the layer sequence.

stackup.materials[] objects support these keys:

name
conductivity
dielectric_loss_tangent
magnetic_loss_tangent
mass_density
permittivity
permeability
poisson_ratio
specific_heat
thermal_conductivity
youngs_modulus
thermal_expansion_coefficient
dc_conductivity
dc_permittivity
dielectric_model_frequency
loss_tangent_at_frequency
permittivity_at_frequency
thermal_modifiers

Each entry in thermal_modifiers is an object with these fields:
- property_name: material property this modifier applies to (required)
- basic_quadratic_c1: first quadratic coefficient (default 0)
- basic_quadratic_c2: second quadratic coefficient (default 0)
- basic_quadratic_temperature_reference: reference temperature in °C (default 22)
- advanced_quadratic_lower_limit: lower temperature limit in °C (default -273.15)
- advanced_quadratic_upper_limit: upper temperature limit in °C (default 1000)
- advanced_quadratic_auto_calculate: auto-calculate quadratic constants (default true)
- advanced_quadratic_lower_constant: lower constant (default 1)
- advanced_quadratic_upper_constant: upper constant (default 1)

stackup.layers[] objects support these keys:

name
type
material
fill_material
thickness
roughness
etching

roughness supports:

enabled
top / bottom / side
Each surface can use either a Huray roughness model (model, nodule_radius, surface_ratio) or a Groiss roughness model (model, roughness).

etching supports:

factor
etch_power_ground_nets
enabled

Example:

{
  "stackup": {
    "materials": [
      {
        "name": "copper",
        "conductivity": 58000000.0
      },
      {
        "name": "fr4",
        "permittivity": 4.4,
        "dielectric_loss_tangent": 0.02
      }
    ],
    "layers": [
      {
        "name": "top",
        "type": "signal",
        "material": "copper",
        "fill_material": "fr4",
        "thickness": "35um"
      },
      {
        "name": "diel1",
        "type": "dielectric",
        "material": "fr4",
        "thickness": "100um"
      }
    ]
  }
}

`nets`#

Use this section to classify nets by intent.

`nets` fields#
Field	Type	Purpose
`signal_nets`	array of strings	Nets treated as signal nets.
`power_ground_nets`	array of strings	Nets treated as power or ground nets.

`components`#

This section assigns electrical and package-related properties to component instances.

Each components[] entry supports these keys:

`components[]` fields#
Field	Type	Purpose
`reference_designator`	string	Component instance name such as `U1` or `R15`.
`part_type`	string	Component type such as `resistor`, `capacitor`, or `ic`.
`enabled`	Boolean	Enables or disables application of the entry.
`definition`	string	Component definition / part name.
`placement_layer`	string	Placement layer used when constructing components in `modeler`.
`pin_pair_model`	array	Pin-pair RLC model definitions.
`s_parameter_model`	object	S-parameter model assignment for the component.
`spice_model`	object	SPICE model assignment for the component.
`netlist_model`	object	Raw netlist payload.
`ic_die_properties`	object	Die configuration for IC components.
`solder_ball_properties`	object	Solder-ball geometry and material.
`port_properties`	object	Port reference geometry.

Nested component objects support these keys:

pin_pair_model[]: first_pin, second_pin, resistance, inductance, capacitance, is_parallel, resistance_enabled, inductance_enabled, capacitance_enabled.
s_parameter_model: model_name, model_path, reference_net.
spice_model: model_name, model_path, sub_circuit, terminal_pairs.
netlist_model: netlist.
ic_die_properties: type (flip_chip, wire_bond, no_die), orientation (chip_up or chip_down), height.
solder_ball_properties: shape (cylinder, spheroid, no_solder_ball), diameter, height, material, mid_diameter.
port_properties: reference_height, reference_size_auto, reference_size_x, reference_size_y.

`padstacks`#

Use this section to define padstack definitions and update placed padstack instances.

padstacks.definitions[] supports:

name
hole_plating_thickness
material (serialized as the hole material)
hole_range
pad_parameters
hole_parameters
solder_ball_parameters

padstacks.instances[] supports:

name
id
backdrill_parameters
is_pin
net_name
layer_range
definition
position
rotation
hole_override_enabled
hole_override_diameter
solder_ball_layer

backdrill_parameters can define from_top and/or from_bottom. Each branch can use either:

drill_to_layer + diameter
drill_to_layer + diameter + stub_length
drill_depth + diameter

`pin_groups`#

Use pin groups to name a set of pins once and then reuse that name in ports, sources, probes, or explicit terminals.

Each pin_groups[] entry supports:

name
reference_designator
pins (explicit pin list)
net (single net name or list of net names)

Define either pins or net.

`terminals`#

This is the low-level terminal section. Most users do not need it because ports, sources, and probes create terminals implicitly. It becomes useful when you want explicit terminal objects or bundle terminals.

Supported terminal entry types are:

padstack_instance
pin_group
point
edge
bundle

Common terminal keys are:

name
impedance
is_circuit_port
reference_terminal
amplitude
phase
terminal_to_ground

Accepted values: "no_ground" / "kNoGround" (default), "negative" / "kNegative", "positive" / "kPositive", "kNegativeNode", "kPositiveNode".
boundary_type

Accepted values (human-friendly aliases recommended):
- "port" / "PortBoundary"
- "pec" / "PecBoundary"
- "rlc" / "RlcBoundary"
- "current_source" / "kCurrentSource"
- "voltage_source" / "kVoltageSource"
- "voltage_probe" / "kVoltageProbe"
- "dc_terminal" / "kDcTerminal"
- "kNexximGround", "kNexximPort", "InvalidBoundary"
hfss_type

Accepted values: "Wave", "Gap", or null.

Type-specific keys:

padstack_instance: padstack_instance, padstack_instance_id, layer
pin_group: pin_group
point: x, y, layer, net
edge: primitive, point_on_edge_x, point_on_edge_y, horizontal_extent_factor, vertical_extent_factor, pec_launch_width
bundle: terminals

`ports`, `sources`, and `probes`#

These sections use terminal specifiers rather than low-level terminal objects.

Supported terminal-specifier forms are:

Terminal specifiers#
Specifier	Shape	Purpose
Pin	`{"pin": "A1"}`	Address a specific component pin.
Net	`{"net": "VDD"}`	Address pins on a named net.
Pin group	`{"pin_group": "pg_VDD"}`	Reuse a previously defined pin group.
Padstack instance	`{"padstack": "via_1"}`	Address a named padstack instance.
Coordinates	`{"coordinates": {"layer": "top", "point": [x, y], "net": "SIG"}}`	Create a point-based terminal at a coordinate.
Nearest pin	`{"nearest_pin": {"reference_net": "GND", "search_radius": "5mm"}}`	Choose a reference pin automatically for negative terminals.

Optional terminal-specifier helper fields supported by the runtime terminal resolver are:

reference_designator
contact_type (for example default, full, center, quad, inline)
contact_radius
num_of_contact
contact_expansion

Each ports[] entry uses one of these shapes:

Circuit or coax port:
- name
- type = circuit or coax
- positive_terminal
- negative_terminal (circuit only)
- reference_designator
- impedance
- distributed
Wave or gap port:
- name
- type = wave_port or gap_port
- primitive_name
- point_on_edge
- horizontal_extent_factor
- vertical_extent_factor
- pec_launch_width
Differential wave port:
- name
- type = diff_wave_port
- positive_terminal with primitive_name and point_on_edge
- negative_terminal with primitive_name and point_on_edge
- horizontal_extent_factor
- vertical_extent_factor
- pec_launch_width

Each sources[] entry supports:

name
type = current or voltage
positive_terminal
negative_terminal
magnitude
impedance
reference_designator
distributed

Each probes[] entry supports:

name
type = probe
positive_terminal
negative_terminal
reference_designator

`setups`#

The setups array contains HFSS, SIwave AC, and SIwave DC simulation setup objects.

Every setup has at least:

name
type

hfss setups support:

adapt_type = single, broadband, or multi_frequencies
single_frequency_adaptive_solution
broadband_adaptive_solution
multi_frequency_adaptive_solution
auto_mesh_operation
mesh_operations
freq_sweep

single_frequency_adaptive_solution supports:

adaptive_frequency
max_passes
max_delta

broadband_adaptive_solution supports:

low_frequency
high_frequency
max_passes
max_delta

multi_frequency_adaptive_solution supports:

adapt_frequencies[] with adaptive_frequency, max_passes, and max_delta

auto_mesh_operation supports:

enabled
trace_ratio_seeding
signal_via_side_number

mesh_operations[] currently supports length mesh operations with:

type or mesh_operation_type = length
name
max_elements
max_length
restrict_length
refine_inside
nets_layers_list

siwave_ac setups support:

use_si_settings
si_slider_position
pi_slider_position
freq_sweep

siwave_dc setups support:

dc_slider_position
dc_ir_settings with export_dc_thermal_data

All AC sweep objects inside freq_sweep support:

name
type = discrete, interpolation, or interpolating
frequencies
use_q3d_for_dc
compute_dc_point
enforce_causality
enforce_passivity
adv_dc_extrapolation
use_hfss_solver_regions
hfss_solver_region_setup_name
hfss_solver_region_sweep_name

Each frequencies[] entry supports:

start
stop
increment
distribution = linear_scale, log_scale, single, linear_count, log_count

`boundaries`#

Use this section to control HFSS open-region and dielectric extent settings.

Supported keys are:

use_open_region
open_region_type
is_pml_visible
operating_freq
radiation_level
dielectric_extent_type
dielectric_base_polygon
dielectric_extent_size with size and is_multiple
honor_user_dielectric
extent_type
base_polygon
truncate_air_box_at_ground
air_box_horizontal_extent with size and is_multiple
air_box_positive_vertical_extent with size and is_multiple
air_box_negative_vertical_extent with size and is_multiple
sync_air_box_vertical_extent

`operations`#

Use this section for cutout creation and automatic HFSS region generation.

Supported keys are:

cutout
generate_auto_hfss_regions

cutout supports:

auto_identify_nets with enabled, resistor_below, inductor_below, capacitor_above
signal_list
reference_list
extent_type
expansion_size
number_of_threads
custom_extent
custom_extent_units
expansion_factor

`s_parameters`#

Each s_parameters[] entry supports:

name
component_definition
file_path
apply_to_all
components
reference_net
reference_net_per_component
pin_order

Relative file_path values are resolved from general.s_parameter_library.

`spice_models`#

Each spice_models[] entry supports:

name
component_definition
file_path
sub_circuit_name
apply_to_all
components
terminal_pairs

Relative file_path values are resolved from general.spice_model_library.

`package_definitions`#

Use this section for thermal package and heat-sink definitions.

Each package_definitions[] entry supports:

name
component_definition
maximum_power
thermal_conductivity
theta_jb
theta_jc
height
apply_to_all
components
extent_bounding_box
heatsink

heatsink supports:

fin_base_height
fin_height
fin_orientation
fin_spacing
fin_thickness

`variables`#

Each variables[] entry supports:

name
value
description

Names starting with $ are created as project variables. Other names are created as design variables.

`modeler`#

Use this section to create traces, planes, padstack content, components, and primitive deletions.

Supported keys are:

traces
planes
padstack_definitions
padstack_instances
components
primitives_to_delete

traces[] support:

name
layer
path
width
net_name
start_cap_style
end_cap_style
corner_style
incremental_path

planes[] support:

Common: name, layer, net_name, type, voids
Rectangle: lower_left_point, upper_right_point, corner_radius, rotation
Polygon: points
Circle: radius, position

modeler.padstack_definitions[] and modeler.padstack_instances[] use the same payload shapes as the top-level padstacks section.

modeler.components[] use the same payload shape as the top-level components section, and can additionally be combined with the created padstack instances referenced through pins in the lower-level runtime configuration path.

primitives_to_delete supports:

layer_name
name
net_name

Best practices#

Start with only the sections you need.
Prefer pin_groups and terminal specifiers for readability.
Use ports / sources / probes unless you explicitly need low-level terminals.
Keep relative model paths under general.spice_model_library and general.s_parameter_library.
When a section is empty, omit it entirely instead of writing empty values.
For programmatic authoring, prefer Configuration API guide and complete example.

Next step#

If you want to generate these payloads in Python instead of hand-authoring JSON, continue with Configuration API guide and complete example.

Configuration file architecture#

Two ways to configure a design#

How a configuration file is consumed#

Top-level architecture#

Minimal file shape#

Supported sections and fields#

general#

stackup#

nets#

components#

padstacks#

pin_groups#

terminals#

ports, sources, and probes#

setups#

boundaries#

operations#

s_parameters#

spice_models#

package_definitions#

variables#

modeler#

Best practices#

Next step#

`general`#

`stackup`#

`nets`#

`components`#

`padstacks`#

`pin_groups`#

`terminals`#

`ports`, `sources`, and `probes`#

`setups`#

`boundaries`#

`operations`#

`s_parameters`#

`spice_models`#

`package_definitions`#

`variables`#

`modeler`#