squadds.simulations.drivenmodal package

Submodules

squadds.simulations.drivenmodal.artifacts module

Checkpoint and progress-tracking helpers for driven-modal runs.

squadds.simulations.drivenmodal.artifacts.initialize_run_manifest(root_dir, run_id, request_payload)

Create a new run directory with an initial manifest.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.load_run_manifest(manifest_path_or_dir)

Load a manifest from disk.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.mark_stage_complete(manifest_path_or_dir, stage_name)

Mark a manifest stage complete and persist the change.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.mark_sweep_point_failed(manifest_path_or_dir, point_id, error_message)

Mark a sweep point failed and persist the latest error message.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.mark_sweep_point_running(manifest_path_or_dir, point_id)

Mark a sweep point as running and increment attempts.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.mark_sweep_point_success(manifest_path_or_dir, point_id, artifact_uri)

Mark a sweep point successful and persist its artifact URI.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.register_sweep_points(manifest_path_or_dir, sweep_points)

Merge new sweep points into a manifest without duplicating existing point ids.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.artifacts.select_sweep_points(manifest, statuses)

Select sweep points by status from an in-memory manifest.

Return type:

list[dict[str, Any]]

squadds.simulations.drivenmodal.capacitance module

Capacitance extraction helpers for frequency-dependent driven-modal data.

squadds.simulations.drivenmodal.capacitance.capacitance_dataframe_from_y_sweep(freqs_hz, y_matrices, node_names)

Flatten a Y-parameter sweep into a dataframe of capacitance entries by node pair.

Return type:

DataFrame

squadds.simulations.drivenmodal.capacitance.capacitance_matrix_from_y(freq_hz, y_matrix)

Compute the capacitance matrix from the imaginary part of the admittance matrix.

Return type:

ndarray

squadds.simulations.drivenmodal.capacitance.maxwell_capacitance_dataframe(c_matrix, *, node_names, ground_name='ground')

Expand an active-node capacitance matrix into a full Maxwell matrix with ground.

Return type:

DataFrame

squadds.simulations.drivenmodal.coupled_postprocess module

Pure helpers for driven-modal coupled-system post-processing.

squadds.simulations.drivenmodal.coupled_postprocess.calculate_chi_hz(f_ground_hz, f_excited_hz)

Return the dispersive shift in Hz from the embedded ground/excited resonances.

Return type:

float

squadds.simulations.drivenmodal.coupled_postprocess.calculate_g_from_chi(*, f_r_hz, f_q_hz, chi_hz, alpha_hz)

Back-calculate coupling strength magnitude using the dispersive transmon relation with the non-RWA term.

Return type:

float

squadds.simulations.drivenmodal.coupled_postprocess.calculate_kappa_hz(*, f_res_hz, loaded_q)

Compute kappa / 2pi in Hz from loaded quality factor.

Return type:

float

squadds.simulations.drivenmodal.coupled_postprocess.calculate_loaded_q(*, f_res_hz, fwhm_hz)

Compute loaded quality factor from resonance frequency and FWHM.

Return type:

float

squadds.simulations.drivenmodal.coupled_postprocess.terminate_port_y(y_matrices, *, terminated_port, load_impedance_ohms)

Terminate a single port of an N-port admittance sweep using a load impedance.

Return type:

ndarray

squadds.simulations.drivenmodal.coupled_postprocess.y_to_s(y_matrices, *, z0_ohms=50.0)

Convert a sweep of admittance matrices into scattering matrices for a uniform reference impedance.

Return type:

ndarray

squadds.simulations.drivenmodal.design module

Design helpers for explicit driven-modal layer-stack workflows.

squadds.simulations.drivenmodal.design.apply_buffered_chip_bounds(design, *, selection, chip_name='main', x_buffer_mm=0.2, y_buffer_mm=0.2)

Set the chip size from the rendered-component bounds plus renderer buffers.

Qiskit Metal’s HFSS and Q3D renderers both use the same shared box_plus_buffer=True logic in QAnsysRenderer. This helper makes that box explicit on the design before rendering so tutorials can record and inspect the exact chip/ground bounding box used for a run.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.design.apply_cryo_silicon_material_properties(renderer, *, permittivity=11.45, loss_tangent=1e-07, hfss_factory=None, materials_factory=None)

Overwrite HFSS silicon properties with the cryogenic SQuADDS defaults.

Qiskit Metal’s driven-modal renderer only references the material by name in the layer stack. On a fresh AEDT install, that means HFSS keeps Ansys’ default room-temperature silicon permittivity instead of the 11.45 value already used in the eigenmode/Q3D flows. We patch the active project material in-place once the renderer is connected to the target design.

Return type:

dict[str, float | str]

squadds.simulations.drivenmodal.design.connect_renderer_to_new_ansys_design(renderer, design_name, solution_type='drivenmodal')

Create a new Ansys design without forcing an immediate setup lookup.

