TK2 Excitation Analysis

Use this skill for excitation-system recorder files in TK2 binary format, especially WFLC/TK-style files containing UAB, UBC, UCA, UFD, Uld, and IFD channels.

Quick Start

Run the bundled script first; it handles the fragile binary parsing and plotting:

python scripts/analyze_tk2.py INPUT.tk2 --output-dir OUT --mode single --phase UAB --kind step

Common modes:

# 5% or large step response, using UAB only
python scripts/analyze_tk2.py "01-5%阶跃.tk2" --output-dir out --mode single --phase UAB --kind step

# Pulse-blocking decay, using UAB only
python scripts/analyze_tk2.py "05-封脉冲.tk2" --output-dir out --mode single --phase UAB --kind decay

# Legacy three-phase average RMS, only if explicitly requested
python scripts/analyze_tk2.py "01-5%阶跃.tk2" --output-dir out --mode three-phase --kind step

Outputs:

• *_curve.png: normalized voltage response curve.
• *_series.csv: per-cycle time, voltage RMS, UFD mean, IFD mean.
• *_metrics.json: sampling info and calculated metrics.

Parsing Assumptions

The script uses the recorder pattern observed in Manla excitation tests:

• Header starts at byte 0 and contains GBK/ASCII channel metadata.
• Waveform samples begin after the header; the default auto-detection tries to find the first offset where the remaining bytes divide into 6 * int16 channel samples.
• Effective channel order is:

1. UAB
2. UBC
3. UCA
4. UFD
5. Uld
6. IFD
• Samples are little-endian signed 16-bit integers.
• Sampling rate is inferred from positive-going zero crossings in the chosen phase. For 50 Hz recordings, a 512-sample cycle gives 25600 Hz.

If auto-detection fails, rerun with explicit values:

python scripts/analyze_tk2.py INPUT.tk2 --header-bytes 8930 --sample-rate 25600 --output-dir OUT

Calculation Rules

For report work, prefer --mode single --phase UAB unless the user explicitly asks for three-phase average.

Single-phase mode:

• Compute one-cycle RMS from the selected phase (UAB, UBC, or UCA).
• Normalize response curves to the initial steady value.

Three-phase mode:

• Compute one-cycle RMS for UAB, UBC, and UCA.
• Average the three RMS curves.

For UFD, Uld, and IFD, calculate one-cycle arithmetic means.

Step Metrics

For --kind step, the script estimates:

• amp_pct: final steady voltage change relative to initial value.
• Mp_pct: overshoot relative to the step amplitude.
• Tup_s: 10%-to-90% rise time.
• Tp_s: time from step start to peak.
• Ts_s: first time after which the response stays within a 5% band of final step amplitude.

Inspect metrics before copying them into reports. If the step happens outside the default detection window, set:

--step-window START END
--initial-window START END
--final-window START END

Decay Metrics

For --kind decay, the script estimates T_decay_1e_s from the time between:

• start of decay, detected when normalized voltage first drops below 0.999, and
• crossing of 1/e of the initial value.

Use the result as the pulse-blocking open-circuit decay time constant when the recorder setup and test method match the report method.

Report Integration

When inserting results into a Word report:

• State the processing basis, for example: 按UAB单相有效值计算.
• Keep the plotted caption consistent with the calculation mode, for example: 发电机5%空载阶跃响应试验（UAB单相有效值）.
• Do not mix three-phase-average metrics with single-phase plots.
• Use exported CSV/JSON as auditable intermediates; use PNG for report figures.