JSIM User's Manual¶

Version of manual: Release 2.1.2 (macOS/Linux/Windows Edition 2026)

JSIM - Josephson Junction Circuit Simulator

About This Manual¶

This manual documents JSIM Release 2.1, which includes:

Original JSIM functionality (Emerson Fang, UC Berkeley, 1992)
Stochastic noise extensions (Julian Satchell, DRA Malvern, 1997)
Modern platform support, detailed manual and new features (Pascal Febvre, 2026)

For legacy reference, the original manuals are included as appendices, the corresponding original content is in the legacy folder of the source code.

Table of Contents¶

Introduction
Installation and Usage
Circuit Description
Subcircuit Definition
Model Specification
Analysis Specification
Print and File Specifications
Option Specifications
Noise Simulation
Output Files
Command-Line Reference
Tips and Best Practices
Troubleshooting
Test Suite
Appendix A: Original Manual (1992)
Appendix B: Noise Extension Manual (1997)

1. Introduction¶

JSIM (Josephson SIMulator) is a circuit simulation program specifically designed for Josephson junction circuits used in superconducting electronics.

Supported Circuit Elements¶

Resistors (R)
Capacitors (C)
Inductors (L)
Mutual Inductors (K)
Independent Voltage Sources (V) - DC, sinusoidal, pulse, PWL, noise
Independent Current Sources (I) - DC, sinusoidal, pulse, PWL, noise
Lossless Transmission Lines (T)
Josephson Junctions (B)
Subcircuits (X)

Analysis Type¶

Only transient analysis is supported.

Input Format¶

JSIM's input format is similar to SPICE. If you are not familiar with SPICE, reading a SPICE user guide is recommended.

2. Installation and Usage¶

Compilation on macOS and linux¶

# Clone or extract JSIM source
cd jsim

# Compile
make clean
make

The executable is: jsim_n

Note for macOS users: On macOS, thejsim_n executable may be blocked from running the first time. If the command fails to launch, you first need to grant execute permission from within the directory: chmod +x jsim_n On recent versions of macOS, Gatekeeper may still block the process even after this. If that happens, open System Settings, go to Privacy & Security, and allow jsim_n to run. After that, ./jsim_n will work normally. This only needs to be done once.

Compilation on Windows¶

# Clone or extract JSIM source
cd jsim

# Compile
mingw32-make clean
mingw32-make

The executable is: jsim_n.exe

Basic Usage¶

# Simulate a circuit file
./jsim_n circuit.cir

# Display help
./jsim_n -h

# Show version
./jsim_n -v

# Save output to file
./jsim_n -o results.txt circuit.cir

# Input from stdin
./jsim_n < circuit.cir
cat circuit.cir | ./jsim_n

Platform Support¶

JSIM Release 2.1 compiles and runs on:

macOS (Intel x86_64 and Apple Silicon ARM64)
Linux (Ubuntu, CentOS, and compatible distributions)
Windows 64-bit (using MinGW-w64)

3. Circuit Description¶

3.1. Resistors¶

General form:

1	`RXXXX N1 N2 VALUE`

Example:

1 2	`RC1 12 9 1KOHM R1 1 0 50`

Notes:

RXXXX: Name must start with 'R'
N1 N2: Nodes (positive and negative)
VALUE: Resistance value (supports units: OHM, KOHM, MEGOHM)

3.2. Capacitors¶

General form:

1	`CXXXX N1 N2 VALUE <IC=VALUE>`

Example:

1 2	`C1 10 11 1PF C2 5 0 2.5PF IC=0V`

Notes:

Initial values may be specified but are currently ignored
Supports units: F, PF, NF, UF

3.3. Inductors¶

General form:

1	`LXXXX N1 N2 VALUE <FCHECK> <IC=VALUE>`

Example:

1 2	`L2 1 0 2.3PH FCHECK L1 3 4 5.0PH`

FCHECK option:

If specified, JSIM tracks flux changes through the inductor Φ = L × I (inductance × its branch current). At each timestep, JSIM computes how much that flux changed since the last step: ΔΦ = L × ΔI. If ΔΦ would exceed a threshold (FVALUE, default = one flux quantum-ish unit scaled by the solver's max step, or ~1 if unspecified), JSIM shrinks the internal timestep so the flux doesn't jump too far in a single step.
Important: In each superconducting loop, at least one inductor should use FCHECK. Inductors not flagged FCHECK are excluded from this check entirely — they're free to jump any amount of flux per step without throttling the solver.
Why it matters for phase-mode circuits: in a superconducting loop, phase and flux are directly linked (phase winds by 2π per flux quantum around the loop). If the solver takes a step so large that the flux through the loop jumps by more than it should, it can silently miscount how many flux quanta moved — a real physical error, not just numerical noise. Flagging one inductor per loop with FCHECK gives JSIM a proxy for the loop's total flux and forces it to keep the timestep small enough to track that change accurately — one inductor is enough because in a single loop, flux is a shared/loop-level quantity, not something to track separately per inductor.

Units: H, PH, NH, UH, MH

option: not used

General form:

1	`LXXXX N1 N2 VALUE <FCHECK> <FVALUE=VALUE> <IC=VALUE>`

Example:

1
2
3

 L2 1 0 2.3PH FCHECK
 L3 2 5 1.8PH FCHECK FVALUE=0.5
 L1 3 4 5.0PH

FCHECK option:

If specified, JSIM tracks flux changes through the inductor Φ = L × I (inductance × its branch current). At each timestep, JSIM computes how much that flux changed since the last step: ΔΦ = L × ΔI. If ΔΦ would exceed a threshold, JSIM shrinks the internal timestep so the flux doesn't jump too far in a single step.
The threshold is the global MAXFLUXSTEP option (see .OPTIONS, default 0.5e-15), optionally scaled per-inductor by FVALUE (see below). Inductors not flagged FCHECK are excluded from this check entirely — they're free to jump any amount of flux per step without throttling the solver.
Important: In each superconducting loop, at least one inductor should use FCHECK.

FVALUE=VALUE option:

Only meaningful on an inductor that also has FCHECK. Sets a per-instance multiplier — a "proportion of MAXFLUXSTEP" — applied to the global flux-step threshold for that inductor only: effective threshold = FVALUE × MAXFLUXSTEP.
Default 1.0 (i.e. the inductor simply uses the global MAXFLUXSTEP unscaled). Use a value below 1 to watch a particularly sensitive loop more tightly than the rest of the circuit; above 1 to relax the check for a loop that doesn't need it.

Why FCHECK/FVALUE matter for phase-mode circuits: in a superconducting loop, phase and flux are directly linked (phase winds by 2π per flux quantum around the loop). If the solver takes a step so large that the flux through the loop jumps by more than it should, it can silently miscount how many flux quanta moved — a real physical error, not just numerical noise. Flagging one inductor per loop with FCHECK gives JSIM a proxy for the loop's total flux and forces it to keep the timestep small enough to track that change accurately — one inductor is enough because in a single loop, flux is a shared/loop-level quantity, not something to track separately per inductor.

Units: H, PH, NH, UH, MH

<IC=VALUE> option: accepted by the parser but has no effect on the simulation — the inductor's initial current always starts at 0 regardless of this value.

3.4. Mutual Inductors¶

General form:

1	`KXXXX LXXXX LYYYY VALUE`

Example:

1	`K1 L1 L2 0.9`

Notes:

Couples two inductors (LXXXX and LYYYY)
VALUE is the coupling coefficient (typically 0 to 1)

3.5. Independent Voltage Sources¶

3.5.1. Sinusoidal Sources¶

General form:

1	`VXXXX N1 N2 SIN(VO VA FREQ TD THETA)`

Parameters:

VO: DC offset voltage (must be zero)
VA: Amplitude
FREQ: Frequency
TD: Time delay
THETA: Damping factor

Example:

1	`V1 1 0 SIN(0 1MV 100MEGHZ 0US 0)`

3.5.2. Pulse Sources¶

General form:

1	`VXXXX N1 N2 PULSE(V1 V2 TD TR TF PW PER)`

Parameters:

V1: Initial value (must be zero)
V2: Pulsed value
TD: Time delay
TR: Rise time
TF: Fall time
PW: Pulse width
PER: Period

Example:

1	`V2 2 0 PULSE(0MV 1MV 0PS 2PS 2PS 10PS 50PS)`

3.5.3. Piece-wise Linear Sources¶

General form:

1	`VXXXX N1 N2 PWL(T0 V0 T1 V1 T2 V2 ...)`

Example:

1	`V3 3 0 PWL(0PS 0MV 1PS 1MV 5PS 1MV 6PS 0MV)`

Notes:

T0 and V0 must be zero
Define arbitrary voltage waveforms with time-voltage pairs

3.5.4. Noise Sources (Stochastic Extension)¶

General form:

1	`VXXXX N1 N2 NOISE(VA TD TSTEP)`

Parameters:

VA: Spectral amplitude density in V/√Hz
TD: Time delay before noise starts
TSTEP: Maximum time step (limits stochastic algorithm errors)

Example:

1	`V4 1 0 NOISE(1P 0PS 1PS)`

Notes:

TSTEP of 1ps is reasonable for HTS junction parameters
See Section 9: Noise Simulation for more details

3.6. Independent Current Sources¶

Current sources follow the same syntax as voltage sources, but use I instead of V:

3.6.1. Sinusoidal Current Sources¶

1	`IXXXX N1 N2 SIN(IO IA FREQ TD THETA)`

Example: I1 1 0 SIN(0 1MA 100MEGHZ 0US 0)

3.6.2. Pulse Current Sources¶

1	`IXXXX N1 N2 PULSE(I1 I2 TD TR TF PW PER)`

Example: I2 2 0 PULSE(0MA 1MA 0PS 2PS 2PS 10PS 50PS)

3.6.3. Piece-wise Linear Current Sources¶

1	`IXXXX N1 N2 PWL(T0 I0 T1 I1 ...)`

Example: I3 3 0 PWL(0PS 0MA 1PS 1MA)

3.6.4. Noise Current Sources¶

1	`IXXXX N1 N2 NOISE(IA TD TSTEP)`

Example: I4 1 0 NOISE(1P 0PS 1PS)

Note: For all sources, initial values (V0, I0, V1, I1) must be zero.

3.7. Josephson Junctions¶

General form:

1	`BXXXX N1 N2 MODNAME <AREA=VALUE> <CONDEV=DEVNAME> <IC=V0,PHI0>`

Example:

1 2	`B1 2 3 JJMOD1 AREA=1.5 CONDEV=L2 B2 5 0 JJSTD`

Parameters:

MODNAME: Model name (defined with .MODEL statement)
AREA: Junction area multiplier (scales ICRIT and CAP, as well as RN and R0 inversely with AREA)
CONDEV: Device for critical current modulation (inductor, voltage, or current source)
IC: Initial conditions (currently ignored)

Critical-current modulation by a control current

General form (junction line): BXXXX N1 N2 MODNAME <AREA=VALUE> <CONDEV=DEVNAME>

CONDEV=DEVNAME names another "connected" device (an inductor, voltage source, or current source, referenced purely by name — it does not need to share a node with the junction) whose instantaneous current JSIM reads at every timestep and uses to modulate the junction's critical current. It only takes effect if the junction's connected .MODEL also sets CCT=1 (sin(x)/x weighting); with the default CCT=0, CONDEV is parsed and validated but has no effect on the simulation.

When active, the modulation is Icrit(t) = ICRIT × sin(π·Icontrol(t)/ICON) / (π·Icontrol(t)/ICON) where Icontrol(t) is CONDEV's current at time t, and ICON (read "Ic ON") is a .MODEL parameter giving the scale of the control current — the control current at which the sinc weighting completes its first lobe. ICON defaults to 1mA if not specified in the .MODEL block; it must never be set to exactly 0 when CONDEV+CCT=1 are in use, as this produces a division by zero.

Example:

1
2
3

I1 5 0 PWL(0 0 100PS 0.5MA) // Control current `I1`ramps to 0.5mA at t=100ps, then holds.
B1 1 2 JJMOD CONDEV=I1 // `B1`is the junction whose critical current is modulated by `I1`.
.MODEL JJMOD JJ(RTYPE=1 ICRIT=1MA CCT=1 ICON=0.8MA)

I1 is a separate branch (node 5 to ground) — not wired to B1's own nodes 1/2 — that ramps from 0 to a steady 0.5mA by t=100ps and holds there for the rest of the run. Because JJMOD sets CCT=1 and explicitly gives ICON=0.8MA (rather than relying on the 1mA default), JSIM continuously rescales B1's critical current using Icontrol=0.5mA and ICON=0.8mA: ratio = 0.5mA / 0.8mA = 0.625 – Icrit(t) = 1mA × sin(π×0.625) / (π×0.625) ≈ 1mA × 0.470 ≈ 0.47mA. So from t=100ps onward, B1's effective critical current settles at about 0.47mA — roughly half its nominal 1mA — for as long as I1 holds at 0.5mA. If I1 varied over time instead, B1's critical current would track the sinc curve dynamically as the control current changed.

3.8. Transmission Lines¶

General form:

1	`TXXXX N1 N2 N3 N4 LOSSLESS <Z0=VALUE> <TD=VALUE>`

Example:

1	`T1 1 0 2 0 LOSSLESS Z0=50 TD=100PS`

Parameters:

N1 N2: Port 1 nodes (input)
N3 N4: Port 2 nodes (output)
Z0: Characteristic impedance (default: 50Ω)
TD: Time delay (default: 1 second)

3.9. Subcircuit Calls¶

General form:

1	`XYYYY SUBDEFNAME N1 N2 N3 ...`

Example:

1 2	`X1 SQUID 1 3 4 5 X2 DCSFQ 10 11 12`

Notes:

XYYYY: Subcircuit instance name (must start with 'X')
SUBDEFNAME: Name of subcircuit definition
Node list must match subcircuit definition

4. Subcircuit Definition¶

General form:

1
2
3

.SUBCKT SUBDEFNAME N1 N2 N3 ...
<circuit elements>
.ENDS

Example:

.SUBCKT JTL 0 1 2
* Generic JJ-based cell
* 0=GROUND, 1=INPUT, 2=OUTPUT

*circuit*
L1 1 20 2pH
L2 20 40 2pH
Ijtl 0 40 PWL(0 0u 5p 350u 100n 350u)
L3 40 50 2pH
L4 50 2 2pH
B1 20 0 JJ250
RB1 20 0 1
B2 50 0 JJ250
RB2 50 0 1

.MODEL JJ250 JJ(RTYPE=0 ICRIT=250UA RN=90 CAP=1.25PF)
.ENDS

Notes:

Nodes must be integers, not names
Node numbers are local to the subcircuit
Subcircuits can contain any circuit elements including other subcircuits
Nodes in the parameter list are external connections

5. Model Specification¶

5.1. Josephson Junction Models¶

General form:

1	`.MODEL MNAME JJ(<PARAM=VALUE>, <PARAM=VALUE>, ...)`

Example:

1 2	`.MODEL JJMOD1 JJ(VG=2.5MV, CAP=0.6PF, ICRIT=100UA) .MODEL JJHTS JJ(RTYPE=1, VG=30MV, CAP=0.2PF, ICRIT=200UA, RN=10)`

Model Parameters¶

Parameter	Description	Default	Units
RTYPE	Quasiparticle model: 0=zero conductance, 1=piece-wise linear	0	-
ICRIT	Critical current	1	mA
RN	Normal state resistance	5	Ω
R0	Subgap resistance	30	Ω
CAP	Junction capacitance	2.5	pF
VG	Gap voltage	2.8	mV
DELV	Gap transition voltage	0.1	mV
CCT	Control current type: 0=none, 1=sin(x)/x	0	-
ICON	Control current scale (must be different from 0)	1	mA

Notes:

RTYPE=0: Ideal junction with zero quasiparticle current below gap
RTYPE=1: More realistic model with piece-wise linear I-V curve
Use AREA in junction definition to scale ICRIT and CAP, as well as RN and R0 inversely with AREA
For use of CCT and ICON (read "Ic ON") parameters see this note

6. Transient Analysis Specification¶

6.1. Transient Analysis¶

General form:

1	`.TRAN PRSTEP TSTOP <TSTART> <MAXTSTEP>`

Example:

1 2	`.TRAN 1PS 100PS 20PS 0.5PS .TRAN 0.1PS 500PS`

Parameters:

PRSTEP: Printing interval (output timestep)
TSTOP: Simulation stop time
TSTART: Start time for output (default: 0)
MAXTSTEP: Maximum internal timestep (default: 1ps)

Notes:

PRSTEP determines output data density
MAXTSTEP limits internal solver step size
Actual internal steps may be smaller (adaptive stepping)

7. Print and File Specifications¶

7.1. Output Files¶

General form:

1	`.FILE FILENAME`

Example:

1 2	`.FILE OUTPUT1 .FILE RESULTS_JJ`

Notes:

Subsequent .PRINT statements direct output to this file
Multiple .FILE statements create multiple output files

7.2. Print Statements¶

General form:

1	`.PRINT PRTYPE PRNAME <PART>`

Print Types:

PRTYPE	Description	Example
NODEV	Node voltage	`.PRINT NODEV 5 0`
DEVV	Device voltage	`.PRINT DEVV R1`
DEVI	Device current	`.PRINT DEVI L1`
PHASE	Junction phase	`.PRINT PHASE B1`

Examples:

.FILE OUT1
.PRINT NODEV 2 0
.PRINT DEVV X1_X2_B1
.FILE OUT2
.PRINT DEVI B2 JJTOTAL
.PRINT PHASE B3
.PRINT DEVV T1 PORT1

7.3. Subcircuit Element Printing¶

To print values from subcircuit elements, expand the element name with subcircuit hierarchy:

Example:

1	`X1_X2_B1`

Means: Junction B1 in subcircuit X2, which is called from subcircuit X1.

This eliminates the need for long node lists in subcircuit definitions.

7.4. Junction Current Components¶

For Josephson junctions, specific current components can be printed as shown in the table below.

Contribution to the current	Description
JJTOTAL	Total current (sum of the contributions)
JJJOSEPH	Josephson supercurrent
JJCAP	Capacitive current due to junction internal capacitance
JJRESIS	Quasiparticle current
JJALL	All components (one column per contribution)

Example:

1 2	`.PRINT DEVI B1 JJTOTAL .PRINT DEVI B1 JJALL`

7.5. Transmission Line Ports¶

Example:

1
2
3

.PRINT DEVV T1 PORT1    # Port 1 voltage
.PRINT DEVV T1 PORT2    # Port 2 voltage
.PRINT DEVI T1          # Both ports

8. Option Specifications¶

General form:

1	`.OPTIONS <PARAM=VALUE>, <PARAM=VALUE>, ...`

Example:

1 2	`.OPTIONS RELTOL=0.01 MAXPHISTEP=1.5 .OPTIONS LTE NUMDGT=10`

Available Options¶

Option	Description	Default
RELTOL=VALUE	Relative tolerance	0.001
PHITOL=VALUE	Absolute phase tolerance	0.0001
VNTOL=VALUE	Absolute voltage tolerance (with LTE)	0.1 µV
INTOL=VALUE	Absolute current tolerance (with LTE)	0.1 µA
MAXPHISTEP=VALUE	Max phase change per timestep	1.5
MAXFLUXSTEP=VALUE	Max flux change per timestep	0.5e-15
LTE	Enable local truncation error checking	OFF
IGWARN	Ignore warnings and continue	OFF
NUMDGT=VALUE	Number of output digits	3

Notes:

PHITOL default (0.0001) may be too small; try 0.01 for better convergence
LTE option enables adaptive timestep based on truncation error
MAXFLUXSTEP only applies to inductors with FCHECK flag
NUMDGT affects output only, not precision

9. Noise Simulation¶

JSIM includes stochastic noise simulation capabilities added by Julian Satchell (1997).

9.1. Noise Sources¶

Noise sources are available for both voltage and current:

Voltage Noise:

1	`VXXXX N1 N2 NOISE(VA TD TSTEP)`

Current Noise:

1	`IXXXX N1 N2 NOISE(IA TD TSTEP)`

Parameters:

VA or IA: Spectral amplitude density (V/√Hz or A/√Hz)
TD: Time delay before noise begins
TSTEP: Maximum timestep (typically 1ps for HTS junctions)

9.2. Automatic Thermal Noise Addition¶

An AWK script (noise.awkf) is provided to automatically add Johnson-Nyquist thermal noise to all resistors in a circuit.

Script Code:

BEGIN {const=5.529e-23}
$1 ~ /^[rR]/&&!/[rR][zZ]/ {
  print $0
  noise = sqrt(const*temperature/$4)* 1e12
  printf "i%s %s %s NOISE(%fp 0.0 1.0p) \n",$1,$2,$3,noise
}
$1  !~/^[Rr]/||/^[Rr][Zz]/ {print $0}

Translation:

Constant: const = 5.529e-23 is derived from 4*k*B where k is Boltzmann's constant
For each resistor line (starting with R or r, but NOT Rz or rZ):
Print the original resistor line
Calculate noise: sqrt(4*k*T/R) in pA/√Hz
Add a parallel noise current source
For all other lines: Pass through unchanged

Example Transformation¶

Input circuit:

1
2
3

R1 1 2 100 # Gets noise
R2 2 3 50  # Gets noise
ZR3 3 0 1K # No noise (starts with Z)

How it works:

For each resistor R (except those starting with 'Z'), the script:
Keeps the original resistor line
Adds a parallel noise current source
Noise amplitude = √(4kT/R) where k is Boltzmann's constant

Temperature examples:

temperature=4.2 - Liquid helium
temperature=77.36 - Liquid nitrogen
temperature=300 - Room temperature

After AWK processing (temperature=77.36K):

R1 1 2 100
iR1 1 2 NOISE(3.26e-12p 0.0 1.0p)
R2 2 3 50
iR2 2 3 NOISE(4.61e-12p 0.0 1.0p)
ZR3 3 0 1K

Usage:

awk -f noise.awkf temperature=77.36 < circuit.cir | ./jsim_n -o noisy_output.txt

Note: awk formats numeric output according to the system locale settings. In locales such as fr_FR, the decimal separator is a comma (,), which produces invalid numeric syntax for SPICE netlists. On systems configured with a non-English locale , run the script with LC_NUMERIC=C to enforce dot decimal formatting:

LC_NUMERIC=C awk -f noise.awkf temperature=77.36 < circuit.cir | ./jsim_n -o noisy_output.txt

Note for Windows: since awk is not available by default on Windows:

Install for instance Git Bash which supports awk at https://git-scm.com/download/win .
Add its tools to the PowerShell PATH. For instance [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\Git\usr\bin", "User")
Verify that it is recognized by PowerShell with awk --version
Then you can use:
bash cmd /c "awk -f noise.awkf temperature=77.36 < circuit.cir | jsim_n.exe -o noisy_output.txt"

or:

bash cmd /c "set LC_NUMERIC=C && awk -f noise.awkf temperature=77.36 < circuit.cir | jsim_n.exe -o noisy_output.txt"

Excluding resistors from noise:

Name resistors starting with 'Z' (e.g., ZR1, ZBIAS) to exclude them
Useful for bias networks, ideal filters, etc.

10. Output Files¶

JSIM can generate special output files depending on command-line options:

File	Created By	Description
`jsim.dbg`	`-d` flag	Debug output with device list, node mapping, and detailed simulation info
`jsim.raw`	`-r` flag	Rawfile format output for post-processing
`<filename>`	`-o <filename>`	User-specified output file with simulation results

11. Command-Line Reference¶

Synopsis¶

jsim_n [options] [files] [options] [files] ...

Options¶

Option	Description
-d	Toggle debugging (creates jsim.dbg)
-r	Toggle rawfile output (creates jsim.raw)
-o	Output to specified file
-noheader	Suppress column header (use with -o)
-h, --help	Display help message
-v, --version	Display version information
-	Read from standard input

Option Behavior¶

Options toggle their state (initially off)
Options affect files listed to the right
Options remain active until toggled again
Multiple options can be combined (e.g., -rd)

Usage Examples¶

Basic simulation:

1	`jsim_n circuit.cir`

Output to file:

jsim_n -o data.txt circuit.cir

Data file without header:

jsim_n -noheader -o data_noheader.txt circuit.cir

Other output options:

jsim_n circuit.cir > alldata.txt
# Save full header, output data and footer in alldata.txt

jsim_n -o data.txt circuit.cir > footer_header.txt
# Save output in data.txt, full header and footer in footer_header.txt

Debug mode:

jsim_n -d circuit.cir              # Creates jsim.dbg

Rawfile output:

jsim_n -r circuit.cir              # Creates jsim.raw

Input from stdin:

jsim_n < circuit.cir
cat circuit.cir | ./jsim_n
jsim_n -                           # Explicit stdin

Multiple files:

jsim_n file1.cir file2.cir file3.cir

Option toggling:

jsim_n file1.cir -d file2.cir -d file3.cir
# file1: normal, file2: debug, file3: normal

Complex multi-file:

jsim_n file1.cir -rd - file2.cir < file3.cir
# file1: normal
# file2: debug + rawfile
# file3 (stdin): debug + rawfile

With thermal noise:

awk -f noise.awkf temperature=77.36 < circuit.cir | jsim_n -o data_noisy.txt

12. Tips and Best Practices¶

Circuit Design¶

Use FCHECK on loop inductors - Essential for phase-mode circuits
Name bias resistors starting with Z - Excludes them from noise simulation
Specify MAXTSTEP carefully - Too large may miss fast transients
Use subcircuits - Makes complex designs manageable

Simulation Performance¶

Start with larger timesteps - Use PRSTEP=1ps for initial runs
Reduce RELTOL if needed - Default 0.001 is usually fine
Use LTE for difficult circuits - Helps with convergence
Increase PHITOL to 0.01 - If phase convergence fails

Output Management¶

Use -noheader for plotting - Easier to import into Python/MATLAB
Use .FILE for organization - Separate outputs by type
Request specific JJ currents - JJALL gives complete picture

Debugging¶

Use -d flag - Creates detailed jsim.dbg file
Check jsim.dbg - Contains device list, node mapping, and circuit info
Start simple - Test with basic circuits first
Reduce MAXTSTEP - If results seem wrong

13. Troubleshooting¶

Common Issues¶

Problem: Simulation doesn't converge

Try increasing PHITOL to 0.01
Reduce MAXTSTEP
Enable LTE option
Check for unrealistic parameter values

Problem: Results look incorrect

Verify node connections
Check unit specifications (pH vs nH, etc.)
Review junction model parameters
Enable debug mode (-d)

Problem: Crashes or hangs

Check for superconducting loops without FCHECK
Verify MAXPHISTEP and MAXFLUXSTEP values
Ensure all source offsets are zero
Check for node numbering conflicts

Problem: No output file created

Verify -o filename doesn't have special characters
Check disk space
Ensure write permissions

14. Test Suite¶

The tests/ directory contains a set of reference circuits used to validate JSIM correctness and measure performance. Each test is a .cir circuit file, and each file includes a *WHY comment line describing what it tests, and one or more *REF lines giving the expected output value(s) for comparison.

14.1. Running the Tests¶

The shell script dotest (C-shell) automates the test runs. It expects the JSIM executable to be at ../jsim_n relative to the tests/ directory. Usage:

# Use 'dotest' on macOS and linux.
# On Linux you must install csh shell.
# Use 'dotest.bat' on Windows with PowerShell.

# Run all tests
./dotest

# Run a single test (e.g. test3 or test9n)
./dotest 3
./dotest 9n

For deterministic tests (no noise), the simulator output is printed alongside the *REF reference value so you can compare them directly. For stochastic (noise) tests — identified by an n in the filename — the test is run 16 times and the third column of output (the voltage) is printed for each run, giving a sense of the statistical distribution around the reference value.

14.2. Test Descriptions¶

test0 — Ohm's Law¶

The most basic sanity check. A PWL current source ramps from 0 to 100µA across a 1Ω resistor. The expected voltage across R2 is 100µV. Verifies that resistive circuits and PWL current sources work correctly.

1
2
3

I0  0  1 PWL(0 0 20ps 100UA)
R2 1 0 1.0
*REF 5.000e-11 1.000e-04 1.000e-04

test1 — Capacitor Charging¶

A 1mA pulse current source charges a 1pF capacitor (with a 100MΩ bleed resistor). Checks that capacitor integration is working, with the voltage rising at the expected rate dV/dt = I/C.

1
2
3

I0  0  1 PULSE(0 1MA 20p 5p 5p 5P 200P)
C2 1 0 1.0pf
*REF 5.000e-11 0.000e-04 1.000e-02

test2 — Inductor Pulse¶

A 1mV voltage pulse drives a 1pH inductor through a 1pΩ series resistor. Checks inductor current ramping (dI/dt = V/L).

1
2
3

V0  1  0 PULSE(0 1MV 20p 5p 5p 5P 200P)
L2 11 0 1.0pH
*REF 5.000e-11 0.000e-04 1.000e-02

test3 — Josephson Junction Below Ic, Zero Temperature¶

A JJ (Ic = 100µA, CAP = 0.1pF) is driven by a DC current ramping to 80µA, which is below the critical current. The junction should remain in the zero-voltage state. Expected device voltage is 0V.

1
2
3

I0 0 1  PWL(0 0 30p 80UA)
B2 1 0 jm
*REF 1.000e-10 8.000e-05 0.000e-02

test4 — JJ Above Ic, Zero Temperature (120µA)¶

Junction driven above Ic to 120µA. The junction switches to the resistive state and produces an average voltage. Expected output ~66.3µV (reference from Likharev).

1
2
3

I0 0 1  PWL(0 0 40p 120UA)
.MODEL jm JJ(RTYPE=0, ICRIT= 100UA, CAP=0.1PF)
*REF 2.0e-9 1.20e-04 6.63e-05

test5 — JJ Above Ic, Zero Temperature (150µA)¶

Same circuit with current raised to 150µA. Expected average voltage ~111.8µV.

1	`*REF 2.0e-9 1.50e-04 1.118e-04`

test6 — JJ at Ic, Zero Temperature, β=1¶

The drive current is stepped to just above Ic then pulled back to Ic (105µA → 100µA). The circuit includes a realistic output filter (R-L-C chain). This tests the voltage plateau behaviour. Two reference values are given: from Likharev (4×10⁻⁵ V) and from an independent implementation (~5.5×10⁻⁵ V).

I0 0 1  PWL(0 0 40p 105UA 70p 100UA)
.MODEL jm JJ(RTYPE=0, ICRIT= 100UA, CAP=3.24PF)
*REF 2.0e-9 1.00e-04 4e-05    FROM Likharev pg 97
*REF 2.0e-9 1.00e-04 5.5e-05  FROM my program IVX

test7n — JJ at Ic, T=119K, β=0.01, γ=0.05 (noise)¶

Stochastic test at full critical current with very low damping and low thermal noise. The reference average voltage is ~29.3µV from the Ambegaokar-Halperin (A-H) solution (Likharev p. 116, also computable with ah.c). Results will vary between runs.

1
2
3

.MODEL jm JJ(RTYPE=0, ICRIT= 100UA, CAP=0.0324PF)
iR1 1 0 NOISE(81.114179p 0.0 1.0p)
*REF 2.93e-05 FROM Likharev pg 116

test8n — JJ at Ic, T=119K, β=0.04, γ=0.2 (noise)¶

Higher noise (γ=0.2) with slightly higher β. Expected average voltage ~11.6µV (A-H solution, Likharev p. 116).

1 2	`.MODEL jm JJ(RTYPE=0, ICRIT= 25UA, CAP=0.0324PF) *REF 1.16e-05 FROM Likharev pg 116`

test9n — JJ at 0.6·Ic, T=119K, β=0.04, γ=0.2 (noise)¶

Current reduced to 60% of Ic. Thermally activated switching becomes significant. Expected average voltage ~1.48µV (Likharev p. 119).

1
2
3

I0 0 1  PWL(0 0  70p 15UA)
.MODEL jm JJ(RTYPE=0, ICRIT= 25UA, CAP=0.0324PF)
*REF 1.48e-06 FROM Likharev pg 119

test10n — JJ at 0.8·Ic, T=119K, β=4, γ=0.2 (noise)¶

High-β (capacitive) junction at 80% of Ic. Expected average voltage ~11µV (Likharev p. 121).

1 2	`.MODEL jm JJ(RTYPE=0, ICRIT= 25UA, CAP=51.84PF) *REF 1.1e-05 FROM Likharev pg 121`

test11n — JJ at 0.6·Ic, T=119K, β=4, γ=0.2 (noise)¶

High-β junction at 60% of Ic — deeper into the thermally activated regime. Expected average voltage ~1.4µV (Likharev p. 121).

1 2	`.MODEL jm JJ(RTYPE=0, ICRIT= 25UA, CAP=51.84PF) *REF 1.4e-06 FROM Likharev pg 121`

14.3. Output Filter Network¶

The noise tests (test7n–test11n) and the T=0 voltage tests (test4–test6) use a two-stage R-L-C low-pass filter to extract the average junction voltage:

1	`Junction → R(1.7kΩ) – L(uH) – C(pF) → R(10kΩ) – L(uH) – C(pF) → output`

The .PRINT DEVV c3 directive reads the voltage across the final capacitor, which approximates the DC average after filtering out the Josephson oscillation. The filter component values differ between the low-β (test7n–test9n) and high-β (test10n–test11n) groups in order to match the relevant Josephson frequency range.

14.4. Auxiliary Programs¶

Two small C programs are included in the tests/ directory to support validation.

ah.c — Ambegaokar-Halperin Analytical Solution¶

Computes the expected average voltage for a resistively-shunted junction (RSJ model) at finite temperature using the Ambegaokar-Halperin formula (Likharev, p. 116). This provides the theoretical reference for the noise tests.

# Compile (macOS)
clang ah.c -lm -o ah

# Compile (Linux)
gcc ah.c -lm -o ah

# Compile (Windows)
gcc ah.c -lm -o ah.exe

# Run — enter bias current and gamma (thermal noise parameter)
./ah
Enter current, gamma
100e-6 0.05

rt.c — Random Number Generator Tester¶

Analyses the statistical properties of the platform random number generator used in noise simulations: prints moments, complement moments, autocorrelation, and a distribution histogram over 1,000,000 samples. Useful to verify that the RNG is well-behaved before relying on noise simulation results.

# Compilation
# macOS / Linux — defaults to random()
clang rt.c -lm -o rt # Linux: gcc rt.c -lm -o rt

# Force rand() (Windows-compatible generator)
clang -DUSERAND rt.c -lm -o rt # Linux: gcc -DUSERAND rt.c -lm -o rt

# Use lrand48()
clang -DUSERAND48 rt.c -lm -o rt #Linux: gcc -DUSERAND48 rt.c -lm -o rt

# Windows — defaults to rand()
gcc rt.c -o rt.exe

14.5. Interpreting Noise Test Results¶

Because the noise tests are stochastic, a single run may deviate significantly from the reference. dotest runs each noise test 16 times and prints the resulting voltage each time. To assess whether the simulator is working correctly, compute the mean over the 16 runs and compare to the *REF value. The statistical uncertainty scales as 1/√N, so with 16 runs the standard error on the mean is about 25% of the single-run standard deviation.

For the low-noise, high-current tests (test7n at γ=0.05), the distribution is fairly tight and the mean should converge close to the reference within the 16-run sample. For low-current tests (test9n, test11n) where thermally activated switching dominates, variance is larger and more runs may be needed for a stable mean.

14.6. Performance Benchmarks¶

Historical benchmarks from the original 1997 test suite (elapsed time for dotest in seconds):

Machine	Compiler	OS	Time (s)
DECstation 5000/33	gcc 2.7.2	Ultrix 4.2a	127
Dell 486/66	gcc 2.7.2	Linux 2.0	180
MacBook Pro	Apple clang version 17.0.0	macOS Tahoe 26.2 arm64	0.584

To obtain your own benchmark on mac or linux: time ./dotest > testlog

On Windows with PowerShell use:Measure-Command { .\dotest.bat | Tee-Object -FilePath testlog } | Select-Object TotalSeconds

Appendix A: Original Manual (1992)¶

This appendix reproduces the original JSIM Preliminary Version User's Guide by E. S. Fang and T. Van Duzer, University of California, Berkeley.

JSIM Preliminary Version User's Guide¶

E. S. Fang and T. Van Duzer
Department of Electrical Engineering and Computer Science
University of California, Berkeley, CA 94720x

1. Introduction¶

JSIM (Josephson SIMulator) is a circuit simulation program for Josephson circuits. Circuits may contain resistors, capacitors, inductors, mutual inductors, independent voltage and current sources, lossless transmission lines and Josephson junctions. At present time, only transient analysis is allowed.

The input format of JSIM is quite similar to SPICE. If you are not familiar with SPICE, it is recommended that you read the SPICE user guide also.

2. Circuit Description¶

2.1. Resistors
General form: RXXXX N1 N2 VALUE
Example: RC1 12 9 1KOHM

2.2. Capacitors
General form: CXXXX N1 N2 VALUE <IC=VALUE>
Example: C1 10 11 1PF

Initial value may be specified, but currently it is ignored. This applies to ALL initial values.

2.3. Inductors
General form: LXXXX N1 N2 VALUE <FCHECK> <IC=VALUE>
Example: L2 1 0 2.3PH FCHECK

If FCHECK (flux check) is specified, JSIM will keep track of the change of flux through the inductor. It is recommended particularly for phase mode circuit. In each superconductive loop, at least one inductor should be considered for FCHECK option.

2.4. Mutual Inductors
General form: KXXXX LXXXX LYYYY VALUE
Example: K1 L1 L2 0.9

2.5. Independent Voltage Sources

2.5.1. Sinusoidal Sources
General form: VXXXX N1 N2 SIN(VO VA FREQ TD THETA)
Example: V1 1 0 SIN(0 1MV 100MEGHZ 0US 0)
Note VO must be zero.

2.5.2. Pulse Sources
General form: VXXXX N1 N2 PULSE(V1 V2 TD TR TF PW PER)
Example: V2 2 0 PULSE(0MV 1MV 0PS 2PS 2PS 10PS 50PS)
Note V1 must be zero.

2.5.3. Piece-wise Linear Sources
General form: VXXXX N1 N2 PWL(T0 V0 T1 V1 ....)
Example: V3 3 0 PWL(0PS 0MV 1PS 1MV)
Note T0 and V0 must be zero.

2.6. Independent Current Sources

2.6.1. Sinusoidal Sources
General form: IXXXX N1 N2 SIN(IO IA FREQ TD THETA)
Example: I1 1 0 SIN(0 1MA 100MEGHZ 0US 0)
Note IO must be zero.

2.6.2. Pulse Sources
General form: IXXXX N1 N2 PULSE(I1 I2 TD TR TF PW PER)
Example: I2 2 0 PULSE(0MA 1MA 0PS 2PS 2PS 10PS 50PS)
Note I1 must be zero.

2.6.3. Piece-wise Linear Sources
General form: IXXXX N1 N2 PWL(T0 I0 T1 I1 ....)
Example: I3 3 0 PWL(0PS 0MA 1PS 1MA)
Note T0 and I0 must be zero.

2.7. Josephson Junctions
General form: BXXXX N1 N2 MODNAME <AREA> <CONDEV=DEVNAME> <IC=V0,PHI0>
Example: B1 2 3 JJMOD1 AREA=1.5 CONDEV=L2

MODNAME is the model name, CONDEV is used to simulate the modulation of critical current due to magnetic field, DEVNAME can only be inductors, voltage and current sources.

2.8. Transmission Line
General form: TXXXX N1 N2 N3 N4 LOSSLESS <Z0=VALUE> <TD=VALUE>
Example: T1 1 0 2 0 LOSSLESS Z0=50 TD=100PS

N1 and N2 are nodes for port 1, and N3 and N4 are nodes for port 2. Default Z0=50ohm, TD=1sec.

2.9. Subcircuit Calls
General form: XYYYY SUBDEFNAME N1 N2 .....
Example: X1 SGA 1 3 4 5

3. Subcircuit Definition¶

General form:

1
2
3

.SUBCKT SUBDEFNAME N1 N2 ......
<circuit elements>
.ENDS

Example:

.SUBCKT TEST 1 2 3
R1 1 2 3K
C1 2 3 3PF
.ENDS

4. Model Specification¶

4.1. Josephson Models
General form: .MODEL MNAME JJ(<PARAM=VALUE>,...)
Example: .MODEL JJMOD1 JJ(VG=2.5MV, CAP=0.6PF, ICRIT=100UA)

Parameters:

RTYPE: quasiparticle model (0 or 1), default 0
CCT: control current type (0 or 1), default 0
VG: gap voltage, default 2.8mV
DELV: gap transition voltage, default 0.1mV
ICON: control current scale, default 1mA
R0: subgap resistance, default 30ohm
RN: normal resistance, default 5ohm
CAP: junction capacitance, default 2.5pf
ICRIT: critical current, default 1mA

5. Transient Analysis Specification¶

General form: .TRAN PRSTEP TSTOP <TSTART> <MAXTSTEP>
Example: .TRAN 1PS 100PS 20PS 0.5PS

PRSTEP is the printing step.
TSTOP is the stop time.
TSTART is the starting time for printing, default is 0.
MAXTSTEP is the maximum internal time step, default is 1ps.

6. Print and File Specifications¶

General form: .FILE FILENAME
General form: .PRINT PRTYPE PRNAME <PART>

Examples:

.FILE OUT1
.PRINT NODEV 2 0
.PRINT DEVV X1_X2_B1
.FILE OUT2
.PRINT DEVI B2 JJTOTAL
.PRINT PHASE B3
.PRINT DEVV T1 PORT1
.PRINT DEVI T1

To print out device voltage or current of a subcircuit element, just expand the element name by the subcircuit call name. In the above examples, X1_X2_B1 means B1 belongs to subcircuit call X2 which is in turn called by X1.

Junction current components:

JJTOTAL: total current
JJJOSEPH: Josephson current
JJCAP: current due to capacitive effect
JJRESIS: quasi-particle current
JJALL: print all currents in the order specified

Transmission line ports:

PORT1: print port1 of transmission line
PORT2: print port2 of transmission line
No port specification prints both ports

7. Option Specifications¶

General form: .OPTIONS <PARAM, ....>
Example: .OPTIONS RELTOL=0.01 MAXPHISTEP=1.5

Available options:

RELTOL=VALUE: relative tolerance, default 0.001
PHITOL=VALUE: absolute tolerance for phase, default 0.0001 (too small, set to 0.01)
VNTOL=VALUE: absolute voltage tolerance, default 0.1 uV (with LTE)
INTOL=VALUE: absolute current tolerance, default 0.1 uA (with LTE)
MAXPHISTEP=VALUE: maximum phase change per timestep, default 1.5
MAXFLUXSTEP=VALUE: maximum flux change per timestep, default 0.5e-15
LTE: check for local truncation error
IGWARN: ignore warning and proceed
NUMDGT=VALUE: number of digits to be printed, default 3

8. Special Files¶

JSIM will generate some special files. All the special files start with .jsim. They are: devlist, devname, model, nodemap and subdef.

9. CAUTION¶

This is a preliminary version of the program. Many parameters have no defaults, and have to be specified.

10. BUGS¶

If you find any problems, please send e-mail to esfang@argon.berkeley.edu, include the input deck that causes the problem and a description of the problem. Also you may call (415) 642-0502 and contact Emerson Fang, or write to Prof. Ted Van Duzer at the above address.

Appendix B: Noise Extension Manual (1997)¶

This appendix reproduces the Noise Supplement to JSIM User's Guide by J. S. Satchell, DRA Malvern, UK.

Note

The syntax for the NOISE function is wrong. There are only 3 parameters to enter and in a different order. Refer to the right syntax in the manual above.

Noise supplement JSIM Preliminary Version User's Guide¶

J. S. Satchell
DRA(Malvern)
St. Andrews Rd., Worcs, UK WR14 3PS

1. Introduction¶

JSIM (Josephson SIMulator) is a circuit simulation program for Josephson circuits. The noise extension adds two new device types, and is intended to be a strict superset of standard JSIM, documented in the file manual.ms.

Modifications, makefile, awk script, this document and the contents of the test directory are:

Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that the above copyright notice appears in all copies. The copyright holders make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. No liability is accepted by the copyright holder for any use made of this software.

2. Circuit Description¶

2.1. Independent Voltage Sources

2.1.1. Noise Sources

General form: VXXXX N1 N2 NOISE(VO VA TSTEP TD)
Example: V1 1 0 NOISE(0 1P 1PS 0PS)

Note VO must be zero. VA is the spectral amplitude density of the noise source in Volts/√Hz. TSTEP is the maximum time step that will be used, this provides an opportunity to limit the errors in the stochastic algorithm. 1pS seems to be reasonable for HTS junction parameters. TD is a time delay before noise starts.

2.2. Independent Current Sources

2.2.1. Noise Sources

General form: IXXXX N1 N2 NOISE(IO IA TSTEP TD)
Example: I1 1 0 NOISE(0 1P 1PS 0PS)

Note IO must be zero. IA is the spectral amplitude density of the noise source in Amps/√Hz. TSTEP is the maximum time step that will be used, this provides an opportunity to limit the errors in the stochastic algorithm. 1pS seems to be reasonable for HTS junction parameters. TD is a time delay before noise starts.

BUGS¶

If you find any problems with the stochastic extension, please send e-mail to satchell@dra.hmg.gb, include the input deck that causes the problem and a description of the problem. Warning: I may ignore you, be too busy or be unable to help.

End of Manual

License¶

The 2026 modifications and enhancements are provided under the same terms.

Credits¶

Original JSIM (1992):
Emerson Fang, UC Berkeley
Professor Ted Van Duzer's Cryoelectronics Group

Cleanup Crew:
Jay Fleischman (jef@swordfish.berkeley.edu)
Steve Whiteley (stevew@landau.conductus.com)

Stochastic Extension (1997):
Julian Satchell, DRA Malvern, UK (satchell@dra.hmg.gb)

2026 Multi-Platform Edition:
Pascal Febvre, University Savoie Mont Blanc, France (pascal.febvre@univ-smb.fr)

JSIM Release 2.1 - User's Manual
Version: 2.1-macOS-linux-windows-2026
Date: February 2026