Qiskit Metal’s new_ansys_design(..., connect=True) helper reconnects via connect_ansys_design(), which unconditionally calls connect_setup(). Brand-new driven-modal designs do not have a setup yet, so that path fails before callers can create one. We avoid that eager setup lookup by creating the design with connect=False and then explicitly binding pinfo to the new design only.

squadds.simulations.drivenmodal.design.create_multiplanar_design(*, layer_stack, layer_stack_path, chip_size_x='9mm', chip_size_y='7mm', chip_center_z='0.0mm', enable_renderers=True)

Create a MultiPlanar design bound to an explicit layer-stack CSV.

Return type:

tuple[qiskit_metal.designs.design_multiplanar.MultiPlanar, Path]

squadds.simulations.drivenmodal.design.ensure_drivenmodal_setup(renderer, **setup_kwargs)

Create and bind a driven-modal setup across Qiskit Metal renderer versions.

Some HFSS renderer versions create the setup but do not update renderer.pinfo.setup to reference the newly created name. Later calls such as add_sweep then fail because they look up the active setup through pinfo. We make that state transition explicit here and reapply the supported editable setup fields once the setup is activated.

squadds.simulations.drivenmodal.design.ensure_perfect_e_boundary(renderer, object_names, *, boundary_name='PerfE_Metal')

Ensure a stable Perfect E boundary exists for the rendered metal sheets.

Return type:

list[str]

squadds.simulations.drivenmodal.design.format_exception_for_console(exc)

Return an ASCII-safe exception string for Windows console output.

Return type:

str

squadds.simulations.drivenmodal.design.render_drivenmodal_design(renderer, *, selection, open_pins=None, port_list=None, jj_to_port=None, ignored_jjs=None, box_plus_buffer=True)

Render a driven-modal geometry with a Qiskit Metal compatibility guard.

Qiskit Metal’s current HFSS driven-modal renderer assumes open_pins is a list whenever port_list is present and concatenates into it internally. Normalizing None to [] here keeps the public call shape clean while avoiding that renderer-side TypeError.

squadds.simulations.drivenmodal.design.run_drivenmodal_sweep(renderer, setup, *, setup_name, **sweep_kwargs)

Insert and analyze a driven-modal sweep with compatibility fallbacks.

Older HFSS renderer stacks expose a valid setup object from add_drivenmodal_setup but fail when the renderer later tries to recover that setup through pinfo.get_setup(setup_name). When a concrete setup handle is available, use it directly for sweep insertion and analysis, then store the resulting sweep on renderer.current_sweep so parameter export continues to work.

squadds.simulations.drivenmodal.design.safe_ansys_design_name(identifier, *, prefix='dm')

Return a short HFSS-safe design name derived from a longer run identifier.

Older HFSS / pyEPR combinations can become unstable when driven-modal design names are long and heavily punctuated. We keep the user-facing run ID in the checkpoint and artifact layout, but use a compact deterministic alias for the internal Ansys design name.

Return type:

str

squadds.simulations.drivenmodal.design.save_renderer_project(renderer, project_file)

Persist the current AEDT project state to disk.

Return type:

Path

squadds.simulations.drivenmodal.design.simplify_collinear_path_points(design)

Collapse redundant collinear path vertices before Ansys rendering.

Qiskit Metal can emit straight CPW centerlines with tiny extra collinear segments near terminations. Older HFSS / COM combinations sometimes reject those paths in CreatePolyline even though the geometry is physically a simple straight line. Removing only the redundant collinear interior points preserves bends/fillets while producing a more stable path for rendering.

Return type:

int

squadds.simulations.drivenmodal.design.snapshot_boundary_assignments(renderer)

Return saved HFSS boundary assignments for later artifact/debug dumps.

Return type:

dict[str, list[str]]

squadds.simulations.drivenmodal.design.write_qiskit_layer_stack_csv(spec, output_path)

Persist the resolved layer stack in the CSV format consumed by Qiskit Metal.

Return type:

Path

squadds.simulations.drivenmodal.extractors module

Load driven-modal comparison values from exported solver artifacts.

squadds.simulations.drivenmodal.extractors.coupled_hamiltonian_from_prepared_runs(prepared_runs)

Load extracted Hamiltonian metrics from the first available band summary.json.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.extractors.hamiltonian_from_summary_json(summary_path)

Read artifacts/summary.json written by coupled driven-modal post-processing.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.extractors.hamiltonian_from_summary_mapping(extracted)

Normalize a post-processing extracted record to HAMILTONIAN_KEYS.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.extractors.pair_capacitances_fF_from_run_dir(run_dir, *, system_kind, extraction_freq_ghz)

Load artifacts/y_parameters.pkl and return pair capacitances in fF.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.extractors.pair_capacitances_fF_from_y_frame(y_frame, *, system_kind, extraction_freq_ghz)

