# Device Models

This directory contains compact device models needed for circuit simulation, covering MOSFET, FinFET, SOI, BJT, HEMT, and other device types.

## Directory Overview

| Directory | Content | Format | Source |
|------|------|------|------|
| `PTM/` | Predictive Technology Model parameter files | `.mod` (SPICE model cards) | Arizona State University |
| `VA-Models/` | Collection of 30+ Verilog-A compact models | `.va` (Verilog-A source code) | Dietmar Warning (GitHub) |
| `BSIM-BULK107.2.1_02112025/` | BSIM-BULK 107.2.1 | `.va` | UC Berkeley BSIM Group |
| `BSIM-CMG_112.1.0_04282026/` | BSIM-CMG 112.1.0 (FinFET) | `.va` | UC Berkeley BSIM Group |
| `BSIM-IMG_103.1.0_09102024/` | BSIM-IMG 103.1.0 (Independent Multi-Gate) | `.va` | UC Berkeley BSIM Group |
| `BSIM-SOI_100.1.0_10172023/` | BSIM-SOI 100.1.0 | `.va` | UC Berkeley BSIM Group |
| `BSIM-SOI_4.7.0_05192025/` | BSIM-SOI 4.7.0 | `.va` | UC Berkeley BSIM Group |
| `BSIM4_4.8.3_standard_05192025/` | BSIM4 4.8.3 | `.va` | UC Berkeley BSIM Group |
| `Xyce_plugin/` | Xyce-specific BSIM-CMG 111 plugin | `.so` (compiled artifact) | Xyce team modified version |

---

## Relationship Between PTM, Berkeley BSIM, and VA-Models

### Core Relationship Diagram

```
Berkeley BSIM Group (UC Berkeley)
├─ Official standard implementations (Verilog-A)
│  ├─ BSIM4 4.8.3           → This directory: BSIM4_4.8.3_standard_05192025/
│  ├─ BSIM-BULK 107.2.1     → This directory: BSIM-BULK107.2.1_02112025/
│  ├─ BSIM-CMG 112.1.0      → This directory: BSIM-CMG_112.1.0_04282026/
│  ├─ BSIM-IMG 103.1.0      → This directory: BSIM-IMG_103.1.0_09102024/
│  └─ BSIM-SOI 4.7.0/100.1.0 → This directory: BSIM-SOI_*.*/
│
├─ PTM (Arizona State University)
│  └─ Uses BSIM as underlying model, provides parameter cards for different process nodes
│     ├─ 180nm–22nm Bulk → Based on BSIM4 (level=54)
│     └─ 20nm–7nm FinFET → Based on BSIM-CMG (level=72)
│
└─ VA-Models (Dietmar Warning, GitHub community)
   └─ Collection of BSIM + 30+ other models in Verilog-A
      ├─ bsim4 4.8.0         → Unofficial latest, but optimized and verified
      ├─ bsimbulk 107.2.1    → Same version as Berkeley
      ├─ bsimcmg 111.2.1     → One version earlier than Berkeley 112.1.0
      └─ Others: PSP, EKV, HICUM, MEXTRAM, Angelov...
```

### Detailed Description

#### 1. Berkeley BSIM (Independent Subdirectories in This Directory)

**Nature**: **Official standard implementations** released by UC Berkeley BSIM Group, CMC (Compact Model Council) certified industry standard models.

**Characteristics**:
- Latest versions, official technical manuals and update notes
- Includes complete documentation (Technical Manual + Updates PDF)
- Verilog-A source code (`.va` files in `code/` directory)
- Suitable for scenarios requiring latest features or official support

**Use Cases**:
- Need latest model features (e.g., BSIM-CMG 112.1.0 improvements)
- Industrial-grade design requiring CMC standard certification
- Need to reference official technical manuals

#### 2. PTM (This Directory's `PTM/` Subdirectory)

**Nature**: **Predictive process model parameter sets** provided by Arizona State University, not a new model but a parameterized implementation based on BSIM.

**Characteristics**:
- Provided in SPICE `.model` card format (`.mod` files)
- Covers 180nm to 7nm process nodes
- **Underlying models**:
  - 180nm–22nm Bulk CMOS → Uses BSIM4 (level=54)
  - 20nm–7nm FinFET → Uses BSIM-CMG (level=72)
