FRF AI Diagnostic System

An open-source, physics-informed diagnostic toolkit for machine-structure Frequency Response Function (FRF) analysis.

The project combines structural-dynamics features with machine learning to compare measured X/Y/Z-axis FRF responses against healthy baselines, generate controlled GO/NG training data, train XGBoost classifiers, detect out-of-distribution responses, and expose results through a local web interface.

This is an independently maintained open-source project. It is not an official product, publication, or endorsement of any employer or institution.

Why this project exists

FRF inspection is commonly performed by manually comparing resonance peaks, frequency shifts, and amplitude changes. This repository packages that workflow into a reproducible pipeline that keeps the physical interpretation visible instead of treating the spectrum as an opaque feature vector.

Key capabilities:

• Multi-sweep FRF CSV parsing and complex-domain averaging.
• Accelerance-to-receptance conversion and frequency-band feature extraction.
• Physics-constrained data augmentation using modal stiffness and damping perturbations.
• Per-axis XGBoost classification with Isolation Forest OOD screening.
• Physical metrics such as dominant resonance shift, amplitude ratio, and spectrum correlation.
• SHAP-based feature attribution and interactive diagnostic dashboards.
• Config-driven onboarding for multiple machine models.

Project status

The project is under active development. The current codebase is intended for engineering research, reproducible experimentation, and quality-diagnostic workflow development. It is not a safety-certified inspection system, and deployment thresholds should be validated against the target machine population before production use.

Repository layout

configs/               Machine-specific frequency bands, channels, modes, and thresholds
core/                  Calibration, augmentation, training, inference, and dashboard generation
projects/              Machine datasets, generated features, models, and evaluation artifacts
tools/                 Windows helper scripts for onboarding and retraining
web_deployment/        Flask-based local diagnostic and model-management UI

Quick start

Python 3.11+ is recommended.

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
python web_deployment/app.py --port 5050

Then open http://127.0.0.1:5050.

On Windows, 啟動系統.bat provides the same local web-server entry point.

Expected FRF input

The core parser expects CSV or tab-separated FRF exports containing a header row with frequency and complex response columns compatible with:

• first column: frequency in Hz
• second column: real response component
• third column: imaginary response component

Axis routing is config-driven and typically uses filename patterns such as ch2x, ch3y / ch4y, and ch3z / ch4z.

Training workflow

For a machine model named XYZ990:

1. Create configs/XYZ990_config.json from an existing config and adjust frequency bounds, axis filename patterns, modal frequencies, and OOD thresholds.
2. Place verified baseline FRF files under projects/XYZ990/Raw_Data/.
3. Run calibration, augmentation, and training:

python core/auto_calibration.py --machine XYZ990 --raw_dir projects/XYZ990/Raw_Data --config configs/XYZ990_config.json
python core/data_augmentation.py --config configs/XYZ990_config.json --data_dir projects/XYZ990/Raw_Data --out_dir projects/XYZ990/augmented_dataset --headless
python core/model_training.py --config configs/XYZ990_config.json --raw_dir projects/XYZ990/Raw_Data --augmented_dir projects/XYZ990/augmented_dataset --out_dir projects/XYZ990/models

Windows helper scripts are available in tools/new_machine.bat and tools/re_train.bat.

Evaluation and reproducibility

Training produces per-axis model artifacts and diagnostic charts under projects/<MODEL>/models/ and projects/<MODEL>/reports/ when report generation is enabled. These artifacts are useful for engineering review, but reported metrics should always be interpreted together with the dataset split strategy and machine-level independence of the validation set.

For reproducible contributions:

• keep machine-specific behavior in configs/ instead of hard-coding it into core logic;
• document the origin and redistribution status of contributed datasets;
• avoid committing credentials, private production identifiers, or machine-local absolute paths;
• include the smallest validation command that demonstrates the change.

Maintainer and governance

The repository is maintained by @b40609, the original author and Primary Maintainer. Maintainer responsibilities and project decision rules are documented in MAINTAINERS.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development workflow and pull-request expectations, and CODE_OF_CONDUCT.md for community standards.

Security issues should follow SECURITY.md rather than being disclosed in a public issue.

License

Released under the MIT License.

中文簡介

本專案是一套開源的 FRF 結構動力學與機器學習診斷工具，涵蓋頻譜前處理、物理拘束資料擴增、XGBoost 三軸分類、OOD 判定、SHAP 歸因與 Web 視覺化。主要目標是讓機台 FRF 品檢流程具備可重現、可解釋與可擴充的工程實作基礎。