Convert a Y-parameter sweep table into the same six pair labels used by Q3D rows.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.hfss_data module

Helpers for parsing HFSS parameter tables into array and network structures.

squadds.simulations.drivenmodal.hfss_data.network_from_parameter_dataframe(frame, *, matrix_size, z0_ohms=50.0)

Build a scikit-rf Network from an HFSS S-parameter dataframe.

Return type:

Network

squadds.simulations.drivenmodal.hfss_data.parameter_dataframe_to_tensor(frame, *, matrix_size, parameter_prefix)

Convert a Qiskit Metal HFSS parameter dataframe into a frequency sweep tensor.

Return type:

tuple[ndarray, ndarray]

squadds.simulations.drivenmodal.hfss_data.write_touchstone_from_dataframe(frame, *, matrix_size, output_path, z0_ohms=50.0)

Write a Touchstone file from an HFSS S-parameter dataframe.

Return type:

Path

squadds.simulations.drivenmodal.hfss_runner module

High-level driven-modal runner entrypoint.

squadds.simulations.drivenmodal.hfss_runner.run_drivenmodal_request(request, *, checkpoint_dir=None, export_artifacts=True)

Initialize a checkpointed driven-modal run and return its prepared state.

squadds.simulations.drivenmodal.layer_stack module

Layer-stack presets for driven-modal HFSS workflows.

squadds.simulations.drivenmodal.layer_stack.build_layer_stack_dataframe(spec)

Return the resolved layer stack in the column order expected by Qiskit Metal.

Return type:

DataFrame

squadds.simulations.drivenmodal.layer_stack.resolve_chip_metadata(spec)

Return the chip-level metadata expected by legacy HFSS/Q3D renderers.

Qiskit Metal’s Ansys renderers do not rely on the layer-stack CSV alone. They also expect chip material, substrate thickness, and sample-holder extents to be present under design.chips[chip_name]. MultiPlanar does not always prepopulate those entries, so we derive them from the same preset that defines the explicit layer stack.

Return type:

dict[str, str]

squadds.simulations.drivenmodal.layer_stack.resolve_layer_stack(spec)

Resolve a fixed material preset into explicit layer-stack rows.

Return type:

list[dict[str, Any]]

squadds.simulations.drivenmodal.models module

Typed request and result models for HFSS driven-modal workflows.

class squadds.simulations.drivenmodal.models.CapacitanceExtractionRequest(system_kind, design_payload, layer_stack, setup, sweep, artifacts, metadata=<factory>)

Bases: object

Request to extract a frequency-dependent capacitance matrix from HFSS driven-modal data.

artifacts: DrivenModalArtifactPolicy

design_payload: Mapping[str, Any]

layer_stack: DrivenModalLayerStackSpec

metadata: Mapping[str, Any]

setup: DrivenModalSetupSpec

sweep: DrivenModalSweepSpec

system_kind: str

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.CapacitanceExtractionResult(request, layer_stack, sim_results, artifacts)

Bases: object

Compact result surface for capacitance extraction workflows.

artifacts: Mapping[str, Any]

layer_stack: list[dict[str, Any]]

request: Mapping[str, Any]

sim_results: Mapping[str, Any]

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.CoupledSystemDrivenModalRequest(resonator_type, design_payload, layer_stack, setup, sweep, artifacts, metadata=<factory>)

Bases: object

Request to extract a multiport coupled-system response and post-process it into SQuADDS outputs.

artifacts: DrivenModalArtifactPolicy

design_payload: Mapping[str, Any]

layer_stack: DrivenModalLayerStackSpec

metadata: Mapping[str, Any]

resonator_type: str

setup: DrivenModalSetupSpec

sweep: DrivenModalSweepSpec

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.CoupledSystemDrivenModalResult(request, layer_stack, sim_results, artifacts)

Bases: object

Compact result surface for coupled-system workflows.

artifacts: Mapping[str, Any]

layer_stack: list[dict[str, Any]]

request: Mapping[str, Any]

sim_results: Mapping[str, Any]

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.DrivenModalArtifactPolicy(export_touchstone=True, export_y_parameters=True, export_capacitance_tables=True, checkpoint_after_stage=True, resume_existing=True)

Bases: object

Artifact and checkpoint export controls for solver and post-processing outputs.

checkpoint_after_stage: bool = True

export_capacitance_tables: bool = True

export_touchstone: bool = True

export_y_parameters: bool = True

resume_existing: bool = True

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.DrivenModalLayerStackSpec(preset='squadds_hfss_v1', chip_name='main', metal_layer=1, substrate_layer=3, datatype=0, metal_thickness_um=0.2, substrate_thickness_um=750.0, metal_z_coord_um=0.0, substrate_z_coord_um=0.0)

Bases: object

Resolved from a fixed SQuADDS layer-stack preset plus thickness overrides.

chip_name: str = 'main'

datatype: int = 0

metal_layer: int = 1