- Parameters optimized for each process node (HP/LP/LSTP variants)

**Use Cases**:
- Rapid verification without manual parameter extraction
- Academic research, algorithm verification
- Process node comparison studies

**Important Note**: PTM requires corresponding built-in BSIM models in simulator:
- Bulk nodes: ngspice/Xyce have built-in BSIM4, can directly `.include`
- FinFET nodes: Need to load BSIM-CMG (`.osdi` or `.so` plugin)

#### 3. VA-Models (This Directory's `VA-Models/` Subdirectory)

**Nature**: **GitHub open-source model collection** maintained by Dietmar Warning, containing Verilog-A implementations of 30+ compact models.

**Characteristics**:
- BSIM series versions slightly older than Berkeley official latest:
  - `bsimcmg 111.2.1` vs Berkeley `112.1.0`
  - `bsimbulk 107.2.1` same version as Berkeley
- **Convergence optimized**: Modified convergence parameters, equations unchanged
- Unified test cases and compilation scripts
- Includes non-BSIM models: PSP, EKV, HICUM, MEXTRAM, Angelov, etc.

**Use Cases**:
- Need non-BSIM models (e.g., PSP, EKV, BJT, HEMT)
- Need convergence-verified models
- Batch compilation of multiple models
- Compare different model implementations (e.g., BSIM4 vs PSP vs EKV)

**Version Selection Recommendation**:
- Prefer Berkeley official version for BSIM models (independent subdirectories in this directory)
- Use VA-Models version for non-BSIM models
- When convergence issues are severe, try VA-Models optimized versions

### Version Comparison Table (BSIM Models)

| Model | Berkeley Official | VA-Models | PTM Underlying Model |
|------|--------------|-----------|-------------|
| BSIM4 | 4.8.3 (2025-05-19) | 4.8.0 | level=54 (built-in) |
| BSIM-BULK | 107.2.1 (2025-02-11) | 107.2.1 | — |
| BSIM-CMG | 112.1.0 (2026-04-28) | 111.2.1 | level=72 (need to load) |
| BSIM-IMG | 103.1.0 (2024-09-10) | 102.9.6 | — |
| BSIM-SOI | 4.7.0 (2025-05-19) / 100.1.0 (2023-10-17) | 4.6.1 | — |

### Practical Usage Decision Flow

```
Need BSIM model?
├─ Yes → Have existing process parameters?
│      ├─ No → Use PTM parameter cards (Bulk direct .include, FinFET needs BSIM-CMG)
│      └─ Yes → Need latest features?
│             ├─ Yes → Use Berkeley official version
│             └─ No → VA-Models or Berkeley both work
│
└─ No → What model needed?
       ├─ PSP/EKV/HiSIM → VA-Models
       ├─ BJT (HICUM/MEXTRAM/VBIC) → VA-Models
       ├─ HEMT (GaN/GaAs) → VA-Models
       └─ Passive devices → VA-Models
```

---

## Model Classification and Applicable Devices

### SPICE Parameter Models (PTM)

PTM (Predictive Technology Model) is a predictive process model parameter set provided by Arizona State University, in SPICE `.model` card format, directly readable by simulators.

| Process Node | Device Type | Underlying Model |
|---------|---------|---------|
| 180nm, 130nm, 90nm, 65nm | Bulk CMOS | BSIM4 (level=54) |
| 45nm, 32nm, 22nm (hp/lp) | Bulk CMOS | BSIM4 (level=54) |
| 20nm, 16nm, 14nm, 10nm, 7nm (hp/lstp) | FinFET | BSIM-CMG (level=72/111) |

### Verilog-A Compact Models

Provided as Verilog-A source code, requires compilation to `.osdi` via OpenVAF before loading into simulator.

| Category | Model | Applicable Devices |
|------|------|---------|
| **Bulk MOSFET** | BSIM4, BSIM-BULK, PSP102/103/104, EKV26/3, HiSIM2 | Bulk silicon CMOS |
| **FinFET/Multi-Gate** | BSIM-CMG, BSIM-IMG | FinFET, GAA, Nanosheet |
| **SOI** | BSIM-SOI, L-UTSOI, HiSIM-SOI, HiSIM-SOTB | SOI MOSFET |
| **High-Voltage MOS** | HiSIM-HV, PSP-HV | LDMOS, DMOS |
| **BJT** | HICUM L0/L2, MEXTRAM, VBIC, FBH-HBT | Bipolar transistors |
| **HEMT** | ASMHEMT, Angelov, EPFL-HEMT, MVSG-CMC | GaN/GaAs HEMT |
| **Passive/Other** | r2_cmc, r3_cmc, diode_cmc, JUNCAP, MOSVAR, IGBT | Resistors, diodes, varactors, IGBT |

