05_test_analyze_TFT_refactored.py ダウンロード/コピー

05_test_analyze_TFT_refactored.py をダウンロード

05_test_analyze_TFT_refactored.py
05_test_analyze_TFT_refactored.py
  1#!/usr/bin/env python3
  2"""Tests for analyze_TFT_refactored.py using artificial TFT data.
  3
  4This file can be used in two ways.
  5
  61. Normal pytest execution with the default seed and noise level::
  7
  8       pytest -q test_analyze_TFT_refactored.py
  9
 102. Standalone execution with configurable seed and noise level::
 11
 12       python test_analyze_TFT_refactored.py --seed 12345 --noise-level 0.005
 13
 14The standalone mode internally calls pytest after setting environment variables.
 15The target script is assumed to be placed next to this test file, but it can be
 16changed by --target-script or the TFT_TARGET_SCRIPT environment variable.
 17
 18Artificial-data cases
 19---------------------
 20Case A: Ideal noiseless data
 21    Saturation-region data follow Id = Ioff + A_sat * max(Vg - Vth, 0)^2.
 22    Linear-region data follow Id = Ioff + A_lin * max(Vg - Vth, 0).
 23    These data are used for strict numerical checks of Vth and mobility.
 24
 25Case B: Noisy but reproducible data
 26    The same model is used, but multiplicative Gaussian noise is added with a
 27    fixed random seed. These tests check reproducibility and that the analysis
 28    does not break. Because the maximum-slope method is intentionally sensitive
 29    to noise, these tests do not require close agreement with the true values.
 30
 31Case C: Edge/error data
 32    Missing columns, too-short data, low-current data that never reach the SS
 33    target current, and zero/negative current points are checked.
 34"""
 35
 36from __future__ import annotations
 37
 38import argparse
 39import importlib.util
 40import os
 41import sys
 42from pathlib import Path
 43from typing import NamedTuple
 44
 45# Use a non-interactive backend before importing the target script.
 46os.environ.setdefault("MPLBACKEND", "Agg")
 47
 48import numpy as np
 49import pandas as pd
 50import pytest
 51
 52
 53DEFAULT_SEED = 12345
 54DEFAULT_NOISE_LEVEL = 0.005
 55
 56# Known parameters for artificial data.
 57TRUE_VTH = 2.0
 58TRUE_SS = 0.4  # V/dec, used only in subthreshold artificial data.
 59TRUE_IOFF = 1.0e-15
 60TRUE_MU_SAT = 10.0e-4  # 10 cm^2/Vs expressed as m^2/Vs.
 61TRUE_MU_FE = 8.0e-4    # 8 cm^2/Vs expressed as m^2/Vs.
 62VDS_SAT = 10.0
 63VDS_LIN = 0.1
 64VG_MIN = -5.0
 65VG_MAX = 15.0
 66N_POINTS = 201
 67
 68
 69class ArtificialData(NamedTuple):
 70    """Container for saturation and linear-region artificial Id-Vg data."""
 71
 72    sat: pd.DataFrame
 73    lin: pd.DataFrame
 74
 75
 76def runtime_seed() -> int:
 77    """Return the seed used by tests."""
 78
 79    return int(os.environ.get("TFT_TEST_SEED", DEFAULT_SEED))
 80
 81
 82def runtime_noise_level() -> float:
 83    """Return the relative noise level used by Case B tests."""
 84
 85    return float(os.environ.get("TFT_TEST_NOISE_LEVEL", DEFAULT_NOISE_LEVEL))
 86
 87
 88def load_target_module():
 89    """Dynamically import the target analysis script from a file path."""
 90
 91    default_target = Path(__file__).with_name("analyze_TFT_refactored.py")
 92    target_path = Path(os.environ.get("TFT_TARGET_SCRIPT", str(default_target))).resolve()
 93    if not target_path.exists():
 94        raise FileNotFoundError(
 95            f"Target script was not found: {target_path}\n"
 96            "Set TFT_TARGET_SCRIPT or run this test next to analyze_TFT_refactored.py."
 97        )
 98
 99    spec = importlib.util.spec_from_file_location("analyze_TFT_refactored_under_test", target_path)
