Hand off an already fitted line model from external network data

Start with the supported boundary

JoSIM®-Pro 2.9 does not directly import arbitrary Touchstone S-parameter files or fit sampled network data. It accepts supported circuit/line models, including an already fitted passive scalar real-pole WIDEBAND model. Renaming an .s2p file, including it as circuit text or inventing a .MODEL ... S2P declaration does not convert the network.

First decide whether the external network can be represented by a supported model family. A resonant multiport, arbitrary complex-pole fit or frequency-dependent multiconductor matrix cannot be assumed equivalent to a uniform scalar line. If the supported form cannot represent the required behaviour, retain an explicit handoff limit rather than forcing coefficients into the wrong model.

If you start with S-parameter data from InductEx® or TetraHenry®, use the linked plotting/export and frequency-refinement guides to identify the source data and its resolution. Obtaining an accepted WIDEBAND coefficient model remains a separate step; a data or plot file alone does not supply that model.

Prepare an external fit without losing the reference conventions

In the supplied Version 1.0-style two-port reference, # Hz S RI R 50 declares hertz, scattering parameters, real/imaginary pairs and a common real 50-ohm reference. Pair order is S11, S21, S12, S22. The official IBIS specification also describes other versions, orders and formats; this deliberately small teaching parser does not implement them.

1. Retain the original complex data, frequency units and band, physical port map, reference conductors/planes, reference impedances and any de-embedding. Record whether ports are single-ended or mixed-mode. A magnitude-only curve cannot preserve phase or establish the required time-domain network.
2. Choose a supported topology and fit form. For a scalar uniform line, obtain its length and per-length base R/L/G/C and, when needed, real-pole R/G increments. Keep the external fit procedure, residuals, causality/passivity assessment and validity band with the model.
3. Convert the coefficient basis and units explicitly, then validate the complete JoSIM model against the original complex response under matching termination/reference conditions. Increase NSEG and check numerical sensitivity separately from fit error.
4. If the representation, reference conversion or validity evidence is missing, stop at that missing step. This knowledge-base client checks a supplied model; it does not provide the external fitter or recover missing measurement metadata.

Express the accepted real-pole basis

For this model, s = j·2πf. R(s) = RPERL + Σ RDELTA[k]·s/(s + 2π·RFREQ[k]); G(s) has the corresponding GDELTA/GFREQ terms. Series impedance per length is R(s) + s·LPERL; shunt admittance per length is G(s) + s·CPERL. Pole frequencies in the JoSIM lists are Hz, not angular rates in rad/s.

A fitter using D + Σ residue/(s + pole) has a different coefficient basis. Algebraically, Δ·s/(s+p) = Δ − Δ·p/(s+p). Copying raw residues into RDELTA/GDELTA would therefore change the model, including its sign and constant term. Rewrite the representation and recheck its response before use.

Base R/G and all increments must be nonnegative; L/C must be positive. Matching frequency/increment lists have equal length, strictly increasing positive frequencies and at most 64 terms per list. The core rejects negative increments and unpaired lists. That validation does not fit data or repair an invalid external model.

Use the complete synthetic example

The five-file download supplies forward.cir, reverse.cir, wb_model.cir, reference.s2p and check_handoff.py. The line is 1 mm long. Its SI per-metre base values are R = 500 Ω/m, L = 250 nH/m, G = 0.001 S/m and C = 100 pF/m. One series-loss increment is 1000 Ω/m at 5 GHz; one shunt-loss increment is 0.002 S/m at 10 GHz. FMAX is 20 GHz.

This is a public synthetic uniform-line example, not a fit to measured hardware. The reference is the continuous line’s analytic ABCD response at 21 frequencies from 1 to 20 GHz. JoSIM uses a finite section model. Their comparison tests model admission, port reconstruction and spatial discretisation without pretending that synthetic data establish physical accuracy.

Both ports are single-ended relative to node 0 at the line ends, with real 50-ohm reference impedances. LEN uses metres consistently with the per-metre coefficients. The source and load resistors each equal 50 ohms. This symmetric reciprocal example cannot independently identify every possible port-order mistake in an unrelated network.

Run and inspect the model in JoSIM®-Pro

1. Extract all five files into a new writable folder. Open forward.cir, keep wb_model.cir beside it and save the intended source. Use a compatible licensed 2.9 GUI with the required runtime/daemon.
2. Choose a new CSV destination under a writable results directory in Run > Run settings..., then Run simulation. Inspect the current AC case, diagnostics and the complex magnitude/phase panels for V(P1) and V(P2). The frequency axis is displayed in GHz; CSV stores Hz.
3. Run reverse.cir into a different destination. The source now excites P2 while the physical P1/P2 labels remain fixed. Retain both typed complex CSVs and their current case/configuration records.
4. Reopen a newly committed AC CSV through File > Open to inspect it as a complex imported-result tab. This inspection does not rerun the circuit or import Touchstone data.

