Compare cases and create derived traces or measurements

Compare current cases before combining traces

Use the run-case explorer to compare separate successful cases, then Trace Manager to organise their traces or calculate a derived output. These are separate actions. A comparison plot adds a view over existing data; subtraction creates new sampled values. Neither rewrites the source circuit.

Extract the complete two-file teaching download. compare.cir runs bias 1 mA then 2 mA, with resistance 3, 2 then 1 ohm. The last .STEP dimension advances fastest. Cases 1 and 4 therefore share 3 ohm resistance and differ only in bias: V(N) is 3 mV and 6 mV; I(R1) is 1 mA and 2 mA. Each case has fresh state.

1. Open compare.cir in a compatible licensed JoSIM 2.9 GUI. Save source and select a new native CSV destination in a separate writable results folder through Run > Run settings.... Keep buffered output with interactive data retained, then run the complete saved deck.
2. Open the run-case explorer beside the result selector. Check cases tran-001.case-1 and tran-004.case-4 and choose Compare plots. The native check exercises the actual explorer and its Compare plots action.
3. Check both current case IDs and the “matching output time coordinates” comparison note. The example creates four source series: voltage/current for each selected case. Keep current case details and committed paths with any exported comparison.

Understand the comparison limits

Transient plot comparison accepts 2–8 successful retained cases, at most 128 series and a bounded display budget. Selected transient cases must have identical output time coordinates; no resampling is performed. Stale, failed, file-only or other ineligible cases need the comparison table or committed data instead. Filtering or sorting the case list does not change the underlying plan.

IV case comparison uses independent voltage coordinates in separate panels. OP, DC and AC results have different result contracts; a transient overlay is not a general cross-analysis conversion. The checked walkthrough here uses only the supplied fixed-step transient cases.

Subtract two voltage traces

1. Open Run > Trace Manager and select Analysis. Choose Operation Subtract, Source trace tran-004.case-4 :: "V(N)" and Right trace tran-001.case-1 :: "V(N)".
2. Enter delta_voltage as Output name. Leave “Also add a comparison plot” enabled when you want the source/derived overlay as well, then choose Create derived.
3. Check that all four source traces remain and delta_voltage appears as a fifth trace. For this exact example it is 0.003 V at each of the 1,001 retained sample coordinates. Reversing the operands changes the sign.

Apply a scalar and record a separate measurement

A derived trace contains a value at each coordinate; a scalar measurement summarises the selected data. Operations come from the supported menu rather than an arbitrary expression language. Check units yourself, especially for multiplication, division, calculus and logarithms. The UI does not provide a general dimensional-algebra guarantee.

1. Choose the x/k scalar-division operation and delta_voltage as the source. Set k = 2 and Output name half_delta, then Create derived. The result is 0.0015 V. A zero k disables creation and reports “Scalar division requires non-zero k”; correct it before continuing.
2. Choose Measure mean, select delta_voltage and enter delta_mean. The action changes from Create derived to Measure. Choose it and inspect the separate scalar entry delta_mean = 0.003 V.
3. Use the Selection tab to hide, rename, group or reorder items deliberately. Select at least two compatible traces and Compare to add a view. Removing an added comparison view does not replace source values.

Check the actual time coordinates

The case explorer’s transient comparison uses exact coordinate equality. Do not assume that a general Trace Manager operation provides the same guarantee for unrelated imported series.

KB-TRACE-001: a detached production-workspace check accepts [0, 100 ps] and [0, 200 ps] as compatible and permits index-by-index subtraction. Its common axis tolerance has a 1 ns absolute floor for these SI time coordinates; a larger 10 ns coordinate mismatch is rejected. This is a reproduced owner-level check, not a physical mismatched-file GUI walkthrough.

Before combining independently sourced traces, compare all stored x coordinates. If they differ, keep them in separate views or perform a deliberate, documented resampling outside this route. The complete CSV client below rejects any coordinate mismatch and never silently interpolates. The supplied native case comparison uses genuinely matching coordinates.

Export and retain the right evidence

Plot export studio’s CSV/TSV formats write numerical data; figure formats write presentation. Keep the intended scope, current case IDs and original committed files. In the checked production all-visible CSV export, additive comparison panels repeat their member series: 12 columns comprise time and 11 displayed-series columns, including repeated headers.

Do not load that all-visible file into a dictionary keyed only by header text: duplicate names can overwrite each other in such a reader. Preserve column order and inspect the complete header. The independent client’s difference.csv has three unique columns and is a simpler route for this specific numeric comparison; it is not the GUI’s export implementation.

The native check exports through the production service, removes half_delta, rebuilds the matching source comparison and reapplies its analysis recipes without warnings. This proves same-session matching-source restoration. It does not prove automatic application restart/session restoration; that remains a separate known limitation.

KB-OUTPUT-002: two later native attempts failed to commit case 2 with a Windows sharing-violation diagnostic. A new generation with an explicit destination outside the source folder completed. The lock owner and cause remain unknown; the new path is a checked recovery instance, not a product repair. Retain the failed receipt, resolve any known open output handle and use a new destination rather than accepting partial files as a complete run.

Compare the case CSVs 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 host uses 64-bit Windows CPython 3.13.11. Use a new results directory; the client references the licence in an isolated child configuration without copying its contents.

The client runs the complete six-case deck, verifies the current case files and writes difference.csv plus receipt.json. This is independent standard-library CSV arithmetic; it does not call a JoSIM GUI recipe API or discover unsaved GUI buffers. The same complete input bytes also passed on the recorded maintained Linux CLI candidate.

$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 .\run_compare.py --josim $josim --licence $licence --results .\comparison-results
if ($LASTEXITCODE -ne 0) { throw 'The current sweep or CSV comparison failed.' }
Get-Content -LiteralPath .\comparison-results\receipt.json -Raw | ConvertFrom-Json