metal_thickness_um: float = 0.2

metal_z_coord_um: float = 0.0

preset: str = 'squadds_hfss_v1'

substrate_layer: int = 3

substrate_thickness_um: float = 750.0

substrate_z_coord_um: float = 0.0

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.DrivenModalPortSpec(kind, component, pin, impedance_ohms=50.0, metadata=<factory>)

Bases: object

A reusable Qiskit Metal / HFSS lumped-port declaration.

component: str

impedance_ohms: float = 50.0

kind: str

metadata: Mapping[str, Any]

pin: str

to_dict()

Return type:

dict[str, Any]

to_qiskit_port_entry()

Return type:

tuple[str, str, float]

class squadds.simulations.drivenmodal.models.DrivenModalRunManifest(run_id, run_dir, stages, request_payload)

Bases: object

Serializable checkpoint state for a driven-modal run.

request_payload: Mapping[str, Any]

run_dir: str

run_id: str

stages: Mapping[str, Any]

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.DrivenModalSetupSpec(name='Setup', freq_ghz=5.0, max_delta_s=0.1, max_passes=10, min_passes=1, min_converged=1, pct_refinement=30, basis_order=1)

Bases: object

HFSS driven-modal adaptive setup parameters.

basis_order: int = 1

freq_ghz: float = 5.0

max_delta_s: float = 0.1

max_passes: int = 10

min_converged: int = 1

min_passes: int = 1

name: str = 'Setup'

pct_refinement: int = 30

to_renderer_kwargs()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.models.DrivenModalSweepSpec(start_ghz, stop_ghz, count, name='Sweep', sweep_type='Fast', save_fields=False, interpolation_tol=None, interpolation_max_solutions=None)

Bases: object

Frequency sweep configuration attached to a driven-modal setup.

count: int

interpolation_max_solutions: int | None = None

interpolation_tol: float | None = None

name: str = 'Sweep'

save_fields: bool = False

start_ghz: float

stop_ghz: float

sweep_type: str = 'Fast'

to_renderer_kwargs()

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.ports module

Reusable port-spec builders for driven-modal workflows.

squadds.simulations.drivenmodal.ports.build_capacitance_port_specs(system_kind, design_payload)

Build the ordered port declarations for capacitance extraction systems.

Return type:

list[DrivenModalPortSpec]

squadds.simulations.drivenmodal.ports.build_coupled_system_port_specs(design_payload)

Build the ordered feedline and JJ ports for coupled systems.

Return type:

list[DrivenModalPortSpec]

squadds.simulations.drivenmodal.ports.split_rendered_ports(port_specs)

Split mixed pin/junction specs into Qiskit Metal port_list and jj_to_port payloads.

Return type:

tuple[list[tuple[str, str, float]], list[tuple[str, str, float, bool]]]

squadds.simulations.drivenmodal.qubit_admittance module

Helpers for extracting qubit properties from driven-modal port admittance.

squadds.simulations.drivenmodal.qubit_admittance.bare_lj_to_ej_ghz(lj_h)

Convert a bare Josephson inductance into EJ in GHz for scqubits.

Return type:

float

squadds.simulations.drivenmodal.qubit_admittance.capacitance_to_ec_ghz(c_total_f)

Convert a total shunting capacitance in Farads into EC in GHz for scqubits.

Return type:

float

squadds.simulations.drivenmodal.qubit_admittance.combine_port_admittance_with_jj(freqs_hz, y33_env, *, lj_h, cj_f=0.0, rj_ohms=inf)

Return the total small-signal admittance seen by the JJ port.

Return type:

ndarray

squadds.simulations.drivenmodal.qubit_admittance.extract_parallel_mode_from_total_admittance(freqs_hz, y_total, *, center_hint_hz=None)

Extract the linearized qubit mode from a total JJ-port admittance trace.

The resonance is identified from zero crossings of Im[Y_total] with a positive slope, which correspond to parallel resonances of the full linear environment plus the JJ surrogate. The effective capacitance follows from 0.5 * d(Im[Y]) / dω at the zero crossing.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.qubit_admittance.extract_qubit_from_port_admittance(freqs_hz, y33_env, *, lj_h, cj_f=0.0, rj_ohms=inf, center_hint_hz=None, ncut=35)

Estimate transmon parameters from the JJ-port admittance and a JJ RLC model.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.qubit_admittance.jj_parallel_admittance(freqs_hz, *, lj_h, cj_f=0.0, rj_ohms=inf)

Return the parallel RLC admittance of a Josephson junction surrogate.

Return type:

ndarray

squadds.simulations.drivenmodal.qubit_admittance.jj_parallel_impedance(freqs_hz, *, lj_h, cj_f=0.0, rj_ohms=inf)

Return the equivalent impedance of the parallel JJ RLC model.

Return type:

ndarray

squadds.simulations.drivenmodal.qubit_admittance.reduce_terminated_port_admittance(y_matrices, *, target_port, terminated_port_impedances)