100    if spec is None or spec.loader is None:
101        raise ImportError(f"Could not create import specification for {target_path}")
102
103    module = importlib.util.module_from_spec(spec)
104    # dataclass needs sys.modules[__module__] to exist during dynamic import.
105    sys.modules[spec.name] = module
106    spec.loader.exec_module(module)
107    return module
108
109
110tft = load_target_module()
111
112
113def make_vg_grid() -> np.ndarray:
114    """Create the common Vg grid used by artificial transfer curves."""
115
116    return np.linspace(VG_MIN, VG_MAX, N_POINTS)
117
118
119def apply_relative_noise(values: np.ndarray, noise_level: float, rng: np.random.Generator) -> np.ndarray:
120    """Apply multiplicative Gaussian noise and keep current values positive.
121
122    Args:
123        values: Clean current values.
124        noise_level: Standard deviation of relative Gaussian noise. For example,
125            0.005 means approximately 0.5% relative noise.
126        rng: NumPy random-number generator.
127
128    Returns:
129        Positive noisy current values.
130    """
131
132    if noise_level <= 0:
133        return values.copy()
134
135    factor = 1.0 + rng.normal(loc=0.0, scale=noise_level, size=len(values))
136    # Keep the artificial current positive. This avoids testing negative-current
137    # handling in Case B; that is handled separately in Case C.
138    factor = np.clip(factor, 0.01, None)
139    return np.clip(values * factor, 1.0e-20, None)
140
141
142def make_sat_current(vg: np.ndarray, config, noise_level: float = 0.0, seed: int = DEFAULT_SEED) -> np.ndarray:
143    """Generate artificial saturation-region Id-Vg current.
144
145    For Vg < Vth, a simple subthreshold exponential is used. For Vg >= Vth,
146    the ideal square-law saturation model is used.
147    """
148
149    a_sat = config.channel_width * config.cox * TRUE_MU_SAT / (2.0 * config.channel_length)
150    id_sub = TRUE_IOFF * 10.0 ** ((vg - TRUE_VTH) / TRUE_SS)
151    id_on = TRUE_IOFF + a_sat * np.maximum(vg - TRUE_VTH, 0.0) ** 2
152    clean = np.where(vg < TRUE_VTH, id_sub, id_on)
153    return apply_relative_noise(clean, noise_level, np.random.default_rng(seed))
154
155
156def make_lin_current(vg: np.ndarray, config, noise_level: float = 0.0, seed: int = DEFAULT_SEED) -> np.ndarray:
157    """Generate artificial linear-region Id-Vg current.
158
159    For Vg < Vth, a simple subthreshold exponential is used. For Vg >= Vth,
160    the low-Vd linear-region model is used.
161    """
162
163    a_lin = config.channel_width / config.channel_length * config.cox * TRUE_MU_FE * VDS_LIN
164    id_sub = TRUE_IOFF * 10.0 ** ((vg - TRUE_VTH) / TRUE_SS)
165    id_on = TRUE_IOFF + a_lin * np.maximum(vg - TRUE_VTH, 0.0)
166    clean = np.where(vg < TRUE_VTH, id_sub, id_on)
167    return apply_relative_noise(clean, noise_level, np.random.default_rng(seed + 1))
168
169
170def make_artificial_data(config, noise_level: float = 0.0, seed: int = DEFAULT_SEED) -> ArtificialData:
171    """Create paired saturation and linear-region artificial Id-Vg DataFrames."""
172
173    vg = make_vg_grid()
174    sat = pd.DataFrame(
175        {
176            "Vg": vg,
177            "Vd": np.full_like(vg, VDS_SAT),
178            "Id": make_sat_current(vg, config, noise_level=noise_level, seed=seed),
179        }
180    )
181    lin = pd.DataFrame(
182        {
183            "Vg": vg,
184            "Vd": np.full_like(vg, VDS_LIN),
185            "Id": make_lin_current(vg, config, noise_level=noise_level, seed=seed),
186        }
187    )
188    return ArtificialData(sat=sat, lin=lin)
189
190
191def make_low_current_data(config) -> ArtificialData:
192    """Create data that never reach the target current used for SS/Von."""
193
194    vg = make_vg_grid()
195    low_id = np.full_like(vg, config.target_current * 1.0e-3, dtype=float)
196    sat = pd.DataFrame({"Vg": vg, "Vd": np.full_like(vg, VDS_SAT), "Id": low_id})
197    lin = pd.DataFrame({"Vg": vg, "Vd": np.full_like(vg, VDS_LIN), "Id": low_id})
198    return ArtificialData(sat=sat, lin=lin)
199
200
201def write_excel_inputs(data: ArtificialData, directory: Path) -> tuple[Path, Path]:
202    """Write artificial input Excel files and return (lin_path, sat_path)."""
203
204    lin_path = directory / "IdVg-Vd0.1.xlsx"
205    sat_path = directory / "IdVg-Vd10.xlsx"
206    data.lin.to_excel(lin_path, index=False)
207    data.sat.to_excel(sat_path, index=False)
208    return lin_path, sat_path
209
210
211# -----------------------------------------------------------------------------
212# Case A: ideal data
213# -----------------------------------------------------------------------------
214def test_case_a_ideal_data_recovers_vth_and_mobility() -> None:
215    """Ideal data should recover the known Vth and mobility values."""
216
217    config = tft.AnalysisConfig()
218    data = make_artificial_data(config, noise_level=0.0, seed=runtime_seed())
219
220    sat_result = tft.analyze_idvg_sat(data.sat, config)
221    lin_result = tft.analyze_idvg_lin(data.lin, config)
222
223    assert sat_result.vth == pytest.approx(TRUE_VTH, abs=0.05)
224    assert lin_result.vth == pytest.approx(TRUE_VTH, abs=0.05)
225    assert sat_result.mobility == pytest.approx(TRUE_MU_SAT, rel=0.02)
226    assert lin_result.mobility == pytest.approx(TRUE_MU_FE, rel=0.02)
227    assert sat_result.ion > 0
228    assert lin_result.ion > 0
229
230
231# -----------------------------------------------------------------------------
232# Case B: noisy reproducible data
233# -----------------------------------------------------------------------------
234def test_case_b_noisy_data_are_reproducible() -> None:
235    """Noisy artificial data should be exactly reproducible for a fixed seed."""
236
237    config = tft.AnalysisConfig()
238    seed = runtime_seed()
239    noise_level = runtime_noise_level()
240
241    data1 = make_artificial_data(config, noise_level=noise_level, seed=seed)
242    data2 = make_artificial_data(config, noise_level=noise_level, seed=seed)
243
244    np.testing.assert_allclose(data1.sat["Id"].to_numpy(), data2.sat["Id"].to_numpy())
245    np.testing.assert_allclose(data1.lin["Id"].to_numpy(), data2.lin["Id"].to_numpy())
246
247
248def test_case_b_noisy_data_do_not_break_analysis() -> None:
249    """Noisy data should still produce finite positive summary values.
250
251    The original maximum-slope method can be very sensitive to noise, so this
252    test intentionally checks robustness rather than strict agreement with the
253    true parameters.
254    """
255
256    config = tft.AnalysisConfig()
257    data = make_artificial_data(config, noise_level=runtime_noise_level(), seed=runtime_seed())
258
259    sat_result = tft.analyze_idvg_sat(data.sat, config)
260    lin_result = tft.analyze_idvg_lin(data.lin, config)
261
262    assert np.isfinite(sat_result.vth)
263    assert np.isfinite(lin_result.vth)
264    assert VG_MIN <= sat_result.vth <= VG_MAX
265    assert VG_MIN <= lin_result.vth <= VG_MAX
266    assert sat_result.mobility > 0
267    assert lin_result.mobility > 0
268    assert sat_result.ion > 0
269    assert lin_result.ion > 0
270
271
272# -----------------------------------------------------------------------------
273# CLI/output test
274# -----------------------------------------------------------------------------
275def test_cli_creates_expected_output_files(tmp_path: Path) -> None:
276    """The command-line workflow should read Excel files and create outputs."""
277
278    config = tft.AnalysisConfig()
279    data = make_artificial_data(config, noise_level=0.0, seed=runtime_seed())
280    lin_path, sat_path = write_excel_inputs(data, tmp_path)
281    outdir = tmp_path / "result"
282
283    exit_code = tft.main(
284        [
285            "--lin", str(lin_path),
286            "--sat", str(sat_path),
287            "--outdir", str(outdir),
288        ]
289    )
290
291    assert exit_code == 0
292    expected_files = [
293        "IdVg-Vd10_analyze.csv",
294        "IdVg-Vd0.1_analyze.csv",
295        "output.csv",
296        "output_log.csv",
297        "rootIdVg.png",
298        "IdVg_LIN.png",
299    ]
300    for filename in expected_files:
301        path = outdir / filename
302        assert path.exists(), f"Missing output file: {path}"
303        assert path.stat().st_size > 0, f"Empty output file: {path}"
304
305    summary = pd.read_csv(outdir / "output.csv")
306    for column in ["Vth_SAT", "muSAT", "SS_SAT", "Ion_SAT", "Vth_LIN", "muFE", "SS_LIN", "Ion_LIN"]:
307        assert column in summary.columns
308
309
310# -----------------------------------------------------------------------------
311# Case C: edge/error data
312# -----------------------------------------------------------------------------
313def test_case_c_missing_required_columns_raise_value_error() -> None:
314    """Missing required columns should raise clear ValueError exceptions."""
315
316    config = tft.AnalysisConfig()
317    missing_id = pd.DataFrame({"Vg": [0.0, 1.0, 2.0], "Vd": [0.1, 0.1, 0.1]})
318
319    with pytest.raises(ValueError, match="missing required columns"):
320        tft.analyze_idvg_sat(missing_id, config)
321
322    with pytest.raises(ValueError, match="missing required columns"):
323        tft.analyze_idvg_lin(missing_id, config)
324
325
326def test_case_c_short_data_raise_value_error_for_vth() -> None:
327    """Too-short data should fail clearly because rolling slopes are unavailable."""
328
329    config = tft.AnalysisConfig(rolling_window=7)
330    short = pd.DataFrame(
331        {
332            "Vg": [0.0, 1.0, 2.0],
333            "Vd": [VDS_LIN, VDS_LIN, VDS_LIN],
334            "Id": [1.0e-15, 1.0e-12, 1.0e-10],
335        }
336    )
337
338    with pytest.raises(ValueError, match="No valid slope values"):
339        tft.analyze_idvg_sat(short, config)
340
341    with pytest.raises(ValueError, match="No valid slope values"):
342        tft.analyze_idvg_lin(short, config)
343
344
345def test_case_c_low_current_sets_ss_and_von_to_nan() -> None:
346    """If target current is never reached, SS and Von should be NaN."""
347
348    config = tft.AnalysisConfig()
349    data = make_low_current_data(config)
350
351    sat_result = tft.analyze_idvg_sat(data.sat, config)
352    lin_result = tft.analyze_idvg_lin(data.lin, config)
353
354    assert np.isnan(sat_result.ss)
355    assert np.isnan(sat_result.von)
356    assert np.isnan(lin_result.ss)
357    assert np.isnan(lin_result.von)
358
359
360def test_case_c_zero_and_negative_currents_are_ignored_for_log_and_sqrt() -> None:
361    """Zero/negative Id values should become NaN in Id_rm, logId, and rootId."""
362
363    config = tft.AnalysisConfig()
364    data = make_artificial_data(config, noise_level=0.0, seed=runtime_seed())
365    sat_df = data.sat.copy()
366
367    bad_indices = [5, 20, 40]
368    sat_df.loc[bad_indices[0], "Id"] = 0.0
369    sat_df.loc[bad_indices[1], "Id"] = -1.0e-12
370    sat_df.loc[bad_indices[2], "Id"] = -1.0
371
372    result = tft.analyze_idvg_sat(sat_df, config)
373
374    assert result.dataframe.loc[bad_indices, "Id_rm"].isna().all()
375    assert result.dataframe.loc[bad_indices, "logId"].isna().all()
376    assert result.dataframe.loc[bad_indices, "rootId"].isna().all()
377    assert result.mobility > 0
378
379
380def test_case_c_missing_input_file_returns_nonzero_exit_code(tmp_path: Path) -> None:
381    """main() should return a nonzero code when input files do not exist."""
382
383    outdir = tmp_path / "result"
384    exit_code = tft.main(
385        [
386            "--lin", str(tmp_path / "missing_lin.xlsx"),
387            "--sat", str(tmp_path / "missing_sat.xlsx"),
388            "--outdir", str(outdir),
389        ]
390    )
391
392    assert exit_code != 0
393
394
395# -----------------------------------------------------------------------------
396# Standalone wrapper
397# -----------------------------------------------------------------------------
398def parse_wrapper_args(argv: list[str] | None = None) -> argparse.Namespace:
399    """Parse arguments for standalone execution of this test file."""
400
401    parser = argparse.ArgumentParser(
402        description="Run pytest-based tests for analyze_TFT_refactored.py."
403    )
404    parser.add_argument(
405        "--seed",
406        type=int,
407        default=DEFAULT_SEED,
408        help=f"Random seed for noisy artificial data. Default: {DEFAULT_SEED}",
409    )
410    parser.add_argument(
411        "--noise-level",
412        type=float,
413        default=DEFAULT_NOISE_LEVEL,
414        help=f"Relative noise level for Case B artificial data. Default: {DEFAULT_NOISE_LEVEL}",
415    )
416    parser.add_argument(
417        "--target-script",
418        default=os.environ.get("TFT_TARGET_SCRIPT", str(Path(__file__).with_name("analyze_TFT_refactored.py"))),
419        help="Path to analyze_TFT_refactored.py. Default: next to this test file.",
420    )
421    parser.add_argument(
422        "--pytest-args",
423        default="-q",
424        help="Extra arguments passed to pytest as a single string. Default: -q",
425    )
426    return parser.parse_args(argv)
427
428
429def main(argv: list[str] | None = None) -> int:
430    """Run pytest with seed/noise options supplied through environment variables."""
431
432    args = parse_wrapper_args(argv)
433    os.environ["TFT_TEST_SEED"] = str(args.seed)
434    os.environ["TFT_TEST_NOISE_LEVEL"] = str(args.noise_level)
435    os.environ["TFT_TARGET_SCRIPT"] = str(Path(args.target_script).resolve())
436
437    pytest_args = args.pytest_args.split() + [str(Path(__file__).resolve())]
438    return int(pytest.main(pytest_args))
439
440
441if __name__ == "__main__":
442    raise SystemExit(main())