docs: add comprehensive model card

7101d42 verified 2 months ago

6.62 kB

---
license: mit
language:
- en
tags:
- machining
- tool-wear
- manufacturing
- time-series
- foundation-model
- physics-informed
datasets:
- phm2010
metrics:
- mae
- rmse
- r2
pipeline_tag: time-series-classification
---
# MachiningFM 2.0 — Physics-Guided Foundation Model for Machining

A pretrained foundation model for CNC machining sensor data,
extended with a **classical physics calibration layer** for downstream tasks.

## Architecture

```
Raw Machining Signal (force, vibration, AE, NC program, ...)
        │
        ▼
  MachiningFMV2 (CausalFusionTransformer, d_model=384)
        │
        ▼
  Latent Embedding
        │
        ▼
  Downstream Head (Ridge / MLP)
        │
        ▼
  Raw Prediction
        │
        ├── Taylor Tool-Life  (r_T = t / T_Taylor)
        ├── Kienzle Force     (F_measured / F_Kienzle)
        └── Cutting Energy    (E_c = ∫ F_c · V_c · dt)
        │
        ▼
  Physics Calibration (y_final = y_FM + α · g(physics))
        │
        ▼
   Final Prediction
```

### Model Config (pretrained/machiningfm_v2_base.pt)

| Parameter | Value |
|-----------|-------|
| d_model | 384 |
| fusion_layers | 6 |
| num_heads | 8 |
| dropout | 0.1 |
| forecast_horizons | [64, 1280, 12800] |
| output_channels | 3 |
| trained steps | 5,432 |
| training loss | -1.94 |
### Supported Input Modalities
| Modality | Description |
|----------|-------------|
| `raw_waveform` | High-rate sensor signals (force, vibration, AE) |
| `spectral` | FFT / STFT / CWT spectral features |
| `cnc` | CNC SEFC (Servo Error / Feed / Current) data |
| `nc_tokens` | NC program token sequences |
| `image` | Tool wear images |
| `metadata_vector` | Machining condition scalars |

---

## Files

```
MachiningFM2.0/
├── pretrained/
│   └── machiningfm_v2_base.pt       # 170MB — primary pretrained checkpoint
├── configs/
│   ├── model/base.yaml              # Model architecture config
│   ├── physics/default.yaml         # Generic steel/carbide parameters
│   └── physics/ti6al4v_carbide.yaml # Ti-6Al-4V parameters
└── README.md
```

> **Note**: The large v1 pretraining checkpoint (7.4GB) is not included due to file size constraints.
> The v2 base checkpoint above was initialized from it and fine-tuned with the v2 architecture.

---

## Usage

```bash
git clone https://github.com/junseokShim/MachiningFM.git
cd MachiningFM
pip install -e .
```

Download this checkpoint:

```python
from huggingface_hub import hf_hub_download
ckpt_path = hf_hub_download(
    repo_id="Junseok2/MachiningFM2.0",
    filename="pretrained/machiningfm_v2_base.pt",
)
```

Load and encode:

```python
import torch
from machiningfm.models.backbone import MachiningFMBackbone
backbone = MachiningFMBackbone(
    checkpoint_path=ckpt_path,
    backbone_mode="frozen",  # frozen | linear_probe | partial_finetune | full_finetune
)
batch = {"raw_waveform": torch.randn(1, 4096, 3)}
encoded = backbone.encode(batch)
embedding = encoded["embedding"]  # shape: (1, 384)
```

Tool wear regression with physics calibration:

```python
from machiningfm.tasks.tool_wear import ToolWearRegressor
from machiningfm.physics.calibration import PhysicsCalibrator, PhysicsFeatures
from machiningfm.physics.taylor import TaylorParams, compute_tool_life_ratio
# Extract embeddings from backbone (offline)
# X_train, X_val, X_test: (N, 384) numpy arrays
# y_train, y_val, y_test: (N,) VB wear in mm
# Build physics features
params = TaylorParams(C=200.0, n=0.25)
pf = [
    PhysicsFeatures(tool_life_ratio=compute_tool_life_ratio(t, 250.0, 0.25, 0.125, params))
    for t in elapsed_times
]
# Fit with physics calibration
cal = PhysicsCalibrator(method="ridge")
reg = ToolWearRegressor(feature_dim=384, calibrator=cal)
reg.fit(X_train, y_train, pf_train, X_val, y_val, pf_val)
preds = reg.predict(X_test, pf_test)
```

---

## Downstream Tasks

| Task | Input | Output | Evaluation |
|------|-------|--------|-----------|
| A. Wear Regression | embedding | VB (mm) | MAE, RMSE, R² |
| B. Stage Classification | embedding | healthy/moderate/severe | Acc, Macro F1 |
| C. RUL Prediction | embedding | remaining time (min) | MAE, RMSE, R² |
| D. Dimensional Compensation | wear + condition | offset (mm) | physics-derived interface |

### Wear Stage Thresholds (ISO 8688-1:1989)
- Healthy: VB < 0.1 mm
- Moderate: 0.1 ≤ VB < 0.2 mm
- Severe: VB ≥ 0.2 mm

