Skip to content

Commit 7f382ab

Browse files
MarwanSamy-99MarwanSamy-99
committed
Initial readme setup
1 parent 4b53b49 commit 7f382ab

File tree

6 files changed

+374
-51
lines changed

6 files changed

+374
-51
lines changed

‎ihp-sg13g2/libs.tech/ngspice/testing/devices/README.md‎

Lines changed: 106 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,113 @@
1-
# Device Testing Directory
1+
# Device Testing
22

3-
## Introduction
3+
This directory provides setup files, Makefile targets, and scripts to run **device-level verification** for the IHP SG13 PDK.
4+
Tests can be executed with either **pytest** or the custom **`models_verifier`** runner.
45

5-
This directory contains setup files, templates, scripts, and reports for device-level verification of the IHP SG13 PDK.
6-
It is organized by device type (MOS, HBT, PNP) and includes a custom test runner (`models_verifier`) and Makefile.
6+
# Table of contents
7+
8+
- [Device Testing](#device-testing)
9+
- [Table of contents](#table-of-contents)
10+
11+
- [Folder Structure](#folder-structure)
12+
- [Prerequisites](#prerequisites)
13+
- [Usage](#usage)
14+
15+
- [Running with Makefile](#running-with-makefile)
16+
- [Examples](#examples)
717

818
## Folder Structure
919

20+
```text
21+
📁 devices
22+
┣ 📜 Makefile Main entrypoint for running device tests.
23+
┣ 📁 devices_configs YAML configs and templates for MOS, HBT, PNP devices.
24+
┣ 📁 models_verifier Python package for simulation & verification.
25+
┣ 📁 models_run Generated outputs (netlists, CSVs, reports).
26+
┣ 📁 verification Pytest tests and notebooks.
27+
┗ 📜 README.md Documentation (this file).
28+
```
29+
30+
## Prerequisites
31+
32+
You need the following tools to run the SG13G2 device tests:
33+
34+
- **Python 3.9+**
35+
- **ngspice** (for running simulations)
36+
- **openvaf** (for compiling Verilog-A models)
37+
38+
To build the required OSDI models, please follow the instructions in:
39+
[`ihp-sg13g2/libs.tech/verilog-a/README.md`](../../../verilog-a/README.md)
40+
41+
### Setup Python Virtual Environment
42+
43+
It is recommended to use a local virtual environment:
44+
45+
```bash
46+
# Create and activate venv
47+
python3 -m venv .venv
48+
source .venv/bin/activate
49+
50+
# Install required packages
51+
pip install -r requirements.txt
52+
```
53+
54+
## Usage
55+
56+
> Always run from this directory:
57+
> `ihp-sg13g2/libs.tech/ngspice/testing/devices`
58+
59+
### Running with Makefile
60+
61+
The Makefile defines groups and individual device targets.
62+
The **default runner** is `models_verifier`. To switch, use `RUNNER=pytest`.
63+
64+
**Available targets:**
65+
66+
- **Groups**:
67+
68+
- `make test-all` → all devices
69+
- `make test-mos` → NMOS/PMOS (LV/HV)
70+
- `make test-hbt` → HBT (NPN13G2 variants)
71+
- `make test-pnp` → PNP MPA
72+
73+
- **Devices**:
74+
75+
- `nmos_lv`, `pmos_lv`, `nmos_hv`, `pmos_hv`,
76+
- `npn13g2`, `npn13g2l`, `npn13g2v`,
77+
- `pnp_mpa`
78+
79+
### Examples
80+
81+
Run all devices with default runner (`models_verifier`):
82+
83+
```bash
84+
make test-all
1085
```
11-
📁devices
12-
┣ 📜Makefile Make targets to run device tests (pytest or models_verifier).
13-
┣ 📁mos Directory for MOSFET device testing (NMOS/PMOS, LV/HV).
14-
┃ ┣ 📜cap_template.spice.j2 Template for MOS capacitance simulation.
15-
┃ ┣ 📜dc_template.spice.j2 Template for MOS DC sweep simulation.
16-
┃ ┣ 📁nmos_lv Low-voltage NMOS device configs and results.
17-
┃ ┃ ┣ 📜sg13_lv_nmos.yaml Config file for LV NMOS tests.
18-
┃ ┣ 📁nmos_hv High-voltage NMOS device configs.
19-
┃ ┃ ┗ 📜sg13_hv_nmos.yaml Config file for HV NMOS tests.
20-
┃ ┣ 📁pmos_lv Low-voltage PMOS device configs.
21-
┃ ┃ ┗ 📜sg13_lv_pmos.yaml Config file for LV PMOS tests.
22-
┃ ┗ 📁pmos_hv High-voltage PMOS device configs.
23-
┃ ┗ 📜sg13_hv_pmos.yaml Config file for HV PMOS tests.
24-
┣ 📁hbt Directory for HBT (NPN) device testing.
25-
┃ ┣ 📜hbt_dc.spice.j2 Template for HBT DC sweep simulation.
26-
┃ ┣ 📁npn13g2 NPN13G2 variant device configs and results.
27-
┃ ┃ ┣ 📜npn13g2.yaml Config file for NPN13G2.
28-
┃ ┣ 📁npn13g2l NPN13G2L variant configs and results (same structure).
29-
┃ ┗ 📁npn13g2v NPN13G2V variant configs and results (same structure).
30-
┣ 📁pnp_mpa Directory for PNP MPA device testing.
31-
┃ ┣ 📜pnpmpa.yaml Config file for PNP MPA device.
32-
┃ ┣ 📜pnpMPA_dc.spice.j2 Template for PNP DC sweep.
33-
┣ 📁models_verifier Python package for running simulations and verification.
34-
┃ ┣ 📜models_verifier.py CLI entry point for running verification with a config.
35-
┃ ┣ 📜mdm_aggregator.py Combines measurement data into dataframes.
36-
┃ ┣ 📜mdm_parser.py Parser for raw MDM measurement files.
37-
┃ ┣ 📜mdm_parser_utils.py Helper utilities for parsing MDM files.
38-
┃ ┣ 📜mdm_parser_const.py Constants for parsing and verification.
39-
┃ ┣ 📁dc_runner Module for DC sweep simulation.
40-
┃ ┃ ┣ 📜dc_sweep_runner.py Orchestrates ngspice DC runs.
41-
┃ ┃ ┗ 📜helper.py Helper functions for simulation configs.
42-
┃ ┣ 📁error_analyzer Module for analyzing simulation vs measurement results.
43-
┃ ┃ ┣ 📜config.py Metric and threshold specification.
44-
┃ ┃ ┗ 📜range_checker.py Range/tolerance checking of results.
45-
┃ ┗ 📜README.md Package-level documentation.
46-
┣ 📁tests Pytest test suite for device verification.
47-
┃ ┗ 📜test_devices.py Runs pytest-based device verification.
48-
┗ 📁run_test_flow Example notebooks / workflows.
49-
┗ 📜IHP_devices_testing.ipynb Notebook demonstrating device testing flow.
86+
87+
Run only MOS devices with pytest:
88+
89+
```bash
90+
make test-mos RUNNER=pytest
5091
```
92+
93+
Run a single device (e.g., LV NMOS) with verifier:
94+
95+
```bash
96+
make nmos_lv
97+
```
98+
99+
Run PNP MPA with pytest:
100+
101+
```bash
102+
make pnp_mpa RUNNER=pytest
103+
```
104+
105+
---
106+
107+
For more details on available targets and options, run:
108+
109+
```bash
110+
make help
111+
```
112+
113+
---

‎ihp-sg13g2/libs.tech/ngspice/testing/devices/devices_configs/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Device Configurations
2+
3+
This folder contains **per-device YAML configurations** and **ngspice netlist templates** for running SG13G2 device verification.
4+
Each config defines the measurement data, model libraries, run settings, and output paths for one device type.
5+
6+
# Table of contents
7+
8+
* [Device Configurations](#device-configurations)
9+
* [Table of contents](#table-of-contents)
10+
11+
* [Folder Structure](#folder-structure)
12+
* [YAML Configuration](#yaml-configuration)
13+
14+
* [Key Sections](#key-sections)
15+
16+
---
17+
18+
## Folder Structure
19+
20+
```text
21+
📁 devices_configs
22+
┣ 📁 mos
23+
┃ ┣ 📜 cap_template.spice.j2 Template for MOS capacitance simulations.
24+
┃ ┣ 📜 dc_template.spice.j2 Template for MOS DC sweeps.
25+
┃ ┣ 📁 nmos_lv LV NMOS configuration.
26+
┃ ┃ ┗ 📜 sg13_lv_nmos.yaml
27+
┃ ┣ 📁 pmos_lv LV PMOS configuration.
28+
┃ ┃ ┗ 📜 sg13_lv_pmos.yaml
29+
┃ ┣ 📁 nmos_hv HV NMOS configuration.
30+
┃ ┃ ┗ 📜 sg13_hv_nmos.yaml
31+
┃ ┗ 📁 pmos_hv HV PMOS configuration.
32+
┃ ┗ 📜 sg13_hv_pmos.yaml
33+
┣ 📁 hbt
34+
┃ ┣ 📜 hbt_dc.spice.j2 Template for HBT DC sweeps.
35+
┃ ┣ 📁 npn13g2 NPN13G2 configuration.
36+
┃ ┃ ┗ 📜 npn13g2.yaml
37+
┃ ┣ 📁 npn13g2l NPN13G2L configuration.
38+
┃ ┃ ┗ 📜 npn13g2l.yaml
39+
┃ ┗ 📁 npn13g2v NPN13G2V configuration.
40+
┃ ┗ 📜 npn13g2v.yaml
41+
┗ 📁 pnp_mpa
42+
┣ 📜 pnpMPA_dc.spice.j2 Template for PNP DC sweeps.
43+
┗ 📜 pnpmpa.yaml Config for PNP MPA.
44+
```
45+
46+
## YAML Configuration
47+
48+
Each YAML describes **what to simulate, how to run it, and how to evaluate results**.
49+
Below is an excerpt from `sg13_hv_nmos.yaml`:
50+
51+
```yaml
52+
# PDK Models Setup
53+
mdm_dir: "../../../../libs.doc/meas/MOS/SG13_nmosHVXm1Y3"
54+
corner_lib_path: "../../../../libs.tech/ngspice/models/cornerMOShv.lib"
55+
osdi_path: "../../../../libs.tech/ngspice/osdi/psp103_nqs.osdi"
56+
57+
# Device Configuration
58+
device_type: "mos"
59+
device_name: "sg13_hv_nmos"
60+
61+
# Run Configuration
62+
dc_template_path: "devices_configs/mos/dc_template.spice.j2"
63+
generate_netlists: true
64+
max_workers: 4
65+
66+
# Output configuration
67+
threshold_percent_oob: 5.0
68+
69+
metrics:
70+
- name: "id"
71+
meas: "id_meas"
72+
tt: "id_sim_mos_tt"
73+
ss: "id_sim_mos_ss"
74+
ff: "id_sim_mos_ff"
75+
- name: "ib"
76+
meas: "ib_meas"
77+
tt: "ib_sim_mos_tt"
78+
ss: "ib_sim_mos_ss"
79+
ff: "ib_sim_mos_ff"
80+
81+
# Output Paths
82+
output_dir: "models_run/nmos_hv/"
83+
```
84+
85+
### Key Sections
86+
87+
* **PDK Models Setup**
88+
89+
* `mdm_dir`: Directory of measurement data (MDM format).
90+
* `corner_lib_path`: Path to the SPICE corner library.
91+
* `osdi_path`: Path to compiled OSDI Verilog-A models.
92+
93+
* **Device Configuration**
94+
95+
* `device_type`: Device family (`mos`, `pnpmpa`, `hbt`).
96+
* `device_name`: Unique identifier for the device.
97+
98+
* **Run Configuration**
99+
100+
* `dc_template_path`: Jinja2 netlist template for simulations.
101+
* `generate_netlists`: If `true`, netlists are saved to disk. If `false`, runs in-memory only.
102+
* `max_workers`: Number of parallel workers for simulations.
103+
104+
* **Output Configuration**
105+
106+
* `threshold_percent_oob`: Maximum % of points allowed outside tolerance before test fails.
107+
* `threshold_count_oob`: Alternative to percentage — max absolute count of failing points.
108+
109+
* **Metrics**
110+
Defines which currents/voltages to check, and maps them to:
111+
112+
* `meas`: Measured column in the MDM dataset.
113+
* `tt/ss/ff`: Simulated results for typical, slow, and fast corners.
114+
115+
* **Output Paths**
116+
117+
* `output_dir`: Directory where results are stored (`models_run/<device>`).

‎ihp-sg13g2/libs.tech/ngspice/testing/devices/models_run/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Models Run Outputs
2+
3+
This folder is the **output directory for device verification runs**.
4+
Each device will create its own subfolder here when tests are executed using the Makefile or `models_verifier`.
5+
6+
# Table of contents
7+
8+
* [Models Run Outputs](#models-run-outputs)
9+
* [Table of contents](#table-of-contents)
10+
11+
* [Folder Structure Template](#folder-structure-template)
12+
* [Content Description](#content-description)
13+
14+
15+
## Folder Structure Template
16+
17+
When populated, this folder will look like the following:
18+
19+
```text
20+
📁 models_run
21+
┣ 📁 <device_name>/
22+
┃ ┣ 📁 netlists/ Generated ngspice netlists (if enabled in YAML).
23+
┃ ┣ 📁 per_setup_mdm_csvs/ Merged CSVs per measurement/setup.
24+
┃ ┣ 📁 per_setup_sim_vs_meas/ CSV comparisons of simulation vs measurement.
25+
┃ ┗ 📁 verification_reports/ Aggregated pass/fail reports.
26+
┗ 📜 README.md Documentation (this file).
27+
```
28+
29+
## Content Description
30+
31+
* **`netlists/`**
32+
Contains generated `.cir` netlists from templates.
33+
Only created if `generate_netlists: true` is set in the device YAML config.
34+
35+
* **`per_setup_mdm_csvs/`**
36+
Contains merged CSVs for each test setup, combining measurement and simulation data.
37+
38+
* **`per_setup_sim_vs_meas/`**
39+
Contains CSV comparisons between simulated and measured data (if applicable for the device).
40+
41+
* **`verification_reports/`**
42+
Final verification summaries:
43+
44+
* `summary.csv` → Roll-up summary by metric/target
45+
* `full_report.csv` → Detailed results per block/metric
46+
* `detailed_failures.csv` → List of failing points (only if failures exist)
47+
48+
---
49+
50+
**Note**
51+
52+
* This folder is **initially empty**.
53+
* Subfolders are created automatically the first time you run `make <device>`.
54+

‎ihp-sg13g2/libs.tech/ngspice/testing/devices/requirements.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
pytest
2+
pyyaml
3+
pandas
4+
numpy
5+
jinja2
6+
ipywidgets

0 commit comments

Comments
 (0)