Reconstruct all four scattering parameters

The source is a 1 V peak, zero-phase Thevenin voltage behind 50 ohms; the opposite port is terminated in 50 ohms. For forward excitation, S11 = 2·V(P1) − 1 and S21 = 2·V(P2). For reverse excitation, S22 = 2·V(P2) − 1 and S12 = 2·V(P1). These formulas apply to this exact source amplitude/angle and equal real reference arrangement.

More generally divide each voltage by the complex source phasor before applying the same matched-source relationships. The common peak-to-RMS scale cancels in the dimensionless ratios; it does not make a peak voltage a power measurement. Unequal/complex references, mixed-mode transforms and other terminations need their own correct wave definitions and conversion.

Compare complex values at matching frequencies before reducing them to magnitude, dB or phase. The client stores S11, S21, S12 and S22 as real/imaginary columns. It also checks sampled maximum power-wave gain. A finite frequency-sample check is not a general proof of an arbitrary external model’s passivity or causality.

Check the supplied model from PowerShell

Run this complete command from the extracted teaching folder. Select your actual Python, compatible JoSIM 2.9 CLI and existing issued JoSIM licence path. The checked client uses 64-bit Windows CPython 3.13.11 and its standard library.

Use a new result directory. The client runs both port excitations at NSEG 4, 8 and 16, reconstructs scattering data and compares them with the supplied reference. It references the selected licence in an isolated child configuration without copying licence contents.

$ErrorActionPreference = 'Stop'
$python = 'python'
$josim = 'C:\Program Files\SUN Magnetics\JoSIM-Pro\bin\josim-pro-cli.exe'
$licence = 'C:\Program Files\SUN Magnetics\Licenses\sm_license_jpro.txt'
& $python -B .\check_handoff.py --josim $josim --licence $licence --results .\handoff-results
if ($LASTEXITCODE -ne 0) { throw 'The current model or reference comparison failed.' }
(Get-Content -LiteralPath .\handoff-results\receipt.json -Raw | ConvertFrom-Json).cases | Format-Table

Separate fit error, spatial refinement and device accuracy

The checked maximum absolute complex error across all four S entries and 21 frequencies is about 0.00182260 at NSEG 4, 0.000454280 at 8 and 0.000113485 at 16. The teaching criterion requires decreasing error and a finest error below 0.001; the coarse model does not meet that limit. These are dimensionless complex differences, not dB or a universal relative-accuracy tolerance.

At each level, model-response.csv contains frequency_Hz and paired real/imaginary columns for S11, S21, S12 and S22. receipt.json records current status, error, input/runtime identities and output hashes. Exit 0 with status passed means this complete example met its current checks; exit 2 means input, execution or comparison failure.

The reference has no external fitting residual because it was generated from the supplied continuous-line coefficients. A real external-data workflow must separately report its fit error, spatial discretisation, transient timestep sensitivity where relevant and agreement with the intended device. The AC example does not qualify transient timing or all line families.

Keep FMAX and failure recovery explicit

FMAX declares the intended fit band; it does not filter a transient waveform. Standalone AC rejects a sweep containing a frequency above FMAX. The native check deliberately requests 21 GHz against 20 GHz, confirms rejection and preservation of the earlier authoritative CSV, then reruns the original saved source into a fresh generation.

For a transient application, check the relevant signal spectrum against the model’s validity and repeat timestep and NSEG refinement separately. The manual’s initial guidance is at least ten timesteps per finite-line section transit time; that is a starting resolution estimate, not an accuracy guarantee. WIDEBAND fixed-step operation requires BDF and does not accept explicit ICV/ICI relaxation state.

A missing model/include, negative increment, unpaired frequency list or invented S2P model declaration must be corrected at its source. Do not silently discard a loss term, change its sign or widen FMAX to hide a failing validation. The complete parser refuses a 75-ohm reference rather than treating it as 50 ohms.

After correction, select a new results directory and require current complete typed outputs. Existing study generations are refused. Review private logs, source paths and configurations before sharing; an old file or a plausible magnitude plot is not proof that the current handoff succeeded.

Save forward.cir