Reduce a multiport admittance tensor to one port with explicit terminations.

Raw Y-parameters are defined with the other ports shorted. For the qubit port we instead want the environment admittance with the feedline ports terminated in their physical loads, so we eliminate those ports via a Schur complement.

Return type:

ndarray

squadds.simulations.drivenmodal.workflows module

User-facing driven-modal workflow helpers.

These helpers keep tutorial notebooks focused on the SQuADDS workflow:

1. choose a reference design,

2. declare the driven-modal solve,

3. run or reuse solver artifacts, and

4. compare extracted parameters against the SQuADDS reference row.

The lower-level renderer and HFSS compatibility helpers remain available for advanced users, but most notebooks should start here.

class squadds.simulations.drivenmodal.workflows.DrivenModalRuntimePaths(root, checkpoints, hfss_projects, local_analysis=None)

Bases: object

Conventional runtime folders for tutorial and scripted runs.

checkpoints: str

hfss_projects: str

local_analysis: str | None = None

root: str

squadds.simulations.drivenmodal.workflows.bare_lj_h_from_qubit_options(qubit_options)

Return the bare JJ inductance in Henry from a SQuADDS qubit option dict.

Return type:

float

squadds.simulations.drivenmodal.workflows.build_capacitance_request(row, *, system_kind, run_id, layer_stack=None, setup=None, sweep=None, artifacts=None)

Build a capacitance request for a qubit-claw or NCap reference row.

Return type:

CapacitanceExtractionRequest

squadds.simulations.drivenmodal.workflows.build_coupled_system_request(row, *, resonator_type, run_id, setup, sweep, layer_stack=None, artifacts=None)

Build the 3-port driven-modal request for a qubit-cavity-feedline system.

Return type:

CoupledSystemDrivenModalRequest

squadds.simulations.drivenmodal.workflows.build_segmented_coupled_system_requests(row, *, resonator_type, run_id, reference, setup=None, sweeps=None, layer_stack=None, artifacts=None)

Build same-geometry requests for qubit, bridge, and resonator sweeps.

Return type:

dict[str, CoupledSystemDrivenModalRequest]

squadds.simulations.drivenmodal.workflows.capacitance_comparison_table(*, drivenmodal_fF, q3d_fF)

Compare driven-modal capacitances against the SQuADDS Q3D row.

Return type:

DataFrame

squadds.simulations.drivenmodal.workflows.capacitance_reference_summary(row, *, system_kind)

Extract the SQuADDS Q3D capacitance summary from a reference row.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.workflows.coupled_design_payload(row)

Normalize a SQuADDS qubit-cavity row into the QubitCavity payload shape.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.workflows.coupled_reference_summary(row)

Extract the target/reference Hamiltonian and JJ data from a SQuADDS row.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.workflows.default_artifact_policy(*, resume_existing=True)

Return the artifact policy used by the driven-modal tutorials.

Return type:

DrivenModalArtifactPolicy

squadds.simulations.drivenmodal.workflows.default_capacitance_setup(*, freq_ghz=5.0)

Return a Q3D-comparison driven-modal setup for capacitance extraction.

Return type:

DrivenModalSetupSpec

squadds.simulations.drivenmodal.workflows.default_capacitance_sweep(*, start_ghz=1.0, stop_ghz=10.0, count=400)

Return the broad interpolating sweep used for capacitance checks.

Return type:

DrivenModalSweepSpec

squadds.simulations.drivenmodal.workflows.default_hamiltonian_setup(*, freq_ghz)

Return a coupled-system setup centered near the expected cavity mode.

Return type:

DrivenModalSetupSpec

squadds.simulations.drivenmodal.workflows.default_hamiltonian_sweep(*, name, start_ghz, stop_ghz, count, sweep_type='Interpolating')

Return one named sweep for a coupled-system Hamiltonian run.

Return type:

DrivenModalSweepSpec

squadds.simulations.drivenmodal.workflows.default_layer_stack()

Return the SQuADDS cryogenic HFSS layer-stack convention.

Return type:

DrivenModalLayerStackSpec

squadds.simulations.drivenmodal.workflows.hamiltonian_comparison_table(*, drivenmodal, squadds)

Compare extracted Hamiltonian parameters against the SQuADDS row.

Return type:

DataFrame

squadds.simulations.drivenmodal.workflows.maxwell_matrix_interpretation()

Return the active-node convention used to avoid capacitance double counting.

Return type:

DataFrame

squadds.simulations.drivenmodal.workflows.regularize_coupled_design_payload(design_options)

Normalize nested design options before driven-modal rendering.

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.workflows.segmented_hamiltonian_sweeps(reference, *, qubit_padding_ghz=0.5, resonator_padding_ghz=0.5, qubit_count=22000, bridge_count=4001, resonator_count=22000)