---

## Physics Models

| Model | Status | Required Data |
|-------|--------|--------------|
| Taylor Tool-Life | Enabled | speed, feed, depth |
| Kienzle Force | Enabled | chip thickness, width |
| Cutting Energy | Enabled | force series, speed |
| Archard Wear | **Disabled** | F_N, L (not in standard datasets) |
| Usui Wear Rate | **Disabled** | cutting temperature (not in standard datasets) |
Physics parameters are stored in YAML configs (see `configs/physics/`).
All parameter sources are documented (`literature` / `dataset_calibrated` / `manufacturer` / `user_defined`).
---
## Dataset
**PHM Society Data Challenge 2010**
- URL: https://www.phmsociety.org/competition/phm/10
- Sensor data: force (x/y/z), vibration (x/y/z), acoustic emission RMS
- Labels: flank wear VB (mm) per cut, per condition (real measurements)
- Citation: PHM Society (2010). PHM Data Challenge. Prognostics and Health Management Society.
**Data Integrity Notes:**
- PHM2010 does NOT contain dimensional accuracy measurements.
  Task D (dimensional compensation) outputs are physics-derived estimates, not experimental results.
- Archard/Usui models are disabled by default because PHM2010 lacks the required quantities.
- All splits use leave-one-condition-out to prevent temporal leakage.
---
## Limitations
- Pretrained on proprietary CNC machining data — domain gap to new materials/machines is expected.
- PHM2010 benchmarks with synthetic data demonstrate code correctness, not production performance.
- Physics calibration provides marginal improvement on clean synthetic data; real benefit expected on noisy real-world data.
- Archard and Usui models require data not typically available in standard machining datasets.
- The 7.4GB v1 pretraining checkpoint is not included due to file size constraints.
---
## Citation
If you use this model or framework, please cite:
```
@software{machiningfm2026,
  author = {Shim, Junseok},
  title  = {MachiningFM: Physics-Guided Foundation Model for Machining},
  year   = {2026},
  url    = {https://github.com/junseokShim/MachiningFM}
}
```
---
## Source Code
- GitHub: https://github.com/junseokShim/MachiningFM
- License: MIT

	---
	license: mit
	language:
	- en
	tags:
	- machining
	- tool-wear
	- manufacturing
	- time-series
	- foundation-model
	- physics-informed
	datasets:
	- phm2010
	metrics:
	- mae
	- rmse
	- r2
	pipeline_tag: time-series-classification
	---

	# MachiningFM 2.0 — Physics-Guided Foundation Model for Machining

	A pretrained foundation model for CNC machining sensor data,
	extended with a classical physics calibration layer for downstream tasks.

	## Architecture

	```
	Raw Machining Signal (force, vibration, AE, NC program, ...)
	│
	▼
	MachiningFMV2 (CausalFusionTransformer, d_model=384)
	│
	▼
	Latent Embedding
	│
	▼
	Downstream Head (Ridge / MLP)
	│
	▼
	Raw Prediction
	│
	├── Taylor Tool-Life (r_T = t / T_Taylor)
	├── Kienzle Force (F_measured / F_Kienzle)
	└── Cutting Energy (E_c = ∫ F_c · V_c · dt)
	│
	▼
	Physics Calibration (y_final = y_FM + α · g(physics))
	│
	▼
	Final Prediction
	```

	### Model Config (pretrained/machiningfm_v2_base.pt)

	\| Parameter \| Value \|
	\|-----------\|-------\|
	\| d_model \| 384 \|
	\| fusion_layers \| 6 \|
	\| num_heads \| 8 \|
	\| dropout \| 0.1 \|
	\| forecast_horizons \| [64, 1280, 12800] \|
	\| output_channels \| 3 \|
	\| trained steps \| 5,432 \|
	\| training loss \| -1.94 \|

	### Supported Input Modalities

	\| Modality \| Description \|
	\|----------\|-------------\|
	\| `raw_waveform` \| High-rate sensor signals (force, vibration, AE) \|
	\| `spectral` \| FFT / STFT / CWT spectral features \|
	\| `cnc` \| CNC SEFC (Servo Error / Feed / Current) data \|
	\| `nc_tokens` \| NC program token sequences \|
	\| `image` \| Tool wear images \|
	\| `metadata_vector` \| Machining condition scalars \|

	---

	## Files

	```
	MachiningFM2.0/
	├── pretrained/
	│ └── machiningfm_v2_base.pt # 170MB — primary pretrained checkpoint
	├── configs/
	│ ├── model/base.yaml # Model architecture config
	│ ├── physics/default.yaml # Generic steel/carbide parameters
	│ └── physics/ti6al4v_carbide.yaml # Ti-6Al-4V parameters
	└── README.md
	```

	> Note: The large v1 pretraining checkpoint (7.4GB) is not included due to file size constraints.
	> The v2 base checkpoint above was initialized from it and fine-tuned with the v2 architecture.

	---

	## Usage

	```bash
	git clone https://github.com/junseokShim/MachiningFM.git
	cd MachiningFM
	pip install -e .
	```

	Download this checkpoint:

	```python
	from huggingface_hub import hf_hub_download

	ckpt_path = hf_hub_download(
	repo_id="Junseok2/MachiningFM2.0",
	filename="pretrained/machiningfm_v2_base.pt",
	)
	```

	Load and encode:

	```python
	import torch
	from machiningfm.models.backbone import MachiningFMBackbone

	backbone = MachiningFMBackbone(
	checkpoint_path=ckpt_path,
	backbone_mode="frozen", # frozen \| linear_probe \| partial_finetune \| full_finetune
	)

	batch = {"raw_waveform": torch.randn(1, 4096, 3)}
	encoded = backbone.encode(batch)
	embedding = encoded["embedding"] # shape: (1, 384)
	```

	Tool wear regression with physics calibration:

	```python
	from machiningfm.tasks.tool_wear import ToolWearRegressor
	from machiningfm.physics.calibration import PhysicsCalibrator, PhysicsFeatures
	from machiningfm.physics.taylor import TaylorParams, compute_tool_life_ratio

	# Extract embeddings from backbone (offline)
	# X_train, X_val, X_test: (N, 384) numpy arrays
	# y_train, y_val, y_test: (N,) VB wear in mm

	# Build physics features
	params = TaylorParams(C=200.0, n=0.25)
	pf = [
	PhysicsFeatures(tool_life_ratio=compute_tool_life_ratio(t, 250.0, 0.25, 0.125, params))
	for t in elapsed_times
	]

	# Fit with physics calibration
	cal = PhysicsCalibrator(method="ridge")
	reg = ToolWearRegressor(feature_dim=384, calibrator=cal)
	reg.fit(X_train, y_train, pf_train, X_val, y_val, pf_val)

	preds = reg.predict(X_test, pf_test)
	```

	---

	## Downstream Tasks

	\| Task \| Input \| Output \| Evaluation \|
	\|------\|-------\|--------\|-----------\|
	\| A. Wear Regression \| embedding \| VB (mm) \| MAE, RMSE, R² \|
	\| B. Stage Classification \| embedding \| healthy/moderate/severe \| Acc, Macro F1 \|
	\| C. RUL Prediction \| embedding \| remaining time (min) \| MAE, RMSE, R² \|
	\| D. Dimensional Compensation \| wear + condition \| offset (mm) \| physics-derived interface \|

	### Wear Stage Thresholds (ISO 8688-1:1989)
	- Healthy: VB < 0.1 mm
	- Moderate: 0.1 ≤ VB < 0.2 mm
	- Severe: VB ≥ 0.2 mm

	---

	## Physics Models

	\| Model \| Status \| Required Data \|
	\|-------\|--------\|--------------\|
	\| Taylor Tool-Life \| Enabled \| speed, feed, depth \|
	\| Kienzle Force \| Enabled \| chip thickness, width \|
	\| Cutting Energy \| Enabled \| force series, speed \|
	\| Archard Wear \| Disabled \| F_N, L (not in standard datasets) \|
	\| Usui Wear Rate \| Disabled \| cutting temperature (not in standard datasets) \|

	Physics parameters are stored in YAML configs (see `configs/physics/`).
	All parameter sources are documented (`literature` / `dataset_calibrated` / `manufacturer` / `user_defined`).

	---

	## Dataset

	PHM Society Data Challenge 2010
	- URL: https://www.phmsociety.org/competition/phm/10
	- Sensor data: force (x/y/z), vibration (x/y/z), acoustic emission RMS
	- Labels: flank wear VB (mm) per cut, per condition (real measurements)
	- Citation: PHM Society (2010). PHM Data Challenge. Prognostics and Health Management Society.

	Data Integrity Notes:
	- PHM2010 does NOT contain dimensional accuracy measurements.
	Task D (dimensional compensation) outputs are physics-derived estimates, not experimental results.
	- Archard/Usui models are disabled by default because PHM2010 lacks the required quantities.
	- All splits use leave-one-condition-out to prevent temporal leakage.

	---

	## Limitations

	- Pretrained on proprietary CNC machining data — domain gap to new materials/machines is expected.
	- PHM2010 benchmarks with synthetic data demonstrate code correctness, not production performance.
	- Physics calibration provides marginal improvement on clean synthetic data; real benefit expected on noisy real-world data.
	- Archard and Usui models require data not typically available in standard machining datasets.
	- The 7.4GB v1 pretraining checkpoint is not included due to file size constraints.

	---

	## Citation

	If you use this model or framework, please cite:

	```
	@software{machiningfm2026,
	author = {Shim, Junseok},
	title = {MachiningFM: Physics-Guided Foundation Model for Machining},
	year = {2026},
	url = {https://github.com/junseokShim/MachiningFM}
	}
	```

	---

	## Source Code

	- GitHub: https://github.com/junseokShim/MachiningFM
	- License: MIT