* Port 1 driven by a 1 V peak Thevenin source with 50 ohm source impedance
.INCLUDE "wb_model.cir"
VDRIVE DRIVE 0 DC 0 AC 1 0
RSOURCE DRIVE P1 50
TLINE P1 0 P2 0 TYPE=WIDEBAND MODEL=WB LEN=1m NSEG=16
RLOAD P2 0 50
.OPTION SEED=27
.AC LIN 21 1G 20G
.PRINT AC V(P1) V(P2)
.END

Save reverse.cir

* Port 2 driven; the physical P1/P2 labels and 50 ohm reference are unchanged
.INCLUDE "wb_model.cir"
VDRIVE DRIVE 0 DC 0 AC 1 0
RSOURCE DRIVE P2 50
TLINE P1 0 P2 0 TYPE=WIDEBAND MODEL=WB LEN=1m NSEG=16
RLOAD P1 0 50
.OPTION SEED=27
.AC LIN 21 1G 20G
.PRINT AC V(P1) V(P2)
.END

Save wb_model.cir

* Public synthetic uniform-line coefficients; SI units per metre
* This supplied real-pole model was not fitted to a measured device
.MODEL WB WIDEBAND(RPERL=500 LPERL=250n GPERL=0.001 CPERL=100p RFREQ=(5G) RDELTA=(1000) GFREQ=(10G) GDELTA=(0.002) FMAX=20G)

Save reference.s2p

! Public synthetic uniform-line reference, not measured customer data
! 1 mm line; R=500 ohm/m L=250nH/m G=0.001S/m C=100pF/m
! Dynamic R: 1000*s/(s+2*pi*5GHz); dynamic G: 0.002*s/(s+2*pi*10GHz)
! Port 1=P1-to-ground; port 2=P2-to-ground; both reference planes at line ends
! Touchstone 1 two-port order: S11 S21 S12 S22; real/imaginary; real 50 ohm
! Continuous uniform-line ABCD model, independent of the finite JoSIM ladder
# Hz S RI R 50
1000000000 0.0053898014893489178 0.0017290816792524487 0.99406459176418105 -0.033148419655665728 0.99406459176418105 -0.033148419655665728 0.0053898014893489178 0.0017290816792524487
1950000000 0.0064523793192443508 0.0029422873075120866 0.99161297417561112 -0.064182357171455817 0.99161297417561112 -0.064182357171455817 0.0064523793192443508 0.0029422873075120866
2900000000 0.0077948983930122779 0.0035628853453049092 0.98798698236366345 -0.094569475880433046 0.98798698236366345 -0.094569475880433046 0.0077948983930122779 0.0035628853453049092
3850000000 0.0091207772904957247 0.0036506110386246844 0.98348457094109532 -0.12434200528405333 0.98348457094109532 -0.12434200528405333 0.0091207772904957247 0.0036506110386246844
4800000000 0.010270697888394683 0.0033600217630603952 0.9782678388733318 -0.15362688465063143 0.9782678388733318 -0.15362688465063143 0.010270697888394683 0.0033600217630603952
5750000000 0.011196217883880397 0.0028394147426105062 0.97238923491556872 -0.18254509027261784 0.97238923491556872 -0.18254509027261784 0.011196217883880397 0.0028394147426105062
6700000000 0.01190680185656285 0.0021961197456278922 0.96584426098656928 -0.21117704738316451 0.96584426098656928 -0.21117704738316451 0.01190680185656285 0.0021961197456278922
7650000000 0.012432879152412275 0.001498028413172614 0.95860824128722311 -0.23956412569973776 0.95860824128722311 -0.23956412569973776 0.012432879152412275 0.001498028413172614
8600000000 0.012807734555132032 0.00078495166337951266 0.95065435701918011 -0.26771993053300797 0.95065435701918011 -0.26771993053300797 0.012807734555132032 0.00078495166337951266
9550000000 0.013060690959274042 7.9051332891359944e-05 0.94196044690286951 -0.2956406853957626 0.94196044690286951 -0.2956406853957626 0.013060690959274042 7.9051332891359944e-05
10500000000 0.013215506493385877 -0.00060793383251659674 0.93251061763168963 -0.32331243524480124 0.93251061763168963 -0.32331243524480124 0.013215506493385877 -0.00060793383251659674
11450000000 0.013290755899483489 -0.0012702030919577499 0.92229487599614612 -0.35071552995411753 0.92229487599614612 -0.35071552995411753 0.013290755899483489 -0.0012702030919577499
12400000000 0.013300771632662625 -0.0019052484637662598 0.91130819911837802 -0.37782728169477237 0.91130819911837802 -0.37782728169477237 0.013300771632662625 -0.0019052484637662598
13350000000 0.013256600355583103 -0.0025123346231210328 0.89954958450551814 -0.40462350499730887 0.89954958450551814 -0.40462350499730887 0.013256600355583103 -0.0025123346231210328
14300000000 0.013166806354808176 -0.0030916388774299866 0.8870212482215204 -0.43107940062783867 0.8870212482215204 -0.43107940062783867 0.013166806354808176 -0.0030916388774299866
15250000000 0.013038097522104119 -0.003643771118605386 0.87372799624215158 -0.45717006102247559 0.87372799624215158 -0.45717006102247559 0.013038097522104119 -0.003643771118605386
16200000000 0.012875796792176628 -0.004169510629507601 0.85967674698456698 -0.48287075910001948 0.85967674698456698 -0.48287075910001948 0.012875796792176628 -0.004169510629507601
17150000000 0.012684191872441986 -0.0046696660609361817 0.84487617296181994 -0.50815711347323811 0.84487617296181994 -0.50815711347323811 0.012684191872441986 -0.0046696660609361817
18100000000 0.012466793310360108 -0.0051450050169651838 0.82933643213212127 -0.53300518332009805 0.82933643213212127 -0.53300518332009805 0.012466793310360108 -0.0051450050169651838
19050000000 0.012226524932187149 -0.0055962226345087898 0.81306896536015749 -0.55739152342066489 0.81306896536015749 -0.55739152342066489 0.012226524932187149 -0.0055962226345087898
20000000000 0.011965864802212001 -0.0060239316453527319 0.79608634216009289 -0.58129321685738233 0.79608634216009289 -0.58129321685738233 0.011965864802212001 -0.0060239316453527319