---

## How Each Simulator Uses These Models

### ngspice

ngspice supports two model loading methods:

**Method 1: SPICE Model Cards (PTM) — Direct `.include`**

```spice
.include "models/PTM/65nm/ptm_65nm_nmos_bulk.mod"
.include "models/PTM/65nm/ptm_65nm_pmos_bulk.mod"

M1 out in vdd vdd pfet W=1u L=65n
M2 out in 0   0   nfet W=0.5u L=65n
```

Suitable for PTM's Bulk CMOS nodes (180nm–22nm), because PTM's `.mod` files are essentially BSIM4 parameter cards, and ngspice has built-in BSIM4.

**Method 2: OSDI Dynamic Library — Load After OpenVAF Compilation**

```bash
# Compile
openvaf-r models/VA-Models/code/bsimcmg/bsimcmg.va
```

```spice
.control
pre_osdi bsimcmg.osdi
.endc

.model nfet bsimcmg_va type=1
+ ...parameters...
```

Suitable for all Verilog-A models. ngspice loads `.osdi` files via `pre_osdi` command.

### VACASK

VACASK natively uses OSDI API, all models loaded via `.osdi`. VACASK also supports runtime automatic compilation of `.va` files.

**Method 1: Load Precompiled .osdi**

```
load "bsimcmg.osdi"
model nfet bsimcmg_va
+ ...parameters...
```

**Method 2: Runtime Compile .va (Automatically Calls OpenVAF)**

```
load "models/VA-Models/code/bsimcmg/bsimcmg.va"
model nfet bsimcmg_va
+ ...parameters...
```

VACASK automatically calls OpenVAF to compile when detecting `.va` suffix, compilation artifacts cached in working directory.

**Note**: VACASK doesn't support SPICE format `.model` cards (PTM's `.mod` files cannot be used directly), parameters need to be rewritten to VACASK's netlist syntax.

### Xyce

Xyce supports three model loading methods:

**Method 1: Built-in Models + SPICE Model Cards (PTM Bulk Nodes)**

```spice
.include "models/PTM/65nm/ptm_65nm_nmos_bulk.mod"

M1 out in 0 0 nfet W=0.5u L=65n
```

Xyce has built-in BSIM4 (level=54), PTM's Bulk CMOS nodes can be used directly.

**Method 2: ADMS Plugin — Compile to .so Shared Library**

```bash
# Compile (requires ADMS + Xyce development environment)
cd models/Xyce_plugin/BSIM-CMG/code
buildxyceplugin.sh -o bsimcmg111 bsimcmg.va ..
```

```bash
# Use
Xyce -plugin models/Xyce_plugin/BSIM-CMG/libbsimcmg111.so circuit.cir
```

This is Xyce's traditional method for loading custom Verilog-A models, converting `.va` to C code via ADMS then compiling to shared library.

**Method 3: OSDI Dynamic Library — Load After OpenVAF Compilation**

```bash
openvaf-r models/VA-Models/code/bsimcmg/bsimcmg.va
```

```spice
.model nfet bsimcmg_va level=111 osdi("bsimcmg.osdi")
+ ...parameters...
```

Newer versions of Xyce support loading OpenVAF-compiled models via OSDI interface.

---

## Model Usage Quick Reference

| Model Format | ngspice | VACASK | Xyce |
|---------|---------|--------|------|
| `.mod` (PTM SPICE parameter cards) | `.include` direct use | Not supported, need rewrite | `.include` direct use (Bulk nodes) |
| `.va` (Verilog-A source code) | OpenVAF → `.osdi` → `pre_osdi` | `load "xxx.va"` (auto-compile) | ADMS → `.so` → `-plugin` |
| `.osdi` (OpenVAF compilation artifact) | `pre_osdi xxx.osdi` | `load "xxx.osdi"` | `osdi("xxx.osdi")` |
| `.so` (ADMS/Xyce plugin) | Not supported | Not supported | `Xyce -plugin xxx.so` |