Build fine/coarse/fine sweeps for one coupled-system driven-modal run.

Return type:

dict[str, DrivenModalSweepSpec]

squadds.simulations.drivenmodal.workflows.transmon_state_inductances(*, lj_h, cross_to_ground_fF, cross_to_claw_fF, ng=0.0, ncut=30)

Compute state-dependent JJ inductances with scqubits.

Return type:

dict[str, float]

Module contents

Driven-modal HFSS request, result, and utility models.

class squadds.simulations.drivenmodal.CapacitanceExtractionRequest(system_kind, design_payload, layer_stack, setup, sweep, artifacts, metadata=<factory>)

Bases: object

Request to extract a frequency-dependent capacitance matrix from HFSS driven-modal data.

artifacts: DrivenModalArtifactPolicy

design_payload: Mapping[str, Any]

layer_stack: DrivenModalLayerStackSpec

metadata: Mapping[str, Any]

setup: DrivenModalSetupSpec

sweep: DrivenModalSweepSpec

system_kind: str

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.CapacitanceExtractionResult(request, layer_stack, sim_results, artifacts)

Bases: object

Compact result surface for capacitance extraction workflows.

artifacts: Mapping[str, Any]

layer_stack: list[dict[str, Any]]

request: Mapping[str, Any]

sim_results: Mapping[str, Any]

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.CoupledSystemDrivenModalRequest(resonator_type, design_payload, layer_stack, setup, sweep, artifacts, metadata=<factory>)

Bases: object

Request to extract a multiport coupled-system response and post-process it into SQuADDS outputs.

artifacts: DrivenModalArtifactPolicy

design_payload: Mapping[str, Any]

layer_stack: DrivenModalLayerStackSpec

metadata: Mapping[str, Any]

resonator_type: str

setup: DrivenModalSetupSpec

sweep: DrivenModalSweepSpec

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.CoupledSystemDrivenModalResult(request, layer_stack, sim_results, artifacts)

Bases: object

Compact result surface for coupled-system workflows.

artifacts: Mapping[str, Any]

layer_stack: list[dict[str, Any]]

request: Mapping[str, Any]

sim_results: Mapping[str, Any]

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.DrivenModalArtifactPolicy(export_touchstone=True, export_y_parameters=True, export_capacitance_tables=True, checkpoint_after_stage=True, resume_existing=True)

Bases: object

Artifact and checkpoint export controls for solver and post-processing outputs.

checkpoint_after_stage: bool = True

export_capacitance_tables: bool = True

export_touchstone: bool = True

export_y_parameters: bool = True

resume_existing: bool = True

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.DrivenModalLayerStackSpec(preset='squadds_hfss_v1', chip_name='main', metal_layer=1, substrate_layer=3, datatype=0, metal_thickness_um=0.2, substrate_thickness_um=750.0, metal_z_coord_um=0.0, substrate_z_coord_um=0.0)

Bases: object

Resolved from a fixed SQuADDS layer-stack preset plus thickness overrides.

chip_name: str = 'main'

datatype: int = 0

metal_layer: int = 1

metal_thickness_um: float = 0.2

metal_z_coord_um: float = 0.0

preset: str = 'squadds_hfss_v1'

substrate_layer: int = 3

substrate_thickness_um: float = 750.0

substrate_z_coord_um: float = 0.0

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.DrivenModalPortSpec(kind, component, pin, impedance_ohms=50.0, metadata=<factory>)

Bases: object

A reusable Qiskit Metal / HFSS lumped-port declaration.

component: str

impedance_ohms: float = 50.0

kind: str

metadata: Mapping[str, Any]

pin: str

to_dict()

Return type:

dict[str, Any]

to_qiskit_port_entry()

Return type:

tuple[str, str, float]

class squadds.simulations.drivenmodal.DrivenModalRunManifest(run_id, run_dir, stages, request_payload)

Bases: object

Serializable checkpoint state for a driven-modal run.

request_payload: Mapping[str, Any]

run_dir: str

run_id: str

stages: Mapping[str, Any]

to_dict()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.DrivenModalSetupSpec(name='Setup', freq_ghz=5.0, max_delta_s=0.1, max_passes=10, min_passes=1, min_converged=1, pct_refinement=30, basis_order=1)

Bases: object

HFSS driven-modal adaptive setup parameters.

basis_order: int = 1

freq_ghz: float = 5.0

max_delta_s: float = 0.1

max_passes: int = 10

min_converged: int = 1

min_passes: int = 1

name: str = 'Setup'

pct_refinement: int = 30

to_renderer_kwargs()

Return type:

dict[str, Any]

class squadds.simulations.drivenmodal.DrivenModalSweepSpec(start_ghz, stop_ghz, count, name='Sweep', sweep_type='Fast', save_fields=False, interpolation_tol=None, interpolation_max_solutions=None)

Bases: object

Frequency sweep configuration attached to a driven-modal setup.

count: int