Read the client result and recover

Exit 0 and receipt status passed mean this supplied study completed its current checks. Each case has 1,001 finite samples from 0 to 100 ns. difference.csv columns are time_s, delta_voltage_V and half_delta_V. The checked Windows and Linux initial differences and sample means are both 0.003 V; the DC source values already appear at time zero. Initial samples in a different circuit must be inspected rather than assumed.

The post-initial ideal-resistor check uses 1e-12 V/A for this teaching example. It is not a general solver accuracy or physical-device tolerance. CSV subtraction is checked against the actual two source columns at identical coordinates.

Exit 2 indicates input, runtime, output or comparison failure. Inspect the current private log and receipt, correct the issue and use a new directory. Existing generations are refused. Preserve source and the original case CSVs; private logs/configuration can contain local paths and need review before sharing.

FFT, masks, calculus, timing measurements, annotation export, every selection/layout action and full package/restart behaviour require their own checked examples. Their presence in the supported operation list does not mean this one arithmetic walkthrough qualifies them.

Save compare.cir

* Public six-case resistor comparison; every case has fresh state
.PARAM bias=1m
.PARAM resistance=1
I1 0 N DC bias
R1 N 0 resistance
.OPTION ANALYSIS=VOLTAGE INTEGRATION=BDF SEED=27
.STEP PARAM bias LIST 1m 2m
.STEP PARAM resistance LIST 3 2 1
.TRAN 1p 100n 0 100p
.PRINT V(N) I(R1)
.END

Save run_compare.py

"""Run the complete teaching sweep and independently subtract two case CSVs.

This standard-library client performs CSV arithmetic, not JoSIM GUI recipe APIs.
It checks the supplied ideal resistor example; it is not general device validation.
"""
import argparse,csv,hashlib,json,math,os,shutil,subprocess,sys
from pathlib import Path

def sha(p):return hashlib.sha256(p.read_bytes()).hexdigest()
def read_case(path):
    with path.open(encoding='utf-8-sig',newline='') as stream:
        reader=csv.DictReader(stream)
        if reader.fieldnames!=['time','V(N)','I(R1)']:raise ValueError('Unexpected current trace names.')
        rows=[[float(row[n]) for n in reader.fieldnames] for row in reader]
    if len(rows)!=1001 or not all(math.isfinite(v) for row in rows for v in row):raise ValueError('Expected 1001 finite samples.')
    if rows[0][0]!=0 or abs(rows[-1][0]-1e-7)>1e-20 or not all(a[0]<b[0] for a,b in zip(rows,rows[1:])):
        raise ValueError('Unexpected time range or non-increasing coordinates.')
    return rows

def difference(left,right):
    if len(left)!=len(right) or any(a[0]!=b[0] for a,b in zip(left,right)):
        raise ValueError('Time coordinates differ. No resampling is performed.')
    return [[a[0],b[1]-a[1],(b[1]-a[1])/2] for a,b in zip(left,right)]

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:
        binary,licence=[x.resolve(strict=True) for x in (a.josim,a.licence)];source=Path(__file__).resolve().with_name('compare.cir');original=sha(source);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 result 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','')
        shutil.copyfile(source,work/'compare.cir')
        receipt={'status':'running','input_sha256':original,'josim_sha256':sha(binary),'scope':'Complete six-case teaching deck and independent CSV subtraction; no GUI recipe or general accuracy qualification.'}
        def save():(work/'receipt.json').write_text(json.dumps(receipt,indent=2)+'\n',encoding='utf-8')
        save()
        with (work/'private-run.log').open('wb') as log:
            result=subprocess.run([str(binary),'--minimal','-P','17','-o','result.csv','compare.cir'],cwd=work,env=env,stdout=log,stderr=subprocess.STDOUT,timeout=120)
        receipt['exit_code']=result.returncode
        if result.returncode:raise RuntimeError('The current sweep failed; inspect its private diagnostic.')
        paths=[work/f'result.tran-{i:03d}.case-{i}.csv' for i in range(1,7)]
        if set(work.glob('*.csv'))!=set(paths):raise ValueError('Expected exactly six current case outputs.')
        cases=[read_case(path) for path in paths]
        for index,rows in enumerate(cases):
            current=.001 if index<3 else .002;resistance=[3,2,1][index%3]
            if not all(abs(row[1]-current*resistance)<1e-12 and abs(row[2]-current)<1e-12 for row in rows[1:]):
                raise ValueError('A post-initial case sample differs from the ideal resistor reference.')
        delta=difference(cases[0],cases[3])
        if not all(abs(row[1]-.003)<1e-12 and abs(row[2]-.0015)<1e-12 for row in delta[1:]):raise ValueError('The expected subtraction/half-difference check failed.')
        with (work/'difference.csv').open('x',encoding='utf-8',newline='') as stream:
            writer=csv.writer(stream);writer.writerow(['time_s','delta_voltage_V','half_delta_V']);writer.writerows(delta)
        if sha(source)!=original or sha(work/'compare.cir')!=original:raise ValueError('A source input changed.')
        mean=sum(row[1] for row in delta)/len(delta)
        receipt.update(status='passed',cases=6,samples_per_case=1001,compared_case_indexes=[1,4],initial_difference_V=delta[0][1],sample_mean_difference_V=mean,
            steady_difference_V=.003,inputs_preserved=True,outputs={path.name:sha(path) for path in [*paths,work/'difference.csv']})
        save();print(json.dumps({'status':'passed','cases':6,'samples_per_case':1001,'initial_difference_V':delta[0][1],'sample_mean_difference_V':mean}));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())