fitting ¤
Stable S-parameter fitting API for Circulax.
Modules:
| Name | Description |
|---|---|
aaa | AAA (Adaptive Antoulas-Anderson) rational approximation. |
aaa_jax | Fixed-capacity JAX AAA discovery, comparable to the NumPy scalar AAA. |
aaa_numpy | NumPy-only scalar AAA discovery, preserved from vfitax. |
api | Stable S-parameter fitting, validation, and circuit-construction API. |
conditioning_numpy | Vectorized sample-domain conditioning, independently implemented in NumPy. |
delay_selection | Conservative propagation-delay inference for low-reflection two-ports. |
driver | VFdriver equivalent: two-phase iterative Vector Fitting. |
enforcement_numpy | Experimental fixed-pole, finite-grid rational S passivity enforcement. |
passivity | |
pole_id | Stage 1: Pole identification via Fast Relaxed Vector Fitting. |
pole_sweep | Fixed-shape, vmapped screening of scattering-model pole budgets. |
reduction_numpy | NumPy/SciPy S-domain AAA, compact pole screening, and relaxed VF. |
residue_id | Stage 2: Residue identification via weighted least squares. |
rlgc | Compact causal two-port models of uniform, frequency-dependent RLGC lines. |
sparam | S-parameter preprocessing with delay de-embedding for vector fitting. |
surface | Differentiable fixed-pole rational surface fitting prototype. |
types | Core data structures for Circulax rational fitting. |
utils | Utility functions: pole initialisation, data reshaping, weights, error. |
validation | Pre-simulation validation for rational S-parameter surface fits. |
vectfit | Single Vector Fitting iteration: pole identification + residue identification. |
Classes:
| Name | Description |
|---|---|
CharacteristicLineModel | Uniform line as characteristic admittance and delayed propagation. |
DelayInferenceOptions | Conservative controls for propagation-delay inference. |
DelayInferenceWarning | Emitted when requested delay inference returns the undelayed baseline. |
ModelCoefficients | Portable S(s)=D+sum(R_k/(s-p_k)) coefficients; no hidden conversion. |
ModelFitOptions | Controls for proper S fitting with optional one-way port delays. |
ModelValidationReport | Validation evidence for admitting fitted coefficients to simulation. |
RationalResponse | Scalar |
Functions:
| Name | Description |
|---|---|
circuit_from_coefficients | Build a simulation-ready :class: |
fit_model | Fit S data and return coefficients only, without making a component. |
fit_rlgc | Fit a reduced uniform-line model, checked before admission to simulation. |
fit_rlgc_characteristic | Fit a uniform line by its characteristic admittance and de-embedded delay. |
rlgc_sparameters | Evaluate an exact uniform line on the supplied frequency grid. |
validate_model | Validate fitted coefficients without compiling a circuit. |
CharacteristicLineModel dataclass ¤
CharacteristicLineModel(
length: float,
delay: float,
resistance_floor: float,
conductance_floor: float,
admittance: RationalResponse,
propagation: RationalResponse,
metadata: dict,
)
Uniform line as characteristic admittance and delayed propagation.
With port currents I1, I2 flowing into the line,
Yc*V1 - I1 = H * (Yc*V2 + I2) and Yc*V2 - I2 = H * (Yc*V1 + I1),
where H(s) = exp(-gamma*length) = exp(-s*delay) * propagation(s). The exact delay is removed before fitting, so propagation and admittance are smooth and need few poles even for long lines.
Methods:
| Name | Description |
|---|---|
circuit | Realize the model as a transient/AC/HB-capable two-port |
propagation_function | Fitted |
sparameters | S-parameters of the fitted model, shape |
circuit ¤
Realize the model as a transient/AC/HB-capable two-port Circuit.
propagation_function ¤
Fitted exp(-gamma*length), including the exact delay.
Source code in circulax/fitting/rlgc.py
sparameters ¤
S-parameters of the fitted model, shape (frequencies, 2, 2).
Source code in circulax/fitting/rlgc.py
DelayInferenceOptions dataclass ¤
DelayInferenceOptions(
min_transmission: float = 0.05,
phase_residual: float = 0.05,
direction_tolerance: float = 0.05,
reflection_threshold: float = 0.05,
delay_fractions: tuple[float, ...] = (1.0, 0.5),
reciprocity_tolerance: float = 0.02,
passivity_tolerance: float = 0.01,
validation_fraction: float = 0.2,
validation_degradation: float = 0.1,
)
Conservative controls for propagation-delay inference.
Inference is limited to passive, approximately reciprocal, low-reflection two-ports. By default, 20% of the frequencies are reserved for candidate selection, and the selected configuration is refitted on all samples.
DelayInferenceWarning ¤
Bases: RuntimeWarning
Emitted when requested delay inference returns the undelayed baseline.
ModelCoefficients dataclass ¤
ModelCoefficients(
poles: ndarray,
residues: ndarray,
D: ndarray,
z0: float = 50.0,
frequency_range: tuple[float, float] = (0.0, 0.0),
metadata: dict = dict(),
port_delays: ndarray | None = None,
)
Portable S(s)=D+sum(R_k/(s-p_k)) coefficients; no hidden conversion.
Arrays use full conjugate-pair storage and poles in rad/s. Frequencies are Hz, z0 is a common real impedance in ohms. port_delays are one-way seconds. evaluate returns P S_core P; there is no proportional term. Diagnostics are informational, never a trusted passivity certificate.
Methods:
| Name | Description |
|---|---|
evaluate | Evaluate complex S-parameters at frequencies in Hz. |
evaluate_core | Evaluate the rational core, before one-way port delays (seconds). |
load | Read and validate an archive without executing pickled objects. |
save | Write a versioned NPZ archive (no pickle); preserve the exact path. |
evaluate ¤
Evaluate complex S-parameters at frequencies in Hz.
Source code in circulax/fitting/api.py
evaluate_core ¤
Evaluate the rational core, before one-way port delays (seconds).
load classmethod ¤
load(path: str | Path) -> ModelCoefficients
Read and validate an archive without executing pickled objects.
Source code in circulax/fitting/api.py
save ¤
Write a versioned NPZ archive (no pickle); preserve the exact path.
Source code in circulax/fitting/api.py
ModelFitOptions dataclass ¤
ModelFitOptions(
delay_mode: Literal["none", "supplied", "infer"] = "none",
port_delays: tuple[float, ...] | None = None,
max_delay: float | None = None,
delay_inference: DelayInferenceOptions = DelayInferenceOptions(),
method: Literal["vector_fitting", "aaa"] = "vector_fitting",
vector_fit_order: tuple[int, int] | None = None,
aaa_backend: Literal["numpy", "jax"] = "numpy",
tol: float = 1e-08,
mmax: int = 12,
iterations: int = 6,
reciprocal: bool = True,
screening: Literal["compact", "masked"] = "compact",
reduction_stage: Literal["initial", "refined"] = "refined",
normalized_rmse: float = 0.02,
max_absolute_error: float = 0.05,
enforce_passivity: bool = False,
passivity_limit: float = 0.999999,
enforcement_iterations: int = 300,
enforcement_freqs: tuple[float, ...] | None = None,
)
Controls for proper S fitting with optional one-way port delays.
Conventional scikit-rf vector fitting is the default. AAA is experimental. JAX selects AAA discovery only; refinement and enforcement use NumPy/SciPy. Supplied initial poles bypass either discovery backend and reduction, using the NumPy residue/refinement solver. They are relocated unless iterations=0. Error limits apply AFTER optional enforcement as well.
ModelValidationReport dataclass ¤
ModelValidationReport(
status: Literal["pass", "warn", "fail"],
training_nrmse: float | None,
training_max_error: float | None,
validation_nrmse: float | None,
validation_max_error: float | None,
maximum_singular_value: float,
maximum_s_pole_real_part: float,
maximum_y_pole_real_part: float,
findings: tuple[str, ...],
)
Validation evidence for admitting fitted coefficients to simulation.
Methods:
| Name | Description |
|---|---|
raise_for_simulation | Raise when the report does not admit the model to simulation. |
Attributes:
| Name | Type | Description |
|---|---|---|
simulation_ready | bool | Whether validation passed without findings. |
RationalResponse dataclass ¤
Scalar constant + sum(residues / (s - poles)) with poles in rad/s.
Complex poles are stored with their conjugates, so the response is real for real s.
Methods:
| Name | Description |
|---|---|
evaluate | Evaluate the response at frequencies in Hz. |
evaluate ¤
Evaluate the response at frequencies in Hz.
Source code in circulax/fitting/rlgc.py
circuit_from_coefficients ¤
circuit_from_coefficients(
coefficients: ModelCoefficients | str | Path,
*,
name: str = "FittedModel",
holomorphic: bool = True
) -> Circuit
Build a simulation-ready :class:circulax.Circuit from coefficients.
The return type is the same for rational cores, delayed models, and ideal through lines. Fitting and passivity enforcement never occur here.
Source code in circulax/fitting/api.py
fit_model ¤
fit_model(
S: ndarray,
freqs: ndarray,
*,
options: ModelFitOptions | None = None,
z0: float = 50.0,
initial_poles: ndarray | None = None
) -> ModelCoefficients
Fit S data and return coefficients only, without making a component.
Automatic order selection is the default. Optional enforcement is sampled, not globally certified; independent rational testing remains necessary.
Source code in circulax/fitting/api.py
390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 | |
fit_rlgc ¤
fit_rlgc(
frequencies: ArrayLike,
*,
R: ArrayLike | Callable[[ndarray], ArrayLike],
L: ArrayLike | Callable[[ndarray], ArrayLike],
G: ArrayLike | Callable[[ndarray], ArrayLike],
C: ArrayLike | Callable[[ndarray], ArrayLike],
length: float,
z0: float = 50.0,
options: ModelFitOptions | None = None
) -> ModelCoefficients
Fit a reduced uniform-line model, checked before admission to simulation.
Fit the exact distributed two-port, reserving every fifth interior sample for validation. At least six frequency samples are required. Defaults use reciprocal vector fitting with sampled passivity enforcement. The proper stable realization is causal; this does not certify arbitrary input data or extrapolation. Passivity is enforced/tested on a grid, not globally certified.
Supplied options can choose order, tolerances and optional native delays (delay_mode='supplied' or 'infer'). Reciprocity is required. Disabling enforcement still requires the resulting fit to pass passivity validation. Returned coefficients can be saved or passed to circuit_from_coefficients.
Source code in circulax/fitting/rlgc.py
fit_rlgc_characteristic ¤
fit_rlgc_characteristic(
frequencies: ArrayLike,
*,
R: ArrayLike | Callable[[ndarray], ArrayLike],
L: ArrayLike | Callable[[ndarray], ArrayLike],
G: ArrayLike | Callable[[ndarray], ArrayLike],
C: ArrayLike | Callable[[ndarray], ArrayLike],
length: float,
tolerance: float = 0.001,
max_order: int = 40,
delay_fraction: float = 0.98,
z0: float = 50.0
) -> CharacteristicLineModel
Fit a uniform line by its characteristic admittance and de-embedded delay.
The propagation delay delay_fraction times the phase delay at the highest frequency is removed exactly, rather than approximated by poles. The characteristic admittance Yc = sqrt(Y/Z) and the remaining propagation exp(-gamma*length + s*delay) are fitted separately with the same order, increased from 4 until every check passes:
- maximum absolute S error (reference
z0) on all samples, including held-out ones, against the supplied, unfloored RLGC is withintolerance; - stable poles;
- sampled passivity (largest singular value of S at most 1),
Re(Yc) >= 0and|propagation| <= 1on a grid from DC to ten times the band.
A DC sample is required and the fitted DC values are pinned exactly, so the floored model is exact at DC. With G = 0 (or R = 0) the DC resistance is the ratio of two vanishing quantities. Conductance and resistance are therefore floored at 2*pi*f_low*C and 2*pi*f_low*L, where f_low is the lowest nonzero frequency, putting the floors' corner inside the grid. Their effect is included in the S check. Lower f_low if it fails. Sampled passivity is not a global certificate, and input causality is not certified.
Source code in circulax/fitting/rlgc.py
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 | |
rlgc_sparameters ¤
rlgc_sparameters(
frequencies: ArrayLike,
*,
R: ArrayLike | Callable[[ndarray], ArrayLike],
L: ArrayLike | Callable[[ndarray], ArrayLike],
G: ArrayLike | Callable[[ndarray], ArrayLike],
C: ArrayLike | Callable[[ndarray], ArrayLike],
length: float,
z0: float = 50.0
) -> ndarray
Evaluate an exact uniform line on the supplied frequency grid.
RLGC are nonnegative per-metre scalars, arrays or functions of Hz, in ohm/m, H/m, S/m and F/m. This frequency-domain calculation does not make arbitrary input curves causal. No junction loading or termination is added.
Source code in circulax/fitting/rlgc.py
validate_model ¤
validate_model(
coefficients: ModelCoefficients | str | Path,
*,
measured_S: ndarray | None = None,
freqs: ndarray | None = None,
validation_S: ndarray | None = None,
validation_freqs: ndarray | None = None,
simulation_frequency_range: tuple[float, float] | None = None,
expected_passive: bool = True,
expected_reciprocal: bool = True,
normalized_rmse: float = 0.02,
max_absolute_error: float = 0.05,
passivity_tolerance: float = 1e-09
) -> ModelValidationReport
Validate fitted coefficients without compiling a circuit.
Accuracy checks are performed when measured data are supplied. Independent validation requires both validation_S and validation_freqs. Passivity is required by default; active models must opt out explicitly.
Source code in circulax/fitting/api.py
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 | |