interpolation_max_solutions: int | None = None

interpolation_tol: float | None = None

name: str = 'Sweep'

save_fields: bool = False

start_ghz: float

stop_ghz: float

sweep_type: str = 'Fast'

to_renderer_kwargs()

Return type:

dict[str, Any]

squadds.simulations.drivenmodal.bare_lj_to_ej_ghz(lj_h)

Convert a bare Josephson inductance into EJ in GHz for scqubits.

Return type:

float

squadds.simulations.drivenmodal.build_capacitance_request(row, *, system_kind, run_id, layer_stack=None, setup=None, sweep=None, artifacts=None)

Build a capacitance request for a qubit-claw or NCap reference row.

Return type:

CapacitanceExtractionRequest

squadds.simulations.drivenmodal.build_coupled_system_request(row, *, resonator_type, run_id, setup, sweep, layer_stack=None, artifacts=None)

Build the 3-port driven-modal request for a qubit-cavity-feedline system.

Return type:

CoupledSystemDrivenModalRequest

squadds.simulations.drivenmodal.build_layer_stack_dataframe(spec)

Return the resolved layer stack in the column order expected by Qiskit Metal.

Return type:

DataFrame

squadds.simulations.drivenmodal.build_segmented_coupled_system_requests(row, *, resonator_type, run_id, reference, setup=None, sweeps=None, layer_stack=None, artifacts=None)

Build same-geometry requests for qubit, bridge, and resonator sweeps.

Return type:

dict[str, CoupledSystemDrivenModalRequest]

squadds.simulations.drivenmodal.calculate_chi_hz(f_ground_hz, f_excited_hz)

Return the dispersive shift in Hz from the embedded ground/excited resonances.

Return type:

float

squadds.simulations.drivenmodal.calculate_g_from_chi(*, f_r_hz, f_q_hz, chi_hz, alpha_hz)

Back-calculate coupling strength magnitude using the dispersive transmon relation with the non-RWA term.

Return type:

float

squadds.simulations.drivenmodal.calculate_kappa_hz(*, f_res_hz, loaded_q)

Compute kappa / 2pi in Hz from loaded quality factor.

Return type:

float

squadds.simulations.drivenmodal.calculate_loaded_q(*, f_res_hz, fwhm_hz)

Compute loaded quality factor from resonance frequency and FWHM.

Return type:

float

squadds.simulations.drivenmodal.capacitance_comparison_table(*, drivenmodal_fF, q3d_fF)

Compare driven-modal capacitances against the SQuADDS Q3D row.

Return type:

DataFrame

squadds.simulations.drivenmodal.capacitance_dataframe_from_y_sweep(freqs_hz, y_matrices, node_names)

Flatten a Y-parameter sweep into a dataframe of capacitance entries by node pair.

Return type:

DataFrame

squadds.simulations.drivenmodal.capacitance_matrix_from_y(freq_hz, y_matrix)

Compute the capacitance matrix from the imaginary part of the admittance matrix.

Return type:

ndarray

squadds.simulations.drivenmodal.capacitance_reference_summary(row, *, system_kind)

Extract the SQuADDS Q3D capacitance summary from a reference row.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.capacitance_to_ec_ghz(c_total_f)

Convert a total shunting capacitance in Farads into EC in GHz for scqubits.

Return type:

float

squadds.simulations.drivenmodal.combine_port_admittance_with_jj(freqs_hz, y33_env, *, lj_h, cj_f=0.0, rj_ohms=inf)

Return the total small-signal admittance seen by the JJ port.

Return type:

ndarray

squadds.simulations.drivenmodal.coupled_hamiltonian_from_prepared_runs(prepared_runs)

Load extracted Hamiltonian metrics from the first available band summary.json.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.coupled_reference_summary(row)

Extract the target/reference Hamiltonian and JJ data from a SQuADDS row.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.create_multiplanar_design(*, layer_stack, layer_stack_path, chip_size_x='9mm', chip_size_y='7mm', chip_center_z='0.0mm', enable_renderers=True)

Create a MultiPlanar design bound to an explicit layer-stack CSV.

Return type:

tuple[qiskit_metal.designs.design_multiplanar.MultiPlanar, Path]

squadds.simulations.drivenmodal.default_artifact_policy(*, resume_existing=True)

Return the artifact policy used by the driven-modal tutorials.

Return type:

DrivenModalArtifactPolicy

squadds.simulations.drivenmodal.default_capacitance_setup(*, freq_ghz=5.0)

Return a Q3D-comparison driven-modal setup for capacitance extraction.

Return type:

DrivenModalSetupSpec

squadds.simulations.drivenmodal.default_capacitance_sweep(*, start_ghz=1.0, stop_ghz=10.0, count=400)

Return the broad interpolating sweep used for capacitance checks.

Return type:

DrivenModalSweepSpec

squadds.simulations.drivenmodal.default_hamiltonian_setup(*, freq_ghz)

Return a coupled-system setup centered near the expected cavity mode.

Return type:

DrivenModalSetupSpec

squadds.simulations.drivenmodal.default_hamiltonian_sweep(*, name, start_ghz, stop_ghz, count, sweep_type='Interpolating')

Return one named sweep for a coupled-system Hamiltonian run.

Return type:

DrivenModalSweepSpec

squadds.simulations.drivenmodal.default_layer_stack()

Return the SQuADDS cryogenic HFSS layer-stack convention.

Return type:

DrivenModalLayerStackSpec

squadds.simulations.drivenmodal.extract_parallel_mode_from_total_admittance(freqs_hz, y_total, *, center_hint_hz=None)

Extract the linearized qubit mode from a total JJ-port admittance trace.

The resonance is identified from zero crossings of Im[Y_total] with a positive slope, which correspond to parallel resonances of the full linear environment plus the JJ surrogate. The effective capacitance follows from 0.5 * d(Im[Y]) / dω at the zero crossing.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.extract_qubit_from_port_admittance(freqs_hz, y33_env, *, lj_h, cj_f=0.0, rj_ohms=inf, center_hint_hz=None, ncut=35)

Estimate transmon parameters from the JJ-port admittance and a JJ RLC model.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.hamiltonian_comparison_table(*, drivenmodal, squadds)

Compare extracted Hamiltonian parameters against the SQuADDS row.

Return type:

DataFrame

squadds.simulations.drivenmodal.hamiltonian_from_summary_json(summary_path)

Read artifacts/summary.json written by coupled driven-modal post-processing.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.hamiltonian_from_summary_mapping(extracted)

Normalize a post-processing extracted record to HAMILTONIAN_KEYS.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.jj_parallel_admittance(freqs_hz, *, lj_h, cj_f=0.0, rj_ohms=inf)

Return the parallel RLC admittance of a Josephson junction surrogate.

Return type:

ndarray

squadds.simulations.drivenmodal.jj_parallel_impedance(freqs_hz, *, lj_h, cj_f=0.0, rj_ohms=inf)

Return the equivalent impedance of the parallel JJ RLC model.

Return type:

ndarray

squadds.simulations.drivenmodal.maxwell_capacitance_dataframe(c_matrix, *, node_names, ground_name='ground')

Expand an active-node capacitance matrix into a full Maxwell matrix with ground.

Return type:

DataFrame

squadds.simulations.drivenmodal.maxwell_matrix_interpretation()

Return the active-node convention used to avoid capacitance double counting.

Return type:

DataFrame

squadds.simulations.drivenmodal.network_from_parameter_dataframe(frame, *, matrix_size, z0_ohms=50.0)

Build a scikit-rf Network from an HFSS S-parameter dataframe.

Return type:

Network

squadds.simulations.drivenmodal.pair_capacitances_fF_from_run_dir(run_dir, *, system_kind, extraction_freq_ghz)

Load artifacts/y_parameters.pkl and return pair capacitances in fF.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.pair_capacitances_fF_from_y_frame(y_frame, *, system_kind, extraction_freq_ghz)

Convert a Y-parameter sweep table into the same six pair labels used by Q3D rows.

Return type:

dict[str, float]

squadds.simulations.drivenmodal.parameter_dataframe_to_tensor(frame, *, matrix_size, parameter_prefix)

Convert a Qiskit Metal HFSS parameter dataframe into a frequency sweep tensor.

Return type:

tuple[ndarray, ndarray]

squadds.simulations.drivenmodal.resolve_layer_stack(spec)

Resolve a fixed material preset into explicit layer-stack rows.

Return type:

list[dict[str, Any]]

squadds.simulations.drivenmodal.segmented_hamiltonian_sweeps(reference, *, qubit_padding_ghz=0.5, resonator_padding_ghz=0.5, qubit_count=22000, bridge_count=4001, resonator_count=22000)

Build fine/coarse/fine sweeps for one coupled-system driven-modal run.

Return type:

dict[str, DrivenModalSweepSpec]

squadds.simulations.drivenmodal.terminate_port_y(y_matrices, *, terminated_port, load_impedance_ohms)

Terminate a single port of an N-port admittance sweep using a load impedance.

Return type:

ndarray

squadds.simulations.drivenmodal.write_qiskit_layer_stack_csv(spec, output_path)

Persist the resolved layer stack in the CSV format consumed by Qiskit Metal.

Return type:

Path

squadds.simulations.drivenmodal.write_touchstone_from_dataframe(frame, *, matrix_size, output_path, z0_ohms=50.0)

Write a Touchstone file from an HFSS S-parameter dataframe.

Return type:

Path

squadds.simulations.drivenmodal.y_to_s(y_matrices, *, z0_ohms=50.0)

Convert a sweep of admittance matrices into scattering matrices for a uniform reference impedance.

Return type:

ndarray