Skip to content

About

Reference training code for BLE-informed residual protective performance prediction of pitted Whipple shields.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Whipple RPP Benchmark

Reference training code accompanying:

Peng Ji, Runqiang Chi, and Wuxiong Cao, “Ballistic limit equation-constrained and data-driven residual protective performance assessment of Whipple shields with pitting damage,” Aerospace Science and Technology, 179, 113473 (2026). https://doi.org/10.1016/j.ast.2026.113473

This repository provides the model definitions, data interfaces, ballistic limit equation (BLE), loss functions, reference configurations, and training entry points used to study residual protective performance (RPP) fields for pitted Whipple shields.

中文说明

Included implementations

The package covers four deep spatial-field models and two statistical baselines:

Public name Reference implementation
cnn Convolutional CWT/thickness encoder and spatial regression head
unet Shared encoder followed by a U-Net field refiner
transformer Shared encoder followed by spatial-token self-attention
vqsm Two-stage target codebook and signal-to-latent surrogate
gpr PCA-reduced Gaussian-process regression baseline
kriging PCA-reduced regression-kriging baseline

Method map

The pipeline below summarizes the data flow from processed signals and shield parameters to the predicted RPP field, including the BLE label branch.

flowchart LR
    AE[Processed four-channel CWT tensor] --> E[Signal encoder]
    TB[Front-plate thickness tB] --> E
    E --> CNN[CNN]
    E --> UNET[U-Net]
    E --> TX[Transformer]
    E --> VQ[VQ-SM]
    AE --> PCA[Feature scaling and PCA]
    TB --> META[Metadata vector]
    DP[Projectile diameter dp] --> META
    VP[Impact velocity vp] --> META
    PCA --> GPR[GPR]
    PCA --> KRG[Regression kriging]
    META --> GPR
    META --> KRG
    CNN --> RPP[Predicted RPP field]
    UNET --> RPP
    TX --> RPP
    VQ --> RPP
    GPR --> RPP
    KRG --> RPP
    TR[Residual thickness t_res] --> BLE[BLE label calculation]
    EP[Equivalent plastic strain eps_p] --> BLE
    VP --> BLE
    BLE --> LABEL[Reference RPP field dc]
    LABEL --> LOSS[Training objective]
    RPP --> LOSS
Loading

Repository layout

.
├── configs/                  # one reference YAML for each public model
├── scripts/static_check.py   # repository-level static checks
├── src/whipple_rpp/
│   ├── data.py               # NPZ contract, manifests, normalization
│   ├── physics.py            # central BLE defaults and implementations
│   ├── losses.py             # field, gradient, midrange, BLE losses
│   ├── models/               # CNN, U-Net, Transformer, and VQ-SM
│   ├── train_deep.py         # deep-model CLI
│   └── train_baseline.py     # GPR/Kriging CLI
├── CITATION.cff
├── DATA_ACCESS.md
└── NOTICE.md

The supplied YAML files use portable relative paths. Add local datasets under the ignored data/ directory or point the configurations to an equivalent relative layout.

Data contract

Each manifest is a UTF-8 text file containing one NPZ path per line, relative to data.root. Blank lines and lines beginning with # are ignored. Absolute paths and paths that leave data.root are rejected.

Each NPZ case requires:

  • ae: processed four-channel CWT tensor, shaped (4, H, W) or (H, W, 4);
  • tB: scalar front-plate thickness;
  • either dc: the target RPP field, shaped (H, W) or (1, H, W);
  • or both t_res and eps_p: one-channel residual-thickness and equivalent plastic-strain fields from which dc is calculated with the BLE.

The GPR and Kriging baselines additionally require scalar dp and vp fields. When vp is used by the BLE it must be expressed in metres per second; t_res must be expressed in metres. Keep all other quantities consistent with the preprocessing that produced the tensors. Pickled NPZ objects are disabled.

Normalization statistics are computed from the training manifest at runtime.

BLE defaults

whipple_rpp.physics.BLEParameters is the single source of truth for the defaults corresponding to Table A3 of the article:

Parameter Default
k 3.0
q_h 0.1
m 2.34
n 0.34
rho_shield 2.78
rho_projectile 2.78
a 265 MPa
b 426 MPa
c 5386 m/s
theta_rad 0
reference velocity 5000 m/s
reporting scale 0.5

YAML ble entries may override these values. Leaving ble: {} uses the central defaults. The BLE can construct a missing dc field and can also be enabled as an auxiliary consistency loss through loss.ble_weight.

Installation

Python 3.10 or newer is expected. The dependency list specifies direct packages with broad lower bounds.

python -m venv .venv
python -m pip install -e .

Kriging uses pykrige; the remaining baselines use scikit-learn. Deep models use PyTorch. Select a PyTorch build appropriate for the target hardware.

Configuration and training

Create the files referenced by a YAML configuration, for example:

data/
├── manifests/
│   ├── train.txt
│   └── validation.txt
└── cases/
    └── your_case.npz

A manifest entry would be cases/your_case.npz. Data, manifests, checkpoints, and run outputs are ignored by Git.

Run one of the four deep-model configurations:

python -m whipple_rpp.train_deep --model cnn --config configs/cnn.yaml
python -m whipple_rpp.train_deep --model unet --config configs/unet.yaml
python -m whipple_rpp.train_deep --model transformer --config configs/transformer.yaml
python -m whipple_rpp.train_deep --model vqsm --config configs/vqsm.yaml

Run a statistical baseline:

python -m whipple_rpp.train_baseline --model gpr --config configs/gpr.yaml
python -m whipple_rpp.train_baseline --model kriging --config configs/kriging.yaml

The CLI model must match model.name in the YAML. Output directories must be relative paths. VQ-SM first learns a target-field codebook and decoder, then freezes them while learning the signal-to-latent mapping. GPR and Kriging use 16 AE principal components and 24 target-field components in the supplied reference configurations.

Reproducibility scope

The repository supplies the six model implementations, reference configurations, BLE calculation, data loaders, and training entry points. Reproducing the article results also requires the study-specific processed data, case splits, preprocessing parameters, normalization inputs, and trained weights. These materials are managed through the data-request process described in DATA_ACCESS.md.

Static checks

The repository checker compiles Python, imports the package, exercises both CLI help pages, parses every YAML file, rejects absolute configuration paths, scans for common credential and local-path patterns, and checks for disallowed assets and large files:

python scripts/static_check.py

This command validates repository structure and interfaces; training and numerical evaluation remain experiment-level tasks.

Citation and data access

Use CITATION.cff to cite the associated article. Research-data requests may be sent to the corresponding author at [email protected]. See DATA_ACCESS.md for the requested information and review process.

License

No software license has been granted for this repository. All rights are reserved by the applicable rights holders. See NOTICE.md.

About

Reference training code for BLE-informed residual protective performance prediction of pitted Whipple shields.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages