rover_contact_grc1_viper

Physics-informed surrogate (random-Fourier-feature residual tanh MLP, 4 blocks x 96) of the Wong-Reece rigid-wheel model for the NASA VIPER wheel (R 0.25 m, b 0.20 m, 24 grousers, parametric model from public figures) on GRC-1 lunar simulant, with slip-sinkage (sinkage exponent n = n0 + n1 s, Ding et al. 2010/2011; GRC-1 n1 = 0.8). Inputs slip and sinkage, outputs drawbar pull, normal load and driving torque. Trained with soft constraints dFz/dz >= 0, dFx/ds >= 0 (slip <= 0.3), Mohr-Coulomb traction limit and My >= R Fx. The exact physics configuration it was trained on is recorded in data_lineage.physics and config.json (checked by ZooContactSurrogate.check_physics).

rover_contact_grc1_viper v1.1.0 (revision v1.1.0.post1) · part of the PINNeAPPle zoo · training data PINNeAPPle-Labs/rover-contact-grc1-viper

Try it without installing anything: PINNeAPPle zoo demo (pick rover_contact_grc1_viper: its predictions along each input with their band and where its physics checks warn or fail, and your own inputs evaluated in the browser).

Task: Wheel-soil contact forces of a rigid grousered wheel on lunar regolith simulant (terramechanics)

Inputs

Outputs

Validity range

• slip: [-0.4, 0.9]
• sinkage_m: [0.002, 0.06]
• soil: GRC-1 (pinneapple terramechanics soil database)
• wheel: VIPER wheel, R 0.25 m, b 0.20 m, 24 grousers
• slip_angle_deg: 0.0
• physics: Wong-Reece with slip-sinkage n = n0 + n1 s on driving slip (GRC-1: n0 0.8, n1 0.8); steady state, so the slip that sets the exponent equals the slip

Known limitations

• Only as good as the Wong-Reece model: against published single-wheel tests the model's drawbar pull RMSE is 4-14 N (digitised data), larger than the surrogate's own error.
• One soil and one wheel; zero slip angle (no lateral force); steady state.
• Slip-sinkage makes the forces kink at zero slip (the exponent grows only with driving slip); the network smooths the kink over a small slip interval.

Architecture

• contact_net — {"hidden": 96, "depth": 4, "n_fourier": 16, "scale": 2.0, "seed": 0}

Physics

• Wong-Reece rigid wheel on deformable soil (Bekker pressure-sinkage, Janosi-Hanamoto shear)

Validation

Reference: 2000 held-out Latin-hypercube states (seed 1000, disjoint from training) of the Wong-Reece model evaluated by adaptive quadrature (analytic reference). The Wong-Reece implementation is compared with published single-wheel tests (Ding et al. 2011; Wang & Han 2016; dataset single_wheel_tests).

Trust

Decision: APPROVED · score 1.00 · coverage 100%

Training data

• dataset: rover_contact_grc1_viper
• source: pinneapple_simulation.terramechanics.WongReeceModel(get_soil('GRC-1'), pinneapple_simulation.vehicle.viper().wheel)
• physics: {'model': 'Wong-Reece', 'soil': {'name': 'GRC-1', 'c': 250.0, 'phi_deg': 38.0, 'K': 0.018, 'Ky': 0.018, 'k_c': 700.0, 'k_phi': 505000.0, 'n0': 0.8, 'n1': 0.8, 'rho': 1620.0, 'a0': 0.4, 'a1': 0.15, 'c3': 0.3333333333333333, 'k_u0': 200000000.0, 'A_u': 0.0}, 'wheel': {'radius': 0.25, 'width': 0.2, 'grouser_count': 24, 'grouser_height': 0.025, 'shear_radius_factor': 1.0}, 'g': 1.62, 'bulldozing': 'lateral', 'slip_sinkage': 'drive', 'R_m': 0.25, 'b_m': 0.2, 'c_Pa': 250.0, 'phi_deg': 38.0}

License: apache-2.0

Citation

PINNeAPPle contributors (2026). Wheel-soil contact PINN surrogate (Wong-Reece, GRC-1, VIPER wheel). PINNeAPPle model zoo, https://github.com/PINNeAPPle-Labs/PINNeAPPle

Physics validation

pass: every applicable check passed (12/12 applicable checks pass; level standard; generated by pp.validate with PINNeAPPle 0.7.0, schema validation-report/v1).

Model SHA-256 210464578510a4f94eae0e5071efe1141367015e645274bd0ff9c28d072825b4.

How to use

pip install "pinneapple @ git+https://github.com/PINNeAPPle-Labs/PINNeAPPle"

import pinneapple as pp

model = pp.zoo.load("rover_contact_grc1_viper")          # weights checked against their SHA-256
inputs = {"slip": -0.00237311, "sinkage_m": 0.0121651}
out = model.predict(inputs)                 # warns for inputs outside the validity range
print({k: round(float(v[0]), 6) for k, v in out.items()})
# {'Fx_N': -10.081497, 'Fz_N': 165.083856, 'My_Nm': 2.054259}
print(pp.zoo.query_checks(model, inputs)[0]["verdict"]["status"])   # per-query trust checks
# pass
print(pp.zoo.validate(model).decisao)        # card metrics reproduced + physics checks
# APPROVED

The inputs are the first held-out test case of the training dataset; its reference value is Fx_N = -10.4698, Fz_N = 167.455, My_Nm = 2.18489. pp.zoo.evaluate("rover_contact_grc1_viper") recomputes every metric of the card on the stored reference.

Hosted inference

No Hugging Face inference provider can run this model, so the Hub widget is off (inference: false). It is a small PyTorch network, but its prediction is more than a forward pass: the inputs are encoded and normalised, the outputs denormalised (and, for ensembles, averaged with their spread), and every query is checked against the validity range and the model's physics checks. The pinneapple library does all of that (below); the ONNX graph carries the pre- and post-processing but not the checks; the zoo demo Space shows the model along a sweep of each input and runs it, with its checks, in your browser.

ONNX

model.onnx (opset 17) maps x, shape (n, 2) float32 with the columns slip, sinkage_m, to the outputs y: ['Fx_N', 'Fz_N', 'My_Nm']. Pre- and post-processing are in the graph (largest difference from PyTorch on the reference inputs: 5.6e-07); the validity-range and physics checks are not, so check the range yourself.

import numpy as np, onnxruntime as ort
from huggingface_hub import hf_hub_download

path = hf_hub_download("PINNeAPPle-Labs/rover-contact-grc1-viper", "model.onnx", revision="v1.1.0.post1")
session = ort.InferenceSession(path)
x = np.array([[-0.00237311, 0.0121651]], np.float32)
print(dict(zip([o.name for o in session.get_outputs()], session.run(None, {"x": x}))))

Files

The SHA-256 are those of the package's manifest: pp.zoo.load refuses any other file.

Cite

If you use this model, please cite PINNeAPPle (software, Zenodo DOI 10.5281/zenodo.23343062; see CITATION.cff):

@software{pinneapple,
  author = {Barros, Yan and Schiassi, Enrico},
  title  = {PINNeAPPle},
  doi    = {10.5281/zenodo.23343062},
  url    = {https://github.com/PINNeAPPle-Labs/PINNeAPPle}
}