Save check_handoff.py

"""Check an already supplied scalar WIDEBAND model against a two-port reference.

This complete teaching client does not fit or convert arbitrary Touchstone data.
The public reference is synthetic and follows the declared uniform-line model.
"""
import argparse,csv,hashlib,io,json,math,os,shutil,subprocess,sys
from pathlib import Path

NAMES=('forward.cir','reverse.cir','wb_model.cir','reference.s2p','check_handoff.py')
def sha(p):return hashlib.sha256(p.read_bytes()).hexdigest()

def reference(path):
    rows=[];option=False
    for line in path.read_text(encoding='ascii').splitlines():
        text=line.split('!',1)[0].strip()
        if not text:continue
        if text.startswith('#'):
            if option or text.upper().split()!=['#','HZ','S','RI','R','50']:
                raise ValueError('This teaching parser requires one # Hz S RI R 50 option line.')
            option=True;continue
        if not option:raise ValueError('Missing explicit frequency/format/reference convention.')
        values=[float(x) for x in text.split()]
        if len(values)!=9 or not all(math.isfinite(v) for v in values):raise ValueError('Expected nine finite numbers per two-port RI row.')
        f=values[0]
        if f<=0 or (rows and f<=rows[-1][0]):raise ValueError('Reference frequencies must be positive and strictly increasing.')
        # Touchstone 1 two-port order: S11, S21, S12, S22.
        s=[complex(values[i],values[i+1]) for i in (1,3,5,7)]
        rows.append((f,s))
    if len(rows)!=21 or rows[0][0]!=1e9 or rows[-1][0]!=20e9:raise ValueError('Use the complete supplied 21-point reference.')
    return rows

def ac(path):
    first,rest=path.read_text(encoding='utf-8-sig').split('\n',1)
    if not first.startswith('# josim-ac-csv/1 '):raise ValueError('Expected typed complex AC data, not transient samples.')
    metadata=json.loads(first[len('# josim-ac-csv/1 '):])
    reader=csv.reader(io.StringIO(rest));names=next(reader)
    if names!=['frequency (Hz)','Re(V(P1)) (V)','Im(V(P1)) (V)','Re(V(P2)) (V)','Im(V(P2)) (V)']:
        raise ValueError('Unexpected phasor columns or port order.')
    rows=[[float(v) for v in row] for row in reader if row]
    if len(rows)!=21 or not all(len(row)==5 and all(math.isfinite(v) for v in row) for row in rows):
        raise ValueError('Missing, malformed or nonfinite current AC values.')
    return rows,metadata

def sampled_max_gain_squared(s):
    s11,s21,s12,s22=s
    a=abs(s11)**2+abs(s21)**2;d=abs(s12)**2+abs(s22)**2
    b=s11.conjugate()*s12+s21.conjugate()*s22
    return (a+d+math.sqrt((a-d)**2+4*abs(b)**2))/2