---

## Special Handling of PTM FinFET Nodes

PTM's FinFET nodes (7nm–20nm) use `level=72` (HSpice standard BSIM-CMG), but Xyce doesn't recognize `level=72`. Solutions:

| Simulator | Solution |
|--------|------|
| ngspice | OpenVAF compile BSIM-CMG → `.osdi`, then use PTM parameters |
| VACASK | Same as above, or directly `load "bsimcmg.va"` |
| Xyce | Use `Xyce_plugin/BSIM-CMG/libbsimcmg111.so` plugin, level=111 |

See `Xyce_plugin/README.md` for details.

---

## Compilation Workflow

### OpenVAF Compilation (Recommended, Suitable for All Simulators)

```bash
# Compile single model
openvaf-r models/BSIM-CMG_112.1.0_04282026/code/bsimcmg.va

# Batch compile VA-Models
cd models/VA-Models/code/bsimcmg
openvaf-r bsimcmg.va              # → bsimcmg.osdi
```

Artifact `.osdi` can be loaded by ngspice, VACASK, and Xyce.

### ADMS Compilation (Xyce Plugin Only)

```bash
cd models/Xyce_plugin/BSIM-CMG/code
buildxyceplugin.sh -o bsimcmg111 bsimcmg.va ..
```

Artifact `.so` for Xyce use only. Requires ADMS + Xyce development environment.

---

## VA-Models Simulator Compatibility

From Dietmar Warning's VA-Models collection, verified simulator compatibility:

| Model | Version | ngspice | Xyce | VACASK |
|------|------|---------|------|--------|
| r2_cmc | 1.0.1 | ✓ | | ✓ |
| r3_cmc | 1.1.2 | ✓ | ✓ | ✓ |
| diode_cmc | 2.0.0 | ✓ | ✓ | ✓ |
| juncap | 200.6.1 | ✓ | ✓ | ✓ |
| mosvar | 1.3.0 | ✓ | ✓ | ✓ |
| bsim4 | 4.8.0 | ✓ | ✓ | ✓ |
| bsim6 | 6.1.1 | ✓ | ✓ | ✓ |
| bsimbulk | 107.2.1 | ✓ | ✓ | ✓ |
| ekv26 | 2.6 | ✓ | ✓ | ✓ |
| ekv3 | 302.00 | ✓ | ✓ | ✓ |
| psp103 | 103.8.2 | ✓ | ✓ | ✓ |
| bsimcmg | 111.2.1 | ✓ | ✓ | ✓ |
| bsimimg | 102.9.6 | ✓ | | ✓ |
| bsimsoi | 4.6.1 | ✓ | ✓ | ✓ |
| l-utsoi | 102.7.0 | ✓ | ✓ | ✓ |
| hicum0 | 2.1.0 | ✓ | ✓ | ✓ |
| hicum2 | 3.1.0 | ✓ | ✓ | ✓ |
| mextram | 505.5.0 | ✓ | ✓ | ✓ |
| vbic | 1.3 | ✓ | ✓ | ✓ |
| angelov | 2.0 | ✓ | ✓ | ✓ |
| igbt3 | 1.0.0 | ✓ | ✓ | ✓ |
| hisim2 | 3.2.0 | ✓ | | ✓ |
| psp102 | 102.5.0 | ✓ | | ✓ |
| hisimhv | 2.5.1 | ✓ | | ✓ |
| asmhemt | 101.4.0 | ✓ | | ✓ |
| mvsg_cmc | 3.2.0 | ✓ | | ✓ |
| fbh_hbt | 2.3 | ✓ | | ✓ |

VACASK column marked ✓ indicates model can be loaded after compilation to `.osdi` via OpenVAF (VACASK uses same OSDI interface as ngspice).

---

## Recommended Usage

1. **Rapid Verification (Bulk CMOS)**: Directly use PTM `.mod` files + ngspice/Xyce
2. **FinFET Simulation**: OpenVAF compile BSIM-CMG → `.osdi` → any simulator
3. **High-Precision Simulation**: Use BSIM Group latest versions (independent BSIM-* directories in this directory)
4. **Multi-Model Comparison**: VA-Models provides multiple model implementations for same device, convenient for comparison
5. **Xyce Large-Scale Parallel**: Use precompiled plugins in `Xyce_plugin/`