def main():
    p=argparse.ArgumentParser(description=__doc__);p.add_argument('--josim',type=Path,required=True);p.add_argument('--licence',type=Path,required=True);p.add_argument('--results',type=Path,required=True);a=p.parse_args()
    try:
        root=Path(__file__).resolve().parent;original={n:sha(root/n) for n in NAMES};ref=reference(root/'reference.s2p')
        binary,licence=[x.resolve(strict=True) for x in (a.josim,a.licence)];work=a.results.absolute()
        if not binary.is_file() or not licence.is_file():raise ValueError('Select existing compatible CLI and issued licence files.')
        if work.exists() or not work.parent.is_dir():raise ValueError('Use a new results directory under an existing parent.')
        work.mkdir();home=work/'private-home';config=home/'.josimpro';config.mkdir(parents=True)
        (config/'config.ini').write_text('[General]\nLicenseLocation='+str(licence)+'\n',encoding='utf-8')
        env=os.environ.copy();env['HOME']=str(home);env['USERPROFILE']=str(home);env['LD_LIBRARY_PATH']=str(binary.parent)+':'+env.get('LD_LIBRARY_PATH','')
        receipt={'status':'running','inputs':original,'josim_sha256':sha(binary),'cases':[],
                 'scope':'Supplied synthetic 50-ohm scalar uniform-line model, two excitations and 4/8/16 spatial sections; no arbitrary fitting, device validation or final-package qualification.'}
        def save():(work/'receipt.json').write_text(json.dumps(receipt,indent=2)+'\n',encoding='utf-8')
        save()
        for sections in (4,8,16):
            folder=work/f'sections-{sections}';folder.mkdir();shutil.copyfile(root/'wb_model.cir',folder/'wb_model.cir');ports={}
            for direction in ('forward','reverse'):
                deck=folder/(direction+'.cir');deck.write_text((root/(direction+'.cir')).read_text(encoding='utf-8').replace('NSEG=16',f'NSEG={sections}'),encoding='utf-8')
                with (folder/(direction+'-private.log')).open('wb') as log:
                    run=subprocess.run([str(binary),'--minimal','-P','17','-o',direction+'.csv',direction+'.cir'],cwd=folder,env=env,stdout=log,stderr=subprocess.STDOUT,timeout=120)
                if run.returncode:raise RuntimeError('Current '+direction+' AC failed at NSEG='+str(sections)+'; inspect its private diagnostic.')
                ports[direction],_=ac(folder/(direction+'.csv'))
            errors=[];output=[]
            for (f,expected),fw,rv in zip(ref,ports['forward'],ports['reverse']):
                if abs(fw[0]-f)>1e-12*f or fw[0]!=rv[0]:raise ValueError('Frequency coordinates differ; no interpolation is performed.')
                vp1,vp2=complex(fw[1],fw[2]),complex(fw[3],fw[4]);rp1,rp2=complex(rv[1],rv[2]),complex(rv[3],rv[4])
                s=[2*vp1-1,2*vp2,2*rp1,2*rp2-1]
                errors += [abs(x-y) for x,y in zip(s,expected)]
                if sampled_max_gain_squared(s)>1+1e-10:raise ValueError('Sampled model response has power-wave gain above one.')
                output.append([f,*[v for x in s for v in (x.real,x.imag)]])
            with (folder/'model-response.csv').open('x',newline='',encoding='utf-8') as stream:
                writer=csv.writer(stream);writer.writerow(['frequency_Hz','S11_re','S11_im','S21_re','S21_im','S12_re','S12_im','S22_re','S22_im']);writer.writerows(output)
            receipt['cases'].append({'NSEG':sections,'frequencies':21,'maximum_absolute_complex_error':max(errors),
              'response_sha256':sha(folder/'model-response.csv'),'forward_csv_sha256':sha(folder/'forward.csv'),'reverse_csv_sha256':sha(folder/'reverse.csv')});save()
        errors=[row['maximum_absolute_complex_error'] for row in receipt['cases']]
        if not errors[2]<errors[1]<errors[0] or errors[-1]>.001:raise ValueError('The supplied spatial-refinement/reference criterion was not met.')
        if any(sha(root/n)!=h for n,h in original.items()):raise ValueError('An original teaching input changed.')
        receipt.update(status='passed',inputs_preserved=True,reference_impedance_ohm=50,frequency_range_Hz=[1e9,20e9]);save()
        print(json.dumps({'status':'passed','maximum_absolute_complex_errors':errors}));return 0
    except (OSError,ValueError,RuntimeError,subprocess.TimeoutExpired) as error:
        if 'receipt' in locals():receipt.update(status='failed',reason=str(error));save()
        print(str(error),file=sys.stderr);return 2

if __name__=='__main__':raise SystemExit(main())